Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (23 loc) · 3.2 KB

AGENTS.md

File metadata and controls

38 lines (23 loc) · 3.2 KB
Raw

Repository Guidelines

Project structure and module organization

The CLI and flag parsing live in cmd/gh-md-toc. Application wiring is in internal/app; routing and concurrency are in internal/controller. Models and TOC rules live under internal/core/entity and internal/core/toc. Workflows are separated into internal/core/usecase/{localmd,remotemd,remotehtml}. Filesystem, HTTP, GitHub parsing, and logging implementations belong in internal/adapters. Tests sit beside production files as *_test.go; e2e-tests/ contains golden output.

Documentation

See ARCHITECTURE.md for the component hierarchy, runtime flows, and dependencies. After every change, review both ARCHITECTURE.md and README.md; update affected sections in the same PR so both files remain current.

Build, test, and development commands

  • go run ./cmd/gh-md-toc ./README.md runs the CLI against a local document.
  • go build ./cmd/gh-md-toc verifies the command package builds.
  • go test ./... runs all tests.
  • go test -race ./... runs the race detector.
  • make lint runs go vet and golangci-lint.
  • go mod tidy -diff checks module-file consistency without modifying files.
  • go mod verify verifies downloaded modules.
  • make e2e checks nine live GitHub scenarios against golden files and requires network access.

Coding style and naming conventions

Target Go 1.26 or newer. Format every changed Go file with gofmt; use tabs as generated by the formatter. Follow standard Go naming and keep existing exported names unless a functional change requires otherwise. Keep interfaces small and declare them near consumers. Put external I/O in adapters and shared TOC behavior in core. Write code comments in English and wrap errors with operation and input context.

Testing guidelines

Use the standard testing package. Name tests TestXxx and prefer table-driven cases for related inputs. Use t.TempDir for files and httptest for HTTP behavior. Add tests in the same change as behavior. Preserve existing golden output unless the PR intentionally changes the CLI format.

Commit and pull request guidelines

Use Conventional Commits, for example fix(http): reject oversized responses or refactor(toc): simplify rendering. Use typed branch prefixes such as fix/, refactor/, feat/, docs/, or chore/, based on master. Keep each PR focused. Explain what changed, why it changed, compatibility impact, and exact validation commands. Link the originating issue or regression PR when applicable. Include CLI output examples when observable formatting changes.

Record user-visible changes in CHANGELOG.md under [Unreleased] in the same PR, following Keep a Changelog. Internal refactors that leave CLI behaviour and output unchanged do not need an entry. GoReleaser still generates the per-release commit list on the GitHub release page; CHANGELOG.md is the curated history and takes precedence when the two differ in emphasis.

Security and configuration

Never log or commit GitHub tokens. Use GH_TOC_TOKEN for authentication and GH_TOC_URL for an alternate API endpoint. Keep secrets out of tests, fixtures, debug output, and PR descriptions.