canary-test-cli 7.0.0 → 7.2.0

package/dist/engine/cli.core.js

@@ -7,8 +7,8 @@
  *
  * Conventions follow `guardian/cli.ts` (see `cli-common.ts`): a
  * {@link createCanaryCommand} factory wired to an injectable {@link MainDeps},
- * `CliExit` for business exits, `normalizeUsageExit` on the program AND every
- * subcommand so usage errors exit 2 (typer/click) not commander's default 1, and
+ * `CliExitError` for business exits, `normalizeUsageExit` on the program AND
+ * every subcommand so usage errors exit 2 (typer/click) not commander's 1, and
  * an eager `-V/--version` global option + `_main` callback analog.
  *
  * Sub-app mounting note: `guardian`/`history`/`analyze` are mounted as FRESH
@@ -17,9 +17,9 @@
  * mount into multiple `createCanaryCommand()` calls, e.g. across tests).
  */
 import { Command, Option } from 'commander';
-import { CliExit, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, normalizeUsageExit } from './cli-common.js';
 import { createAnalyzeCommand } from './analysis/cli.js';
-import { doctorStub, feedbackCmd, flakeCheckCmd, frameworksCmd, healTestCmd, initCmd, migrateCmd, overlayStub, recommendCmd, reviewTestCmd, runCmd, setupCmd, ticketUpdateCmd, upgradeCmd, versionCmd, } from './cli-commands.js';
+import { doctorCmd, feedbackCmd, flakeCheckCmd, listFrameworksCmd, healTestCmd, initCmd, migrateCmd, overlayCmd, promoteCheckCmd, recommendFrameworkCmd, reviewTestCmd, runCmd, setupCmd, ticketUpdateCmd, uninstallCmd, upgradeCmd, vacuityCheckCmd, versionCmd, } from './cli-commands.js';
 import { buildCompanyKnowledgeCommand } from './company-knowledge-cli.js';
 import { createGuardianCommand } from './guardian/cli.js';
 import { createHistoryCommand } from './history/cli.js';
