@vyuhlabs/dxkit 2.7.1 → 2.9.0

package/dist/ingest/engine-resolver.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDeepSastEngine = resolveDeepSastEngine;
+/**
+ * License-aware deep-SAST engine resolver.
+ *
+ * Interprocedural SAST is not free-and-unconditional the way dxkit's
+ * bundled scanners are: CodeQL's CLI license permits free analysis only
+ * for open-source repos or under GitHub Advanced Security; Snyk Code is
+ * the customer's own licensed engine. So "which engine do we use for
+ * deep SAST?" is a decision that depends on repo visibility, what the
+ * customer already licenses, and explicit consent — exactly the shape
+ * of the baseline-mode resolver (see `src/baseline/modes.ts`), and kept
+ * deliberately parallel to it.
+ *
+ * This module decides; it does not run anything. The caller (the
+ * `ingest` CLI, the `dxkit-ingest` skill) acts on the decision —
+ * including prompting for consent when `requiresConsent` is set, so an
+ * engine never runs on private code without the user accepting the
+ * license terms.
+ *
+ * Pure: the only I/O is the visibility probe, which is injectable for
+ * tests.
+ */
+const visibility_1 = require("../baseline/visibility");
+const GHAS_NOTE = "CodeQL's license permits free use on open-source repos, academic " +
+    'research, or under GitHub Advanced Security. This repo is not public — ' +
+    'confirm you have GitHub Advanced Security (or ingest an engine you ' +
+    'already license, e.g. Snyk) before running CodeQL.';
+/**
+ * Resolve which deep-SAST engine to use. Precedence:
+ *   1. explicit `--engine` flag
+ *   2. a configured Snyk token (ingest the customer's own results —
+ *      license-safe, no consent)
+ *   3. repo visibility: public → CodeQL (licensed for OSS); otherwise
+ *      CodeQL gated behind consent (GHAS), so the caller can prompt or
+ *      fall back.
+ */
+function resolveDeepSastEngine(opts) {
+    const probe = opts.visibilityProbe ?? visibility_1.detectRepoVisibility;
+    // 1. Explicit override.
+    if (opts.engineFlag) {
+        const engine = opts.engineFlag;
+        if (engine === 'codeql') {
+            const visibility = probe(opts.cwd);
+            const consent = visibility !== 'public';
+            return {
+                engine,
+                source: 'flag',
+                requiresConsent: consent,
+                explanation: `engine=codeql (--engine)${consent ? '; consent required (non-public repo)' : ''}`,
+                ...(consent ? { licenseNote: GHAS_NOTE } : {}),
+            };
+        }
+        return {
+            engine,
+            source: 'flag',
+            requiresConsent: false,
+            explanation: `engine=${engine} (--engine)`,
+        };
+    }
+    // 2. Snyk configured → ingest the customer's own licensed results.
+    if (opts.snykConfigured) {
+        return {
+            engine: 'snyk-code',
+            source: 'snyk-configured',
+            requiresConsent: false,
+            explanation: 'engine=snyk-code (SNYK_TOKEN + project configured; quota-free read)',
+        };
+    }
+    // 3. Visibility-derived default.
+    const visibility = probe(opts.cwd);
+    if (visibility === 'public') {
+        return {
+            engine: 'codeql',
+            source: 'visibility-public',
+            requiresConsent: false,
+            explanation: 'engine=codeql (public repo; CodeQL is licensed for open source)',
+        };
+    }
+    return {
+        engine: 'codeql',
+        source: 'visibility-private',
+        requiresConsent: true,
+        explanation: `engine=codeql (visibility=${visibility}; consent required before running)`,
+        licenseNote: GHAS_NOTE,
+    };
+}
+//# sourceMappingURL=engine-resolver.js.map

package/dist/ingest/engine-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-resolver.js","sourceRoot":"","sources":["../../src/ingest/engine-resolver.ts"],"names":[],"mappings":";;AA6EA,sDAoDC;AAjID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uDAA8D;AAyC9D,MAAM,SAAS,GACb,mEAAmE;IACnE,yEAAyE;IACzE,qEAAqE;IACrE,oDAAoD,CAAC;AAEvD;;;;;;;;GAQG;AACH,SAAgB,qBAAqB,CAAC,IAA4B;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,IAAI,iCAAoB,CAAC;IAE3D,wBAAwB;IACxB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,MAAM,OAAO,GAAG,UAAU,KAAK,QAAQ,CAAC;YACxC,OAAO;gBACL,MAAM;gBACN,MAAM,EAAE,MAAM;gBACd,eAAe,EAAE,OAAO;gBACxB,WAAW,EAAE,2BAA2B,OAAO,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC/F,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/C,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM;YACN,MAAM,EAAE,MAAM;YACd,eAAe,EAAE,KAAK;YACtB,WAAW,EAAE,UAAU,MAAM,aAAa;SAC3C,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,OAAO;YACL,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,iBAAiB;YACzB,eAAe,EAAE,KAAK;YACtB,WAAW,EAAE,qEAAqE;SACnF,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,mBAAmB;YAC3B,eAAe,EAAE,KAAK;YACtB,WAAW,EAAE,iEAAiE;SAC/E,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,QAAQ;QAChB,MAAM,EAAE,oBAAoB;QAC5B,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,6BAA6B,UAAU,oCAAoC;QACxF,WAAW,EAAE,SAAS;KACvB,CAAC;AACJ,CAAC"}

