@orkastery/cli 0.5.6 → 0.6.1

package/dist/security-scan/report.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportDir = reportDir;
+exports.writeReport = writeReport;
+exports.readReport = readReport;
+exports.isExcusedUnscanned = isExcusedUnscanned;
+exports.unscannedLoopTools = unscannedLoopTools;
+exports.exitCodeOf = exitCodeOf;
+exports.tally = tally;
+exports.renderMarkdown = renderMarkdown;
+/**
+ * The report of a scan round (spec section 5.4) and the exit code (section 5.5). The files live under
+ * `<state>/security-scan/<head-sha>/` of the main tree, so a scan inside a thread worktree and `ork ship` read the same
+ * place. A finding carries no snippet (see `Finding`), and nothing here prints raw tool output: no secret value reaches
+ * `report.json` or `report.md`.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const locale_1 = require("../locale");
+const manifest_1 = require("../manifest");
+const types_1 = require("./types");
+function reportDir(stateRoot, sha) {
+    return path.join((0, manifest_1.dirEstado)(stateRoot), 'security-scan', sha);
+}
+function atomicWrite(file, content) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, content, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function writeReport(stateRoot, report) {
+    const dir = reportDir(stateRoot, report.head);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const json = path.join(dir, 'report.json');
+    const md = path.join(dir, 'report.md');
+    atomicWrite(json, `${JSON.stringify(report, null, 2)}\n`);
+    atomicWrite(md, renderMarkdown(report));
+    return { json, md };
+}
+/** The stored report of `sha`, or null when absent or not a report of this schema. */
+function readReport(stateRoot, sha) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(reportDir(stateRoot, sha), 'report.json'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const r = JSON.parse(raw);
+        return r && r.schema === 'ork.security-scan/v1' && Array.isArray(r.tools) && Array.isArray(r.findings) ? r : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * "Nothing this tool can scan", declared in the report but not counted as an unscanned loop category: `unsupported-ci`
+ * (a GitLab CI file and no GitHub workflow: no analyzer for it, a known product gap) and `no-requirements-file`
+ * (pip-audit without `requirements*.txt`) when another tool of the same category ran in the round. Counted, either one
+ * would keep every such project red under REQUIRED and every ship asking for authorization.
+ */
+function isExcusedUnscanned(tool, tools) {
+    if (tool.state !== 'unavailable')
+        return false;
+    if (tool.reason === 'unsupported-ci')
+        return true;
+    if (tool.reason === 'no-requirements-file')
+        return tools.some(o => o !== tool && o.category === tool.category && o.state === 'ran');
+    return false;
+}
+/** Loop-category tools that did not run and are not excused (`isExcusedUnscanned`): the single rule of exit code and ship gate. */
+function unscannedLoopTools(report) {
+    return report.tools.filter(t => t.state !== 'ran' && types_1.LOOP_CATEGORIES.includes(t.category) && !isExcusedUnscanned(t, report.tools));
+}
+/**
+ * 1 when a `new` finding is in the loop, or when `required` and a tool of a loop category (secret, dependency, sast, iac,
+ * workflow) is unavailable or failed (never clean), unless excused by `isExcusedUnscanned`; `quality` and `license`
+ * tools never drive the code. Invalid dismissals or config never reach a report: the command fails before.
+ */
+function exitCodeOf(report, required) {
+    if (report.findings.some(f => f.status === 'new' && f.loop))
+        return 1;
+    if (required && unscannedLoopTools(report).length > 0)
+        return 1;
+    return 0;
+}
+function tally(report) {
+    const t = { new: 0, existing: 0, dismissed: 0, loop: 0 };
+    for (const f of report.findings) {
+        t[f.status]++;
+        if (f.status === 'new' && f.loop)
+            t.loop++;
+    }
+    return t;
+}
+const cell = (s) => s.replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
+const bySeverity = (a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity) || a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0);
+function findingLine(f) {
+    const where = f.line === undefined ? f.file : `${f.file}:${f.line}`;
+    return `- \`${f.severity}\` ${f.tool} \`${f.rule}\` ${where}: ${f.message.replace(/[\r\n]+/g, ' ')} (\`${f.fingerprint}\`)`;
+}
+function renderMarkdown(report) {
+    const m = (0, locale_1.msg)().securityScan;
+    const t = tally(report);
+    const out = [`# ${m.title}`, '', m.headBase(report.head, report.base), '', m.generatedAt(report.generatedAt), '',
+        m.stacks(report.stacks.length ? report.stacks.join(', ') : m.noStacks), '', `## ${m.executionHeading}`, ''];
+    if (report.tools.length === 0)
+        out.push(m.noTools);
+    else {
+        out.push(`| ${m.tableTool} | ${m.tableExecutor} | ${m.tableState} | ${m.tableReason} |`, '| --- | --- | --- | --- |');
+        for (const r of report.tools) {
+            out.push(`| ${cell(r.name)} | ${r.executor ?? m.noExecutor} | ${m.states[r.state] ?? r.state} | ${cell(r.reason ?? '')} |`);
+        }
+    }
+    const news = report.findings.filter(f => f.status === 'new');
+    const loop = news.filter(f => f.loop).sort(bySeverity);
+    const warn = news.filter(f => !f.loop).sort(bySeverity);
+    out.push('', `## ${m.countsHeading}`, '', m.counts(t.new, t.existing, t.dismissed, t.loop), '', `## ${m.newLoopHeading}`, '', ...(loop.length ? loop.map(findingLine) : [m.none]), '', `## ${m.newWarnHeading}`, '', ...(warn.length ? warn.map(findingLine) : [m.none]), '', m.existingTotal(t.existing), '', m.dismissedTotal(t.dismissed));
+    if (report.excluded.length)
+        out.push('', `## ${m.excludedHeading}`, '', ...report.excluded.map(e => `- ${e}`));
+    return `${out.join('\n')}\n`;
+}

