@deftai/directive-core 0.55.0

package/dist/vbrief-validate/main.js

@@ -0,0 +1,127 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { evaluateConformance } from "./conformance.js";
+import { USAGE } from "./constants.js";
+import { validateAll } from "./validate-all.js";
+/** CLI entry for vbrief_validate.py parity. */
+export function runValidate(argv) {
+    let vbriefDir = "vbrief";
+    let strictOriginTypes = false;
+    let warningsAsErrors = false;
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "--vbrief-dir" && i + 1 < argv.length) {
+            vbriefDir = argv[i + 1] ?? vbriefDir;
+            i += 2;
+        }
+        else if (arg === "--strict-origin-types") {
+            strictOriginTypes = true;
+            i += 1;
+        }
+        else if (arg === "--warnings-as-errors") {
+            warningsAsErrors = true;
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        }
+        else {
+            process.stderr.write(`Unknown argument: ${arg}\n`);
+            process.stderr.write(`${USAGE}\n`);
+            return 2;
+        }
+    }
+    if (!existsSync(vbriefDir)) {
+        process.stdout.write(`OK: No vbrief directory at ${vbriefDir} -- skipping validation\n`);
+        return 0;
+    }
+    const { errors, warnings, scopeCount } = validateAll(vbriefDir, { strictOriginTypes });
+    for (const w of warnings) {
+        process.stdout.write(`WARN: ${w}\n`);
+    }
+    for (const e of errors) {
+        process.stdout.write(`FAIL: ${e}\n`);
+    }
+    const warningsEscalated = warnings.length > 0 && warningsAsErrors;
+    const exitCode = errors.length > 0 || warningsEscalated ? 1 : 0;
+    if (exitCode === 0) {
+        const parts = [];
+        if (scopeCount > 0) {
+            parts.push(`${scopeCount} scope vBRIEF(s)`);
+        }
+        const projectDef = resolve(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+        if (existsSync(projectDef)) {
+            parts.push("PROJECT-DEFINITION");
+        }
+        const summary = parts.length > 0 ? parts.join(", ") : "no vBRIEF files";
+        const warningNote = warnings.length > 0 ? ` (${warnings.length} warning(s))` : "";
+        process.stdout.write(`OK: vBRIEF validation passed: ${summary}${warningNote}\n`);
+    }
+    else {
+        if (errors.length > 0) {
+            process.stdout.write(`\nFAIL: ${errors.length} error(s) found\n`);
+        }
+        if (warningsEscalated && errors.length === 0) {
+            process.stdout.write(`\nFAIL: ${warnings.length} warning(s) treated as errors (--warnings-as-errors)\n`);
+        }
+    }
+    return exitCode;
+}
+/** CLI entry for verify_vbrief_conformance.py parity. */
+export function runConformance(argv) {
+    let mode = "all";
+    let projectRoot = ".";
+    let allowList = null;
+    let quiet = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--all") {
+            mode = "all";
+        }
+        else if (arg === "--staged") {
+            mode = "staged";
+        }
+        else if (arg === "--quiet") {
+            quiet = true;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = argv[i + 1] ?? projectRoot;
+            i += 1;
+        }
+        else if (arg === "--allow-list") {
+            allowList = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: verify_vbrief_conformance [--all | --staged] [--project-root PATH] [--allow-list PATH] [--quiet]\n");
+            return 0;
+        }
+        else {
+            process.stderr.write(`verify_vbrief_conformance: unrecognized argument: ${arg}\n`);
+            return 2;
+        }
+    }
+    const allowListPath = allowList !== null ? resolve(allowList) : null;
+    const { exitCode, message } = evaluateConformance(resolve(projectRoot), {
+        mode,
+        allowListPath,
+    });
+    if (exitCode === 0) {
+        if (!quiet) {
+            process.stdout.write(`${message}\n`);
+        }
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+    return exitCode;
+}
+export function cmdVbriefValidate(argv) {
+    if (argv[0] === "conformance") {
+        return runConformance(argv.slice(1));
+    }
+    return runValidate(argv);
+}
+//# sourceMappingURL=main.js.map

