project-tiny-context-harness 0.8.17 → 0.11.0

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

@@ -0,0 +1,16 @@
+export declare const CONTEXT_DOCTOR_DEFAULTS: Readonly<{
+    context_file_soft_budget_bytes: number;
+    long_line_code_points: 1000;
+    trigger_fanout_contexts: 4;
+}>;
+export interface ContextDoctorOptions {
+    context_file_soft_budget_bytes?: number;
+    long_line_code_points?: number;
+    trigger_fanout_contexts?: number;
+}
+export interface ContextDoctorAnalysis {
+    info: string[];
+    warnings: string[];
+    errors: string[];
+}
+export declare function resolveContextDoctorOptions(options?: ContextDoctorOptions): Required<ContextDoctorOptions>;

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

@@ -0,0 +1,15 @@
+export const CONTEXT_DOCTOR_DEFAULTS = Object.freeze({
+    context_file_soft_budget_bytes: 64 * 1024,
+    long_line_code_points: 1_000,
+    trigger_fanout_contexts: 4,
+});
+export function resolveContextDoctorOptions(options = {}) {
+    return {
+        context_file_soft_budget_bytes: options.context_file_soft_budget_bytes ??
+            CONTEXT_DOCTOR_DEFAULTS.context_file_soft_budget_bytes,
+        long_line_code_points: options.long_line_code_points ??
+            CONTEXT_DOCTOR_DEFAULTS.long_line_code_points,
+        trigger_fanout_contexts: options.trigger_fanout_contexts ??
+            CONTEXT_DOCTOR_DEFAULTS.trigger_fanout_contexts,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { ContextDoctorAnalysis, ContextDoctorOptions } from "./context-doctor-types.js";
+export declare function inspectContextCatalogHealth(projectRoot: string, options?: ContextDoctorOptions): Promise<ContextDoctorAnalysis>;

package/dist/lib/context-doctor/context-doctor.js

@@ -0,0 +1,130 @@
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { CONTEXT_LEGACY_READ_POLICY_SET } from "../context-catalog/catalog-portable-contract.js";
+import { analyzeContextMarkdownCatalog } from "../context-markdown/context-markdown-analysis.js";
+import { resolveContextDoctorOptions } from "./context-doctor-types.js";
+export async function inspectContextCatalogHealth(projectRoot, options = {}) {
+    const resolved = resolveContextDoctorOptions(options);
+    const result = {
+        info: [],
+        warnings: [],
+        errors: [],
+    };
+    const catalog = await loadContextCatalog(projectRoot);
+    for (const diagnostic of catalog.diagnostics) {
+        const location = diagnostic.path
+            ? `${diagnostic.path}${diagnostic.line ? `:${diagnostic.line}` : ""}: `
+            : "";
+        result[diagnostic.severity === "error" ? "errors" : "warnings"].push(`${location}${diagnostic.message}`);
+    }
+    const registeredByPath = new Map(catalog.registered_contexts.map((entry) => [entry.path, entry]));
+    const unregisteredPaths = new Set(catalog.unregistered_context_files.map((entry) => entry.path));
+    const defaultPaths = new Set(catalog.default_footprint.keys());
+    const markdown = await analyzeContextMarkdownCatalog({
+        project_root: catalog.project_root,
+        files: catalog.context_files,
+        long_line_threshold: resolved.long_line_code_points,
+    });
+    const distribution = distributionFor(catalog.context_files, registeredByPath, defaultPaths, unregisteredPaths);
+    result.info.push(`all Context Markdown: ${catalog.context_files.length} file(s), ${sumBytes(catalog.context_files)} bytes`);
+    result.info.push(`Context distribution: default=${distribution.default.files} file(s)/${distribution.default.bytes} bytes, on-demand=${distribution.on_demand.files} file(s)/${distribution.on_demand.bytes} bytes, legacy=${distribution.legacy.files} file(s)/${distribution.legacy.bytes} bytes, unregistered=${distribution.unregistered.files} file(s)/${distribution.unregistered.bytes} bytes`);
+    const largestOnDemand = [...catalog.context_files]
+        .filter((file) => isOnDemandRegistered(file.path, registeredByPath, defaultPaths))
+        .sort((left, right) => right.bytes - left.bytes || compareUtf8Paths(left.path, right.path))[0];
+    if (largestOnDemand)
+        result.info.push(`largest on-demand Context: ${largestOnDemand.path}, ${largestOnDemand.bytes} bytes`);
+    for (const file of markdown.files) {
+        const registered = registeredByPath.get(file.path);
+        const classification = classifyFile(file.path, registered, defaultPaths, unregisteredPaths);
+        result.info.push(`Context file: ${file.path}, ${file.bytes} bytes, ${classification}, max line ${file.max_line_code_points} code point(s)`);
+        if (file.bytes > resolved.context_file_soft_budget_bytes)
+            result.warnings.push(`${file.path} is ${file.bytes} bytes, above the ${resolved.context_file_soft_budget_bytes}-byte all-Context per-file soft budget; this is advisory and necessary recoverable facts take precedence`);
+        for (const line of file.long_lines)
+            result.warnings.push(`${file.path}:${line.line} has ${line.code_points} Unicode code points, above the ${resolved.long_line_code_points}-code-point advisory threshold`);
+    }
+    for (const fanout of collectTriggerFanout(catalog.registered_contexts, catalog.context_files)) {
+        result.info.push(`Context trigger: ${JSON.stringify(fanout.trigger)}, ${fanout.paths.length} Context(s), ${fanout.cumulative_bytes} cumulative bytes, paths=${fanout.paths.join(", ")}`);
+        if (fanout.paths.length >= resolved.trigger_fanout_contexts)
+            result.warnings.push(`trigger ${JSON.stringify(fanout.trigger)} fans out to ${fanout.paths.length} Contexts (${fanout.cumulative_bytes} bytes): ${fanout.paths.join(", ")}; review whether this literal trigger remains selective`);
+    }
+    for (const reference of markdown.references) {
+        if (reference.status === "valid")
+            continue;
+        const target = reference.target_path ?? reference.destination;
+        result.warnings.push(`${reference.source_path}:${reference.line} has ${reference.status.replaceAll("_", " ")} explicit Markdown Context reference ${JSON.stringify(target)}${reference.detail ? `: ${reference.detail}` : ""}`);
+    }
+    for (const declaration of markdown.invalid_declarations)
+        result.warnings.push(`${declaration.path}:${declaration.line} has invalid ty-context declaration ${JSON.stringify(declaration.raw)}: ${declaration.reason}`);
+    for (const conflict of markdown.declaration_conflicts)
+        result.warnings.push(`${conflict.type} ${conflict.id} is declared by multiple candidate owners: ${conflict.owners.map((owner) => `${owner.path}:${owner.line}`).join(", ")}`);
+    return result;
+}
+function distributionFor(files, registered, defaults, unregistered) {
+    const result = {
+        default: { files: 0, bytes: 0 },
+        on_demand: { files: 0, bytes: 0 },
+        legacy: { files: 0, bytes: 0 },
+        unregistered: { files: 0, bytes: 0 },
+    };
+    for (const file of files) {
+        const entry = registered.get(file.path);
+        let key;
+        if (unregistered.has(file.path))
+            key = "unregistered";
+        else if (defaults.has(file.path))
+            key = "default";
+        else if (entry?.read_policy &&
+            CONTEXT_LEGACY_READ_POLICY_SET.has(entry.read_policy))
+            key = "legacy";
+        else
+            key = "on_demand";
+        result[key].files += 1;
+        result[key].bytes += file.bytes;
+    }
+    return result;
+}
+function classifyFile(contextPath, registered, defaults, unregistered) {
+    if (unregistered.has(contextPath))
+        return "unregistered";
+    const policy = registered?.read_policy;
+    const suffix = policy ? `, read_policy=${policy}` : "";
+    if (defaults.has(contextPath))
+        return `default registered${suffix}`;
+    if (policy && CONTEXT_LEGACY_READ_POLICY_SET.has(policy))
+        return `legacy registered${suffix}`;
+    return `on-demand registered${suffix}`;
+}
+function isOnDemandRegistered(contextPath, registered, defaults) {
+    const entry = registered.get(contextPath);
+    return Boolean(entry &&
+        !defaults.has(contextPath) &&
+        !(entry.read_policy && CONTEXT_LEGACY_READ_POLICY_SET.has(entry.read_policy)));
+}
+function collectTriggerFanout(contexts, files) {
+    const filesByPath = new Map(files.map((file) => [file.path, file]));
+    const groups = new Map();
+    for (const context of contexts) {
+        for (const trigger of context.context?.triggers ?? []) {
+            const normalized = trigger.normalize("NFC").toLocaleLowerCase("en-US");
+            const group = groups.get(normalized) ?? {
+                display: trigger.normalize("NFC"),
+                paths: new Set(),
+            };
+            group.paths.add(context.path);
+            groups.set(normalized, group);
+        }
+    }
+    return [...groups.values()]
+        .map((group) => {
+        const paths = [...group.paths].sort(compareUtf8Paths);
+        return {
+            trigger: group.display,
+            paths,
+            cumulative_bytes: paths.reduce((total, contextPath) => total + (filesByPath.get(contextPath)?.bytes ?? 0), 0),
+        };
+    })
+        .sort((left, right) => compareUtf8Paths(left.trigger, right.trigger));
+}
+function sumBytes(files) {
+    return files.reduce((total, file) => total + file.bytes, 0);
+}

package/dist/lib/context-graph-snapshot.d.ts

@@ -6,12 +6,17 @@ export interface ContextGraphSnapshot {
     controlling_files: string[];
     supporting_files: string[];
 }
+export interface CapturedContextGraphSnapshot {
+    snapshot: ContextGraphSnapshot;
+    physical_files: ReadonlyMap<string, string>;
+}
 export interface CampaignContextBaseline {
     graph_sha256: string;
     files: Record<string, string>;
     baseline_sha256: string;
 }
 export declare function captureContextGraphSnapshot(repositoryRoot: string, contextRefs: Iterable<string>, mode?: "referenced" | "full"): Promise<ContextGraphSnapshot>;
+export declare function captureContextGraphSnapshotWithPhysicalFiles(repositoryRoot: string, contextRefs: Iterable<string>, mode?: "referenced" | "full"): Promise<CapturedContextGraphSnapshot>;
 export declare function captureCampaignContextBaseline(repositoryRoot: string, contextRefs: Iterable<string>): Promise<CampaignContextBaseline>;
 export declare function assertCampaignContextBaselineFresh(repositoryRoot: string, expected: CampaignContextBaseline, contextRefs: Iterable<string>): Promise<void>;
 export declare function currentContextTopologySha256(repositoryRoot: string): Promise<string>;

package/dist/lib/context-graph-snapshot.js

@@ -2,15 +2,20 @@ import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { contextAuthorityTopologyHash } from "./long-task-context-authority-topology.js";
 import { canonicalJson, sha256Hex } from "./strict-codec.js";
+import { compareUtf8Paths, normalizeContextPath, portableContextPathCaseKey, repositoryRelativePathSpelling, } from "./context-catalog/catalog-paths.js";
 import { parseContextManifest, } from "./context-manifest-schema.js";
 import { assertProtectedRepositoryFile } from "./long-task-protected-files.js";
 const CONTEXT_MANIFEST_PATH = "project_context/context.toml";
 const SUPPORTING_CONTEXT_ROLES = new Set(["implementation-index", "archive"]);
 export async function captureContextGraphSnapshot(repositoryRoot, contextRefs, mode = "referenced") {
+    return (await captureContextGraphSnapshotWithPhysicalFiles(repositoryRoot, contextRefs, mode)).snapshot;
+}
+export async function captureContextGraphSnapshotWithPhysicalFiles(repositoryRoot, contextRefs, mode = "referenced") {
     const root = path.resolve(repositoryRoot);
     const manifest = await readContextManifest(root);
-    const allFiles = await listContextFiles(root);
-    const available = new Set(allFiles);
+    const fileRecords = await listContextFileRecords(root);
+    const allFiles = fileRecords.map((file) => file.path);
+    const available = new Map(fileRecords.map((file) => [file.path, file]));
     const selected = new Set();
     const explicitlySelected = new Set();
     if (mode === "full") {
@@ -43,24 +48,27 @@ export async function captureContextGraphSnapshot(repositoryRoot, contextRefs, m
             selected.add(normalized);
             explicitlySelected.add(normalized);
         }
-        addTransitiveChildren(manifest, selected, available);
+        addTransitiveChildren(manifest, selected, new Set(available.keys()));
     }
-    const files = [...selected].sort();
+    const files = [...selected].sort(compareUtf8Paths);
     const authorityTopologySha256 = contextAuthorityTopologyHash(manifest, files);
     const hashes = Object.fromEntries(await Promise.all(files.map(async (file) => [
         file,
         file === CONTEXT_MANIFEST_PATH
             ? authorityTopologySha256
-            : await hashFile(root, path.join(root, file)),
+            : await hashFile(root, available.get(file).absolute_path),
     ])));
     const classification = classifyContextFiles(manifest, files, explicitlySelected, mode);
     return {
-        mode,
-        topology_sha256: authorityTopologySha256,
-        files,
-        sha256: sortRecord(hashes),
-        controlling_files: classification.controlling,
-        supporting_files: classification.supporting,
+        snapshot: {
+            mode,
+            topology_sha256: authorityTopologySha256,
+            files,
+            sha256: sortRecord(hashes),
+            controlling_files: classification.controlling,
+            supporting_files: classification.supporting,
+        },
+        physical_files: new Map(files.map((file) => [file, available.get(file).absolute_path])),
     };
 }
 export async function captureCampaignContextBaseline(repositoryRoot, contextRefs) {
@@ -85,7 +93,7 @@ export async function assertCampaignContextBaselineFresh(repositoryRoot, expecte
             ]),
         ]
             .filter((file) => expected.files[file] !== current.files[file])
-            .sort();
+            .sort(compareUtf8Paths);
         throw new Error(`campaign_context_changed:files:${changed.join(",") || "set"}`);
     }
 }
