Detectors
An objective’s match is a detector: the pattern the campaign is removing. You build it from the
terms below and combine them with all, any and not, nested to any depth.
| Term | Holds when | Example |
|---|---|---|
path |
the repo-relative path matches file (a regex) and not fileNot; with subject (a group number) and convention, that group has the shape |
{ file: "^src/legacy/" } |
imports |
an import resolves to resolves (a glob, { external } or { builtin }), pulling one of symbols if given |
{ resolves: { external: moment } } |
exports |
an export site matches the surface selectors name, kinds, declares, reexport |
{ kinds: [default] } |
members |
a member or call matches the members selectors subject (members or calls), name, in, declares |
{ subject: calls, name: readFileSync } |
requires |
every named sibling file exists (the structure parity strings) |
["{base}.test.ts"] |
content |
the regular expression matches the file’s text (multiline) | { regex: "TODO\\(migrate\\)" } |
syntax |
an ast-grep rule finds a node; see below | { pattern: "console.log($$$)" } |
report |
another tool reported a diagnostic on the file; see below | { file: tsc.txt, format: tsc } |
fn |
your function returns true or a list of subjects; see below |
./campaigns/rsc.mjs#needsClientBoundary |
path.convention is kebab-case, camelCase, PascalCase, snake_case or { regex }; a
rename campaign detects the old shape. Each term object has exactly one key, so a misspelling is a
load error.
client-boundary: holdout: file match: all: - not: { content: { regex: '^["'']use client["'']' } } - any: - syntax: { pattern: "$HOOK($$$)", where: { HOOK: { regex: "^use[A-Z]" } } } - imports: { resolves: { external: framer-motion } } probes: fires: [{ path: app/x.tsx, source: "export default () => { useState(); }" }]The syntax term
Section titled “The syntax term”syntax is an ast-grep rule (pattern, kind,
regex, has, inside, precedes, follows, nthChild, all, any, not) plus an optional
where.
$NAMEmatches one node and$$$any number.kindtakes tree-sitter node kinds:class_declaration,call_expression,arrow_function.hasandinsidesearch only direct children or parents unless you addstopBy: end.
where narrows a metavariable by its text (regex) or by the import that bound it (binding):
where: HOOK: { regex: "^use[A-Z]" } BASE: { binding: { resolves: { external: react }, member: [Component, PureComponent] } }binding follows the identifier to its import, so it matches C after
import { Component as C } and React.Component after import React from "react".
The report term
Section titled “The report term”report turns another tool’s diagnostics, such as type errors, into matches you can ratchet down.
tsc: holdout: match match: report: { command: "npx tsc --noEmit --pretty false", format: tsc, codesNot: [TS6133] } probes: fires: [{ path: src/a.ts, report: [{ line: 1, code: TS2551, message: "Property 'x'…" }] }] ignores: [{ path: src/b.ts, report: [{ line: 1, code: TS6133, message: "'x' is unused" }] }]| Field | Meaning |
|---|---|
command |
a command, or list of commands, run from the repository root. A non-zero exit is fine |
file |
instead of command: a report file (or list) written by an earlier step, relative to the repository root |
format |
tsc, eslint (--format json), oxlint (--format json), or regex |
pattern |
required for regex: named groups file and line, optional column, code, message; one match per line |
codes |
only these codes (TS2551, no-unused-vars, eslint(no-debugger)). Omit for all |
codesNot |
codes to exclude |
Give exactly one of command and file. A probe answers the term with
report: [{ line, column?, code?, message? }] (one-based), so nothing runs at load.
- Lists. Pass a list to run one command per project. They run in parallel; duplicate diagnostics count once.
- Timing. Commands run once per
checkand once per plugin load, including each editor session. For a slow tool, write the report in an earlier step and usefile. - Keys. Each diagnostic is keyed by enclosing declaration, code and a hash of the message, so
it survives line moves. Repeats in one declaration get
~2,~3. - Failures. A command that can’t run, or a missing
file, failscheckonce. The plugin reports it on the first file the campaign selects.
The function term
Section titled “The function term”fn: "module#export" names a function, relative to the root manifest; a
non-function export is refused at load. In a .mjs manifest you can pass the function itself.
/** @type {import("@goodbones/core").CampaignPredicate} */export const needsClientBoundary = ({ file, text, facts, syntax }) => facts.specifiers.some((one) => one.startsWith("@vendor/browser-")) || (syntax?.findAll({ pattern: "window.$X" }).length ?? 0) > 0;It receives the file’s path, text, facts (specifiers, bindings, memberSites, exportSites)
and syntax tree (null without a matcher). It returns a boolean, or { subject, range? }[]:
declaration names for a declaration objective, ledger keys for a match one.