@cairn-tool/cairn 2.0.0

package/dist/context.d.ts

@@ -0,0 +1,106 @@
+import { type DocumentSection } from "./sections.js";
+import type { Workspace } from "./workspace.js";
+export type ContextUnitKind = "frontmatter" | "preamble" | "section";
+export type ContextDirection = "seed" | "link" | "backlink";
+export interface ContextProvenance {
+    /** Graph hops from the nearest seed; 0 for a seed. */
+    distance: number;
+    /** The document that pulled this one in. Absent at distance 0. */
+    via?: string;
+    /**
+     * Line carrying the link. Absent at distance 0.
+     *
+     * The graph stores each edge's lines against its source, so this is a line in
+     * `via` when `direction` is "link" and a line in *this* document when it is
+     * "backlink" — the link points the other way.
+     */
+    viaLine?: number;
+    direction: ContextDirection;
+    reason: string;
+}
+export interface ContextUnit {
+    /** `<file>#<slug>`, `<file>#frontmatter`, or `<file>#preamble`. */
+    id: string;
+    kind: ContextUnitKind;
+    file: string;
+    heading: string | null;
+    slug: string | null;
+    /** Heading depth; 0 for a preamble or frontmatter unit. */
+    depth: number;
+    startLine: number;
+    endLine: number;
+    /** UTF-8 bytes of `content`. */
+    bytes: number;
+    provenance: ContextProvenance;
+    content: string;
+}
+export interface ContextOmission {
+    id: string;
+    file: string;
+    heading: string | null;
+    bytes: number;
+    reason: "budget";
+}
+export interface ContextBrokenDependency {
+    source: string;
+    /** The link target as written. */
+    target: string;
+    /** The path it resolved to. */
+    resolved: string;
+    line: number;
+}
+export interface ContextBudgetReport {
+    /** Null when no budget was set. */
+    limitBytes: number | null;
+    usedBytes: number;
+    omittedBytes: number;
+    /**
+     * ceil(usedBytes / 4). A size signal, not a model tokenizer, and it never
+     * gates inclusion — only bytes do.
+     */
+    tokenEstimate: number;
+    truncated: boolean;
+}
+export interface ContextPack {
+    seeds: string[];
+    depth: number;
+    backlinks: boolean;
+    /** Documents contributing at least one included unit. */
+    files: string[];
+    units: ContextUnit[];
+    omitted: ContextOmission[];
+    broken: ContextBrokenDependency[];
+    budget: ContextBudgetReport;
+    totals: {
+        files: number;
+        units: number;
+        bytes: number;
+    };
+}
+export interface ContextSeed {
+    file: string;
+    /** Restrict this seed to these positions in its section partition. */
+    sections?: number[];
+}
+export interface ContextRequest {
+    workspace: Workspace;
+    /** In discovery order; the first seed listed is the first unit emitted. */
+    seeds: ContextSeed[];
+    /** Every document the traversal may reach. */
+    files: string[];
+    depth: number;
+    backlinks: boolean;
+    frontmatter: boolean;
+    /** 0 means unlimited. */
+    budgetBytes: number;
+    /** Renders an absolute path for output. */
+    path: (file: string) => string;
+}
+/**
+ * The descendants of `sections[index]` in a flat partition: every following
+ * section deeper than it, stopping at the first that is not.
+ */
+export declare function descendantSections(sections: readonly DocumentSection[], index: number): number[];
+/** Positions a `--section` name selects, including descendants when asked. */
+export declare function selectSections(sections: readonly DocumentSection[], heading: string, children: boolean): number[];
+export declare function buildContextPack(request: ContextRequest): ContextPack;

package/dist/context.js

