@cairn-tool/cairn 2.0.0

package/dist/query/plan.js

@@ -0,0 +1,183 @@
+import path from "node:path";
+import { splitLocalTarget } from "../link-target.js";
+import { ENTITY_KINDS, SPECS, fieldNames, } from "./entities.js";
+/** Anything the user got wrong. Always exit 1, never a silently empty result. */
+export class QueryUsageError extends Error {
+}
+const FRONTMATTER = "frontmatter.";
+// Longest first so ">=" is never read as ">" followed by "=".
+const OPERATORS = ["!=", ">=", "<=", "=", "~", ">", "<"];
+const NAMED = /^!?([a-z][a-z0-9-]*):/;
+const NUMERIC = [">", ">=", "<", "<="];
+export function isEntityKind(value) {
+    return ENTITY_KINDS.includes(value);
+}
+/**
+ * Resolves a field token against an entity.
+ *
+ * `frontmatter.<key>` is a virtual field on every entity, read from the
+ * containing document. That is what lets `md query tasks --group-by
+ * frontmatter.owner` work without a join.
+ */
+export function resolveField(entity, token) {
+    if (token.startsWith(FRONTMATTER)) {
+        const keyPath = token.slice(FRONTMATTER.length);
+        if (!keyPath)
+            throw new QueryUsageError("frontmatter fields need a key: frontmatter.<key>");
+        return { token, keyPath };
+    }
+    const spec = SPECS[entity].fields.find((field) => field.name === token);
+    if (!spec) {
+        // A per-occurrence field on `documents` is a hidden join; name the entity
+        // that actually has it rather than returning nothing.
+        const hint = entity === "documents" && ["line", "text", "target", "slug"].includes(token)
+            ? ` Per-occurrence fields need an occurrence entity — try: md query links --select file,${token}`
+            : "";
+        throw new QueryUsageError(`Unknown field for ${entity}: ${token}. Available: ${fieldNames(entity).join(", ")}, frontmatter.<key>.${hint}`);
+    }
+    return { token, spec };
+}
+function coerce(spec, value, source) {
+    if (spec.type === "boolean") {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+        throw new QueryUsageError(`${source}: ${spec.name} is a boolean field; use true or false`);
+    }
+    if (spec.type === "number") {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) {
+            throw new QueryUsageError(`${source}: ${spec.name} is a numeric field; ${value} is not`);
+        }
+        return parsed;
+    }
+    return value;
+}
+function firstOperator(term) {
+    let best;
+    for (const operator of OPERATORS) {
+        const index = term.indexOf(operator);
+        if (index <= 0)
+            continue;
+        if (!best || index < best.index)
+            best = { operator, index };
+    }
+    return best;
+}
+/**
+ * Parses one `--where` term.
+ *
+ * A term is `NAME:ARG` only when the text before the first colon is a valid
+ * predicate name *and* that colon precedes any operator. So `links-to:x.md` is
+ * a named predicate while `target=https://example.com` is a comparison.
+ */
+export function parseWhere(entity, term) {
+    if (!term.trim())
+        throw new QueryUsageError("--where needs a predicate");
+    const named = NAMED.exec(term);
+    const operator = firstOperator(term);
+    const colon = term.indexOf(":");
+    if (named && (!operator || colon < operator.index)) {
+        const negated = term.startsWith("!");
+        const name = named[1];
+        const argument = term.slice(colon + 1);
+        if (!argument)
+            throw new QueryUsageError(`${term}: ${name} needs an argument`);
+        if (name === "has") {
+            const field = resolveField(entity, argument);
+            return { type: "named", name, argument, negated, ...field, source: term };
+        }
+        if (name === "links-to") {
+            if (!SPECS[entity].functions.includes("links-to")) {
+                throw new QueryUsageError(`${term}: links-to is not available on ${entity}; use documents or links`);
+            }
+            const parsed = splitLocalTarget(argument);
+            return {
+                type: "named",
+                name,
+                argument,
+                negated,
+                resolved: {
+                    path: path.resolve(parsed.path),
+                    ...(parsed.fragment === undefined ? {} : { fragment: parsed.fragment }),
+                },
+                source: term,
+            };
+        }
+        throw new QueryUsageError(`${term}: unknown predicate ${name}. Available: has, links-to`);
+    }
+    if (!operator) {
+        throw new QueryUsageError(`${term}: not a predicate. Use <field><op><value> with one of ${OPERATORS.join(" ")}, or has:<field> / links-to:<path>`);
+    }
+    const field = resolveField(entity, term.slice(0, operator.index));
+    const value = term.slice(operator.index + operator.operator.length);
+    // A statically typed field validates its operator and operand now, so a typo
+    // fails loudly. A frontmatter field is untyped YAML and can only be coerced
+    // at evaluation.
+    if (field.spec) {
+        if (NUMERIC.includes(operator.operator) && field.spec.type !== "number") {
+            throw new QueryUsageError(`${term}: ${operator.operator} is only valid on numeric fields; ${field.spec.name} is a ${field.spec.type}`);
+        }
+        return {
+            type: "comparison",
+            field: field.token,
+            operator: operator.operator,
+            value,
+            operand: coerce(field.spec, value, term),
+            spec: field.spec,
+            source: term,
+        };
+    }
+    return {
+        type: "comparison",
+        field: field.token,
+        operator: operator.operator,
+        value,
+        keyPath: field.keyPath,
+        source: term,
+    };
+}
+/** Splits and validates a comma-separated, repeatable field list. */
+export function parseFieldList(entity, values) {
+    const seen = [];
+    for (const value of values) {
+        for (const token of value.split(",")) {
+            const trimmed = token.trim();
+            if (!trimmed)
+                continue;
+            resolveField(entity, trimmed);
+            if (!seen.includes(trimmed))
+                seen.push(trimmed);
+        }
+    }
+    return seen;
+}
+export function buildPlan(input) {
+    if (!isEntityKind(input.kind)) {
+        // Shortcut kinds keep their historical payload rather than growing a second
+        // shape, so name the entity form that answers the same question.
+        const replacement = {
+            "missing-h1": " Try: md query documents --where '!has:h1'",
+            "links-to": " Try: md query links --where links-to:<path>",
+            "frontmatter-keys": " Try: md query frontmatter --select key --group-by key",
+        };
+        throw new QueryUsageError(`${input.kind} does not support composable options. Entities: ${ENTITY_KINDS.join(", ")}.${replacement[input.kind] ?? ""}`);
+    }
+    const entity = input.kind;
+    const predicates = input.where.map((term) => parseWhere(entity, term));
+    const select = parseFieldList(entity, input.select);
+    const groupBy = input.groupBy?.trim();
+    if (groupBy)
+        resolveField(entity, groupBy);
+    return {
+        entity,
+        predicates,
+        select: select.length
+            ? select
+            : SPECS[entity].fields.filter((field) => field.default).map((field) => field.name),
+        selectExplicit: select.length > 0,
+        ...(groupBy ? { groupBy } : {}),
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/query/plan.js.map

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

package/dist/query/render.d.ts

@@ -0,0 +1,3 @@
+import type { QueryPlan } from "./plan.js";
+import type { QueryResult } from "./execute.js";
+export declare function renderQueryText(result: QueryResult, plan: QueryPlan, directory: string, human: boolean): string;

package/dist/query/render.js

@@ -0,0 +1,39 @@
+const MAX_WIDTH = 60;
+function cell(value) {
+    if (value === undefined || value === null)
+        return "(none)";
+    const text = Array.isArray(value) ? value.join(", ") : String(value);
+    // Task text and code-block bodies can span lines; a table row must not.
+    const flat = text.replace(/[\t\r\n]+/g, " ");
+    return flat.length > MAX_WIDTH ? `${flat.slice(0, MAX_WIDTH - 1)}…` : flat;
+}
+function table(fields, rows, indent) {
+    const widths = fields.map((field) => Math.max(field.length, ...rows.map((row) => cell(row[field]).length), 0));
+    const line = (values) => indent +
+        values
+            .map((value, index) => value.padEnd(widths[index]))
+            .join("  ")
+            .trimEnd();
+    return [line(fields), ...rows.map((row) => line(fields.map((field) => cell(row[field]))))];
+}
+export function renderQueryText(result, plan, directory, human) {
+    const bold = (value) => (human ? `\x1b[1m${value}\x1b[0m` : value);
+    const summary = plan.predicates.length
+        ? `${result.matched} ${plan.entity} matching: ${plan.predicates.map((p) => p.source).join(", ")}`
+        : `${result.matched} ${plan.entity} in ${directory}`;
+    const lines = [bold(summary)];
+    // An empty result prints the plan that ran, so a predicate that silently
+    // matched nothing is still visible.
+    if (!result.matched)
+        return lines.join("\n");
+    if (result.groups) {
+        for (const group of result.groups) {
+            lines.push("", bold(`${plan.groupBy}=${group.key ?? "(none)"} (${group.count})`));
+            lines.push(...table(result.fields, group.rows, "  "));
+        }
+        return lines.join("\n");
+    }
+    lines.push(...table(result.fields, result.rows, ""));
+    return lines.join("\n");
+}
+//# sourceMappingURL=render.js.map

package/dist/query/render.js.map

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

package/dist/refs.d.ts

@@ -0,0 +1,19 @@
+import { type Root } from "./markdown-ast.js";
+export interface Reference {
+    line: number;
+    linkText: string;
+    target: string;
+    isImage: boolean;
+    isExternal: boolean;
+    isAnchorOnly: boolean;
+    referenceType: "inline" | "full" | "collapsed" | "shortcut";
+    definitionIdentifier?: string;
+    destinationLine: number;
+    destinationStart?: number;
+    destinationEnd?: number;
+}
+/**
+ * Extract all markdown references (links and images) from content,
+ * skipping code blocks.
+ */
+export declare function extractReferences(input: string | Root): Reference[];

package/dist/refs.js

@@ -0,0 +1,10 @@
+import { parseMarkdown, extractLinks } from "./markdown-ast.js";
+/**
+ * Extract all markdown references (links and images) from content,
+ * skipping code blocks.
+ */
+export function extractReferences(input) {
+    const tree = typeof input === "string" ? parseMarkdown(input) : input;
+    return extractLinks(tree, typeof input === "string" ? input : undefined);
+}
+//# sourceMappingURL=refs.js.map

package/dist/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAa,MAAM,mBAAmB,CAAC;AAgB3E;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAoB;IACpD,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACtE,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC3E,CAAC"}

package/dist/result.d.ts

@@ -0,0 +1,49 @@
+export interface EmitOptions {
+    /** Canonical command id, e.g. "md graph". */
+    command: string;
+    ok: boolean;
+    exitCode: 0 | 1 | 2;
+    /** When false or absent the payload is written exactly as it always was. */
+    envelope?: boolean;
+    /** Schema id for the wrapped payload; resolved to its canonical uri. */
+    schema?: string | null;
+    /** Optional command-specific counters. */
+    summary?: Record<string, unknown>;
+}
+export interface ResultEnvelope {
+    schemaVersion: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+    command: string;
+    ok: boolean;
+    exitCode: 0 | 1 | 2;
+    schema: string | null;
+    data: unknown;
+    summary?: Record<string, unknown>;
+}
+export declare function wrap(payload: unknown, opts: EmitOptions): ResultEnvelope;
+/**
+ * Renders a JSON payload, optionally wrapped in the versioned envelope.
+ *
+ * Without `envelope` the output is byte-identical to a direct
+ * `JSON.stringify(payload, null, 2)`, which is what keeps `--envelope` an
+ * additive change rather than a breaking one.
+ */
+export declare function renderJson(payload: unknown, opts: EmitOptions): string;
+export declare function emitJson(payload: unknown, opts: EmitOptions, stream?: NodeJS.WritableStream): void;
+export interface Outcome {
+    ok?: boolean;
+    exitCode?: 0 | 1 | 2;
+    summary?: Record<string, unknown>;
+}
+/**
+ * Renders a command's JSON payload, looking its schema id up in the registry.
+ *
+ * This is the single place every `--format json` write site goes through, so
+ * `--envelope` reaches all of them and the unenveloped bytes stay unchanged.
+ */
+export declare function jsonPayload(command: string, payload: unknown, opts: {
+    envelope?: boolean;
+}, outcome?: Outcome): string;

package/dist/result.js

@@ -0,0 +1,47 @@
+import { COMMAND_CONTRACTS } from "./contract/registry.js";
+import { CONTRACT_VERSION } from "./contract/version.js";
+import { schemaUriFor } from "./contract/schemas/index.js";
+import { packageName, packageVersion } from "./version.js";
+export function wrap(payload, opts) {
+    return {
+        schemaVersion: CONTRACT_VERSION,
+        tool: { name: packageName, version: packageVersion },
+        command: opts.command,
+        ok: opts.ok,
+        exitCode: opts.exitCode,
+        schema: schemaUriFor(opts.schema),
+        data: payload,
+        ...(opts.summary ? { summary: opts.summary } : {}),
+    };
+}
+/**
+ * Renders a JSON payload, optionally wrapped in the versioned envelope.
+ *
+ * Without `envelope` the output is byte-identical to a direct
+ * `JSON.stringify(payload, null, 2)`, which is what keeps `--envelope` an
+ * additive change rather than a breaking one.
+ */
+export function renderJson(payload, opts) {
+    return JSON.stringify(opts.envelope ? wrap(payload, opts) : payload, null, 2) + "\n";
+}
+export function emitJson(payload, opts, stream = process.stdout) {
+    stream.write(renderJson(payload, opts));
+}
+/**
+ * Renders a command's JSON payload, looking its schema id up in the registry.
+ *
+ * This is the single place every `--format json` write site goes through, so
+ * `--envelope` reaches all of them and the unenveloped bytes stay unchanged.
+ */
+export function jsonPayload(command, payload, opts, outcome = {}) {
+    const exitCode = outcome.exitCode ?? 0;
+    return renderJson(payload, {
+        command,
+        ok: outcome.ok ?? exitCode === 0,
+        exitCode,
+        envelope: Boolean(opts.envelope),
+        schema: COMMAND_CONTRACTS[command]?.outputSchema,
+        summary: outcome.summary,
+    });
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA0B3D,MAAM,UAAU,IAAI,CAAC,OAAgB,EAAE,IAAiB;IACtD,OAAO;QACL,aAAa,EAAE,gBAAgB;QAC/B,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE;QACpD,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;QACjC,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAgB,EAAE,IAAiB;IAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,OAAgB,EAChB,IAAiB,EACjB,SAAgC,OAAO,CAAC,MAAM;IAE9C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1C,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,OAAgB,EAChB,IAA4B,EAC5B,UAAmB,EAAE;IAErB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACvC,OAAO,UAAU,CAAC,OAAO,EAAE;QACzB,OAAO;QACP,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,QAAQ,KAAK,CAAC;QAChC,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAChC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,YAAY;QAChD,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,35 @@
+import type { ResolvedConfig } from "./config.js";
+import { type PathStyle } from "./config.js";
+import { Workspace, type WorkspaceOptions } from "./workspace.js";
+import type { OutputFormat } from "./types.js";
+export interface Runtime {
+    config: ResolvedConfig;
+    workspace: Workspace;
+}
+/**
+ * Installs the process-wide runtime.
+ *
+ * `options` exists for the long-lived server: library helpers such as
+ * `documentsReferencing` and `lintFile` reach for `runtime().workspace`, so a
+ * bounded workspace has to be *the* workspace rather than a second instance
+ * alongside it, or those helpers would quietly populate the unbounded one.
+ */
+export declare function initializeRuntime(config: ResolvedConfig, options?: WorkspaceOptions): Runtime;
+export declare function resetRuntime(): void;
+export declare function runtime(): Runtime;
+export type ResolvedOptions<T extends Record<string, unknown>> = T & {
+    format: OutputFormat;
+    paths: PathStyle;
+};
+/**
+ * Which of `cli`'s keys the user actually typed.
+ *
+ * Commander hands back defaults and typed values indistinguishably, so this
+ * re-reads argv. Config resolution needs it to know what to override, and a
+ * command that rejects conflicting options needs it to avoid misfiring on a
+ * value that came from `.cairn.yml` rather than the command line.
+ */
+export declare function explicitOptionKeys(cli: Record<string, unknown>): Set<string>;
+export declare function commandOptions<T extends Record<string, unknown>>(command: string, builtins: T, cli: Record<string, unknown>): ResolvedOptions<T>;
+export declare function displayPath(filePath: string, style?: PathStyle): string;
+export declare function outputPath(filePath: string, options: object): string;

package/dist/runtime.js

@@ -0,0 +1,77 @@
+import { loadConfig, resolveCommandOptions } from "./config.js";
+import { Workspace } from "./workspace.js";
+import { ALL_FORMATS, supportsDiagnosticFormats } from "./formats.js";
+let activeRuntime;
+/**
+ * Installs the process-wide runtime.
+ *
+ * `options` exists for the long-lived server: library helpers such as
+ * `documentsReferencing` and `lintFile` reach for `runtime().workspace`, so a
+ * bounded workspace has to be *the* workspace rather than a second instance
+ * alongside it, or those helpers would quietly populate the unbounded one.
+ */
+export function initializeRuntime(config, options) {
+    activeRuntime = { config, workspace: new Workspace(config, options) };
+    return activeRuntime;
+}
+export function resetRuntime() {
+    activeRuntime = undefined;
+}
+export function runtime() {
+    return activeRuntime ?? initializeRuntime(loadConfig({ disabled: true }));
+}
+const OPTION_ALIASES = {
+    format: ["-fh", "-fj"],
+    style: ["-s"],
+    external: ["-e"],
+    anchors: ["-a"],
+    images: ["-i"],
+};
+/**
+ * Which of `cli`'s keys the user actually typed.
+ *
+ * Commander hands back defaults and typed values indistinguishably, so this
+ * re-reads argv. Config resolution needs it to know what to override, and a
+ * command that rejects conflicting options needs it to avoid misfiring on a
+ * value that came from `.cairn.yml` rather than the command line.
+ */
+export function explicitOptionKeys(cli) {
+    const argv = process.argv.slice(2);
+    return new Set(Object.keys(cli).filter((key) => {
+        const kebab = key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+        return argv.some((arg) => arg === `--${kebab}` ||
+            arg === `--no-${kebab}` ||
+            arg.startsWith(`--${kebab}=`) ||
+            (OPTION_ALIASES[key] ?? []).includes(arg));
+    }));
+}
+export function commandOptions(command, builtins, cli) {
+    const typed = explicitOptionKeys(cli);
+    const explicit = Object.fromEntries(Object.entries(cli).filter(([key]) => typed.has(key)));
+    const resolved = resolveCommandOptions(runtime().config, command, builtins, explicit);
+    if (!ALL_FORMATS.includes(resolved.format)) {
+        throw new Error(`Invalid output format: ${String(resolved.format)}`);
+    }
+    if ((resolved.format === "jsonl" || resolved.format === "sarif") &&
+        !supportsDiagnosticFormats(command)) {
+        throw new Error(`${resolved.format} output is not supported by md ${command}`);
+    }
+    if (resolved.paths !== "absolute" && resolved.paths !== "relative") {
+        throw new Error(`Invalid path display style: ${String(resolved.paths)}`);
+    }
+    // The envelope is a JSON wrapper; there is nothing to wrap in the other
+    // formats, so accepting it there would silently do nothing.
+    if (resolved.envelope && resolved.format !== "json") {
+        throw new Error("--envelope requires --format json");
+    }
+    return resolved;
+}
+export function displayPath(filePath, style) {
+    return runtime().workspace.displayPath(filePath, style);
+}
+export function outputPath(filePath, options) {
+    const value = options.paths;
+    const style = value === "relative" || value === "absolute" ? value : undefined;
+    return displayPath(filePath, style);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/sarif.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The SARIF 2.1.0 envelope, shared by the `md` diagnostic commands and by
+ * `agent audit`.
+ *
+ * `JSON.stringify` follows insertion order, so both the document and each
+ * caller's result objects must be built in a fixed order — this is what keeps
+ * the `md` output byte-identical now that two producers share the envelope.
+ */
+export declare const SARIF_VERSION = "2.1.0";
+export declare const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+export interface SarifRule {
+    id: string;
+    name: string;
+}
+export type SarifLevel = "error" | "warning" | "note";
+export interface SarifResult {
+    ruleId: string;
+    level: SarifLevel;
+    message: {
+        text: string;
+    };
+    locations: Array<{
+        physicalLocation: {
+            artifactLocation: {
+                uri: string;
+            };
+            /** Omitted by producers whose findings have no line. */
+            region?: {
+                startLine: number;
+            };
+        };
+    }>;
+    properties?: Record<string, unknown>;
+}
+/** Renders one SARIF run. Returns without a trailing newline. */
+export declare function sarifDocument(rules: readonly SarifRule[], results: readonly SarifResult[]): string;

package/dist/sarif.js

@@ -0,0 +1,30 @@
+/**
+ * The SARIF 2.1.0 envelope, shared by the `md` diagnostic commands and by
+ * `agent audit`.
+ *
+ * `JSON.stringify` follows insertion order, so both the document and each
+ * caller's result objects must be built in a fixed order — this is what keeps
+ * the `md` output byte-identical now that two producers share the envelope.
+ */
+export const SARIF_VERSION = "2.1.0";
+export const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+/** Renders one SARIF run. Returns without a trailing newline. */
+export function sarifDocument(rules, results) {
+    return JSON.stringify({
+        version: SARIF_VERSION,
+        $schema: SARIF_SCHEMA,
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "cairn",
+                        informationUri: "https://github.com/cairn-tool/cairn",
+                        rules,
+                    },
+                },
+                results,
+            },
+        ],
+    }, null, 2);
+}
+//# sourceMappingURL=sarif.js.map

