@cairn-tool/cairn 2.1.0 → 3.1.0

package/dist/jira/adf/read.js

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CODES, diagnostic } from "./diagnostics.js";
+/**
+ * Matches the snippet reader's cap. ADF documents are prose, not archives, and
+ * an issue description past two megabytes is a sign of something other than an
+ * issue description.
+ */
+export const MAX_INPUT_BYTES = 2 * 1024 * 1024;
+/**
+ * Maximum ADF nesting depth.
+ *
+ * ADF is a recursive tree and both converters walk it recursively, so this is a
+ * correctness guard rather than hygiene: without it a document nested a few
+ * hundred thousand deep exits with a stack overflow and no diagnostic, which for
+ * input arriving off a network is the wrong failure.
+ */
+export const MAX_DEPTH = 200;
+function contained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/**
+ * Reads a conversion input, from a path or from stdin when `source` is `-`.
+ *
+ * The guards mirror `readSnippetSource` in src/snippets.ts, which bounds reads
+ * of files named by analyzed content. Here the content itself arrives from a
+ * REST API, so the same treatment applies: resolve through symlinks, refuse
+ * anything that is not a regular file, cap the size, and reject NUL.
+ */
+/**
+ * Reads stdin to completion.
+ *
+ * Not `fs.readFileSync(0)`: when stdin is a pipe whose writer has not produced
+ * anything yet, that throws `EAGAIN` rather than waiting — and
+ * `curl | jq | cairn jira adf to-markdown -` is the primary documented workflow, so
+ * the failure would land squarely on the common case. Streaming the descriptor
+ * waits properly.
+ */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readInput(source, containmentRoot) {
+    if (source === "-") {
+        const content = await readStdin();
+        return content.includes("\0")
+            ? {
+                ok: false,
+                diagnostic: diagnostic({
+                    code: CODES.notJson,
+                    severity: "error",
+                    quality: "unsupported",
+                    message: "Input contains a NUL byte, so it is not text",
+                }),
+            }
+            : { ok: true, content };
+    }
+    const resolved = path.resolve(source);
+    let real;
+    try {
+        real = fs.realpathSync(resolved);
+    }
+    catch {
+        return {
+            ok: false,
+            diagnostic: diagnostic({
+                code: CODES.failure,
+                severity: "error",
+                quality: "unsupported",
+                message: `Input file not found: ${source}`,
+            }),
+        };
+    }
+    if (containmentRoot !== undefined) {
+        let realRoot = containmentRoot;
+        try {
+            realRoot = fs.realpathSync(containmentRoot);
+        }
+        catch {
+            // An unresolvable root can only make the check stricter.
+        }
+        if (!contained(realRoot, real))
+            return {
+                ok: false,
+                diagnostic: diagnostic({
+                    code: CODES.failure,
+                    severity: "error",
+                    quality: "unsupported",
+                    message: `Input file is outside the permitted root: ${source}`,
+                }),
+            };
+    }
+    // Checked on the open descriptor, not on the path, so the file cannot be
+    // swapped between the check and the read. O_NONBLOCK is what makes that safe
+    // to do here: opening a FIFO without it blocks until a writer appears, which
+    // is the very hazard the regular-file check exists to prevent.
+    let descriptor;
+    try {
+        descriptor = fs.openSync(real, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return {
+            ok: false,
+            diagnostic: diagnostic({
+                code: CODES.failure,
+                severity: "error",
+                quality: "unsupported",
+                message: `Input file could not be opened: ${source}`,
+            }),
+        };
+    }
+    try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile())
+            return {
+                ok: false,
+                diagnostic: diagnostic({
+                    code: CODES.failure,
+                    severity: "error",
+                    quality: "unsupported",
+                    message: `Input path is not a regular file: ${source}`,
+                }),
+            };
+        if (stat.size > MAX_INPUT_BYTES)
+            return {
+                ok: false,
+                diagnostic: diagnostic({
+                    code: CODES.tooLarge,
+                    severity: "error",
+                    quality: "unsupported",
+                    message: `Input is larger than ${MAX_INPUT_BYTES} bytes`,
+                    remediation: "Split the document, or convert the field you actually need.",
+                }),
+            };
+        const content = fs.readFileSync(descriptor, "utf8");
+        if (content.includes("\0"))
+            return {
+                ok: false,
+                diagnostic: diagnostic({
+                    code: CODES.notJson,
+                    severity: "error",
+                    quality: "unsupported",
+                    message: `Input contains a NUL byte, so it is not text: ${source}`,
+                }),
+            };
+        return { ok: true, content };
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+/** Keys a Jira REST response uses for a rich-text field, in the order to suggest. */
+const WRAPPER_FIELDS = ["fields.description", "fields.summary", "body", "comment.body"];
+function depthOf(node, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return depth;
+    if (Array.isArray(node))
+        return node.reduce((max, item) => Math.max(max, depthOf(item, depth + 1)), depth);
+    if (!node || typeof node !== "object")
+        return depth;
+    let max = depth;
+    for (const value of Object.values(node))
+        max = Math.max(max, depthOf(value, depth + 1));
+    return max;
+}
+/**
+ * Finds a plausible ADF document nested inside an arbitrary object.
+ *
+ * Used only to write a better error. The tool converts a bare ADF document and
+ * knows nothing about the Jira response wrapper, so this never *extracts* the
+ * document — it only lets AD002 say which field to pull out, which is the
+ * likeliest first mistake anyone makes and the one place a good message replaces
+ * a whole option.
+ */
+function locateNested(value, trail = [], found = []) {
+    if (found.length > 3 || !value || typeof value !== "object")
+        return found;
+    if (Array.isArray(value))
+        return found;
+    const record = value;
+    if (record.type === "doc" && Array.isArray(record.content))
+        found.push(trail.join("."));
+    for (const [key, child] of Object.entries(record))
+        locateNested(child, [...trail, key], found);
+    return found;
+}
+/** Parses and shape-checks an ADF document, without validating its content model. */
+export function parseAdfDocument(content, source) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            diagnostic: diagnostic({
+                code: CODES.notJson,
+                severity: "error",
+                quality: "unsupported",
+                message: `Input is not valid JSON: ${error.message}`,
+            }),
+        };
+    }
+    const isDocument = Boolean(value) &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.type === "doc";
+    if (!isDocument) {
+        const nested = locateNested(value).filter(Boolean);
+        const suggestion = nested.length
+            ? `Extract it first, for example: jq .${nested[0]} ${source === "-" ? "" : source}`.trim()
+            : `This command converts a bare ADF document — an object with "type": "doc". A Jira REST response nests one under a field such as ${WRAPPER_FIELDS.join(" or ")}; extract it with jq first.`;
+        return {
+            ok: false,
+            diagnostic: diagnostic({
+                code: CODES.notADocument,
+                severity: "error",
+                quality: "unsupported",
+                message: nested.length
+                    ? `Input is not an ADF document, but one appears at .${nested[0]}`
+                    : 'Input is not an ADF document: no top-level "type": "doc"',
+                remediation: suggestion,
+            }),
+        };
+    }
+    const depth = depthOf(value);
+    if (depth > MAX_DEPTH)
+        return {
+            ok: false,
+            diagnostic: diagnostic({
+                code: CODES.tooDeep,
+                severity: "error",
+                quality: "unsupported",
+                message: `Input nests deeper than ${MAX_DEPTH} levels`,
+            }),
+        };
+    const record = value;
+    return {
+        ok: true,
+        document: {
+            version: typeof record.version === "number" ? record.version : 1,
+            type: "doc",
+            content: Array.isArray(record.content) ? record.content : [],
+        },
+    };
+}
+//# sourceMappingURL=read.js.map