package/dist/security-scan/run.js

@@ -0,0 +1,448 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failedAll = exports.SCAN_CACHE_VERSION = exports.defaultProbe = exports.chooseExecutor = void 0;
+exports.git = git;
+exports.emptyCounts = emptyCounts;
+exports.resolveBase = resolveBase;
+exports.stackPairs = stackPairs;
+exports.unitsOf = unitsOf;
+exports.commitsScanned = commitsScanned;
+exports.checkout = checkout;
+exports.cacheRoot = cacheRoot;
+exports.scanTool = scanTool;
+exports.runScan = runScan;
+/**
+ * The scan round of `ork security-scan` (spec section 5.2): resolve the base, detect the stacks of the HEAD tree, run
+ * every applicable catalog tool on the HEAD tree and on the base (a temporary detached worktree, or the cache), make
+ * each output a list of RawFinding, and classify HEAD against the base. Reports are written by Task 8 (report.ts).
+ *
+ * Rules that hold for every tool:
+ * - `unavailable` and `failed` contribute no finding and are never clean: their counts are zero and the state says why.
+ * - A tool runs once per detected (stack, dir) when its command uses {stackDir} (or has `argsByStack`), else once at
+ *   the root. The per-pair outcomes combine as failed > unavailable > ran.
+ * - The base is the `--base` ref, else `git merge-base HEAD <remote>/<worktree.base_branch>`, else the merge-base with
+ *   the local branch; unresolved, every tool is `failed`/`base-unresolved`. Base equal to HEAD is valid: the HEAD
+ *   results are the base ones and every finding is `existing` (the baseline of a project adopting the scan).
+ * - Gitleaks: HEAD = mergeByFingerprint(dir scan of the HEAD tree, git scan of base..HEAD); base = dir scan of the base
+ *   tree. The git scan of a linked worktree mounts the main `.git` (read-only, at its own path) so that the worktree's
+ *   `.git` file resolves in the container; base..HEAD with commits and "0 commits scanned" is `zero-commits-scanned`.
+ * - The base results are cached as normalized RawFindings (never raw output) in
+ *   `$XDG_CACHE_HOME/orkastery/security-scan/<base-sha>/<tool>-<id>[-<stack>-<dir>].json`, keyed by the whole ToolSpec,
+ *   the resolved tool config content and SCAN_CACHE_VERSION.
+ * - HEAD is scanned from a detached worktree of the HEAD commit, like the base: only committed content is scanned
+ *   (uncommitted or ignored files, node_modules, .env, are not), and `.ork-security/` is read from that tree. The report
+ *   carries the HEAD sha, which is what `ork verify` and `ork ship` prove. A scan started from a subdirectory scans the
+ *   repository (`git rev-parse --show-toplevel`).
+ * - `deadlineMs` bounds the whole round: each process gets the tool `timeoutMs` capped by the time left, and once it is
+ *   spent the remaining units are `failed`/`timeout` without running. A round killed by a signal is cleaned up by the
+ *   reaper of guard.ts (worktrees, raw output dirs, the running container, the native process group).
+ * - A failure on the base side carries the `base-` prefix (`base-timeout`, `base-exit-2: ...`).
+ * - Errors the catalog tolerates (`expect.tolerate`: Semgrep warn-level Timeout and PartialParsing) leave the tool
+ *   `ran` with the HEAD reason `partial-timeout: <n>` / `partial-parsing: <n>`; the findings obtained count.
+ */
+const node_child_process_1 = require("node:child_process");
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const estado_thread_1 = require("../estado-thread");
+const manifest_1 = require("../manifest");
+const compare_1 = require("./compare");
+const config_1 = require("./config");
+const detect_1 = require("./detect");
+const executor_1 = require("./executor");
+const guard_1 = require("./guard");
+const normalize_1 = require("./normalize");
+const tools_1 = require("./tools");
+var executor_2 = require("./executor");
+Object.defineProperty(exports, "chooseExecutor", { enumerable: true, get: function () { return executor_2.chooseExecutor; } });
+Object.defineProperty(exports, "defaultProbe", { enumerable: true, get: function () { return executor_2.defaultProbe; } });
+/** Version of the normalized cache content; bump when a normalizer or the RawFinding shape changes. */
+exports.SCAN_CACHE_VERSION = 1;
+const STATUSES = ['new', 'existing', 'dismissed'];
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+const GIT_TIMEOUT_MS = 60000;
+function git(cwd, args) {
+    const r = (0, node_child_process_1.spawnSync)('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+    return r.error || r.status !== 0 ? null : r.stdout.trim();
+}
+function emptyCounts() {
+    return Object.fromEntries(STATUSES.map(s => [s, Object.fromEntries(SEVERITIES.map(v => [v, 0]))]));
+}
+/** Base sha: `--base`, else merge-base with `<remote>/<base_branch>`, else with the local branch; null when unresolved. */
+function resolveBase(root, stateRoot, ref) {
+    const commit = (r) => git(root, ['rev-parse', '--verify', '--quiet', `${r}^{commit}`]);
+    if (ref !== undefined)
+        return commit(ref);
+    let branch = 'main';
+    let remote = 'origin';
+    try {
+        const m = (0, manifest_1.carregarManifesto)(stateRoot) ?? (0, manifest_1.carregarManifesto)(root);
+        if (m) {
+            branch = m.manifesto.worktree.base_branch || branch;
+            remote = m.manifesto.fabrica.remoto || remote;
+        }
+    }
+    catch { /* an invalid manifest leaves the defaults; `ork verify` reports it on its own */ }
+    for (const target of [`${remote}/${branch}`, branch]) {
+        if (!commit(target))
+            continue;
+        const mb = git(root, ['merge-base', 'HEAD', target]);
+        if (mb)
+            return mb;
+    }
+    return null;
+}
+/** Detected (stack, dir) pairs adjusted by `config.stacks`: `remove` drops a stack, `add` forces it at the root. */
+function stackPairs(root, config) {
+    const pairs = (0, detect_1.detectStacks)(root).filter(p => !config.stacks.remove.includes(p.stack));
+    for (const s of config.stacks.add)
+        if (!pairs.some(p => p.stack === s))
+            pairs.push({ stack: s, dir: '.', forced: true });
+    return pairs;
+}
+const usesStackDir = (t) => !!t.argsByStack || t.args.some(a => a.includes('{stackDir}'));
+const argvFor = (t, stack) => (stack && t.argsByStack?.[stack]) || t.args;
+function unitsOf(t, pairs) {
+    if (!usesStackDir(t))
+        return [{ dir: '.' }];
+    return pairs.filter(p => (t.stacks === 'all' || t.stacks.includes(p.stack)) && argvFor(t, p.stack).length > 0)
+        .map(p => ({ stack: p.stack, dir: p.dir, ...(p.forced ? { forced: true } : {}) }));
+}
+const hasWorkflows = (tree) => {
+    const dir = path.join(tree, '.github', 'workflows');
+    try {
+        return fs.readdirSync(dir).some(f => /\.ya?ml$/.test(f));
+    }
+    catch {
+        return false;
+    }
+};
+/** The report files one argv produces: those named in it as `{out}/<file>`, or the `stdoutFile`. */
+const filesOf = (t, argv) => t.expect.files.filter(f => argv.some(a => a.includes(`{out}/${f}`)) || t.stdoutFile === f);
+const firstLine = (text) => (text.split('\n').find(l => l.trim()) ?? '').trim().slice(0, 200);
+/** The last non-empty stderr line: wrappers print install noise first and the fatal message last. */
+const lastLine = (text) => (text.split('\n').filter(l => l.trim()).pop() ?? '').trim().slice(0, 200);
+const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/** Commits Gitleaks says it read ("N commits scanned."); null when the line is absent. */
+function commitsScanned(stderr) {
+    const m = /(\d+) commits? scanned/.exec(stripAnsi(stderr));
+    return m ? Number(m[1]) : null;
+}
+/** A detached worktree of `sha` from the main repository, registered in the guard (removed by `guard.close()`). */
+function checkout(mainRoot, sha, guard) {
+    const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ork-security-scan-tree-')));
+    const tree = path.join(tmp, 'tree');
+    guard.add('worktrees', tree);
+    const r = (0, node_child_process_1.spawnSync)('git', ['worktree', 'add', '--detach', tree, sha], { cwd: mainRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS * 5 });
+    if (r.error || r.status !== 0)
+        throw Error(`worktree-failed: ${firstLine(r.stderr ?? '')}`);
+    return tree;
+}
+function cacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    return path.join(xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), '.cache'), 'orkastery', 'security-scan');
+}
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+const slug = (dir) => (dir === '.' ? 'root' : dir.replace(/[^A-Za-z0-9._-]/g, '_'));
+const remaining = (ctx) => ctx.deadline - Date.now();
+/**
+ * Whether base..HEAD has any patch content for Gitleaks to read. A range of merges without conflict resolution, empty
+ * commits or pure renames has none, and Gitleaks then reports 0 commits scanned with nothing skipped. A git error
+ * (including output too large for the buffer) counts as content: the strict reading keeps `zero-commits-scanned`.
+ */
+function rangeHasPatch(ctx) {
+    if (ctx.rangePatch === undefined) {
+        const out = git(ctx.mainRoot, ['log', '-p', '--format=', `${ctx.base}..${ctx.head}`]);
+        ctx.rangePatch = out === null || out !== '';
+    }
+    return ctx.rangePatch;
+}
+/** Host path of the tool config: the project's `.ork-security/<file>` in the HEAD tree, else the embedded default. */
+function configOf(t, ctx) {
+    const name = executor_1.CONFIG_FILES[t.name];
+    if (!name)
+        return undefined;
+    const project = path.join(ctx.headTree, '.ork-security', name);
+    return fs.existsSync(project) ? project : path.join((0, executor_1.defaultsDir)(), name);
+}
+/** The scan of one tool on one tree for one unit; `extra` adds the `extraArgs` (Gitleaks git scan, HEAD only). */
+function scanTree(t, executor, tree, unit, ctx, extra) {
+    const fail = (kind, reason) => ({ outcome: { kind, reason }, lists: [] });
+    const configHost = configOf(t, ctx);
+    const rangeArgs = extra ? t.extraArgs ?? [] : [];
+    if (rangeArgs.length && ctx.rangeCommits === null)
+        return fail('failed', 'commit-range-unresolved');
+    const argvs = [argvFor(t, unit.stack), ...(ctx.rangeCommits ? rangeArgs : [])];
+    const lists = [];
+    const partial = [];
+    for (const argv of argvs) {
+        const timeoutMs = Math.min(t.timeoutMs, remaining(ctx));
+        if (timeoutMs <= 0)
+            return fail('failed', 'timeout');
+        const isGitScan = argv !== argvs[0] && t.baseMode === 'commit-range';
+        const out = fs.mkdtempSync(path.join(os.tmpdir(), 'ork-security-scan-out-'));
+        ctx.guard.add('outDirs', out);
+        try {
+            const inv = {
+                tool: t, argv, srcHost: tree, outHost: out, base: ctx.base, stackDir: unit.dir, configHost, timeoutMs, guard: ctx.guard,
+                // The tree is a linked worktree: its `.git` file points into the main `.git`, mounted at its own path.
+                sameMounts: isGitScan ? [path.join(ctx.mainRoot, '.git')] : [],
+            };
+            const r = executor === 'docker' ? (0, executor_1.runDocker)(inv) : (0, executor_1.runNative)(inv);
+            if (r.timedOut)
+                return fail('failed', 'timeout');
+            // actionlint exits 4 when there is no workflow to read (the HEAD precheck already caught .gitlab-ci.yml).
+            if (r.status === 4 && t.category === 'workflow') {
+                lists.push([]);
+                continue;
+            }
+            if (r.status === 3 && /no-requirements-file/.test(r.stderr))
+                return fail('unavailable', 'no-requirements-file');
+            if (r.status !== 0) {
+                // A secret scanner's stderr is never quoted: it could carry the value.
+                const detail = t.category === 'secret' ? '' : lastLine(stripAnsi(r.stderr));
+                return fail('failed', `exit-${r.status ?? 'signal'}${detail ? `: ${detail}` : ''}`);
+            }
+            if (isGitScan && !commitsScanned(r.stderr) && rangeHasPatch(ctx))
+                return fail('failed', 'zero-commits-scanned');
+            if (t.stdoutFile)
+                fs.writeFileSync(path.join(out, t.stdoutFile), r.stdout, { mode: 0o600 });
+            const findings = [];
+            for (const file of filesOf(t, argv)) {
+                const f = path.join(out, file);
+                if (!fs.existsSync(f))
+                    return fail('failed', `missing-output: ${file}`);
+                const nctx = { root: executor === 'docker' ? '/src' : tree, stackDir: unit.dir };
+                try {
+                    const content = fs.readFileSync(f, 'utf8');
+                    findings.push(...normalize_1.NORMALIZERS[t.name](content, nctx));
+                    const p = (0, normalize_1.partialOf)(t.name, content);
+                    if (p)
+                        partial.push(p);
+                }
+                catch (e) {
+                    const msg = e.message;
+                    return fail('failed', msg.startsWith('security-scan.parse') || t.category !== 'secret' ? msg : 'security-scan.parse: unreadable output');
+                }
+            }
+            lists.push(findings);
+        }
+        finally {
+            // The raw output (Gitleaks keeps the secret value) never outlives the run.
+            fs.rmSync(out, { recursive: true, force: true });
+            ctx.guard.remove('outDirs', out);
+        }
+    }
+    const findings = lists.length > 1 ? (0, compare_1.mergeByFingerprint)(lists) : lists.flat();
+    return { outcome: { kind: 'ran', findings, ...(partial.length ? { reason: partial.join('; ') } : {}) }, lists };
+}
+/** Base findings of one unit: cache, else the base worktree; "nothing to scan" on the base is an empty list. */
+function scanBase(t, executor, unit, ctx, headMain) {
+    if (ctx.base === ctx.head)
+        return { kind: 'ran', findings: headMain };
+    const nativeVersion = executor === 'native' ? (0, executor_1.nativeVersionOf)(t, ctx.probe) : '';
+    const id = executor === 'docker' ? (t.image.split('@sha256:')[1] ?? sha256(t.image)).slice(0, 12) : sha256(nativeVersion).slice(0, 12);
+    const file = path.join(cacheRoot(), ctx.base, `${t.name}-${id}${unit.stack ? `-${unit.stack}-${slug(unit.dir)}` : ''}.json`);
+    const configHost = configOf(t, ctx);
+    const key = sha256(JSON.stringify({ version: exports.SCAN_CACHE_VERSION, tool: t, executor, nativeVersion, unit,
+        config: configHost ? fs.readFileSync(configHost, 'utf8') : null }));
+    try {
+        const cached = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (cached.key === key && Array.isArray(cached.findings))
+            return { kind: 'ran', findings: cached.findings };
+    }
+    catch { /* absent or unreadable: scan again */ }
+    ctx.baseTree ??= checkout(ctx.mainRoot, ctx.base, ctx.guard);
+    const tree = ctx.baseTree;
+    if (unit.dir !== '.' && !fs.existsSync(path.join(tree, unit.dir)))
+        return { kind: 'ran', findings: [] };
+    if (t.category === 'workflow' && !hasWorkflows(tree))
+        return { kind: 'ran', findings: [] };
+    // A detected stack whose manifest is absent from the base at that dir (a project adopting it, or moving it, in this
+    // change): nothing to scan on the base, not a failure. A stack forced by `config.stacks.add` has no manifest by design
+    // and is always scanned. A manifest moved from `a/` to `b/` leaves `b/` empty on the base, so its findings are `new`.
+    if (unit.stack && !unit.forced && !(0, detect_1.hasStackManifest)(tree, unit.stack, unit.dir))
+        return { kind: 'ran', findings: [] };
+    const { outcome } = scanTree(t, executor, tree, unit, ctx, false);
+    if (outcome.kind === 'unavailable')
+        return { kind: 'ran', findings: [] };
+    if (outcome.kind === 'ran') {
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(file, JSON.stringify({ key, findings: outcome.findings }), { mode: 0o600 });
+        }
+        catch { /* a cache that cannot be written only costs time */ }
+    }
+    return outcome;
+}
+const DOCKER_OFF = (p) => ({ ...p, dockerCli: () => false, dockerDaemon: () => false });
+function scanTool(t, units, config, ctx) {
+    const result = (state, executor, reason, head = [], base = []) => ({
+        run: { name: t.name, category: t.category, version: executor === 'native' ? (0, executor_1.nativeVersionOf)(t, ctx.probe) : t.version, executor, state, ...(reason ? { reason } : {}), counts: emptyCounts() },
+        head, base,
+    });
+    if (config.tools[t.name]?.disabled)
+        return result('unavailable', null, 'disabled');
+    const choice = (0, executor_1.chooseExecutor)(t, ctx.probe);
+    if (choice.kind === 'unavailable')
+        return result('unavailable', null, choice.reason);
+    let executor = choice.kind;
+    if (executor === 'docker') {
+        if (!ctx.images.has(t.image))
+            ctx.images.set(t.image, (0, executor_1.ensureImage)(t.image, Math.min(t.timeoutMs, remaining(ctx))));
+        if (!ctx.images.get(t.image)) {
+            // Docker -> native -> unavailable (spec 5.2.1): an image that cannot be pulled falls back to the native binary.
+            const native = (0, executor_1.chooseExecutor)(t, DOCKER_OFF(ctx.probe));
+            if (native.kind !== 'native') {
+                return result(remaining(ctx) <= 0 ? 'failed' : 'unavailable', null, remaining(ctx) <= 0 ? 'timeout' : 'image-pull-failed');
+            }
+            executor = 'native';
+        }
+    }
+    if (t.category === 'workflow' && !hasWorkflows(ctx.headTree)) {
+        if (fs.existsSync(path.join(ctx.headTree, '.gitlab-ci.yml')))
+            return result('unavailable', executor, 'unsupported-ci');
+        return result('ran', executor); // no CI workflow at all: nothing to scan, nothing found
+    }
+    const outcomes = [];
+    const head = [];
+    const base = [];
+    const partial = [];
+    for (const unit of units) {
+        const h = scanTree(t, executor, ctx.headTree, unit, ctx, true);
+        if (h.outcome.kind !== 'ran') {
+            outcomes.push(h.outcome);
+            continue;
+        }
+        let b;
+        try {
+            b = scanBase(t, executor, unit, ctx, h.lists[0] ?? []);
+        }
+        catch (e) {
+            b = { kind: 'failed', reason: firstLine(e.message) };
+        }
+        if (b.kind === 'ran') {
+            outcomes.push(h.outcome);
+            head.push(...h.outcome.findings);
+            base.push(...b.findings);
+            // Partial coverage of the HEAD scan is reported; on the base it only makes HEAD findings `new` (stricter).
+            if (h.outcome.reason)
+                partial.push(h.outcome.reason);
+        }
+        else
+            outcomes.push({ kind: b.kind, reason: `base-${b.reason}` });
+    }
+    const worst = outcomes.find(o => o.kind === 'failed') ?? outcomes.find(o => o.kind === 'unavailable');
+    if (worst && worst.kind !== 'ran')
+        return result(worst.kind, executor, worst.reason);
+    return result('ran', executor, partial.join('; ') || undefined, head, base);
+}
+const failedAll = (tools, config, reason) => tools.map(t => ({
+    name: t.name, category: t.category, version: t.version, executor: null,
+    state: config.tools[t.name]?.disabled ? 'unavailable' : 'failed', reason: config.tools[t.name]?.disabled ? 'disabled' : reason, counts: emptyCounts(),
+}));
+exports.failedAll = failedAll;
+function runScan(opts) {
+    const start = path.resolve(opts.root);
+    const root = git(start, ['rev-parse', '--show-toplevel']) ?? start;
+    const generatedAt = (opts.now ?? (() => new Date()))().toISOString();
+    const head = git(root, ['rev-parse', 'HEAD']) ?? '';
+    let mainRoot = root;
+    try {
+        mainRoot = (0, estado_thread_1.raizDoEstado)(root);
+    }
+    catch { /* not a linked worktree git understands: use the root itself */ }
+    const report = { schema: 'ork.security-scan/v1', base: '', head, generatedAt, stacks: [], tools: [], excluded: [], findings: [] };
+    const catalog = opts.tools ?? (0, tools_1.loadTools)();
+    if (!head) {
+        // No commit to scan: nothing is checked out; stacks and config come from the directory as it is.
+        const config = (0, config_1.loadConfig)(root);
+        const pairs = stackPairs(root, config);
+        report.stacks = [...new Set(pairs.map(p => p.stack))];
+        report.tools = (0, exports.failedAll)((0, tools_1.toolsFor)(report.stacks, catalog).filter(t => unitsOf(t, pairs).length > 0), config, 'base-unresolved');
+        return report;
+    }
+    const guard = new guard_1.RoundGuard(mainRoot);
+    try {
+        let headTree;
+        try {
+            headTree = checkout(mainRoot, head, guard);
+        }
+        catch (e) {
+            const config = (0, config_1.loadConfig)(root);
+            const pairs = stackPairs(root, config);
+            report.stacks = [...new Set(pairs.map(p => p.stack))];
+            report.tools = (0, exports.failedAll)((0, tools_1.toolsFor)(report.stacks, catalog).filter(t => unitsOf(t, pairs).length > 0), config, `head-${firstLine(e.message)}`);
+            return report;
+        }
+        const config = (0, config_1.loadConfig)(headTree);
+        const dismissals = (0, config_1.loadDismissals)(headTree);
+        const pairs = stackPairs(headTree, config);
+        report.stacks = [...new Set(pairs.map(p => p.stack))];
+        const tools = (0, tools_1.toolsFor)(report.stacks, catalog).filter(t => unitsOf(t, pairs).length > 0);
+        const base = resolveBase(root, path.resolve(opts.stateRoot), opts.base);
+        if (!base) {
+            report.tools = (0, exports.failedAll)(tools, config, 'base-unresolved');
+            return report;
+        }
+        report.base = base;
+        const count = git(root, ['rev-list', '--count', `${base}..${head}`]);
+        const ctx = {
+            headTree, mainRoot, base, head, rangeCommits: count === null ? null : Number(count),
+            probe: opts.probe ?? (0, executor_1.defaultProbe)(), guard, images: new Map(),
+            deadline: opts.deadlineMs === undefined ? Infinity : Date.now() + opts.deadlineMs,
+            baseTree: base === head ? headTree : undefined,
+        };
+        const excluded = new Set();
+        for (const t of tools) {
+            const r = scanTool(t, unitsOf(t, pairs), config, ctx);
+            if (r.run.state === 'ran') {
+                const c = (0, compare_1.classify)(r.head, r.base, dismissals, config.exclude);
+                for (const f of c.findings)
+                    r.run.counts[f.status][f.severity]++;
+                report.findings.push(...c.findings);
+                c.excluded.forEach(e => excluded.add(e));
+            }
+            report.tools.push(r.run);
+        }
+        report.excluded = [...excluded].sort();
+        return report;
+    }
+    finally {
+        guard.close();
+    }
+}

