project-tiny-context-harness 0.8.16 → 0.11.0

package/dist/lib/context-move/context-move-live-validation.js

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import { analyzeContextMarkdownCatalog } from "../context-markdown/context-markdown-analysis.js";
+import { resolveCatalogFile } from "../context-catalog/catalog-paths.js";
+import { assertProtectedRepositoryFile } from "../repository-path-safety.js";
+import { validateContextContentForRole } from "../validators.js";
+import { scanStagedRepositoryForContextPath } from "./context-move-literal-scan.js";
+import { issueSignatures } from "./context-move-reference-validation.js";
+export async function validateLiveContextMove(repository, catalog, journal) {
+    if (journal.operation_data.kind !== "move")
+        invalid("move_data_required");
+    const data = journal.operation_data;
+    const owners = catalog.registered_contexts.filter((entry) => entry.path === data.to_path);
+    if (owners.length !== 1 ||
+        owners[0].source !== data.owner_source ||
+        owners[0].role !== data.role ||
+        (owners[0].read_policy ?? null) !== data.read_policy ||
+        catalog.registered_contexts.some((entry) => entry.path === data.from_path))
+        invalid("live_move_owner_mismatch");
+    const targetFile = resolveCatalogFile(catalog, data.to_path);
+    if (!targetFile)
+        invalid("live_move_target_missing");
+    const target = await assertProtectedRepositoryFile(repository, targetFile.absolute_path, "context_mutation_moved_context");
+    const content = await readFile(target, "utf8");
+    const recoveryErrors = validateContextContentForRole(repository, data.to_path, content, data.role);
+    if (recoveryErrors.length)
+        invalid(`live_move_recovery:${recoveryErrors.join("|")}`);
+    const analysis = await analyzeContextMarkdownCatalog({
+        project_root: repository,
+        files: catalog.context_files,
+        long_line_threshold: Number.MAX_SAFE_INTEGER,
+    });
+    if (analysis.references.some((entry) => entry.target_path === data.from_path))
+        invalid("live_move_stale_markdown_reference");
+    if (!sameArray(issueSignatures(analysis), data.expected_reference_issues))
+        invalid("live_move_reference_issues_mismatch");
+    const scan = await scanStagedRepositoryForContextPath({
+        repository,
+        logical_context_path: data.from_path,
+        physical_context_path: journal.files.find((entry) => entry.path === data.from_path)
+            ?.physical_path ?? data.from_path,
+        file_overrides: new Map(),
+    });
+    if (!scan.complete)
+        invalid(`live_move_scan_incomplete:${scan.limits_exceeded.join("|")}`);
+    if (scan.matches.length)
+        invalid(`live_move_unresolved_literals:${scan.matches
+            .map((entry) => `${entry.path}:${entry.line}`)
+            .join(",")}`);
+}
+function sameArray(left, right) {
+    return (left.length === right.length &&
+        left.every((entry, index) => entry === right[index]));
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}

package/dist/lib/context-move/context-move-markdown-plan.d.ts

@@ -0,0 +1,22 @@
+export interface ContextMoveMarkdownPlan {
+    target_content: string;
+    updated_context_files: Map<string, string>;
+    references_updated: Array<{
+        source_path: string;
+        line: number;
+        column: number;
+        previous_destination: string;
+        next_destination: string;
+    }>;
+}
+export declare function planContextMoveMarkdown(input: {
+    files: ReadonlyMap<string, {
+        path: string;
+        physical_path: string;
+        content: string;
+    }>;
+    from_path: string;
+    to_path: string;
+    from_physical_path: string;
+    to_physical_path: string;
+}): ContextMoveMarkdownPlan;

package/dist/lib/context-move/context-move-markdown-plan.js

