canary-test-cli 6.8.1 → 7.1.0

package/dist/engine/core/migrator.js

@@ -42,13 +42,14 @@ import { homedir } from 'node:os';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readJsonWithWarning } from './config-validation.js';
 import { uncertainDetectionMessage } from './detection.js';
-import { _CONFIG_PROBES, inferPlaywrightShape, probe, } from './framework-probes.js';
+import { CONFIG_PROBES, inferPlaywrightTestType, probeFramework, } from './framework-probes.js';
 import { comparePathParts, globDirs, globFiles, isDir, isFile, readTextOrNull, } from './fs-glob.js';
 import { detectWorkspace, workspaceGlobs, } from './workspace-detect.js';
 import { FrameworkRegistry } from './framework-registry.js';
 import { EXIT_ABSTAINED, gateOutcome } from './gate-result.js';
 import { Scaffolder, scaffoldableFrameworks, TEMPLATES } from './scaffolder.js';
 import { SkillRegistry } from './skill-registry.js';
+import { ensureAscii } from '../util/ensure-ascii.js';
 // ---------------------------------------------------------------------------
 // Python-compatibility helpers (copied locally per-module, matching reporter.ts)
 // ---------------------------------------------------------------------------
@@ -64,13 +65,6 @@ function pyTruthy(value) {
         return Object.keys(value).length > 0;
     return Boolean(value);
 }