package/dist/security-scan/tools.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTools = loadTools;
+exports.loadAgileTools = loadAgileTools;
+exports.toolsFor = toolsFor;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Catalog location: dist/security-scan (and the package) or dist-test/src/security-scan (tests), the same two-level lookup the other readers use. */
+function catalogFile() {
+    const file = [path.join(__dirname, '..', '..', 'assets', 'security-scan', 'tools.json'),
+        path.join(__dirname, '..', '..', '..', 'assets', 'security-scan', 'tools.json')].find(fs.existsSync);
+    if (!file)
+        throw Error('security-scan.catalog.unavailable');
+    return file;
+}
+function loadTools() {
+    return JSON.parse(fs.readFileSync(catalogFile(), 'utf8'));
+}
+/**
+ * RM-072 (D13): o catalogo so do Agile Check (`tools-agil.json`, ao lado do `tools.json`): `osv-scanner` e `oxlint`,
+ * atras de `check.agile.osv_scanner` e `check.agile.oxlint`. O Classic nunca le este arquivo.
+ */
+function loadAgileTools() {
+    return JSON.parse(fs.readFileSync(path.join(path.dirname(catalogFile()), 'tools-agil.json'), 'utf8'));
+}
+/** The tools that run for at least one of the stacks (`all` tools always run). */
+function toolsFor(stacks, tools = loadTools()) {
+    return tools.filter(t => t.stacks === 'all' || t.stacks.some(s => stacks.includes(s)));
+}