@@ -0,0 +1,39 @@
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { patchMarkdownLinksForContextMove } from "../context-mutation/markdown-link-patch.js";
+export function planContextMoveMarkdown(input) {
+    const source = input.files.get(input.from_path);
+    if (source === undefined)
+        throw new Error(`context_move_source_content_missing:${input.from_path}`);
+    const updated = new Map();
+    const references = [];
+    let targetContent = source.content;
+    for (const [file, markdown] of [...input.files].sort(([left], [right]) => compareUtf8Paths(left, right))) {
+        const patch = patchMarkdownLinksForContextMove({
+            content: markdown.content,
+            source_path: file,
+            source_physical_path: markdown.physical_path,
+            from_path: input.from_path,
+            from_physical_path: input.from_physical_path,
+            to_path: input.to_path,
+            to_physical_path: input.to_physical_path,
+        });
+        const outputPath = file === input.from_path ? input.to_path : file;
+        if (file === input.from_path)
+            targetContent = patch.content;
+        else if (patch.content !== markdown.content)
+            updated.set(file, patch.content);
+        for (const change of patch.changes)
+            references.push({
+                source_path: outputPath,
+                line: change.line,
+                column: change.column,
+                previous_destination: change.previous_destination,
+                next_destination: change.next_destination,
+            });
+    }
+    return {
+        target_content: targetContent,
+        updated_context_files: updated,
+        references_updated: references,
+    };
+}

package/dist/lib/context-move/context-move-projection.d.ts

@@ -0,0 +1,3 @@
+import type { ContextFootprintState } from "../context-mutation/mutation-types.js";
+import type { ContextMoveResult } from "./context-move-types.js";
+export declare function contextMoveFootprintDiff(before: ContextFootprintState, after: ContextFootprintState): ContextMoveResult["default_footprint"];

package/dist/lib/context-move/context-move-projection.js

@@ -0,0 +1,11 @@
+import { sameMutationArray } from "../context-mutation/mutation-command-support.js";
+export function contextMoveFootprintDiff(before, after) {
+    return {
+        changed: before.bytes !== after.bytes ||
+            !sameMutationArray(before.paths, after.paths),
+        before,
+        after,
+        added: after.paths.filter((file) => !before.paths.includes(file)),
+        removed: before.paths.filter((file) => !after.paths.includes(file)),
+    };
+}

package/dist/lib/context-move/context-move-reference-validation.d.ts

@@ -0,0 +1,11 @@
+import type { ContextMarkdownCatalogAnalysis } from "../context-markdown/context-markdown-types.js";
+import type { ContextCatalog } from "../context-catalog/catalog-types.js";
+export declare function validateStagedContextMoveReferences(input: {
+    repository: string;
+    before_catalog: ContextCatalog;
+    after_catalog: ContextCatalog;
+    file_overrides: ReadonlyMap<string, Uint8Array | null>;
+    from_path: string;
+    to_path: string;
+}): Promise<string[]>;
+export declare function issueSignatures(analysis: ContextMarkdownCatalogAnalysis): string[];

package/dist/lib/context-move/context-move-reference-validation.js

