project-tiny-context-harness 0.11.0 → 0.12.0

package/dist/lib/context-router/context-route-types.d.ts

@@ -1,101 +0,0 @@
-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 { ContextRouteBudgetName } from "./context-route-budget.js";
-export type ContextRouteTermSource = "explicit" | "quoted_phrase" | "code_identifier" | "path_fragment" | "manifest_trigger" | "stable_name";
-export interface ContextRouteTerm {
-    value: string;
-    normalized: string;
-    source: ContextRouteTermSource;
-    order: number;
-}
-export type ContextRouteGroup = "default_registered" | "on_demand_registered" | "legacy_registered" | "unregistered" | "path_candidates" | "trigger_candidates" | "literal_candidates" | "manual_includes";
-export interface ContextRouteMatch {
-    term: string;
-    term_source: ContextRouteTermSource;
-    line: number;
-    column: number;
-}
-export interface ContextRouteReason {
-    kind: "default" | "path" | "trigger" | "literal" | "manual_include";
-    input: string;
-    detail: string;
-}
-export interface ContextRouteCandidate {
-    path: string;
-    registration: "registered" | "unregistered";
-    role: ContextRole | null;
-    read_policy: string | null;
-    groups: ContextRouteGroup[];
-    reasons: ContextRouteReason[];
-    matched_terms: string[];
-    matched_paths: string[];
-    matches: ContextRouteMatch[];
-    bytes: number;
-    cumulative_bytes: number;
-}
-export interface ContextRouteDefaultEntry {
-    path: string;
-    reasons: DefaultContextSelectionReason[];
-    bytes: number;
-    cumulative_bytes: number;
-}
-export interface ContextRouteAreaCandidate {
-    id: string;
-    root: string;
-    context: string;
-}
-export interface ContextRouteAmbiguity {
-    kind: "area_path";
-    input: string;
-    candidates: ContextRouteAreaCandidate[];
-    reason: string;
-}
-export interface ContextRouteUnresolved {
-    kind: "path" | "include";
-    input: string;
-    reason: string;
-}
-export interface ContextRouteBudgetExceeded {
-    budget: ContextRouteBudgetName;
-    limit: number;
-    observed: number;
-    path?: string;
-}
-export interface ContextRouteScanReport {
-    files_considered: number;
-    files_scanned: number;
-    bytes_scanned: number;
-    budget_exceeded: boolean;
-    exceeded: ContextRouteBudgetExceeded[];
-}
-export interface ContextRouteResult {
-    schema_version: 1;
-    complete: boolean;
-    catalog_valid: boolean;
-    experimental: true;
-    authority: false;
-    workflow_search_replaced: false;
-    matching: {
-        literal: true;
-        unicode_normalization: "NFC";
-        case_sensitive: boolean;
-    };
-    scan: ContextRouteScanReport;
-    output_truncated: boolean;
-    default_context: ContextRouteDefaultEntry[];
-    candidates: ContextRouteCandidate[];
-    unregistered_matches: ContextRouteCandidate[];
-    ambiguous: ContextRouteAmbiguity[];
-    unresolved: ContextRouteUnresolved[];
-    diagnostics: CatalogDiagnostic[];
-}
-export interface ContextRouteInput {
-    project_root: string;
-    task: string;
-    paths?: string[];
-    explicit_terms?: string[];
-    includes?: string[];
-    case_sensitive?: boolean;
-    max_search_results?: number;
-}

package/dist/lib/context-router/context-route-types.js

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

package/dist/lib/context-router/context-route.d.ts

@@ -1,2 +0,0 @@
-import type { ContextRouteInput, ContextRouteResult } from "./context-route-types.js";
-export declare function routeContext(input: ContextRouteInput): Promise<ContextRouteResult>;

package/dist/lib/context-router/context-route.js

