doc-detective 4.0.2-dev.1 → 4.0.2-dev.11

package/dist/agents/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agents/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,SAAS,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;KACnD,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC;CACvB;AAOD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,iBAAiB,EACvB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,aAAa,EAAE,CAAC,CAmE1B"}

package/dist/agents/runner.js

@@ -0,0 +1,155 @@
+import { listAdapters } from "./registry.js";
+const defaultLogger = (msg, level = "info") => {
+    if (level === "error")
+        console.error(msg);
+    else
+        console.log(msg);
+};
+export async function runInstallAgents(argv, deps = {}) {
+    const adapters = deps.adapters ?? listAdapters();
+    const logger = deps.logger ?? defaultLogger;
+    const isTTY = deps.isTTY ?? (() => Boolean(process.stdin.isTTY));
+    const dryRun = argv["dry-run"] === true;
+    // --yes requires explicit --agent and --scope; no prompts.
+    if (argv.yes) {
+        if (!argv.agent || argv.agent.length === 0) {
+            throw new Error("--yes requires at least one --agent (for example, --agent claude).");
+        }
+        if (!argv.scope) {
+            throw new Error("--yes requires --scope project|global.");
+        }
+    }
+    // Resolve which agents to target.
+    const targeted = await resolveTargetAgents(argv, adapters, {
+        isTTY: isTTY(),
+        prompts: deps.prompts,
+        logger,
+    });
+    if (targeted.length === 0) {
+        return [];
+    }
+    // Resolve scope.
+    const scope = await resolveScope(argv, targeted, {
+        isTTY: isTTY(),
+        prompts: deps.prompts,
+    });
+    // Install each in order; collect reports. When an adapter doesn't support
+    // the requested scope, degrade to its nearest supported scope and attach a
+    // note to the report so callers see the divergence.
+    const reports = [];
+    for (const adapter of targeted) {
+        const effective = effectiveScopeFor(adapter, scope);
+        if (effective.degraded) {
+            logger(`⚠ ${adapter.displayName} does not support ${scope} scope — installing as ${effective.scope}.`, "warn");
+        }
+        logger(`\n→ ${adapter.displayName} (${adapter.id}) — scope: ${effective.scope}`, "info");
+        const report = await adapter.install({
+            scope: effective.scope,
+            force: Boolean(argv.force),
+            dryRun,
+            logger,
+        });
+        const finalReport = effective.degraded
+            ? {
+                ...report,
+                notes: [
+                    ...(report.notes ?? []),
+                    `Requested scope '${scope}' is not supported by ${adapter.displayName}; installed as '${effective.scope}' instead.`,
+                ],
+            }
+            : report;
+        reports.push(finalReport);
+        logger(summarizeReport(finalReport), "info");
+    }
+    return reports;
+}
+/**
+ * Resolve the effective scope an adapter will actually receive. If the desired
+ * scope is supported, pass it through. Otherwise, degrade to the adapter's
+ * first supported scope and flag that we did.
+ */
+function effectiveScopeFor(adapter, desired) {
+    const supported = adapter.supportsScopes();
+    if (supported.includes(desired))
+        return { scope: desired, degraded: false };
+    return { scope: supported[0], degraded: true };
+}
+async function resolveTargetAgents(argv, adapters, ctx) {
+    if (argv.agent && argv.agent.length > 0) {
+        const chosen = [];
+        const seen = new Set();
+        for (const id of argv.agent) {
+            // Preserve first-seen order but drop duplicates — `--agent codex --agent codex`
+            // should run one install, not two.
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const match = adapters.find((a) => a.id === id);
+            if (!match) {
+                const known = adapters.map((a) => a.id).join(", ");
+                throw new Error(`Unknown agent '${id}'. Known agents: ${known}`);
+            }
+            chosen.push(match);
+        }
+        return chosen;
+    }
+    // No --agent: run detection across all adapters and prompt the user with the
+    // ones that reported present.
+    const detections = await Promise.all(adapters.map(async (a) => ({ adapter: a, result: await a.detect() })));
+    const detected = detections.filter((d) => d.result.present).map((d) => d.adapter);
+    if (detected.length === 0) {
+        ctx.logger("No supported coding agents detected on this machine. Install one (e.g., Claude Code) and re-run.", "info");
+        return [];
+    }
+    if (!ctx.isTTY) {
+        throw new Error("Cannot prompt for agents in a non-TTY environment. Pass --agent explicitly (repeatable).");
+    }
+    if (!ctx.prompts) {
+        throw new Error("No prompts implementation available; pass --agent explicitly.");
+    }
+    const selectedIds = await ctx.prompts.pickAgents(detected);
+    return detected.filter((a) => selectedIds.includes(a.id));
+}
+async function resolveScope(argv, targeted, ctx) {
+    if (argv.scope === "project" || argv.scope === "global") {
+        return argv.scope;
+    }
+    // Intersect the supported-scope sets across all chosen adapters. Seed with
+    // the first adapter's supported scopes (not `[]`) so that an empty running
+    // intersection stays empty — otherwise the next adapter would re-seed it.
+    const [first, ...rest] = targeted;
+    const intersection = rest.reduce((acc, a) => acc.filter((s) => a.supportsScopes().includes(s)), first.supportsScopes());
+    // If no scope is common to every chosen adapter, pick "global" as a
+    // sensible default and let each adapter degrade via effectiveScopeFor().
+    if (intersection.length === 0)
+        return "global";
+    if (intersection.length === 1)
+        return intersection[0];
+    if (!ctx.isTTY) {
+        throw new Error("Cannot prompt for scope in a non-TTY environment. Pass --scope project|global.");
+    }
+    if (!ctx.prompts) {
+        throw new Error("No prompts implementation available; pass --scope project|global.");
+    }
+    return ctx.prompts.pickScope(intersection);
+}
+function summarizeReport(r) {
+    const ver = r.installedVersion ? ` @ ${r.installedVersion}` : "";
+    switch (r.action) {
+        case "installed":
+            return `  installed${ver}`;
+        case "updated":
+            return `  updated${ver}`;
+        case "already-up-to-date":
+            return `  already up to date${ver}`;
+        case "forced":
+            return `  forced reinstall${ver}`;
+        case "dry-run":
+            return `  dry-run (no changes)`;
+        case "fallback":
+            return `  wrote settings.json fallback${ver}`;
+        default:
+            return `  ${r.action}${ver}`;
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/agents/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/agents/runner.ts"],"names":[],"mappings":"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"}

package/dist/agents/spawn-helper.d.ts

@@ -0,0 +1,33 @@
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Build a single cmd.exe-safe command line from (cmd, args). Follows the
+ * canonical `CommandLineToArgvW` escaping rules so the child process sees
+ * each arg verbatim:
+ *   1. Double any run of backslashes that directly precedes a `"` or the
+ *      end of the string (so the closing `"` we add below isn't escaped).
+ *   2. Escape each embedded `"` as `\"`.
+ *   3. Wrap the whole arg in `"..."`.
+ * Naive `s.replace(/"/g, '\\"')` is wrong for args like `a\"b` or `a\\`
+ * because the preceding backslashes turn the intended escape into a real
+ * backslash + unescaped quote, breaking out of the quoted context.
+ *
+ * Chose this shape because Node 22+'s DEP0190 deprecates
+ * `spawn(cmd, args[], {shell:true})` (joining args without escaping), but
+ * `spawn(<single string>, [], {shell:true})` stays supported. Inside
+ * double quotes cmd.exe treats `&|<>^` literally, so no caret escaping is
+ * needed for our hardcoded args.
+ */
+export declare function winCommandLine(cmd: string, args: string[]): string;
+/**
+ * Spawn a command and resolve with its stdout/stderr/exit code. Unlike the
+ * shared `spawnCommand` in src/utils.ts, this helper attaches an `error`
+ * listener so that ENOENT (binary not on PATH) rejects the promise cleanly
+ * instead of crashing the process. That matters for adapters that probe for
+ * optional binaries (`copilot`, `gemini`, `codex`).
+ */
+export declare function safeSpawn(cmd: string, args?: string[]): Promise<SpawnResult>;
+//# sourceMappingURL=spawn-helper.d.ts.map

package/dist/agents/spawn-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-helper.d.ts","sourceRoot":"","sources":["../../src/agents/spawn-helper.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAQlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CA6DhF"}

package/dist/agents/spawn-helper.js

@@ -0,0 +1,98 @@
+import { spawn } from "node:child_process";
+/**
+ * Build a single cmd.exe-safe command line from (cmd, args). Follows the
+ * canonical `CommandLineToArgvW` escaping rules so the child process sees
+ * each arg verbatim:
+ *   1. Double any run of backslashes that directly precedes a `"` or the
+ *      end of the string (so the closing `"` we add below isn't escaped).
+ *   2. Escape each embedded `"` as `\"`.
+ *   3. Wrap the whole arg in `"..."`.
+ * Naive `s.replace(/"/g, '\\"')` is wrong for args like `a\"b` or `a\\`
+ * because the preceding backslashes turn the intended escape into a real
+ * backslash + unescaped quote, breaking out of the quoted context.
+ *
+ * Chose this shape because Node 22+'s DEP0190 deprecates
+ * `spawn(cmd, args[], {shell:true})` (joining args without escaping), but
+ * `spawn(<single string>, [], {shell:true})` stays supported. Inside
+ * double quotes cmd.exe treats `&|<>^` literally, so no caret escaping is
+ * needed for our hardcoded args.
+ */
+export function winCommandLine(cmd, args) {
+    const quote = (s) => {
+        const escaped = s.replace(/(\\*)("|$)/g, (_, slashes, end) => slashes + slashes + (end === '"' ? '\\"' : ""));
+        return `"${escaped}"`;
+    };
+    return [cmd, ...args].map(quote).join(" ");
+}
+/**
+ * Spawn a command and resolve with its stdout/stderr/exit code. Unlike the
+ * shared `spawnCommand` in src/utils.ts, this helper attaches an `error`
+ * listener so that ENOENT (binary not on PATH) rejects the promise cleanly
+ * instead of crashing the process. That matters for adapters that probe for
+ * optional binaries (`copilot`, `gemini`, `codex`).
+ */
+export function safeSpawn(cmd, args = []) {
+    return new Promise((resolve, reject) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (err, result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (err)
+                reject(err);
+            else
+                resolve(result);
+        };
+        try {
+            // Close the child's stdin with `ignore` so any interactive prompt in
+            // the target tool (for example, `qwen extensions install` asking for
+            // consent despite `--consent`) fails fast with EOF instead of hanging
+            // indefinitely in CI / non-TTY contexts. We capture stdout/stderr via
+            // pipes so the caller can still surface output/errors.
+            //
+            // On Windows, npm installs globally-linked binaries as `.cmd` / `.ps1`
+            // shims (so `qwen` on disk is actually `qwen.cmd`). Without
+            // `shell: true`, Node's spawn resolves only exact filenames — it can't
+            // see `.cmd` extensions and ENOENTs even when the binary works fine
+            // from PowerShell / cmd. We therefore enable the shell on win32 so
+            // cmd.exe resolves PATHEXT extensions the same way the user's
+            // terminal does. Node 22+ deprecates `spawn(cmd, args, {shell: true})`
+            // (DEP0190) because args are joined without escaping, so on win32 we
+            // instead build a single pre-quoted command line and pass it as the
+            // `cmd` argument with `shell: true`. All callers pass hardcoded
+            // strings, so shell-injection isn't a risk.
+            const onWindows = process.platform === "win32";
+            const spawnCmd = onWindows ? winCommandLine(cmd, args) : cmd;
+            const spawnArgs = onWindows ? [] : args;
+            const child = spawn(spawnCmd, spawnArgs, {
+                env: process.env,
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: onWindows,
+            });
+            child.on("error", (err) => finish(err));
+            child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+            child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+            child.on("close", (code, signal) => {
+                // `code === null` means the child was killed by a signal. Surface that
+                // as a non-zero exit code (and annotate stderr) so callers that only
+                // inspect exitCode still detect failure.
+                const exitCode = code !== null ? code : 1;
+                const signalNote = signal ? `\n[terminated by signal ${signal}]` : "";
+                finish(null, {
+                    // Strip `\r?\n` so Windows CLIs that emit CRLF don't leave a
+                    // stray `\r` in captured output (breaks log comparisons and
+                    // produces mystery `^M` glyphs in terminal output).
+                    stdout: stdout.replace(/\r?\n$/, ""),
+                    stderr: (stderr + signalNote).replace(/\r?\n$/, ""),
+                    exitCode,
+                });
+            });
+        }
+        catch (err) {
+            finish(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+//# sourceMappingURL=spawn-helper.js.map

package/dist/agents/spawn-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-helper.js","sourceRoot":"","sources":["../../src/agents/spawn-helper.ts"],"names":[],"mappings":"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"}

package/dist/agents/types.d.ts

@@ -0,0 +1,41 @@
+export type Scope = "global" | "project";
+export interface DetectionResult {
+    present: boolean;
+    onPath: boolean;
+    version?: string;
+    configPaths: {
+        global?: string;
+        project?: string;
+    };
+    notes?: string[];
+}
+export interface InstallState {
+    installed: boolean;
+    installedVersion?: string;
+    latestVersion?: string;
+    upToDate?: boolean;
+}
+export type LogLevel = "info" | "warn" | "error" | "debug";
+export interface InstallOptions {
+    scope: Scope;
+    force: boolean;
+    dryRun: boolean;
+    logger: (message: string, level?: LogLevel) => void;
+}
+export type InstallAction = "installed" | "updated" | "already-up-to-date" | "forced" | "dry-run" | "fallback";
+export interface InstallReport {
+    adapterId: string;
+    scope: Scope;
+    action: InstallAction;
+    installedVersion?: string;
+    notes?: string[];
+}
+export interface AgentAdapter {
+    id: string;
+    displayName: string;
+    detect(): Promise<DetectionResult>;
+    supportsScopes(): Scope[];
+    getInstallState(scope: Scope): Promise<InstallState>;
+    install(opts: InstallOptions): Promise<InstallReport>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,SAAS,GACT,oBAAoB,GACpB,QAAQ,GACR,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACnC,cAAc,IAAI,KAAK,EAAE,CAAC;IAC1B,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACvD"}

package/dist/agents/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -1,22 +1,53 @@
 import { runTests } from "./core/index.js";
-import { setArgs, setConfig, outputResults, setMeta, getVersionData, log, getResolvedTestsFromEnv, reportResults, } from "./utils.js";
-import { argv } from "node:process";
+import { buildYargs, setConfig, outputResults, setMeta, getVersionData, log, getResolvedTestsFromEnv, reportResults, } from "./utils.js";
+import { installAgentsCommand } from "./agents/command.js";
+import { argv as processArgv } from "node:process";
 import path from "node:path";
 import fs from "node:fs";
 // Run
 setMeta();
-main(argv);
-// Run
+main(processArgv).catch((err) => {
+    // yargs' .fail handler prints usage + message; this catches anything that
+    // escapes (including our rethrown errors) so the process exits non-zero.
+    console.error(err?.message || err);
+    process.exit(1);
+});
 async function main(argv) {
-    // Find index of `doc-detective` or `run` in argv
-    const index = argv.findIndex((arg) => arg.endsWith("doc-detective") || arg.endsWith("index.js"));
-    // Set args
-    const args = setArgs(argv);
+    await buildYargs(argv)
+        .command({
+        command: "$0",
+        describe: "Run Doc Detective tests (default).",
+        handler: runTestsHandler,
+    })
+        .command({
+        // Preserved for back-compat with the `runTests` npm script and any
+        // existing CI invocations. Runs the same handler as the default.
+        command: "runTests",
+        describe: false,
+        handler: runTestsHandler,
+    })
+        .command(installAgentsCommand)
+        .strict()
+        .demandCommand(0)
+        // Suppress yargs' default help-dump on failure; surface the concrete error
+        // message instead. The top-level .catch() prints it and sets exit code.
+        .fail((msg, err) => {
+        if (err)
+            throw err;
+        throw new Error(msg);
+    })
+        .parseAsync();
+}
+// Legacy "run tests" flow — unchanged behavior when no subcommand is given.
+async function runTestsHandler(args) {
     // Get .doc-detective JSON or YAML config, if it exists, preferring a config arg if provided
     const configPathJSON = path.resolve(process.cwd(), ".doc-detective.json");
     const configPathYAML = path.resolve(process.cwd(), ".doc-detective.yaml");
     const configPathYML = path.resolve(process.cwd(), ".doc-detective.yml");
-    const configPath = fs.existsSync(args.config)
+    // Guard `args.config` so the handler falls back to the defaults cleanly
+    // when --config is omitted (args.config is undefined in that case).
+    const hasExplicitConfig = typeof args.config === "string" && args.config.length > 0 && fs.existsSync(args.config);
+    const configPath = hasExplicitConfig
         ? args.config
         : fs.existsSync(configPathJSON)
             ? configPathJSON
@@ -42,7 +73,8 @@ async function main(argv) {
         await reportResults({ apiConfig, results });
     }
     else {
-        // Output results
+        // Output results — config.reporters (populated from args.reporters by
+        // setConfig) is the source of truth for which reporters run.
         await outputResults(config, output, results, { command: "runTests" });
     }
 }

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/common/src/detectTests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detectTests.d.ts","sourceRoot":"","sources":["../../../src/common/src/detectTests.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAA+C,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAoCvF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAe3F;AAED,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAOlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAoEnH;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,iBAAiB,EAAE,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAkD5G;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CA2DrC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAW,EACX,OAAO,EACP,QAAa,EACb,QAAQ,GACT,EAAE;IACD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAqU1B;AAsBD;;GAEG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,CAqBhF"}
+{"version":3,"file":"detectTests.d.ts","sourceRoot":"","sources":["../../../src/common/src/detectTests.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAA+C,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAoCvF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAe3F;AAED,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAOlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAoEnH;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,iBAAiB,EAAE,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAgE5G;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CA2DrC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAW,EACX,OAAO,EACP,QAAa,EACb,QAAQ,GACT,EAAE;IACD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmU1B;AAkDD;;GAEG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,CAqBhF"}

package/dist/common/src/detectTests.js

@@ -183,6 +183,19 @@ export function parseXmlAttributes({ stringifiedObject }) {
  */
 export function parseObject({ stringifiedObject }) {
     if (typeof stringifiedObject === "string") {
+        // Decode XML/HTML entities (e.g., " → " and ' → ') that may be
+        // introduced by DITA OT or other XML processors when normalizing attribute
+        // values. & must be decoded last so author-escaped sequences like
+        // "<" (meant to render as the literal text "<") aren't double-decoded
+        // into "<".
+        if (/&(?:#\d+|#x[0-9a-fA-F]+|amp|lt|gt|quot|apos);/.test(stringifiedObject)) {
+            stringifiedObject = stringifiedObject
+                .replace(/&#39;|&apos;/g, "'")
+                .replace(/&#34;|&quot;/g, '"')
+                .replace(/&lt;/g, "<")
+                .replace(/&gt;/g, ">")
+                .replace(/&amp;/g, "&");
+        }
         // First, try to parse as XML attributes
         const xmlAttrs = parseXmlAttributes({ stringifiedObject });
         if (xmlAttrs !== null) {
@@ -488,18 +501,7 @@ export async function parseContent({ config = {}, content, filePath = "", fileTy
                             if (step.screenshot && config._herettoPathMapping) {
                                 const herettoIntegration = findHerettoIntegration(config, filePath);
                                 if (herettoIntegration) {
-                                    if (typeof step.screenshot === "string") {
-                                        step.screenshot = { path: step.screenshot };
-                                    }
-                                    else if (typeof step.screenshot === "boolean") {
-                                        step.screenshot = {};
-                                    }
-                                    step.screenshot.sourceIntegration = {
-                                        type: "heretto",
-                                        integrationName: herettoIntegration,
-                                        filePath: step.screenshot.path || "",
-                                        contentPath: filePath,
-                                    };
+                                    attachHerettoScreenshotSourceIntegration(step, herettoIntegration, filePath);
                                 }
                             }
                         }
@@ -576,6 +578,13 @@ export async function parseContent({ config = {}, content, filePath = "", fileTy
                         endIndex: statement._endIndex,
                     };
                 }
+                // Attach sourceIntegration for Heretto on screenshot steps
+                if (step.screenshot && config._herettoPathMapping) {
+                    const herettoIntegration = findHerettoIntegration(config, filePath);
+                    if (herettoIntegration) {
+                        attachHerettoScreenshotSourceIntegration(step, herettoIntegration, filePath);
+                    }
+                }
                 const validation = validate({
                     schemaKey: "step_v3",
                     object: step,
@@ -618,6 +627,28 @@ export async function parseContent({ config = {}, content, filePath = "", fileTy
     });
     return validatedTests;
 }
+/**
+ * Attaches a Heretto sourceIntegration descriptor to a screenshot step in place.
+ * Normalizes non-object screenshot values (string paths, booleans, other primitives)
+ * to an object shape before assigning sourceIntegration so downstream validation
+ * has a predictable structure to reject or accept.
+ */
+function attachHerettoScreenshotSourceIntegration(step, integrationName, contentPath) {
+    if (typeof step.screenshot === "string") {
+        step.screenshot = { path: step.screenshot };
+    }
+    else if (step.screenshot === null ||
+        typeof step.screenshot !== "object" ||
+        Array.isArray(step.screenshot)) {
+        step.screenshot = {};
+    }
+    step.screenshot.sourceIntegration = {
+        type: "heretto",
+        integrationName,
+        filePath: step.screenshot.path || "",
+        contentPath,
+    };
+}
 /**
  * Helper function to find which Heretto integration a file belongs to.
  */