@@ -0,0 +1,64 @@
+import { analyzeContextMarkdownCatalog } from "../context-markdown/context-markdown-analysis.js";
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { mutationCatalogFailure } from "../context-mutation/mutation-command-support.js";
+export async function validateStagedContextMoveReferences(input) {
+    const before = await analyzeContextMarkdownCatalog({
+        project_root: input.repository,
+        files: input.before_catalog.context_files,
+        long_line_threshold: Number.MAX_SAFE_INTEGER,
+    });
+    const after = await analyzeContextMarkdownCatalog({
+        project_root: input.repository,
+        files: input.after_catalog.context_files,
+        long_line_threshold: Number.MAX_SAFE_INTEGER,
+        file_overrides: input.file_overrides,
+    });
+    const previousIssues = issueCounts(before, input.from_path, input.to_path);
+    const afterIssues = issueSignatures(after);
+    const additions = [];
+    for (const issue of afterIssues) {
+        const remaining = previousIssues.get(issue) ?? 0;
+        if (remaining === 0)
+            additions.push(issue);
+        else
+            previousIssues.set(issue, remaining - 1);
+    }
+    const stale = after.references.filter((reference) => reference.target_path === input.from_path);
+    if (stale.length)
+        mutationCatalogFailure(`staged Context move leaves explicit links targeting ${input.from_path}: ${stale
+            .map((entry) => `${entry.source_path}:${entry.line}`)
+            .join(", ")}`);
+    if (additions.length)
+        mutationCatalogFailure(`staged Context move introduces Markdown reference problems: ${additions.join("; ")}`);
+    return afterIssues;
+}
+export function issueSignatures(analysis) {
+    return analysis.references
+        .filter((entry) => entry.status !== "valid")
+        .map(referenceIssueSignature)
+        .sort(compareUtf8Paths);
+}
+function issueCounts(analysis, fromPath, toPath) {
+    const result = new Map();
+    for (const reference of analysis.references) {
+        if (reference.status === "valid")
+            continue;
+        const signature = referenceIssueSignature({
+            ...reference,
+            source_path: reference.source_path === fromPath ? toPath : reference.source_path,
+            target_path: reference.target_path === fromPath ? toPath : reference.target_path,
+        });
+        result.set(signature, (result.get(signature) ?? 0) + 1);
+    }
+    return result;
+}
+function referenceIssueSignature(reference) {
+    return JSON.stringify([
+        reference.source_path,
+        reference.kind,
+        reference.status,
+        reference.target_path,
+        reference.fragment,
+        reference.detail ?? null,
+    ]);
+}

package/dist/lib/context-move/context-move-render.d.ts

@@ -0,0 +1,2 @@
+import type { ContextMoveResult } from "./context-move-types.js";
+export declare function renderContextMoveText(result: ContextMoveResult): string;

package/dist/lib/context-move/context-move-render.js

@@ -0,0 +1,24 @@
+export function renderContextMoveText(result) {
+    const lines = [
+        `Context move: ${result.from_path} -> ${result.to_path}`,
+        `State: ${result.applied ? "committed" : "dry-run"}`,
+        `Apply readiness: ${result.can_apply ? "ready" : "blocked"}`,
+        `Owner: ${result.owner.source}/${result.owner.role}`,
+        `Transaction: ${result.transaction.id}`,
+    ];
+    if (result.directories_created.length)
+        lines.push("Directories created on apply:", ...result.directories_created.map((entry) => `- ${entry}`));
+    lines.push("File plan:");
+    for (const file of result.files)
+        lines.push(`- ${file.action} ${file.path} (${file.before_bytes} -> ${file.after_bytes} bytes)`);
+    lines.push(`Manifest replacements: ${result.manifest.replacements.length}`, `Markdown references updated: ${result.links.references_updated.length}`, `Repository scan: ${result.scan.complete ? "complete" : "incomplete"}; ${result.scan.files_scanned} files, ${result.scan.bytes_scanned} bytes`);
+    if (result.unresolved.length) {
+        lines.push("Unresolved exact references (apply is refused):");
+        for (const entry of result.unresolved)
+            lines.push(`- ${entry.path}:${entry.line}:${entry.column} ${entry.kind}: ${entry.matched}`);
+    }
+    if (result.scan.limits_exceeded.length)
+        lines.push("Scan limits (apply is refused):", ...result.scan.limits_exceeded.map((entry) => `- ${entry}`));
+    lines.push(`Default footprint: ${result.default_footprint.before.path_count}/${result.default_footprint.before.bytes} -> ${result.default_footprint.after.path_count}/${result.default_footprint.after.bytes}`, "Dry-run is the default; --apply uses the CAS/journal transaction and has no force bypass.");
+    return `${lines.join("\n")}\n`;
+}

package/dist/lib/context-move/context-move-support.d.ts

@@ -0,0 +1,10 @@
+import type { CatalogRegisteredContext, ContextCatalog } from "../context-catalog/catalog-types.js";
+export declare function assertContextMoveEndpoints(catalog: ContextCatalog, fromPath: string, toPath: string): CatalogRegisteredContext;
+export declare function assertStagedContextMoveOwner(catalog: ContextCatalog, owner: CatalogRegisteredContext, from: string, to: string): void;
+export declare function missingContextMoveDirectories(repository: string, targetPath: string): Promise<string[]>;
+export declare function readContextMoveMarkdown(repository: string, catalog: ContextCatalog): Promise<Map<string, {
+    path: string;
+    physical_path: string;
+    content: string;
+}>>;
+export declare function renderContextMoveFileDiff(file: string, before: string, after: string): string;

