@deftai/directive-core 0.78.0 → 0.79.1

package/dist/vitest-runner/coverage-debt.js

@@ -0,0 +1,155 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Shared coverage goal (vitest thresholds). */
+export const COVERAGE_GOAL = {
+    lines: 85,
+    functions: 85,
+    branches: 85,
+    statements: 85,
+};
+const DEBT_FLAG = "--allow-coverage-debt";
+const DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
+const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
+/** Parse `#2573`, `2573`, or bare numeric strings. */
+export function parseCoverageDebtIssueNumber(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const normalized = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+    if (!/^\d+$/.test(normalized))
+        return null;
+    const issue = Number.parseInt(normalized, 10);
+    return Number.isFinite(issue) && issue > 0 ? issue : null;
+}
+/** Parse `--allow-coverage-debt=#N` tokens from argv. */
+export function parseCoverageDebtArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? "";
+        if (token === DEBT_FLAG) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                return { kind: "invalid", reason: `${DEBT_FLAG} requires an issue number (#N)` };
+            }
+            const issue = parseCoverageDebtIssueNumber(next);
+            return issue === null
+                ? { kind: "invalid", reason: `${DEBT_FLAG} value must be #N or N` }
+                : { kind: "valid", issue };
+        }
+        if (token.startsWith(`${DEBT_FLAG}=`)) {
+            const value = token.slice(DEBT_FLAG.length + 1);
+            const issue = parseCoverageDebtIssueNumber(value);
+            return issue === null
+                ? { kind: "invalid", reason: `${DEBT_FLAG}= value must be #N or N` }
+                : { kind: "valid", issue };
+        }
+    }
+    return { kind: "none" };
+}
+/**
+ * Resolve coverage-debt issue from argv or release-scoped env (#2573 / #1553).
+ * Raw env bypass is accepted only during release Step-5 preflight.
+ */
+export function resolveCoverageDebtIssue(argv, env = process.env) {
+    const fromArgv = parseCoverageDebtArgv(argv);
+    if (fromArgv.kind !== "none")
+        return fromArgv;
+    const rawEnv = env[DEBT_ENV];
+    if (rawEnv && env[RELEASE_PREFLIGHT_ENV] === "1") {
+        const issue = parseCoverageDebtIssueNumber(rawEnv);
+        return issue === null
+            ? { kind: "invalid", reason: `${DEBT_ENV} must be a positive integer` }
+            : { kind: "valid", issue };
+    }
+    return { kind: "none" };
+}
+/** Aggregate global coverage percentages from istanbul coverage-final.json. */
+export function summarizeCoverageFinal(coverageFinal) {
+    let stmtTotal = 0;
+    let stmtCovered = 0;
+    let fnTotal = 0;
+    let fnCovered = 0;
+    let branchTotal = 0;
+    let branchCovered = 0;
+    for (const file of Object.values(coverageFinal)) {
+        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 pct = (covered, total) => total === 0 ? 100 : (covered / total) * 100;
+    const statements = pct(stmtCovered, stmtTotal);
+    const functions = pct(fnCovered, fnTotal);
+    const branches = pct(branchCovered, branchTotal);
+    // Istanbul coverage-final.json does not carry pre-aggregated line hit counts —
+    // `l` (line map) is optional and its format differs from `s`/`f`/`b`. Using
+    // statements as a proxy may overstate line coverage when multiple statements
+    // share a single uncovered line.
+    return {
+        statements,
+        functions,
+        branches,
+        lines: statements, // approximation: actual line coverage may differ
+    };
+}
+export function readCoverageTotalsFromReport(coverageDir) {
+    const finalPath = join(coverageDir, "coverage-final.json");
+    try {
+        const raw = readFileSync(finalPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return summarizeCoverageFinal(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function metricsBelowGoal(totals) {
+    const missed = [];
+    for (const metric of Object.keys(COVERAGE_GOAL)) {
+        if (totals[metric] + 1e-9 < COVERAGE_GOAL[metric]) {
+            missed.push(metric);
+        }
+    }
+    return missed;
+}
+const sanitizeMetric = (value) => String(value).replace(/\r?\n/g, " ");
+export function formatCoverageAttribution(issue, totals) {
+    const lines = [
+        `coverage-debt: soft-pass acknowledged for issue #${issue}`,
+        `  measured: branches ${sanitizeMetric(totals.branches.toFixed(2))}% | lines ${sanitizeMetric(totals.lines.toFixed(2))}% | functions ${sanitizeMetric(totals.functions.toFixed(2))}% | statements ${sanitizeMetric(totals.statements.toFixed(2))}%`,
+        `  goal:     branches ${sanitizeMetric(COVERAGE_GOAL.branches)}% | lines ${sanitizeMetric(COVERAGE_GOAL.lines)}% | functions ${sanitizeMetric(COVERAGE_GOAL.functions)}% | statements ${sanitizeMetric(COVERAGE_GOAL.statements)}%`,
+    ];
+    return lines.join("\n");
+}
+/** Count recent release sections citing coverage-debt (CHANGELOG scan). */
+export function countRecentCoverageDebtMentions(changelog, maxSections = 5) {
+    const versionHeader = /^## \[(?!Unreleased)/m;
+    const sections = changelog.split(versionHeader).slice(1, maxSections + 1);
+    const pattern = /coverage[- ]debt soft[- ]pass|allow-coverage-debt=#?\d/i;
+    return sections.filter((section) => pattern.test(section)).length;
+}
+export function formatOveruseWarning(recentCount) {
+    if (recentCount < 2)
+        return null;
+    return (`coverage-debt WARN: ${recentCount} of the last release sections already cite coverage debt — ` +
+        "consider restoring real coverage instead of reusing the escape hatch.");
+}
+//# sourceMappingURL=coverage-debt.js.map

package/dist/vitest-runner/win32-coverage-tmp-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Win32 globalSetup for coverage runs (#2580).
+ *
+ * Vitest's v8 provider writes per-suite JSON under coverage/.tmp without always
+ * re-mkdir'ing before writeFile. Under parallel fork load the directory can
+ * disappear mid-suite, surfacing as ENOENT after an otherwise green run.
+ * Keep the directory present for the coordinator process; late ENOENT flakes
+ * are tolerated via vitest dangerouslyIgnoreUnhandledErrors (#2546) without
+ * soft-failing real coverage threshold failures.
+ */
+export default function setup(): void;
+//# sourceMappingURL=win32-coverage-tmp-setup.d.ts.map

package/dist/vitest-runner/win32-coverage-tmp-setup.js

@@ -0,0 +1,24 @@
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+const COVERAGE_TMP = resolve(process.cwd(), "coverage", ".tmp");
+function ensureCoverageTmpDir() {
+    mkdirSync(COVERAGE_TMP, { recursive: true });
+}
+/**
+ * Win32 globalSetup for coverage runs (#2580).
+ *
+ * Vitest's v8 provider writes per-suite JSON under coverage/.tmp without always
+ * re-mkdir'ing before writeFile. Under parallel fork load the directory can
+ * disappear mid-suite, surfacing as ENOENT after an otherwise green run.
+ * Keep the directory present for the coordinator process; late ENOENT flakes
+ * are tolerated via vitest dangerouslyIgnoreUnhandledErrors (#2546) without
+ * soft-failing real coverage threshold failures.
+ */
+export default function setup() {
+    if (process.platform !== "win32")
+        return;
+    ensureCoverageTmpDir();
+    const keepalive = setInterval(ensureCoverageTmpDir, 100);
+    keepalive.unref?.();
+}
+//# sourceMappingURL=win32-coverage-tmp-setup.js.map

package/dist/xbrief-migrate/detect.js

@@ -33,6 +33,51 @@ function walkJsonFiles(root, acc = []) {
     }
     return acc;
 }
+/** Cache support state may contain only ordinary files/directories, never links or special files. */
+function containsUnsupportedCacheEntry(root) {
+    if (!isDirectory(root))
+        return false;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            return true;
+        if (entry.isDirectory()) {
+            if (containsUnsupportedCacheEntry(join(root, entry.name)))
+                return true;
+            continue;
+        }
+        if (!entry.isFile())
+            return true;
+    }
+    return false;
+}
+/**
+ * A top-level `.triage-cache/` is operational support state, not evidence that
+ * project artifacts have already migrated. Everything else keeps the generic
+ * empty-tree semantics; unknown files and symlinks remain real content.
+ */
+function xbriefHasProjectContent(root) {
+    if (!isDirectory(root))
+        return false;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const full = join(root, entry.name);
+        if (entry.name === ".triage-cache" && entry.isDirectory()) {
+            if (containsUnsupportedCacheEntry(full))
+                return true;
+            continue;
+        }
+        if (entry.isSymbolicLink())
+            return true;
+        if (entry.isDirectory()) {
+            if (!isEffectivelyEmptyDir(full))
+                return true;
+            continue;
+        }
+        if (entry.isFile() && (entry.name === ".gitkeep" || entry.name === ".keep"))
+            continue;
+        return true;
+    }
+    return false;
+}
 function scanFileContent(path, content, reasons) {
     if (path.endsWith(LEGACY_ARTIFACT_SUFFIX)) {
         reasons.add(`legacy artifact filename: ${path}`);
@@ -94,7 +139,7 @@ export function detectXbriefConvergence(projectRoot) {
     const vbriefHasMarker = vbriefPresent && hasVbriefDeprecationMarker(legacyDir);
     const vbriefEmpty = vbriefPresent && !vbriefHasMarker && isEffectivelyEmptyDir(legacyDir);
     const xbriefPresent = isDirectory(migratedDir);
-    const xbriefHasContent = xbriefPresent && !isEffectivelyEmptyDir(migratedDir);
+    const xbriefHasContent = xbriefPresent && xbriefHasProjectContent(migratedDir);
     let state;
     if (vbriefHasMarker) {
         state = "xbrief-marker";

package/dist/xbrief-migrate/migrate-project.js

@@ -6,6 +6,7 @@ import { patchAgentsMdHeader, renderHeaderPatchSummary } from "./agents-header.j
 import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
 import { detectLegacyVbriefLayout, detectXbriefConvergence } from "./detect.js";
 import { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir } from "./fs-helpers.js";
+import { assertMigrationSourceSafe } from "./migration-containment.js";
 import { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
 import { rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional } from "./transforms.js";
 function collectFiles(root, acc = []) {
@@ -45,19 +46,32 @@ function writeMigratedFile(srcPath, destPath) {
     const raw = readFileSync(srcPath, "utf8");
     writeFileSync(destPath, rewriteEmbeddedTokens(raw), "utf8");
 }
-function backupLegacyTree(projectRoot, legacyDir) {
+function backupMigrationInputs(projectRoot, legacyDir, migratedDir) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     const backupRoot = join(projectRoot, ".deft", `xbrief-migrate-backup-${stamp}`);
     mkdirSync(backupRoot, { recursive: true });
     cpSync(legacyDir, join(backupRoot, LEGACY_ARTIFACT_DIR), { recursive: true });
+    if (existsSync(migratedDir)) {
+        cpSync(migratedDir, join(backupRoot, MIGRATED_ARTIFACT_DIR), { recursive: true });
+    }
     return backupRoot;
 }
+/** Overlay the already-canonical cache last so it wins collisions. */
+function overlayCanonicalTriageCache(migratedDir, stagedDir) {
+    const source = join(migratedDir, ".triage-cache");
+    if (!isDirectory(source))
+        return;
+    cpSync(source, join(stagedDir, ".triage-cache"), { recursive: true, force: true });
+}
 function migrateLegacyTree(projectRoot, legacyDir, options) {
     const migratedDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
-    if (existsSync(migratedDir)) {
-        throw new Error(`refusing to migrate: '${MIGRATED_ARTIFACT_DIR}/' already exists alongside '${LEGACY_ARTIFACT_DIR}/'`);
+    const convergence = detectXbriefConvergence(projectRoot);
+    const hasCanonicalCache = isDirectory(join(migratedDir, ".triage-cache"));
+    if (existsSync(migratedDir) && (convergence.xbriefHasContent || !hasCanonicalCache)) {
+        throw new Error(`refusing to migrate: '${MIGRATED_ARTIFACT_DIR}/' already exists alongside '${LEGACY_ARTIFACT_DIR}/' and is not a cache-only support tree`);
     }
-    const backupDir = backupLegacyTree(projectRoot, legacyDir);
+    assertMigrationSourceSafe(projectRoot, legacyDir);
+    const backupDir = backupMigrationInputs(projectRoot, legacyDir, migratedDir);
     const stagedDir = join(projectRoot, `.${MIGRATED_ARTIFACT_DIR}.migrate-staging`);
     if (existsSync(stagedDir)) {
         rmSync(stagedDir, { recursive: true, force: true });
@@ -70,6 +84,7 @@ function migrateLegacyTree(projectRoot, legacyDir, options) {
             const destPath = join(stagedDir, mapRelativePath(rel));
             writeMigratedFile(srcPath, destPath);
         }
+        overlayCanonicalTriageCache(migratedDir, stagedDir);
         renameOrReplace(stagedDir, migratedDir);
         // Converge to a single unambiguous root: the fully-migrated legacy tree is
         // either removed (default) or retained for read-compat behind an explicit

package/dist/xbrief-migrate/migration-containment.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Refuse migrate:xbrief when legacy `vbrief/` (or any traversed entry) escapes
+ * the project tree via symlinks (#2601).
+ */
+export declare function assertMigrationSourceSafe(projectRoot: string, legacyDir: string): void;
+//# sourceMappingURL=migration-containment.d.ts.map

package/dist/xbrief-migrate/migration-containment.js

@@ -0,0 +1,37 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
+/**
+ * Refuse migrate:xbrief when legacy `vbrief/` (or any traversed entry) escapes
+ * the project tree via symlinks (#2601).
+ */
+export function assertMigrationSourceSafe(projectRoot, legacyDir) {
+    assertProjectionContained(projectRoot, legacyDir);
+    walkMigrationTreeRejectSymlinks(legacyDir);
+}
+function walkMigrationTreeRejectSymlinks(root) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(root, entry.name);
+        let info;
+        try {
+            info = lstatSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (info.isSymbolicLink()) {
+            throw new Error(`refusing to migrate: symlink on migration path: ${full}`);
+        }
+        if (info.isDirectory()) {
+            walkMigrationTreeRejectSymlinks(full);
+        }
+    }
+}
+//# sourceMappingURL=migration-containment.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -278,6 +278,10 @@
       "types": "./dist/umbrella-current-shape/index.d.ts",
       "default": "./dist/umbrella-current-shape/index.js"
     },
+    "./issue-sync": {
+      "types": "./dist/issue-sync/index.d.ts",
+      "default": "./dist/issue-sync/index.js"
+    },
     "./task-surface": {
       "types": "./dist/task-surface/index.d.ts",
       "default": "./dist/task-surface/index.js"
@@ -301,8 +305,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.78.0",
-    "@deftai/directive-types": "^0.78.0",
+    "@deftai/directive-content": "^0.79.1",
+    "@deftai/directive-types": "^0.79.1",
     "archiver": "^8.0.0"
   },
   "scripts": {