Objectives
An objective is one thing a campaign tracks: a pattern to remove, something each sector must have, or a number to reach. Its ledger lists every place it still fires.
objectives: no-legacy-write: holdout: match match: { syntax: { pattern: "legacyBilling.write($$$)" } } probes: { fires: [{ path: src/billing/a.ts, source: "legacyBilling.write(x)" }] }Fields
Section titled “Fields”Set exactly one of match, sector and measure.
| Field | Meaning |
|---|---|
holdout |
What one ledger entry is: file, declaration, match or sector. Required with match or sector. |
match |
A per-file detector: all, any, not over terms. |
sector |
A term over the whole sector: has, oneRoot or oneHost. See Sectors. |
measure |
A number per sector. See Scalar objectives. |
until |
The phase at which the objective stops counting (exclusive). See Phases. |
how, why |
Override the campaign’s message and rationale for this objective. |
probes |
Sources it must fire on, and stay silent on. Required with match. |
An objective no phase names counts in every phase. Share a detector across campaigns with
defs/use.
The holdout
Section titled “The holdout”holdout sets what one ledger entry is:
| Holdout | One entry is | Ledger key |
|---|---|---|
file |
a whole file | file |
declaration |
a named declaration | file#Name |
match |
one matched expression | file#Anchor#hash |
sector |
the sector itself | ~ |
Keys are relative to the sector’s root, so moving a sector’s folder changes no entries. A
match key anchors on its enclosing declaration, so reformatting or editing elsewhere keeps
the entry; if the matched text itself changes, objectives clear updates the hash without
counting it as progress. A top-level match has no anchor and is keyed by its hash.
Mixing term levels
Section titled “Mixing term levels”File-level terms are path, imports, requires, content and a boolean fn.
Declaration-level terms are exports and members. Match-level terms are syntax, report
and a list-returning fn.
- In a
fileobjective, each term means “the file contains one”, andnotmeans “contains none”. - In a
declarationormatchobjective, declaration and match terms produce candidates, and a file term keeps all of them or none. A declaration term in amatchobjective tests the match’s enclosing declaration; a match term in adeclarationobjective yields the declaration it sits in. notonly removes candidates:all: [syntax A, not syntax B]works, butnot syntax Balone matches nothing and fails its probe.
Probes
Section titled “Probes”Probes prove a detector fires. If any probe fails, the policy refuses to load.
probes: fires: - path: src/legacy/util.ts source: 'import { sdk } from "vendor"; export const x = sdk();' edges: { vendor: { external: vendor } } files: [src/legacy/util.test.ts] ignores: - path: src/util.ts source: "export const x = 1;"| Field | Meaning |
|---|---|
fires |
Sources the objective must report. At least one. |
ignores |
Sources it must not report. A failure names the term that let it through. |
path |
The file the probe stands for. Must be inside the campaign’s scope. |
source |
The file’s contents. Required when the detector has a content, syntax, exports, members or fn term. |
edges |
Where each import in source resolves, in the three forms imports.resolves takes. |
files |
Sibling files that exist, for requires. |
report |
Diagnostics a report term would return, with one-based positions. |
value |
For a scalar, the number the file contributes. |
has terms and match perimeters take probes the same way.