package/dist/lib/context-move/context-move-support.js

@@ -0,0 +1,88 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertCatalogStagedFilePath } from "../context-catalog/catalog-staged-path-safety.js";
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { decodeMutationUtf8, mutationCatalogFailure, mutationIoFailure, mutationMessage, } from "../context-mutation/mutation-command-support.js";
+import { assertProtectedRepositoryFile } from "../repository-path-safety.js";
+export function assertContextMoveEndpoints(catalog, fromPath, toPath) {
+    const source = catalog.registered_contexts.filter((entry) => entry.path === fromPath);
+    if (source.length !== 1)
+        mutationCatalogFailure(`context move requires exactly one registered source: ${fromPath}`);
+    const folded = fold(toPath);
+    const collision = catalog.context_files.find((entry) => fold(entry.path) === folded);
+    if (collision)
+        mutationIoFailure(`context move target already exists: ${collision.path}`);
+    const registered = catalog.registered_contexts.find((entry) => fold(entry.path) === folded);
+    if (registered)
+        mutationCatalogFailure(`context move target is already registered: ${registered.path}`);
+    return source[0];
+}
+export function assertStagedContextMoveOwner(catalog, owner, from, to) {
+    const matches = catalog.registered_contexts.filter((entry) => entry.path === to);
+    if (matches.length !== 1 ||
+        matches[0].source !== owner.source ||
+        matches[0].role !== owner.role ||
+        (matches[0].read_policy ?? null) !== (owner.read_policy ?? null) ||
+        catalog.registered_contexts.some((entry) => entry.path === from))
+        mutationCatalogFailure("staged Context move changed owner metadata");
+}
+export async function missingContextMoveDirectories(repository, targetPath) {
+    const parent = path.posix.dirname(targetPath);
+    const directories = [];
+    let cursor = "";
+    for (const segment of parent.split("/")) {
+        cursor = cursor ? `${cursor}/${segment}` : segment;
+        const absolute = path.join(repository, ...cursor.split("/"));
+        const status = await lstat(absolute).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!status)
+            directories.push(cursor);
+        else if (!status.isDirectory() || status.isSymbolicLink())
+            mutationIoFailure(`context move target parent is unsafe: ${cursor}`);
+    }
+    const staged = new Set(directories);
+    try {
+        await assertCatalogStagedFilePath(repository, targetPath, staged, "context_move_target");
+    }
+    catch (error) {
+        mutationIoFailure(`context move target is unsafe: ${mutationMessage(error)}`, error);
+    }
+    return directories;
+}
+export async function readContextMoveMarkdown(repository, catalog) {
+    const result = new Map();
+    for (const file of [...catalog.context_files].sort((left, right) => compareUtf8Paths(left.path, right.path))) {
+        try {
+            const absolute = await assertProtectedRepositoryFile(repository, file.absolute_path, "context_move_markdown");
+            result.set(file.path, {
+                path: file.path,
+                physical_path: file.physical_path,
+                content: decodeMutationUtf8(await readFile(absolute), file.path),
+            });
+        }
+        catch (error) {
+            mutationIoFailure(`unable to read Context Markdown ${file.path}: ${mutationMessage(error)}`, error);
+        }
+    }
+    return result;
+}
+export function renderContextMoveFileDiff(file, before, after) {
+    if (before === after)
+        return "";
+    const previous = before.replace(/\r\n/gu, "\n").split("\n");
+    const next = after.replace(/\r\n/gu, "\n").split("\n");
+    return [
+        `--- ${file}`,
+        `+++ ${file}`,
+        "@@ exact byte replacement @@",
+        ...previous.map((line) => `-${line}`),
+        ...next.map((line) => `+${line}`),
+        "",
+    ].join("\n");
+}
+function fold(value) {
+    return value.normalize("NFC").toLocaleLowerCase("en-US");
+}