package/dist/ingest/normalize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalize ingested external findings into the security pipeline's
+ * `SecurityFinding` shape.
+ *
+ * Deliberately a pure field-map and nothing more. In particular it does
+ * NOT compute identity: the security aggregator owns fingerprinting for
+ * every code finding (`canonicalRuleFor(tool, rule)` →
+ * `computeCodeFingerprint`) and the cross-tool dedup that collapses,
+ * say, a Snyk Code and a semgrep finding on the same line into one
+ * `CodeFinding`. Routing ingested findings through that same path is
+ * what keeps one fingerprint scheme across native + ingested findings
+ * (Rule 9) — an ingest-local hash would silently fork the contract.
+ *
+ * The engine name becomes the finding's `tool` provenance, so the
+ * canonical rule (`canonicalRuleFor(engine, rule)`) and the report's
+ * attribution both trace back to the producing engine.
+ */
+import type { SecurityFinding } from '../analyzers/security/types';
+import type { ExternalFinding } from './types';
+/** Map normalized external findings to `SecurityFinding[]` for the
+ *  aggregator. Identity + dedup happen downstream (Rule 9). */
+export declare function externalToSecurityFindings(findings: ReadonlyArray<ExternalFinding>): SecurityFinding[];
+//# sourceMappingURL=normalize.d.ts.map

package/dist/ingest/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/ingest/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;+DAC+D;AAC/D,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,GACvC,eAAe,EAAE,CAWnB"}

package/dist/ingest/normalize.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.externalToSecurityFindings = externalToSecurityFindings;
+/** Map normalized external findings to `SecurityFinding[]` for the
+ *  aggregator. Identity + dedup happen downstream (Rule 9). */
+function externalToSecurityFindings(findings) {
+    return findings.map((f) => ({
+        severity: f.severity,
+        category: f.category,
+        cwe: f.cwe,
+        rule: f.rule,
+        title: f.title,
+        file: f.file,
+        line: f.line,
+        tool: f.engine,
+    }));
+}
+//# sourceMappingURL=normalize.js.map

package/dist/ingest/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/ingest/normalize.ts"],"names":[],"mappings":";;AAsBA,gEAaC;AAfD;+DAC+D;AAC/D,SAAgB,0BAA0B,CACxC,QAAwC;IAExC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,MAAM;KACf,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/ingest/sarif.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SARIF 2.1.0 → `ExternalFinding[]`.
+ *
+ * SARIF is the lingua franca of SAST: CodeQL, Snyk Code (`snyk code
+ * test --sarif`), Semgrep Pro, and Bearer all emit it. Parsing it once
+ * here means every current and future interprocedural engine funnels
+ * into dxkit through the same door — the engine-agnostic core of the
+ * deep-SAST tier.
+ *
+ * Severity resolution prefers the numeric `security-severity` property
+ * (a CVSS-style 0–10 score most security rules carry) and falls back to
+ * the SARIF result `level`. CWE comes from the rule's `tags`
+ * (`external/cwe/cwe-022` → `CWE-22`). Rules can live on the driver or
+ * on a tool extension (CodeQL puts the query pack's rules under
+ * `extensions`), so we index both.
+ *
+ * Pure + defensive: a malformed run, a result with no location, or a
+ * missing rule never throws — it's skipped or filled with a safe
+ * default, because ingestion runs against third-party output we don't
+ * control.
+ */
+import type { SourceEngine, ExternalFinding } from './types';
+/**
+ * Parse a SARIF 2.1.0 document. `engine` overrides the auto-detected
+ * driver name (callers usually know which engine produced the file);
+ * pass `undefined` to infer from the SARIF tool driver.
+ */
+export declare function parseSarif(raw: string, engine?: SourceEngine): ExternalFinding[];
+//# sourceMappingURL=sarif.d.ts.map