@@ -1,127 +0,0 @@
-import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
-import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
-import { loadContextCatalog } from "../context-catalog/catalog-load.js";
-import { CONTEXT_ROUTE_BUDGETS, CONTEXT_ROUTE_SCHEMA_VERSION, } from "./context-route-budget.js";
-import { defaultEntries, emptyResult } from "./context-route-candidates.js";
-import { stableRouteBudgetExceeded } from "./context-route-order.js";
-import { matchContextAreas, normalizeRepositoryInputs, resolveManualIncludes, } from "./context-route-paths.js";
-import { scanContextCatalogFiles } from "./context-route-scan.js";
-import { selectContextRouteCandidates } from "./context-route-selection.js";
-import { buildContextRouteTerms } from "./context-route-terms.js";
-export async function routeContext(input) {
-    const caseSensitive = input.case_sensitive ?? false;
-    const maxSearchResults = input.max_search_results ?? CONTEXT_ROUTE_BUDGETS.output_matches;
-    const inputExceeded = [];
-    const taskBytes = Buffer.byteLength(input.task, "utf8");
-    let task = input.task;
-    if (taskBytes > CONTEXT_ROUTE_BUDGETS.task_utf8_bytes) {
-        inputExceeded.push({
-            budget: "task_utf8_bytes",
-            limit: CONTEXT_ROUTE_BUDGETS.task_utf8_bytes,
-            observed: taskBytes,
-        });
-        task = utf8Prefix(input.task, CONTEXT_ROUTE_BUDGETS.task_utf8_bytes);
-    }
-    let catalog;
-    try {
-        catalog = await loadContextCatalog(input.project_root);
-    }
-    catch (error) {
-        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to load Context Catalog: ${message(error)}`, { cause: error });
-    }
-    const catalogValid = !catalog.diagnostics.some((entry) => entry.severity === "error");
-    const defaultContext = defaultEntries(catalog);
-    if (!catalogValid) {
-        return emptyResult({
-            catalog,
-            caseSensitive,
-            defaultContext,
-            exceeded: inputExceeded,
-        });
-    }
-    const paths = normalizeRepositoryInputs(input.paths ?? [], "--path");
-    const triggers = [
-        ...new Set(catalog.registered_contexts.flatMap((entry) => (entry.context?.triggers ?? []).map((trigger) => trigger.normalize("NFC")))),
-    ].sort(compareUtf8Paths);
-    const termBuild = buildContextRouteTerms({
-        task,
-        explicit_terms: input.explicit_terms ?? [],
-        paths,
-        manifest_triggers: triggers,
-        case_sensitive: caseSensitive,
-    });
-    inputExceeded.push(...termBuild.exceeded);
-    const pathResult = matchContextAreas(catalog, paths);
-    let includes;
-    try {
-        includes = await resolveManualIncludes(catalog, input.includes ?? []);
-    }
-    catch (error) {
-        if (error instanceof CliCommandError)
-            throw error;
-        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to resolve route includes: ${message(error)}`, { cause: error });
-    }
-    let scanned;
-    try {
-        scanned = await scanContextCatalogFiles({
-            files: catalog.context_files,
-            terms: termBuild.terms,
-            case_sensitive: caseSensitive,
-            max_search_results: maxSearchResults,
-        });
-    }
-    catch (error) {
-        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to scan Context files: ${message(error)}`, { cause: error });
-    }
-    const selected = selectContextRouteCandidates({
-        catalog,
-        default_context: defaultContext,
-        path_matches: pathResult.matches,
-        literal_matches: scanned.matches_by_path,
-        includes,
-        task,
-        case_sensitive: caseSensitive,
-    });
-    const scanExceeded = [...inputExceeded, ...scanned.scan.exceeded];
-    const scan = {
-        ...scanned.scan,
-        budget_exceeded: scanExceeded.length > 0,
-        exceeded: stableRouteBudgetExceeded(scanExceeded),
-    };
-    return {
-        schema_version: CONTEXT_ROUTE_SCHEMA_VERSION,
-        complete: !scan.budget_exceeded,
-        catalog_valid: true,
-        experimental: true,
-        authority: false,
-        workflow_search_replaced: false,
-        matching: {
-            literal: true,
-            unicode_normalization: "NFC",
-            case_sensitive: caseSensitive,
-        },
-        scan,
-        output_truncated: scanned.output_truncated,
-        default_context: defaultContext,
-        candidates: selected.registered,
-        unregistered_matches: selected.unregistered,
-        ambiguous: pathResult.ambiguous,
-        unresolved: pathResult.unresolved,
-        diagnostics: catalog.diagnostics,
-    };
-}
-function utf8Prefix(value, maximumBytes) {
-    let bytes = 0;
-    let result = "";
-    for (const point of Array.from(value)) {
-        const size = Buffer.byteLength(point, "utf8");
-        if (bytes + size > maximumBytes)
-            break;
-        result += point;
-        bytes += size;
-    }
-    return result;
-}
-function message(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/lib/context-units-migration.d.ts

@@ -1,13 +0,0 @@
-import type { Migration } from "./migrations.js";
-type ConversionPlan = {
-    status: "absent";
-} | {
-    status: "safe";
-    content: string;
-} | {
-    status: "manual";
-    reason: string;
-};
-export declare const contextUnitsMigration: Migration;
-export declare function planContextUnitsConversion(content: string): ConversionPlan;
-export {};

package/dist/lib/context-units-migration.js

@@ -1,217 +0,0 @@
-import { parse } from "smol-toml";
-import path from "node:path";
-import { CONTEXT_MANIFEST_PATH } from "./context-manifest.js";
-import { parseContextManifest } from "./context-manifest-schema.js";
-import { loadContextCatalog } from "./context-catalog/catalog-load.js";
-import { pathExists, readText, writeTextIfChanged } from "./fs.js";
-const ID = "context-units-to-context";
-const INTRODUCED_IN = "0.10.0";
-const DESCRIPTION = "Convert provably simple legacy [[context_units]] tables to Schema v4 [[context]] tables without rewriting the Manifest.";
-const SCOPE = "project_context/context.toml";
-const CURRENT_FIELDS = new Set([
-    "path",
-    "role",
-    "read_when",
-    "read_policy",
-    "triggers",
-    "default_children",
-]);
-const LEGACY_ONLY_FIELDS = new Set(["id", "area"]);
-export const contextUnitsMigration = {
-    id: ID,
-    introducedIn: INTRODUCED_IN,
-    description: DESCRIPTION,
-    scope: SCOPE,
-    risk: "safe",
-    manualMessage: "Convert complex legacy Context tables manually; Tiny Context will not canonicalize or guess their fields.",
-    detect: async (projectRoot) => {
-        const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
-        if (!(await pathExists(manifestPath)))
-            return [];
-        const plan = planContextUnitsConversion(await readText(manifestPath));
-        if (plan.status === "absent")
-            return [];
-        return [
-            planItem(plan.status === "safe" ? "safe_pending" : "manual_required", plan.status === "safe"
-                ? "Convert simple legacy Context tables with a bounded byte patch."
-                : plan.reason),
-        ];
-    },
-    apply: migrateContextUnits,
-    verify: verifyContextUnitsMigration,
-};
-export function planContextUnitsConversion(content) {
-    if (!/^[ \t]*\[\[[ \t]*context_units[ \t]*\]\]/mu.test(content))
-        return { status: "absent" };
-    let decoded;
-    try {
-        const value = parse(content);
-        if (!isRecord(value))
-            return {
-                status: "manual",
-                reason: "legacy Manifest root is not a TOML table",
-            };
-        decoded = value;
-    }
-    catch (error) {
-        return {
-            status: "manual",
-            reason: `legacy Manifest is not valid TOML: ${message(error)}`,
-        };
-    }
-    const units = decoded.context_units;
-    if (!Array.isArray(units) || units.some((entry) => !isRecord(entry)))
-        return {
-            status: "manual",
-            reason: "context_units must be an array of TOML tables",
-        };
-    const currentContexts = decoded.context;
-    if (currentContexts !== undefined &&
-        (!Array.isArray(currentContexts) ||
-            currentContexts.some((entry) => !isRecord(entry))))
-        return {
-            status: "manual",
-            reason: "current context tables are malformed",
-        };
-    const currentPaths = new Set((currentContexts ?? [])
-        .map((entry) => (typeof entry.path === "string" ? entry.path : null))
-        .filter((entry) => entry !== null));
-    const legacyPaths = new Set();
-    for (const unit of units) {
-        const unknown = Object.keys(unit).filter((key) => !CURRENT_FIELDS.has(key) && !LEGACY_ONLY_FIELDS.has(key));
-        if (unknown.length > 0)
-            return {
-                status: "manual",
-                reason: `legacy Context table has unsupported fields: ${unknown.join(", ")}`,
-            };
-        if (typeof unit.path !== "string" || typeof unit.role !== "string")
-            return {
-                status: "manual",
-                reason: "every legacy Context table requires string path and role fields",
-            };
-        if (legacyPaths.has(unit.path) || currentPaths.has(unit.path))
-            return {
-                status: "manual",
-                reason: `legacy Context path conflicts with another table: ${unit.path}`,
-            };
-        legacyPaths.add(unit.path);
-    }
-    const patched = patchSimpleLegacyTables(content);
-    if (patched.status === "manual")
-        return patched;
-    if (patched.status === "absent")
-        return {
-            status: "manual",
-            reason: "legacy Context tables disappeared during conversion planning",
-        };
-    const parsed = parseContextManifest(patched.content);
-    if (parsed.errors.length > 0)
-        return {
-            status: "manual",
-            reason: `converted Manifest is not valid Schema v4: ${parsed.errors[0]}`,
-        };
-    return patched;
-}
-async function migrateContextUnits(projectRoot, _root, report) {
-    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
-    const plan = planContextUnitsConversion(await readText(manifestPath));
-    if (plan.status === "absent") {
-        report.skipped.push(`${CONTEXT_MANIFEST_PATH}#context-units`);
-        return;
-    }
-    if (plan.status === "manual")
-        throw new Error(`${CONTEXT_MANIFEST_PATH} changed after upgrade planning or is not safely convertible: ${plan.reason}`);
-    if (await writeTextIfChanged(manifestPath, plan.content))
-        report.changed.push(`${CONTEXT_MANIFEST_PATH}#context-units-to-context`);
-    else
-        report.skipped.push(`${CONTEXT_MANIFEST_PATH}#context-units-to-context`);
-}
-async function verifyContextUnitsMigration(projectRoot) {
-    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
-    const content = await readText(manifestPath);
-    if (/^[ \t]*\[\[[ \t]*context_units[ \t]*\]\]/mu.test(content))
-        throw new Error("context-units-to-context migration verification failed");
-    const catalog = await loadContextCatalog(projectRoot);
-    const errors = catalog.diagnostics.filter((entry) => entry.severity === "error");
-    if (errors.length > 0)
-        throw new Error(`context-units-to-context produced an invalid Catalog: ${errors[0].message}`);
-}
-function patchSimpleLegacyTables(content) {
-    const eols = content.match(/\r\n|\r|\n/gu) ?? [];
-    if (new Set(eols).size > 1)
-        return {
-            status: "manual",
-            reason: "legacy Manifest has mixed line endings",
-        };
-    const eol = eols[0] ?? "\n";
-    const lines = content.split(eol);
-    let inLegacyTable = false;
-    let convertedTables = 0;
-    const output = [];
-    for (const line of lines) {
-        const table = /^[ \t]*\[\[[ \t]*([^\]]+?)[ \t]*\]\](?:[ \t]*#.*)?$/u.exec(line);
-        const otherTable = /^[ \t]*\[[^[]/u.test(line);
-        if (table) {
-            inLegacyTable = table[1].trim() === "context_units";
-            if (inLegacyTable) {
-                output.push(line.replace(/(\[\[[ \t]*)context_units([ \t]*\]\])/u, "$1context$2"));
-                convertedTables += 1;
-            }
-            else
-                output.push(line);
-            continue;
-        }
-        if (otherTable)
-            inLegacyTable = false;
-        if (!inLegacyTable || !line.trim() || line.trimStart().startsWith("#")) {
-            output.push(line);
-            continue;
-        }
-        const assignment = /^[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*=(.*)$/u.exec(line);
-        if (!assignment)
-            return {
-                status: "manual",
-                reason: "legacy Context tables must use simple single-line field assignments",
-            };
-        const key = assignment[1];
-        if (!CURRENT_FIELDS.has(key) && !LEGACY_ONLY_FIELDS.has(key))
-            return {
-                status: "manual",
-                reason: `legacy Context table has unsupported source field: ${key}`,
-            };
-        try {
-            parse(line);
-        }
-        catch {
-            return {
-                status: "manual",
-                reason: `legacy Context field ${key} is not a complete single-line TOML value`,
-            };
-        }
-        if (!LEGACY_ONLY_FIELDS.has(key))
-            output.push(line);
-    }
-    if (convertedTables === 0)
-        return {
-            status: "manual",
-            reason: "no exact legacy table header was found",
-        };
-    return { status: "safe", content: output.join(eol) };
-}
-function planItem(status, reason) {
-    return {
-        id: ID,
-        introducedIn: INTRODUCED_IN,
-        description: DESCRIPTION,
-        scope: SCOPE,
-        status,
-        path: CONTEXT_MANIFEST_PATH,
-        message: reason,
-    };
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function message(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/lib/design-authority-binding.d.ts

@@ -1,7 +0,0 @@
-import { type DesignAuthorityHandoffBinding, type DesignAuthorityHandoffResolution } from "./design-authority-types.js";
-export declare function parseDesignAuthorityHandoffBinding(value: unknown, label: string): DesignAuthorityHandoffBinding;
-export declare function resolveDesignAuthorityHandoffBinding(input: {
-    repository: string;
-    style_dependency: "style-bearing" | "non-fidelity" | "mixed";
-    binding?: DesignAuthorityHandoffBinding;
-}): Promise<DesignAuthorityHandoffResolution>;

package/dist/lib/design-authority-binding.js

@@ -1,96 +0,0 @@
-import { loadCurrentDesignAuthorityClosure, inspectDesignAuthorityClosure, } from "./design-authority-closure.js";
-import { DESIGN_AUTHORITY_ENTRY_PATH, DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION, DESIGN_AUTHORITY_MANIFEST_PATH, isDesignAuthorityDigest, } from "./design-authority-types.js";
-import { designResourceShapeFail } from "./design-resource-handoff-shape-primitives.js";
-import { literal, object, string } from "./long-task-shape-primitives.js";
-export function parseDesignAuthorityHandoffBinding(value, label) {
-    const base = object(value, label, ["kind"], [
-        "format_version",
-        "entry_path",
-        "manifest_path",
-        "closure_digest",
-        "revision",
-        "rationale",
-    ]);
-    const kind = literal(base.kind, ["repository-closure", "not-applicable"], `${label}.kind`);
-    if (kind === "not-applicable") {
-        const row = object(value, label, ["kind", "rationale"]);
-        return {
-            kind,
-            rationale: string(row.rationale, `${label}.rationale`),
-        };
-    }
-    const row = object(value, label, [
-        "kind",
-        "format_version",
-        "entry_path",
-        "manifest_path",
-        "closure_digest",
-        "revision",
-    ]);
-    if (row.format_version !== DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION)
-        designResourceShapeFail(`${label}.format_version`, `must equal ${DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION}`);
-    if (row.entry_path !== DESIGN_AUTHORITY_ENTRY_PATH)
-        designResourceShapeFail(`${label}.entry_path`, `must equal ${DESIGN_AUTHORITY_ENTRY_PATH}`);
-    if (row.manifest_path !== null &&
-        row.manifest_path !== DESIGN_AUTHORITY_MANIFEST_PATH)
-        designResourceShapeFail(`${label}.manifest_path`, `must be null or ${DESIGN_AUTHORITY_MANIFEST_PATH}`);
-    if (!isDesignAuthorityDigest(row.closure_digest))
-        designResourceShapeFail(`${label}.closure_digest`, "must be a sha256:<64 lowercase hex> identity");
-    if (row.revision !== null && typeof row.revision !== "string")
-        designResourceShapeFail(`${label}.revision`, "must be a string or null");
-    if (typeof row.revision === "string" && !row.revision.trim())
-        designResourceShapeFail(`${label}.revision`, "must not be empty");
-    return {
-        kind,
-        format_version: DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION,
-        entry_path: DESIGN_AUTHORITY_ENTRY_PATH,
-        manifest_path: row.manifest_path,
-        closure_digest: row.closure_digest,
-        revision: row.revision,
-    };
-}
-export async function resolveDesignAuthorityHandoffBinding(input) {
-    if (!input.binding) {
-        const inspection = await inspectDesignAuthorityClosure(input.repository);
-        if (inspection.status !== "valid" || !inspection.identity)
-            invalid(`legacy_omission_without_current_authority:${inspection.diagnostics.length
-                ? inspection.diagnostics
-                    .map((item) => `${item.code}:${item.detail}`)
-                    .join("|")
-                : inspection.status}`);
-        if (inspection.mode !== "legacy")
-            invalid("legacy_omission_bundle_not_allowed");
-        return {
-            identity: inspection.identity,
-            member_paths: inspection.member_paths,
-            compatibility_derived: true,
-        };
-    }
-    if (input.binding.kind === "not-applicable") {
-        if (input.style_dependency !== "non-fidelity")
-            invalid("not_applicable_requires_non_fidelity");
-        return {
-            identity: null,
-            member_paths: [],
-            compatibility_derived: false,
-        };
-    }
-    const current = await loadCurrentDesignAuthorityClosure(input.repository);
-    for (const field of [
-        "format_version",
-        "entry_path",
-        "manifest_path",
-        "closure_digest",
-        "revision",
-    ])
-        if (current.identity[field] !== input.binding[field])
-            invalid(`identity_mismatch:${field}:${String(input.binding[field])}:${String(current.identity[field])}`);
-    return {
-        identity: current.identity,
-        member_paths: current.member_paths,
-        compatibility_derived: false,
-    };
-}
-function invalid(reason) {
-    throw new Error(`design_resource_handoff_invalid:project_design_authority:${reason}`);
-}

package/dist/lib/design-authority-closure.d.ts

@@ -1,3 +0,0 @@
-import { type DesignAuthorityClosureSnapshot, type DesignAuthorityInspection } from "./design-authority-types.js";
-export declare function inspectDesignAuthorityClosure(repositoryInput: string): Promise<DesignAuthorityInspection>;
-export declare function loadCurrentDesignAuthorityClosure(repository: string): Promise<DesignAuthorityClosureSnapshot>;