package/dist/jira/adf/read.js.map

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

package/dist/jira/adf/serialize.d.ts

@@ -0,0 +1,5 @@
+import type { AdfDocument } from "./types.js";
+/** Returns the document with every key in canonical order. */
+export declare function canonicalize(document: AdfDocument): AdfDocument;
+/** Canonical ADF JSON, two-space indented, one trailing newline. */
+export declare function serializeAdf(document: AdfDocument): string;

package/dist/jira/adf/serialize.js

@@ -0,0 +1,54 @@
+/**
+ * Serializes ADF with a fixed key order.
+ *
+ * `JSON.stringify` follows insertion order, so key order is contract: a consumer
+ * diffing converted ADF in Git sees every reordering. This is the same reason
+ * `src/sarif.ts` builds its document in a load-bearing order and
+ * `tests/unit/automation.test.ts` asserts byte equality against a fixed input.
+ *
+ * The order is `version`, `type`, `attrs`, `content`, `marks`, `text` — the
+ * order Atlassian's own editor emits, so a converted document diffs cleanly
+ * against one round-tripped through Jira.
+ */
+function orderMark(mark) {
+    const ordered = { type: mark.type };
+    if (mark.attrs !== undefined)
+        ordered.attrs = orderAttrs(mark.attrs);
+    return ordered;
+}
+/**
+ * Attribute order within `attrs` is contract too, and there is no natural one,
+ * so it is byte order. Never `localeCompare`: that is ICU-build and locale
+ * dependent, so a differently configured runner would reorder the output.
+ */
+function orderAttrs(attrs) {
+    const ordered = {};
+    for (const key of Object.keys(attrs).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)))
+        ordered[key] = attrs[key];
+    return ordered;
+}
+function orderNode(node) {
+    const ordered = { type: node.type };
+    if (node.attrs !== undefined)
+        ordered.attrs = orderAttrs(node.attrs);
+    if (node.content !== undefined)
+        ordered.content = node.content.map(orderNode);
+    if (node.marks !== undefined)
+        ordered.marks = node.marks.map(orderMark);
+    if (node.text !== undefined)
+        ordered.text = node.text;
+    return ordered;
+}
+/** Returns the document with every key in canonical order. */
+export function canonicalize(document) {
+    return {
+        version: document.version,
+        type: "doc",
+        ...(document.content === undefined ? {} : { content: document.content.map(orderNode) }),
+    };
+}
+/** Canonical ADF JSON, two-space indented, one trailing newline. */
+export function serializeAdf(document) {
+    return `${JSON.stringify(canonicalize(document), null, 2)}\n`;
+}
+//# sourceMappingURL=serialize.js.map

package/dist/jira/adf/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../src/jira/adf/serialize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,SAAS,SAAS,CAAC,IAAa;IAC9B,MAAM,OAAO,GAAY,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAA8B;IAChD,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,IAAa;IAC9B,MAAM,OAAO,GAAY,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrE,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC9E,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACtD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,QAAqB;IAChD,OAAO;QACL,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,IAAI,EAAE,KAAK;QACX,GAAG,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;KACxF,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,QAAqB;IAChD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC"}

package/dist/jira/adf/to-markdown.d.ts

@@ -0,0 +1,14 @@
+import type { AdfDocument, ConversionDiagnostic } from "./types.js";
+export interface ToMarkdownResult {
+    markdown: string;
+    diagnostics: ConversionDiagnostic[];
+}
+/**
+ * Converts an ADF document to Markdown.
+ *
+ * Emits no frontmatter, ever, and this is not an option: an ADF document carries
+ * no title, key, status, or author, so there is nothing to put there. Provenance
+ * belongs in the result payload, the way `agent convert` writes a report rather
+ * than inlining one.
+ */
+export declare function toMarkdown(document: AdfDocument): ToMarkdownResult;