Documentation
¶
Overview ¶
Package contract derives per-file API-surface fingerprints for the paths the manifest pipeline already observes (ADR-044, ADR-048). A fingerprint names only the exported surface of a file: symbol names, a normalized declaration signature with the body and comments removed, and a hash per signature. Raw source, bodies, and diffs never leave this package.
Go, TypeScript and TSX use their own extractors; Python, JavaScript, Java, Rust, C#, PHP, C, C++, Scala, Kotlin and Dart are parsed by tree-sitter. Every other extension has no fingerprint and therefore never produces a contract finding.
Go extraction uses the standard library go/parser and go/ast. TypeScript and TSX extraction uses a bounded scanner written in pure Go; it is deliberately best-effort, and typescript.go documents the exact recognized forms and their limitations. Python and JavaScript are parsed by tree-sitter grammars running as WebAssembly under wazero (ADR-063), which keeps ADR-019's CGO-free, never-invoke-Node boundary because the C toolchain is a build-time dependency producing a vendored module rather than a link-time one.
Extraction never returns an error. A file that cannot be parsed, is too large, or is not fingerprintable simply has no fingerprint, so manifest publication is never blocked by a parse failure.
Index ¶
Constants ¶
const MaxSignatureRunes = fingerprint.MaxSignatureRunes
MaxSignatureRunes bounds a normalized signature. A longer declaration is truncated and marked so a reader can tell the text is not the whole header.
const MaxSourceBytes = fingerprint.MaxSourceBytes
MaxSourceBytes refuses files large enough to make extraction unbounded work.
const MaxSymbols = fingerprint.MaxSymbols
MaxSymbols bounds the exported surface recorded for one file.
const TruncationMarker = fingerprint.TruncationMarker
TruncationMarker terminates a signature that exceeded MaxSignatureRunes.
Variables ¶
This section is empty.
Functions ¶
func Fingerprintable ¶
Fingerprintable reports whether a repository-relative path has a contract fingerprint at all. Extraction and comparison are limited to these languages.
It answers the static question "is this a language Overgent fingerprints", not "will extraction succeed here and now". A wasm-backed language stays fingerprintable on a platform without wazero's compiler; Extract returns no fingerprint there and WasmStatus explains why. Reporting the language as unsupported instead would hide a platform gap behind a language gap, which ADR-063 forbids.
func LoadedGrammars ¶
func LoadedGrammars() []string
LoadedGrammars reports which grammars this process has actually compiled. It exists so the laziness is observable rather than assumed.
func WasmStatus ¶
WasmStatus reports whether wasm-backed extraction actually works on this platform, and why not when it does not.
It answers the question by compiling one real grammar, because that is the only honest test: wazero's compiler support is what decides this, and it is not knowable without asking it. The probe language is loaded lazily like any other, so calling this costs one grammar rather than all of them.
It exists so the service can honor the honest-fidelity rule: a platform without wazero's compiler produces no fingerprint for the wasm-backed languages, and must say so rather than let an empty exported surface read as a stable contract.
Types ¶
type File ¶
type File = fingerprint.File
File is the fingerprint of one repository-relative path.
func Extract ¶
Extract derives the fingerprint of one file. The second result is false when the path is not fingerprintable, the source is too large, or the source could not be parsed; callers treat that as "no fingerprint", never as an error.
deny is the wire gate for derived signature text. A symbol whose normalized signature is denied is omitted from the symbol list and from the file contract hash, so a gated symbol can never desynchronize the hash from the symbols that are actually published. A nil deny filters nothing.
type Symbol ¶
type Symbol = fingerprint.Symbol
Symbol is one exported declaration in a file's API surface.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fingerprint holds the contract-fingerprint value types and their bounds.
|
Package fingerprint holds the contract-fingerprint value types and their bounds. |
|
Package multilang is the spike's tree-sitter-backed contract extractor.
|
Package multilang is the spike's tree-sitter-backed contract extractor. |
|
Package tsw runs a tree-sitter build compiled to wasm32-wasi under wazero.
|
Package tsw runs a tree-sitter build compiled to wasm32-wasi under wazero. |
|
Package wasmgrammar carries the built tree-sitter modules as embedded blobs, one per language.
|
Package wasmgrammar carries the built tree-sitter modules as embedded blobs, one per language. |