@deftai/directive-core 0.55.0

package/dist/codebase/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./constants.js";
+export * from "./default-extractor.js";
+export * from "./json.js";
+export * from "./map.js";
+export * from "./map-fresh.js";
+export * from "./projection-registry.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/codebase/index.js

@@ -0,0 +1,8 @@
+export * from "./constants.js";
+export * from "./default-extractor.js";
+export * from "./json.js";
+export * from "./map.js";
+export * from "./map-fresh.js";
+export * from "./projection-registry.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/codebase/json.d.ts

@@ -0,0 +1,14 @@
+/** Deep-sort object keys (mirrors Python json.dumps sort_keys=True). */
+export declare function sortKeysDeep(value: unknown): unknown;
+/**
+ * Escape every non-ASCII code unit to a `\uXXXX` sequence, mirroring Python's
+ * `json.dumps(..., ensure_ascii=True)` (the default). Iterating by UTF-16 code
+ * unit reproduces Python's surrogate-pair escaping for astral characters, so a
+ * digest taken over this output matches the Python oracle byte-for-byte.
+ */
+export declare function ensureAscii(text: string): string;
+/** JSON.stringify with sorted keys and 2-space indent (mirrors Python sort_keys + indent=2). */
+export declare function sortedStringifyPretty(value: unknown): string;
+/** Compact JSON with sorted keys (mirrors Python json.dumps sort_keys=True). */
+export declare function sortedStringifyCompact(value: unknown): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/codebase/json.js