-/**
- * Reproduce `json.dumps(..., ensure_ascii=True)` on `JSON.stringify` output:
- * escape every code point >= 0x80 as `\uXXXX`. (Same helper as reporter.ts.)
- */
-function ensureAscii(json) {
-    return json.replace(/[\u0080-\uffff]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
 // Non-ASCII glyphs kept out of the source text as escapes, emitted verbatim.
 const CHECK = '\u{2705}'; // white heavy check mark
 const WARN = '\u{26A0}'; // warning sign
@@ -248,6 +242,23 @@ function resolveTemplatePath(skillDir, rel) {
         return null;
     return full;
 }
+/**
+ * Is the deployed copy of a skill the consumer's rather than the overlay's?
+ *
+ * True when it differs from the overlay AND from the hash recorded at deploy
+ * time -- or carries no recorded provenance at all, since unknown provenance is
+ * not permission to overwrite.
+ *
+ * This is the single definition of `local_edit`. The skill-deploy phase refuses
+ * to overwrite on it (#334) and the workflow-install phase withholds on it
+ * (#667); sharing one predicate is what keeps the two phases from reporting
+ * contradictory things about the same skill in the same run.
+ */
+function isLocallyEdited(overlayHash, targetHash, recordedHash) {
+    if (targetHash === overlayHash)
+        return false;
+    return recordedHash === undefined || targetHash !== recordedHash;
+}
 // ---------------------------------------------------------------------------
 // Constants / probes
 // ---------------------------------------------------------------------------
@@ -255,7 +266,7 @@ function resolveTemplatePath(skillDir, rel) {
  * Frameworks a user can pass to `canary migrate --framework <name>`. Surfaced in
  * the fail-loud message when auto-detection is uncertain (issue #295).
  */
-export const KNOWN_FRAMEWORKS = [
+const KNOWN_FRAMEWORKS = [
     'playwright',
     'vitest',
     'pytest',
@@ -294,9 +305,7 @@ function findWorkspaceSuites(root, framework) {
     const globs = workspaceGlobs(root);
     if (globs.length === 0)
         return [];
-    const configNames = _CONFIG_PROBES
-        .filter(([, fw]) => fw === framework)
-        .map(([filename]) => filename);
+    const configNames = CONFIG_PROBES.filter(([, fw]) => fw === framework).map(([filename]) => filename);
     if (configNames.length === 0)
         return [];
     const dirs = new Set();
@@ -330,11 +339,11 @@ function findWorkspaceSuites(root, framework) {
  * shape detection produced rather than overwriting it with a guess.
  */
 function shapeForFrameworkOverride(framework, root) {
-    for (const [, probeFramework, shape] of _CONFIG_PROBES) {
-        if (probeFramework !== framework)
+    for (const [, candidateFramework, shape] of CONFIG_PROBES) {
+        if (candidateFramework !== framework)
             continue;
-        if (probeFramework === 'playwright' && shape === 'e2e_ui') {
-            return inferPlaywrightShape(root);
+        if (candidateFramework === 'playwright' && shape === 'e2e_ui') {
+            return inferPlaywrightTestType(root);
         }
         return shape;
     }
@@ -455,8 +464,10 @@ export class SkillDeployResult {
  *   - `dry_run`   -- what an `--apply` run would have done
  *   - `missing`   -- the overlay declares a template it does not ship
  *   - `invalid`   -- the declared path escapes the skill directory (refused)
+ *   - `withheld`  -- the declaring skill was skipped as locally edited, so its
+ *                    templates were not installed either (#667)
  *
- * `outdated` and `conflict` are REPORTS. Neither ever writes.
+ * `outdated`, `conflict`, and `withheld` are REPORTS. None ever writes.
  */
 export class WorkflowInstallResult {
     /** File name under `.github/workflows/`. */
@@ -506,11 +517,21 @@ export class FreshnessReport {
      * nagging about something canary has no claim over.
      */
     workflows;
-    constructor(shape, overlay_path = null, results = [], workflows = []) {
+    /**
+     * Every shape the gate actually resolved -- the set `migrate` deploys for
+     * (#504 part 1). The scalar `shape` above stays, because the `--check --json`
+     * payload is documented and consumers read it; `shapes` is additive.
+     *
+     * A mixed monorepo collapses `shape` to `unknown` while `shapes` still names
+     * both, so the two disagree by design rather than by accident.
+     */
+    shapes;
+    constructor(shape, overlay_path = null, results = [], workflows = [], shapes = []) {
         this.shape = shape;
         this.overlay_path = overlay_path;
         this.results = results;
         this.workflows = workflows;
+        this.shapes = shapes;
     }
     get stale() {
         return this.results.filter((r) => r.status === 'stale' || r.status === 'missing');
@@ -564,6 +585,7 @@ export class FreshnessReport {
     to_dict() {
         return {
             shape: this.shape,
+            shapes: this.shapes,
             overlay_path: this.overlay_path,
             in_sync: this.in_sync,
             has_drift: this.has_drift,
@@ -587,14 +609,20 @@ export class FreshnessReport {
             `**Shape:** ${this.shape}`,
             '',
         ];
+        // A workspace repo resolves several shapes at once; naming only the scalar
+        // would tell a reader `unknown` while the gate checked two shapes (#504).
+        if (this.shapes.length > 1) {
+            lines.push(`**Shapes checked:** ${this.shapes.map((s) => `\`${s}\``).join(', ')}`, '');
+        }
         if (this.results.length === 0) {
             lines.push("_No overlay skills match this project's shape._", '');
             lines.push(`${WARN} **Abstained** ${EMDASH} the gate verified zero skills, so this is not a pass.`, '');
-            if (this.shape === 'unknown') {
+            if (this.shapes.length === 0) {
                 lines.push('The shape could not be detected. Set `canary_shape` in', '`.canary/company.json` or pass `--framework <name>`.', '');
             }
             else {
-                lines.push(`The overlay ships no skills with \`deploy_to\` covering \`${this.shape}\`.`, "Check the overlay's `deploy_to` lists or the resolved `canary_shape`.", '');
+                const covered = this.shapes.map((s) => `\`${s}\``).join(', ');
+                lines.push(`The overlay ships no skills with \`deploy_to\` covering ${covered}.`, "Check the overlay's `deploy_to` lists or the resolved `canary_shape`.", '');
             }
             lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
@@ -654,6 +682,14 @@ function workflowMarkdown(results, dryRun) {
             'differs from the template. Re-run with `--force` to take the ' +
             "overlay's version.", '');
     }
+    // #667: a withheld install is the one line that says why a template the
+    // overlay declares is absent from the target -- without it, the section
+    // simply omits the file and reads as though it were never declared.
+    if (results.some((r) => r.status === 'withheld')) {
+        lines.push(`${WARN} Templates declared by a skill with local edits were withheld: ` +
+            'the skill itself was skipped, so its workflows were not installed ' +
+            'either. Revert the local edits, or re-run with `--force`.', '');
+    }
     return lines;
 }
 export class MigrationReport {
@@ -994,6 +1030,10 @@ export class HarnessMigrator {
             ? shapeForFrameworkOverride(framework, projectRoot)
             : null;
         const shape = overrideShape ?? ctx.detected_shape;
+        // The set that actually drives deployment. Re-derived from the *effective*
+        // scalar rather than reusing `ctx.shapes`, so a `--framework` override
+        // contributes its resolved shape to the union too (#504 parts 1-2).
+        const deployShapes = unionShapes(shape, ctx.workspace);
         const followups = [];
         if (effectiveFramework === null) {
             followups.push(uncertainDetectionMessage('test framework', {
@@ -1004,7 +1044,7 @@ export class HarnessMigrator {
             // Issue #295 point 3: a detection miss must not block skill deployment --
             // nor, for the same reason, the workflow install (#459). The guardian
             // workflow is exactly what an unrecognised repo most needs.
-            const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+            const deployed = this.deploySkills(deployShapes, overlayPath, projectRoot, dryRun);
             return new MigrationReport({
                 framework: 'unknown',
                 shape,
@@ -1014,9 +1054,9 @@ export class HarnessMigrator {
                 manual_followups: followups,
                 config_warnings: ctx.config_warnings,
                 workspace: ctx.workspace,
-                shapes: ctx.shapes,
+                shapes: deployShapes,
                 deployed_skills: deployed,
-                installed_workflows: this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force),
+                installed_workflows: this.installWorkflows(deployShapes, overlayPath, projectRoot, dryRun, force),
             });
         }
         // A framework canary knows but cannot scaffold gets no config boilerplate.
@@ -1035,10 +1075,10 @@ export class HarnessMigrator {
         // must not be offered a second one at the root.
         const existingSuites = findWorkspaceSuites(projectRoot, effectiveFramework);
         const scaffolder = new Scaffolder();
-        const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+        const deployed = this.deploySkills(deployShapes, overlayPath, projectRoot, dryRun);
         // Post-copy install phase: the template bytes already landed under
         // .canary/skills/ with the skill; this puts them where Actions looks.
-        const installedWorkflows = this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force);
+        const installedWorkflows = this.installWorkflows(deployShapes, overlayPath, projectRoot, dryRun, force);
         if (dryRun) {
             const tmpl = TEMPLATES[effectiveFramework];
             const files = tmpl?.files ?? {};
@@ -1067,7 +1107,7 @@ export class HarnessMigrator {
                 installed_workflows: installedWorkflows,
                 config_warnings: ctx.config_warnings,
                 workspace: ctx.workspace,
-                shapes: ctx.shapes,
+                shapes: deployShapes,
             });
         }
         // Same guard on the apply path: what the dry run refuses to propose, an
@@ -1092,16 +1132,25 @@ export class HarnessMigrator {
             installed_workflows: installedWorkflows,
             config_warnings: ctx.config_warnings,
             workspace: ctx.workspace,
-            shapes: ctx.shapes,
+            shapes: deployShapes,
         });
     }
     // -- private helpers --------------------------------------------------------
     /**
      * Return `[[SkillInfo, skillDir], ...]` for overlay skills whose `deploy_to`
-     * matches *shape* (or the `all` sentinel). Sources: *overlayPath* first, then
-     * `~/.canary/skills/`. The first definition of a name wins.
+     * matches **any** shape in *shapes* (or the `all` sentinel). Sources:
+     * *overlayPath* first, then `~/.canary/skills/`. The first definition of a
+     * name wins.
+     *
+     * *shapes* is a set, not a scalar, because a monorepo genuinely has several
+     * shapes at once (#504 part 1). One pass over the overlay collects the union
+     * deduplicated by name, so a skill matching two shapes is collected once and
+     * the deploy manifest is read and written exactly once -- which a per-shape
+     * loop would not give.
+     *
+     * An empty *shapes* is the old `unknown`: only `deploy_to: [all]` matches.
      */
-    collectOverlaySkills(shape, overlayPath) {
+    collectOverlaySkills(shapes, overlayPath) {
         const candidateRoots = [];
         if (overlayPath !== null)
             candidateRoots.push(overlayPath);
@@ -1143,7 +1192,7 @@ export class HarnessMigrator {
                     continue;
                 if (!pyTruthy(info.deploy_to))
                     continue;
-                if (!info.deploy_to.includes(shape) &&
+                if (!shapes.some((s) => info.deploy_to.includes(s)) &&
                     !info.deploy_to.includes('all')) {
                     continue;
                 }
@@ -1154,12 +1203,12 @@ export class HarnessMigrator {
         return collected;
     }
     /**
-     * Copy skills from the overlay's `.canary/skills/` that match *shape*.
+     * Copy skills from the overlay's `.canary/skills/` matching any of *shapes*.
      * Deployment is strictly one-way -- the overlay owns deployed files (#334).
      */
-    deploySkills(shape, overlayPath, targetRoot, dryRun) {
+    deploySkills(shapes, overlayPath, targetRoot, dryRun) {
         const results = [];
-        const skillsToDeploy = this.collectOverlaySkills(shape, overlayPath);
+        const skillsToDeploy = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
         const doc = readManifestDoc(targetSkillsDir);
         const manifest = doc.skills;
@@ -1178,8 +1227,7 @@ export class HarnessMigrator {
                     }
                     continue;
                 }
-                const recorded = manifest[dirName]?.hash;
-                if (recorded === undefined || targetHash !== recorded) {
+                if (isLocallyEdited(overlayHash, targetHash, manifest[dirName]?.hash)) {
                     // Hand-edited (or unprovenanced) -- one-way ownership refuses to clobber.
                     results.push(new SkillDeployResult(info.name, 'skipped', `local edits ${EMDASH} not overwritten`));
                     continue;
@@ -1210,6 +1258,21 @@ export class HarnessMigrator {
             writeManifestDoc(targetSkillsDir, doc);
         return results;
     }
+    /**
+     * Would the deploy phase skip this skill as `local_edit` (#667)?
+     *
+     * Answers for the CURRENT on-disk state, so it holds whether the deploy phase
+     * has already run this invocation (apply) or never will (dry run / `--check`)
+     * -- the workflow report then says the same thing about a skill as the skill
+     * report does.
+     */
+    skillWasSkipped(skillDir, targetSkillsDir, manifest) {
+        const dirName = basename(skillDir);
+        const dest = join(targetSkillsDir, dirName);
+        if (!existsSync(dest))
+            return false;
+        return isLocallyEdited(hashSkillDir(skillDir), hashSkillDir(dest), manifest[dirName]?.hash);
+    }
     /**
      * Install the workflow templates the shape-matching overlay skills declare
      * into the target's `.github/workflows/` (#459).
@@ -1225,22 +1288,43 @@ export class HarnessMigrator {
      * a hand-tuned workflow -- or nagging that it is "stale" via an exit code --
      * would be a worse failure than the partial adoption this fixes.
      *
-     * Shape selection reuses the same resolved `canary_shape` that drives
-     * `deploy_to` matching: skills are gated by {@link collectOverlaySkills}, and
-     * an entry may additionally carry a `<shape>:` prefix to pick a variant.
+     * **The skill's own protection extends here (#667).** A skill the deploy
+     * phase skips as `local_edit` installs nothing: it is reported `withheld`
+     * with the reason and no bytes are written. Otherwise a run could announce
+     * "skipped -- local edits, not overwritten" while writing that same skill's
+     * files to `.github/workflows/` anyway, which is how a consumer who
+     * deliberately de-listed a template got it reinstated on every sync. The
+     * de-listing lives in the consumer's SKILL.md, and the install list is read
+     * from the OVERLAY copy -- so withholding is also the only way that edit can
+     * mean anything.
+     *
+     * Shape selection reuses the same resolved shape set that drives `deploy_to`
+     * matching: skills are gated by {@link collectOverlaySkills}, and an entry may
+     * additionally carry a `<shape>:` prefix to pick a variant. A prefixed entry
+     * installs when its shape is anywhere in *shapes* (#504 part 1) -- a monorepo
+     * carrying both an e2e and a unit package wants both variants, and matching
+     * only the scalar would silently install neither once the scalar collapses to
+     * `unknown`.
      */
-    installWorkflows(shape, overlayPath, targetRoot, dryRun, force = false) {
+    installWorkflows(shapes, overlayPath, targetRoot, dryRun, force = false) {
         const results = [];
-        const skills = this.collectOverlaySkills(shape, overlayPath);
+        const skills = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
         const doc = readManifestDoc(targetSkillsDir);
         const workflowsDir = join(targetRoot, '.github', 'workflows');
         let manifestDirty = false;
         for (const [info, skillDir] of skills) {
             const { entries, version } = readWorkflowDeclaration(info.path);
+            // Hashing a skill directory is not free, so only skills that actually
+            // declare templates pay for the local-edit lookup.
+            const skillWithheld = !force &&
+                entries.length > 0 &&
+                this.skillWasSkipped(skillDir, targetSkillsDir, doc.skills);
             for (const entry of entries) {
                 const [wantShape, rel] = parseWorkflowEntry(entry);
-                if (wantShape !== null && wantShape !== shape && wantShape !== 'all') {
+                if (wantShape !== null &&
+                    !shapes.includes(wantShape) &&
+                    wantShape !== 'all') {
                     continue;
                 }
                 const src = resolveTemplatePath(skillDir, rel);
@@ -1274,6 +1358,21 @@ export class HarnessMigrator {
                 const push = (status, detail) => {
                     results.push(new WorkflowInstallResult(name, info.name, status, detail));
                 };
+                const installedBytes = existsSync(dest) ? readBytesOrNull(dest) : null;
+                const alreadyCurrent = installedBytes !== null && installedBytes.equals(templateBytes);
+                // #667: the declaring skill was skipped as locally edited, so this
+                // template is not ours to place. An already-identical file is exempt:
+                // it is a no-op, and calling that "withheld" would raise a finding on
+                // every scheduled freshness check. Everything else is gated here,
+                // ahead of `outdated`, whose remedy ("re-run with --force") would
+                // otherwise talk a consumer into the very overwrite the skip refused.
+                if (skillWithheld && !alreadyCurrent) {
+                    push('withheld', `.github/workflows/${name} was NOT installed ${EMDASH} its skill ` +
+                        `'${info.name}' has local edits and was skipped, so its ` +
+                        'templates were withheld too; re-run with --force to install it ' +
+                        'anyway');
+                    continue;
+                }
                 if (!existsSync(dest)) {
                     if (dryRun) {
                         push('dry_run', `would install .github/workflows/${name} (v${version})`);
@@ -1283,8 +1382,7 @@ export class HarnessMigrator {
                     push('installed', `installed .github/workflows/${name} (v${version})`);
                     continue;
                 }
-                const installedBytes = readBytesOrNull(dest);
-                if (installedBytes !== null && installedBytes.equals(templateBytes)) {
+                if (alreadyCurrent) {
                     // Back-fill provenance for a hand-placed but identical file so a later
                     // template fix can be reported as `outdated` rather than `conflict`.
                     if (doc.workflows[name]?.hash !== templateHash)
@@ -1334,7 +1432,12 @@ export class HarnessMigrator {
                 'Expected harness.config.json and .harness/ directory.');
         }
         const shape = ctx.detected_shape;
-        const skills = this.collectOverlaySkills(shape, overlayPath);
+        // The gate must examine exactly what `migrate` deploys. Resolving only the
+        // scalar here would let `--check` report "in sync" about skills it never
+        // looked at in a monorepo -- a deliberate false green in a drift gate
+        // (#504 part 1).
+        const shapes = ctx.shapes;
+        const skills = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(projectRoot, '.canary', 'skills');
         const manifest = readManifestDoc(targetSkillsDir).skills;
         const results = [];
@@ -1362,7 +1465,7 @@ export class HarnessMigrator {
         return new FreshnessReport(shape, overlayPath !== null ? String(overlayPath) : null, results, 
         // dryRun = true: `--check` reports what an install WOULD do and never
         // writes. Informational only -- see FreshnessReport.workflows.
-        this.installWorkflows(shape, overlayPath, projectRoot, true, false));
+        this.installWorkflows(shapes, overlayPath, projectRoot, true, false), shapes);
     }
     detectFramework(root, config, ws = null) {
         // Explicit override in .canary/company.json ("canary_shape" field) is
@@ -1400,7 +1503,7 @@ export class HarnessMigrator {
         const findings = ws.findings;
         if (findings.length === 0)
             return null;
-        const pairs = new Set(findings.map((f) => `${f.framework}${f.shape}`));
+        const pairs = new Set(findings.map((f) => `${f.framework}\0${f.shape}`));
         if (pairs.size > 1) {
             return [null, 'unknown', 'workspace (mixed)', 'none'];
         }
@@ -1414,7 +1517,7 @@ export class HarnessMigrator {
         ];
     }
     probeFramework(root, config) {
-        return probe(root, config, ['config', 'content', 'language']);
+        return probeFramework(root, config, ['config', 'content', 'language']);
     }
     findExistingTests(root) {
         const found = [];

package/dist/engine/core/pattern-matcher.js

@@ -8,18 +8,36 @@
  */
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, resolve } from 'node:path';
+import { JS_TEST_EXTENSIONS } from './static-linter.js';
+/**
+ * `**\/*.<infix>.<ext>` for every extension the scanners can actually read.
+ *
+ * Derived from {@link JS_TEST_EXTENSIONS} rather than hand-listed, because the
+ * hand-listed version is what made #566 possible and this module carried the
+ * same gap one layer deeper: the globs covered `.ts`/`.js` only, so a project
+ * whose suite is ESM (`.mjs`) or CJS (`.cjs`) scanned to `test_count: 0` — a
+ * value indistinguishable from "this project has no tests", which every
+ * consumer branching on {@link isEmpty} then treats as a clean absence.
+ *
+ * No suite in this repo is `.mjs`/`.cjs`, so CI can never trip over this by
+ * accident; `pattern-matcher.test.ts` asserts the coverage against the shared
+ * extension list instead of restating it.
+ */
+function jsGlobs(...infixes) {
+    return infixes.flatMap((infix) => JS_TEST_EXTENSIONS.map((ext) => `**/*.${infix}${ext}`));
+}
 const FILE_PATTERNS = {
-    playwright: ['**/*.spec.ts', '**/*.spec.js', '**/*.test.ts', '**/*.test.js'],
-    vitest: ['**/*.test.ts', '**/*.test.js', '**/*.spec.ts', '**/*.spec.js'],
+    playwright: jsGlobs('spec', 'test'),
+    vitest: jsGlobs('test', 'spec'),
     pytest: ['**/test_*.py', '**/*_test.py'],
     k6: ['**/*.load.js', '**/load.js'],
-    e2e_ui: ['**/*.spec.ts', '**/*.spec.js'],
-    frontend_unit: ['**/*.test.ts', '**/*.test.js'],
+    e2e_ui: jsGlobs('spec'),
+    frontend_unit: jsGlobs('test'),
     api: ['**/test_*.py', '**/*_test.py'],
     performance: ['**/*.load.js'],
     python_unit: ['**/test_*.py', '**/*_test.py'],
 };
-const DEFAULT_PATTERNS = ['**/test_*.py', '**/*.spec.ts', '**/*.test.ts'];
+const DEFAULT_PATTERNS = ['**/test_*.py', ...jsGlobs('spec', 'test')];
 const IGNORED_DIRS = new Set([
     'node_modules',
     '.git',