@vyuhlabs/dxkit 2.4.6 → 2.4.8

package/dist/analyzers/cache.d.ts

@@ -0,0 +1,95 @@
+/**
+ * AnalysisResult cache — the cross-process persistence layer for the
+ * canonical analysis envelope.
+ *
+ * Two layers of caching:
+ *
+ *   1. **In-memory** (`Map<cacheKey, Promise<AnalysisResult>>`).
+ *      Dedupes concurrent calls within one process. Survives across
+ *      subcommands that share a Node process; cleared on process exit.
+ *
+ *   2. **On-disk JSON** under `<cwd>/.dxkit/cache/`. Persists across
+ *      processes so a second subcommand minutes later can skip the
+ *      gather entirely. Keyed by short commit SHA.
+ *
+ * Invalidation triggers (any one forces a rebuild + overwrites the
+ * cached file):
+ *
+ *   - Commit SHA differs from the cached file's `commitSha`.
+ *   - `.dxkit-ignore` mtime differs (changes affect what gets scanned).
+ *   - Cached file's `dxkitVersion` differs from the running version
+ *     (new tools or scoring formulas can change metrics).
+ *   - Cached file's `schemaVersion` differs from
+ *     `ANALYSIS_RESULT_SCHEMA_VERSION` (incompatible envelope shape).
+ *   - Caller passes `rescan: true`.
+ *
+ * Dirty-tree behavior:
+ *
+ *   Working-tree-dirty results are NEVER persisted to disk and are
+ *   NOT read back from disk. The commit SHA doesn't reflect the on-
+ *   disk state, so a disk cache keyed by SHA would alias two genuinely-
+ *   different states. In-memory caching still applies, so multiple
+ *   subcommands within one process share the rebuild without thrashing.
+ *
+ * The cache module never invokes a gather itself. Callers supply a
+ * `build` function returning `AnalysisResultBody`; the module stamps
+ * provenance and handles persistence. This keeps the gather pipeline
+ * decoupled from the cache layer and makes both unit-testable in
+ * isolation.
+ */
+import { type AnalysisResult, type AnalysisResultBody } from '../analysis-result';
+/**
+ * Provenance fields the cache resolves before deciding hit vs miss.
+ * Separate from `AnalysisResult` so the cache can compute it without
+ * a build, then compare against the cached file's persisted shape.
+ */
+export interface ResolvedProvenance {
+    commitSha: string;
+    branch: string;
+    cwd: string;
+    dxkitVersion: string;
+    ignoreFileMtime: number | null;
+    workingTreeDirty: boolean;
+}
+/**
+ * Builder contract. The cache calls this when it needs to (re)build
+ * the body. Implementations live alongside the consumers that
+ * orchestrate the gather pipeline (`analyzeHealthInternal` and
+ * friends).
+ */
+export type AnalysisResultBuilder = (cwd: string) => Promise<AnalysisResultBody>;
+export interface ReadOrBuildOptions {
+    /** Force a rebuild even on cache hit. Mirrors the CLI `--rescan` flag. */
+    rescan?: boolean;
+    /** Override cache directory location. Defaults to `<cwd>/.dxkit/cache`.
+     *  Tests use this to isolate cache state in a tmpdir; production
+     *  callers should never set it. */
+    cacheDir?: string;
+    /** Override the provenance resolver. Tests use this to inject SHA /
+     *  dirty-flag without spawning git. Production callers should never
+     *  set it. */
+    resolveProvenance?: (cwd: string) => ResolvedProvenance;
+    /** Override the wall-clock used for `builtAt`. Tests use this to
+     *  produce deterministic timestamps. Defaults to `new Date()`. */
+    now?: () => Date;
+}
+/**
+ * Resolve provenance fields needed to compute the cache key. Reads
+ * git state via `git rev-parse` + `git status --porcelain`,
+ * `.dxkit-ignore` mtime via `fs.statSync`, and pulls dxkit version
+ * from the package constant.
+ */
+export declare function resolveProvenance(cwd: string): ResolvedProvenance;
+/**
+ * Main entry. Returns a cached `AnalysisResult` when the cache key
+ * still matches, or rebuilds via `build` and persists. Dirty trees
+ * bypass disk persistence; the in-memory layer still applies.
+ */
+export declare function readOrBuildAnalysisResult(args: {
+    cwd: string;
+    build: AnalysisResultBuilder;
+    opts?: ReadOrBuildOptions;
+}): Promise<AnalysisResult>;
+/** Test seam — drop in-memory dedup state between test cases. */
+export declare function clearInMemoryCache(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/analyzers/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/analyzers/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAM5B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;uCAEmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;kBAEc;IACd,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAExD;sEACkE;IAClE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAOD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CASjE;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,CA+C1B;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/analyzers/cache.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * AnalysisResult cache — the cross-process persistence layer for the
+ * canonical analysis envelope.
+ *
+ * Two layers of caching:
+ *
+ *   1. **In-memory** (`Map<cacheKey, Promise<AnalysisResult>>`).
+ *      Dedupes concurrent calls within one process. Survives across
+ *      subcommands that share a Node process; cleared on process exit.
+ *
+ *   2. **On-disk JSON** under `<cwd>/.dxkit/cache/`. Persists across
+ *      processes so a second subcommand minutes later can skip the
+ *      gather entirely. Keyed by short commit SHA.
+ *
+ * Invalidation triggers (any one forces a rebuild + overwrites the
+ * cached file):
+ *
+ *   - Commit SHA differs from the cached file's `commitSha`.
+ *   - `.dxkit-ignore` mtime differs (changes affect what gets scanned).
+ *   - Cached file's `dxkitVersion` differs from the running version
+ *     (new tools or scoring formulas can change metrics).
+ *   - Cached file's `schemaVersion` differs from
+ *     `ANALYSIS_RESULT_SCHEMA_VERSION` (incompatible envelope shape).
+ *   - Caller passes `rescan: true`.
+ *
+ * Dirty-tree behavior:
+ *
+ *   Working-tree-dirty results are NEVER persisted to disk and are
+ *   NOT read back from disk. The commit SHA doesn't reflect the on-
+ *   disk state, so a disk cache keyed by SHA would alias two genuinely-
+ *   different states. In-memory caching still applies, so multiple
+ *   subcommands within one process share the rebuild without thrashing.
+ *
+ * The cache module never invokes a gather itself. Callers supply a
+ * `build` function returning `AnalysisResultBody`; the module stamps
+ * provenance and handles persistence. This keeps the gather pipeline
+ * decoupled from the cache layer and makes both unit-testable in
+ * isolation.
+ */
+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.resolveProvenance = resolveProvenance;
+exports.readOrBuildAnalysisResult = readOrBuildAnalysisResult;
+exports.clearInMemoryCache = clearInMemoryCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const analysis_result_1 = require("../analysis-result");
+const constants_1 = require("../constants");
+const IGNORE_FILE = '.dxkit-ignore';
+const CACHE_SUBDIR = path.join('.dxkit', 'cache');
+// In-memory dedup across subcommands sharing a process. Keyed by the
+// resolved provenance so a SHA change inside one process (rare but
+// possible — e.g. a long-running daemon) correctly misses.
+const inMemoryCache = new Map();
+/**
+ * Resolve provenance fields needed to compute the cache key. Reads
+ * git state via `git rev-parse` + `git status --porcelain`,
+ * `.dxkit-ignore` mtime via `fs.statSync`, and pulls dxkit version
+ * from the package constant.
+ */
+function resolveProvenance(cwd) {
+    return {
+        commitSha: gitRevParse(cwd, '--short', 'HEAD'),
+        branch: gitRevParse(cwd, '--abbrev-ref', 'HEAD'),
+        cwd: path.resolve(cwd),
+        dxkitVersion: constants_1.VERSION,
+        ignoreFileMtime: readIgnoreFileMtime(cwd),
+        workingTreeDirty: isWorkingTreeDirty(cwd),
+    };
+}
+/**
+ * Main entry. Returns a cached `AnalysisResult` when the cache key
+ * still matches, or rebuilds via `build` and persists. Dirty trees
+ * bypass disk persistence; the in-memory layer still applies.
+ */
+async function readOrBuildAnalysisResult(args) {
+    const { cwd, build } = args;
+    const opts = args.opts ?? {};
+    const provenance = (opts.resolveProvenance ?? resolveProvenance)(cwd);
+    const cacheDir = opts.cacheDir ?? path.join(provenance.cwd, CACHE_SUBDIR);
+    const cacheKey = buildCacheKey(provenance);
+    // In-memory short-circuit. Same provenance, same process: one rebuild.
+    if (!opts.rescan) {
+        const cached = inMemoryCache.get(cacheKey);
+        if (cached)
+            return cached;
+    }
+    const promise = (async () => {
+        // Disk read — only when the tree is clean (otherwise the cached SHA
+        // doesn't represent the gathered state) and the caller didn't ask
+        // for a forced rebuild.
+        if (!opts.rescan && !provenance.workingTreeDirty) {
+            const fromDisk = readDiskCache(cacheDir, provenance);
+            if (fromDisk)
+                return fromDisk;
+        }
+        // Build, stamp provenance, persist (when clean).
+        const body = await build(cwd);
+        const now = (opts.now ?? (() => new Date()))();
+        const result = {
+            ...body,
+            commitSha: provenance.commitSha,
+            branch: provenance.branch,
+            cwd: provenance.cwd,
+            builtAt: now.toISOString(),
+            dxkitVersion: provenance.dxkitVersion,
+            schemaVersion: analysis_result_1.ANALYSIS_RESULT_SCHEMA_VERSION,
+            ignoreFileMtime: provenance.ignoreFileMtime,
+            workingTreeDirty: provenance.workingTreeDirty,
+        };
+        if (!provenance.workingTreeDirty) {
+            writeDiskCache(cacheDir, result);
+        }
+        return result;
+    })();
+    inMemoryCache.set(cacheKey, promise);
+    // Drop the in-memory entry if the build itself threw — keep the cache
+    // honest, don't poison subsequent calls with a rejected Promise.
+    promise.catch(() => inMemoryCache.delete(cacheKey));
+    return promise;
+}
+/** Test seam — drop in-memory dedup state between test cases. */
+function clearInMemoryCache() {
+    inMemoryCache.clear();
+}
+// ─── Internals ────────────────────────────────────────────────────────────
+function buildCacheKey(p) {
+    // Including dirty-flag means a dirty rebuild doesn't get reused as a
+    // clean-tree hit after the user stashes/commits without restarting
+    // the process. Including version + schema keeps long-running daemons
+    // honest across an in-place dxkit upgrade.
+    return [
+        p.cwd,
+        p.commitSha || 'no-sha',
+        p.workingTreeDirty ? 'dirty' : 'clean',
+        p.dxkitVersion,
+        String(analysis_result_1.ANALYSIS_RESULT_SCHEMA_VERSION),
+        p.ignoreFileMtime ?? 'no-ignore',
+    ].join('::');
+}
+function cacheFilePath(cacheDir, commitSha) {
+    const sha = commitSha || 'no-sha';
+    return path.join(cacheDir, `analysis-result-${sha}.json`);
+}
+function readDiskCache(cacheDir, expected) {
+    const file = cacheFilePath(cacheDir, expected.commitSha);
+    if (!fs.existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        // Corrupt cache file — drop it and force a rebuild rather than
+        // crashing the caller. Defensive: a partial write or manual edit
+        // shouldn't break dxkit.
+        safeUnlink(file);
+        return null;
+    }
+    if (!isCacheStillValid(parsed, expected)) {
+        safeUnlink(file);
+        return null;
+    }
+    return parsed;
+}
+function isCacheStillValid(cached, expected) {
+    if (cached.schemaVersion !== analysis_result_1.ANALYSIS_RESULT_SCHEMA_VERSION)
+        return false;
+    if (cached.dxkitVersion !== expected.dxkitVersion)
+        return false;
+    if (cached.commitSha !== expected.commitSha)
+        return false;
+    if (cached.ignoreFileMtime !== expected.ignoreFileMtime)
+        return false;
+    // A persisted result is always clean (we don't write dirty ones).
+    // Defensive: refuse to honor any persisted record claiming dirty.
+    if (cached.workingTreeDirty)
+        return false;
+    return true;
+}
+function writeDiskCache(cacheDir, result) {
+    try {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        const file = cacheFilePath(cacheDir, result.commitSha);
+        fs.writeFileSync(file, JSON.stringify(result, null, 2), 'utf-8');
+    }
+    catch {
+        // Persistence failure is non-fatal — the caller already has a
+        // valid in-memory result. Logging is deferred to a future
+        // observability pass; silent failure here matches the broader
+        // "cache is best-effort" posture.
+    }
+}
+function safeUnlink(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch {
+        /* file already gone — fine */
+    }
+}
+function gitRevParse(cwd, ...args) {
+    try {
+        return (0, child_process_1.execSync)(`git rev-parse ${args.join(' ')}`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function isWorkingTreeDirty(cwd) {
+    try {
+        // `--untracked-files=all` expands every untracked file to its own
+        // line. The default behavior collapses an untracked directory to
+        // a single entry for its parent — which would hide a nested
+        // `.dxkit/` under a non-dxkit collapsed parent and leak it past
+        // the segment filter below. `=all` is also resilient to git's
+        // future grouping rules.
+        const out = (0, child_process_1.execSync)('git status --porcelain --untracked-files=all', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        // `.dxkit/` (analysis reports + this cache file + dashboard
+        // renders) and `.dxkit-ignore` (dxkit's own config file) are
+        // dxkit-owned paths. Untracked entries for either — at ANY depth
+        // in the tree — can't invalidate the cache the cache itself
+        // populates. Customer repos that haven't added `.dxkit/` to their
+        // `.gitignore` would otherwise always look dirty and the cache
+        // would never persist across processes. Nested cases matter too:
+        // a monorepo may have analysis state at `Code/Source/.dxkit/`
+        // alongside the root `.dxkit/`, and both should be filtered.
+        //
+        // Narrow exclusion — anything else under the tree (new source
+        // files, build artifacts, editor state) still flags dirty
+        // because it CAN change gather output. We match exact path
+        // segments to avoid masking unrelated names that merely contain
+        // the substring (e.g. a hypothetical `my.dxkit.json` file would
+        // not match the `.dxkit` segment check).
+        const lines = out.split('\n').filter((line) => {
+            if (!line.trim())
+                return false;
+            const m = /^\?\? (.+)$/.exec(line);
+            if (!m)
+                return true;
+            const segments = stripTrailingSlash(m[1]).split('/');
+            return !segments.some((seg) => seg === '.dxkit' || seg === '.dxkit-ignore');
+        });
+        return lines.length > 0;
+    }
+    catch {
+        // Not in a git repo (or git missing) — treat as dirty so we never
+        // persist a result we can't invalidate by SHA. Same posture as the
+        // dirty-tree path: in-memory cache still applies.
+        return true;
+    }
+}
+function stripTrailingSlash(p) {
+    return p.endsWith('/') ? p.slice(0, -1) : p;
+}
+function readIgnoreFileMtime(cwd) {
+    try {
+        const stat = fs.statSync(path.join(cwd, IGNORE_FILE));
+        return stat.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/analyzers/cache.js.map

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

package/dist/analyzers/coverage-runner.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Run `test-with-coverage` across every active language pack and
+ * collect the outcome rows. Single source of truth shared by:
+ *   - `vyuh-dxkit coverage` command  (cli.ts)
+ *   - `vyuh-dxkit health --with-coverage` (D021 sub-piece 2)
+ *   - `vyuh-dxkit test-gaps --with-coverage`  (D021 sub-piece 2)
+ *   - `vyuh-dxkit report` orchestrator  (D021 sub-piece 3)
+ *
+ * The function is provider-driven — each pack's
+ * `LanguagePackCapabilities.coverage.runTests` produces the artifact
+ * its parser reads back later via `loadCoverage()`. Pre-D021 the
+ * orchestration lived inline in cli.ts; extracting it here lets
+ * `--with-coverage` reuse the exact flow without duplicating the
+ * per-pack iteration / fail-fast / row-shape logic.
+ */
+import type { LanguageSupport } from '../languages/types';
+export type CoverageRunStatus = 'success' | 'unavailable' | 'failed' | 'skipped';
+export interface CoverageRunRow {
+    pack: string;
+    status: CoverageRunStatus;
+    durationMs: number;
+    artifact: string | null;
+    reason: string | null;
+}
+export interface CoverageRunOptions {
+    /** Restrict to one pack id (matches `vyuh-dxkit coverage --lang <id>`). */
+    langFilter?: string;
+    /** Stop at the first `failed` row when true (mirrors the CLI default). */
+    failFast?: boolean;
+    /**
+     * Streaming progress hook. Called once with `start` before each pack
+     * runs and once with `done` after, regardless of outcome. CLI hosts
+     * use this to print `→ <pack>: running tests with coverage...` lines
+     * incrementally — the function itself stays silent.
+     */
+    onPackStart?: (packId: string) => void;
+    onPackEnd?: (row: CoverageRunRow) => void;
+}
+export interface CoverageRunResult {
+    rows: CoverageRunRow[];
+    /** Packs that detect-active matched but failed the `langFilter` gate. */
+    activePacks: LanguageSupport[];
+}
+/**
+ * Iterate active packs and invoke each one's
+ * `capabilities.coverage.runTests`, returning per-pack outcome rows.
+ * Packs without a `runTests` implementation surface as `'skipped'` so
+ * the caller can still render the full active-pack matrix.
+ *
+ * Fail-fast semantics match the legacy `coverage` command: a
+ * `failed` outcome stops the iteration (caller handles exit code).
+ * `unavailable` and `skipped` keep the loop running because they mean
+ * "no artifact this run" rather than "the test run blew up."
+ */
+export declare function runCoverageAcrossPacks(cwd: string, opts?: CoverageRunOptions): Promise<CoverageRunResult>;
+//# sourceMappingURL=coverage-runner.d.ts.map

package/dist/analyzers/coverage-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-runner.d.ts","sourceRoot":"","sources":["../../src/analyzers/coverage-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,yEAAyE;IACzE,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAsD5B"}

package/dist/analyzers/coverage-runner.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCoverageAcrossPacks = runCoverageAcrossPacks;
+const languages_1 = require("../languages");
+/**
+ * Iterate active packs and invoke each one's
+ * `capabilities.coverage.runTests`, returning per-pack outcome rows.
+ * Packs without a `runTests` implementation surface as `'skipped'` so
+ * the caller can still render the full active-pack matrix.
+ *
+ * Fail-fast semantics match the legacy `coverage` command: a
+ * `failed` outcome stops the iteration (caller handles exit code).
+ * `unavailable` and `skipped` keep the loop running because they mean
+ * "no artifact this run" rather than "the test run blew up."
+ */
+async function runCoverageAcrossPacks(cwd, opts = {}) {
+    const failFast = opts.failFast ?? true;
+    const active = (0, languages_1.detectActiveLanguages)(cwd);
+    const candidates = active.filter((p) => !opts.langFilter || p.id === opts.langFilter);
+    const rows = [];
+    for (const pack of candidates) {
+        const provider = pack.capabilities?.coverage;
+        if (!provider?.runTests) {
+            const row = {
+                pack: pack.id,
+                status: 'skipped',
+                durationMs: 0,
+                artifact: null,
+                reason: 'no runTests() implementation yet (pack coverage capability is read-only)',
+            };
+            rows.push(row);
+            opts.onPackEnd?.(row);
+            continue;
+        }
+        opts.onPackStart?.(pack.id);
+        const outcome = await provider.runTests(cwd);
+        let row;
+        if (outcome.kind === 'success') {
+            row = {
+                pack: pack.id,
+                status: 'success',
+                durationMs: outcome.durationMs,
+                artifact: outcome.artifact,
+                reason: null,
+            };
+        }
+        else if (outcome.kind === 'unavailable') {
+            row = {
+                pack: pack.id,
+                status: 'unavailable',
+                durationMs: 0,
+                artifact: null,
+                reason: outcome.reason,
+            };
+        }
+        else {
+            row = {
+                pack: pack.id,
+                status: 'failed',
+                durationMs: outcome.durationMs,
+                artifact: null,
+                reason: outcome.reason,
+            };
+        }
+        rows.push(row);
+        opts.onPackEnd?.(row);
+        if (row.status === 'failed' && failFast)
+            break;
+    }
+    return { rows, activePacks: active };
+}
+//# sourceMappingURL=coverage-runner.js.map

package/dist/analyzers/coverage-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-runner.js","sourceRoot":"","sources":["../../src/analyzers/coverage-runner.ts"],"names":[],"mappings":";;AA4DA,wDAyDC;AArGD,4CAAqD;AAiCrD;;;;;;;;;;GAUG;AACI,KAAK,UAAU,sBAAsB,CAC1C,GAAW,EACX,OAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;IACvC,MAAM,MAAM,GAAG,IAAA,iCAAqB,EAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC;IACtF,MAAM,IAAI,GAAqB,EAAE,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC;YACxB,MAAM,GAAG,GAAmB;gBAC1B,IAAI,EAAE,IAAI,CAAC,EAAE;gBACb,MAAM,EAAE,SAAS;gBACjB,UAAU,EAAE,CAAC;gBACb,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,0EAA0E;aACnF,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,GAAmB,CAAC;QACxB,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,GAAG,GAAG;gBACJ,IAAI,EAAE,IAAI,CAAC,EAAE;gBACb,MAAM,EAAE,SAAS;gBACjB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,MAAM,EAAE,IAAI;aACb,CAAC;QACJ,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAC1C,GAAG,GAAG;gBACJ,IAAI,EAAE,IAAI,CAAC,EAAE;gBACb,MAAM,EAAE,aAAa;gBACrB,UAAU,EAAE,CAAC;gBACb,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,GAAG,GAAG;gBACJ,IAAI,EAAE,IAAI,CAAC,EAAE;gBACb,MAAM,EAAE,QAAQ;gBAChB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ;YAAE,MAAM;IACjD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC"}

package/dist/analyzers/dashboard/index.d.ts

@@ -0,0 +1,24 @@
+export interface DashboardOptions {
+    /** Where to read markdown reports from. Default: `<cwd>/.dxkit/reports`. */
+    reportsDir?: string;
+    /** Where to read JSON synthesis data from. Default: same as reportsDir. */
+    jsonDir?: string;
+    /** Project name shown in the header. Default: derived from package.json or basename(cwd). */
+    projectName?: string;
+}
+export interface DashboardResult {
+    html: string;
+    reportCount: number;
+    criticalIssueCount: number;
+    /** Best-effort summary numbers, surfaced to the CLI for stderr logging. */
+    summary: {
+        healthScore: number | null;
+        healthGrade: string | null;
+        vulnCount: number;
+        gapCount: number;
+        advisoryCount: number;
+        slopScore: number | null;
+    };
+}
+export declare function analyzeDashboard(cwd: string, options?: DashboardOptions): DashboardResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/analyzers/dashboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analyzers/dashboard/index.ts"],"names":[],"mappings":"AAwDA,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;CACH;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA8R7F"}