docs(repomap): package-level README, doc.go, and per-file comments - #52
Merged
Conversation
…/context/repomap A go-doc compatible overview that supersedes the previous 3-line package comment on repomap.go (kept for backward compatibility). It documents: - the package's role as the deep code-analysis engine (call graph, search, quality signals, API scanning, incremental indexing) - the dual-package relationship with internal/context/repomap, which is the prompt-injection shim and shares no code with this package - the stdlib-only core (no CGO, no tree-sitter binary) - extension points: new language parsers, new smell heuristics, new HTTP framework scanners - performance and scaling notes (MaxFiles cap, in-process LRU cache, persistent IncrementalMap at .hawk/repomap-cache.json)
… signals, API surface, and Incremental files (16 files) Each comment is a 1-3 line description of what the file does, written so that 'go doc' on any file in the package produces a useful summary. Comments are deliberately concise; the deeper architecture overview lives in doc.go and README.md. Files in this commit: - Core/cache.go in-process LRU symbol cache - Core/gitignore.go composed .gitignore rule walker - Core/watcher.go fsnotify wrapper - Symbols/parser.go original regex-based Go extractor - Symbols/parser_enhanced.go AST-based Go extractor - Symbols/parser_langs.go regex extractors for non-Go languages - Symbols/treesitter.go tree-sitter-style scope-aware extractor - Symbols/patterns.go index include/exclude pattern loader - Static/callgraph.go Go caller/callee graph from go/ast - Static/depgraph.go package-level dep graph (go.mod + package.json) - Static/imports.go file-level import graph - Static/hierarchy.go project -> package -> file 3-level summary - Static/interface_extract.go exported API surface (signatures only) - Static/cochange.go git-history co-change matrix - Static/changeset.go change-set-aware working set from git diff - Static/ownership.go git + CODEOWNERS ownership map - Quality/smells.go design smell detectors - Quality/complexity.go cyclomatic complexity - Quality/health_score.go weighted health-score rollup - Quality/doclint.go doc-comment coverage - Quality/dead_code.go unreferenced declaration detector - Quality/migration_detector.go deprecated-API migration suggestions - API/api_scanner.go HTTP route scanners + OpenAPI export - Incr/incremental.go CodeIndexer interface and reindex loop - Incr/incremental_map.go persistent on-disk symbol cache
…g Symbols files (18 files) Second batch of file-level leading comments, covering the Search and navigation files (BM25, PageRank, reranking, prediction, change-set context), the Grouping file (file_grouper, summary), and the remaining Symbols files (parser, parser_enhanced, parser_langs, treesitter, patterns, watcher). Each comment is intentionally short; see doc.go and README.md for the architecture overview.
…ion shim The previous package comment described what the package did but did not call out the boundary with internal/intelligence/repomap, which is the deeper analysis engine. The two packages share no code and serve different callers (this one is the context layer's narrow budgeted-map entry point; the other is the full analysis toolkit). The new comment makes the boundary explicit, points readers at the deep package for symbol-level search / quality / API features, and adds implementation notes on the PageRank pass and file-size limits.
The README is the human-facing entry point for the package. It contains: - One-paragraph overview (what Generate does, what else lives here) - Architecture diagram (mermaid) of the file groups and their data flow - File-group table mapping every group to its files and purpose - Entry-point map listing the headline public APIs by group - Storage model (in-process LRU, persistent .hawk/repomap-cache.json, fsnotify watch protocol) - Extension points: how to add a new language parser, a new code smell, a new HTTP framework scanner - Performance characteristics and known scaling limits per subsystem - A pointer to doc.go (machine-readable) and doc_test.go (worked example), plus the cross-reference back to internal/context/repomap
Adds ExampleGenerate (a godoc-consumable worked example) and TestExampleGenerate_isRunnable (the actual validator for 'go test'). The example is callable but the output depends on a temp directory path that is not stable across runs, so the example function intentionally omits a '// Output:' comment. The test function is the source of truth. The example walks through the full primary use case: - create a tiny project under t.TempDir() with one Go and one Python file - call Generate with explicit Options - render the result with Format - assert the output is non-empty and contains the expected files and symbols The test is wired to the rest of the package's tests so 'go test ./internal/intelligence/repomap/...' exercises it alongside the existing test suite.
…up 1) go doc treats a comment that begins with 'Package <name>' as a package-level doc comment, even when it lives in a non-doc.go file. The previous per-file leading comments all started with '// Package repomap: <filename> ...' which caused go doc to dump all 30+ file comments at the package level instead of showing the doc.go overview and the per-file comments in their proper place. The fix: replace the 'Package repomap: <filename>' prefix with just '<filename>' so the comments are recognised as file-level doc comments by go doc and godoc.
…up 2) Second batch of the same fix, covering the Search, Grouping, and remaining Symbols files. See the prior commit for context.
Patel230
added a commit
that referenced
this pull request
Jun 18, 2026
* docs(repomap): add doc.go explaining dual-package split with internal/context/repomap A go-doc compatible overview that supersedes the previous 3-line package comment on repomap.go (kept for backward compatibility). It documents: - the package's role as the deep code-analysis engine (call graph, search, quality signals, API scanning, incremental indexing) - the dual-package relationship with internal/context/repomap, which is the prompt-injection shim and shares no code with this package - the stdlib-only core (no CGO, no tree-sitter binary) - extension points: new language parsers, new smell heuristics, new HTTP framework scanners - performance and scaling notes (MaxFiles cap, in-process LRU cache, persistent IncrementalMap at .hawk/repomap-cache.json) * docs(repomap): add leading comments to Core, Static analysis, Quality signals, API surface, and Incremental files (16 files) Each comment is a 1-3 line description of what the file does, written so that 'go doc' on any file in the package produces a useful summary. Comments are deliberately concise; the deeper architecture overview lives in doc.go and README.md. Files in this commit: - Core/cache.go in-process LRU symbol cache - Core/gitignore.go composed .gitignore rule walker - Core/watcher.go fsnotify wrapper - Symbols/parser.go original regex-based Go extractor - Symbols/parser_enhanced.go AST-based Go extractor - Symbols/parser_langs.go regex extractors for non-Go languages - Symbols/treesitter.go tree-sitter-style scope-aware extractor - Symbols/patterns.go index include/exclude pattern loader - Static/callgraph.go Go caller/callee graph from go/ast - Static/depgraph.go package-level dep graph (go.mod + package.json) - Static/imports.go file-level import graph - Static/hierarchy.go project -> package -> file 3-level summary - Static/interface_extract.go exported API surface (signatures only) - Static/cochange.go git-history co-change matrix - Static/changeset.go change-set-aware working set from git diff - Static/ownership.go git + CODEOWNERS ownership map - Quality/smells.go design smell detectors - Quality/complexity.go cyclomatic complexity - Quality/health_score.go weighted health-score rollup - Quality/doclint.go doc-comment coverage - Quality/dead_code.go unreferenced declaration detector - Quality/migration_detector.go deprecated-API migration suggestions - API/api_scanner.go HTTP route scanners + OpenAPI export - Incr/incremental.go CodeIndexer interface and reindex loop - Incr/incremental_map.go persistent on-disk symbol cache * docs(repomap): add leading comments to Search, Grouping, and remaining Symbols files (18 files) Second batch of file-level leading comments, covering the Search and navigation files (BM25, PageRank, reranking, prediction, change-set context), the Grouping file (file_grouper, summary), and the remaining Symbols files (parser, parser_enhanced, parser_langs, treesitter, patterns, watcher). Each comment is intentionally short; see doc.go and README.md for the architecture overview. * docs(context/repomap): clarify that this package is the prompt-injection shim The previous package comment described what the package did but did not call out the boundary with internal/intelligence/repomap, which is the deeper analysis engine. The two packages share no code and serve different callers (this one is the context layer's narrow budgeted-map entry point; the other is the full analysis toolkit). The new comment makes the boundary explicit, points readers at the deep package for symbol-level search / quality / API features, and adds implementation notes on the PageRank pass and file-size limits. * docs(repomap): add README with architecture overview and entry-point map The README is the human-facing entry point for the package. It contains: - One-paragraph overview (what Generate does, what else lives here) - Architecture diagram (mermaid) of the file groups and their data flow - File-group table mapping every group to its files and purpose - Entry-point map listing the headline public APIs by group - Storage model (in-process LRU, persistent .hawk/repomap-cache.json, fsnotify watch protocol) - Extension points: how to add a new language parser, a new code smell, a new HTTP framework scanner - Performance characteristics and known scaling limits per subsystem - A pointer to doc.go (machine-readable) and doc_test.go (worked example), plus the cross-reference back to internal/context/repomap * docs(repomap): add worked example in doc_test.go Adds ExampleGenerate (a godoc-consumable worked example) and TestExampleGenerate_isRunnable (the actual validator for 'go test'). The example is callable but the output depends on a temp directory path that is not stable across runs, so the example function intentionally omits a '// Output:' comment. The test function is the source of truth. The example walks through the full primary use case: - create a tiny project under t.TempDir() with one Go and one Python file - call Generate with explicit Options - render the result with Format - assert the output is non-empty and contains the expected files and symbols The test is wired to the rest of the package's tests so 'go test ./internal/intelligence/repomap/...' exercises it alongside the existing test suite. * fix(docs): drop 'Package repomap:' prefix from per-file comments (group 1) go doc treats a comment that begins with 'Package <name>' as a package-level doc comment, even when it lives in a non-doc.go file. The previous per-file leading comments all started with '// Package repomap: <filename> ...' which caused go doc to dump all 30+ file comments at the package level instead of showing the doc.go overview and the per-file comments in their proper place. The fix: replace the 'Package repomap: <filename>' prefix with just '<filename>' so the comments are recognised as file-level doc comments by go doc and godoc. * fix(docs): drop 'Package repomap:' prefix from per-file comments (group 2) Second batch of the same fix, covering the Search, Grouping, and remaining Symbols files. See the prior commit for context. * fix(repomap): rename shadowed err in doc_test.go to writeErr (lint) ---------
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation to the previously-undocumented
hawk/internal/intelligence/repomap/package (62 files) per the post-merge cleanup plan.This PR:
doc.go(67 lines) with go-doc compatible overview explaining the dual-package splitREADME.md(288 lines) with architecture overview and entry-point mapinternal/context/repomap/repomap.gospelling out the boundary with the deep packagedoc_test.goexample (108 lines) showing the basic Generate → output flowVerification
gofmt -l internal/intelligence/repomap/: cleango vet ./internal/intelligence/repomap/...: cleango test -count=1 -run TestExampleGenerate_isRunnable ./internal/intelligence/repomap/...: PASSgo doc ./internal/intelligence/repomapproduces sensible per-file outputgit initwhich is blocked in the sandbox; same tests fail onmain, so the failures are pre-existing and sandbox-induced, not caused by this PR)Test plan
go doc ./internal/intelligence/repomapreads wellgo test ./internal/intelligence/repomap/...passes in CIThis is docs-only — no logic changes.
Made with Cursor