@@ -38,18 +38,18 @@ export function createCanaryCommand(depsInit = {}) {
         .hook('preAction', () => {
         if (program.opts()['version']) {
             versionCmd(deps);
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
     })
         .action(() => {
         if (program.opts()['version']) {
             versionCmd(deps);
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
         // Python `typer.Typer(no_args_is_help=True)` prints help and exits 2 on a
         // bare `canary` invocation (a usage exit), NOT 0.
         program.outputHelp();
-        throw new CliExit(2);
+        throw new CliExitError(2);
     });
     program
         .command('recommend')
@@ -57,14 +57,14 @@ export function createCanaryCommand(depsInit = {}) {
         .argument('<prompt>')
         .option('--json', 'Output as JSON for tool integration.')
         .action((prompt, opts) => {
-        recommendCmd(prompt, opts, deps);
+        recommendFrameworkCmd(prompt, opts, deps);
     });
     program
         .command('frameworks')
         .description('List the supported testing frameworks and how to run each.')
         .option('--json', 'Dump the registry as JSON for tool integration.')
         .action((opts) => {
-        frameworksCmd(opts, deps);
+        listFrameworksCmd(opts, deps);
     });
     program
         .command('feedback')
@@ -107,6 +107,7 @@ export function createCanaryCommand(depsInit = {}) {
         .option('-o, --overlay <path>', '[deprecated: use --from] Path to an overlay repo whose .canary/skills/ are deployed.')
         .option('--apply', 'Write files. Without this flag the command is a dry run.')
         .option('--check', 'Freshness gate: report drift without writing.')
+        .option('--adoption-report', 'Report which adoption pieces (company.json, shape, overlay, skills, manifest, workflows) are present or missing in this repo. Writes nothing. Exits 0 fully adopted, 1 pieces missing, 3 nothing verifiable.')
         .option('--force', 'Overwrite a .github/workflows/ file that differs from the overlay template. Without this flag a difference is only reported -- your CI is never rewritten behind your back.')
         .option('--json', 'Emit the report as JSON.')
         .action((opts) => {
@@ -131,6 +132,22 @@ export function createCanaryCommand(depsInit = {}) {
         .action((path, opts) => {
         flakeCheckCmd(path, opts, deps);
     });
+    program
+        .command('promote-check')
+        .description('Decide whether a generated test may be promoted into the committed suite.')
+        .argument('<path>', 'The generated test file to judge.')
+        .option('--json', 'Emit the structured verdict as JSON.')
+        .action((path, opts) => {
+        promoteCheckCmd(path, opts, deps);
+    });
+    program
+        .command('vacuity-check')
+        .description('Find tests that pass without proving anything -- advisory, no LLM required.')
+        .argument('<path>', 'Test file or directory to scan.')
+        .option('--json', 'Output the verdict and its denominator as JSON.')
+        .action((path, opts) => {
+        vacuityCheckCmd(path, opts, deps);
+    });
     program
         .command('heal-test')
         .description('Apply deterministic pattern fixes to a test file -- no LLM required.')
@@ -162,7 +179,7 @@ export function createCanaryCommand(depsInit = {}) {
         .allowExcessArguments(true)
         .argument('[args...]')
         .action(() => {
-        overlayStub(deps);
+        overlayCmd(deps);
     });
     program
         .command('doctor')
@@ -171,7 +188,16 @@ export function createCanaryCommand(depsInit = {}) {
         .allowExcessArguments(true)
         .argument('[args...]')
         .action(() => {
-        doctorStub(deps);
+        doctorCmd(deps);
+    });
+    program
+        .command('uninstall')
+        .description('Remove installed Canary artifacts (requires the npm install of Canary).')
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .argument('[args...]')
+        .action(() => {
+        uninstallCmd(deps);
     });
     program
         .command('ticket-update')

package/dist/engine/cli.js

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { CommanderError } from 'commander';
 
 import { createCanaryCommand } from './cli.core.js';
-import { CliExit } from './cli-common.js';
+import { CliExitError } from './cli-common.js';
 
 const require = createRequire(import.meta.url);
 
@@ -24,7 +24,7 @@ const program = createCanaryCommand({ pkgVersion: () => readVersion() });
 try {
   await program.parseAsync(process.argv.slice(2), { from: 'user' });
 } catch (err) {
-  if (err instanceof CliExit) process.exit(err.code);
+  if (err instanceof CliExitError) process.exit(err.code);
   if (err instanceof CommanderError) process.exit(err.exitCode);
   console.error(err);
   process.exit(1);

package/dist/engine/company-knowledge-cli.js

@@ -11,14 +11,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command, Option } from 'commander';
 import pc from 'picocolors';
-import { CliExit, jsonIndent2, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit } from './cli-common.js';
 import { CompanyKnowledge } from './core/company-knowledge.js';
 import { CHECK, CROSS, WARN } from './main-deps.js';
 function ckShowCmd(opts, deps) {
     const ck = deps.loadCompanyKnowledge(opts.env ?? null);
     if (ck.error && ck.isEmpty) {
         deps.out(`${pc.red(CROSS)} ${ck.error}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (opts.json) {
         deps.out(jsonIndent2(ck.toDict()));

package/dist/engine/core/adoption.js

@@ -0,0 +1,408 @@
+/**
+ * The adoption report (#459, acceptance criterion 4).
+ *
+ * Answers one question for a consumer repo: **which pieces of a canary overlay
+ * adoption are actually in place here, and which are not?** The reported
+ * failure behind #459 is a repo that looks adopted -- overlay skills sitting in
+ * `.canary/skills/` -- while no workflow was ever installed, so the guardian
+ * never runs and every surface stays quiet. A partial adoption has to be
+ * *nameable* before it can be fixed.
+ *
+ * ## Why it lives here and not in `canary doctor`
+ *
+ * The issue asks for a "doctor-style" report, and `doctor` would be the natural
+ * home -- but `doctor` lives in the CommonJS npm shim (`npm/src/doctor.ts`),
+ * which structurally cannot import the ESM engine (see
+ * `npm/scripts/sync-gate-result.mjs` for the same boundary). Every piece this
+ * report inspects is an engine concept: shape resolution, `deploy_to` matching,
+ * the deploy manifest, `install_workflows`. Re-deriving shape detection in the
+ * shim to keep the report in `doctor` would be a second implementation of the
+ * thing most likely to drift. So the report is doctor-*style* (per-piece
+ * present/missing lines with a remedy under each gap) and ships on the command
+ * that owns the machinery: `canary migrate --adoption-report`.
+ *
+ * ## What it never does
+ *
+ * It writes nothing. The skill and workflow pieces are read from
+ * {@link HarnessMigrator.checkFreshness}, whose workflow phase already runs as
+ * a dry run, so the report is a pure observation of on-disk state.
+ *
+ * ## The ownership line, restated
+ *
+ * A consumer's `.github/workflows/` is theirs (#459 decision). A workflow that
+ * differs from the overlay template is therefore **present** -- adopted, then
+ * edited -- never a finding. Only a declared template with *no file at all* is
+ * missing. Reporting an edited workflow as a gap would nag about the single
+ * thing canary has no claim over, which is a worse failure than the partial
+ * adoption this report exists to surface.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CompanyKnowledge } from './company-knowledge.js';
+import { gateOutcome } from './gate-result.js';
+import { DEPLOY_MANIFEST_NAME, } from './migrator.js';
+const CHECK = '\u{2705}'; // white heavy check mark
+const CROSS = '\u{274C}'; // cross mark
+const WARN = '\u{26A0}'; // warning sign
+const EMDASH = '\u{2014}'; // em dash
+/**
+ * Workflow statuses that mean *a file exists at that path*.
+ *
+ * `outdated` and `conflict` included on purpose: both describe a workflow the
+ * repo HAS. The overlay having moved on, or the consumer having tuned their own
+ * CI, is a freshness question -- `migrate --check` already reports it -- not an
+ * adoption gap.
+ */
+const WORKFLOW_PRESENT = new Set([
+    'installed',
+    'updated',
+    'skipped',
+    'outdated',
+    'conflict',
+]);
+/** The report: a list of pieces, and the single decision that follows. */
+export class AdoptionReport {
+    pieces;
+    constructor(pieces) {
+        this.pieces = pieces;
+    }
+    get present() {
+        return this.pieces.filter((p) => p.status === 'present');
+    }
+    get missing() {
+        return this.pieces.filter((p) => p.status === 'missing');
+    }
+    /** Pieces the report could not reach. Reported, never counted as verified. */
+    get unverifiable() {
+        return this.pieces.filter((p) => p.status === 'unknown');
+    }
+    /** The denominator: pieces that produced a real verdict. */
+    get checked() {
+        return this.present.length + this.missing.length;
+    }
+    /** True only when every piece was verified AND every piece is in place. */
+    get adopted() {
+        return (this.checked > 0 &&
+            this.missing.length === 0 &&
+            this.unverifiable.length === 0);
+    }
+    skipped() {
+        return this.unverifiable.map((p) => ({
+            name: p.id,
+            reason: p.skipReason ?? p.detail,
+        }));
+    }
+    /** A report that reached nothing has abstained, not passed (#508). */
+    get abstained() {
+        return gateOutcome({
+            checked: this.checked,
+            findings: this.missing,
+            skipped: this.skipped(),
+        }, 'gate').abstained;
+    }
+    /** 0 fully adopted, 1 pieces missing, 3 nothing verifiable (#508 D4). */
+    exit_code() {
+        return gateOutcome({
+            checked: this.checked,
+            findings: this.missing,
+            skipped: this.skipped(),
+        }, 'gate').exitCode;
+    }
+    to_dict() {
+        return {
+            schema_version: 1,
+            adopted: this.adopted,
+            checked: this.checked,
+            missing: this.missing.length,
+            unverifiable: this.unverifiable.length,
+            abstained: this.abstained,
+            exit_code: this.exit_code(),
+            pieces: this.pieces.map((p) => ({
+                id: p.id,
+                label: p.label,
+                status: p.status,
+                detail: p.detail,
+                ...(p.remedy !== undefined ? { remedy: p.remedy } : {}),
+            })),
+        };
+    }
+    to_markdown() {
+        const symbol = {
+            present: CHECK,
+            missing: CROSS,
+            unknown: WARN,
+        };
+        const lines = ['# Canary Adoption', ''];
+        for (const p of this.pieces) {
+            lines.push(`- ${symbol[p.status]} **${p.label}** ${EMDASH} ${p.detail}`);
+            if (p.remedy)
+                lines.push(`  - fix: ${p.remedy}`);
+        }
+        lines.push('');
+        if (this.unverifiable.length > 0) {
+            lines.push(`${this.unverifiable.length} piece(s) were **not verified** ` +
+                `${EMDASH} that is not the same as being in place.`, '');
+        }
+        lines.push(gateOutcome({
+            checked: this.checked,
+            findings: this.missing,
+            skipped: this.skipped(),
+        }, 'gate', { noun: 'adoption piece(s)' }).summaryLine);
+        if (this.abstained) {
+            lines.push('', `Nothing was verified, so this is not a pass. Track an overlay ` +
+                '(`canary overlay add <source>`) and re-run, so there is something ' +
+                'to compare this repo against.');
+        }
+        return lines.join('\n');
+    }
+}
+/** `.canary/company.json` -- the pointer file every other piece reads. */
+function companyJsonPiece(input) {
+    return input.companyJsonPresent
+        ? {
+            id: 'company_json',
+            label: 'Company knowledge',
+            status: 'present',
+            detail: '`.canary/company.json` is present',
+        }
+        : {
+            id: 'company_json',
+            label: 'Company knowledge',
+            status: 'missing',
+            detail: 'no `.canary/company.json` in this repo',
+            remedy: 'run `canary setup` to scaffold it',
+        };
+}
+/**
+ * A resolved test shape.
+ *
+ * Load-bearing rather than cosmetic: `deploy_to` matching and `<shape>:`-keyed
+ * workflow variants are both shape-keyed, so an unresolved shape silently
+ * deploys and installs nothing (#504).
+ */
+function shapePiece(input) {
+    return input.shapes.length > 0
+        ? {
+            id: 'shape',
+            label: 'Test shape resolved',
+            status: 'present',
+            detail: input.shapes.map((s) => `\`${s}\``).join(', '),
+        }
+        : {
+            id: 'shape',
+            label: 'Test shape resolved',
+            status: 'missing',
+            detail: 'no shape was detected, so every shape-keyed skill and workflow ' +
+                'variant matches nothing',
+            remedy: 'set `canary_shape` in `.canary/company.json`, or pass ' +
+                '`--framework <name>` to resolve one',
+        };
+}
+/**
+ * The portable-path pointers a generated workflow interpolates.
+ *
+ * Undeclared is `unknown`, not `missing`: a template with no pointer falls back
+ * to its own default, and whether that default fits this repo is not knowable
+ * from the repo alone. Calling it a gap would raise a finding on every
+ * lcov-default repo that is working perfectly.
+ */
+function pathPointersPiece(input) {
+    const declared = [];
+    if (input.coverageReportPath)
+        declared.push(`coverage_report_path=\`${input.coverageReportPath}\``);
+    if (input.sutControllersPath)
+        declared.push(`sut_controllers_path=\`${input.sutControllersPath}\``);
+    if (declared.length > 0) {
+        return {
+            id: 'path_pointers',
+            label: 'Portable path pointers',
+            status: 'present',
+            detail: declared.join(', '),
+        };
+    }
+    return {
+        id: 'path_pointers',
+        label: 'Portable path pointers',
+        status: 'unknown',
+        detail: 'neither `coverage_report_path` nor `sut_controllers_path` is declared, ' +
+            'so a workflow template that reads one uses its own default ' +
+            `${EMDASH} whether that default fits this repo cannot be told from here`,
+        remedy: 'declare the repo-relative paths in `.canary/company.json` if the ' +
+            "installed workflow's defaults are wrong",
+        skipReason: 'none declared',
+    };
+}
+/** An overlay to adopt from. Without one, nothing overlay-derived is knowable. */
+function overlayPiece(input) {
+    return input.overlayPath !== null
+        ? {
+            id: 'overlay',
+            label: 'Overlay resolved',
+            status: 'present',
+            detail: `\`${input.overlayPath}\``,
+        }
+        : {
+            id: 'overlay',
+            label: 'Overlay resolved',
+            status: 'missing',
+            detail: 'no overlay is tracked or passed, so nothing was deployed here',
+            remedy: 'track one with `canary overlay add <source>`, or pass ' +
+                '`--from <overlay>`',
+        };
+}
+/** Overlay skills deployed under `.canary/skills/`. */
+function skillsPiece(input) {
+    const label = 'Overlay skills deployed';
+    const freshness = input.freshness;
+    if (freshness === null) {
+        return {
+            id: 'skills',
+            label,
+            status: 'unknown',
+            detail: 'no overlay to compare against, so deployment was not checked',
+            remedy: 'resolve an overlay (see above) and re-run',
+            skipReason: 'no overlay',
+        };
+    }
+    if (freshness.results.length === 0) {
+        return {
+            id: 'skills',
+            label,
+            status: 'unknown',
+            detail: "zero overlay skills matched this repo's shape, so nothing was " +
+                'verified',
+            remedy: "check the overlay's `deploy_to` lists against the resolved shape",
+            skipReason: 'no skill matched the shape',
+        };
+    }
+    const absent = freshness.results.filter((r) => r.status === 'missing');
+    if (absent.length === 0) {
+        return {
+            id: 'skills',
+            label,
+            status: 'present',
+            detail: `${freshness.results.length} matching skill(s) deployed`,
+        };
+    }
+    return {
+        id: 'skills',
+        label,
+        status: 'missing',
+        detail: `${absent.length} of ${freshness.results.length} matching skill(s) ` +
+            `not deployed: ${absent.map((r) => `\`${r.skill_name}\``).join(', ')}`,
+        remedy: 'run `canary migrate --apply` to deploy them',
+    };
+}
+/**
+ * The deploy manifest.
+ *
+ * Its own piece rather than a footnote on the skills line: without it the
+ * freshness gate cannot tell "the overlay moved ahead" from "the consumer
+ * edited this", so drift detection is structurally unreachable however many
+ * skills are deployed.
+ */
+function manifestPiece(input) {
+    return input.manifestPresent
+        ? {
+            id: 'manifest',
+            label: 'Deploy manifest',
+            status: 'present',
+            detail: `\`.canary/skills/${DEPLOY_MANIFEST_NAME}\` records provenance`,
+        }
+        : {
+            id: 'manifest',
+            label: 'Deploy manifest',
+            status: 'missing',
+            detail: `no \`.canary/skills/${DEPLOY_MANIFEST_NAME}\`, so drift cannot be ` +
+                'told apart from a local edit',
+            remedy: 'run `canary migrate --apply` to record it',
+        };
+}
+/** Declared workflow templates actually sitting in `.github/workflows/`. */
+function workflowsPiece(input) {
+    const label = 'Overlay workflows installed';
+    const freshness = input.freshness;
+    if (freshness === null) {
+        return {
+            id: 'workflows',
+            label,
+            status: 'unknown',
+            detail: 'no overlay to compare against, so `.github/workflows/` was not ' +
+                'checked',
+            remedy: 'resolve an overlay (see above) and re-run',
+            skipReason: 'no overlay',
+        };
+    }
+    if (freshness.workflows.length === 0) {
+        return {
+            id: 'workflows',
+            label,
+            status: 'unknown',
+            detail: 'no matching overlay skill declares an `install_workflows` template, ' +
+                'so there is nothing to install into `.github/workflows/`',
+            remedy: 'if a workflow is expected, check the declaring skill deploys for ' +
+                'this shape',
+            skipReason: 'no template declared',
+        };
+    }
+    const absent = freshness.workflows.filter((w) => !WORKFLOW_PRESENT.has(w.status));
+    if (absent.length === 0) {
+        return {
+            id: 'workflows',
+            label,
+            status: 'present',
+            detail: `${freshness.workflows.length} declared workflow(s) in \`.github/workflows/\``,
+        };
+    }
+    return {
+        id: 'workflows',
+        label,
+        status: 'missing',
+        detail: absent
+            .map((w) => `\`${w.workflow}\` (${w.status}) ${EMDASH} ${w.detail}`)
+            .join('; '),
+        remedy: 'run `canary migrate --apply` to install the declared workflow(s)',
+    };
+}
+/**
+ * Derive the report from gathered facts.
+ *
+ * Piece order is the adoption order: local config first, then the overlay, then
+ * what the overlay put here. A reader hitting the first `missing` line has
+ * found the step to fix, because nothing below it can work without it.
+ */
+export function buildAdoptionReport(input) {
+    return new AdoptionReport([
+        companyJsonPiece(input),
+        shapePiece(input),
+        pathPointersPiece(input),
+        overlayPiece(input),
+        skillsPiece(input),
+        manifestPiece(input),
+        workflowsPiece(input),
+    ]);
+}
+/**
+ * Read the target repo and build its adoption report. Writes nothing.
+ *
+ * `home` is the company-knowledge cascade's home layer (a test seam, matching
+ * `CompanyKnowledge.load`); the *presence* check deliberately looks only at the
+ * project-local file, because an org-wide `~/.canary/company.json` is not
+ * something this repo has adopted.
+ */
+export function gatherAdoptionReport(migrator, projectRoot, overlayPath, home) {
+    const ctx = migrator.detect(projectRoot);
+    const ck = CompanyKnowledge.load(projectRoot, null, home);
+    return buildAdoptionReport({
+        shapes: ctx.shapes,
+        overlayPath,
+        freshness: overlayPath === null
+            ? null
+            : migrator.checkFreshness(projectRoot, { overlayPath }),
+        companyJsonPresent: existsSync(join(projectRoot, '.canary', 'company.json')),
+        manifestPresent: existsSync(join(projectRoot, '.canary', 'skills', DEPLOY_MANIFEST_NAME)),
+        coverageReportPath: ck.coverage_report_path,
+        sutControllersPath: ck.sut_controllers_path,
+    });
+}
+//# sourceMappingURL=adoption.js.map

package/dist/engine/core/framework-probes.js

@@ -9,7 +9,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { globFiles, readTextOrNull } from './fs-glob.js';
 // (config_file, framework, shape, confidence)
-export const _CONFIG_PROBES = [
+export const CONFIG_PROBES = [
     ['playwright.config.ts', 'playwright', 'e2e_ui', 'config'],
     ['playwright.config.js', 'playwright', 'e2e_ui', 'config'],
     ['cypress.config.ts', 'playwright', 'e2e_ui', 'config'],
@@ -72,7 +72,7 @@ const _PW_UI_FIXTURE_RE = /async\s*\(\s*\{[^}]*\b(?:page|browser)\b/;
  * Return 'api' when no playwright spec file uses page/browser fixtures, else
  * 'e2e_ui' (the default when any UI signal is found or no spec files exist).
  */
-export function inferPlaywrightShape(root) {
+export function inferPlaywrightTestType(root) {
     const specGlobs = [
         'tests/**/*.spec.ts',
         'tests/**/*.spec.js',
@@ -100,11 +100,11 @@ export function inferPlaywrightShape(root) {
 }
 /** Tier 1 -- a dedicated config file (highest confidence). */
 function probeConfig(root) {
-    for (const [filename, framework, shape, confidence] of _CONFIG_PROBES) {
+    for (const [filename, framework, shape, confidence] of CONFIG_PROBES) {
         if (existsSync(join(root, filename))) {
             // For playwright config files, distinguish API vs UI suites.
             if (framework === 'playwright' && shape === 'e2e_ui') {
-                const inferred = inferPlaywrightShape(root);
+                const inferred = inferPlaywrightTestType(root);
                 if (inferred !== shape)
                     return [framework, inferred, filename, 'content'];
             }
@@ -193,10 +193,10 @@ function probeLanguage(config) {
  * (#504 part 1, spec test #8).
  *
  * Note the tier list and the returned `confidence` are not the same axis: the
- * config tier returns confidence `content` when `inferPlaywrightShape` refines
- * e2e_ui to api, because the refinement read file contents to decide.
+ * config tier returns confidence `content` when `inferPlaywrightTestType`
+ * refines e2e_ui to api, because the refinement read file contents to decide.
  */
-export function probe(dir, config, tiers) {
+export function probeFramework(dir, config, tiers) {
     const on = (t) => tiers.includes(t);
     if (on('config')) {
         const hit = probeConfig(dir);

package/dist/engine/core/fs-glob.js

@@ -93,7 +93,7 @@ function subDirs(dir) {
  * silently suppress a scaffold the user needs -- and a `**` glob over a real
  * monorepo would otherwise walk every installed package on disk.
  */
-export const _WORKSPACE_SKIP_DIRS = new Set([
+export const WORKSPACE_SKIP_DIRS = new Set([
     'node_modules',
     '.git',
     '.venv',
@@ -117,7 +117,7 @@ export const _WORKSPACE_SKIP_DIRS = new Set([
 export function globDirs(root, pattern) {
     const segments = pattern.split('/').filter((s) => s !== '');
     const out = [];
-    const walkable = (dir) => subDirs(dir).filter((d) => !_WORKSPACE_SKIP_DIRS.has(basename(d)));
+    const walkable = (dir) => subDirs(dir).filter((d) => !WORKSPACE_SKIP_DIRS.has(basename(d)));
     const visit = (dir, si) => {
         if (si === segments.length) {
             if (dir !== root)

package/dist/engine/core/gate-result.js

@@ -25,6 +25,23 @@ const EMDASH = '\u{2014}'; // em dash
 // C0 controls (incl. \n, ESC) and DEL: a skip name must never be able to
 // forge output lines or smuggle ANSI sequences into the summary.
 const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+// A libuv/POSIX errno code (`ENOENT`, `EACCES`, `EISDIR`), as opposed to a Node
+// programmer-error code (`ERR_INVALID_ARG_TYPE`).
+const ERRNO = /^E[A-Z0-9]+$/;
+/**
+ * The errno code `e` carries, or `null` when it carries none.
+ *
+ * Load-bearing wherever a read failure is absorbed into a {@link SkipEntry}:
+ * only "the filesystem said no" may become a skip. Node PROGRAMMER errors carry
+ * a string `code` too, so keying off `typeof code === 'string'` reports a
+ * genuine defect inside the scanner as a tidy abstention with a misleading
+ * reason -- which is how a scanner learns to go quiet. Anything this returns
+ * `null` for must still throw.
+ */
+export function errnoCode(e) {
+    const code = e?.code;
+    return typeof code === 'string' && ERRNO.test(code) ? code : null;
+}
 /**
  * D7: skipped entries render in EVERY summary line.
  *