canary-test-cli 5.15.0 → 6.0.0

package/dist/engine/core/config-validation.js

@@ -0,0 +1,74 @@
+/**
+ * Shared fail-loud-but-not-hard-fail JSON config reading.
+ *
+ * Faithful TypeScript port of `agent/core/config_validation.py`. Callers that
+ * read a config file (`harness.config.json`, `.mcp.json`,
+ * `.canary/company.json`, ...) have historically caught every read/parse error
+ * in one blanket `catch` and treated the result the same as "file doesn't
+ * exist" — silently falling back to defaults. That collapses two very different
+ * situations into one:
+ *
+ *   - The file genuinely doesn't exist. Totally normal; fall back silently.
+ *   - The file exists but is malformed or unreadable. The user has a broken
+ *     config and deserves to know — silently treating it as absent produces
+ *     wrong-but-confident output.
+ *
+ * {@link readJsonWithWarning} distinguishes the two. It never raises: a
+ * malformed/unreadable file degrades to `[null, "<warning message>"]` rather
+ * than an exception, so existing call sites can adopt it without introducing a
+ * new failure mode. Callers are responsible for surfacing the warning message
+ * (CLI output, log line, etc.) — this module only detects and describes the
+ * problem.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Read and parse a JSON file, distinguishing "absent" from "malformed".
+ *
+ * Returns a `[data, warning]` tuple:
+ *
+ *   - `[null, null]` — the file does not exist. Not an error; the caller
+ *     should proceed as if there is no config.
+ *   - `[null, "<message>"]` — the file exists but could not be read or parsed.
+ *     The caller should surface this warning to the user instead of silently
+ *     treating the config as absent.
+ *   - `[data, null]` — the file exists and parsed successfully.
+ *
+ * Never raises.
+ */
+export function readJsonWithWarning(path) {
+    let exists;
+    try {
+        exists = existsSync(path);
+    }
+    catch {
+        // A broken symlink or similar can make even existence checks raise on some
+        // platforms; treat it as "can't confirm presence" -> warn, don't crash.
+        return [null, `${path} could not be accessed`];
+    }
+    if (!exists) {
+        return [null, null];
+    }
+    let text;
+    try {
+        // ACCEPTED DIVERGENCE: Python's `read_text(encoding="utf-8")` raises an
+        // UNCAUGHT `UnicodeDecodeError` on a non-UTF-8 file (the Python only catches
+        // `OSError`), which contradicts this function's own "Never raises" contract.
+        // Node's `readFileSync(path, 'utf-8')` substitutes U+FFFD instead, so a
+        // non-UTF-8 config degrades to an invalid-JSON warning below rather than
+        // crashing. We intentionally KEEP the safe behavior over the latent crash.
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (e) {
+        return [null, `${path} exists but could not be read: ${errMessage(e)}`];
+    }
+    try {
+        return [JSON.parse(text), null];
+    }
+    catch (e) {
+        return [null, `${path} exists but is not valid JSON: ${errMessage(e)}`];
+    }
+}
+function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=config-validation.js.map

package/dist/engine/core/detection.js

@@ -0,0 +1,48 @@
+/**
+ * Fail-loud auto-detection messaging.
+ *
+ * Faithful TypeScript port of `agent/core/detection.py`.
+ *
+ * Several CLI paths auto-detect something (a test framework, a doctor persona)
+ * and, when detection is uncertain, used to silently fall back to `unknown` /
+ * `None` or a bare "flag required" failure. That erodes user trust: the caller
+ * has no idea *what* was being detected, *why* it failed, or *what to do next*.
+ *
+ * {@link uncertainDetectionMessage} renders one clear, actionable message from
+ * the pieces a call site has on hand, so every uncertain-detection path reads
+ * the same way instead of each inventing its own ad hoc string. It is pure
+ * string-building — it never prints, raises, or decides control flow; the
+ * caller owns those. Message text is byte-for-byte identical to the oracle.
+ */
+/**
+ * Build a clear, actionable message for an uncertain/failed detection.
+ *
+ * Python: `uncertain_detection_message`. The keyword-only Python args
+ * (`reason`, `candidates`, `override_hint`) map to the {@link
+ * UncertainDetectionOptions} object; `override_hint` → `overrideHint`.
+ *
+ * @param what What we tried to detect, as a human-readable noun phrase (e.g.
+ *   "test framework", "doctor persona").
+ * @returns A single string. Always names `what` and always gives at least one
+ *   next step when an override hint or candidate list is provided — never a
+ *   bare `unknown`.
+ */
+export function uncertainDetectionMessage(what, options = {}) {
+    const { reason, candidates, overrideHint } = options;
+    const parts = [`Could not confidently auto-detect the ${what}.`];
+    // Python `if reason:` — an empty string is falsy and omits the clause.
+    if (reason) {
+        parts.push(`Reason: ${reason}.`);
+    }
+    // Python `if candidates:` — a missing or empty list omits the "Known …"
+    // clause entirely (no bare "Known …: ." string).
+    if (candidates && candidates.length > 0) {
+        const joined = candidates.join(', ');
+        parts.push(`Known ${what}(s): ${joined}.`);
+    }
+    if (overrideHint) {
+        parts.push(`Set it explicitly with ${overrideHint}.`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=detection.js.map

package/dist/engine/core/domain-scanner.js

@@ -0,0 +1,212 @@
+/**
+ * Domain knowledge scanner — faithful TS port of
+ * `agent/core/domain_scanner.py`.
+ *
+ * Scans a project's source files (not test files) to extract components, public
+ * functions, and API routes. Regex-based, no AST. Pure filesystem reads.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    '.harness',
+    'tests',
+    'test',
+    '__tests__',
+    'spec',
+    'coverage',
+]);
+const TEST_FILE_RE = /(^test_|_test\.py$|\.spec\.|\.test\.)/i;
+const MAX_SOURCE_FILES = 20;
+const MAX_FILE_BYTES = 32_768;
+const MAX_ITEMS = 15;
+const PY_EXTS = ['.py'];
+const JS_EXTS = ['.ts', '.tsx', '.js', '.jsx'];
+export function isEmpty(ctx) {
+    return ctx.sourceFiles === 0;
+}
+function emptyContext() {
+    return {
+        sourceFiles: 0,
+        modules: [],
+        components: [],
+        functions: [],
+        apiRoutes: [],
+    };
+}
+export class DomainScanner {
+    scan(projectRoot = '.') {
+        const root = resolve(projectRoot);
+        const all = walkSourceFiles(root);
+        const pyFiles = all.filter((p) => p.endsWith('.py')).sort(cmp);
+        const jsFiles = all
+            .filter((p) => JS_EXTS.some((e) => p.endsWith(e)))
+            .sort(cmp);
+        const files = [...pyFiles, ...jsFiles].slice(0, MAX_SOURCE_FILES);
+        if (files.length === 0)
+            return emptyContext();
+        const ctx = emptyContext();
+        ctx.sourceFiles = files.length;
+        ctx.modules = deriveModules(root, files);
+        for (const path of files) {
+            const text = safeRead(path);
+            if (text === null)
+                continue;
+            if (path.endsWith('.py'))
+                extractPython(text, ctx);
+            else
+                extractJs(text, ctx);
+        }
+        ctx.components = dedupCap(ctx.components);
+        ctx.functions = dedupCap(ctx.functions);
+        ctx.apiRoutes = dedupCap(ctx.apiRoutes);
+        return ctx;
+    }
+}
+function walkSourceFiles(root) {
+    const found = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                if (!isSourceExt(entry.name))
+                    continue;
+                // Faithful to Python: reject if ANY segment of the absolute path is an
+                // ignored dir — this includes ancestors above the scan root, not just
+                // dirs skipped during the walk.
+                if (hasIgnoredSegment(full))
+                    continue;
+                if (TEST_FILE_RE.test(entry.name))
+                    continue;
+                if (oversized(full))
+                    continue;
+                found.push(full);
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+function isSourceExt(name) {
+    return [...PY_EXTS, ...JS_EXTS].some((e) => name.endsWith(e));
+}
+function hasIgnoredSegment(absPath) {
+    return absPath.split(/[/\\]/).some((seg) => IGNORED_DIRS.has(seg));
+}
+function oversized(path) {
+    try {
+        return statSync(path).size > MAX_FILE_BYTES;
+    }
+    catch {
+        return true;
+    }
+}
+function deriveModules(root, files) {
+    const modules = [];
+    for (const path of files) {
+        const rel = relative(root, path);
+        if (rel.startsWith('..'))
+            continue;
+        const parts = rel.split(/[/\\]/);
+        parts[parts.length - 1] = parts[parts.length - 1].replace(/\.(py|tsx?|jsx?)$/, '');
+        if (parts[parts.length - 1] === '__init__')
+            parts.pop();
+        if (parts.length > 0)
+            modules.push(parts.join('/'));
+    }
+    return modules.slice(0, MAX_ITEMS);
+}
+function extractPython(text, ctx) {
+    for (const m of text.matchAll(/^class\s+([A-Za-z]\w*)/gm)) {
+        ctx.components.push(m[1]);
+    }
+    for (const m of text.matchAll(/^def\s+([a-z]\w*)\s*\(/gm)) {
+        const name = m[1];
+        if (!name.startsWith('_'))
+            ctx.functions.push(name);
+    }
+    const routeRe = /@(?:app|router|bp)\.(get|post|put|patch|delete|route)\s*\(\s*['"]([^'"]+)['"]/gi;
+    for (const m of text.matchAll(routeRe)) {
+        const method = m[1].toUpperCase();
+        const pathVal = m[2];
+        ctx.apiRoutes.push(method === 'ROUTE' ? pathVal : `${method} ${pathVal}`);
+    }
+}
+function extractJs(text, ctx) {
+    extractJsClasses(text, ctx);
+    extractJsCallables(text, ctx);
+    extractJsRoutes(text, ctx);
+}
+function extractJsClasses(text, ctx) {
+    for (const m of text.matchAll(/\bexport\s+(?:default\s+)?class\s+([A-Za-z]\w*)/g)) {
+        ctx.components.push(m[1]);
+    }
+}
+function extractJsCallables(text, ctx) {
+    for (const m of text.matchAll(/\bexport\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z]\w*)/g)) {
+        pushNamed(ctx, m[1]);
+    }
+    for (const m of text.matchAll(/\bexport\s+const\s+([A-Za-z]\w*)\s*(?::[^=]+)?\s*=/g)) {
+        pushNamed(ctx, m[1]);
+    }
+}
+function extractJsRoutes(text, ctx) {
+    const routeRe = /\b(?:router|app)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/gi;
+    for (const m of text.matchAll(routeRe)) {
+        ctx.apiRoutes.push(`${m[1].toUpperCase()} ${m[2]}`);
+    }
+}
+/** PascalCase → component; else function (matches the Python heuristic). */
+function pushNamed(ctx, name) {
+    if (name[0] === name[0].toUpperCase() && /[A-Z]/.test(name[0])) {
+        ctx.components.push(name);
+    }
+    else {
+        ctx.functions.push(name);
+    }
+}
+function dedupCap(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            result.push(item);
+        }
+        if (result.length >= MAX_ITEMS)
+            break;
+    }
+    return result;
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=domain-scanner.js.map