@deftai/directive-core 0.79.3 → 0.80.0

package/dist/coverage-hotspots/evaluate.d.ts

@@ -0,0 +1,49 @@
+import { type CoverageMetric, type CoverageTotals, summarizeCoverageFinal } from "../vitest-runner/coverage-debt.js";
+import { type CoverageThresholds } from "./thresholds.js";
+export declare const DEFAULT_MIN_HEADROOM_PP = 0.3;
+export declare const DEFAULT_LOWEST_MODULE_LIMIT = 10;
+export interface ModuleCoverage {
+    readonly path: string;
+    readonly lines: number;
+    readonly functions: number;
+    readonly branches: number;
+    readonly statements: number;
+}
+export interface UncoveredBranchSample {
+    readonly path: string;
+    readonly line: number;
+    readonly branchId: string;
+    readonly type: string;
+}
+export interface CoverageHotspotsReport {
+    readonly ok: boolean;
+    readonly global: CoverageTotals;
+    readonly thresholds: CoverageThresholds;
+    readonly headroomPp: Record<CoverageMetric, number>;
+    readonly minHeadroomPp: number;
+    readonly failReasons: readonly string[];
+    readonly lowestModules: readonly ModuleCoverage[];
+    readonly uncoveredBranches: readonly UncoveredBranchSample[];
+    readonly pathFilter: readonly string[];
+    readonly coverageReportPath: string;
+}
+export interface CoverageHotspotsResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly report: CoverageHotspotsReport | null;
+    readonly message: string;
+}
+export interface CoverageHotspotsOptions {
+    readonly projectRoot: string;
+    readonly coverageDir?: string;
+    readonly minHeadroomPp?: number;
+    readonly baseRef?: string | null;
+    readonly pathFilter?: readonly string[] | null;
+    readonly useDiffPaths?: boolean;
+    readonly lowestModuleLimit?: number;
+}
+export declare function evaluateCoverageHotspots(options: CoverageHotspotsOptions): CoverageHotspotsResult;
+export declare function formatJsonReport(report: CoverageHotspotsReport): string;
+export declare function formatTextReport(report: CoverageHotspotsReport, failed: boolean): string;
+/** Re-export for tests that build synthetic reports. */
+export { summarizeCoverageFinal };
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/coverage-hotspots/evaluate.js

