Skip to main content

Crate g8_extractor

Crate g8_extractor 

Source
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 mapping

Returns 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.
ScanResult
The result of a full directory-tree scan.
ScanStats
Aggregate statistics for a scan run.
ScanWarning
A non-fatal warning encountered during extraction.

Enums§

ExtractorError
Errors produced by g8-extractor.

Functions§

scan_project
Scan a directory tree for all G8 annotations.