canary-test-cli 6.6.0 → 6.7.0

package/bin/canary.js

@@ -1,6 +1,68 @@
 #!/usr/bin/env node
 'use strict';
 
+// ---------------------------------------------------------------------------
+// Node-floor guard (#559). Everything in this block runs BEFORE the bundled
+// engine is required, and deliberately so.
+//
+// `engines` is advisory: npm prints `warn EBADENGINE` and installs anyway
+// (verified — it errors only under `engine-strict=true`, which almost nobody
+// sets). So on an unsupported Node the user reaches this file, and the require
+// of `../dist/router.js` below can throw a bare SyntaxError from engine code
+// compiled for a newer runtime. A guard placed after that require would only
+// ever run on versions that did not need it.
+//
+// The floor is read from `engines.node` rather than hardcoded, so the manifest
+// stays the single source of truth — see ts/test/node-engines-floor.test.ts,
+// which holds the manifest, the README badge, and the README prose together.
+// ---------------------------------------------------------------------------
+
+/** Floor major from this package's own `engines.node` (e.g. `>=22` -> 22). */
+function readMinNodeMajor() {
+  var declared = (require('../package.json').engines || {}).node || '';
+  var match = /^>=\s*(\d+)/.exec(String(declared).trim());
+  return match ? Number(match[1]) : 0;
+}
+
+var MIN_NODE_MAJOR = readMinNodeMajor();
+
+/**
+ * Returns an error message when `version` is below `minMajor`, else null.
+ *
+ * Abstains (returns null) on a version string it cannot parse: a false block
+ * would be worse than letting an odd runtime through to whatever the real
+ * error turns out to be.
+ */
+function checkNodeFloor(version, minMajor) {
+  var match = /^v?(\d+)\./.exec(String(version));
+  if (!match || !minMajor) return null;
+  var major = Number(match[1]);
+  if (major >= minMajor) return null;
+  return (
+    'canary requires Node ' +
+    minMajor +
+    ' or newer, but this is Node ' +
+    version +
+    '.\n' +
+    'The bundled engine is compiled for Node ' +
+    minMajor +
+    ', so older runtimes fail in ways that look\n' +
+    'like canary bugs. npm only warns about this (EBADENGINE), it does not ' +
+    'stop the install.\n' +
+    'Upgrade with nvm, volta, or mise — e.g. `nvm install ' +
+    minMajor +
+    '` — then re-run canary.\n'
+  );
+}
+
+if (require.main === module) {
+  var floorError = checkNodeFloor(process.versions.node, MIN_NODE_MAJOR);
+  if (floorError) {
+    process.stderr.write(floorError);
+    process.exit(1);
+  }
+}
+
 const { execFileSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
@@ -65,5 +127,11 @@ function main() {
   );
 }
 
-module.exports = { getEnginePath, forwardToEngine, run };
+module.exports = {
+  getEnginePath,
+  forwardToEngine,
+  run,
+  checkNodeFloor,
+  MIN_NODE_MAJOR,
+};
 if (require.main === module) main();

package/dist/doctor-manifest.js