package/dist/sarif.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.js","sourceRoot":"","sources":["../src/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AACrC,MAAM,CAAC,MAAM,YAAY,GAAG,+CAA+C,CAAC;AAuB5E,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAC3B,KAA2B,EAC3B,OAA+B;IAE/B,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,OAAO,EAAE,aAAa;QACtB,OAAO,EAAE,YAAY;QACrB,IAAI,EAAE;YACJ;gBACE,IAAI,EAAE;oBACJ,MAAM,EAAE;wBACN,IAAI,EAAE,OAAO;wBACb,cAAc,EAAE,qCAAqC;wBACrD,KAAK;qBACN;iBACF;gBACD,OAAO;aACR;SACF;KACF,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/scripts/execute.d.ts

@@ -0,0 +1,65 @@
+import type { ScriptDefinition, ScriptRegistry } from "./registry.js";
+/** Deep enough for real composition, shallow enough to stop a runaway. */
+export declare const MAX_SCRIPT_DEPTH = 8;
+export interface ScriptExecution {
+    /** `pass-through` for llm and human, `capture` for json. */
+    mode: "pass-through" | "capture";
+    definition: ScriptDefinition;
+    registry: ScriptRegistry;
+    workingDirectory: string;
+    invokedFrom: string;
+    /** Verbatim tokens after the first `--`. */
+    args: readonly string[];
+}
+export interface ScriptOutcome {
+    /** The child's status, or null when a signal killed it or it never started. */
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    /** Capture mode only. */
+    stdout?: string;
+    stderr?: string;
+    truncated?: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+    durationMs: number;
+    /** Set when the child could not be started at all. */
+    startupError?: string;
+}
+/**
+ * The child's environment.
+ *
+ * Every variable is exported under both the current and the pre-rename spelling.
+ * A script is user code this tool does not get to edit, so one already reading
+ * `CLAUDE_CLI_SCRIPT_ROOT` has to keep working; duplicating six variables is the
+ * cheap half of that bargain.
+ */
+export declare function scriptEnvironment(execution: ScriptExecution): NodeJS.ProcessEnv;
+/**
+ * Refuses a script that is already running.
+ *
+ * This is a footgun guard, not a security control — a script can clear either
+ * variable. It exists so a self-referential definition fails immediately instead
+ * of forking until something else gives out.
+ */
+export declare function checkRecursionDepth(execution: ScriptExecution): void;
+interface SpawnPlan {
+    command: string;
+    argv: string[];
+}
+/**
+ * The program and argv for one script.
+ *
+ * Exported for the unit tests, which assert the exact argv rather than
+ * inspecting behavior through a child process.
+ */
+export declare function spawnPlan(execution: ScriptExecution): SpawnPlan;
+export declare function executeScript(execution: ScriptExecution): Promise<ScriptOutcome>;
+/**
+ * The status this process exits with when it passes the child's through.
+ *
+ * A bare `code & 0xff` would map 256 to 0, reporting success for a child that
+ * failed, so an out-of-range code that truncates to zero becomes 1 instead.
+ */
+export declare function exitStatusFor(outcome: ScriptOutcome): number;
+export {};