@cosyte/script-utils 0.1.1 → 0.1.3

package/claude-card.js

@@ -0,0 +1,296 @@
+// @cosyte/script-utils/claude-card
+//
+// THE CLAUDE.md CARD CHECKER. Every Cosyte repository keeps a short CLAUDE.md that every Claude Code
+// session in it reads first: what must pass before a push (`## Gate`), what a change can break that
+// a green gate would not show (`## Hazard`), and the rules that bind there (`## Rules`). The spec is
+// `documentation/claude-card.md` in cosyte/config; this file is what enforces it.
+//
+// THE RULES, each one id a finding names:
+//
+//   title          line 1 is `# <name>` (after a YAML front matter block, when there is one)
+//   intro          a paragraph sits between the title and the first section
+//   section-missing  `## Gate`, `## Hazard` and `## Rules` are all there (a heading may go on
+//                  after its word: `## Hazard: ...`, `## Rules that bind here`)
+//   section-order  in that order
+//   section-extra  no other level-2 heading
+//   section-empty  none of the three is empty
+//   lines          at most `CARD_MAX_LINES` lines, counted as `wc -l` counts them
+//   width          every line at most `CARD_MAX_LINE_LENGTH` characters, code included
+//   bytes          at most `CARD_MAX_BYTES` bytes of UTF-8
+//   agents-import  when an AGENTS.md sits beside the card, the card imports it on a line of its own
+//                  (`@AGENTS.md`); an import of an AGENTS.md that is not there is a finding too
+//
+// EXIT CODES, the contract every gate here keeps: 0 the card follows the spec, 1 a finding, 2 the
+// gate could not read its input.
+//
+// ZERO DEPENDENCIES AND NO BUILD STEP, like the rest of this package.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { isCliEntrypoint } from "./index.js";
+
+/** The most lines a card may have. */
+export const CARD_MAX_LINES = 60;
+
+/** The most characters (code points) a line may have, code blocks included. */
+export const CARD_MAX_LINE_LENGTH = 100;
+
+/**
+ * The most bytes of UTF-8 a card may have: 5 KiB, about 1,300 tokens, paid by every session in the
+ * repository before any work starts. 60 lines of 100 characters is up to 6,060 bytes, so this is
+ * the cap that binds; the spec gives the measurement behind the number.
+ */
+export const CARD_MAX_BYTES = 5_120;
+
+/** The three sections, in order. A heading matches when it is the word, or the word then more. */
+export const CARD_SECTIONS = Object.freeze(["Gate", "Hazard", "Rules"]);
+
+/** The line that imports AGENTS.md into the card. */
+export const AGENTS_IMPORT = "@AGENTS.md";
+
+/** Every rule id a finding can carry, with what it requires. */
+export const CARD_RULES = Object.freeze({
+  title: "The card opens with `# <name>`, after a YAML front matter block if it has one.",
+  intro: "A paragraph sits between the title and the first section.",
+  "section-missing": "`## Gate`, `## Hazard` and `## Rules` are all there.",
+  "section-order": "The three sections appear in that order.",
+  "section-extra": "There is no other level-2 heading.",
+  "section-empty": "None of the three sections is empty.",
+  lines: `At most ${CARD_MAX_LINES} lines.`,
+  width: `Every line is at most ${CARD_MAX_LINE_LENGTH} characters, code blocks included.`,
+  bytes: `At most ${CARD_MAX_BYTES.toLocaleString("en-US")} bytes.`,
+  "agents-import": `The card imports a sibling AGENTS.md on a line of its own (${AGENTS_IMPORT}).`,
+});
+
+/** Which of the three sections a level-2 heading's text is, or `null` for none of them. */
+function sectionOf(text) {
+  for (const word of CARD_SECTIONS) {
+    if (text.startsWith(word) && !/[A-Za-z0-9]/.test(text.charAt(word.length))) return word;
+  }
+  return null;
+}
+
+/**
+ * An ATX heading's level and text, or `null` when the line is not one.
+ *
+ * Read with index arithmetic rather than one regular expression: a pattern of the shape
+ * `[ \t]+(.*?)[ \t]*#*[ \t]*$` backtracks polynomially on a long run of tabs or spaces.
+ */
+function parseHeading(line) {
+  let level = 0;
+  while (level < line.length && line[level] === "#") level += 1;
+  if (level === 0 || level > 6) return null;
+  if (line[level] !== " " && line[level] !== "\t") return null;
+  let text = line.slice(level).trim();
+  // An optional closing run of `#`, which counts only when a space or tab comes before it.
+  let end = text.length;
+  while (end > 0 && text[end - 1] === "#") end -= 1;
+  if (end === 0) text = "";
+  else if (end < text.length && (text[end - 1] === " " || text[end - 1] === "\t")) {
+    text = text.slice(0, end).trimEnd();
+  }
+  return { level, text };
+}
+
+/** The headings outside fenced code blocks, with 0-based line numbers. */
+function headingsOf(lines) {
+  const headings = [];
+  let fence = null;
+  lines.forEach((line, index) => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence !== null) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+      return;
+    }
+    if (marker) {
+      fence = marker[1];
+      return;
+    }
+    const heading = parseHeading(line);
+    if (heading !== null) headings.push({ ...heading, line: index });
+  });
+  return headings;
+}
+
+/**
+ * Check a CLAUDE.md card against the spec.
+ *
+ * @param {string} text The card's contents.
+ * @param {{ agentsMd?: boolean }} [context] `agentsMd`: whether an AGENTS.md sits beside the card.
+ *   When it is left out, the import rule is not checked.
+ * @returns {{ rule: string, line: number, message: string }[]} The findings; empty when the card
+ *   follows the spec. `line` is 1-based, 0 for the whole file.
+ */
+export function checkClaudeCard(text, context = {}) {
+  if (typeof text !== "string") throw new TypeError("checkClaudeCard(text) expects a string.");
+  const findings = [];
+  const add = (rule, line, message) => findings.push({ rule, line, message });
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+
+  // ---- Size ---------------------------------------------------------------------------------
+  const lineCount = (text.match(/\n/g) ?? []).length;
+  if (lineCount > CARD_MAX_LINES) {
+    add("lines", 0, `the card is ${lineCount} lines; the limit is ${CARD_MAX_LINES}.`);
+  }
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes > CARD_MAX_BYTES) {
+    add(
+      "bytes",
+      0,
+      `the card is ${bytes.toLocaleString("en-US")} bytes; the limit is ` +
+        `${CARD_MAX_BYTES.toLocaleString("en-US")}. Move detail to documentation/agent-notes.md.`,
+    );
+  }
+  lines.forEach((line, index) => {
+    const length = [...line.replace(/\r$/, "")].length;
+    if (length > CARD_MAX_LINE_LENGTH) {
+      add(
+        "width",
+        index + 1,
+        `line ${index + 1} is ${length} characters; the limit is ${CARD_MAX_LINE_LENGTH}.`,
+      );
+    }
+  });
+
+  // ---- Title and intro ------------------------------------------------------------------------
+  // A YAML front matter block may come first (a repository whose documents carry one); the title
+  // is then the first line after it.
+  let titleLine = 0;
+  if (lines[0] === "---") {
+    const close = lines.indexOf("---", 1);
+    if (close > 0) titleLine = close + 1;
+    while (titleLine < lines.length && lines[titleLine].trim() === "") titleLine += 1;
+  }
+  if (!/^# \S/.test(lines[titleLine] ?? "")) {
+    add("title", titleLine + 1, "the card must open with its title, `# <name>`.");
+  }
+  const headings = headingsOf(lines);
+  const firstSection = headings.find((h) => h.level === 2);
+  const introEnd = firstSection === undefined ? lines.length : firstSection.line;
+  const intro = lines
+    .slice(titleLine + 1, introEnd)
+    .filter((line) => line.trim() !== "" && line.trim() !== AGENTS_IMPORT && !/^#/.test(line));
+  if (intro.length === 0) {
+    add("intro", 2, "say what this repository is in a paragraph under the title.");
+  }
+
+  // ---- Sections -------------------------------------------------------------------------------
+  const found = new Map();
+  for (const heading of headings.filter((h) => h.level === 2)) {
+    const word = sectionOf(heading.text);
+    if (word === null) {
+      add(
+        "section-extra",
+        heading.line + 1,
+        `"## ${heading.text}" is not one of the card's sections (${CARD_SECTIONS.join(", ")}); ` +
+          `make it a ### inside one of them, or move it to the agent notes.`,
+      );
+    } else if (!found.has(word)) {
+      found.set(word, heading);
+    } else {
+      add("section-extra", heading.line + 1, `"## ${heading.text}" repeats the ${word} section.`);
+    }
+  }
+  for (const word of CARD_SECTIONS) {
+    if (!found.has(word)) add("section-missing", 0, `the card has no "## ${word}" section.`);
+  }
+  const present = CARD_SECTIONS.filter((word) => found.has(word));
+  for (let i = 1; i < present.length; i += 1) {
+    if (found.get(present[i]).line < found.get(present[i - 1]).line) {
+      add(
+        "section-order",
+        found.get(present[i]).line + 1,
+        `"## ${present[i]}" must come after "## ${present[i - 1]}" (the order is ` +
+          `${CARD_SECTIONS.join(", ")}).`,
+      );
+      break;
+    }
+  }
+  for (const [word, heading] of found) {
+    const next = headings.find((h) => h.line > heading.line && h.level <= 2);
+    const body = lines.slice(heading.line + 1, next === undefined ? lines.length : next.line);
+    if (body.every((line) => line.trim() === "")) {
+      add("section-empty", heading.line + 1, `the ${word} section is empty.`);
+    }
+  }
+
+  // ---- AGENTS.md ------------------------------------------------------------------------------
+  if (typeof context.agentsMd === "boolean") {
+    const imports = lines.some((line) => line.trim() === AGENTS_IMPORT);
+    if (context.agentsMd && !imports) {
+      add(
+        "agents-import",
+        0,
+        `an AGENTS.md sits beside the card, so the card imports it on a line of its own: ` +
+          `${AGENTS_IMPORT}.`,
+      );
+    }
+    if (!context.agentsMd && imports) {
+      add(
+        "agents-import",
+        0,
+        `the card imports ${AGENTS_IMPORT}, and there is no AGENTS.md beside it.`,
+      );
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Run the card checker over one repository: read its CLAUDE.md, note whether an AGENTS.md sits
+ * beside it, report, and return the exit code. It never exits the process.
+ *
+ * @param {{ dir?: string, argv?: string[] }} [options] `dir` is the repository root (default: the
+ *   working directory). `argv` is the CLI arguments, read only for `--dir <path>`.
+ * @returns {0 | 1 | 2} 0 the card follows the spec, 1 a finding, 2 the card could not be read.
+ */
+export function runClaudeCardGate(options = {}) {
+  let dir = options.dir ?? process.cwd();
+  const argv = options.argv ?? [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--dir" && typeof argv[i + 1] === "string") {
+      dir = argv[i + 1];
+      i += 1;
+    } else if (argv[i] !== "--") {
+      process.stderr.write(
+        `CLAUDE.md card: ${JSON.stringify(argv[i])} is not an argument this check accepts (only ` +
+          `--dir <repository root>). Nothing was checked.\n`,
+      );
+      return 2;
+    }
+  }
+  dir = resolve(dir);
+
+  let text;
+  try {
+    text = readFileSync(join(dir, "CLAUDE.md"), "utf8");
+  } catch (err) {
+    process.stderr.write(`CLAUDE.md card: could not read CLAUDE.md in ${dir}: ${err.message}\n`);
+    return 2;
+  }
+  const findings = checkClaudeCard(text, { agentsMd: existsSync(join(dir, "AGENTS.md")) });
+  if (findings.length === 0) {
+    const lineCount = (text.match(/\n/g) ?? []).length;
+    process.stdout.write(
+      `CLAUDE.md card: follows the spec (${lineCount} of ${CARD_MAX_LINES} lines, ` +
+        `${Buffer.byteLength(text, "utf8").toLocaleString("en-US")} of ` +
+        `${CARD_MAX_BYTES.toLocaleString("en-US")} bytes).\n`,
+    );
+    return 0;
+  }
+  const report = findings
+    .map((f) => `  CLAUDE.md${f.line > 0 ? `:${f.line}` : ""} [${f.rule}] ${f.message}`)
+    .join("\n");
+  process.stderr.write(
+    `CLAUDE.md card: CLAUDE.md does not follow the card spec.\n${report}\n` +
+      `${findings.length} finding(s). The spec is documentation/claude-card.md in cosyte/config.\n`,
+  );
+  return 1;
+}
+
+if (isCliEntrypoint(import.meta.url)) {
+  process.exitCode = runClaudeCardGate({ argv: process.argv.slice(2) });
+}

package/internal-refs.d.ts

@@ -46,9 +46,9 @@ export interface ExtraRule {
   /** What a hit report calls it. */
   name: string;
   /** One pattern, as a source string or a `RegExp`. */
-  pattern?: string | RegExp;
+  pattern?: string | RegExp | { source: string; flags?: string };
   /** Several patterns, when one rule needs two case policies. */
-  patterns?: (string | RegExp)[];
+  patterns?: (string | RegExp | { source: string; flags?: string })[];
   /** Text this rule MUST match. At least one is required. */
   positives: string[];
   /** Text this rule must NOT match. At least one is required: it is what stops a widening. */
@@ -221,3 +221,13 @@ export declare const DEFAULT_EXIT_CODES: InternalRefsExitCodes;
 
 /** Option names refused by name, with the reason each one is not something a caller may supply. */
 export declare const REFUSED_OPTIONS: ReadonlyMap<string, string>;
+
+/** Where the command-line form reads the repository's axes: `scripts/internal-refs.json`. */
+export declare const INTERNAL_REFS_CONFIG_PATH: "scripts/internal-refs.json";
+
+/**
+ * The command-line form: run the gate over the repository in the working directory, with the
+ * axes read from `scripts/internal-refs.json` (or `--config <path>`). Exit 0 clean, 1 hits, 2 the
+ * gate could not run. `node node_modules/@cosyte/script-utils/internal-refs.js`.
+ */
+export declare function runInternalRefsCli(argv: string[]): number;

package/internal-refs.js

@@ -24,8 +24,16 @@
 // change what this gate looks for or what it concludes.
 
 import { execFileSync } from "node:child_process";
-import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * The exit codes this gate assigns, as a caller may redeclare them.
@@ -332,7 +340,7 @@ export function compileCanonicalRules(resolved) {
       name: "phase or wave language",
       patterns: [
         new RegExp(
-          `\\b(?:roadmap phase\\b[ ]?[A-Za-z0-9]*|${PHASE_NOT_CLINICAL}phase[ -]${PHASE_NOT_FIELD}` +
+          `\\b(?:roadmap phases?\\b[ ]?[A-Za-z0-9]*|${PHASE_NOT_CLINICAL}phases?[ -]${PHASE_NOT_FIELD}` +
             `[A-Za-z0-9]+[a-z]?\\b|wave \\d+\\b|the \\w+ and final phase\\b|` +
             `documentation residual\\b|${ORDINAL} (?:slice|wave)\\b)`,
           "gi",
@@ -340,6 +348,8 @@ export function compileCanonicalRules(resolved) {
       ],
       positives: [
         "Phase 5b closes it (Phase W, Phase-L and the thirteenth slice landed earlier, in wave 2)",
+        // The plural, which ten of the eleven per-repository copies matched (`phases?[ -]`).
+        "Phases 1 to 6 shipped together",
       ],
       negatives: [
         "CSP-1 Study Phase Identifier, CSP-2 Study Phase Start Date/Time, CSP-3 Study Phase End " +
@@ -351,8 +361,12 @@ export function compileCanonicalRules(resolved) {
     {
       id: "adr-reference",
       name: "ADR reference",
-      patterns: [new RegExp("\\bADR[ -]?\\d{3,4}\\b", "gi")],
-      positives: ["Decided in ADR 0015 and restated in ADR-0021"],
+      // `[ /-]`: ten of the eleven per-repository copies also matched an ADR path segment.
+      patterns: [new RegExp("\\bADR[ /-]?\\d{3,4}\\b", "gi")],
+      positives: [
+        "Decided in ADR 0015 and restated in ADR-0021",
+        "Recorded in docs/adr/0001-scope.md",
+      ],
       negatives: ["ADR is not a segment, and 0015 alone is a value"],
     },
     {
@@ -646,13 +660,26 @@ function compileExtraRule(rule, index) {
       }
       continue;
     }
+    // `{ source, flags }`: the form a JSON configuration can carry, so a rule read from
+    // `scripts/internal-refs.json` can be case-insensitive (`"flags": "i"`). `g` is always added.
+    if (isPlainObject(entry) && typeof entry.source === "string") {
+      const flags = typeof entry.flags === "string" ? entry.flags : "";
+      try {
+        patterns.push(new RegExp(entry.source, flags.includes("g") ? flags : `${flags}g`));
+      } catch (cause) {
+        problems.push(`${where} carries a pattern that does not compile: ${String(cause)}`);
+      }
+      continue;
+    }
     if (entry instanceof RegExp) {
       patterns.push(
         new RegExp(entry.source, entry.flags.includes("g") ? entry.flags : `${entry.flags}g`),
       );
       continue;
     }
-    problems.push(`${where} carries a pattern that is neither a string nor a RegExp`);
+    problems.push(
+      `${where} carries a pattern that is neither a string, a RegExp nor a { source, flags } object`,
+    );
   }
   if (patterns.length === 0) problems.push(`${where} declares no pattern`);
   if (!isStringList(rule.positives) || rule.positives.length === 0) {
@@ -1361,3 +1388,101 @@ function report(hits) {
 
 /** Re-exported for a caller that wants to state, in its own docs, what it cannot turn off. */
 export { DEFAULT_EXIT_CODES, REFUSED_OPTIONS };
+
+// ---- The command-line form (ST34) --------------------------------------------
+//
+// `node node_modules/@cosyte/script-utils/internal-refs.js` runs this gate over the repository in
+// the working directory with no caller script: the axes a caller would pass are read from
+// `scripts/internal-refs.json`, the one file a repository keeps for this gate. Keys starting with
+// `$` are notes and are ignored. The exit codes are the house contract, 0 clean, 1 hits, 2 the gate
+// could not run, and the file may not set them, the repository root or the output sinks: the
+// command-line form owns those, and a file that names one is refused rather than half-honoured.
+
+/** Where the command-line form reads the repository's axes. */
+export const INTERNAL_REFS_CONFIG_PATH = "scripts/internal-refs.json";
+
+/** The exit codes of the command-line form. */
+const CLI_EXIT_CODES = Object.freeze({ clean: 0, hits: 1, refuse: 2 });
+
+/** Keys a configuration file may not set, because the command-line form sets them. */
+const CLI_OWNED_KEYS = ["exitCodes", "repoRoot", "write"];
+
+/**
+ * Run the gate from the command line over the repository in the working directory.
+ *
+ * @param {string[]} argv Only `--config <path>` is accepted (default `scripts/internal-refs.json`).
+ * @returns {number} 0 clean, 1 hits, 2 the gate could not run.
+ */
+export function runInternalRefsCli(argv) {
+  let path = INTERNAL_REFS_CONFIG_PATH;
+  const args = argv.filter((arg) => arg !== "--");
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--config" && typeof args[i + 1] === "string") {
+      path = args[i + 1];
+      i += 1;
+    } else {
+      process.stderr.write(
+        `internal-refs: ${JSON.stringify(args[i])} is not an argument this gate accepts (only ` +
+          `--config <path>). Nothing was checked.\n`,
+      );
+      return CLI_EXIT_CODES.refuse;
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(join(process.cwd(), path), "utf8"));
+  } catch (err) {
+    process.stderr.write(
+      `internal-refs: could not read ${path}: ${err.message} Nothing was checked.\n`,
+    );
+    return CLI_EXIT_CODES.refuse;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    process.stderr.write(`internal-refs: ${path} is not a JSON object. Nothing was checked.\n`);
+    return CLI_EXIT_CODES.refuse;
+  }
+  const owned = CLI_OWNED_KEYS.filter((key) => key in parsed);
+  if (owned.length > 0) {
+    process.stderr.write(
+      `internal-refs: ${path} sets ${owned.join(", ")}, which the command-line form sets ` +
+        `itself. Remove ${owned.length === 1 ? "it" : "them"}. Nothing was checked.\n`,
+    );
+    return CLI_EXIT_CODES.refuse;
+  }
+  const config = Object.fromEntries(Object.entries(parsed).filter(([key]) => !key.startsWith("$")));
+  return runInternalRefsScan({ ...config, exitCodes: CLI_EXIT_CODES, repoRoot: process.cwd() });
+}
+
+/**
+ * Whether node was pointed at this file, which is the command-line form.
+ *
+ * SELF-CONTAINED ON PURPOSE: this module is also vendored and copied as a single file, so it may not
+ * import a sibling at load. A file whose name differs from the one node was pointed at cannot be the
+ * entry point, and that is settled without loading anything; only a matching name asks `index.js`'s
+ * `isCliEntrypoint`, and a copy with no `index.js` beside it compares real paths instead. Unsure is
+ * yes, so a gate that cannot tell runs loudly rather than skipping.
+ *
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @returns {Promise<boolean>}
+ */
+async function invokedAsCommand(moduleUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry === "") return false;
+  const own = fileURLToPath(moduleUrl);
+  const stem = (path) => basename(path).replace(/\.[cm]?[jt]s$/, "");
+  if (stem(entry) !== stem(own)) return false;
+  try {
+    const { isCliEntrypoint } = await import("./index.js");
+    return isCliEntrypoint(moduleUrl);
+  } catch {
+    try {
+      return realpathSync(entry) === realpathSync(own);
+    } catch {
+      return true;
+    }
+  }
+}
+
+void invokedAsCommand(import.meta.url).then((command) => {
+  if (command) process.exitCode = runInternalRefsCli(process.argv.slice(2));
+});

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",
     "entrypoint",
     "import-meta",
     "phi",
+    "readme",
     "scripts",
     "cosyte"
   ],
@@ -37,6 +38,22 @@
     "./attw": {
       "types": "./attw.d.ts",
       "default": "./attw.js"
+    },
+    "./readme": {
+      "types": "./readme.d.ts",
+      "default": "./readme.js"
+    },
+    "./claude-card": {
+      "types": "./claude-card.d.ts",
+      "default": "./claude-card.js"
+    },
+    "./catalog": {
+      "types": "./catalog.d.ts",
+      "default": "./catalog.js"
+    },
+    "./agent-notes": {
+      "types": "./agent-notes.d.ts",
+      "default": "./agent-notes.js"
     }
   },
   "files": [
@@ -48,6 +65,15 @@
     "internal-refs.d.ts",
     "attw.js",
     "attw.d.ts",
+    "readme.js",
+    "readme.d.ts",
+    "claude-card.js",
+    "claude-card.d.ts",
+    "catalog.js",
+    "catalog.d.ts",
+    "catalog.json",
+    "agent-notes.js",
+    "agent-notes.d.ts",
     "check-no-emdash.sh",
     "README.md",
     "CHANGELOG.md"

package/phi-scan.d.ts

@@ -274,3 +274,25 @@ export declare function runPhiScan(config: PhiScanConfig): number;
  * is read by NEITHER sweeping route, while a `.md` named explicitly on argv IS scanned.
  */
 export declare function exemptsMarkdown(relPath: string): boolean;
+
+/** Where the command-line form reads what a repository leaves out: `scripts/phi-scan.exclude`. */
+export declare const PHI_EXCLUDE_PATH: "scripts/phi-scan.exclude";
+
+/**
+ * Read an exclusions file (one literal tracked path per line, `#` lines are comments) against the
+ * repository's tracked paths. A directory, a pattern, a repeat or a path git does not track is a
+ * problem, never a silent skip.
+ */
+export declare function readPhiExclusions(
+  text: string,
+  tracked: ReadonlySet<string>,
+): { paths: Set<string>; problems: string[] };
+
+/**
+ * The command-line form: the engine over the repository in the working directory, with exit codes
+ * 0 clean, 1 hits, 2 refuse, the whole repository as the scan root, the `--staged` route reading
+ * everything but Markdown, and `scripts/phi-scan.exclude`. The cross-cutting floor only: a
+ * repository that needs field-level detectors keeps a caller passing `detect`.
+ * `node node_modules/@cosyte/script-utils/phi-scan.js [--staged | <path>...]`.
+ */
+export declare function runPhiScanCli(argv: string[]): number;