@@ -308,7 +308,12 @@ function skipped(check, reason) {
 }
 function runCommandSucceeds(check, ctx, timeoutMs) {
     if (!ctx.consentGranted) {
-        return skipped(check, "command checks need consent — re-run 'canary overlay add'");
+        return skipped(check, 
+        // #505: name the overlay's source, and say the re-add is safe. The bare
+        // "re-run 'canary overlay add'" read as "reinstall it", which is the
+        // one thing a user with a working overlay will not risk.
+        "command checks need consent — re-run 'canary overlay add <source>' " +
+            '(safe on an installed overlay: it re-asks consent, never re-clones)');
     }
     const command = check.command ?? [];
     const cmd = `\`${command.join(' ')}\``;

package/dist/doctor.js

@@ -186,10 +186,13 @@ function summarizeChecks(groups) {
  */
 function abstentionRemedy(summary) {
     return summary.skipped.length > 0
-        ? 'Every registered check was skipped or informational, so doctor verified ' +
-            'nothing. Grant command-check consent (re-run `canary overlay add ' +
-            '<name> --yes`) or install an overlay whose checks apply here, then ' +
-            're-run.'
+        ? // #505: `<source>`, not `<name>` -- `add` takes the source spec, so the
+            // copied-and-pasted form failed for anyone who followed it literally.
+            'Every registered check was skipped or informational, so doctor verified ' +
+                'nothing. Grant command-check consent (re-run `canary overlay add ' +
+                '<source> --yes`, which re-asks consent on an already-installed overlay ' +
+                'without re-cloning) or install an overlay whose checks apply here, ' +
+                'then re-run.'
         : 'No check was registered, so doctor verified nothing. Install an ' +
             'overlay that ships a `.canary/doctor.json` (`canary overlay add ' +
             '<source>`), then re-run.';

package/dist/engine/cli-commands.js

@@ -11,7 +11,7 @@
  * `\u{...}` escapes emitted verbatim.
  */
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { basename, extname, join, resolve } from 'node:path';
 import pc from 'picocolors';
 import { CliExit, jsonIndent2 } from './cli-common.js';
 import { gateOutcome } from './core/gate-result.js';
@@ -19,6 +19,7 @@ import { ckInitCmd } from './company-knowledge-cli.js';
 import { extractFrameworkHint } from './core/classifier.js';
 import { VALID_CATEGORIES, buildFeedback } from './core/feedback.js';
 import { OverlayNotFound, listOverlays, resolveOverlay, } from './core/overlays.js';
+import { JS_TEST_EXTENSIONS, lintableFramework } from './core/static-linter.js';
 import { RunSummary } from './core/ticket-updater.js';
 import { renderBanner } from './ui/banner.js';
 import { ARROW, CHECK, CHECK_MARK, CROSS, EM_DASH, HAMMER, NEXT, REDX, ROCKET, WARN, WRENCH, } from './main-deps.js';
@@ -46,6 +47,24 @@ function isDir(p) {
         return false;
     }
 }
+/**
+ * Directories never worth walking. A dependency's own test suite is not the
+ * consumer's to fix: before #566, `node_modules` accounted for 254 of 256
+ * findings in one downstream run, and the only `critical` sat inside vendored
+ * code. `pattern-matcher.ts` has carried this set since the Python port; this
+ * walk was the copy that never got it.
+ */
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+]);
 function walkFiles(dir) {
     const out = [];
     let entries;
@@ -57,23 +76,27 @@ function walkFiles(dir) {
     }
     for (const e of entries) {
         const full = join(dir, e.name);
-        if (e.isDirectory())
-            out.push(...walkFiles(full));
+        if (e.isDirectory()) {
+            if (!IGNORED_DIRS.has(e.name))
+                out.push(...walkFiles(full));
+        }
         else if (e.isFile())
             out.push(full);
     }
     return out;
 }
+/**
+ * `test_*.py` plus `*.test.*` / `*.spec.*` over every extension the scanners
+ * can actually read -- `.mjs` and `.cjs` included, which is the half of #566
+ * that made a directory of ESM tests collect zero files.
+ */
+const JS_TEST_FILE_RE = new RegExp(`\\.(test|spec)\\.(${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join('|')})$`);
 /** Recursive test-file glob matching Python's `rglob` union, sorted by path. */
 function collectTestFiles(dir) {
     return walkFiles(dir)
         .filter((p) => {
         const b = basename(p);
-        return ((b.startsWith('test_') && b.endsWith('.py')) ||
-            b.endsWith('.spec.ts') ||
-            b.endsWith('.spec.js') ||
-            b.endsWith('.test.ts') ||
-            b.endsWith('.test.js'));
+        return ((b.startsWith('test_') && b.endsWith('.py')) || JS_TEST_FILE_RE.test(b));
     })
         .sort();
 }
@@ -394,6 +417,21 @@ function findingPayload(f) {
         suggestion: f.suggestion,
     };
 }