package/dist/vbrief-validate/origin.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject } from "./schema.js";
+/** Warn if a scope vBRIEF in pending/ or active/ has no origin reference (D11). */
+export declare function validateOriginProvenance(filepath: string, data: JsonObject, vbriefDir: string, strictOriginTypes?: boolean): string[];
+//# sourceMappingURL=origin.d.ts.map

package/dist/vbrief-validate/origin.js

@@ -0,0 +1,76 @@
+import { LEGACY_ORIGIN_TYPES, STRICT_ORIGIN_ALLOWLIST } from "./constants.js";
+import { lifecycleFolderFor } from "./paths.js";
+function legacyOriginMatch(refType) {
+    if (LEGACY_ORIGIN_TYPES.has(refType)) {
+        return true;
+    }
+    for (const legacy of LEGACY_ORIGIN_TYPES) {
+        if (refType.startsWith(`${legacy}-`) || refType.startsWith(`${legacy}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function schemaTrustingOrigin(refType) {
+    return refType.startsWith("x-vbrief/");
+}
+/** Warn if a scope vBRIEF in pending/ or active/ has no origin reference (D11). */
+export function validateOriginProvenance(filepath, data, vbriefDir, strictOriginTypes = false) {
+    const folder = lifecycleFolderFor(filepath, vbriefDir);
+    if (folder !== "pending" && folder !== "active") {
+        return [];
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const refs = plan.references;
+    if (!Array.isArray(refs)) {
+        return strictOriginTypes
+            ? [
+                `${filepath}: scope vBRIEF in '${folder}/' has no references ` +
+                    "with an allow-listed origin type (D11; " +
+                    "--strict-origin-types)",
+            ]
+            : [
+                `${filepath}: scope vBRIEF in '${folder}/' has no references ` +
+                    "with an origin type (D11)",
+            ];
+    }
+    let hasOrigin = false;
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+            continue;
+        }
+        const refType = ref.type;
+        if (typeof refType !== "string") {
+            continue;
+        }
+        if (legacyOriginMatch(refType)) {
+            hasOrigin = true;
+            break;
+        }
+        if (strictOriginTypes) {
+            if (STRICT_ORIGIN_ALLOWLIST.has(refType)) {
+                hasOrigin = true;
+                break;
+            }
+        }
+        else if (schemaTrustingOrigin(refType)) {
+            hasOrigin = true;
+            break;
+        }
+    }
+    if (!hasOrigin) {
+        if (strictOriginTypes) {
+            return [
+                `${filepath}: scope vBRIEF in '${folder}/' has no references with an allow-listed origin type (D11; --strict-origin-types)`,
+            ];
+        }
+        return [
+            `${filepath}: scope vBRIEF in '${folder}/' has no references with an origin type (D11)`,
+        ];
+    }
+    return [];
+}
+//# sourceMappingURL=origin.js.map

package/dist/vbrief-validate/paths.d.ts

@@ -0,0 +1,11 @@
+/** Return true when ``child`` resolves under ``parent``. */
+export declare function isRelativeTo(child: string, parent: string): boolean;
+/** Resolve a reference URI to an absolute filesystem path. */
+export declare function resolveRefPath(uri: string, vbriefDir: string): string | null;
+/** Return possible PROJECT-DEFINITION registry IDs for a local scope URI. */
+export declare function scopeIdsForRefUri(uri: string): Set<string>;
+/** Return the lifecycle folder name when ``filePath`` lives under ``vbriefDir``. */
+export declare function lifecycleFolderFor(filePath: string, vbriefDir: string): string | null;
+/** Display path matching Python ``str(Path)`` for paths discovered under vbriefDir. */
+export declare function displayPath(filePath: string, vbriefDir: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/vbrief-validate/paths.js

@@ -0,0 +1,83 @@
+import { basename, relative, resolve, sep } from "node:path";
+/** Return true when ``child`` resolves under ``parent``. */
+export function isRelativeTo(child, parent) {
+    const resolvedParent = resolve(parent);
+    const resolvedChild = resolve(child);
+    if (resolvedChild === resolvedParent) {
+        return true;
+    }
+    const prefix = resolvedParent.endsWith(sep) ? resolvedParent : `${resolvedParent}${sep}`;
+    return resolvedChild.startsWith(prefix);
+}
+/** Resolve a reference URI to an absolute filesystem path. */
+export function resolveRefPath(uri, vbriefDir) {
+    if (typeof uri !== "string") {
+        return null;
+    }
+    if (uri.startsWith("file://")) {
+        const rel = uri.slice("file://".length);
+        return resolve(vbriefDir, rel);
+    }
+    if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("#")) {
+        return null;
+    }
+    return resolve(vbriefDir, uri);
+}
+/** Split like Python ``str.split(sep, maxsplit)`` (maxsplit splits, not result length). */
+function splitMax(value, sep, maxsplit) {
+    if (maxsplit <= 0) {
+        return value.split(sep);
+    }
+    const out = [];
+    let rest = value;
+    for (let i = 0; i < maxsplit; i += 1) {
+        const idx = rest.indexOf(sep);
+        if (idx === -1) {
+            break;
+        }
+        out.push(rest.slice(0, idx));
+        rest = rest.slice(idx + sep.length);
+    }
+    out.push(rest);
+    return out;
+}
+/** Return possible PROJECT-DEFINITION registry IDs for a local scope URI. */
+export function scopeIdsForRefUri(uri) {
+    const rel = uri.startsWith("file://") ? uri.slice("file://".length) : uri;
+    const name = basename(rel);
+    const fullId = name.endsWith(".vbrief.json") ? name.slice(0, -".vbrief.json".length) : name;
+    const ids = new Set([fullId]);
+    const parts = splitMax(fullId, "-", 3);
+    if (parts.length === 4 &&
+        parts[0]?.length === 4 &&
+        parts[1]?.length === 2 &&
+        parts[2]?.length === 2 &&
+        parts.slice(0, 3).every((part) => /^\d+$/.test(part))) {
+        ids.add(parts[3] ?? "");
+    }
+    return ids;
+}
+/** Return the lifecycle folder name when ``filePath`` lives under ``vbriefDir``. */
+export function lifecycleFolderFor(filePath, vbriefDir) {
+    try {
+        const rel = relative(resolve(vbriefDir), resolve(filePath));
+        const parts = rel.split(sep).filter(Boolean);
+        if (parts.length < 2) {
+            return null;
+        }
+        return parts[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Display path matching Python ``str(Path)`` for paths discovered under vbriefDir. */
+export function displayPath(filePath, vbriefDir) {
+    try {
+        return relative(resolve(vbriefDir, ".."), resolve(filePath)).split(sep).join("/");
+    }
+    catch {
+        return filePath.split(sep).join("/");
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/vbrief-validate/placeholders.d.ts

@@ -0,0 +1,3 @@
+/** Check that deprecated root markdown files contain redirect sentinels (#334). */
+export declare function validateDeprecatedPlaceholders(vbriefDir: string): string[];
+//# sourceMappingURL=placeholders.d.ts.map

package/dist/vbrief-validate/placeholders.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { DEPRECATED_FILES } from "./constants.js";
+import { isCurrentGeneratedSpecification, isDeprecationRedirect } from "./precutover.js";
+/** Check that deprecated root markdown files contain redirect sentinels (#334). */
+export function validateDeprecatedPlaceholders(vbriefDir) {
+    const warnings = [];
+    const projectRoot = resolve(vbriefDir, "..");
+    for (const filename of DEPRECATED_FILES) {
+        const filepath = join(projectRoot, filename);
+        if (!existsSync(filepath)) {
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(filepath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (isDeprecationRedirect(content)) {
+            continue;
+        }
+        if (filename === "SPECIFICATION.md" && isCurrentGeneratedSpecification(projectRoot, content)) {
+            continue;
+        }
+        warnings.push(`${filename} contains non-redirect content -- ` +
+            "this file is deprecated; use scope vBRIEFs " +
+            "in vbrief/ instead");
+    }
+    return warnings;
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/vbrief-validate/plan-hooks.d.ts

@@ -0,0 +1,9 @@
+/** vbrief_validate hook: validate ``plan.policy.wipCap`` (#1124). */
+export declare function validateWipCapOnPlan(plan: unknown, filepath: string): string[];
+/** vbrief_validate hook for ``sessionRitualStalenessHours`` (#1348). */
+export declare function validateSessionRitualStalenessHoursOnPlan(plan: unknown, filepath: string): string[];
+/** vbrief_validate hook: validate ``plan.policy.triageRankingLabels`` (#1128). */
+export declare function validateTriageRankingLabelsOnPlan(plan: unknown, filepath: string): string[];
+/** Run all PROJECT-DEFINITION policy hooks (mirrors lazy-import block in Python). */
+export declare function runProjectDefinitionHooks(plan: unknown, filepath: string): string[];
+//# sourceMappingURL=plan-hooks.d.ts.map

package/dist/vbrief-validate/plan-hooks.js

@@ -0,0 +1,145 @@
+import { validateTriageAutoClassifyOnPlan, validateTriageHoldMarkersOnPlan, } from "../triage/classify/index.js";
+import { validateRankingLabels } from "../triage/queue/ranking-labels.js";
+import { pyStrRepr, pythonTypeName } from "../triage/scope/python-repr.js";
+import { validateTriageScopeIgnoresOnPlan, validateTriageScopeOnPlan, } from "../triage/scope/validate.js";
+function validateWipCap(value) {
+    const errors = [];
+    if (value === null || value === undefined) {
+        return errors;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        const repr = typeof value === "string"
+            ? pyStrRepr(value)
+            : value === null
+                ? "None"
+                : typeof value === "boolean"
+                    ? value
+                        ? "True"
+                        : "False"
+                    : String(value);
+        errors.push(`plan.policy.wipCap must be an integer; got ${pythonTypeName(value)} (${repr})`);
+        return errors;
+    }
+    if (value < 0) {
+        errors.push(`plan.policy.wipCap must be >= 0; got ${value}`);
+    }
+    return errors;
+}
+/** vbrief_validate hook: validate ``plan.policy.wipCap`` (#1124). */
+export function validateWipCapOnPlan(plan, filepath) {
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const policy = plan.policy;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return [];
+    }
+    if (!("wipCap" in policy)) {
+        return [];
+    }
+    const out = [];
+    for (const err of validateWipCap(policy.wipCap)) {
+        out.push(`${filepath}: ${err} (#1124)`);
+    }
+    return out;
+}
+function validateSessionRitualStalenessHours(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        const repr = typeof value === "string"
+            ? pyStrRepr(value)
+            : value === null
+                ? "None"
+                : typeof value === "boolean"
+                    ? value
+                        ? "True"
+                        : "False"
+                    : String(value);
+        return [
+            "plan.policy.sessionRitualStalenessHours must be an integer; got " +
+                `${pythonTypeName(value)} (${repr})`,
+        ];
+    }
+    if (value <= 0) {
+        return [`plan.policy.sessionRitualStalenessHours must be > 0; got ${value}`];
+    }
+    return [];
+}
+/** vbrief_validate hook for ``sessionRitualStalenessHours`` (#1348). */
+export function validateSessionRitualStalenessHoursOnPlan(plan, filepath) {
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const policy = plan.policy;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return [];
+    }
+    if (!("sessionRitualStalenessHours" in policy)) {
+        return [];
+    }
+    const out = [];
+    for (const err of validateSessionRitualStalenessHours(policy.sessionRitualStalenessHours)) {
+        out.push(`${filepath}: ${err} (#1348)`);
+    }
+    return out;
+}
+/** vbrief_validate hook: validate ``plan.policy.triageRankingLabels`` (#1128). */
+export function validateTriageRankingLabelsOnPlan(plan, filepath) {
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const policy = plan.policy;
+    const raw = typeof policy === "object" && policy !== null && !Array.isArray(policy)
+        ? policy.triageRankingLabels
+        : undefined;
+    if (raw === undefined || raw === null) {
+        return [];
+    }
+    const { errors } = validateRankingLabels(raw);
+    return errors.map((err) => `${filepath}: ${err} (#1128)`);
+}
+/** Run all PROJECT-DEFINITION policy hooks (mirrors lazy-import block in Python). */
+export function runProjectDefinitionHooks(plan, filepath) {
+    const errors = [];
+    try {
+        errors.push(...validateTriageScopeOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateTriageScopeIgnoresOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateTriageAutoClassifyOnPlan(plan, filepath));
+        errors.push(...validateTriageHoldMarkersOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateTriageRankingLabelsOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateWipCapOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateSessionRitualStalenessHoursOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    return errors;
+}
+//# sourceMappingURL=plan-hooks.js.map

package/dist/vbrief-validate/precutover.d.ts

@@ -0,0 +1,7 @@
+import { DEPRECATION_SENTINEL } from "../vbrief-build/constants.js";
+export { DEPRECATION_SENTINEL as DEPRECATED_REDIRECT_SENTINEL };
+/** Return true when markdown content is a migration redirect stub. */
+export declare function isDeprecationRedirect(content: string): boolean;
+/** Return true for a fully current ``task spec:render`` root export. */
+export declare function isCurrentGeneratedSpecification(projectRoot: string, content: string): boolean;
+//# sourceMappingURL=precutover.d.ts.map

package/dist/vbrief-validate/precutover.js

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DEPRECATION_SENTINEL } from "../vbrief-build/constants.js";
+export { DEPRECATION_SENTINEL as DEPRECATED_REDIRECT_SENTINEL };
+const DEPRECATION_REDIRECT_PURPOSE = "<!-- Purpose: deprecation redirect -->";
+const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
+const GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+const SPEC_SOURCE_RELPATH = join("vbrief", "specification.vbrief.json");
+const LIFECYCLE_FOLDERS = ["proposed", "pending", "active", "completed", "cancelled"];
+function missingLifecycleFolders(projectRoot) {
+    const vbriefRoot = join(projectRoot, "vbrief");
+    return LIFECYCLE_FOLDERS.filter((folder) => !existsSync(join(vbriefRoot, folder)));
+}
+function hasCompleteLifecycle(projectRoot) {
+    return missingLifecycleFolders(projectRoot).length === 0;
+}
+/** Return true when markdown content is a migration redirect stub. */
+export function isDeprecationRedirect(content) {
+    return content.includes(DEPRECATION_SENTINEL) || content.includes(DEPRECATION_REDIRECT_PURPOSE);
+}
+function isGeneratedSpecificationExport(projectRoot, content) {
+    return (content.includes(GENERATED_SPEC_PURPOSE) &&
+        content.includes(GENERATED_SPEC_SOURCE) &&
+        existsSync(join(projectRoot, SPEC_SOURCE_RELPATH)));
+}
+/** Return true for a fully current ``task spec:render`` root export. */
+export function isCurrentGeneratedSpecification(projectRoot, content) {
+    return isGeneratedSpecificationExport(projectRoot, content) && hasCompleteLifecycle(projectRoot);
+}
+//# sourceMappingURL=precutover.js.map

package/dist/vbrief-validate/project-definition.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject } from "./schema.js";
+/** Validate PROJECT-DEFINITION.vbrief.json specific requirements (D3). */
+export declare function validateProjectDefinition(filepath: string, data: JsonObject, vbriefDir: string): string[];
+//# sourceMappingURL=project-definition.d.ts.map