package/dist/ingest/sarif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../src/ingest/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAuG7D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,EAAE,CAqDhF"}

package/dist/ingest/sarif.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSarif = parseSarif;
+/** Map a SARIF tool driver name to a known engine, when the caller
+ *  didn't pass one explicitly. Unknown drivers fall back to the generic
+ *  `sarif` engine so attribution is still honest. */
+function engineFromDriver(name) {
+    const n = (name || '').toLowerCase();
+    if (n.includes('codeql'))
+        return 'codeql';
+    if (n.includes('snyk'))
+        return 'snyk-code';
+    if (n.includes('semgrep'))
+        return 'semgrep-pro';
+    return 'sarif';
+}
+/** Normalize any CWE-ish string to canonical `CWE-<n>` (leading zeros
+ *  stripped), or '' when none present. */
+function normalizeCwe(s) {
+    if (!s)
+        return '';
+    const m = /cwe[-/_]?(\d+)/i.exec(s);
+    return m ? `CWE-${parseInt(m[1], 10)}` : '';
+}
+/** Resolve the CWE for a rule across engine conventions:
+ *  Snyk Code uses `properties.cwe: ["CWE-94"]`; CodeQL uses
+ *  `properties.tags: ["external/cwe/cwe-094"]`. Checks both. */
+function cweFromRule(rule) {
+    const direct = rule?.properties?.cwe;
+    if (Array.isArray(direct)) {
+        for (const c of direct) {
+            const n = normalizeCwe(c);
+            if (n)
+                return n;
+        }
+    }
+    for (const tag of rule?.properties?.tags ?? []) {
+        const n = normalizeCwe(tag);
+        if (n)
+            return n;
+    }
+    return '';
+}
+/** Resolve four-tier severity. Prefer numeric `security-severity`
+ *  (CVSS-like 0–10); else the rule's `problem.severity`; else the
+ *  result `level`. */
+function resolveSeverity(rule, level) {
+    const num = rule?.properties?.['security-severity'];
+    if (num !== undefined && num !== null && num !== '') {
+        const score = typeof num === 'number' ? num : parseFloat(String(num));
+        if (!Number.isNaN(score)) {
+            if (score >= 9.0)
+                return 'critical';
+            if (score >= 7.0)
+                return 'high';
+            if (score >= 4.0)
+                return 'medium';
+            return 'low';
+        }
+    }
+    const ps = rule?.properties?.['problem.severity'];
+    if (ps === 'error')
+        return 'high';
+    if (ps === 'warning' || ps === 'recommendation')
+        return 'medium';
+    // SARIF result level is the last resort.
+    if (level === 'error')
+        return 'high';
+    if (level === 'note')
+        return 'low';
+    if (level === 'warning')
+        return 'medium';
+    return 'medium';
+}
+/**
+ * Parse a SARIF 2.1.0 document. `engine` overrides the auto-detected
+ * driver name (callers usually know which engine produced the file);
+ * pass `undefined` to infer from the SARIF tool driver.
+ */
+function parseSarif(raw, engine) {
+    let log;
+    try {
+        log = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const run of log.runs || []) {
+        const driverName = run.tool?.driver?.name;
+        const resolvedEngine = engine ?? engineFromDriver(driverName);
+        // Index rules by id from driver + every extension.
+        const rulesById = new Map();
+        const ruleLists = [];
+        if (run.tool?.driver?.rules)
+            ruleLists.push(run.tool.driver.rules);
+        for (const ext of run.tool?.extensions || []) {
+            if (ext.rules)
+                ruleLists.push(ext.rules);
+        }
+        const flatRules = [];
+        for (const list of ruleLists) {
+            for (const r of list) {
+                flatRules.push(r);
+                if (r.id)
+                    rulesById.set(r.id, r);
+            }
+        }
+        for (const res of run.results || []) {
+            const ruleId = res.ruleId || res.rule?.id;
+            // Rule can be referenced by id or by index into the (flattened) list.
+            let rule = ruleId ? rulesById.get(ruleId) : undefined;
+            if (!rule && typeof res.rule?.index === 'number')
+                rule = flatRules[res.rule.index];
+            const loc = res.locations?.[0]?.physicalLocation;
+            const file = loc?.artifactLocation?.uri;
+            const line = loc?.region?.startLine;
+            // A finding with no source location can't be fingerprinted or
+            // fixed — skip rather than emit a phantom at line 0.
+            if (!file || !line)
+                continue;
+            out.push({
+                engine: resolvedEngine,
+                severity: resolveSeverity(rule, res.level),
+                category: 'code',
+                cwe: cweFromRule(rule),
+                rule: ruleId || rule?.name || 'unknown',
+                title: res.message?.text || rule?.shortDescription?.text || ruleId || 'SAST finding',
+                file,
+                line,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=sarif.js.map

package/dist/ingest/sarif.js.map

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

package/dist/ingest/snapshot.d.ts

@@ -0,0 +1,26 @@
+import type { SourceEngine, ExternalFinding } from './types';
+/** Directory (relative to repo root) where ingestion snapshots live. */
+export declare const EXTERNAL_DIR: string;
+export interface ExternalSnapshot {
+    schemaVersion: 1;
+    engine: SourceEngine;
+    /** ISO timestamp the snapshot was produced. Stamped by the caller so
+     *  this module stays free of clock access (testability). */
+    generatedAt: string;
+    /** Commit the snapshot was produced against, when known. */
+    commitSha?: string;
+    findings: ExternalFinding[];
+}
+/** Write (overwrite) an engine's snapshot. Creates `.dxkit/external/`
+ *  if needed. */
+export declare function writeSnapshot(cwd: string, snapshot: ExternalSnapshot): string;
+/**
+ * Read every snapshot under `.dxkit/external/` and return the union of
+ * their findings. Fail-open: a missing directory, an unreadable file,
+ * or a malformed snapshot yields no findings from that file rather than
+ * throwing — ingestion is optional and must never break a scan.
+ */
+export declare function readAllSnapshots(cwd: string): ExternalFinding[];
+/** Distinct engines present in `.dxkit/external/` (for provenance). */
+export declare function snapshotEngines(cwd: string): string[];
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/ingest/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/ingest/snapshot.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7D,wEAAwE;AACxE,eAAO,MAAM,YAAY,QAAkC,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB;gEAC4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAOD;iBACiB;AACjB,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAM7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAmB/D;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAUrD"}

package/dist/ingest/snapshot.js

@@ -0,0 +1,114 @@
+"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.EXTERNAL_DIR = void 0;
+exports.writeSnapshot = writeSnapshot;
+exports.readAllSnapshots = readAllSnapshots;
+exports.snapshotEngines = snapshotEngines;
+/**
+ * Persisted ingestion snapshots under `.dxkit/external/`.
+ *
+ * `vyuh-dxkit ingest` writes one snapshot file per engine
+ * (`.dxkit/external/<engine>.json`). The snapshot is committed to the
+ * repo so every developer and every CI run reads the ingested findings
+ * WITHOUT needing the engine's token — only the one CI refresh job that
+ * produced it needs `SNYK_TOKEN` (or a CodeQL license). This is what
+ * makes "an admin adds the token once and everyone benefits" true.
+ *
+ * The snapshot is the normalized `ExternalFinding[]` plus light
+ * metadata for provenance/diagnostics. It deliberately carries no
+ * engine-token or account identifier — only finding data — so it is
+ * safe to commit.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Directory (relative to repo root) where ingestion snapshots live. */
+exports.EXTERNAL_DIR = path.join('.dxkit', 'external');
+/** Absolute path to an engine's snapshot file. */
+function snapshotPath(cwd, engine) {
+    return path.join(cwd, exports.EXTERNAL_DIR, `${engine}.json`);
+}
+/** Write (overwrite) an engine's snapshot. Creates `.dxkit/external/`
+ *  if needed. */
+function writeSnapshot(cwd, snapshot) {
+    const dir = path.join(cwd, exports.EXTERNAL_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = snapshotPath(cwd, snapshot.engine);
+    fs.writeFileSync(file, JSON.stringify(snapshot, null, 2) + '\n', 'utf-8');
+    return file;
+}
+/**
+ * Read every snapshot under `.dxkit/external/` and return the union of
+ * their findings. Fail-open: a missing directory, an unreadable file,
+ * or a malformed snapshot yields no findings from that file rather than
+ * throwing — ingestion is optional and must never break a scan.
+ */
+function readAllSnapshots(cwd) {
+    const dir = path.join(cwd, exports.EXTERNAL_DIR);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), 'utf-8');
+            const snap = JSON.parse(raw);
+            if (Array.isArray(snap.findings))
+                out.push(...snap.findings);
+        }
+        catch {
+            // skip unreadable / malformed snapshot
+        }
+    }
+    return out;
+}
+/** Distinct engines present in `.dxkit/external/` (for provenance). */
+function snapshotEngines(cwd) {
+    const dir = path.join(cwd, exports.EXTERNAL_DIR);
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.replace(/\.json$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/ingest/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/ingest/snapshot.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,sCAMC;AAQD,4CAmBC;AAGD,0CAUC;AAtFD;;;;;;;;;;;;;;GAcG;AACH,uCAAyB;AACzB,2CAA6B;AAG7B,wEAAwE;AAC3D,QAAA,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAa5D,kDAAkD;AAClD,SAAS,YAAY,CAAC,GAAW,EAAE,MAAoB;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAY,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;AACxD,CAAC;AAED;iBACiB;AACjB,SAAgB,aAAa,CAAC,GAAW,EAAE,QAA0B;IACnE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAY,CAAC,CAAC;IACzC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,GAAW;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAY,CAAC,CAAC;IACzC,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;YACjD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAY,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,EAAE;aACN,WAAW,CAAC,GAAG,CAAC;aAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;aAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/ingest/snyk-api.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Snyk Code (SAST) reader — pulls a project's already-computed findings
+ * from the Snyk REST API.
+ *
+ * Why API-read (not `snyk code test`): reading stored issues does NOT
+ * consume the org's Snyk Code test quota. On a free/limited tier where
+ * tests are capped per billing period, this is the only repeatable way
+ * to get the findings out. An admin provides a `SNYK_TOKEN` once
+ * (ideally as a CI secret); the refresh job commits a snapshot so every
+ * other developer and CI run reads it without a token.
+ *
+ * Endpoint (REST):
+ *   GET /rest/orgs/{org_id}/issues
+ *       ?version=<date>&type=code
+ *       &scan_item.type=project&scan_item.id=<project_id>
+ *   Authorization: token <SNYK_TOKEN>
+ *
+ * Field paths (confirmed against the published OpenAPI):
+ *   - severity → attributes.effective_severity_level
+ *                (info|low|medium|high|critical)
+ *   - cwe      → attributes.classes[] where source == 'CWE' (id 'CWE-23')
+ *   - title    → attributes.title
+ *   - location → attributes.coordinates[].representations[].sourceLocation
+ *                .file  +  .region.start.line
+ *
+ * VALIDATION NOTE: the precise auth scheme (`token` vs `Bearer`) and the
+ * exact nesting of `sourceLocation` for code issues must be confirmed
+ * against a REAL response from a live token before this is trusted in
+ * production — synthetic-schema parsers drift from real output. The
+ * parser below is defensive (missing fields skip, never throw) so a
+ * schema surprise degrades to "fewer findings", never a crash.
+ */
+import type { ExternalFinding } from './types';
+export interface SnykReadOptions {
+    token: string;
+    orgId: string;
+    projectId: string;
+    /** REST API base; override for self-hosted/regional tenants
+     *  (e.g. https://api.eu.snyk.io). */
+    apiBase?: string;
+    /** REST API version date. Snyk requires an explicit version. */
+    version?: string;
+}
+interface SnykClass {
+    id?: string;
+    source?: string;
+}
+interface SnykRepresentation {
+    sourceLocation?: {
+        file?: string;
+        region?: {
+            start?: {
+                line?: number;
+            };
+        };
+    };
+}
+interface SnykCoordinate {
+    representations?: SnykRepresentation[];
+}
+interface SnykIssue {
+    id?: string;
+    attributes?: {
+        title?: string;
+        type?: string;
+        effective_severity_level?: string;
+        classes?: SnykClass[];
+        coordinates?: SnykCoordinate[];
+    };
+}
+/** Map one Snyk issue → `ExternalFinding`, or null when it has no
+ *  usable source location (can't be fingerprinted/fixed). */
+export declare function snykIssueToFinding(issue: SnykIssue): ExternalFinding | null;
+/**
+ * Fetch all Snyk Code findings for a project, following pagination.
+ * Pure-ish: the only side effect is the network read. Throws on auth /
+ * network failure so the CLI can surface a clear message; a successful
+ * call with zero issues returns `[]`.
+ */
+export declare function fetchSnykCodeFindings(opts: SnykReadOptions): Promise<ExternalFinding[]>;
+export {};
+//# sourceMappingURL=snyk-api.d.ts.map

package/dist/ingest/snyk-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snyk-api.d.ts","sourceRoot":"","sources":["../../src/ingest/snyk-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB;yCACqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAuBD,UAAU,SAAS;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,UAAU,kBAAkB;IAC1B,cAAc,CAAC,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE;gBAAE,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC;KACxC,CAAC;CACH;AACD,UAAU,cAAc;IACtB,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACxC;AACD,UAAU,SAAS;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;QACtB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;KAChC,CAAC;CACH;AA8BD;6DAC6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe,GAAG,IAAI,CAe3E;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAsC7F"}