@@ -0,0 +1,262 @@
+import * as childProcess from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { summarizeCoverageFinal, } from "../vitest-runner/coverage-debt.js";
+import { readProjectCoverageThresholds } from "./thresholds.js";
+export const DEFAULT_MIN_HEADROOM_PP = 0.3;
+export const DEFAULT_LOWEST_MODULE_LIMIT = 10;
+class GitCommandError extends Error {
+}
+function runGit(args, projectRoot) {
+    try {
+        return childProcess.execFileSync("git", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const e = err;
+        const stderr = String(e.stderr ?? e.message ?? err).trim();
+        throw new GitCommandError(`coverage-hotspots: git ${args.join(" ")} failed: ${stderr}`);
+    }
+}
+function splitLines(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function resolveBaseRef(projectRoot, override) {
+    if (override && override.trim().length > 0)
+        return override.trim();
+    for (const candidate of ["origin/master", "origin/main", "master", "main", "HEAD~1"]) {
+        try {
+            runGit(["rev-parse", "--verify", "-q", candidate], projectRoot);
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    return "HEAD~1";
+}
+function diffPaths(projectRoot, baseRef) {
+    return splitLines(runGit(["diff", "--name-only", baseRef, "HEAD"], projectRoot));
+}
+function pct(covered, total) {
+    return total === 0 ? 100 : (covered / total) * 100;
+}
+function summarizeFileCoverage(relPath, file) {
+    let stmtTotal = 0;
+    let stmtCovered = 0;
+    let fnTotal = 0;
+    let fnCovered = 0;
+    let branchTotal = 0;
+    let branchCovered = 0;
+    if (file.s) {
+        for (const hits of Object.values(file.s)) {
+            stmtTotal += 1;
+            if (hits > 0)
+                stmtCovered += 1;
+        }
+    }
+    if (file.f) {
+        for (const hits of Object.values(file.f)) {
+            fnTotal += 1;
+            if (hits > 0)
+                fnCovered += 1;
+        }
+    }
+    if (file.b) {
+        for (const paths of Object.values(file.b)) {
+            for (const hits of paths) {
+                branchTotal += 1;
+                if (hits > 0)
+                    branchCovered += 1;
+            }
+        }
+    }
+    const statements = pct(stmtCovered, stmtTotal);
+    const functions = pct(fnCovered, fnTotal);
+    const branches = pct(branchCovered, branchTotal);
+    return {
+        path: relPath,
+        statements,
+        functions,
+        branches,
+        lines: statements,
+    };
+}
+function normalizeReportPath(projectRoot, rawKey, file) {
+    if (file.path && file.path.length > 0) {
+        const abs = file.path;
+        if (abs.startsWith(projectRoot)) {
+            return relative(projectRoot, abs).replace(/\\/g, "/");
+        }
+        return abs.replace(/\\/g, "/");
+    }
+    return rawKey.replace(/\\/g, "/");
+}
+function pathMatchesFilter(relPath, filters) {
+    if (filters.length === 0)
+        return true;
+    // Substring only — do not feed CLI/argv filters into RegExp (CodeQL js/regex-injection).
+    return filters.some((pattern) => relPath.includes(pattern));
+}
+function collectUncoveredBranches(relPath, file) {
+    if (!file.b)
+        return [];
+    const samples = [];
+    for (const [branchId, hits] of Object.entries(file.b)) {
+        if (!hits.some((count) => count === 0))
+            continue;
+        const meta = file.branchMap?.[branchId];
+        const line = meta?.line ?? meta?.loc?.start?.line ?? 0;
+        samples.push({
+            path: relPath,
+            line,
+            branchId,
+            type: meta?.type ?? "branch",
+        });
+    }
+    return samples;
+}
+function computeHeadroom(totals, thresholds) {
+    return {
+        lines: totals.lines - thresholds.lines,
+        functions: totals.functions - thresholds.functions,
+        branches: totals.branches - thresholds.branches,
+        statements: totals.statements - thresholds.statements,
+    };
+}
+function evaluatePassFail(totals, thresholds, headroomPp, minHeadroomPp) {
+    const reasons = [];
+    if (totals.branches + 1e-9 < thresholds.branches) {
+        reasons.push(`branches ${totals.branches.toFixed(2)}% below project floor ${thresholds.branches}%`);
+    }
+    if (headroomPp.branches + 1e-9 < minHeadroomPp) {
+        reasons.push(`branch headroom ${headroomPp.branches.toFixed(2)}pp below minimum ${minHeadroomPp}pp`);
+    }
+    return reasons;
+}
+function configError(message) {
+    return { exitCode: 2, report: null, message };
+}
+export function evaluateCoverageHotspots(options) {
+    const projectRoot = options.projectRoot;
+    const coverageDir = options.coverageDir ?? join(projectRoot, "coverage");
+    const minHeadroomPp = options.minHeadroomPp ?? DEFAULT_MIN_HEADROOM_PP;
+    const lowestModuleLimit = options.lowestModuleLimit ?? DEFAULT_LOWEST_MODULE_LIMIT;
+    const useDiffPaths = options.useDiffPaths ?? true;
+    const reportPath = join(coverageDir, "coverage-final.json");
+    if (!existsSync(reportPath)) {
+        return configError(`coverage-hotspots: coverage report missing at ${reportPath}\n` +
+            "  Run tests with coverage first (e.g. vitest run --coverage or task test:coverage).");
+    }
+    let rawReport;
+    try {
+        rawReport = JSON.parse(readFileSync(reportPath, "utf8"));
+    }
+    catch (err) {
+        return configError(`coverage-hotspots: unreadable coverage report at ${reportPath}: ${String(err.message)}`);
+    }
+    const totals = summarizeCoverageFinal(rawReport);
+    const thresholds = readProjectCoverageThresholds(projectRoot);
+    const headroomPp = computeHeadroom(totals, thresholds);
+    let pathFilter = options.pathFilter ?? [];
+    if (pathFilter.length === 0 && useDiffPaths) {
+        try {
+            const baseRef = resolveBaseRef(projectRoot, options.baseRef);
+            pathFilter = diffPaths(projectRoot, baseRef);
+        }
+        catch (err) {
+            const message = err instanceof GitCommandError
+                ? `${err.message}\n  Recovery: pass explicit --path filters or run inside a git repo.`
+                : `coverage-hotspots: ${String(err.message)}`;
+            return configError(message);
+        }
+    }
+    const modules = [];
+    const uncoveredBranches = [];
+    for (const [rawKey, file] of Object.entries(rawReport)) {
+        const relPath = normalizeReportPath(projectRoot, rawKey, file);
+        modules.push(summarizeFileCoverage(relPath, file));
+        if (pathMatchesFilter(relPath, pathFilter)) {
+            uncoveredBranches.push(...collectUncoveredBranches(relPath, file));
+        }
+    }
+    modules.sort((a, b) => a.branches - b.branches || a.path.localeCompare(b.path));
+    const lowestModules = modules.slice(0, lowestModuleLimit);
+    uncoveredBranches.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.branchId.localeCompare(b.branchId));
+    const failReasons = evaluatePassFail(totals, thresholds, headroomPp, minHeadroomPp);
+    const report = {
+        ok: failReasons.length === 0,
+        global: totals,
+        thresholds,
+        headroomPp,
+        minHeadroomPp,
+        failReasons,
+        lowestModules,
+        uncoveredBranches,
+        pathFilter,
+        coverageReportPath: reportPath,
+    };
+    if (failReasons.length > 0) {
+        return {
+            exitCode: 1,
+            report,
+            message: formatTextReport(report, true),
+        };
+    }
+    return {
+        exitCode: 0,
+        report,
+        message: formatTextReport(report, false),
+    };
+}
+export function formatJsonReport(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+function metricLine(label, value, threshold, headroom) {
+    return `  ${label.padEnd(12)} ${value.toFixed(2)}%  (floor ${threshold}% | headroom ${headroom.toFixed(2)}pp)`;
+}
+export function formatTextReport(report, failed) {
+    const lines = [];
+    lines.push(failed ? "coverage-hotspots: FAIL" : "coverage-hotspots: OK");
+    lines.push(`report: ${report.coverageReportPath}`);
+    lines.push("global:");
+    lines.push(metricLine("branches", report.global.branches, report.thresholds.branches, report.headroomPp.branches));
+    lines.push(metricLine("lines", report.global.lines, report.thresholds.lines, report.headroomPp.lines));
+    lines.push(metricLine("functions", report.global.functions, report.thresholds.functions, report.headroomPp.functions));
+    lines.push(metricLine("statements", report.global.statements, report.thresholds.statements, report.headroomPp.statements));
+    lines.push(`min branch headroom: ${report.minHeadroomPp}pp`);
+    if (report.pathFilter.length > 0) {
+        lines.push(`path filter (${report.pathFilter.length}): ${report.pathFilter.slice(0, 8).join(", ")}${report.pathFilter.length > 8 ? ", ..." : ""}`);
+    }
+    if (report.failReasons.length > 0) {
+        lines.push("fail reasons:");
+        for (const reason of report.failReasons) {
+            lines.push(`  - ${reason}`);
+        }
+    }
+    if (report.lowestModules.length > 0) {
+        lines.push("lowest modules (branches):");
+        for (const mod of report.lowestModules.slice(0, 5)) {
+            lines.push(`  - ${mod.path}: branches ${mod.branches.toFixed(2)}%`);
+        }
+    }
+    if (report.uncoveredBranches.length > 0) {
+        lines.push("uncovered branch samples:");
+        for (const sample of report.uncoveredBranches.slice(0, 12)) {
+            lines.push(`  - ${sample.path}:${sample.line} (${sample.type} #${sample.branchId})`);
+        }
+        if (report.uncoveredBranches.length > 12) {
+            lines.push(`  ... ${report.uncoveredBranches.length - 12} more`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Re-export for tests that build synthetic reports. */
+export { summarizeCoverageFinal };
+//# sourceMappingURL=evaluate.js.map

package/dist/coverage-hotspots/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./thresholds.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/coverage-hotspots/index.js

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./thresholds.js";
+//# sourceMappingURL=index.js.map

package/dist/coverage-hotspots/thresholds.d.ts

@@ -0,0 +1,5 @@
+import { type CoverageMetric } from "../vitest-runner/coverage-debt.js";
+export type CoverageThresholds = Record<CoverageMetric, number>;
+/** Best-effort read of vitest coverage thresholds; falls back to framework 85% defaults. */
+export declare function readProjectCoverageThresholds(projectRoot: string): CoverageThresholds;
+//# sourceMappingURL=thresholds.d.ts.map

package/dist/coverage-hotspots/thresholds.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { COVERAGE_GOAL } from "../vitest-runner/coverage-debt.js";
+const VITEST_CONFIG_CANDIDATES = [
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.js",
+    "vitest.config.cjs",
+    "vitest.config.mjs",
+];
+const METRIC_PATTERN = /(?:^|[\n\r{,])\s*(branches|lines|functions|statements)\s*:\s*(\d+(?:\.\d+)?)/g;
+function parseMetricBlock(text, anchor) {
+    const match = anchor.exec(text);
+    if (match?.index === undefined)
+        return {};
+    const slice = text.slice(match.index, match.index + 800);
+    const out = {};
+    for (const metricMatch of slice.matchAll(METRIC_PATTERN)) {
+        const metric = metricMatch[1];
+        const value = metricMatch[2];
+        if (metric === undefined || value === undefined)
+            continue;
+        out[metric] = Number.parseFloat(value);
+    }
+    return out;
+}
+/** Best-effort read of vitest coverage thresholds; falls back to framework 85% defaults. */
+export function readProjectCoverageThresholds(projectRoot) {
+    for (const name of VITEST_CONFIG_CANDIDATES) {
+        const path = join(projectRoot, name);
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf8");
+        const fromCoverageThresholds = parseMetricBlock(text, /coverageThresholds\s*=\s*\{/);
+        const fromNested = parseMetricBlock(text, /thresholds\s*:\s*\{/);
+        const merged = { ...fromNested, ...fromCoverageThresholds };
+        if (Object.keys(merged).length > 0) {
+            return {
+                lines: merged.lines ?? COVERAGE_GOAL.lines,
+                functions: merged.functions ?? COVERAGE_GOAL.functions,
+                branches: merged.branches ?? COVERAGE_GOAL.branches,
+                statements: merged.statements ?? COVERAGE_GOAL.statements,
+            };
+        }
+    }
+    return { ...COVERAGE_GOAL };
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/hooks/dispatcher.d.ts

@@ -1,12 +1,19 @@
+import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type VerifyResult } from "../session/verify-session-ritual.js";
 import { type ActiveScopeInspection } from "./scope.js";
-export { DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool } from "./tools.js";
+export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isSpawnTool, READ_ONLY_HOOK_ENV, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
-export declare const HOOK_EVENTS: readonly ["session.start", "tool.before"];
+export declare const HOOK_EVENTS: readonly ["session.start", "session.compact", "tool.before"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Hosts that receive compact/resume hook deposits via init/update (#2113). */
+export declare const COMPACT_HOOK_HOSTS: readonly ["claude", "grok", "cursor"];
+export type CompactHookHost = (typeof COMPACT_HOOK_HOSTS)[number];
+/** Hosts without a native compact hook surface — deposit skips cleanly (#2113). */
+export declare const COMPACT_HOOK_SKIP_HOSTS: readonly ["codex"];
 export type HookVerdict = "allow" | "deny";
-export type HookDecisionCode = "session-start" | "session-start-degraded" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready";
+export type HookDecisionCode = "session-start" | "session-start-degraded" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready" | "spawn-ready" | "spawn-not-ready" | "runtime-policy-deny-path" | "runtime-policy-deny-scope";
 export interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -17,11 +24,19 @@ export interface HookDecision {
     readonly message: string;
     readonly scopePath: string | null;
 }
+/** Stdin parse metadata from hook-dispatch; absent when callers supply payload directly. */
+export interface HookPayloadContext {
+    readonly stdinEmpty?: boolean;
+    readonly parseFailed?: boolean;
+}
 export interface HookDispatchInput {
     readonly host: HookHost;
     readonly event: HookEvent;
     readonly projectRoot: string;
     readonly payload: unknown;
+    readonly payloadContext?: HookPayloadContext;
+    /** Injected for tests; defaults to `process.env`. */
+    readonly environ?: NodeJS.ProcessEnv;
 }
 export interface HookPolicySeams {
     readonly inspectRitual?: (projectRoot: string) => VerifyResult;
@@ -31,7 +46,14 @@ export interface HookPolicySeams {
         stdout: string;
         stderr: string;
     };
+    readonly markCompactStale?: (projectRoot: string) => {
+        changed: boolean;
+        statePath: string;
+        message: string;
+    };
+    readonly loadRuntimeAuthority?: (projectRoot: string) => RuntimeAuthorityPolicy;
 }
+export declare function hookPayloadTopLevelKeys(payload: unknown): string[];
 export declare function hookToolName(payload: unknown, host?: HookHost): string | null;
 /**
  * Best-effort write-target path from host PreToolUse payloads (#2625).