project-tiny-context-harness 0.8.17 → 0.11.0

package/dist/lib/context-catalog/catalog-diagnostics.js

@@ -0,0 +1,34 @@
+import { compareUtf8Paths, normalizeContextPath } from "./catalog-paths.js";
+const DIAGNOSTIC_SEVERITY_ORDER = {
+    error: 0,
+    warning: 1,
+};
+export function catalogDiagnostic(code, severity, message, location = {}) {
+    return { code, severity, message, ...location };
+}
+export function catalogErrors(diagnostics) {
+    return sortCatalogDiagnostics(diagnostics)
+        .filter((entry) => entry.severity === "error")
+        .map((entry) => entry.message);
+}
+export function catalogWarnings(diagnostics) {
+    return sortCatalogDiagnostics(diagnostics)
+        .filter((entry) => entry.severity === "warning")
+        .map((entry) => entry.message);
+}
+export function compareCatalogDiagnostics(left, right) {
+    return (DIAGNOSTIC_SEVERITY_ORDER[left.severity] -
+        DIAGNOSTIC_SEVERITY_ORDER[right.severity] ||
+        compareUtf8Paths(diagnosticPath(left), diagnosticPath(right)) ||
+        (left.line ?? 0) - (right.line ?? 0) ||
+        compareUtf8Paths(left.code, right.code) ||
+        compareUtf8Paths(left.message, right.message));
+}
+export function sortCatalogDiagnostics(diagnostics) {
+    return [...diagnostics].sort(compareCatalogDiagnostics);
+}
+function diagnosticPath(diagnostic) {
+    // Diagnostics without a path sort first. Path comparison is slash-normalized
+    // and byte-defined; it never depends on the process locale or ICU build.
+    return diagnostic.path ? normalizeContextPath(diagnostic.path) : "";
+}

package/dist/lib/context-catalog/catalog-discovery.d.ts

@@ -0,0 +1,7 @@
+import type { CatalogFile } from "./catalog-types.js";
+import type { CatalogDiagnostic } from "./catalog-types.js";
+export interface CatalogDiscoveryResult {
+    files: CatalogFile[];
+    diagnostics: CatalogDiagnostic[];
+}
+export declare function discoverContextMarkdownFiles(projectRoot: string, fileOverrides?: ReadonlyMap<string, Uint8Array | null>): Promise<CatalogDiscoveryResult>;

package/dist/lib/context-catalog/catalog-discovery.js

