Expand description
g8-extractor — annotation extraction for the G8.
Detects // @g8.<kind>(...) magic-comment annotations (and # @g8.<kind>(...)
for Python) across Rust, TypeScript, Python, and Go source files via the
ast-grep CLI shell-out. Also parses AGENTS.md, CLAUDE.md, and *.g8.md
sidecar files into Intent / Plan / Decision annotations via a native
Markdown-section scanner.
§Python comment syntax
Python uses # as its comment prefix, not //. Both forms are accepted:
# @g8.capability(name = "x")— Python-native, recommended for Python files.// @g8.capability(name = "x")— uniform cross-language form, also accepted.
The ast-grep comment node kind rule for Python matches both because
Python’s tree-sitter grammar represents all comment text under comment nodes
regardless of the leading character. The annotation parser strips either prefix.
§Architecture
Extractor::scan_dir(root)
├── walk via `ignore` crate (respects .gitignore)
├── source files (.rs .ts .tsx .py .go)
│ └── ast-grep CLI shell-out (--json=stream, per R2 §6)
│ └── parse NDJSON → Vec<RawAstMatch>
│ └── strip comment prefix → call g8_core::parse_annotation_grammar
└── sidecar files (AGENTS.md, CLAUDE.md, *.g8.md)
└── Markdown-section scanner (per ARCH §3.2 / Decision 4)
└── heading regex → IntentKind mappingReturns ScanResult with a deduplicated Vec<Annotation>, warnings, and stats.
§Runtime dependency
The ast-grep binary (sg) must be on PATH (or configured via
Extractor::with_binary). Install with cargo install ast-grep or via
Homebrew (brew install ast-grep). The extractor checks at construction time
and returns ExtractorError::BinaryNotFound if absent.
Structs§
- Extractor
- The main entry point for annotation extraction.
- Scan
Result - The result of a full directory-tree scan.
- Scan
Stats - Aggregate statistics for a scan run.
- Scan
Warning - A non-fatal warning encountered during extraction.
Enums§
- Extractor
Error - Errors produced by
g8-extractor.
Functions§
- scan_
project - Scan a directory tree for all G8 annotations.