Skip to content

PROJECT.md

Latest commit

 

History

History
63 lines (51 loc) · 2.95 KB

PROJECT.md

File metadata and controls

63 lines (51 loc) · 2.95 KB
Raw

Project

This document gives agents and contributors the project overview, package map, documentation ownership, and CI notes. For agent operating policy, read AGENTS.md.

Overview

embed-code-go is a Go command-line application. It scans Markdown and HTML documents for embed-code instructions, resolves source fragments, renders them inside code fences, and checks whether existing snippets are up-to-date.

Project Map

  • main.go: executable entry point, mode dispatch, aggregate errors, and final user-facing output.
  • cli/: flag parsing, YAML loading, validation, and runtime config conversion.
  • configuration/: defaults and normalized settings used by processing code.
  • embedding/: document discovery, per-document processing, embedding writes, and up-to-date checks.
  • embedding/parsing/: state-machine parser for instructions, ordinary Markdown fences, embedding fences, and rendered-content comparison.
  • embedding/commentfilter/: language-aware comment-retention filtering.
  • fragmentation/: whole-file, named-fragment, and line-pattern extraction; source lookup; partition assembly; encoding checks; and caches.
  • files/: filesystem validation and file helpers.
  • indent/: shared indentation measurement and removal.
  • logging/: slog handler, clickable file references, panic reporting, and terminal formatting support.
  • type/: YAML-compatible string and named-path list types. The import path segment is type, but the Go package identifier is _type because type is a Go keyword.
  • test/resources/: parser, embedding, configuration, and source-code fixtures.
  • showcase/: executable user guide and end-to-end example suite.

Documentation Ownership

  • README.md: project entry point, short run/build instructions, and links to the complete guide.
  • showcase/README.md: complete user guide entry point and runnable workflow.
  • showcase/configuration/README.md: command-line flags, YAML configuration, source roots, include/exclude patterns, and multiple embedding targets.
  • showcase/embedding/README.md: <embed-code> instruction syntax, source selection, fragments, patterns, comment filtering, and rendered examples.
  • PROJECT.md: project map, package ownership, documentation ownership, and CI notes for contributors and agents.
  • AGENTS.md: repository operating policy for agents.

Keep usage details in the showcase. Keep architecture and ownership details in this file. Keep the root README short.

CI

This repository is configured with these GitHub workflows:

  • check: runs linting, the normal Go test suite, and the showcase end-to-end tests across supported platforms.
  • release-binaries: reads VERSION, builds Linux, macOS, and Windows binaries, and creates the matching GitHub Release on pushes to master.

The release tag is v<version> from VERSION. When the release already exists, the workflow emits a warning and finishes successfully without rebuilding or uploading binaries.