@deftai/directive-core 0.55.0

package/dist/vbrief-validation/safety.js

@@ -0,0 +1,422 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+export const PREMIGRATE_SUFFIX = ".premigrate";
+export const SAFETY_MANIFEST_NAME = "safety-manifest.json";
+export const MIGRATION_DIR = "migration";
+export const LEGACY_DIR = "legacy";
+const ROOT_MD_INPUTS = ["SPECIFICATION.md", "PROJECT.md", "ROADMAP.md", "PRD.md"];
+const VBRIEF_JSON_INPUTS = ["specification.vbrief.json", "plan.vbrief.json"];
+const DEPRECATION_SENTINEL_DEFAULT = "<!-- deft:deprecated-redirect -->";
+export class SafetyManifest {
+    version;
+    migration_timestamp;
+    backups;
+    created_files;
+    created_dirs;
+    post_migration_stub_hashes;
+    renames;
+    file_modifications;
+    constructor(data = {}) {
+        this.version = data.version ?? "1";
+        this.migration_timestamp = data.migration_timestamp ?? "";
+        this.backups = data.backups ?? [];
+        this.created_files = data.created_files ?? [];
+        this.created_dirs = data.created_dirs ?? [];
+        this.post_migration_stub_hashes = data.post_migration_stub_hashes ?? {};
+        this.renames = data.renames ?? [];
+        this.file_modifications = data.file_modifications ?? [];
+    }
+    toJson() {
+        const payload = {
+            version: this.version,
+            migration_timestamp: this.migration_timestamp,
+            backups: this.backups,
+            created_files: [...this.created_files],
+            created_dirs: [...this.created_dirs],
+            post_migration_stub_hashes: { ...this.post_migration_stub_hashes },
+            renames: this.renames,
+            file_modifications: this.file_modifications,
+        };
+        return `${JSON.stringify(payload, null, 2)}\n`;
+    }
+    static fromJson(raw) {
+        const data = JSON.parse(raw);
+        const backups = (data.backups ?? []).map((b) => b);
+        const renames = (data.renames ?? []).map((r) => r);
+        const fileMods = (data.file_modifications ?? []).map((m) => m);
+        return new SafetyManifest({
+            version: String(data.version ?? "1"),
+            migration_timestamp: String(data.migration_timestamp ?? ""),
+            backups,
+            created_files: data.created_files ?? [],
+            created_dirs: data.created_dirs ?? [],
+            post_migration_stub_hashes: data.post_migration_stub_hashes ?? {},
+            renames,
+            file_modifications: fileMods,
+        });
+    }
+    currentPathFor(original) {
+        let resolved = original;
+        for (let hop = 0; hop < this.renames.length + 1; hop += 1) {
+            let target = resolved;
+            for (const record of this.renames) {
+                if (record.original === resolved) {
+                    target = record.current;
+                }
+            }
+            if (target === resolved) {
+                break;
+            }
+            resolved = target;
+        }
+        return resolved;
+    }
+}
+export function premigrateSibling(path) {
+    const name = path.split(/[/\\]/).pop() ?? path;
+    const dir = dirname(path);
+    if (name.includes(".")) {
+        const dot = name.indexOf(".");
+        const stem = name.slice(0, dot);
+        const rest = name.slice(dot + 1);
+        return join(dir, `${stem}${PREMIGRATE_SUFFIX}.${rest}`);
+    }
+    return join(dir, `${name}${PREMIGRATE_SUFFIX}`);
+}
+function isDeprecationStub(path, sentinel = DEPRECATION_SENTINEL_DEFAULT) {
+    try {
+        const head = readFileSync(path, { encoding: "utf8", flag: "r" }).slice(0, 4096);
+        return head.includes(sentinel);
+    }
+    catch {
+        return false;
+    }
+}
+function rel(projectRoot, target) {
+    try {
+        return relative(projectRoot, target).split("\\").join("/");
+    }
+    catch {
+        return target.split("\\").join("/");
+    }
+}
+export function planBackups(projectRoot, options = {}) {
+    const sentinel = options.deprecationSentinel ?? DEPRECATION_SENTINEL_DEFAULT;
+    const pairs = [];
+    for (const name of ROOT_MD_INPUTS) {
+        const src = join(projectRoot, name);
+        try {
+            if (statSync(src).isFile() && !isDeprecationStub(src, sentinel)) {
+                pairs.push([src, premigrateSibling(src)]);
+            }
+        }
+        catch {
+            // skip missing
+        }
+    }
+    const vbriefDir = join(projectRoot, "vbrief");
+    for (const name of VBRIEF_JSON_INPUTS) {
+        const src = join(vbriefDir, name);
+        try {
+            if (statSync(src).isFile() && !isDeprecationStub(src, sentinel)) {
+                pairs.push([src, premigrateSibling(src)]);
+            }
+        }
+        catch {
+            // skip missing
+        }
+    }
+    return pairs;
+}
+export function writeBackups(projectRoot, pairs, options) {
+    const records = [];
+    const actions = [];
+    for (const [src, dst] of pairs) {
+        const raw = readFileSync(src);
+        const digest = createHash("sha256").update(raw).digest("hex");
+        const size = raw.length;
+        const relSrc = rel(projectRoot, src);
+        const relDst = rel(projectRoot, dst);
+        if (!options.dryRun) {
+            mkdirSync(dirname(dst), { recursive: true });
+            copyFileSync(src, dst);
+        }
+        records.push({
+            source: relSrc,
+            backup: relDst,
+            source_sha256: digest,
+            size_bytes: size,
+        });
+        const tag = options.dryRun ? "DRYRUN BACKUP" : "BACKUP";
+        actions.push(`${tag} ${relSrc} -> ${relDst} (${size} bytes)`);
+    }
+    return [records, actions];
+}
+export function isTreeDirty(projectRoot) {
+    try {
+        const result = spawnSync("git", ["status", "--porcelain"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            timeout: 30_000,
+        });
+        if (result.error || result.status !== 0) {
+            return false;
+        }
+        return Boolean(String(result.stdout ?? "").trim());
+    }
+    catch {
+        return false;
+    }
+}
+export function dirtyTreeRefusalMessage() {
+    return ("ERROR: Working tree is not clean. Migration is destructive; commit " +
+        "or stash your changes first, then re-run.\n" +
+        "       Bypass with: task migrate:vbrief -- --force (not recommended)");
+}
+export function manifestPath(projectRoot) {
+    return join(projectRoot, "vbrief", MIGRATION_DIR, SAFETY_MANIFEST_NAME);
+}
+export function writeSafetyManifest(projectRoot, manifest, options) {
+    const target = manifestPath(projectRoot);
+    const relTarget = rel(projectRoot, target);
+    if (options.dryRun) {
+        return `DRYRUN WRITE ${relTarget} (safety manifest)`;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, manifest.toJson(), "utf8");
+    return `WRITE ${relTarget} (safety manifest, ${manifest.backups.length} backup(s))`;
+}
+export function loadSafetyManifest(projectRoot) {
+    const path = manifestPath(projectRoot);
+    try {
+        if (!statSync(path).isFile()) {
+            return null;
+        }
+        return SafetyManifest.fromJson(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function sha256Of(path) {
+    try {
+        if (!statSync(path).isFile()) {
+            return "";
+        }
+        return createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
+function defaultConfirm(prompt) {
+    try {
+        process.stdout.write(`${prompt} [yes/NO]: `);
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function nowUtcIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function rollback(projectRoot, options = {}) {
+    const force = options.force ?? false;
+    const actions = [];
+    const manifest = loadSafetyManifest(projectRoot);
+    if (manifest === null) {
+        return [
+            false,
+            [
+                "ERROR: No safety manifest found. Either migration has not run, or rollback has already completed. Expected " +
+                    `${rel(projectRoot, manifestPath(projectRoot))}.`,
+            ],
+        ];
+    }
+    const editedStubs = [];
+    for (const [relPathKey, expectedHash] of Object.entries(manifest.post_migration_stub_hashes)) {
+        const current = sha256Of(join(projectRoot, relPathKey));
+        if (current && current !== expectedHash) {
+            editedStubs.push([relPathKey, expectedHash, current]);
+        }
+    }
+    if (editedStubs.length > 0 && !force) {
+        const lines = ["ERROR: Redirect stubs have been edited since migration:"];
+        for (const [relPathKey, expected, current] of editedStubs) {
+            lines.push(`  - ${relPathKey} (expected sha256 ${expected.slice(0, 12)}..., got ${current.slice(0, 12)}...)`);
+        }
+        lines.push("Rollback would overwrite your edits. Re-run with --force to proceed anyway, or commit the stubs before rolling back.");
+        return [false, lines];
+    }
+    const editedModifications = [];
+    for (const mod of manifest.file_modifications) {
+        const current = sha256Of(join(projectRoot, mod.path));
+        if (!current) {
+            continue;
+        }
+        if (current === mod.pre_hash || current === mod.post_hash) {
+            continue;
+        }
+        editedModifications.push([mod.path, mod.pre_hash, mod.post_hash, current]);
+    }
+    if (editedModifications.length > 0 && !force) {
+        const lines = ["ERROR: Migrator-modified file(s) have been edited since migration:"];
+        for (const [relPathKey, pre, post, current] of editedModifications) {
+            lines.push(`  - ${relPathKey} (expected sha256 ${post.slice(0, 12)}... or ${pre.slice(0, 12)}..., got ${current.slice(0, 12)}...)`);
+        }
+        lines.push("Rollback would overwrite your edits. Re-run with --force to proceed anyway, or commit the file(s) before rolling back.");
+        return [false, lines];
+    }
+    if (!force) {
+        const promptFn = options.confirmFn ?? defaultConfirm;
+        const summary = `Rollback will restore ${manifest.backups.length} backup(s) and ` +
+            `remove ${manifest.created_files.length} migrator-created file(s). Proceed?`;
+        if (!promptFn(summary)) {
+            return [false, ["Rollback aborted by operator."]];
+        }
+    }
+    const missingBackups = manifest.backups
+        .map((record) => record.backup)
+        .filter((backupRel) => !existsSync(join(projectRoot, backupRel)));
+    if (missingBackups.length > 0) {
+        const lines = [
+            "ERROR: Backup file(s) missing -- cannot restore all sources:",
+            ...missingBackups.map((p) => `  - ${p}`),
+            "Manifest preserved for investigation. Resolve the missing .premigrate.* file(s) (or restore from VCS) and retry `task migrate:vbrief -- --rollback`.",
+        ];
+        return [false, [...actions, ...lines]];
+    }
+    for (const record of manifest.backups) {
+        const backupPath = join(projectRoot, record.backup);
+        const sourcePath = join(projectRoot, record.source);
+        mkdirSync(dirname(sourcePath), { recursive: true });
+        copyFileSync(backupPath, sourcePath);
+        actions.push(`RESTORE ${record.source} <- ${record.backup} (${record.size_bytes} bytes)`);
+    }
+    const sortedCreated = [...manifest.created_files].sort((a, b) => b.split("/").length - a.split("/").length);
+    for (const relFile of sortedCreated) {
+        const currentRel = manifest.currentPathFor(relFile);
+        const path = join(projectRoot, currentRel);
+        try {
+            if (statSync(path).isFile()) {
+                unlinkSync(path);
+                if (currentRel !== relFile) {
+                    actions.push(`REMOVE ${currentRel} (renamed from ${relFile})`);
+                }
+                else {
+                    actions.push(`REMOVE ${relFile}`);
+                }
+            }
+            else if (currentRel !== relFile) {
+                actions.push(`SKIP   ${currentRel} (already absent; renamed from ${relFile})`);
+            }
+            else {
+                actions.push(`SKIP   ${relFile} (already absent)`);
+            }
+        }
+        catch {
+            if (currentRel !== relFile) {
+                actions.push(`SKIP   ${currentRel} (already absent; renamed from ${relFile})`);
+            }
+            else {
+                actions.push(`SKIP   ${relFile} (already absent)`);
+            }
+        }
+    }
+    const sortedDirs = [...manifest.created_dirs].sort((a, b) => b.split("/").length - a.split("/").length);
+    for (const relDir of sortedDirs) {
+        const path = join(projectRoot, relDir);
+        try {
+            if (statSync(path).isDirectory()) {
+                rmSync(path, { recursive: false });
+                actions.push(`RMDIR  ${relDir}`);
+            }
+        }
+        catch {
+            actions.push(`SKIP   rmdir ${relDir} (not empty)`);
+        }
+    }
+    for (const mod of manifest.file_modifications) {
+        const target = join(projectRoot, mod.path);
+        const current = sha256Of(target);
+        if (mod.operation === "create") {
+            try {
+                if (current && statSync(target).isFile()) {
+                    unlinkSync(target);
+                    actions.push(`REMOVE ${mod.path} (created by migrator)`);
+                }
+                else {
+                    actions.push(`SKIP   ${mod.path} (already absent)`);
+                }
+            }
+            catch {
+                actions.push(`SKIP   ${mod.path} (already absent)`);
+            }
+            continue;
+        }
+        if (mod.operation === "append") {
+            if (!current) {
+                actions.push(`SKIP   ${mod.path} (file no longer exists; nothing to strip)`);
+                continue;
+            }
+            if (current === mod.pre_hash) {
+                actions.push(`SKIP   ${mod.path} (already at pre-migration hash)`);
+                continue;
+            }
+            try {
+                const body = readFileSync(target, "utf8");
+                if (body.endsWith(mod.appended_content)) {
+                    writeFileSync(target, body.slice(0, -mod.appended_content.length), "utf8");
+                    actions.push(`REVERT ${mod.path} (stripped ${mod.appended_content.length} appended byte(s))`);
+                }
+                else {
+                    actions.push(`SKIP   ${mod.path} (content shape drifted; cannot strip append cleanly -- restore manually)`);
+                }
+            }
+            catch {
+                actions.push(`SKIP   ${mod.path} (unreadable; cannot strip append)`);
+            }
+            continue;
+        }
+        actions.push(`SKIP   ${mod.path} (unknown operation '${mod.operation}')`);
+    }
+    for (const record of manifest.backups) {
+        const backupPath = join(projectRoot, record.backup);
+        try {
+            if (statSync(backupPath).isFile()) {
+                unlinkSync(backupPath);
+                actions.push(`REMOVE ${record.backup}`);
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    const mPath = manifestPath(projectRoot);
+    try {
+        if (statSync(mPath).isFile()) {
+            unlinkSync(mPath);
+            actions.push(`REMOVE ${rel(projectRoot, mPath)}`);
+        }
+    }
+    catch {
+        // skip
+    }
+    for (const parent of [dirname(mPath), dirname(dirname(mPath))]) {
+        try {
+            if (statSync(parent).isDirectory() && readdirSync(parent).length === 0) {
+                rmSync(parent, { recursive: false });
+                actions.push(`RMDIR  ${rel(projectRoot, parent)}`);
+            }
+        }
+        catch {
+            // non-empty
+        }
+    }
+    actions.push("Rollback completed successfully.");
+    return [true, actions];
+}
+//# sourceMappingURL=safety.js.map

package/dist/vbrief-validation/story-quality.d.ts

@@ -0,0 +1,29 @@
+import type { JsonObject } from "./types.js";
+export declare const BROAD_FILE_SCOPE_ROOTS: Set<string>;
+export declare const CODE_PATH_TERMS: readonly ["api", "cli", "component", "config", "database", "endpoint", "file", "handler", "model", "module", "repository", "route", "schema", "script", "service", "source", "src/"];
+export declare const VERIFY_EVIDENCE_TERMS: readonly ["assert", "evidence", "fixture", "report", "spec", "test", "tests/", "verify"];
+export declare const GENERIC_VERIFY_COMMANDS: Set<string>;
+export declare const PLACEHOLDER_ACCEPTANCE_PATTERNS: readonly ["acceptance criteria for", "copy from parent", "copy from specification", "placeholder", "refine from parent", "tbd", "to be defined", "to refine", "to refine from parent scope", "todo"];
+export declare const DOCS_ONLY_ACCEPTANCE_PATTERNS: readonly ["docs updated", "documentation updated", "readme updated", "update docs", "update documentation", "update readme"];
+export declare const GENERIC_IMPLEMENTATION_PATTERNS: readonly ["add tests so it works", "change the code", "implement the feature", "make it work", "update the code", "works as expected"];
+export declare const VAGUE_ACCEPTANCE_PATTERNS: readonly ["displays a message", "handles errors", "is implemented", "is updated", "passes tests", "shows a message", "the system displays a message", "updates the ui", "works as expected"];
+export declare const OBSERVABLE_TERMS: readonly ["blocks", "creates", "deletes", "displays", "emits", "fails", "persists", "records", "redirects", "rejects", "renders", "returns", "saves", "shows", "stores", "updates", "validates", "when ", "given ", "then "];
+export declare function asStrList(value: unknown): string[];
+export declare function acceptanceTextsFromItems(items: unknown): string[];
+export declare function itemHasAcceptance(item: JsonObject): boolean;
+export declare function itemsHaveAcceptance(items: unknown): boolean;
+export declare function itemHasTraces(item: JsonObject): boolean;
+export declare function missingRequiredSwarmFields(swarm: JsonObject): string[];
+export declare function deprecatedSubitemsIssues(items: unknown, prefix?: string): string[];
+export interface StoryQualityParams {
+    readonly title: string;
+    readonly description: string;
+    readonly implementationPlan: string;
+    readonly userStory: string;
+    readonly acceptanceTexts: readonly string[];
+    readonly acceptanceCountJustification: string;
+    readonly swarm: JsonObject;
+    readonly concurrentReady?: boolean;
+}
+export declare function storyQualityIssues(params: StoryQualityParams): string[];
+//# sourceMappingURL=story-quality.d.ts.map