@@ -94,11 +102,17 @@ export async function currentContextTopologySha256(repositoryRoot) {
     return contextAuthorityTopologyHash(await readContextManifest(root), await listContextFiles(root));
 }
 export async function listContextFiles(repositoryRoot) {
+    return (await listContextFileRecords(path.resolve(repositoryRoot))).map((file) => file.path);
+}
+async function listContextFileRecords(repositoryRoot) {
     const root = path.resolve(repositoryRoot);
     const contextRoot = path.join(root, "project_context");
-    const result = [];
+    const result = new Map();
+    const portabilityKeys = new Map();
     async function visit(directory) {
-        for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => compareUtf8Paths(left.name, right.name));
+        for (const entry of entries) {
             const absolute = path.join(directory, entry.name);
             if (entry.isSymbolicLink()) {
                 throw new Error(`protected_input_symlink_not_allowed:context_authority:${absolute.replace(/\\/gu, "/")}`);
@@ -108,12 +122,26 @@ export async function listContextFiles(repositoryRoot) {
             }
             else if (entry.isFile()) {
                 await assertProtectedRepositoryFile(root, absolute, "context_authority");
-                result.push(repoRelative(root, absolute));
+                const physicalPath = repositoryRelativePathSpelling(root, absolute);
+                const publicPath = normalizeContextPath(physicalPath);
+                const existing = result.get(publicPath);
+                if (existing)
+                    throw new Error(`context_authority_unicode_collision:${existing.physical_path}:${physicalPath}:${publicPath}`);
+                const portabilityKey = portableContextPathCaseKey(publicPath);
+                const caseCollision = portabilityKeys.get(portabilityKey);
+                if (caseCollision && caseCollision !== publicPath)
+                    throw new Error(`context_authority_case_collision:${caseCollision}:${publicPath}`);
+                portabilityKeys.set(portabilityKey, publicPath);
+                result.set(publicPath, {
+                    path: publicPath,
+                    physical_path: physicalPath,
+                    absolute_path: absolute,
+                });
             }
         }
     }
     await visit(contextRoot);
-    return result.sort();
+    return [...result.values()].sort((left, right) => compareUtf8Paths(left.path, right.path));
 }
 async function readContextManifest(root) {
     const manifestFile = await assertProtectedRepositoryFile(root, path.join(root, "project_context", "context.toml"), "context_manifest");
@@ -163,16 +191,9 @@ async function hashFile(root, file) {
     const protectedFile = await assertProtectedRepositoryFile(root, file, "context_authority");
     return sha256Hex(await readFile(protectedFile));
 }
-function repoRelative(root, file) {
-    const value = path.relative(root, file).replace(/\\/g, "/");
-    if (value.startsWith("../") || path.isAbsolute(value)) {
-        throw new Error(`Path is outside repository: ${file}`);
-    }
-    return value;
-}
 function normalizeRepoPath(value) {
-    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+    return normalizeContextPath(value);
 }
 function sortRecord(value) {
-    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => compareUtf8Paths(left, right)));
 }

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