+/** Human-readable list of what the collectors look for, for remedy text. */
+const SCANNABLE_DESC = `test_*.py, *.test|spec.{${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join(',')}}`;
+/** Emit the abstention notice in the caller's output mode, then exit 3. */
+function abstain(remedy, deps, json) {
+    const outcome = gateOutcome({ checked: 0, findings: [] }, 'gate');
+    if (json) {
+        deps.out(jsonIndent2([]));
+        deps.err(`${outcome.summaryLine} ${remedy}`);
+    }
+    else {
+        deps.out(pc.bold(pc.yellow(outcome.summaryLine)));
+        deps.out(`  ${remedy}`);
+    }
+    throw new CliExit(outcome.exitCode);
+}
 /**
  * The denominator guard shared by the file-scanning gates (#508 Wave 4a).
  *
@@ -410,29 +448,44 @@ function findingPayload(f) {
 function abstainOnZeroFiles(files, path, deps, json) {
     if (files.length > 0)
         return;
-    const outcome = gateOutcome({ checked: 0, findings: [] }, 'gate');
-    const remedy = `No test file matched under ${path} (looked for test_*.py, ` +
-        `*.spec.ts/js, *.test.ts/js). Point at a directory that holds tests, ` +
-        `or pass a single file directly.`;
-    if (json) {
-        deps.out(jsonIndent2([]));
-        deps.err(`${outcome.summaryLine} ${remedy}`);
-    }
-    else {
-        deps.out(pc.bold(pc.yellow(outcome.summaryLine)));
-        deps.out(`  ${remedy}`);
-    }
-    throw new CliExit(outcome.exitCode);
+    abstain(`No test file matched under ${path} (looked for ${SCANNABLE_DESC}). ` +
+        `Point at a directory that holds tests, or pass a single file directly.`, deps, json);
+}
+/**
+ * The single-file half of the same guard (#566).
+ *
+ * `abstainOnZeroFiles` only ever fires on a directory: a single file is passed
+ * straight through as a one-element list, so its denominator is never zero. It
+ * can still be unmeasurable -- an extension no ruleset parses used to fall back
+ * to the Python scanners, which find nothing in ESM JavaScript and so rendered
+ * "No issues found" over a file that was never actually read. Zero findings
+ * from a scanner that could not parse the input is an abstention, not a pass.
+ */
+function abstainOnUnlintableFile(path, deps, json) {
+    if (lintableFramework(path) !== null)
+        return;
+    const ext = extname(path) || basename(path);
+    abstain(`Cannot lint ${ext} — no ruleset parses it, so a clean result would be ` +
+        `meaningless (looked for ${SCANNABLE_DESC}).`, deps, json);
 }
 export function reviewTestCmd(path, opts, deps) {
+    const json = opts.json === true;
     const files = isDir(path) ? collectTestFiles(path) : [path];
-    abstainOnZeroFiles(files, path, deps, opts.json === true);
+    abstainOnZeroFiles(files, path, deps, json);
+    if (!isDir(path) && !opts.framework)
+        abstainOnUnlintableFile(path, deps, json);
     const linter = deps.makeLinter();
     const allFindings = [];
     for (const f of files)
         allFindings.push(...linter.lint(f, opts.framework));
-    if (opts.json) {
+    // `--json` renders the machine payload and then falls through to the same
+    // exit-code decision as human mode. It used to `return` here, so a consumer
+    // gating on `$?` saw every finding-bearing run as clean (#566).
+    if (json) {
         deps.out(jsonIndent2(allFindings.map(findingPayload)));
+        if (allFindings.some((f) => f.severity === 'critical')) {
+            throw new CliExit(1);
+        }
         return;
     }
     if (allFindings.length === 0) {
@@ -462,14 +515,20 @@ export function reviewTestCmd(path, opts, deps) {
         throw new CliExit(1);
 }
 export function flakeCheckCmd(path, opts, deps) {
+    const json = opts.json === true;
     const files = isDir(path) ? collectTestFiles(path) : [path];
-    abstainOnZeroFiles(files, path, deps, opts.json === true);
+    abstainOnZeroFiles(files, path, deps, json);
+    if (!isDir(path))
+        abstainOnUnlintableFile(path, deps, json);
     const linter = deps.makeLinter();
     const allFindings = [];
     for (const f of files)
         allFindings.push(...linter.flakeCheck(f));
-    if (opts.json) {
+    // Exit-code parity with human mode, same reason as `review-test` above.
+    if (json) {
         deps.out(jsonIndent2(allFindings.map(findingPayload)));
+        if (allFindings.length > 0)
+            throw new CliExit(1);
         return;
     }
     if (allFindings.length === 0) {

package/dist/engine/cli.core.js

@@ -102,7 +102,7 @@ export function createCanaryCommand(depsInit = {}) {
         .command('migrate')
         .description("Migrate a harness-scaffolded test-suite project to Canary's layout.")
         .addOption(new Option('-p, --path <path>', 'Project root to migrate (default: current directory).').default('.'))
-        .option('-f, --framework <framework>', 'Override auto-detected framework.')
+        .option('-f, --framework <framework>', 'Override the auto-detected framework (also resolves its test shape).')
         .option('--from <overlay>', 'Tracked overlay (name or path) whose .canary/skills/ are deployed into the target.')
         .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.')

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

@@ -0,0 +1,218 @@
+/**
+ * Test-framework detection probes, tiered by the kind of evidence they read.
+ *
+ * Split out of `migrator.ts` (#504 part 1) so workspace detection can probe an
+ * individual package without importing the migrator -- see `fs-glob.ts` for why
+ * the direction has to stay leafward.
+ */
+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 = [
+    ['playwright.config.ts', 'playwright', 'e2e_ui', 'config'],
+    ['playwright.config.js', 'playwright', 'e2e_ui', 'config'],
+    ['cypress.config.ts', 'playwright', 'e2e_ui', 'config'],
+    ['cypress.config.js', 'playwright', 'e2e_ui', 'config'],
+    ['vitest.config.ts', 'vitest', 'frontend_unit', 'config'],
+    ['vitest.config.js', 'vitest', 'frontend_unit', 'config'],
+    ['vitest.config.mts', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.ts', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.js', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.mjs', 'vitest', 'frontend_unit', 'config'],
+    ['k6.config.js', 'k6', 'performance', 'config'],
+    ['pytest.ini', 'pytest', 'api', 'config'],
+    ['setup.cfg', 'pytest', 'api', 'config'],
+    ['axe.config.js', 'axe-core', 'accessibility', 'config'],
+    ['backstop.json', 'backstopjs', 'visual', 'config'],
+    ['pact.json', 'pact', 'contract', 'config'],
+    ['.pact', 'pact', 'contract', 'config'],
+    ['stryker.config.js', 'stryker', 'mutation', 'config'],
+    ['stryker.config.mjs', 'stryker', 'mutation', 'config'],
+    ['locust.conf', 'locust', 'load', 'config'],
+    ['locustfile.py', 'locust', 'load', 'config'],
+    ['wdio.conf.ts', 'wdio', 'mobile', 'config'],
+    ['wdio.conf.js', 'wdio', 'mobile', 'config'],
+    ['wdio.conf.mjs', 'wdio', 'mobile', 'config'],
+];
+// pyproject.toml section markers
+const _PYPROJECT_MARKERS = [
+    ['[tool.pytest.ini_options]', 'pytest', 'api'],
+    ['[tool.coverage', 'pytest', 'api'],
+];
+// package.json test script -> (framework, shape)
+const _PACKAGE_SCRIPT_PATTERNS = [
+    [/\bplaywright\b/, 'playwright', 'e2e_ui'],
+    [/\bcypress\b/, 'playwright', 'e2e_ui'],
+    [/\bvitest\b/, 'vitest', 'frontend_unit'],
+    [/\bjest\b/, 'vitest', 'frontend_unit'],
+    [/\bk6\b/, 'k6', 'performance'],
+    [/\blocust\b/, 'locust', 'load'],
+    [/\bstryker\b/, 'stryker', 'mutation'],
+    [/\bwdio\b/, 'wdio', 'mobile'],
+];
+// Python dependency -> (framework, shape). MULTILINE `^` anchored on `\n` only.
+const _PYTHON_DEP_PATTERNS = [
+    [/(?:^|(?<=\n))pytest\b/i, 'pytest', 'api'],
+    [/(?:^|(?<=\n))locust\b/i, 'locust', 'load'],
+    [/(?:^|(?<=\n))pact\b/i, 'pact', 'contract'],
+    [/(?:^|(?<=\n))sdv\b/i, 'sdv', 'synthetic_data'],
+    [/(?:^|(?<=\n))faker\b/i, 'faker', 'synthetic_data'],
+    [/(?:^|(?<=\n))testcontainers\b/i, 'testcontainers', 'integration'],
+];
+// Language -> (framework, shape) fallbacks from harness.config.json
+const _LANGUAGE_FALLBACKS = {
+    python: ['pytest', 'api'],
+    typescript: ['playwright', 'e2e_ui'],
+    javascript: ['playwright', 'e2e_ui'],
+};
+// Detects playwright UI fixture params. MULTILINE is a no-op (no `^`/`$`).
+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) {
+    const specGlobs = [
+        'tests/**/*.spec.ts',
+        'tests/**/*.spec.js',
+        'test/**/*.spec.ts',
+        'test/**/*.spec.js',
+    ];
+    let total = 0;
+    for (const glob of specGlobs) {
+        for (const path of globFiles(root, glob)) {
+            // Python read_text(errors="ignore"); readFileSync substitutes U+FFFD for
+            // invalid bytes -- immaterial for the ASCII fixture pattern below.
+            let content;
+            try {
+                content = readFileSync(path, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            total += 1;
+            if (_PW_UI_FIXTURE_RE.test(content))
+                return 'e2e_ui';
+        }
+    }
+    return total > 0 ? 'api' : 'e2e_ui';
+}
+/** Tier 1 -- a dedicated config file (highest confidence). */
+function probeConfig(root) {
+    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);
+                if (inferred !== shape)
+                    return [framework, inferred, filename, 'content'];
+            }
+            return [framework, shape, filename, confidence];
+        }
+    }
+    return null;
+}
+/** Tier 2a -- pyproject.toml section markers, then its dependency scan. */
+function probePyproject(root) {
+    const pyproject = join(root, 'pyproject.toml');
+    if (!existsSync(pyproject))
+        return null;
+    const content = readTextOrNull(pyproject);
+    if (content === null)
+        return null;
+    for (const [marker, framework, shape] of _PYPROJECT_MARKERS) {
+        if (content.includes(marker)) {
+            return [framework, shape, 'pyproject.toml', 'content'];
+        }
+    }
+    for (const [pattern, framework, shape] of _PYTHON_DEP_PATTERNS) {
+        if (pattern.test(content)) {
+            return [framework, shape, 'pyproject.toml (dependencies)', 'content'];
+        }
+    }
+    return null;
+}
+/** Tier 2b -- requirements*.txt dependency scan. */
+function probeRequirements(root) {
+    for (const reqFile of [
+        'requirements.txt',
+        'requirements-test.txt',
+        'requirements-dev.txt',
+    ]) {
+        const reqPath = join(root, reqFile);
+        if (!existsSync(reqPath))
+            continue;
+        const content = readTextOrNull(reqPath);
+        if (content === null)
+            continue;
+        for (const [pattern, framework, shape] of _PYTHON_DEP_PATTERNS) {
+            if (pattern.test(content))
+                return [framework, shape, reqFile, 'content'];
+        }
+    }
+    return null;
+}
+/** Tier 2c -- package.json scripts.test scan. */
+function probePackageScripts(root) {
+    const pkgJson = join(root, 'package.json');
+    if (!existsSync(pkgJson))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgJson, 'utf-8'));
+        const scripts = (pkg['scripts'] ?? {});
+        const testScript = String(scripts['test'] ?? '');
+        for (const [pattern, framework, shape] of _PACKAGE_SCRIPT_PATTERNS) {
+            if (pattern.test(testScript)) {
+                return [framework, shape, 'package.json (scripts.test)', 'content'];
+            }
+        }
+    }
+    catch {
+        // OSError / JSONDecodeError -> ignore.
+    }
+    return null;
+}
+/** Tier 3 -- language fallback from harness config. */
+function probeLanguage(config) {
+    const language = String(config['language'] ?? '').toLowerCase();
+    if (!Object.prototype.hasOwnProperty.call(_LANGUAGE_FALLBACKS, language)) {
+        return null;
+    }
+    const [fw, shape] = _LANGUAGE_FALLBACKS[language];
+    return [fw, shape, `harness.config.json (language: ${language})`, 'language'];
+}
+/**
+ * Detect a test framework under *dir*, running only the requested *tiers*.
+ *
+ * The tier list is the whole point of this function. Root detection passes all
+ * three; per-package detection passes `['config', 'content']` ONLY. The
+ * language tier maps `language: typescript` to playwright/e2e_ui, so running it
+ * per package would make every package in a TypeScript monorepo "detect"
+ * playwright by inheritance -- canary inventing findings it never observed
+ * (#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.
+ */
+export function probe(dir, config, tiers) {
+    const on = (t) => tiers.includes(t);
+    if (on('config')) {
+        const hit = probeConfig(dir);
+        if (hit !== null)
+            return hit;
+    }
+    if (on('content')) {
+        const hit = probePyproject(dir) ?? probeRequirements(dir) ?? probePackageScripts(dir);
+        if (hit !== null)
+            return hit;
+    }
+    if (on('language')) {
+        const hit = probeLanguage(config);
+        if (hit !== null)
+            return hit;
+    }
+    return [null, 'unknown', 'none', 'none'];
+}
+//# sourceMappingURL=framework-probes.js.map