package/dist/lib/context-move/context-move-transaction-plan.d.ts

@@ -0,0 +1,24 @@
+import type { ContextMutationPlan, MutationFileState } from "../context-mutation/mutation-types.js";
+import type { CatalogRegisteredContext, ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextMoveFileProjection } from "./context-move-types.js";
+export declare function buildContextMoveTransactionPlan(input: {
+    repository: string;
+    owner: CatalogRegisteredContext;
+    normalized: {
+        from_path: string;
+        to_path: string;
+    };
+    directories: string[];
+    source_before: MutationFileState;
+    source_physical_path: string;
+    manifest_before: MutationFileState;
+    manifest_bytes: Buffer;
+    target_bytes: Buffer;
+    updated_files: ReadonlyMap<string, string>;
+    before_catalog: ContextCatalog;
+    after_catalog: ContextCatalog;
+    reference_issues: string[];
+}): Promise<{
+    plan: ContextMutationPlan;
+    projections: ContextMoveFileProjection[];
+}>;

package/dist/lib/context-move/context-move-transaction-plan.js

@@ -0,0 +1,108 @@
+import { absentMutationFileState, captureMutationFileState, mutationFileStateFromBytes, mutationTemporaryPath, } from "../context-mutation/mutation-cas.js";
+import { contextCatalogIdentity, contextFootprintState, } from "../context-mutation/mutation-staged-fs.js";
+import { compareUtf8Paths, resolveCatalogFile, } from "../context-catalog/catalog-paths.js";
+import { mutationCatalogFailure } from "../context-mutation/mutation-command-support.js";
+import { canonicalValueJson, sha256Hex } from "../strict-codec.js";
+const MANIFEST_PATH = "project_context/context.toml";
+export async function buildContextMoveTransactionPlan(input) {
+    const raw = [];
+    raw.push({
+        path: input.normalized.to_path,
+        physical_path: input.normalized.to_path,
+        before: absentMutationFileState(),
+        after: mutationFileStateFromBytes(input.target_bytes, input.source_before.mode),
+    });
+    for (const [file, content] of [...input.updated_files].sort(([left], [right]) => compareUtf8Paths(left, right))) {
+        const catalogFile = resolveCatalogFile(input.before_catalog, file);
+        if (!catalogFile)
+            mutationCatalogFailure(`Context move reference source is absent from the Catalog: ${file}`);
+        const before = await captureMutationFileState(input.repository, catalogFile.physical_path);
+        raw.push({
+            path: file,
+            physical_path: catalogFile.physical_path,
+            before,
+            after: mutationFileStateFromBytes(Buffer.from(content, "utf8"), before.mode),
+        });
+    }
+    raw.push({
+        path: MANIFEST_PATH,
+        physical_path: MANIFEST_PATH,
+        before: input.manifest_before,
+        after: mutationFileStateFromBytes(input.manifest_bytes, input.manifest_before.mode),
+    });
+    raw.push({
+        path: input.normalized.from_path,
+        physical_path: input.source_physical_path,
+        before: input.source_before,
+        after: absentMutationFileState(),
+    });
+    const afterFootprint = contextFootprintState(input.after_catalog);
+    const operationData = {
+        kind: "move",
+        ...input.normalized,
+        owner_source: input.owner.source,
+        role: input.owner.role,
+        read_policy: input.owner.read_policy ?? null,
+        expected_reference_issues: input.reference_issues,
+        expected_default_paths: afterFootprint.paths,
+        expected_default_bytes: afterFootprint.bytes,
+    };
+    const beforeIdentity = contextCatalogIdentity(input.before_catalog);
+    const afterIdentity = contextCatalogIdentity(input.after_catalog);
+    const transactionId = sha256Hex(canonicalValueJson({
+        operation: "move",
+        catalog_before_identity: beforeIdentity,
+        catalog_after_identity: afterIdentity,
+        directories: input.directories,
+        files: raw.map((entry, commit_order) => ({
+            path: entry.path,
+            physical_path: entry.physical_path,
+            before_sha256: entry.before.sha256,
+            after_sha256: entry.after.sha256,
+            commit_order,
+        })),
+        operation_data: operationData,
+    }));
+    const files = raw.map((entry, commitOrder) => ({
+        ...entry,
+        commit_order: commitOrder,
+        temporary_path: mutationTemporaryPath(entry.physical_path, transactionId, commitOrder),
+        temporary_state: null,
+        published_before: null,
+        published_after: null,
+    }));
+    return {
+        plan: {
+            transaction_id: transactionId,
+            operation: "move",
+            catalog_before_identity: beforeIdentity,
+            catalog_after_identity: afterIdentity,
+            directories: input.directories.map((directory) => ({
+                path: directory,
+                before_exists: false,
+            })),
+            files,
+            operation_data: operationData,
+        },
+        projections: files.map(fileProjection),
+    };
+}
+function fileProjection(change) {
+    return {
+        path: change.path,
+        action: !change.before.exists
+            ? "create"
+            : !change.after.exists
+                ? "delete"
+                : "update",
+        before_sha256: change.before.sha256,
+        after_sha256: change.after.sha256,
+        before_bytes: byteLength(change.before),
+        after_bytes: byteLength(change.after),
+    };
+}
+function byteLength(state) {
+    return state.bytes_base64 === null
+        ? 0
+        : Buffer.from(state.bytes_base64, "base64").length;
+}

