providers

type Capability ¶ added in v0.2.9

type Capability struct {
	Security, Practices RuleSet
	Surface             []surface.Category
	CoverageManifest    bool
}

Capability is what a LanguageProvider declares it implements — a fact about the provider, independent of which resolvers currently admit it (exposure, owned by internal/providers/registry). Surface must be a subset of surface.ProviderCategories (C2, checked by ValidSurface); CoverageManifest mirrors whether the provider implements the optional CoverageManifest() method (C4, checked where the provider is resolved).

func (c Capability) ValidSurface() bool

type ExcludedRule ¶ added in v0.2.9

type ExcludedRule struct {
	ID     string // rule id, e.g. "PRAC-004"
	Reason string // why it is permanently not covered
}

ExcludedRule names a rule id a provider will PERMANENTLY not implement, and why. This is a different kind of fact from Declared: Declared says a rule IS covered; a permanent drop says it never will be, and silently omitting it from a coverage answer is indistinguishable from "not yet" — exactly the over-promise this project's coverage manifests exist to prevent (mirrors internal/core/dbcoverage's NotCovered() precedent: DB-012 and DW-022 are recorded there with their reasons rather than left as an absence). Scoped to one rule id rather than free prose, so it can be checked (ValidExclusions) instead of only read.

type LanguageProvider ¶

type LanguageProvider interface {
	// Identity.
	Language() string         // "go", "typescript", "java", "python"
	Frameworks() []string     // recognized frameworks
	FileExtensions() []string // e.g. [".go"], [".ts", ".tsx"]

	// Capability declares what this provider implements — its rule IDs per
	// family and its surface category coverage — independent of which
	// resolvers currently expose it (that is internal/providers/registry's
	// Exposure, a separate fact). A provider cannot know which resolvers admit
	// it, so it never declares its own exposure; it only declares what it can
	// do. Every registered provider MUST return a non-zero Capability (C1).
	Capability() Capability

	// DefaultPathCriticality returns sensible production/test/example defaults
	// for this ecosystem (RF-10), overridable in .codefit.yaml.
	DefaultPathCriticality() config.PathCriticality

	// AnalyzeSecurity runs the provider's language-specific static security
	// analysis (the AST layer of the pyramid) and returns deterministic
	// findings with their natural, pre-path-criticality severity.
	AnalyzeSecurity(src SourceFile) ([]findings.Finding, error)

	// AnalyzePractices runs the provider's best-practice checks.
	AnalyzePractices(src SourceFile) ([]findings.Finding, error)

	// AnalyzeSurface maps the auditable structural surface of a file (PRD
	// section 10): it enumerates, per category, every structure the agent
	// should reason about (e.g. HTTP handlers to verify authorization on). It
	// does not judge whether an item is vulnerable.
	//
	// Provisional: this parser-agnostic, provider-owns-analysis shape (ADR 0001)
	// is revisited in Fase 1 against the real TypeScript provider, where a
	// declarative SurfaceQuery model may replace it.
	AnalyzeSurface(src SourceFile) ([]findings.SurfaceItem, error)
}

LanguageProvider is the contract every supported language implements. The core depends only on this interface, never on a concrete language — which is what lets codefit scale to new languages without changing the engine.

The provider owns its parser (go/ast for Go, tree-sitter for TS/Java/Python later) and exposes analysis that returns findings, so the interface stays parser-agnostic (see ADR 0001).

type QueryExtractor ¶ added in v0.2.4

type QueryExtractor interface {
	ExtractQueryFilters(src SourceFile) ([]query.QueryFilter, error)
}

QueryExtractor is the optional capability a provider implements to extract the neutral query-filter facts from application code — the CODE side of the code↔schema cross (index-vs-query), mirroring how SchemaParser produces the SCHEMA side. It is intentionally NOT part of LanguageProvider: the caller resolves it by type-assertion (provider.(providers.QueryExtractor)), exactly as SchemaParser and CoverageManifest are resolved today (ADR 0014, ADR 0029). Convergence into LanguageProvider waits for a second real extractor to validate the shape.

It is per-file and filesystem-free, mirroring LanguageProvider.AnalyzeSurface: it receives one already-read SourceFile and returns the query filters found in it; the caller walks the project. A file with no column-filtering query yields nil — a query that filters nothing has nothing to cross against an index.

type RuleLimit ¶ added in v0.2.9

type RuleLimit struct {
	ID    string // rule id the limit qualifies; MUST be in the same RuleSet's Declared
	Limit string // what the rule does not cover, and why that is declared rather than fixed
}

RuleLimit records that a rule the provider DOES implement covers less than its id suggests, and says exactly how much less.

This is a third kind of fact, distinct from both of its neighbours, and the distinction is what keeps a coverage answer honest:

Declared      — "this rule is covered"
ExcludedRule  — "this rule will NEVER be covered", and why
RuleLimit     — "this rule IS covered, but not over this shape", and why

Reusing ExcludedRule for a limit would have been ADR 0066's lie pointed backwards: SEC-001 is covered, so recording it as an exclusion would invent a hole that does not exist, exactly as a phantom exclusion invents one that never did.

Limit is expected to be cited BY REFERENCE from wherever the gap actually lives (a const beside the code that causes it), never copied. A copied string is a second place to be wrong; a compile-time reference cannot drift.

type RuleSet ¶ added in v0.2.9

type RuleSet struct {
	Declared   []string // rule IDs, sorted
	Enumerable bool
	Excluded   []ExcludedRule
	// Limits qualify rules this family DOES cover — see RuleLimit.
	Limits []RuleLimit
}

RuleSet is what a provider declares for one deterministic rule family (security or practices): the rule IDs it implements, and whether that list is derivable from a real rule loader (Enumerable: true, e.g. TypeScript's YAML-backed security rules) or a hand-maintained mirror of the provider's own Go source (Enumerable: false, e.g. Go's AST-detector rules, which have no All()/ID() loader today). Declared is never a count — a count cannot be checked against anything; a list of IDs can (Control A, for the Enumerable==true case). Excluded names rule ids this family permanently will NOT implement, each with why (see ExcludedRule) — checked disjoint from Declared by ValidExclusions (C6).

func (r RuleSet) ValidExclusionSource() (ok bool, phantom []string)

func (r RuleSet) ValidExclusions() bool

func (r RuleSet) ValidLimits() (ok bool, orphan []string)

type SchemaParser ¶ added in v0.2.0

type SchemaParser interface {
	ParseSchema(sources []SourceFile) (*db.Schema, error)
}

SchemaParser is the optional capability a provider implements to parse a database schema into the neutral db.Schema model. It is intentionally NOT part of LanguageProvider: the caller resolves it by type-assertion (provider.(providers.SchemaParser)), exactly as codefit-coverage resolves CoverageManifest today — convergence into LanguageProvider waits for a second real parser to validate the shape (ADR 0003, ADR 0014).

The interface lives here, beside LanguageProvider, while its return type lives in core/db — mirroring how LanguageProvider.AnalyzeSurface returns findings.SurfaceItem. providers depends on core/db; core/db never depends on providers (the one-way dependency invariant of ADR 0014).

The implementation is filesystem-free: it receives the already-read SourceFiles (content in hand), never a path. The caller resolves cfg.Database.SchemaPaths from disk.

type SourceFile ¶

type SourceFile struct {
	Path    string
	Content []byte
}

SourceFile is the input to a provider's analysis: a project-relative path and the file's raw content.