canary-test-cli 5.15.0 → 6.0.0

package/dist/engine/core/overlays.js

@@ -0,0 +1,176 @@
+/**
+ * Resolve tracked overlays for `canary migrate --from`.
+ *
+ * Faithful TypeScript port of `agent/core/overlays.py`. Tracked overlays are git
+ * clones under `~/.canary/overlays/<name>/` created by `canary overlay add`.
+ * This module maps a `--from` value to a clone path.
+ *
+ * Cross-runtime contract (matches the Phase 1 skill loader): the clone
+ * **directories** are the source of truth. `overlays.json` is written solely by
+ * the TS side and is read here **only** to order overlay names when it parses —
+ * its absence or corruption never blocks resolution (a directory scan is the
+ * fallback).
+ *
+ * Disambiguation: a value containing a path separator (`./o`, `../o`, `/abs/o`)
+ * is a **path**; a bare token (`example-org-example-overlay`) is an overlay
+ * **name**. A bare token is never treated as a path, so a same-named directory
+ * in the current working directory cannot shadow a tracked overlay, and a
+ * mistyped name fails loudly instead of silently resolving to a stray path.
+ *
+ * Python→TS nuances:
+ *   - `Path.resolve()` (absolute + symlink resolution + normalize) maps to
+ *     `fs.realpathSync`, so a macOS `/var` → `/private/var` symlink resolves the
+ *     same on both sides.
+ *   - Python's `OverlayNotFound.name` attribute (the overlay name) is exposed as
+ *     {@link OverlayNotFound.overlayName} — `Error.name` is reserved for the
+ *     class name in JS.
+ */
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+/** A `--from` value did not resolve to an overlay (bad name or missing path). */
+export class OverlayNotFound extends Error {
+    overlayName;
+    available;
+    constructor(name, available) {
+        const hint = available.length
+            ? 'tracked overlays: ' + available.join(', ')
+            : 'no overlays are tracked — add one with `canary overlay add <source>`';
+        super(`could not resolve overlay '${name}' (${hint})`);
+        this.name = 'OverlayNotFound';
+        this.overlayName = name;
+        this.available = available;
+    }
+}
+function overlaysRoot(home) {
+    return join(home, '.canary', 'overlays');
+}
+/** Overlay names in `overlays.json` order, or `[]` when it is unreadable. */
+function registryOrder(home) {
+    const registry = join(home, '.canary', 'overlays.json');
+    let data;
+    try {
+        data = JSON.parse(readFileSync(registry, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(data))
+        return [];
+    const overlays = data['overlays'];
+    if (!Array.isArray(overlays))
+        return [];
+    const names = [];
+    for (const o of overlays) {
+        if (isRecord(o) && typeof o['name'] === 'string') {
+            names.push(o['name']);
+        }
+    }
+    return names;
+}
+/**
+ * Map overlay name -> declared precedence from `overlays.json` (#333).
+ *
+ * A null/absent/non-numeric precedence is 0. An unreadable or malformed registry
+ * yields an empty map, so callers fall back to directory-name order. Higher
+ * precedence wins a skill-name collision — the winner rule mirrors the TS side
+ * (`npm/src/overlay-conflicts.ts`) so both runtimes agree.
+ */
+export function registryPrecedence(home) {
+    const h = home ?? homedir();
+    const registry = join(h, '.canary', 'overlays.json');
+    let data;
+    try {
+        data = JSON.parse(readFileSync(registry, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+    if (!isRecord(data))
+        return {};
+    const overlays = data['overlays'];
+    if (!Array.isArray(overlays))
+        return {};
+    const result = {};
+    for (const o of overlays) {
+        if (!isRecord(o) || typeof o['name'] !== 'string')
+            continue;
+        const p = o['precedence'];
+        // typeof excludes booleans (JSON `true`), null, undefined, and strings —
+        // the JS analog of Python's `isinstance(p, (int, float)) and not
+        // isinstance(p, bool)`.
+        result[o['name']] = typeof p === 'number' ? p : 0;
+    }
+    return result;
+}
+/**
+ * Names of tracked overlays (clone dirs under `~/.canary/overlays/`).
+ *
+ * Ordered by `overlays.json` when it parses (on-disk overlays not listed there
+ * are appended in sorted order); otherwise a plain sorted directory scan.
+ * Returns `[]` when no overlays root exists.
+ */
+export function listOverlays(home) {
+    const h = home ?? homedir();
+    const root = overlaysRoot(h);
+    if (!isDir(root))
+        return [];
+    const onDisk = new Set(listDirs(root));
+    const ordered = registryOrder(h).filter((name) => onDisk.has(name));
+    const orderedSet = new Set(ordered);
+    const extras = [...onDisk].filter((name) => !orderedSet.has(name)).sort();
+    return [...ordered, ...extras];
+}
+/**
+ * Resolve a `--from` value to an overlay clone path.
+ *
+ * A value with a path separator is resolved as a path (which must exist). A bare
+ * token is looked up as a tracked-overlay name under `~/.canary/overlays/`.
+ * Either miss throws {@link OverlayNotFound} carrying the available names.
+ */
+export function resolveOverlay(nameOrPath, home) {
+    const h = home ?? homedir();
+    if (looksLikePath(nameOrPath)) {
+        if (existsSync(nameOrPath))
+            return realpathSync(nameOrPath);
+        throw new OverlayNotFound(nameOrPath, listOverlays(h));
+    }
+    const candidate = join(overlaysRoot(h), nameOrPath);
+    if (isDir(candidate))
+        return realpathSync(candidate);
+    throw new OverlayNotFound(nameOrPath, listOverlays(h));
+}
+function looksLikePath(value) {
+    const separators = new Set([sep]);
+    // Python's `os.altsep` is "/" on Windows, unset on POSIX.
+    if (process.platform === 'win32')
+        separators.add('/');
+    for (const s of separators) {
+        if (value.includes(s))
+            return true;
+    }
+    return false;
+}
+// ── small helpers ─────────────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function listDirs(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=overlays.js.map

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

@@ -0,0 +1,147 @@
+/**
+ * Pattern-based test healer.
+ *
+ * Faithful TypeScript port of `agent/core/pattern_healer.py`. Applies
+ * regex-safe, deterministic fixes to test files without an LLM. Powers
+ * `canary heal-test --pattern`.
+ *
+ * Only fixes that are unambiguously correct are applied automatically:
+ *  - Hardcoded sleeps → replaced with a TODO comment pointing at event-based
+ *    waits.
+ *  - Missing `await` before Playwright action calls.
+ *
+ * Selector fixes are NOT auto-applied — swapping a selector without the actual
+ * DOM snapshot produces wrong fixes. Selector issues are flagged but left for
+ * the developer (or the /canary-heal-test slash command) to fix.
+ *
+ * Python→TS nuances: `re.sub` (replace-all) maps to `String.replace` with a `g`
+ * flag; `re.MULTILINE` maps to `m`. The greedy `\s*$` backtracking that
+ * governs whether a trailing newline is consumed is identical across both
+ * engines, so `before`/line-number bookkeeping matches byte-for-byte.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+export class HealChange {
+    line;
+    rule;
+    before;
+    after;
+    description;
+    constructor(line, rule, before, after, description) {
+        this.line = line;
+        this.rule = rule;
+        this.before = before;
+        this.after = after;
+        this.description = description;
+    }
+}
+export class HealResult {
+    file;
+    changes;
+    skipped;
+    patched_content;
+    constructor(file) {
+        this.file = file;
+        this.changes = [];
+        this.skipped = [];
+        this.patched_content = '';
+    }
+    get changed() {
+        return this.changes.length > 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fix rules
+// ---------------------------------------------------------------------------
+// NOTE on anchors: Python's `re.MULTILINE` treats ONLY `\n` as a line
+// boundary, but JS caret/dollar under /m also break on lone CR and
+// U+2028/U+2029. Under /g that would let these rules fire on lone-CR /
+// where the oracle matches nothing — and since `apply()` rewrites the file,
+// that silently changes content. So we anchor on `\n` explicitly —
+// `(?:^|(?<=\n))` for line start, `(?=\n|$)` for line end — and drop `/m`.
+// time.sleep(N) → # TODO: replace with event-based wait
+const PY_SLEEP = /(?:^|(?<=\n))(\s*)time\.sleep\s*\([^)]*\)\s*(?=\n|$)/g;
+// page.waitForTimeout(N) → # TODO: replace with event-based wait
+const PW_WAIT_TIMEOUT = /(?:^|(?<=\n))(\s*)(await\s+)?page\.waitForTimeout\s*\([^)]*\)\s*;?\s*(?=\n|$)/g;
+// Missing await before Playwright action — line starts with indentation then
+// page/frame/locator.<action>( without a leading await
+const BARE_PW_ACTION = /(?:^|(?<=\n))(\s*)((?:page|frame|locator)\.(?:click|fill|type|check|uncheck|selectOption|hover|focus|press|tap|dblclick)\s*\([^)]*\))/g;
+// Brittle-selector detection (flag-only; never auto-fixed).
+const SELECTOR_SKIP = new RegExp(`['"]\\.[a-zA-Z][\\w\\-]*['"]|['"]#[a-zA-Z][\\w\\-]*['"]|['"]/+[a-zA-Z\\[\\]/@*]`);
+/** Python `code[:m.start()].count("\n") + 1`. */
+function lineOf(code, index) {
+    let n = 1;
+    for (let i = 0; i < index; i++) {
+        if (code[i] === '\n')
+            n++;
+    }
+    return n;
+}
+/** Python `str.rstrip("\n")`. */
+function rstripNewlines(s) {
+    return s.replace(/\n+$/, '');
+}
+/**
+ * Python `str[:n]` slices by code point; JS `slice` slices by UTF-16 unit, so
+ * an astral char (e.g. an emoji) counts as 2 and truncates early. Slice by code
+ * point to match the oracle.
+ */
+function pySlice(s, n) {
+    return Array.from(s).slice(0, n).join('');
+}
+function fixPySleep(code, changes) {
+    return code.replace(PY_SLEEP, (full, indent, offset) => {
+        const before = rstripNewlines(full);
+        const after = `${indent}# TODO(canary): replace with an event-based wait (e.g. waitFor, wait_for_selector)`;
+        changes.push(new HealChange(lineOf(code, offset), 'HEAL-001', before, after, 'Replaced time.sleep() with a TODO comment.'));
+        return after + '\n';
+    });
+}
+function fixPwWaitTimeout(code, changes) {
+    return code.replace(PW_WAIT_TIMEOUT, (full, indent, _await, offset) => {
+        const before = rstripNewlines(full);
+        const after = `${indent}// TODO(canary): replace with an event-based wait (e.g. await expect(locator).toBeVisible())`;
+        changes.push(new HealChange(lineOf(code, offset), 'HEAL-002', before, after, 'Replaced page.waitForTimeout() with a TODO comment.'));
+        return after + '\n';
+    });
+}
+function fixMissingAwait(code, changes) {
+    return code.replace(BARE_PW_ACTION, (full, indent, call, offset) => {
+        const before = rstripNewlines(full);
+        const after = `${indent}await ${call}`;
+        changes.push(new HealChange(lineOf(code, offset), 'HEAL-003', before, after, `Added missing \`await\` before \`${pySlice(call, 40)}\`.`));
+        return after;
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Applies deterministic, regex-safe fixes to test files. */
+export class PatternHealer {
+    heal(path) {
+        const original = readFileSync(path, 'utf-8');
+        const result = new HealResult(path);
+        let code = original;
+        code = fixPySleep(code, result.changes);
+        code = fixPwWaitTimeout(code, result.changes);
+        code = fixMissingAwait(code, result.changes);
+        result.patched_content = code;
+        // Note what we deliberately skip.
+        if (SELECTOR_SKIP.test(original)) {
+            result.skipped.push('Brittle selectors detected but not auto-fixed — selector swaps require DOM context. ' +
+                'Use /canary-heal-test in Claude Code for selector repair.');
+        }
+        return result;
+    }
+    /** Heal and write the result back to disk. */
+    apply(path) {
+        const result = this.heal(path);
+        if (result.changed) {
+            writeFileSync(path, result.patched_content, 'utf-8');
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=pattern-healer.js.map

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

@@ -0,0 +1,255 @@
+/**
+ * Pattern matcher — extracts a project's existing test conventions.
+ *
+ * Faithful TypeScript port of `agent/core/pattern_matcher.py`. Scans a project
+ * for existing test files and summarises naming/import/assertion conventions so
+ * generated tests match. Uses a dependency-free recursive walk with the same
+ * glob tails and ignore-dir set as the Python original.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+const FILE_PATTERNS = {
+    playwright: ['**/*.spec.ts', '**/*.spec.js', '**/*.test.ts', '**/*.test.js'],
+    vitest: ['**/*.test.ts', '**/*.test.js', '**/*.spec.ts', '**/*.spec.js'],
+    pytest: ['**/test_*.py', '**/*_test.py'],
+    k6: ['**/*.load.js', '**/load.js'],
+    e2e_ui: ['**/*.spec.ts', '**/*.spec.js'],
+    frontend_unit: ['**/*.test.ts', '**/*.test.js'],
+    api: ['**/test_*.py', '**/*_test.py'],
+    performance: ['**/*.load.js'],
+    python_unit: ['**/test_*.py', '**/*_test.py'],
+};
+const DEFAULT_PATTERNS = ['**/test_*.py', '**/*.spec.ts', '**/*.test.ts'];
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+]);
+const MAX_FILES = 10;
+const MAX_FILE_BYTES = 32_768;
+function emptyProfile() {
+    return {
+        test_count: 0,
+        language: '',
+        naming_style: '',
+        assertion_style: '',
+        uses_classes: false,
+        uses_fixtures: false,
+        uses_describe: false,
+        common_imports: [],
+        sample_names: [],
+    };
+}
+/** Convert a recursive-glob pattern to a basename regex (`*` becomes `[^/]*`). */
+function tailRegex(pattern) {
+    const tail = pattern.replace(/^\*\*\//, '');
+    const body = tail
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*');
+    return new RegExp(`^${body}$`);
+}
+/** `Counter.most_common(n)`: count desc, ties in first-seen order. */
+function mostCommon(items, n) {
+    const counts = new Map();
+    for (const it of items)
+        counts.set(it, (counts.get(it) ?? 0) + 1);
+    return [...counts.entries()]
+        .map(([key], i) => ({ key, count: counts.get(key), i }))
+        .sort((a, b) => b.count - a.count || a.i - b.i)
+        .slice(0, n)
+        .map((e) => e.key);
+}
+function walk(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (IGNORED_DIRS.has(e.name))
+                continue;
+            walk(join(dir, e.name), out);
+        }
+        else if (e.isFile()) {
+            out.push(join(dir, e.name));
+        }
+    }
+}
+export function findTestFiles(root, framework, testType) {
+    const patterns = FILE_PATTERNS[framework] ?? FILE_PATTERNS[testType] ?? DEFAULT_PATTERNS;
+    const regexes = patterns.map(tailRegex);
+    const all = [];
+    walk(root, all);
+    const found = [];
+    const seen = new Set();
+    for (const path of all) {
+        const base = path.slice(path.lastIndexOf('/') + 1);
+        if (!regexes.some((re) => re.test(base)))
+            continue;
+        if (seen.has(path))
+            continue;
+        try {
+            if (statSync(path).size > MAX_FILE_BYTES)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        seen.add(path);
+        found.push(path);
+    }
+    return found.sort();
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// --- Python analysis -------------------------------------------------------
+const PY_IMPORT = /^(?:from\s+([\w.]+)\s+import|import\s+([\w.,\s]+))/gm;
+const PY_TEST_FN = /^\s*def\s+(test_\w+)/gm;
+const PY_CLASS = /^\s*class\s+Test\w+/m;
+const PY_FIXTURE = /@pytest\.fixture|conftest/;
+function pythonNamingStyle(names, usesClasses) {
+    if (names.length === 0) {
+        return `${usesClasses ? 'class-based' : 'function-based'} pytest tests`;
+    }
+    const bodies = names
+        .filter((n) => n.startsWith('test_'))
+        .map((n) => n.slice('test_'.length));
+    const should = bodies.filter((b) => b.startsWith('should_')).length;
+    const when = bodies.filter((b) => b.startsWith('when_')).length;
+    const raises = bodies.filter((b) => b.includes('raises') || b.includes('error')).length;
+    let pattern = 'test_<action>_<result> convention';
+    if (should > Math.floor(bodies.length / 2))
+        pattern = 'test_should_* convention';
+    else if (when > Math.floor(bodies.length / 2))
+        pattern = 'test_when_* convention';
+    else if (raises > Math.floor(bodies.length / 3))
+        pattern = 'test_<action>_raises_* convention';
+    return `${usesClasses ? 'class-based' : 'function-based'} pytest, ${pattern}`;
+}
+function parsePyImports(text) {
+    const mods = [];
+    for (const m of text.matchAll(PY_IMPORT)) {
+        const mod = (m[1] || m[2] || '').split(/\s+/)[0].replace(/,$/, '');
+        if (mod)
+            mods.push(mod);
+    }
+    return mods;
+}
+function analyzePython(files, profile) {
+    const imports = [];
+    const funcNames = [];
+    let hasClasses = false;
+    let hasFixtures = false;
+    for (const path of files) {
+        const text = readText(path);
+        if (text === null)
+            continue;
+        imports.push(...parsePyImports(text));
+        for (const m of text.matchAll(PY_TEST_FN))
+            funcNames.push(m[1]);
+        if (PY_CLASS.test(text))
+            hasClasses = true;
+        if (PY_FIXTURE.test(text))
+            hasFixtures = true;
+    }
+    profile.uses_classes = hasClasses;
+    profile.uses_fixtures = hasFixtures;
+    profile.common_imports = mostCommon(imports, 8);
+    profile.sample_names = funcNames.slice(0, 5);
+    profile.naming_style = pythonNamingStyle(funcNames, hasClasses);
+    profile.assertion_style = hasClasses
+        ? 'unittest self.assert* methods'
+        : 'pytest assert statements';
+}
+// --- JS / TS analysis ------------------------------------------------------
+const JS_IMPORT = /^import\s+.*?\s+from\s+['"]([^'"]+)['"]/gm;
+const JS_REQUIRE = /require\(['"]([^'"]+)['"]\)/g;
+const JS_DESCRIBE = /\bdescribe\s*\(/;
+const JS_TEST_NAME = /\b(?:it|test)\s*\(\s*['"]([^'"]{3,60})['"]/g;
+function jsNamingStyle(names, usesDescribe) {
+    const structure = usesDescribe
+        ? 'describe/it blocks'
+        : 'top-level test() calls';
+    if (names.length === 0)
+        return structure;
+    const should = names.filter((n) => n.toLowerCase().startsWith('should')).length;
+    const sentence = names.filter((n) => /^[A-Z]/.test(n)).length;
+    let style = 'imperative names';
+    if (should > Math.floor(names.length / 2))
+        style = 'should-style names';
+    else if (sentence > Math.floor(names.length / 2))
+        style = 'sentence-style names';
+    return `${structure}, ${style}`;
+}
+function jsAssertionStyle(imports) {
+    const relevant = imports.filter((i) => i.includes('expect') || i.includes('chai') || i.includes('assert'));
+    if (relevant.some((i) => i.includes('chai')))
+        return 'chai expect assertions';
+    if (relevant.some((i) => i.includes('assert')))
+        return 'assert-style assertions';
+    return 'expect().toBe() / toEqual() assertions';
+}
+function analyzeJs(files, profile) {
+    const imports = [];
+    const testNames = [];
+    let hasDescribe = false;
+    for (const path of files) {
+        const text = readText(path);
+        if (text === null)
+            continue;
+        for (const m of text.matchAll(JS_IMPORT))
+            imports.push(m[1]);
+        for (const m of text.matchAll(JS_REQUIRE))
+            imports.push(m[1]);
+        if (JS_DESCRIBE.test(text))
+            hasDescribe = true;
+        for (const m of text.matchAll(JS_TEST_NAME))
+            testNames.push(m[1]);
+    }
+    profile.uses_describe = hasDescribe;
+    profile.common_imports = mostCommon(imports, 8);
+    profile.sample_names = testNames.slice(0, 5);
+    profile.naming_style = jsNamingStyle(testNames, hasDescribe);
+    profile.assertion_style = jsAssertionStyle([...new Set(imports)]);
+}
+export function isEmpty(profile) {
+    return profile.test_count === 0;
+}
+export class PatternMatcher {
+    scan(projectRoot = '.', framework = '', testType = '') {
+        const root = resolve(projectRoot);
+        const files = findTestFiles(root, framework, testType);
+        if (files.length === 0)
+            return emptyProfile();
+        const sample = files.slice(0, MAX_FILES);
+        let isPython = framework === 'pytest' ||
+            testType === 'api' ||
+            testType === 'python_unit';
+        if (!isPython && sample.length > 0)
+            isPython = extname(sample[0]) === '.py';
+        const profile = emptyProfile();
+        profile.test_count = files.length;
+        profile.language = isPython ? 'python' : 'javascript';
+        if (isPython)
+            analyzePython(sample, profile);
+        else
+            analyzeJs(sample, profile);
+        return profile;
+    }
+}
+//# sourceMappingURL=pattern-matcher.js.map