@@ -0,0 +1,9 @@
+import type { ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextMarkdownCatalogAnalysis } from "../context-markdown/context-markdown-types.js";
+import type { ContextInspectResult, ContextInspectRoute } from "./context-inspect-types.js";
+export declare function projectContextInspection(input: {
+    catalog: ContextCatalog;
+    markdown: ContextMarkdownCatalogAnalysis;
+    context_path: string;
+    route: ContextInspectRoute | null;
+}): ContextInspectResult;

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

@@ -0,0 +1,49 @@
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+const CORE_ROLES = new Map([
+    ["project_context/global.md", "global"],
+    ["project_context/architecture.md", "architecture"],
+]);
+export function projectContextInspection(input) {
+    const fileAnalysis = input.markdown.files.find((candidate) => candidate.path === input.context_path);
+    if (!fileAnalysis)
+        throw new Error(`Context Markdown analysis omitted ${input.context_path}`);
+    const registered = input.catalog.registered_contexts.find((candidate) => candidate.path === input.context_path);
+    const coreRole = CORE_ROLES.get(input.context_path);
+    const reasons = [
+        ...(input.catalog.default_footprint.get(input.context_path) ?? []),
+    ].sort(compareUtf8Paths);
+    const declarationKeys = new Set(fileAnalysis.declarations.map((entry) => `${entry.type}\0${entry.id}`));
+    return {
+        schema_version: 1,
+        path: input.context_path,
+        registration: registered || coreRole !== undefined ? "registered" : "unregistered",
+        source: coreRole !== undefined ? "core" : (registered?.source ?? null),
+        role: coreRole ?? registered?.role ?? null,
+        read_policy: registered?.read_policy ?? null,
+        read_when: registered?.context?.read_when ?? null,
+        triggers: [...(registered?.context?.triggers ?? [])],
+        default_children: [...(registered?.context?.default_children ?? [])],
+        bytes: fileAnalysis.bytes,
+        default_footprint: {
+            selected: reasons.length > 0,
+            reasons,
+        },
+        referenced_by: input.markdown.references
+            .filter((reference) => reference.status === "valid" &&
+            reference.target_path === input.context_path)
+            .sort(referenceOrder),
+        references: [...fileAnalysis.references].sort(referenceOrder),
+        stable_key_declarations: fileAnalysis.declarations,
+        stable_key_conflicts: input.markdown.declaration_conflicts.filter((conflict) => declarationKeys.has(`${conflict.type}\0${conflict.id}`)),
+        route: input.route,
+        diagnostics: input.catalog.diagnostics.filter((diagnostic) => diagnostic.severity === "error" ||
+            diagnostic.path === undefined ||
+            diagnostic.path === input.context_path),
+    };
+}
+function referenceOrder(left, right) {
+    return (compareUtf8Paths(left.source_path, right.source_path) ||
+        left.line - right.line ||
+        left.column - right.column ||
+        compareUtf8Paths(left.destination, right.destination));
+}

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

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

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