package/dist/lib/context-move/context-move-types.d.ts

@@ -0,0 +1,74 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { ContextFootprintState } from "../context-mutation/mutation-types.js";
+import type { ContextMoveLiteralMatch } from "./context-move-literal-scan.js";
+export interface ContextMoveInput {
+    project_root: string;
+    from_path: string;
+    to_path: string;
+    apply?: boolean;
+}
+export interface ContextMoveFileProjection {
+    path: string;
+    action: "create" | "update" | "delete";
+    before_sha256: string | null;
+    after_sha256: string | null;
+    before_bytes: number;
+    after_bytes: number;
+}
+export interface ContextMoveResult {
+    schema_version: 1;
+    operation: "move";
+    applied: boolean;
+    can_apply: boolean;
+    from_path: string;
+    to_path: string;
+    owner: {
+        source: "area" | "context";
+        role: ContextRole;
+        read_policy: string | null;
+    };
+    directories_created: string[];
+    files: ContextMoveFileProjection[];
+    manifest: {
+        path: "project_context/context.toml";
+        replacements: Array<{
+            kind: "owner" | "default_child";
+            previous_literal: string;
+            next_literal: string;
+        }>;
+    };
+    links: {
+        files_changed: string[];
+        references_updated: Array<{
+            source_path: string;
+            line: number;
+            column: number;
+            previous_destination: string;
+            next_destination: string;
+        }>;
+    };
+    unresolved: ContextMoveLiteralMatch[];
+    scan: {
+        complete: boolean;
+        files_scanned: number;
+        bytes_scanned: number;
+        limits_exceeded: string[];
+    };
+    default_footprint: {
+        changed: boolean;
+        before: ContextFootprintState;
+        after: ContextFootprintState;
+        added: string[];
+        removed: string[];
+    };
+    catalog: {
+        before_identity: string;
+        after_identity: string;
+    };
+    diagnostics: string[];
+    transaction: {
+        id: string;
+        state: "dry-run" | "committed";
+        journal_present: false;
+    };
+}

package/dist/lib/context-move/context-move-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/context-move/context-move.d.ts

@@ -0,0 +1,8 @@
+import type { ContextMutationPlan } from "../context-mutation/mutation-types.js";
+import type { ContextMoveInput, ContextMoveResult } from "./context-move-types.js";
+export interface PlannedContextMove {
+    plan: ContextMutationPlan;
+    result: ContextMoveResult;
+}
+export declare function moveContext(input: ContextMoveInput): Promise<ContextMoveResult>;
+export declare function planContextMove(input: ContextMoveInput): Promise<PlannedContextMove>;