@@ -0,0 +1,202 @@
+import { buildWorkspaceGraph } from "./graph.js";
+import { documentSections, frontmatterEndLine, matchSectionIndex, } from "./sections.js";
+/**
+ * The descendants of `sections[index]` in a flat partition: every following
+ * section deeper than it, stopping at the first that is not.
+ */
+export function descendantSections(sections, index) {
+    const found = [];
+    for (let next = index + 1; next < sections.length; next++) {
+        if (sections[next].depth <= sections[index].depth)
+            break;
+        found.push(next);
+    }
+    return found;
+}
+/** Positions a `--section` name selects, including descendants when asked. */
+export function selectSections(sections, heading, children) {
+    const index = matchSectionIndex(sections, heading);
+    if (index === -1)
+        return [];
+    return children ? [index, ...descendantSections(sections, index)] : [index];
+}
+function edgeIndexes(edges) {
+    const forward = new Map();
+    const inverse = new Map();
+    for (const edge of edges) {
+        const out = forward.get(edge.source) ?? [];
+        out.push(edge);
+        forward.set(edge.source, out);
+        const back = inverse.get(edge.target) ?? [];
+        back.push(edge);
+        inverse.set(edge.target, back);
+    }
+    return { forward, inverse };
+}
+function reason(selection, shown) {
+    if (selection.direction === "seed")
+        return "Requested as a seed";
+    const via = shown(selection.via ?? "");
+    const hops = `${selection.distance} hop(s) from a seed`;
+    return selection.direction === "backlink"
+        ? `Links to ${via} at line ${selection.viaLine ?? 0}, ${hops}`
+        : `Linked to from ${via}:${selection.viaLine ?? 0}, ${hops}`;
+}
+/**
+ * Breadth-first traversal of the reference graph from the seeds.
+ *
+ * The order is total and has no ties: graph distance, then the order a document
+ * entered the frontier, then document order within it. Every input is a sorted
+ * list, so the same workspace bytes always produce the same pack.
+ */
+function traverse(request, graph) {
+    const { forward, inverse } = edgeIndexes(graph.edges);
+    const order = [];
+    const seen = new Set();
+    const add = (selection) => {
+        if (seen.has(selection.file))
+            return false;
+        seen.add(selection.file);
+        order.push(selection);
+        return true;
+    };
+    for (const seed of request.seeds) {
+        add({
+            file: seed.file,
+            distance: 0,
+            direction: "seed",
+            ...(seed.sections ? { sections: seed.sections } : {}),
+        });
+    }
+    let frontier = order.map((selection) => selection.file);
+    for (let distance = 1; distance <= request.depth && frontier.length; distance++) {
+        const next = [];
+        for (const file of frontier) {
+            // Forward before backward, so a document reachable both ways records the
+            // outbound link as its provenance.
+            for (const edge of forward.get(file) ?? []) {
+                if (add({
+                    file: edge.target,
+                    distance,
+                    via: file,
+                    viaLine: edge.lines[0],
+                    direction: "link",
+                })) {
+                    next.push(edge.target);
+                }
+            }
+            if (!request.backlinks)
+                continue;
+            for (const edge of inverse.get(file) ?? []) {
+                if (add({
+                    file: edge.source,
+                    distance,
+                    via: file,
+                    viaLine: edge.lines[0],
+                    direction: "backlink",
+                })) {
+                    next.push(edge.source);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return order;
+}
+function unitsFor(selection, request, shown) {
+    const document = request.workspace.document(selection.file);
+    const sections = documentSections(document);
+    const file = shown(selection.file);
+    const provenance = {
+        distance: selection.distance,
+        ...(selection.via === undefined ? {} : { via: shown(selection.via) }),
+        ...(selection.viaLine === undefined ? {} : { viaLine: selection.viaLine }),
+        direction: selection.direction,
+        reason: reason(selection, shown),
+    };
+    const unit = (kind, slug, heading, depth, startLine, endLine, content) => ({
+        id: `${file}#${slug ?? kind}`,
+        kind,
+        file,
+        heading,
+        slug,
+        depth,
+        startLine,
+        endLine,
+        bytes: Buffer.byteLength(content, "utf8"),
+        provenance,
+        content,
+    });
+    const units = [];
+    const frontmatterEnd = frontmatterEndLine(document.content);
+    if (request.frontmatter && frontmatterEnd > 0) {
+        const content = document.content.split("\n").slice(0, frontmatterEnd).join("\n");
+        units.push(unit("frontmatter", null, null, 0, 1, frontmatterEnd, content));
+    }
+    const chosen = selection.sections
+        ? selection.sections.filter((index) => index < sections.length)
+        : sections.map((_, index) => index);
+    for (const index of [...chosen].sort((a, b) => a - b)) {
+        const section = sections[index];
+        units.push(unit(section.heading ? "section" : "preamble", section.heading?.slug ?? null, section.heading?.text ?? null, section.depth, section.startLine, section.endLine, section.content));
+    }
+    return units;
+}
+export function buildContextPack(request) {
+    const shown = request.path;
+    const graph = buildWorkspaceGraph(request.workspace, request.files, []);
+    const selections = traverse(request, graph);
+    const ordered = selections.flatMap((selection) => unitsFor(selection, request, shown));
+    // The pack is a prefix of the ordered units: the first unit that would exceed
+    // the budget stops inclusion, and everything after it is omitted too. Skipping
+    // an oversized unit and continuing would make the pack non-contiguous and make
+    // its contents shift unpredictably under small edits.
+    const limit = request.budgetBytes > 0 ? request.budgetBytes : null;
+    const units = [];
+    const omitted = [];
+    let usedBytes = 0;
+    let omittedBytes = 0;
+    for (const unit of ordered) {
+        if (limit !== null && (omitted.length > 0 || usedBytes + unit.bytes > limit)) {
+            omitted.push({
+                id: unit.id,
+                file: unit.file,
+                heading: unit.heading,
+                bytes: unit.bytes,
+                reason: "budget",
+            });
+            omittedBytes += unit.bytes;
+            continue;
+        }
+        units.push(unit);
+        usedBytes += unit.bytes;
+    }
+    const included = new Set(selections.map((selection) => selection.file));
+    const files = [...new Set(units.map((unit) => unit.file))];
+    const broken = graph.broken
+        .filter((edge) => included.has(edge.source))
+        .map((edge) => ({
+        source: shown(edge.source),
+        target: edge.target,
+        resolved: shown(edge.resolved),
+        line: edge.line,
+    }));
+    return {
+        seeds: request.seeds.map((seed) => shown(seed.file)),
+        depth: request.depth,
+        backlinks: request.backlinks,
+        files,
+        units,
+        omitted,
+        broken,
+        budget: {
+            limitBytes: limit,
+            usedBytes,
+            omittedBytes,
+            tokenEstimate: Math.ceil(usedBytes / 4),
+            truncated: omitted.length > 0,
+        },
+        totals: { files: files.length, units: units.length, bytes: usedBytes },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/contract/describe.d.ts

@@ -0,0 +1,84 @@
+import type { Command } from "commander";
+import { NOTIFIER_CONTRACT } from "../update-notifier.js";
+import type { ContractStream, ExitCodeMeaning } from "./types.js";
+export interface DescribedArgument {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description: string;
+    default?: unknown;
+}
+export interface DescribedOption {
+    flags: string;
+    long: string | null;
+    short: string | null;
+    description: string;
+    valueName: string | null;
+    valueRequired: boolean;
+    valueOptional: boolean;
+    mandatory: boolean;
+    variadic: boolean;
+    negated: boolean;
+    repeatable: boolean;
+    default?: unknown;
+}
+export interface DescribedCommand {
+    id: string;
+    path: string[];
+    description: string;
+    usage: string;
+    arguments: DescribedArgument[];
+    options: DescribedOption[];
+    subcommands: string[];
+    formats: string[] | null;
+    defaultFormat: string | null;
+    formatConfigurable: boolean;
+    outputSchema: string | null;
+    jsonlSchema?: string | null;
+    sarifSchema?: string | null;
+    exitCodes: ExitCodeMeaning[];
+    exitCodePassthrough?: {
+        min: number;
+        max: number;
+        description: string;
+    };
+    stream: {
+        success: ContractStream;
+        findings?: ContractStream;
+    } | null;
+    writes: boolean | null;
+    stability: "stable" | "experimental" | "undeclared";
+    notes?: string;
+}
+export interface DescribeResult {
+    schemaVersion: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+    formatShorthands: Record<string, string>;
+    machineStreams: typeof NOTIFIER_CONTRACT;
+    schemas: Array<{
+        id: string;
+        uri: string;
+        title: string;
+        commands: string[];
+    }>;
+    commands: DescribedCommand[];
+}
+/**
+ * Walks the commander tree for the mechanical facts, which cannot drift, and
+ * merges the registry for the semantic ones commander cannot know: exit code
+ * meanings, stream assignment, schema ids, and whether a command writes.
+ *
+ * A command with no registry entry is reported as `undeclared` rather than
+ * throwing — a user should not get a crash because a contract row is missing.
+ * `tests/e2e/contract.test.ts` fails on it instead, in both directions.
+ */
+export declare function walkCommands(program: Command): DescribedCommand[];
+export declare function buildDescription(program: Command, tool: {
+    name: string;
+    version: string;
+}): DescribeResult;
+/** Narrows a description to one command path and its descendants. */
+export declare function selectCommands(result: DescribeResult, path: string[]): DescribeResult;

package/dist/contract/describe.js

@@ -0,0 +1,104 @@
+import { collect } from "../option-utils.js";
+import { NOTIFIER_CONTRACT } from "../update-notifier.js";
+import { COMMAND_CONTRACTS } from "./registry.js";
+import { SCHEMAS } from "./schemas/index.js";
+import { CONTRACT_VERSION } from "./version.js";
+const VALUE_NAME = /[<[]([^>\]]+)[>\]]/;
+function describeOption(option) {
+    return {
+        flags: option.flags,
+        long: option.long ?? null,
+        short: option.short ?? null,
+        description: option.description,
+        valueName: VALUE_NAME.exec(option.flags)?.[1] ?? null,
+        valueRequired: Boolean(option.required),
+        valueOptional: Boolean(option.optional),
+        mandatory: Boolean(option.mandatory),
+        variadic: Boolean(option.variadic),
+        negated: Boolean(option.negate),
+        // Repeatable options accumulate through `collect`; comparing by identity
+        // avoids inferring repeatability from description text.
+        repeatable: option.parseArg === collect,
+        ...(option.defaultValue === undefined ? {} : { default: option.defaultValue }),
+    };
+}
+function describeArgument(argument) {
+    return {
+        name: argument.name(),
+        required: argument.required,
+        variadic: argument.variadic,
+        description: argument.description,
+        ...(argument.defaultValue === undefined ? {} : { default: argument.defaultValue }),
+    };
+}
+/**
+ * Walks the commander tree for the mechanical facts, which cannot drift, and
+ * merges the registry for the semantic ones commander cannot know: exit code
+ * meanings, stream assignment, schema ids, and whether a command writes.
+ *
+ * A command with no registry entry is reported as `undeclared` rather than
+ * throwing — a user should not get a crash because a contract row is missing.
+ * `tests/e2e/contract.test.ts` fails on it instead, in both directions.
+ */
+export function walkCommands(program) {
+    const described = [];
+    const visit = (command, path) => {
+        // visibleCommands is the public accessor that already excludes hidden
+        // commands such as the internal cache refresh.
+        const children = command
+            .createHelp()
+            .visibleCommands(command)
+            .filter((child) => child.name() !== "help");
+        if (path.length) {
+            const id = path.join(" ");
+            const contract = COMMAND_CONTRACTS[id];
+            described.push({
+                id,
+                path,
+                description: command.description(),
+                usage: `${program.name()} ${path.join(" ")} ${command.usage()}`.trim(),
+                arguments: command.registeredArguments.map(describeArgument),
+                options: command.options.filter((option) => !option.hidden).map(describeOption),
+                subcommands: children.map((child) => [...path, child.name()].join(" ")),
+                formats: contract?.formats ? [...contract.formats] : null,
+                defaultFormat: contract?.defaultFormat ?? null,
+                formatConfigurable: contract?.formatConfigurable ?? false,
+                outputSchema: contract?.outputSchema ?? null,
+                jsonlSchema: contract?.jsonlSchema ?? null,
+                sarifSchema: contract?.sarifSchema ?? null,
+                exitCodes: contract?.exitCodes ?? [],
+                // Emitted only where it applies, so no existing command's bytes change.
+                ...(contract?.exitCodePassthrough
+                    ? { exitCodePassthrough: contract.exitCodePassthrough }
+                    : {}),
+                stream: contract?.stream ?? null,
+                writes: contract?.writes ?? null,
+                stability: contract?.stability ?? "undeclared",
+                ...(contract?.notes ? { notes: contract.notes } : {}),
+            });
+        }
+        for (const child of children)
+            visit(child, [...path, child.name()]);
+    };
+    visit(program, []);
+    return described;
+}
+export function buildDescription(program, tool) {
+    return {
+        schemaVersion: CONTRACT_VERSION,
+        tool,
+        formatShorthands: { "-fh": "--format=human", "-fj": "--format=json" },
+        machineStreams: NOTIFIER_CONTRACT,
+        schemas: SCHEMAS.map(({ id, uri, title, commands }) => ({ id, uri, title, commands })),
+        commands: walkCommands(program),
+    };
+}
+/** Narrows a description to one command path and its descendants. */
+export function selectCommands(result, path) {
+    const id = path.join(" ");
+    const commands = result.commands.filter((command) => command.id === id || command.id.startsWith(`${id} `));
+    if (!commands.length)
+        throw new Error(`Unknown command: ${id}`);
+    return { ...result, commands };
+}
+//# sourceMappingURL=describe.js.map

package/dist/contract/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/contract/describe.ts"],"names":[],"mappings":"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"}

package/dist/contract/registry.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContract } from "./types.js";
+export declare const COMMAND_CONTRACTS: Readonly<Record<string, CommandContract>>;