Skip to content

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)" }] }

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.

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.

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 file objective, each term means “the file contains one”, and not means “contains none”.
  • In a declaration or match objective, declaration and match terms produce candidates, and a file term keeps all of them or none. A declaration term in a match objective tests the match’s enclosing declaration; a match term in a declaration objective yields the declaration it sits in.
  • not only removes candidates: all: [syntax A, not syntax B] works, but not syntax B alone matches nothing and fails its probe.

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.