@@ -0,0 +1,81 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { listFiles } from "../fs.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, portableContextPathCaseKey, repositoryRelativePathSpelling, } from "./catalog-paths.js";
+import { catalogDiagnostic } from "./catalog-diagnostics.js";
+export async function discoverContextMarkdownFiles(projectRoot, fileOverrides = new Map()) {
+    const contextRoot = path.join(projectRoot, "project_context");
+    const files = (await listFiles(contextRoot))
+        .filter((file) => file.toLowerCase().endsWith(".md"))
+        .map((absolutePath) => ({
+        absolutePath,
+        physicalRelative: repositoryRelativePathSpelling(projectRoot, absolutePath),
+    }))
+        .sort((left, right) => compareUtf8Paths(left.physicalRelative, right.physicalRelative));
+    const diagnostics = [];
+    const result = new Map();
+    const physicalSpellings = new Map();
+    for (const { absolutePath, physicalRelative } of files) {
+        const relative = normalizeContextPath(physicalRelative);
+        const spellings = physicalSpellings.get(relative) ?? [];
+        spellings.push(physicalRelative);
+        physicalSpellings.set(relative, spellings);
+        if (result.has(relative))
+            continue;
+        const metadata = await lstat(absolutePath);
+        result.set(relative, {
+            path: relative,
+            physical_path: physicalRelative,
+            absolute_path: absolutePath,
+            bytes: metadata.size,
+        });
+    }
+    for (const [relative, spellings] of physicalSpellings) {
+        const unique = [...new Set(spellings)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_path_unicode_collision", "error", `Context files ${unique.join(", ")} normalize to the same NFC repository path ${relative}`, { path: relative }));
+    }
+    for (const [relativeInput, bytes] of fileOverrides) {
+        const relative = normalizeContextPath(relativeInput);
+        if (!relative.startsWith("project_context/") ||
+            !relative.toLowerCase().endsWith(".md"))
+            continue;
+        if (bytes === null)
+            result.delete(relative);
+        else {
+            const existing = result.get(relative);
+            if (existing) {
+                result.set(relative, { ...existing, bytes: bytes.byteLength });
+                continue;
+            }
+            const physicalPath = normalizeContextPathSpelling(relativeInput);
+            result.set(relative, {
+                path: relative,
+                physical_path: physicalPath,
+                absolute_path: path.join(projectRoot, ...physicalPath.split("/")),
+                bytes: bytes.byteLength,
+            });
+        }
+    }
+    addContextCaseCollisionDiagnostics(diagnostics, result.keys());
+    return {
+        files: [...result.values()].sort((left, right) => compareUtf8Paths(left.path, right.path)),
+        diagnostics,
+    };
+}
+function addContextCaseCollisionDiagnostics(diagnostics, paths) {
+    const folded = new Map();
+    for (const contextPath of paths) {
+        const key = portableContextPathCaseKey(contextPath);
+        const values = folded.get(key) ?? [];
+        values.push(contextPath);
+        folded.set(key, values);
+    }
+    for (const values of folded.values()) {
+        const unique = [...new Set(values)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_path_case_collision", "error", `Context files ${unique.join(", ")} collide on a case-insensitive filesystem`, { path: unique[0] }));
+    }
+}

package/dist/lib/context-catalog/catalog-load.d.ts

@@ -0,0 +1,8 @@
+import type { ContextCatalog } from "./catalog-types.js";
+export interface LoadContextCatalogOptions {
+    discover_files?: boolean;
+    validate_manifest?: boolean;
+    file_overrides?: ReadonlyMap<string, Uint8Array | null>;
+    directory_overrides?: ReadonlySet<string>;
+}
+export declare function loadContextCatalog(projectRootInput: string, options?: LoadContextCatalogOptions): Promise<ContextCatalog>;

package/dist/lib/context-catalog/catalog-load.js

@@ -0,0 +1,187 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { CONTEXT_MANIFEST_PATH } from "../context-manifest.js";
+import { parseContextManifest } from "../context-manifest-schema.js";
+import { pathExists } from "../fs.js";
+import { selectDefaultContextPaths } from "./catalog-default-footprint.js";
+import { catalogDiagnostic, sortCatalogDiagnostics, } from "./catalog-diagnostics.js";
+import { discoverContextMarkdownFiles } from "./catalog-discovery.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, sortedContextMap, } from "./catalog-paths.js";
+import { validateCatalogManifest } from "./catalog-validation.js";
+export async function loadContextCatalog(projectRootInput, options = {}) {
+    const projectRoot = path.resolve(projectRootInput);
+    const manifestPath = CONTEXT_MANIFEST_PATH;
+    const absoluteManifestPath = path.join(projectRoot, ...manifestPath.split("/"));
+    const diagnostics = [];
+    const normalizedOverrides = normalizeFileOverrides(options.file_overrides);
+    const fileOverrides = normalizedOverrides.values;
+    diagnostics.push(...normalizedOverrides.diagnostics);
+    const directoryOverrides = normalizeDirectoryOverrides(options.directory_overrides);
+    const discovery = options.discover_files === false
+        ? { files: [], diagnostics: [] }
+        : await discoverContextMarkdownFiles(projectRoot, fileOverrides);
+    const contextFiles = discovery.files;
+    diagnostics.push(...discovery.diagnostics);
+    const withoutCoreFiles = contextFiles.filter((entry) => entry.path !== "project_context/global.md" &&
+        entry.path !== "project_context/architecture.md");
+    const manifestOverride = fileOverrides.has(manifestPath)
+        ? fileOverrides.get(manifestPath)
+        : undefined;
+    if (manifestOverride === null ||
+        (manifestOverride === undefined &&
+            !(await pathExists(absoluteManifestPath)))) {
+        diagnostics.push(catalogDiagnostic("context_manifest_missing", "error", "project_context/context.toml is missing", { path: manifestPath }));
+        addUnregisteredDiagnostics(diagnostics, withoutCoreFiles);
+        return {
+            project_root: projectRoot,
+            manifest_path: manifestPath,
+            areas: [],
+            registered_contexts: [],
+            context_files: contextFiles,
+            unregistered_context_files: withoutCoreFiles,
+            default_footprint: new Map(),
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: sortCatalogDiagnostics(diagnostics),
+        };
+    }
+    const manifestContent = manifestOverride === undefined
+        ? await readFile(absoluteManifestPath, "utf8")
+        : Buffer.from(manifestOverride).toString("utf8");
+    const parsed = parseContextManifest(manifestContent, manifestPath);
+    diagnostics.push(...parsed.errors.map((message) => catalogDiagnostic("context_manifest_parse", "error", message, {
+        path: manifestPath,
+    })));
+    if (!parsed.manifest) {
+        addUnregisteredDiagnostics(diagnostics, withoutCoreFiles);
+        return {
+            project_root: projectRoot,
+            manifest_path: manifestPath,
+            manifest_content: manifestContent,
+            areas: [],
+            registered_contexts: [],
+            context_files: contextFiles,
+            unregistered_context_files: withoutCoreFiles,
+            default_footprint: new Map(),
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: sortCatalogDiagnostics(diagnostics),
+        };
+    }
+    const validation = options.validate_manifest === false
+        ? {
+            registered_contexts: [],
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: [],
+        }
+        : await validateCatalogManifest(projectRoot, parsed.manifest, fileOverrides, directoryOverrides, contextFiles);
+    diagnostics.push(...validation.diagnostics);
+    const registeredPaths = new Set([
+        "project_context/global.md",
+        "project_context/architecture.md",
+        ...parsed.manifest.areas.map((area) => normalizeContextPath(area.context)),
+        ...parsed.manifest.contexts.map((context) => normalizeContextPath(context.path)),
+    ]);
+    const unregisteredContextFiles = contextFiles.filter((entry) => !registeredPaths.has(entry.path));
+    addUnregisteredDiagnostics(diagnostics, unregisteredContextFiles);
+    return {
+        project_root: projectRoot,
+        manifest_path: manifestPath,
+        manifest_content: manifestContent,
+        manifest: parsed.manifest,
+        areas: projectAreas(parsed.manifest.areas),
+        registered_contexts: projectRegisteredContexts(validation.registered_contexts),
+        context_files: contextFiles,
+        unregistered_context_files: unregisteredContextFiles,
+        default_footprint: selectDefaultContextPaths(parsed.manifest),
+        roles_by_path: sortedContextMap(validation.roles_by_path),
+        read_policies_by_path: sortedContextMap(validation.read_policies_by_path),
+        diagnostics: sortCatalogDiagnostics(diagnostics),
+    };
+}
+function normalizeDirectoryOverrides(values) {
+    if (!values)
+        return new Set();
+    return new Set([...values].map(normalizeContextPath));
+}
+function normalizeFileOverrides(values) {
+    if (!values)
+        return { values: new Map(), diagnostics: [] };
+    const normalized = new Map();
+    const diagnostics = [];
+    const spellings = new Map();
+    const entries = [...values].sort(([left], [right]) => compareUtf8Paths(normalizeContextPathSpelling(left), normalizeContextPathSpelling(right)));
+    for (const [file, bytes] of entries) {
+        const relative = normalizeContextPath(file);
+        const valuesForPath = spellings.get(relative) ?? [];
+        valuesForPath.push(normalizeContextPathSpelling(file));
+        spellings.set(relative, valuesForPath);
+        if (!normalized.has(relative))
+            normalized.set(relative, bytes === null ? null : Buffer.from(bytes));
+    }
+    for (const [relative, rawSpellings] of spellings) {
+        const unique = [...new Set(rawSpellings)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_override_path_unicode_collision", "error", `Context file overrides ${unique.join(", ")} normalize to the same NFC repository path ${relative}`, { path: relative }));
+    }
+    return { values: normalized, diagnostics };
+}
+function addUnregisteredDiagnostics(diagnostics, files) {
+    for (const file of files) {
+        diagnostics.push(catalogDiagnostic("context_file_unregistered", "warning", `${file.path} is an unregistered Context Markdown file; add it to project_context/context.toml or move it out of project_context/**`, { path: file.path }));
+    }
+}
+function projectAreas(areas) {
+    return areas
+        .map((area) => ({
+        ...area,
+        id: area.id.normalize("NFC"),
+        root: normalizeContextPath(area.root),
+        context: normalizeContextPath(area.context),
+        forbidden_runtime_dependencies: [...area.forbidden_runtime_dependencies]
+            .map((entry) => entry.normalize("NFC"))
+            .sort(compareUtf8Paths),
+    }))
+        .sort((left, right) => compareUtf8Paths(left.root, right.root) ||
+        compareUtf8Paths(left.id, right.id) ||
+        compareUtf8Paths(left.context, right.context) ||
+        left.line - right.line);
+}
+function projectRegisteredContexts(entries) {
+    return entries
+        .map((entry) => ({
+        ...entry,
+        path: normalizeContextPath(entry.path),
+        area: entry.area
+            ? {
+                ...entry.area,
+                id: entry.area.id.normalize("NFC"),
+                root: normalizeContextPath(entry.area.root),
+                context: normalizeContextPath(entry.area.context),
+                forbidden_runtime_dependencies: [
+                    ...entry.area.forbidden_runtime_dependencies,
+                ]
+                    .map((value) => value.normalize("NFC"))
+                    .sort(compareUtf8Paths),
+            }
+            : undefined,
+        context: entry.context
+            ? {
+                ...entry.context,
+                path: normalizeContextPath(entry.context.path),
+                triggers: [...entry.context.triggers]
+                    .map((value) => value.normalize("NFC"))
+                    .sort(compareUtf8Paths),
+                default_children: [...entry.context.default_children]
+                    .map(normalizeContextPath)
+                    .sort(compareUtf8Paths),
+            }
+            : undefined,
+    }))
+        .sort((left, right) => compareUtf8Paths(left.path, right.path) ||
+        compareUtf8Paths(left.source, right.source) ||
+        compareUtf8Paths(left.role, right.role) ||
+        left.line - right.line);
+}

package/dist/lib/context-catalog/catalog-path-validation.d.ts

@@ -0,0 +1,7 @@
+import type { CatalogFile } from "./catalog-types.js";
+export type CatalogPathErrorReporter = (code: string, message: string, location?: {
+    path?: string;
+    line?: number;
+}) => void;
+export declare function validateCatalogManifestPath(projectRoot: string, rawPath: string, allowedRoot: string, source: string, allowFile: boolean, addError: CatalogPathErrorReporter, fileOverrides?: ReadonlyMap<string, Uint8Array | null>, directoryOverrides?: ReadonlySet<string>, filesByPath?: ReadonlyMap<string, CatalogFile>): Promise<boolean>;
+export declare function looksLikeContextExportArtifact(value: string): boolean;

package/dist/lib/context-catalog/catalog-path-validation.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { pathExists } from "../fs.js";
+import { assertCatalogStagedFilePath } from "./catalog-staged-path-safety.js";
+import { isPathWithin, normalizeContextPath } from "./catalog-paths.js";
+const EXPORT_ARTIFACT_NAME_PATTERNS = [
+    /full-project-context/iu,
+    /当前项目context/iu,
+    /当前项目代码实现(?:context)?/iu,
+    /code-level-implementation/iu,
+    /project-overview/iu,
+    /context-bundle/iu,
+    /context-summary/iu,
+    /context-export/iu,
+];
+export async function validateCatalogManifestPath(projectRoot, rawPath, allowedRoot, source, allowFile, addError, fileOverrides = new Map(), directoryOverrides = new Set(), filesByPath = new Map()) {
+    if (path.isAbsolute(rawPath) ||
+        rawPath.replace(/\\/gu, "/").split("/").includes("..")) {
+        addError("manifest_path_not_relative", `project_context/context.toml ${source} path must be relative and must not contain '..': ${rawPath}`);
+        return false;
+    }
+    const target = path.resolve(projectRoot, rawPath);
+    if (!isPathWithin(allowedRoot, target)) {
+        addError("manifest_path_outside_allowed_root", `project_context/context.toml ${source} escapes its allowed root: ${rawPath}`);
+        return false;
+    }
+    const relative = normalizeContextPath(path.relative(projectRoot, target));
+    const physicalRelative = filesByPath.get(relative)?.physical_path ?? relative;
+    const physicalTarget = path.resolve(projectRoot, physicalRelative);
+    if (allowFile && fileOverrides.has(relative)) {
+        if (fileOverrides.get(relative) === null) {
+            addError("manifest_path_missing", `project_context/context.toml references missing context file: ${relative}`);
+            return false;
+        }
+        try {
+            await assertCatalogStagedFilePath(projectRoot, physicalRelative, directoryOverrides, `catalog_staged_file:${source}`);
+            return true;
+        }
+        catch (error) {
+            addError("manifest_path_staged_unsafe", `project_context/context.toml ${source} staged path is unsafe: ${message(error)}`);
+            return false;
+        }
+    }
+    const existingTarget = allowFile ? physicalTarget : target;
+    if (!(await pathExists(existingTarget))) {
+        addError("manifest_path_missing", `project_context/context.toml references missing ${allowFile ? "context file" : "area root"}: ${normalizeContextPath(rawPath)}`);
+        return false;
+    }
+    const realAllowedRoot = await realpath(allowedRoot);
+    const realTarget = await realpath(existingTarget);
+    if (!isPathWithin(realAllowedRoot, realTarget)) {
+        addError("manifest_path_symlink_escape", `project_context/context.toml ${source} resolves through a symbolic link outside its allowed root: ${rawPath}`);
+        return false;
+    }
+    return true;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function looksLikeContextExportArtifact(value) {
+    return EXPORT_ARTIFACT_NAME_PATTERNS.some((pattern) => pattern.test(value));
+}

package/dist/lib/context-catalog/catalog-paths.d.ts

@@ -0,0 +1,11 @@
+import type { CatalogFile, ContextCatalog } from "./catalog-types.js";
+export declare function normalizeContextPath(value: string): string;
+export declare function normalizeContextPathSpelling(value: string): string;
+export declare function resolveProjectPath(projectRoot: string, repositoryRelativePath: string): string;
+export declare function repositoryRelativePath(projectRoot: string, absolutePath: string): string;
+export declare function repositoryRelativePathSpelling(projectRoot: string, absolutePath: string): string;
+export declare function resolveCatalogFile(catalog: Pick<ContextCatalog, "context_files">, repositoryRelativePath: string): CatalogFile | undefined;
+export declare function isPathWithin(root: string, target: string): boolean;
+export declare function compareUtf8Paths(left: string, right: string): number;
+export declare function portableContextPathCaseKey(value: string): string;
+export declare function sortedContextMap<T>(values: Iterable<readonly [string, T]>): Map<string, T>;

package/dist/lib/context-catalog/catalog-paths.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+export function normalizeContextPath(value) {
+    return normalizeContextPathSpelling(value).normalize("NFC");
+}
+// Preserve the physical spelling when discovery needs to diagnose two paths
+// that collapse to the same public NFC key. Catalog consumers should otherwise
+// use normalizeContextPath().
+export function normalizeContextPathSpelling(value) {
+    return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+export function resolveProjectPath(projectRoot, repositoryRelativePath) {
+    return path.resolve(projectRoot, ...normalizeContextPath(repositoryRelativePath).split("/"));
+}
+export function repositoryRelativePath(projectRoot, absolutePath) {
+    return normalizeContextPath(path.relative(projectRoot, absolutePath));
+}
+export function repositoryRelativePathSpelling(projectRoot, absolutePath) {
+    return normalizeContextPathSpelling(path.relative(projectRoot, absolutePath));
+}
+export function resolveCatalogFile(catalog, repositoryRelativePath) {
+    const key = normalizeContextPath(repositoryRelativePath);
+    return catalog.context_files.find((file) => file.path === key);
+}
+export function isPathWithin(root, target) {
+    const relative = path.relative(root, target);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+export function compareUtf8Paths(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+export function portableContextPathCaseKey(value) {
+    // ECMAScript default case conversion is locale-independent. This key is a
+    // portability collision detector, not a filesystem lookup or ontology.
+    return normalizeContextPath(value).toLowerCase();
+}
+export function sortedContextMap(values) {
+    return new Map([...values].sort(([left], [right]) => compareUtf8Paths(left, right)));
+}

package/dist/lib/context-catalog/catalog-portable-contract.d.ts

@@ -0,0 +1,15 @@
+export type ContextRole = "global" | "architecture" | "area" | "domain" | "subdomain" | "foundation" | "archive" | "contract" | "verification" | "deployment" | "implementation-index" | "decision-rationale";
+export declare const CONTEXT_SCHEMA_VERSION: number;
+export declare const CONTEXT_ROLES: readonly string[];
+export declare const CONTEXT_ROLE_ALIASES: Readonly<{
+    [x: string]: string;
+}>;
+export declare const CONTEXT_READ_POLICIES: readonly string[];
+export declare const CONTEXT_LEGACY_READ_POLICIES: readonly string[];
+export declare const CONTEXT_TOP_LEVEL_FIELDS: Set<string>;
+export declare const CONTEXT_AREA_FIELDS: Set<string>;
+export declare const CONTEXT_NODE_FIELDS: Set<string>;
+export declare const CONTEXT_READ_POLICY_SET: Set<string>;
+export declare const CONTEXT_LEGACY_READ_POLICY_SET: Set<string>;
+export declare function normalizeContextRole(value: string): ContextRole | undefined;
+export declare function isContextReadPolicy(value: string): boolean;

package/dist/lib/context-catalog/catalog-portable-contract.js

@@ -0,0 +1,68 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const rawRules = require("../../../assets/tools/context_rules.json");
+const rules = validateRules(rawRules);
+export const CONTEXT_SCHEMA_VERSION = rules.context_schema_version;
+export const CONTEXT_ROLES = Object.freeze([...rules.roles]);
+export const CONTEXT_ROLE_ALIASES = Object.freeze({
+    ...rules.role_aliases,
+});
+export const CONTEXT_READ_POLICIES = Object.freeze([...rules.read_policies]);
+export const CONTEXT_LEGACY_READ_POLICIES = Object.freeze([
+    ...rules.legacy_read_policies,
+]);
+export const CONTEXT_TOP_LEVEL_FIELDS = new Set(rules.top_level_fields);
+export const CONTEXT_AREA_FIELDS = new Set(rules.area_fields);
+export const CONTEXT_NODE_FIELDS = new Set(rules.context_fields);
+export const CONTEXT_READ_POLICY_SET = new Set(CONTEXT_READ_POLICIES);
+export const CONTEXT_LEGACY_READ_POLICY_SET = new Set(CONTEXT_LEGACY_READ_POLICIES);
+export function normalizeContextRole(value) {
+    const normalized = value.trim().toLowerCase();
+    const aliased = CONTEXT_ROLE_ALIASES[normalized] ?? normalized;
+    return CONTEXT_ROLES.includes(aliased) ? aliased : undefined;
+}
+export function isContextReadPolicy(value) {
+    return CONTEXT_READ_POLICY_SET.has(value);
+}
+function validateRules(value) {
+    if (!isRecord(value)) {
+        throw new Error("context_rules_invalid:root");
+    }
+    const arrayFields = [
+        "roles",
+        "read_policies",
+        "legacy_read_policies",
+        "top_level_fields",
+        "area_fields",
+        "context_fields",
+    ];
+    for (const field of arrayFields) {
+        if (!isUniqueStringArray(value[field])) {
+            throw new Error(`context_rules_invalid:${field}`);
+        }
+    }
+    if (!Number.isInteger(value.context_schema_version) ||
+        Number(value.context_schema_version) < 1) {
+        throw new Error("context_rules_invalid:context_schema_version");
+    }
+    if (!isRecord(value.role_aliases) ||
+        Object.values(value.role_aliases).some((entry) => typeof entry !== "string" || !entry.trim())) {
+        throw new Error("context_rules_invalid:role_aliases");
+    }
+    const typed = value;
+    if (typed.legacy_read_policies.some((policy) => !typed.read_policies.includes(policy))) {
+        throw new Error("context_rules_invalid:legacy_read_policies_subset");
+    }
+    if (Object.values(typed.role_aliases).some((role) => !typed.roles.includes(role))) {
+        throw new Error("context_rules_invalid:role_alias_target");
+    }
+    return typed;
+}
+function isUniqueStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.trim()) &&
+        new Set(value).size === value.length);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lib/context-catalog/catalog-staged-path-safety.d.ts

@@ -0,0 +1 @@
+export declare function assertCatalogStagedFilePath(repository: string, relative: string, stagedDirectories: ReadonlySet<string>, label: string): Promise<void>;

package/dist/lib/context-catalog/catalog-staged-path-safety.js

@@ -0,0 +1,36 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryDirectory, assertSafeRepositoryFilePath, resolveInsideRepository, } from "../repository-path-safety.js";
+import { normalizeContextPath, normalizeContextPathSpelling, } from "./catalog-paths.js";
+export async function assertCatalogStagedFilePath(repository, relative, stagedDirectories, label) {
+    const absolute = resolveInsideRepository(repository, relative, label);
+    const parent = normalizeContextPathSpelling(path.posix.dirname(relative));
+    let physicalCursor = "";
+    for (const segment of parent.split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        physicalCursor = physicalCursor ? `${physicalCursor}/${segment}` : segment;
+        const canonicalCursor = normalizeContextPath(physicalCursor);
+        const candidate = path.join(repository, ...physicalCursor.split("/"));
+        const status = await lstat(candidate).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!status) {
+            if (!stagedDirectories.has(canonicalCursor))
+                throw new Error(`staged_parent_not_declared:${label}:${canonicalCursor}`);
+            continue;
+        }
+        await assertProtectedRepositoryDirectory(repository, candidate, `${label}:parent`);
+    }
+    const target = await lstat(absolute).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (target)
+        await assertSafeRepositoryFilePath(repository, relative, label, {
+            destinationMayBeAbsent: true,
+        });
+}

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

@@ -0,0 +1,40 @@
+import type { ContextAreaEntry, ContextManifest, ContextNodeEntry } from "../context-manifest-schema.js";
+import type { ContextRole } from "./catalog-portable-contract.js";
+import type { DefaultContextSelectionReason } from "./catalog-default-footprint.js";
+export type CatalogDiagnosticSeverity = "error" | "warning";
+export interface CatalogDiagnostic {
+    code: string;
+    severity: CatalogDiagnosticSeverity;
+    message: string;
+    path?: string;
+    line?: number;
+}
+export interface CatalogFile {
+    path: string;
+    physical_path: string;
+    absolute_path: string;
+    bytes: number;
+}
+export interface CatalogRegisteredContext {
+    source: "area" | "context";
+    path: string;
+    role: ContextRole;
+    read_policy?: string;
+    line: number;
+    area?: ContextAreaEntry;
+    context?: ContextNodeEntry;
+}
+export interface ContextCatalog {
+    project_root: string;
+    manifest_path: string;
+    manifest_content?: string;
+    manifest?: ContextManifest;
+    areas: ContextAreaEntry[];
+    registered_contexts: CatalogRegisteredContext[];
+    context_files: CatalogFile[];
+    unregistered_context_files: CatalogFile[];
+    default_footprint: Map<string, Set<DefaultContextSelectionReason>>;
+    roles_by_path: Map<string, ContextRole>;
+    read_policies_by_path: Map<string, string>;
+    diagnostics: CatalogDiagnostic[];
+}

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

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

package/dist/lib/context-catalog/catalog-validation.d.ts

@@ -0,0 +1,9 @@
+import type { ContextManifest } from "../context-manifest-schema.js";
+import type { CatalogFile, CatalogDiagnostic, CatalogRegisteredContext } from "./catalog-types.js";
+export interface CatalogManifestValidation {
+    registered_contexts: CatalogRegisteredContext[];
+    roles_by_path: Map<string, CatalogRegisteredContext["role"]>;
+    read_policies_by_path: Map<string, string>;
+    diagnostics: CatalogDiagnostic[];
+}
+export declare function validateCatalogManifest(projectRoot: string, manifest: ContextManifest, fileOverrides?: ReadonlyMap<string, Uint8Array | null>, directoryOverrides?: ReadonlySet<string>, contextFiles?: readonly CatalogFile[]): Promise<CatalogManifestValidation>;