Skip to content

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

syntax is an ast-grep rule (pattern, kind, regex, has, inside, precedes, follows, nthChild, all, any, not) plus an optional where.

  • $NAME matches one node and $$$ any number.
  • kind takes tree-sitter node kinds: class_declaration, call_expression, arrow_function.
  • has and inside search only direct children or parents unless you add stopBy: 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".

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 check and once per plugin load, including each editor session. For a slow tool, write the report in an earlier step and use file.
  • 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, fails check once. The plugin reports it on the first file the campaign selects.

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.