@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/cli/biz-ci-gate.js

@@ -19,13 +19,19 @@ const {
   DEFAULT_REPORT_DIR_RELATIVE_PATH,
   runIntegrationSuite,
 } = require('../utils/integrationRun');
-const { verifyDeployContract } = require('../utils/deployContract');
+const { verifyDeployContract, DEPLOY_CONTRACT_SCOPE } = require('../utils/deployContract');
 const { verifyInstallContract } = require('../utils/installContract');
 const {
   verifyEnvCompleteness,
   ENV_SCAN_SCOPE,
   ENV_SCAN_BLIND_SPOTS,
 } = require('../utils/envContract');
+const {
+  verifyTestCoverage,
+  TEST_COVERAGE_SCOPE,
+  TEST_COVERAGE_NOT_MEASURED,
+  PLATFORM_TEST_FILE_PATTERN,
+} = require('../utils/testCoverageContract');
 const { runPreValidation } = require('../utils/preValidation');
 const { checkLibCompat, loadLibrarySet } = require('../utils/libCompat');
 const { buildSchema } = require('../utils/setupDatabase');
@@ -63,18 +69,26 @@ Usage:
 
 Commands:
   verify-contract             Validate integration-contract.json schema, connector flags,
-                             the deploy contract (R1-R7), the installation contract AND
-                             the env contract.
+                             the deploy contract (${DEPLOY_CONTRACT_SCOPE}), the installation contract,
+                             the env contract AND the test-coverage contract.
   verify-env-contract        Env contract only: every environment variable the service
                              repository visibly reads is declared in the contract's env
                              block or covered by a config placeholder / required connector.
                              Prints its measurement boundary on every run.
-  verify-deploy-contract     Deploy contract only (R1-R7): image pin, deploy sequence,
+  verify-test-coverage       Test-coverage contract only: every test file the service jest
+                             config matches is run by the test:all chain or declared in the
+                             contract's stackTiers with the reason it cannot be — and every
+                             platform test file on disk (${PLATFORM_TEST_FILE_PATTERN}) is
+                             matched by that config in the first place.
+  verify-deploy-contract     Deploy contract only (${DEPLOY_CONTRACT_SCOPE}): image pin, deploy sequence,
                              Node major agreement, no published ports, full commit SHA,
                              CI database engine.
-  verify-install-contract    Installation contract only: the docs/setup package every repo
-                             carries, plus the BASELINE/SEED SQL tree required of every repo
-                             whose contract declares a database.
+  verify-install-contract    Installation contract only: the docs/80-setup package every repo
+                             carries, plus — for every repo whose contract declares a database —
+                             the BASELINE/SEED SQL tree, the four headers with VALUES from the
+                             contract's closed vocabularies on every live migrations/**/*.sql
+                             (archive/ and superseded/ excluded), and each BASELINE manifest
+                             naming exactly the files the installer applies, in that order.
   run-prevalidation          Run the service's cookbooks offline against mocked infrastructure
                              and write conn-runtime/validation-proof.json. Replaces the
                              per-service scripts/run-pre-validation.js.
@@ -95,6 +109,15 @@ Common options:
   --contract <path>          Contract path (absolute or relative to service root).
                              Default: ${DEFAULT_CONTRACT_RELATIVE_PATH}
 
+run-prevalidation options:
+  --operation <regex>             Run only the cookbooks holding a step whose operation
+                                  matches this JavaScript regular expression. The matching
+                                  cookbooks run WHOLE — a later step reads what an earlier
+                                  one wrote. A filtered run writes NO validation proof: a
+                                  proof is the claim that the whole cookbook set passed.
+                                  An expression matching nothing is an error, never an
+                                  empty pass.
+
 verify-lib-compat options:
   --libraries <path|url>          Library SSOT source. Default: $LIBRARIES_SSOT_URL
                                   Auth for an https source: $LIBRARIES_SSOT_TOKEN
@@ -109,8 +132,16 @@ wait-connectors options:
 
 write-summary options:
   --output <path>                 Summary artifact path. Default: <service-root>/ci/integration-signal.json
