Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (76 loc) · 4.85 KB

AGENTS.md

File metadata and controls

90 lines (76 loc) · 4.85 KB

Context

ksrc is a Go CLI for searching and reading Kotlin/Java dependency sources resolved from Gradle projects. It resolves dependencies via Gradle, ensures -sources.jar artifacts exist in Gradle caches, then uses rg for search and zip reads for cat/open. The tool is designed for scriptable/agent workflows: stable output, file-id chaining, and zero mutation of the target project.

Primary docs to keep aligned with code:

  • README.md
  • docs/cli-api.md
  • docs/decisions.md
  • skills/ksrc/SKILL.md

Commands/workflow guidance

  • Run the local quality gate used in CI before pushing:
./scripts/ci-format.sh
go vet ./...
go test ./...
  • Rebuild local CLI binary after code changes:
KSRC_VERSION="$(tr -d ' \n' < VERSION)"
go build -ldflags "-X github.com/respawn-app/ksrc/internal/cli.Version=${KSRC_VERSION}" -o ./bin/ksrc ./cmd/ksrc
  • Run a fast functional smoke check against the sample project:
./bin/ksrc search LocalDate --module org.jetbrains.kotlinx:kotlinx-datetime --project ./sample
  • For release-related changes, follow docs/release-workflow.md and use scripts/update-brew-tap.sh instead of manual formula edits.

Testing instructions

  • Add a regression test for every bug fix.
  • Add unit tests for every new feature.
  • Keep tests in the package being changed (internal/<pkg>/*_test.go) and prefer deterministic fakes/stubs over networked/real-project dependencies.

Test layers used in this repo:

  • Default test suite (go test ./...): unit tests plus lightweight integration tests using testdata/fixture/gradlew fake wrapper and temporary jars.
  • Real Gradle integration suite: gated by KSRC_INTEGRATION=1 in internal/cli/integration_gradle_test.go; uses testdata/integration and sample.
  • MCP integration test: internal/mcpserver/integration_test.go builds and launches ksrc mcp and exercises tool calls.

Useful test commands:

go test ./...
go test ./internal/cli -run Integration
KSRC_INTEGRATION=1 go test ./internal/cli -run IntegrationWithRealGradle
go test -cover ./...

Project Layout & Module Map

  • cmd/ksrc/main.go: CLI entrypoint.
  • internal/cli/: Cobra command wiring, flags, output formatting, hints.
  • internal/resolution/: orchestration layer from CLI to Gradle/cache resolution.
  • internal/gradle/: init script generation, Gradle invocation, traversal (root -> buildSrc -> included builds).
  • internal/resolve/: cache scanning, coordinate/file-id parsing, filtering/version selection.
  • internal/search/: rg execution strategy (--search-zip when supported, extract fallback), output parsing.
  • internal/cat/: zip file reads and --lines range parsing.
  • internal/mcpserver/: stdio MCP server and tool handlers.
  • internal/executil/: command execution abstraction used for testability.
  • testdata/fixture/: fake Gradle wrapper test fixture.
  • testdata/integration/: real Gradle integration fixture.
  • sample/: KMP/Android sample used for smoke coverage.
  • docs/: API spec, decisions, release workflow.
  • scripts/: CI format check, install script, brew tap update automation.

Dev environment tips

  • Build output version is injected from VERSION via ldflags; without that, CLI reports dev.
  • Keep ./bin/ksrc current if your local shell/tooling points to it.

Architecture Notes

  • Keep command wiring thin in internal/cli; add behavior in domain packages (resolution, gradle, resolve, search, cat, mcpserver).
  • Preserve zero-mutation behavior for target Gradle projects; only temporary files are allowed.
  • Resolution behavior is intentional and documented in docs/decisions.md.
  • Gradle invocation failures fall back to cache-only resolution with warnings; this is part of UX contract.
  • Search output and file-id contract are API surfaces; keep formats stable and parseable:
    • Search: <file-id> <line>:<col>:<match>
    • File-id: group:artifact:version!/path/inside/jar.ext
  • MCP tools are plaintext-first; keep tool outputs in content and avoid introducing structured payload dependencies.

Code style

  • Follow gofmt strictly (./scripts/ci-format.sh is authoritative).
  • Keep CLI stdout machine-parseable; send diagnostics/warnings/verbose lines to stderr.
  • Reuse executil.Runner instead of direct os/exec in logic that needs test coverage.
  • Keep changes cohesive and package-local; avoid leaking command concerns into resolution/search internals.
  • When flags/output/API surface changes, update all affected docs and skill files in the same change.
  • Follow the commit style used by changelog automation: scoped/typed subject lines such as cli: ..., mcp: ..., docs: ..., release: ..., fix: ....

Always keep this file up-to-date when you change project behavior, workflows, flags, outputs, release process, or architecture; remove stale facts promptly, and do not add temporary notes, generic boilerplate, or frequently changing product details.