@@ -0,0 +1,45 @@
+/** Deep-sort object keys (mirrors Python json.dumps sort_keys=True). */
+export function sortKeysDeep(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    const rec = value;
+    const out = {};
+    for (const key of Object.keys(rec).sort()) {
+        out[key] = sortKeysDeep(rec[key]);
+    }
+    return out;
+}
+/**
+ * Escape every non-ASCII code unit to a `\uXXXX` sequence, mirroring Python's
+ * `json.dumps(..., ensure_ascii=True)` (the default). Iterating by UTF-16 code
+ * unit reproduces Python's surrogate-pair escaping for astral characters, so a
+ * digest taken over this output matches the Python oracle byte-for-byte.
+ */
+export function ensureAscii(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        if (code > 0x7f) {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            out += text[i];
+        }
+    }
+    return out;
+}
+/** JSON.stringify with sorted keys and 2-space indent (mirrors Python sort_keys + indent=2). */
+export function sortedStringifyPretty(value) {
+    return `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`;
+}
+/** Compact JSON with sorted keys (mirrors Python json.dumps sort_keys=True). */
+export function sortedStringifyCompact(value) {
+    return JSON.stringify(sortKeysDeep(value))
+        .replace(/,/g, ", ")
+        .replace(/:(?=["[\-{0-9ntf])/g, ": ");
+}
+//# sourceMappingURL=json.js.map

package/dist/codebase/map-fresh.d.ts

@@ -0,0 +1,11 @@
+export declare function checkCodebaseMapFresh(projectRoot: string, options: {
+    outputPath: string;
+    artifactPath?: string | null;
+}): string[];
+export interface CodebaseMapFreshCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function runCodebaseMapFreshCli(argv: string[]): CodebaseMapFreshCliResult;
+//# sourceMappingURL=map-fresh.d.ts.map

package/dist/codebase/map-fresh.js

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { CodeStructureConfigError, configErrorToDict, defaultCodeStructurePath, } from "./default-extractor.js";
+import { sortedStringifyPretty } from "./json.js";
+import { GENERATED_SENTINEL, projectionOutputPath, renderCodebaseMap } from "./map.js";
+import { selectCodebaseMap } from "./provider.js";
+export function checkCodebaseMapFresh(projectRoot, options) {
+    const resolvedOutput = isAbsolute(options.outputPath)
+        ? options.outputPath
+        : join(projectRoot, options.outputPath);
+    if (!existsSync(resolvedOutput)) {
+        return [`generated codebase MAP is missing: ${resolvedOutput}`];
+    }
+    let current;
+    try {
+        current = readFileSync(resolvedOutput, { encoding: "utf8" });
+    }
+    catch (err) {
+        return [`generated codebase MAP could not be read: ${String(err)}`];
+    }
+    if (!current.slice(0, 4096).includes(GENERATED_SENTINEL)) {
+        return [`generated codebase MAP lacks the '${GENERATED_SENTINEL}' banner: ${resolvedOutput}`];
+    }
+    // Freshness tracks durable provider policy/artifact paths only; one-off
+    // `--generate-with` commands are intentionally not replayed by this gate.
+    const selection = selectCodebaseMap(projectRoot, null, { artifactPath: options.artifactPath });
+    const expected = renderCodebaseMap(selection.artifact);
+    if (current !== expected) {
+        return [
+            `generated codebase MAP is stale; run \`task codebase:map\` to refresh ${resolvedOutput}`,
+        ];
+    }
+    return [];
+}
+export function runCodebaseMapFreshCli(argv) {
+    let projectRoot = ".";
+    let output;
+    let artifactPath;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: "",
+                    stderr: "argument --project-root: expected one argument\n",
+                };
+            }
+            projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--output") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { exitCode: 2, stdout: "", stderr: "argument --output: expected one argument\n" };
+            }
+            output = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--output=")) {
+            output = arg.slice("--output=".length);
+        }
+        else if (arg === "--artifact-path") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: "",
+                    stderr: "argument --artifact-path: expected one argument\n",
+                };
+            }
+            artifactPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--artifact-path=")) {
+            artifactPath = arg.slice("--artifact-path=".length);
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+    }
+    const root = resolve(projectRoot);
+    let outputPath;
+    let errors;
+    try {
+        outputPath = projectionOutputPath(root, output);
+        errors = checkCodebaseMapFresh(root, { outputPath, artifactPath });
+    }
+    catch (err) {
+        if (err instanceof CodeStructureConfigError || err instanceof Error) {
+            const payload = sortedStringifyPretty(configErrorToDict(defaultCodeStructurePath(root), err));
+            if (json) {
+                return { exitCode: 2, stdout: payload, stderr: "" };
+            }
+            return { exitCode: 2, stdout: "", stderr: `${String(err)}\n` };
+        }
+        throw err;
+    }
+    const resolvedOutput = isAbsolute(outputPath) ? outputPath : join(root, outputPath);
+    if (json) {
+        return {
+            exitCode: errors.length > 0 ? 1 : 0,
+            stdout: sortedStringifyPretty({
+                ok: errors.length === 0,
+                path: resolvedOutput,
+                errors,
+            }),
+            stderr: "",
+        };
+    }
+    if (errors.length > 0) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `${errors.map((error) => `Error: ${error}`).join("\n")}\n`,
+        };
+    }
+    return { exitCode: 0, stdout: "OK: generated codebase MAP is fresh\n", stderr: "" };
+}
+//# sourceMappingURL=map-fresh.js.map

package/dist/codebase/map.d.ts

@@ -0,0 +1,19 @@
+export declare const GENERATED_SENTINEL = "AUTO-GENERATED by task codebase:map";
+export declare const DEFAULT_OUTPUT_PATH = ".planning/codebase/MAP.md";
+export declare const BANNER_TEMPLATE: string;
+export declare function projectionOutputPath(projectRoot: string, explicitOutput?: string | null): string;
+export declare function renderCodebaseMap(artifact: Record<string, unknown>): string;
+export declare function isDeftGenerated(path: string): boolean;
+export declare function writeCodebaseMap(projectRoot: string, options: {
+    outputPath: string;
+    artifactPath?: string | null;
+    generateWith?: string | null;
+    force?: boolean;
+}): string;
+export interface CodebaseMapCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function runCodebaseMapCli(argv: string[]): CodebaseMapCliResult;
+//# sourceMappingURL=map.d.ts.map

package/dist/codebase/map.js