-  --gate-verdict <pass|fail>      Override gate verdict
-  --gate-reason <text>            Override gate reason
+  --gate-verdict <pass|fail>      Report a failure this summary cannot see for itself -
+                                  a step further up the chain that exited non-zero. It may
+                                  only make the verdict WORSE: "pass" over a check measured
+                                  as failing is refused, the verdict stays fail, and the
+                                  artefact's reason names the refusal.
+  --gate-reason <text>            The step that failed. The job watched the chain of
+                                  ci:gate:* steps run, so it is the only party that knows
+                                  which one exited non-zero. Declaring a failing verdict
+                                  without it writes "unknown step failed" - never the name
+                                  of the last check in the row.
 
   Executed test counts are read from ci/integration-run.json, written by
   run-integration. Without that artifact the summary reports them as unknown —
@@ -138,7 +169,7 @@ function resolveContractOptions(options) {
  */
 function reportDeployContract(result) {
   if (result.ok) {
-    process.stdout.write(`[BizCiGate] OK deploy-contract (${result.service}) — R1-R7 satisfied\n`);
+    process.stdout.write(`[BizCiGate] OK deploy-contract (${result.service}) — ${DEPLOY_CONTRACT_SCOPE} satisfied\n`);
     return true;
   }
   for (const violation of result.violations) {
@@ -180,6 +211,39 @@ function reportEnvContract(serviceName, contract, result) {
   return false;
 }
 
+/**
+ * Render the test-coverage result and signal whether it passed.
+ *
+ * The scope line is printed on every run, pass or fail, for the same reason the
+ * env contract prints one: a gate that says "OK" without saying what it looked
+ * at invites the reader to assume it looked at everything. This one compares the
+ * files jest matches against the files the test:all chain and the declared stack
+ * tiers run — and it says out loud that it never checks whether a declared tier
+ * is actually run somewhere.
+ */
+function reportTestCoverage(serviceName, result) {
+  process.stdout.write(`[BizCiGate] test-coverage scope: ${TEST_COVERAGE_SCOPE}\n`);
+  process.stdout.write(`[BizCiGate] test-coverage NOT measured: ${TEST_COVERAGE_NOT_MEASURED}\n`);
+
+  if (result.ok) {
+    const tiers = result.stackTiers.length === 0
+      ? 'no stack tier declared'
+      : result.stackTiers
+        .map((tier) => `${tier.script} (${tier.files.length} file(s)): ${tier.requires}`)
+        .join('; ');
+    process.stdout.write(`[BizCiGate] OK test-coverage (${serviceName}) — `
+      + `${result.totals.matched} file(s) matched, ${result.totals.inTestAll} run by the test:all chain, `
+      + `${result.totals.inStackTiers} in ${result.stackTiers.length} declared stack tier(s) — ${tiers}\n`);
+    return true;
+  }
+
+  for (const violation of result.violations) {
+    process.stderr.write(`[BizCiGate] FAIL ${serviceName} — ${violation.requirement} — ${violation.message}\n`);
+  }
+  process.stderr.write(`[BizCiGate] FAIL ${serviceName} — ${result.violations.length} test-coverage violation(s)\n`);
+  return false;
+}
+
 function reportInstallContract(result) {
   if (result.ok) {
     const half = result.databaseChecked ? 'docs + SQL package' : 'docs (no database declared)';
@@ -202,9 +266,18 @@ function runSetupDb(options) {
   const database = contractInfo.contract.database;
 
   if (!database) {
-    // Skipping is explicit and visible — a service with no database says so by
-    // omitting the block, and that is not the same as a failure to find one.
-    process.stdout.write('[BizCiGate] OK setup-db — no database declared, nothing to build\n');
+    // NOT APPLICABLE, not OK. They are different facts for whoever reads the job
+    // log after a deploy went wrong: OK says the schema was built, this says
+    // there is no schema to build and names the file that decided so. Reporting
+    // a success for work that never happened is the false guarantee
+    // `.claude/rules/automation-gates.md` §5 names, and it is why the step read
+    // as "does nothing" (BIZ-META 2026-09-08).
+    //
+    // Exit stays 0: a service without a database owes no schema, so there is
+    // nothing here to fail on.
+    process.stdout.write(`[BizCiGate] NOT APPLICABLE setup-db — ${contractInfo.contractPath} declares no `
+      + '"database" block, so this service has no schema to build. Nothing was done, and nothing was '
+      + 'expected to be.\n');
     return;
   }
 
@@ -250,7 +323,7 @@ async function runVerifyLibCompat(options) {
 async function runVerifyContract(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
 
-  // The deploy contract (R1-R7) is part of the same mandatory gate: a service
+  // The deploy contract is part of the same mandatory gate: a service
   // whose compose, deploy sequence, Node major or database engine breaks the
   // platform contract must not reach the build stage. Folding it in here means
   // a version bump activates it — no per-repo CI edit, nothing to forget.
@@ -282,6 +355,17 @@ async function runVerifyContract(options) {
     process.exit(1);
   }
 
+  // The test-coverage contract joins on the same argument a third time: a suite
+  // that no job runs fails nowhere, so it looks like coverage and proves nothing.
+  // hello-service carried three such suites for months (measured 2026-09-07,
+  // 17 files matched, 14 run). Folding it in means a version bump activates it.
+  if (!reportTestCoverage(
+    contractInfo.contract.serviceName || path.basename(contractInfo.serviceRoot),
+    verifyTestCoverage({ serviceRoot: contractInfo.serviceRoot, contract: contractInfo.contract })
+  )) {
+    process.exit(1);
+  }
+
   // R6 belongs to the same gate for the same reason. It needs LIBRARIES_SSOT_URL;
   // an unconfigured gate fails loudly rather than passing, so the CI variable
   // must exist before any repo pins a version carrying this check.
@@ -299,38 +383,71 @@ async function runVerifyContract(options) {
 
 
 /**
- * Resolve the service URL from the service's OWN config.
+ * Running cookbooks needs `tests/cookbooks/`, `operations.json` and the handler
+ * modules — nothing else. This command used to resolve the service's own
+ * `@onlineapps/service-wrapper`, run `ConfigLoader.loadAll()` and pass
+ * `service.url` to the runner, which never read it (`this.serviceUrl` appears
+ * nowhere in CookbookTestRunner). `ConfigLoader.loadAll` no longer returns that
+ * field either — the owner removed `port` and `url` from the service shape
+ * (docs/governance/confirmations/biz-service-port-url.md 001), so the value had
+ * been `undefined` for every service on the platform. What the load still did
+ * was make a readable config, an installed wrapper and a resolvable `${ENV}`
+ * placeholder preconditions of a cookbook run that depends on none of them.
+ */
+/**
+ * End the process with this code, once everything written has left the buffers.
+ *
+ * `run-prevalidation` dispatches the service's own v3 handlers in THIS process,
+ * and a handler reaches its schema through a module-level Sequelize pool
+ * (`@onlineapps/conn-base-db` → `createSequelize`). That pool is the service's,
+ * not the runner's: at boot the very same dispatch happens inside
+ * `ServiceWrapper` phase 0.2 and the pool then serves the service for the rest
+ * of its life, so closing connectors after the cookbooks would break the boot
+ * this runner is part of. What differs is the LIFETIME, not the code — a
+ * one-shot command has nothing to serve afterwards.
  *
- * ConfigLoader lives in @onlineapps/service-wrapper (L4) and this package is L3,
- * so it is never a dependency here — it is resolved from the service being
- * validated, which is where it legitimately exists.
+ * Left to end by itself, the command therefore hung: measured 2026-09-14 with a
+ * fixture handler leaving one socket open, every line of output printed, the
+ * proof written, and then nothing until a 15 s kill
+ * (`tests/unit/preValidationCliExit.integration.test.js`). In CI that is a job
+ * that runs to its timeout after the work succeeded.
+ *
+ * `process.exit()` can truncate a write to a pipe, which is how a summary line
+ * disappears from a CI log, so the exit waits for both streams to drain first.
+ *
+ * @param {number} code the exit status
  */
-function resolveServiceUrl(serviceRoot) {
-  let wrapperPath;
-  try {
-    wrapperPath = require.resolve('@onlineapps/service-wrapper', { paths: [serviceRoot] });
-  } catch {
-    throw new Error('[PreValidation] Missing dependency - @onlineapps/service-wrapper is not '
-      + `installed in ${serviceRoot}. Fix: run npm install in the service repository.`);
+function exitWhenFlushed(code) {
+  let pending = 1;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+
+  for (const stream of [process.stdout, process.stderr]) {
+    if (stream.writableLength > 0) {
+      pending += 1;
+      stream.write('', done);
+    }
   }
 
-  const { ConfigLoader } = require(wrapperPath);
-  const config = ConfigLoader.loadAll({ basePath: serviceRoot, env: process.env });
-  return config.service.url;
+  done();
 }
 
 async function runRunPreValidation(options) {
   const outcome = await runPreValidation({
     serviceRoot: path.resolve(options.serviceRoot),
-    serviceUrl: resolveServiceUrl(path.resolve(options.serviceRoot)),
     RunnerClass: require('../CookbookTestRunner'),
     ProofGeneratorClass: require('../validators/ValidationProofGenerator'),
-    logger: console
+    logger: console,
+    operationFilter: options.operation
   });
 
   const { results } = outcome;
-  process.stdout.write(`[BizCiGate] cookbooks — total ${results.total}, `
-    + `passed ${results.passed}, failed ${results.failed} (${results.duration}ms)\n`);
+  // Cookbooks and steps, each under its own name: the line used to print step
+  // counts under the word "cookbooks" (BIZ-converter 2026-08-27).
+  process.stdout.write(`[BizCiGate] cookbooks — ${results.cookbooks.passed}/${results.cookbooks.total} passed, `
+    + `steps ${results.passed}/${results.total} passed, ${results.failed} failed (${results.duration}ms)\n`);
 
   if (!outcome.ok) {
     for (const step of outcome.failedSteps) {
@@ -341,11 +458,21 @@ async function runRunPreValidation(options) {
     }
     process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${results.failed} failed step(s); `
       + 'no validation proof written\n');
-    process.exit(1);
+    exitWhenFlushed(1);
+    return;
+  }
+
+  if (outcome.filteredBy !== null) {
+    process.stdout.write(`[BizCiGate] OK run-prevalidation — filtered by --operation `
+      + `${JSON.stringify(outcome.filteredBy)}, no validation proof written `
+      + `(a proof claims the whole cookbook set passed)\n`);
+    exitWhenFlushed(0);
+    return;
   }
 
   process.stdout.write(`[BizCiGate] OK run-prevalidation — proof ${outcome.proof.validationProof.slice(0, 16)}... `
     + `-> ${outcome.proofPath}\n`);
+  exitWhenFlushed(0);
 }
 
 /** Same checks, runnable on their own — for the cross-repo audit and local use. */
@@ -378,6 +505,17 @@ function runVerifyEnvContract(options) {
   }
 }
 
+/** Same check, runnable on its own — for the cross-repo audit and local use. */
+function runVerifyTestCoverage(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  if (!reportTestCoverage(
+    contractInfo.contract.serviceName || path.basename(contractInfo.serviceRoot),
+    verifyTestCoverage({ serviceRoot: contractInfo.serviceRoot, contract: contractInfo.contract })
+  )) {
+    process.exit(1);
+  }
+}
+
 function runVerifyIntegrationMinimum(options) {
   const result = verifyIntegrationMinimum(options.serviceRoot, options.contractPath);
   process.stdout.write(`[BizCiGate] OK verify-integration-minimum\n`);
@@ -526,6 +664,11 @@ async function main() {
       return;
     }
 
+    if (command === 'verify-test-coverage') {
+      runVerifyTestCoverage(options);
+      return;
+    }
+
     if (command === 'verify-lib-compat') {
       await runVerifyLibCompat(options);
       return;

package/src/cli/oa-lint-scripts.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `npx oa-lint-scripts [--root <dir>] [--api-root <dir>] [--list-scope]
+ * [--files <path...>]` — the SCRIPTS-STANDARD header rules over one repository,
+ * or over the files a caller names.
+ *
+ * The rules are `src/lint/scripts/lintScripts.js`; this file owns the argument
+ * parsing, the report and the exit code, and nothing else. `api/scripts/ci/
+ * lint-scripts.mjs` calls `runCli` rather than re-printing the same lines, so
+ * the api run and a service run cannot grow two dialects of one report
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * No baseline, no skip flag (`automation-gates.md` §3, §1.5).
+ *
+ * @see api/docs/standards/SCRIPTS-STANDARD.md
+ */
+
+const path = require('path');
+
+const { lintScripts, SCRIPT_SCOPE, CITATION_SCOPE } = require('../lint/scripts/lintScripts');
+const { API_CHECKOUT_ROOT } = require('../manifest/workspaceRoot');
+
+/** The name every line of this report opens with; `scripts-lint.bats` reads it. */
+const TOOL = 'lint-scripts';
+
+/** Exit code for a run that could not start at all — distinct from a finding. */
+const USAGE_EXIT = 2;
+
+const USAGE = `${TOOL}.mjs [--root <dir>] [--api-root <dir>] [--list-scope] [--files <path...>]`;
+
+/** Thrown instead of calling `process.exit()`; see `runCli`. */
+class LintAbort extends Error {}
+
+/**
+ * @param {string} message
+ * @throws {LintAbort} always
+ */
+function die(message) {
+  console.error(`[${TOOL}] ERROR: ${message}`);
+  throw new LintAbort(message);
+}
+
+/**
+ * TWO ROOTS, NEVER ONE. `root` is the repository being scanned; `apiRoot` is the
+ * api checkout an `api/…` citation names, which is a convention of the declaring
+ * text rather than a directory of the scanned tree. They coincide only when the
+ * tree being scanned IS the api checkout, and until d.401 the api wrapper
+ * asserted exactly that by handing `--api-root` the scanned root — so a run over
+ * a biz repository turned every `@see api/docs/…` into an S006 about a document
+ * that was there all along (BIZ-PROPERTY 2026-09-12).
+ *
+ * So the default comes from where this package LIES, the same derivation
+ * `workspaceRoot.js` already owns for the manifest's `api/…` paths: a source
+ * checkout answers with its own root, an installed copy answers `null` and the
+ * citation is reported UNRESOLVED rather than judged (`automation-gates.md` §5).
+ * An explicit `--api-root` still wins — explicit over implicit
+ * (`architecture-principles.md` §8).
+ *
+ * @param {string[]} argv the arguments after the script name
+ * @param {string} cwd the directory a bare run reads
+ * @returns {{root: string, apiRoot: string|null, listScope: boolean, files: string[]|null}}
+ */
+function parse(argv, cwd) {
+  let root = cwd;
+  let apiRoot = API_CHECKOUT_ROOT;
+  let listScope = false;
+  let files = null;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') root = path.resolve(argv[i + 1] === undefined ? '' : argv[++i]);
+    else if (argv[i] === '--api-root') apiRoot = path.resolve(argv[i + 1] === undefined ? '' : argv[++i]);
+    else if (argv[i] === '--list-scope') listScope = true;
+    else if (argv[i] === '--files') {
+      files = [];
+      while (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) files.push(argv[++i]);
+    } else die(`Unknown option "${argv[i]}" - Usage: ${USAGE}`);
+  }
+
+  // An empty list is refused rather than treated as "no files": filtering a run
+  // down to nothing prints `0 finding(s)` while judging nothing, which is the
+  // false guarantee `automation-gates.md` §5 is about.
+  if (files !== null && files.length === 0) {
+    die(`Missing value - --files needs at least one path. Fix: name the files to judge `
+      + `(--files scripts/x.sh tests/scripts/y.bats), or drop the option to run over the whole `
+      + `scope. Usage: ${USAGE}`);
+  }
+
+  // Two different questions: one asks which files this lint owns, the other
+  // asks about named files. Answering both in one run would make the exit code
+  // mean two things.
+  if (files !== null && listScope) {
+    die(`--list-scope and --files ask two different questions - pass one. Fix: run --list-scope `
+      + `to learn the scope, then a second run with --files over the paths you picked. `
+      + `Usage: ${USAGE}`);
+  }
+
+  return { root, apiRoot, listScope, files };
+}
+
+/**
+ * One run, as a function, so the api wrapper is a call and not a copy.
+ *
+ * It returns the exit code rather than calling `process.exit()`: on a pipe Node
+ * writes stdout asynchronously, so exiting right after the report ends the
+ * process with the tail still buffered — measured as exactly 65536 bytes
+ * arriving of a larger payload (`api/tests/scripts/scripts-lint.bats`, "survives
+ * a pipe"). The caller sets `process.exitCode` and lets the process drain.
+ *
+ * @param {{argv?: string[], cwd?: string}} params
+ * @returns {number} 0 clean · 1 findings · 2 the tool itself could not run
+ */
+function runCli({ argv = [], cwd = process.cwd() } = {}) {
+  let options;
+  try {
+    options = parse(argv, cwd);
+  } catch (error) {
+    if (error instanceof LintAbort) return USAGE_EXIT;
+    throw error;
+  }
+
+  const { root, apiRoot, listScope, files } = options;
+
+  let result;
+  try {
+    result = lintScripts({ root, apiRoot });
+  } catch (error) {
+    console.error(`[${TOOL}] ERROR: ${error.stack === undefined ? error.message : error.stack}`);
+    return USAGE_EXIT;
+  }
+
+  if (listScope) {
+    for (const relative of [...result.scanned, ...result.citationScanned]) console.log(relative);
+    return 0;
+  }
+
+  // A scope root that is not there is a usage error HERE and an empty scope in
+  // the module: this CLI is pointed at a repository by a human who believes it
+  // has scripts, and answering "0 findings" to a typo is the silence
+  // `automation-gates.md` §5 is about.
+  if (result.scanned.length === 0 && !require('fs').existsSync(path.join(root, SCRIPT_SCOPE))) {
+    try {
+      die(`Scope root not found - ${path.join(root, SCRIPT_SCOPE)} does not exist. `
+        + 'Fix: run from the repository root, or pass --root.');
+    } catch (error) {
+      if (error instanceof LintAbort) return USAGE_EXIT;
+      throw error;
+    }
+  }
+
+  // `--files` NARROWS THE REPORT of a full run, and narrowing loses nothing
+  // here: every rule in `lintScripts` reads one file's own lines — `lintHeader`
+  // is handed the `lines` of a single script, S009 walks the comment lines of a
+  // single test — and the only thing read outside the file is whether an `@see`
+  // TARGET exists, which is a path rather than another script's content. So the
+  // findings of a named file are computable from that file alone, and the
+  // citation scope narrows together with the header scope.
+  //
+  // The scope itself is NOT re-decided here: the lists come from the rules
+  // module, which stays their single owner, and this is the same shape
+  // `api/scripts/ci/lint-infra-docs.mjs` has carried since it grew `--files`
+  // (`.claude/rules/change-discipline.md` § One rail per concern).
+  let findings = result.findings;
+  if (files !== null) {
+    const inScope = new Set([...result.scanned, ...result.citationScanned]);
+    const named = new Set();
+    for (const file of files) {
+      const relative = path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+      // A path this lint does not own — or one that is not on disk — would
+      // otherwise be answered with `0 finding(s)` about a file nobody read.
+      if (!inScope.has(relative)) {
+        try {
+          die(`--files path is not part of the lint scope - "${file}". Expected: an existing file under `
+            + `${SCRIPT_SCOPE}/ or ${CITATION_SCOPE}/ of ${root}. Fix: name a path this lint owns `
+            + `(--list-scope prints them), or drop --files; a run that reported "0 finding(s)" for a `
+            + 'file it never read would be a false pass.');
+        } catch (error) {
+          if (error instanceof LintAbort) return USAGE_EXIT;
+          throw error;
+        }
+      }
+      named.add(relative);
+    }
+    findings = findings.filter((finding) => named.has(finding.file));
+  }
+
+  for (const finding of findings) {
+    console.log(`ERROR ${finding.id}  ${finding.file}:${finding.line}  ${finding.message}`);
+  }
+
+  if (result.unresolved.length > 0) {
+    // Counted over the whole run even under `--files`: an unresolved target is
+    // a path, and it carries no file to narrow it by. Said rather than dropped —
+    // a NOT RUN that disappears reads as a pass. Run from a source checkout the
+    // api root is known, so this line is empty there by construction; an
+    // installed copy lies in no checkout and says so.
+    console.log(`[${TOOL}] NOT RUN: ${result.unresolved.length} @see target(s) into the api checkout could `
+      + `not be resolved (${result.unresolved.join(', ')})${files === null ? '' : ', counted over this run\'s '
+      + 'whole scope rather than the named files'}. Fix: pass --api-root <api checkout>.`);
+  }
+
+  if (files !== null) {
+    console.log(`[${TOOL}] ${findings.length} finding(s) across ${new Set(files.map((file) => path
+      .relative(root, path.resolve(root, file)))).size} file(s) named with --files, of `
+      + `${result.scanned.length} file(s) in scope and `
+      + `${result.citationScanned.length} file(s) in the ${CITATION_SCOPE} citation scope.`);
+    return findings.length > 0 ? 1 : 0;
+  }
+
+  console.log(`[${TOOL}] ${result.findings.length} finding(s) across ${result.scanned.length} file(s) in scope, `
+    + `${result.citationScanned.length} file(s) in the ${CITATION_SCOPE} citation scope.`);
+
+  return result.findings.length > 0 ? 1 : 0;
+}
+
+module.exports = { runCli, TOOL, USAGE };
+
+if (require.main === module) {
+  process.exitCode = runCli({ argv: process.argv.slice(2), cwd: process.cwd() });
+}