Documentation
¶
Overview ¶
Package baseline tracks codefit's view of a project's audited surface across scans. The baseline is a committed file (.codefit-baseline) — shared knowledge like .codefit.yaml — that records every item codefit knows about, identified by a content Fingerprint (see findings.Fingerprint), so a re-scan can tell what is new, unchanged (known), changed, or gone.
Safeguard by certainty (PRD RF-08):
- SURFACE (a question) becomes known automatically once recorded; a re-scan silences it. accept marks it acknowledged (a false positive / accepted debt).
- DETERMINISTIC (an affirmation, confidence 1.0) is NEVER known automatically: it is shown on every scan until a human accepts it explicitly with a reason. Silencing an affirmation is graver than silencing a question, so it needs the stronger safeguard.
codefit never edits code — only this file.
Package baseline implements the adoption baseline (PRD RF-08): a committed snapshot of a project's findings so that, with baseline enabled, codefit reports only new findings while pre-existing debt is recorded (baselined: true) and does not block. This makes adopting codefit on an existing project painless (Scenario B).
Status: SKELETON. This declares the [Snapshot] type and the [Store] contract. The snapshot/diff logic and the on-disk format (.codefit/baseline.json) are implemented in Fase 1.
Index ¶
- Constants
- type Ack
- type AuthzHelper
- type Baseline
- func (b *Baseline) Accept(fps []string, reason, at string) (accepted []string, err error)
- func (b *Baseline) List(filter string) ([]Entry, error)
- func (b *Baseline) Prune(fps []string) (pruned []string)
- func (b *Baseline) RecognizedAuthzHelpers(language string) []string
- func (b *Baseline) RegisterAuthzHelper(name, language, reason, at string) (added bool, err error)
- func (b *Baseline) Save(path string) error
- func (b *Baseline) UnregisterAuthzHelper(name, language string) bool
- type Counts
- type DiffResult
- type Entry
- type Item
- type Observed
- type State
Constants ¶
const Name = ".codefit-baseline"
Name is the baseline file, committed at the repo root.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Ack ¶
type Ack struct {
Reason string `yaml:"reason"`
At string `yaml:"at"`
By string `yaml:"by"` // always "human": codefit never acknowledges on its own
}
Ack records that a human accepted an item (false positive or accepted debt).
type AuthzHelper ¶ added in v0.1.2
type AuthzHelper struct {
Name string `yaml:"name"`
Language string `yaml:"language"`
Reason string `yaml:"reason"`
At string `yaml:"at"`
By string `yaml:"by"` // always "human": codefit never registers on its own
}
AuthzHelper is a project-specific authorization helper the AGENT identified by reasoning over the code and a HUMAN approved registering — so codefit recognizes it on later scans without the agent re-reasoning (it augments the built-in NextAuth-style set per project). It is project knowledge, like an acknowledged item: persisted, committed, recorded by:"human". Registering a helper changes a FACT (known_authz_detected for the authz concern), never a verdict — it clears the AUTHZ gap, never the IDOR/ownership gap (ADR 0013, ADR 0006 amended).
type Baseline ¶
type Baseline struct {
Version string `yaml:"version"`
Items []Item `yaml:"items"`
AuthzHelpers []AuthzHelper `yaml:"authz_helpers,omitempty"`
}
Baseline is the committed set of known items plus the project's registered authz helpers.
func Load ¶
Load reads the baseline at path. A missing file is NOT an error: it returns an empty baseline (the first scan creates it).
func (*Baseline) Accept ¶
Accept marks the given fingerprints as acknowledged by a human. A reason is mandatory; an unknown fingerprint is an error (nothing is changed). codefit records by:"human" — it never acknowledges on its own.
func (*Baseline) List ¶
List returns the baseline items as Entries, filtered by state: "" (all), "known" (not acknowledged), or "acknowledged". An unknown filter is an error.
func (*Baseline) Prune ¶
Prune removes the given fingerprints from the baseline (used for gone items the caller has confirmed no longer exist in the code). Returns the removed fps.
func (*Baseline) RecognizedAuthzHelpers ¶ added in v0.1.2
RecognizedAuthzHelpers returns the names of the helpers registered for a language — the set a scan adds to the built-in authz helpers for that project.
func (*Baseline) RegisterAuthzHelper ¶ added in v0.1.2
RegisterAuthzHelper records a project-specific authz helper as recognized, by:"human". A name, language, and reason are mandatory (the reason is the human's justification, as for Accept). Idempotent: registering an already-known (language, name) is a no-op that returns added=false. codefit never registers on its own — the agent proposes, the human decides (the skill enforces it; codefit records the decision).
func (*Baseline) UnregisterAuthzHelper ¶ added in v0.1.2
UnregisterAuthzHelper removes a registered helper (the reversal of RegisterAuthzHelper — the developer's decision is always reversible). Returns whether a helper was removed.
type Counts ¶
type Counts struct {
New, Changed, Known, Acknowledged, Gone, AffirmationsShown int
}
Counts is the at-a-glance delta.
type DiffResult ¶
type DiffResult struct {
State map[string]State // fp → state, for observed items
Shown map[string]bool // fp → must be shown (not silenced)
Gone []Item // baseline items no longer observed (prune candidates)
Counts Counts
Next *Baseline // the baseline to persist
}
DiffResult is the full comparison of a scan against the previous baseline.
func Diff ¶
func Diff(prev *Baseline, observed []Observed) DiffResult
Diff compares the observed scan against the previous baseline and returns the per-item delta, what must be shown, the gone candidates, and the next baseline to persist. It never silences a deterministic affirmation that has not been acknowledged.
type Entry ¶
type Entry struct {
Fingerprint string `json:"fingerprint"`
File string `json:"file"`
Category string `json:"category"`
State State `json:"state"` // known | acknowledged
Reason string `json:"reason,omitempty"`
At string `json:"at,omitempty"`
}
Entry is a read-only projection of a baseline item for codefit-baseline-list: just what the agent needs to reference an item in accept/prune. It omits the snippet on purpose (the agent supplies the reasoning; this keeps the list small).
type Item ¶
type Item struct {
FP string `yaml:"fp"`
Category string `yaml:"category"`
File string `yaml:"file"`
Snippet string `yaml:"snippet,omitempty"`
Ack *Ack `yaml:"acknowledged,omitempty"`
}
Item is one tracked surface item or deterministic finding. Snippet is a human-readable display only; it is never the matched secret (the identity is the content-hashed FP). Ack is non-nil only when the item was accepted.
Source Files