@@ -0,0 +1,345 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
+import { CodeStructureConfigError, configErrorToDict, defaultCodeStructurePath, } from "./default-extractor.js";
+import { sortedStringifyPretty } from "./json.js";
+import { CODEBASE_MAP_KIND } from "./projection-registry.js";
+import { artifactSha256, selectCodebaseMap } from "./provider.js";
+export const GENERATED_SENTINEL = "AUTO-GENERATED by task codebase:map";
+export const DEFAULT_OUTPUT_PATH = ".planning/codebase/MAP.md";
+export const BANNER_TEMPLATE = "<!-- AUTO-GENERATED by task codebase:map -- DO NOT EDIT MANUALLY -->\n" +
+    "<!-- Purpose: generated codebase MAP projection -->\n" +
+    "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json " +
+    "plan.architecture.codeStructure -->\n" +
+    "<!-- Regenerate with: task codebase:map -->\n";
+function markdownText(value) {
+    const text = value === null || value === undefined ? "" : String(value);
+    return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
+}
+function code(value) {
+    const text = markdownText(value);
+    if (text.length === 0) {
+        return "";
+    }
+    return `\`${text.replace(/`/g, "")}\``;
+}
+function joinCode(values, limit) {
+    if (!Array.isArray(values)) {
+        return "";
+    }
+    let items = values.filter((item) => typeof item === "string" && item.trim().length > 0);
+    let truncated = false;
+    if (limit !== undefined && items.length > limit) {
+        items = items.slice(0, limit);
+        truncated = true;
+    }
+    let rendered = items.map((item) => code(item)).join(", ");
+    if (truncated) {
+        rendered = `${rendered}, ...`;
+    }
+    return rendered;
+}
+function posixPath(path) {
+    return path.replace(/\\/g, "/");
+}
+function displayPath(pathValue, projectRootValue) {
+    if (typeof pathValue !== "string" || pathValue.length === 0) {
+        return "";
+    }
+    if (typeof projectRootValue !== "string" || projectRootValue.length === 0) {
+        return pathValue;
+    }
+    const rel = posixPath(relative(resolve(projectRootValue), resolve(pathValue)));
+    if (rel === "" || rel.startsWith("../") || rel === ".." || isAbsolute(rel)) {
+        return pathValue;
+    }
+    return rel;
+}
+function sourceDigest(artifact) {
+    const source = artifact.source;
+    if (typeof source !== "object" || source === null || Array.isArray(source)) {
+        return artifactSha256(artifact);
+    }
+    const contentHash = source.contentHash;
+    if (typeof contentHash === "object" &&
+        contentHash !== null &&
+        !Array.isArray(contentHash) &&
+        typeof contentHash.value === "string") {
+        return String(contentHash.value);
+    }
+    return artifactSha256(artifact);
+}
+export function projectionOutputPath(projectRoot, explicitOutput) {
+    if (explicitOutput !== undefined && explicitOutput !== null && explicitOutput.length > 0) {
+        return explicitOutput;
+    }
+    const projectDefinition = join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    if (!existsSync(projectDefinition)) {
+        return DEFAULT_OUTPUT_PATH;
+    }
+    const data = loadJsonFile(projectDefinition);
+    const extracted = extractCodeStructure(data);
+    if (extracted === null) {
+        return DEFAULT_OUTPUT_PATH;
+    }
+    const manifest = extracted.record.projectionManifest;
+    if (!Array.isArray(manifest)) {
+        return DEFAULT_OUTPUT_PATH;
+    }
+    for (const entry of manifest) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            continue;
+        }
+        const rec = entry;
+        if (rec.kind === CODEBASE_MAP_KIND && typeof rec.path === "string") {
+            return rec.path;
+        }
+    }
+    return DEFAULT_OUTPUT_PATH;
+}
+export function renderCodebaseMap(artifact) {
+    const source = typeof artifact.source === "object" &&
+        artifact.source !== null &&
+        !Array.isArray(artifact.source)
+        ? artifact.source
+        : {};
+    const provider = typeof artifact.provider === "object" &&
+        artifact.provider !== null &&
+        !Array.isArray(artifact.provider)
+        ? artifact.provider
+        : {};
+    const sourcePath = displayPath(source.codeStructurePath, source.projectRoot);
+    const sourceHome = source.codeStructureHome || "directory-derived fallback";
+    const artifactDigest = artifactSha256(artifact);
+    const digest = sourceDigest(artifact);
+    const lines = [
+        BANNER_TEMPLATE.trimEnd(),
+        `<!-- Artifact sha256: ${artifactDigest} -->`,
+        `<!-- Source digest sha256: ${digest} -->`,
+        "",
+        "# Codebase MAP",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        `| Projection kind | ${code(artifact.kind)} |`,
+        `| Format | ${code(artifact.formatVersion)} |`,
+        `| Provider | ${code(provider.name)} ${code(provider.version)} |`,
+        `| Provider mode | ${code(provider.mode)} |`,
+        `| Source | ${code(sourcePath)} at ${code(sourceHome)} |`,
+        `| Source digest | ${code(digest)} |`,
+        "",
+        "## Modules",
+        "",
+        "| Module | Name | Purpose | Paths | Files |",
+        "| --- | --- | --- | --- | ---: |",
+    ];
+    const modules = Array.isArray(artifact.modules) ? artifact.modules : [];
+    for (const module of modules) {
+        if (typeof module !== "object" || module === null || Array.isArray(module)) {
+            continue;
+        }
+        const rec = module;
+        let fileCount = rec.fileCount;
+        if (typeof fileCount !== "number" || !Number.isInteger(fileCount)) {
+            const files = rec.files;
+            fileCount = Array.isArray(files) ? files.length : 0;
+        }
+        lines.push("| " +
+            `${code(rec.id)} | ` +
+            `${markdownText(rec.name)} | ` +
+            `${markdownText(rec.purpose)} | ` +
+            `${joinCode(rec.pathGlobs, 4)} | ` +
+            `${fileCount} |`);
+    }
+    lines.push("", "## Coupling", "");
+    const coupling = Array.isArray(artifact.coupling)
+        ? artifact.coupling.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+    if (coupling.length > 0) {
+        lines.push("| From | To | Confidence | Evidence |", "| --- | --- | --- | --- |");
+        for (const edge of coupling) {
+            let evidenceText = "";
+            const evidence = edge.evidence;
+            if (Array.isArray(evidence) && evidence.length > 0) {
+                const first = evidence[0];
+                if (typeof first === "object" && first !== null && !Array.isArray(first)) {
+                    const rec = first;
+                    evidenceText = `${rec.path ?? ""}:${rec.line ?? ""} imports ${rec.import ?? ""}`;
+                }
+            }
+            lines.push("| " +
+                `${code(edge.from)} | ` +
+                `${code(edge.to)} | ` +
+                `${markdownText(edge.confidence)} | ` +
+                `${markdownText(evidenceText)} |`);
+        }
+    }
+    else {
+        lines.push("No cross-module coupling was reported by the selected artifact.");
+    }
+    lines.push("", "## Entry Points", "");
+    const entryPoints = Array.isArray(artifact.entryPoints)
+        ? artifact.entryPoints.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+    if (entryPoints.length > 0) {
+        lines.push("| Path | Module | Confidence |", "| --- | --- | --- |");
+        for (const entry of entryPoints) {
+            lines.push("| " +
+                `${code(entry.path)} | ` +
+                `${code(entry.module)} | ` +
+                `${markdownText(entry.confidence)} |`);
+        }
+    }
+    else {
+        lines.push("No entry points were reported by the selected artifact.");
+    }
+    lines.push("", "## Languages", "");
+    const languages = Array.isArray(artifact.languageDistribution)
+        ? artifact.languageDistribution.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+    if (languages.length > 0) {
+        lines.push("| Language | Files |", "| --- | ---: |");
+        for (const entry of languages) {
+            lines.push(`| ${markdownText(entry.language)} | ${markdownText(entry.files)} |`);
+        }
+    }
+    else {
+        lines.push("No language distribution was reported by the selected artifact.");
+    }
+    lines.push("", "## Degraded Signals", "");
+    const degraded = Array.isArray(artifact.degraded)
+        ? artifact.degraded.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+    if (degraded.length > 0) {
+        for (const entry of degraded) {
+            lines.push(`- ${code(entry.code)}: ${markdownText(entry.message)}`);
+        }
+    }
+    else {
+        lines.push("No degraded signals were reported by the selected artifact.");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+export function isDeftGenerated(path) {
+    if (!existsSync(path)) {
+        return true;
+    }
+    try {
+        return readFileSync(path, { encoding: "utf8" }).slice(0, 4096).includes(GENERATED_SENTINEL);
+    }
+    catch {
+        return false;
+    }
+}
+export function writeCodebaseMap(projectRoot, options) {
+    const resolvedOutput = isAbsolute(options.outputPath)
+        ? options.outputPath
+        : join(projectRoot, options.outputPath);
+    if (!options.force && !isDeftGenerated(resolvedOutput)) {
+        throw new Error(`refusing to overwrite non-generated MAP at ${resolvedOutput}; ` +
+            `missing '${GENERATED_SENTINEL}' banner`);
+    }
+    const selection = selectCodebaseMap(projectRoot, options.generateWith, {
+        artifactPath: options.artifactPath,
+    });
+    const document = renderCodebaseMap(selection.artifact);
+    mkdirSync(dirname(resolvedOutput), { recursive: true });
+    writeFileSync(resolvedOutput, document, { encoding: "utf8" });
+    return resolvedOutput;
+}
+export function runCodebaseMapCli(argv) {
+    let projectRoot = ".";
+    let output;
+    let artifactPath;
+    let generateWith;
+    let stdout = false;
+    let force = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: "",
+                    stderr: "argument --project-root: expected one argument\n",
+                };
+            }
+            projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--output") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { exitCode: 2, stdout: "", stderr: "argument --output: expected one argument\n" };
+            }
+            output = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--output=")) {
+            output = arg.slice("--output=".length);
+        }
+        else if (arg === "--artifact-path") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: "",
+                    stderr: "argument --artifact-path: expected one argument\n",
+                };
+            }
+            artifactPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--artifact-path=")) {
+            artifactPath = arg.slice("--artifact-path=".length);
+        }
+        else if (arg === "--generate-with") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: "",
+                    stderr: "argument --generate-with: expected one argument\n",
+                };
+            }
+            generateWith = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--generate-with=")) {
+            generateWith = arg.slice("--generate-with=".length);
+        }
+        else if (arg === "--stdout") {
+            stdout = true;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+    }
+    const root = resolve(projectRoot);
+    try {
+        const outputPath = projectionOutputPath(root, output);
+        const resolvedOutput = isAbsolute(outputPath) ? outputPath : join(root, outputPath);
+        if (stdout) {
+            const selection = selectCodebaseMap(root, generateWith, { artifactPath });
+            const document = renderCodebaseMap(selection.artifact);
+            return { exitCode: 0, stdout: document, stderr: "" };
+        }
+        writeCodebaseMap(root, { outputPath, artifactPath, generateWith, force });
+        return { exitCode: 0, stdout: `Codebase MAP written to ${resolvedOutput}\n`, stderr: "" };
+    }
+    catch (err) {
+        if (err instanceof CodeStructureConfigError || err instanceof Error) {
+            return {
+                exitCode: 2,
+                stdout: "",
+                stderr: sortedStringifyPretty(configErrorToDict(defaultCodeStructurePath(root), err)),
+            };
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=map.js.map

package/dist/codebase/projection-registry.d.ts

@@ -0,0 +1,25 @@
+export declare const CODEBASE_MAP_KIND = "codebase-map";
+export declare const CODEBASE_MAP_FORMAT_VERSION = "codebase-map.v1";
+export declare const CODEBASE_PROVIDER_CONTRACT_VERSION = "codebase-provider.v1";
+export interface ProjectionKind {
+    readonly kind: string;
+    readonly artifact_format_version: string;
+    readonly provider_contract_version: string;
+    readonly output_role: string;
+    readonly generate_action: string;
+    readonly freshness_action: string;
+    readonly description: string;
+}
+/** Return registered projection kinds in deterministic order. */
+export declare function listProjectionKinds(): ProjectionKind[];
+/** Resolve one projection kind or throw with a useful message. */
+export declare function resolveProjectionKind(kind: string): ProjectionKind;
+export declare function projectionKindToDict(entry: ProjectionKind): Record<string, string>;
+export interface ProjectionRegistryCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** CLI entry point for registry inspection. */
+export declare function runProjectionRegistryCli(argv: string[]): ProjectionRegistryCliResult;
+//# sourceMappingURL=projection-registry.d.ts.map