@@ -0,0 +1,29 @@
+export function renderContextInspectText(result) {
+    const lines = [
+        `Context: ${result.path}`,
+        `registration=${result.registration} source=${result.source ?? "none"} role=${result.role ?? "unknown"}`,
+        `read_policy=${result.read_policy ?? "none"} bytes=${result.bytes}`,
+        `default=${result.default_footprint.selected}${result.default_footprint.reasons.length > 0 ? ` reasons=${result.default_footprint.reasons.join(",")}` : ""}`,
+        `read_when=${result.read_when ?? "none"}`,
+        `triggers=${result.triggers.length > 0 ? result.triggers.join(", ") : "none"}`,
+        `default_children=${result.default_children.length > 0 ? result.default_children.join(", ") : "none"}`,
+        `referenced_by=${result.referenced_by.length}`,
+    ];
+    for (const reference of result.referenced_by)
+        lines.push(`  ${reference.source_path}:${reference.line}:${reference.column} (${reference.kind})`);
+    lines.push(`references=${result.references.length}`);
+    for (const reference of result.references)
+        lines.push(`  ${reference.line}:${reference.column} ${reference.status} ${reference.target_path ?? reference.destination}`);
+    lines.push(`stable_key_declarations=${result.stable_key_declarations.length} conflicts=${result.stable_key_conflicts.length}`);
+    if (result.route) {
+        lines.push(`route complete=${result.route.complete} catalog_valid=${result.route.catalog_valid} selected=${result.route.selected}`);
+        if (result.route.candidate)
+            for (const reason of result.route.candidate.reasons)
+                lines.push(`  ${reason.kind}: ${reason.input} — ${reason.detail}`);
+        else
+            lines.push("  no path, trigger, bounded literal or manual selection reason matched this Context");
+    }
+    for (const diagnostic of result.diagnostics)
+        lines.push(`${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}`);
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,43 @@
+import type { CatalogDiagnostic } from "../context-catalog/catalog-types.js";
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { DefaultContextSelectionReason } from "../context-catalog/catalog-default-footprint.js";
+import type { ContextMarkdownReference, ContextStableKeyConflict, ContextStableKeyDeclaration } from "../context-markdown/context-markdown-types.js";
+import type { ContextRouteAmbiguity, ContextRouteCandidate, ContextRouteUnresolved } from "../context-router/context-route-types.js";
+export interface ContextInspectRoute {
+    complete: boolean;
+    catalog_valid: boolean;
+    selected: boolean;
+    candidate: ContextRouteCandidate | null;
+    ambiguous: ContextRouteAmbiguity[];
+    unresolved: ContextRouteUnresolved[];
+}
+export interface ContextInspectResult {
+    schema_version: 1;
+    path: string;
+    registration: "registered" | "unregistered";
+    source: "core" | "area" | "context" | null;
+    role: ContextRole | null;
+    read_policy: string | null;
+    read_when: string | null;
+    triggers: string[];
+    default_children: string[];
+    bytes: number;
+    default_footprint: {
+        selected: boolean;
+        reasons: DefaultContextSelectionReason[];
+    };
+    referenced_by: ContextMarkdownReference[];
+    references: ContextMarkdownReference[];
+    stable_key_declarations: ContextStableKeyDeclaration[];
+    stable_key_conflicts: ContextStableKeyConflict[];
+    route: ContextInspectRoute | null;
+    diagnostics: CatalogDiagnostic[];
+}
+export interface ContextInspectInput {
+    project_root: string;
+    context_path: string;
+    route_task?: string;
+    route_paths?: string[];
+    route_terms?: string[];
+    route_case_sensitive?: boolean;
+}

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

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

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

@@ -0,0 +1,2 @@
+import type { ContextInspectInput, ContextInspectResult } from "./context-inspect-types.js";
+export declare function inspectContext(input: ContextInspectInput): Promise<ContextInspectResult>;

package/dist/lib/context-inspect/context-inspect.js

@@ -0,0 +1,104 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { isPathWithin, normalizeContextPath, } from "../context-catalog/catalog-paths.js";
+import { analyzeContextMarkdownCatalog } from "../context-markdown/context-markdown-analysis.js";
+import { routeContext } from "../context-router/context-route.js";
+import { projectContextInspection } from "./context-inspect-projection.js";
+export async function inspectContext(input) {
+    const projectRoot = path.resolve(input.project_root);
+    const contextPath = normalizeInspectedPath(input.context_path);
+    let catalog;
+    try {
+        catalog = await loadContextCatalog(projectRoot);
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to load Context Catalog: ${message(error)}`, { cause: error });
+    }
+    const file = catalog.context_files.find((candidate) => candidate.path === contextPath);
+    if (!file)
+        throw new CliCommandError(CLI_EXIT_CODES.io, `Context inspect target is not an eligible Markdown file: ${contextPath}`);
+    try {
+        await verifyOrdinaryInRepositoryFile(projectRoot, file.absolute_path);
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to inspect Context file identity: ${message(error)}`, { cause: error });
+    }
+    let markdown;
+    try {
+        markdown = await analyzeContextMarkdownCatalog({
+            project_root: projectRoot,
+            files: catalog.context_files,
+            long_line_threshold: Number.MAX_SAFE_INTEGER,
+        });
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to analyze Context Markdown: ${message(error)}`, { cause: error });
+    }
+    const routeRequested = input.route_task !== undefined ||
+        (input.route_paths?.length ?? 0) > 0 ||
+        (input.route_terms?.length ?? 0) > 0;
+    let route = null;
+    if (routeRequested) {
+        const routed = await routeContext({
+            project_root: projectRoot,
+            task: input.route_task ?? "",
+            paths: input.route_paths ?? [],
+            explicit_terms: input.route_terms ?? [],
+            case_sensitive: input.route_case_sensitive,
+        });
+        const candidate = [
+            ...routed.candidates,
+            ...routed.unregistered_matches,
+        ].find((entry) => entry.path === contextPath);
+        route = {
+            complete: routed.complete,
+            catalog_valid: routed.catalog_valid,
+            selected: Boolean(candidate),
+            candidate: candidate ?? null,
+            ambiguous: routed.ambiguous,
+            unresolved: routed.unresolved,
+        };
+    }
+    try {
+        return projectContextInspection({
+            catalog,
+            markdown,
+            context_path: contextPath,
+            route,
+        });
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.internal, message(error), {
+            cause: error,
+        });
+    }
+}
+function normalizeInspectedPath(value) {
+    if (path.isAbsolute(value))
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect requires a repository-relative path");
+    const normalized = normalizeContextPath(value);
+    if (!normalized.startsWith("project_context/") ||
+        !normalized.toLowerCase().endsWith(".md") ||
+        normalized.split("/").includes(".."))
+        throw new CliCommandError(CLI_EXIT_CODES.io, `Context inspect target must be a Markdown file under project_context/: ${value}`);
+    return normalized;
+}
+async function verifyOrdinaryInRepositoryFile(projectRoot, absolutePath) {
+    const metadata = await lstat(absolutePath);
+    if (!metadata.isFile() || metadata.isSymbolicLink())
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect target must be an ordinary file");
+    const repositoryIdentity = await realpath(projectRoot);
+    // Catalog discovery owns the canonical NFC key -> physical file mapping.
+    // Re-resolving the key would lose an NFD spelling on filesystems that keep
+    // canonical-equivalent names distinct.
+    const targetIdentity = await realpath(absolutePath);
+    if (!isPathWithin(repositoryIdentity, targetIdentity))
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect target resolves outside the repository");
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-manifest-schema.d.ts

@@ -1,4 +1,4 @@
-export type ContextRole = "global" | "architecture" | "area" | "domain" | "subdomain" | "foundation" | "archive" | "contract" | "verification" | "deployment" | "implementation-index" | "decision-rationale";
+export type { ContextRole } from "./context-catalog/catalog-portable-contract.js";
 export interface ContextAreaEntry {
     line: number;
     id: string;

package/dist/lib/context-manifest-schema.js

@@ -1,21 +1,5 @@
 import { parse } from "smol-toml";
-const TOP_LEVEL_FIELDS = new Set(["areas", "context"]);
-const AREA_FIELDS = new Set([
-    "id",
-    "root",
-    "context",
-    "kind",
-    "default",
-    "forbidden_runtime_dependencies",
-]);
-const CONTEXT_FIELDS = new Set([
-    "path",
-    "role",
-    "read_when",
-    "read_policy",
-    "triggers",
-    "default_children",
-]);
+import { CONTEXT_AREA_FIELDS, CONTEXT_NODE_FIELDS, CONTEXT_TOP_LEVEL_FIELDS, } from "./context-catalog/catalog-portable-contract.js";
 export function parseContextManifest(content, file = "project_context/context.toml") {
     const errors = [];
     let parsed;
@@ -29,7 +13,7 @@ export function parseContextManifest(content, file = "project_context/context.to
             ],
         };
     }
-    rejectUnknownFields(parsed, TOP_LEVEL_FIELDS, file, errors);
+    rejectUnknownFields(parsed, CONTEXT_TOP_LEVEL_FIELDS, file, errors);
     const rawAreas = tableArray(parsed.areas, "[[areas]]", file, errors);
     const rawContexts = tableArray(parsed.context, "[[context]]", file, errors);
     const areaLines = tableLines(content, "areas");
@@ -37,7 +21,7 @@ export function parseContextManifest(content, file = "project_context/context.to
     const areas = [];
     for (const [index, value] of rawAreas.entries()) {
         const location = `${file} line ${areaLines[index] ?? 1}`;
-        rejectUnknownFields(value, AREA_FIELDS, location, errors);
+        rejectUnknownFields(value, CONTEXT_AREA_FIELDS, location, errors);
         const id = requiredString(value, "id", location, errors);
         const root = requiredString(value, "root", location, errors);
         const context = requiredString(value, "context", location, errors);
@@ -59,7 +43,7 @@ export function parseContextManifest(content, file = "project_context/context.to
     const contexts = [];
     for (const [index, value] of rawContexts.entries()) {
         const location = `${file} line ${contextLines[index] ?? 1}`;
-        rejectUnknownFields(value, CONTEXT_FIELDS, location, errors);
+        rejectUnknownFields(value, CONTEXT_NODE_FIELDS, location, errors);
         const path = requiredString(value, "path", location, errors);
         const role = requiredString(value, "role", location, errors);
         const readWhen = optionalString(value, "read_when", location, errors);

package/dist/lib/context-markdown/context-markdown-analysis.d.ts

@@ -0,0 +1,15 @@
+import type { CatalogFile } from "../context-catalog/catalog-types.js";
+import type { ContextMarkdownCatalogAnalysis, ContextMarkdownFileAnalysis } from "./context-markdown-types.js";
+export declare function analyzeContextMarkdownCatalog(input: {
+    project_root: string;
+    files: CatalogFile[];
+    long_line_threshold: number;
+    file_overrides?: ReadonlyMap<string, Uint8Array | null>;
+}): Promise<ContextMarkdownCatalogAnalysis>;
+export declare function analyzeContextMarkdownFile(input: {
+    project_root: string;
+    file: CatalogFile;
+    catalog_files?: ReadonlyMap<string, CatalogFile>;
+    long_line_threshold: number;
+    file_overrides?: ReadonlyMap<string, Uint8Array | null>;
+}): Promise<ContextMarkdownFileAnalysis>;