canary-test-cli 7.0.0 → 7.2.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
@@ -272,7 +266,7 @@ function isLocallyEdited(overlayHash, targetHash, recordedHash) {
  * 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',
@@ -311,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();
@@ -347,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;
     }
@@ -1525,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',

package/dist/engine/core/persona.js

@@ -0,0 +1,421 @@
+/**
+ * Personas as a first-class engine concept (issue #462).
+ *
+ * Audience adaptation used to be hand-rolled per skill: each one restated some
+ * variant of "if tester, use simpler words" in its own prose, with its own
+ * vocabulary and its own inference rules. Nothing shared a definition, so tone
+ * drifted between skills and an overlay had nothing to override. The drift was
+ * measurable — `canary-edge-case-discovery` documented
+ * `--level sdet|junior|manual` while {@link
+ * import('./environment-detect.js').detectUserLevel} returned
+ * `sdet|manual|unknown`, and no code read either.
+ *
+ * This module replaces that with one definition skills **consult**:
+ *
+ *   - a **registry** (`ts/src/data/personas/registry.json`) naming each
+ *     audience, how much explanation it wants, which output formats suit it,
+ *     and whether choices should be annotated with their reasoning;
+ *   - a pure **resolver** that picks one from an explicit choice, a detected
+ *     signal, or a fallback, and reports **which** and **why**;
+ *   - **overlay extension** through the same `precedence` arbitration the
+ *     overlay contract already defines for skill-name collisions (#333).
+ *
+ * Three deliberate boundaries, each of which was a decision rather than an
+ * omission:
+ *
+ * **Voice is not a persona field.** `voice/discovery.md` already resolves a
+ * named voice profile from its own project config, scoped by its own globs.
+ * Audience depth and character voice are orthogonal axes — a senior SDET may
+ * want a voiced-but-terse report while a manual tester wants the same voice
+ * with more explanation — so collapsing them into one field would make half
+ * the combinations inexpressible.
+ *
+ * **The fallback is explanatory, not degraded.** Most users will never
+ * configure this, so the no-signal answer has to be a good answer. Erring
+ * explanatory is the repo owner's stated default on #341 and #342: over-
+ * explaining is a mild annoyance, under-explaining silently fails a manual
+ * tester. It is *not* the maximum-explanation persona either, which would
+ * assert an audience nobody claimed.
+ *
+ * **Nothing here reads the environment.** Like `environment-detect.ts`, every
+ * input arrives as an argument, so the resolver is deterministic and the
+ * decision of where a signal comes from stays with the caller.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { uncertainDetectionMessage } from './detection.js';
+import { listOverlays, registryPrecedence, resolveOverlay, } from './overlays.js';
+/** How much explanation a persona wants around the same finding. */
+const DEPTHS = ['terse', 'brief', 'guided'];
+/**
+ * Confidence floor applied when a registry declares none.
+ *
+ * Note what the detector's confidence actually is: `|sdet - manual| / total`,
+ * a *margin* between two tallies, not a probability. One open `.ts` file with
+ * no opposing signal scores 1.0. So this floor screens out genuine ties and
+ * near-ties and nothing else; {@link DEFAULT_MIN_DETECTION_SIGNALS} is the
+ * screen that does the real discriminating.
+ */
+const DEFAULT_MIN_DETECTION_CONFIDENCE = 0.5;
+/**
+ * Independent signals required before a detected level is trusted.
+ *
+ * A confidence floor cannot carry this decision on its own: because confidence
+ * is a margin, one unopposed observation arrives at a perfect 1.0, and a floor
+ * that screens ties but not single observations is confident-and-wrong — the
+ * failure mode this repo keeps rooting out. Two signals of genuinely different
+ * kinds is the screen that discriminates.
+ *
+ * "Independent" is per {@link independentSignalKinds}: distinct *kinds* of
+ * evidence, not a raw count. Ten open TypeScript files are one observation
+ * restated ten times.
+ */
+const DEFAULT_MIN_DETECTION_SIGNALS = 2;
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isDepth(v) {
+    return DEPTHS.includes(v);
+}
+function stringArray(v) {
+    if (!Array.isArray(v))
+        return null;
+    return v.every((x) => typeof x === 'string') ? [...v] : null;
+}
+/**
+ * Validate one raw persona entry, or return null.
+ *
+ * Dropping a malformed entry rather than throwing is deliberate for the
+ * *overlay* path: one bad downstream file must not take the engine's own
+ * personas down with it. The count is observable through {@link personaIds},
+ * so a dropped entry shows up as a missing id rather than as silence.
+ */
+function parsePersona(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { id, label, audience, depth, reasoning } = raw;
+    const formats = stringArray(raw['formats']);
+    if (typeof id !== 'string' || id.trim() === '')
+        return null;
+    if (typeof label !== 'string' || typeof audience !== 'string')
+        return null;
+    if (!isDepth(depth) || formats === null)
+        return null;
+    if (typeof reasoning !== 'boolean')
+        return null;
+    return { id: id.trim(), label, audience, depth, formats, reasoning };
+}
+function parsePersonas(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const parsed = parsePersona(entry);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+function parseDetectionMap(raw) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    for (const [level, target] of Object.entries(raw)) {
+        if (typeof target === 'string')
+            out[level] = target;
+    }
+    return out;
+}
+/** Default registry path: `<module dir>/../data/personas/registry.json`. */
+function defaultPersonaRegistryPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // here = <core> -> sibling data/ dir (src/data under vitest, dist/data once
+    // built and copied by ts/scripts/copy-data.mjs).
+    return resolve(here, '..', 'data', 'personas', 'registry.json');
+}
+/**
+ * Read and validate a persona registry.
+ *
+ * Throws — rather than degrading to an empty registry — because the engine's
+ * own registry going missing is a build/packaging fault, and a silently empty
+ * one would make every resolution return the same fallback while reporting
+ * nothing. Overlay registries take the forgiving path instead; see
+ * {@link readOverlayPersonaLayers}.
+ */
+function loadPersonaRegistry(registryPath = defaultPersonaRegistryPath()) {
+    let text;
+    try {
+        text = readFileSync(registryPath, 'utf-8');
+    }
+    catch (err) {
+        // `String(err)` rather than `err.message`: both throwers here raise real
+        // Errors, so an `instanceof` guard would only add an unreachable branch.
+        throw new Error(`could not read persona registry ${registryPath}: ${String(err)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`persona registry ${registryPath} is not JSON: ${String(err)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new Error(`persona registry ${registryPath} must be a JSON object, not an array` +
+            ' or scalar');
+    }
+    const version = typeof raw['version'] === 'number' ? raw['version'] : 1;
+    const fallback = typeof raw['fallback'] === 'string' ? raw['fallback'] : '';
+    const floor = raw['minDetectionConfidence'];
+    const signalFloor = raw['minDetectionSignals'];
+    return {
+        version,
+        fallback,
+        minDetectionConfidence: typeof floor === 'number' ? floor : DEFAULT_MIN_DETECTION_CONFIDENCE,
+        minDetectionSignals: typeof signalFloor === 'number'
+            ? signalFloor
+            : DEFAULT_MIN_DETECTION_SIGNALS,
+        detectionMap: parseDetectionMap(raw['detectionMap']),
+        personas: parsePersonas(raw['personas']),
+    };
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+/**
+ * The distinct *kinds* of evidence in a detector signal list.
+ *
+ * `detectUserLevel` emits signals shaped `"<kind>: <detail>"` — for example
+ * `"code/test file open: a.ts"`, `"project manifest present: package.json"` —
+ * plus one kindless string (`"cwd path suggests manual testing"`), which is
+ * treated as its own kind. Grouping on the part before the first `": "` is what
+ * makes ten open TypeScript files count once: they are one observation restated,
+ * and a raw length check would have read them as ten independent facts.
+ *
+ * Splitting on `": "` rather than `":"` keeps a Windows path (`C:\src\a.ts`)
+ * from being mistaken for a separator.
+ */
+function independentSignalKinds(signals) {
+    const kinds = new Set();
+    for (const signal of signals) {
+        const at = signal.indexOf(': ');
+        kinds.add(at === -1 ? signal : signal.slice(0, at));
+    }
+    return [...kinds];
+}
+/** Ids in registry order — the discoverable persona vocabulary. */
+function personaIds(registry) {
+    return registry.personas.map((p) => p.id);
+}
+/** The persona with this id (case-insensitive), or null. */
+function findPersona(registry, id) {
+    if (typeof id !== 'string')
+        return null;
+    const want = id.trim().toLowerCase();
+    if (want === '')
+        return null;
+    return registry.personas.find((p) => p.id.toLowerCase() === want) ?? null;
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+function fallbackPersona(registry) {
+    const named = findPersona(registry, registry.fallback);
+    if (named)
+        return named;
+    const first = registry.personas[0];
+    if (first)
+        return first;
+    // Never invent one. An empty registry is the denominator-zero case: the
+    // caller asked for an audience and there is no vocabulary to answer from.
+    throw new Error('persona registry defines no personas, so no persona can be resolved');
+}
+/**
+ * Choose a persona and say where the choice came from.
+ *
+ * Precedence, highest first: an explicit id, then a detected level whose
+ * confidence clears the registry floor, then the fallback. An explicit id that
+ * names nothing does **not** suppress the rest of the cascade — a typo is a
+ * mistake, not an instruction to ignore the signal — but it is always named in
+ * the reason, so the mistake surfaces instead of being swallowed.
+ */
+export function resolvePersona(input = {}) {
+    // `exactOptionalPropertyTypes` forbids passing an explicit `undefined`, so
+    // omit the key rather than forwarding it.
+    const registry = input.registry ??
+        effectivePersonaRegistry(input.home === undefined ? {} : { home: input.home });
+    const signals = [...(input.detected?.signals ?? [])];
+    const notes = [];
+    const explicit = input.explicit;
+    if (typeof explicit === 'string' && explicit.trim() !== '') {
+        const chosen = findPersona(registry, explicit);
+        if (chosen) {
+            return {
+                persona: chosen,
+                source: 'explicit',
+                reason: `explicit persona '${chosen.id}'`,
+                signals,
+            };
+        }
+        notes.push(uncertainDetectionMessage('persona', {
+            reason: `'${explicit.trim()}' is not a known persona`,
+            candidates: personaIds(registry),
+        }));
+    }
+    const detected = input.detected;
+    if (detected) {
+        const floor = registry.minDetectionConfidence;
+        const signalFloor = registry.minDetectionSignals;
+        const kinds = independentSignalKinds(signals);
+        const target = registry.detectionMap[detected.level];
+        const mapped = findPersona(registry, target);
+        if (!mapped) {
+            // Reported ahead of the signal count on purpose: an unmapped level is a
+            // vocabulary problem, and "open more files" would be the wrong next step.
+            notes.push(`detected user level '${detected.level}' maps to no persona, so the` +
+                ' fallback applies');
+        }
+        else if (kinds.length < signalFloor) {
+            // Named as a count rather than as "no signal": a reader has to be able to
+            // tell "I looked and found too little" from "I found nothing", because
+            // only one of those is fixed by giving the detector more to look at.
+            notes.push(`detected '${detected.level}' from ${kinds.length} independent ` +
+                `signal(s) (${signalFloor} required), so the fallback applies`);
+        }
+        else if (detected.confidence < floor) {
+            notes.push(`detected '${detected.level}' at confidence ` +
+                `${detected.confidence} is below the ${floor} floor, so the` +
+                ' fallback applies');
+        }
+        else {
+            notes.push(`detected user level '${detected.level}' at confidence ` +
+                `${detected.confidence}`);
+            return {
+                persona: mapped,
+                source: 'detected',
+                reason: notes.join('; '),
+                signals,
+            };
+        }
+    }
+    const persona = fallbackPersona(registry);
+    notes.push(`fell back to '${persona.id}'`);
+    return { persona, source: 'fallback', reason: notes.join('; '), signals };
+}
+/**
+ * A JSON-serialisable view for embedding in an MCP response.
+ *
+ * Flat rather than nested, and it carries `source`, `reason`, and `signals`
+ * beside the definition: a consumer that adapts its output owes the user an
+ * answer to "why did you decide I was that?".
+ */
+export function personaToDict(resolved) {
+    const { persona, source, reason, signals } = resolved;
+    return {
+        id: persona.id,
+        label: persona.label,
+        audience: persona.audience,
+        depth: persona.depth,
+        formats: [...persona.formats],
+        reasoning: persona.reasoning,
+        source,
+        reason,
+        signals: [...signals],
+    };
+}
+// ---------------------------------------------------------------------------
+// Overlay extension (#333 precedence)
+// ---------------------------------------------------------------------------
+/**
+ * Read each installed overlay's `.canary/personas.json`.
+ *
+ * Forgiving by design: a missing file means the overlay simply has no opinion,
+ * and an unreadable or malformed one is skipped rather than fatal, because a
+ * downstream overlay must not be able to break the engine's own vocabulary.
+ *
+ * The clone path comes from `resolveOverlay` rather than being rebuilt here, so
+ * `~/.canary/overlays/<name>` stays defined in exactly one place.
+ */
+function readOverlayPersonaLayers(home) {
+    const precedence = registryPrecedence(home);
+    const layers = [];
+    for (const overlay of listOverlays(home)) {
+        const path = join(resolveOverlay(overlay, home), '.canary', 'personas.json');
+        if (!existsSync(path))
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(raw))
+            continue;
+        const fallback = raw['fallback'];
+        layers.push({
+            overlay,
+            precedence: precedence[overlay] ?? 0,
+            personas: parsePersonas(raw['personas']),
+            fallback: typeof fallback === 'string' ? fallback : null,
+        });
+    }
+    return layers;
+}
+/**
+ * Fold overlay layers onto the base registry.
+ *
+ * Layers are applied in ascending `(precedence, overlay-name)` order and the
+ * last writer wins — byte-for-byte the rule `skill-registry.ts` uses for
+ * skill-name collisions, so a downstream operator who has already reasoned
+ * about which overlay wins a skill does not have to learn a second model for
+ * personas. An id already in the base is replaced **in place**, so extending
+ * the vocabulary never reorders it.
+ */
+function mergePersonaRegistries(base, layers) {
+    const ordered = [...layers].sort((a, b) => a.precedence - b.precedence || a.overlay.localeCompare(b.overlay));
+    const personas = [...base.personas];
+    let fallback = base.fallback;
+    for (const layer of ordered) {
+        for (const persona of layer.personas) {
+            const at = personas.findIndex((p) => p.id.toLowerCase() === persona.id.toLowerCase());
+            if (at >= 0)
+                personas[at] = persona;
+            else
+                personas.push(persona);
+        }
+        if (layer.fallback !== null)
+            fallback = layer.fallback;
+    }
+    const merged = { ...base, personas, fallback };
+    // A fallback naming nothing is worse than no opinion: it would silently
+    // demote resolution to "first persona in the list".
+    if (!findPersona(merged, merged.fallback))
+        merged.fallback = base.fallback;
+    return merged;
+}
+/**
+ * The registry a resolution actually sees: shipped, plus every overlay.
+ *
+ * This is the function that makes overlay extension real rather than
+ * decorative. {@link resolvePersona} calls it whenever the caller does not
+ * hand over a registry outright, so a downstream `.canary/personas.json` reaches
+ * every consumer without each one remembering to merge — which is the mistake
+ * #341 is a record of: a signal that was produced correctly and read by nobody.
+ *
+ * Re-read per call rather than cached. `analyze_file` already scans the project
+ * tree, so one small JSON read plus a directory listing is not the cost worth
+ * trading a stale-config bug for.
+ *
+ * `registryPath` points the base registry somewhere other than the shipped
+ * file. It is the whole public seam onto the loader: the parsing and merging
+ * helpers below are intentionally module-private, so this is how both a caller
+ * with its own registry and a test exercising a malformed one get in.
+ */
+export function effectivePersonaRegistry(options = {}) {
+    return mergePersonaRegistries(loadPersonaRegistry(options.registryPath), readOverlayPersonaLayers(options.home));
+}
+//# sourceMappingURL=persona.js.map