@cairn-tool/cairn 3.0.0 → 3.2.0

package/dist/jira/adf/validate.js

@@ -0,0 +1,182 @@
+import { CODES, DiagnosticSink } from "./diagnostics.js";
+import { CONTENT_MODEL, FIDELITY, MARK_FIDELITY, PANEL_TYPES, accepts } from "./profile.js";
+/**
+ * Structural validation against this tool's own content model.
+ *
+ * Deliberately not a wrapper around Atlassian's schema. That schema is a
+ * devDependency read only by `tests/unit/jira-adf-profile.test.ts`, which proves the
+ * model here agrees with it in both directions — so this reports the same
+ * legality answers without shipping someone else's document, and a node type the
+ * model does not know reports `AD100` rather than pretending to be Atlassian's
+ * validator. It is the same line `agent test --native` draws: every target
+ * profile declares `nativeValidator: null` and publishes the command to run
+ * yourself.
+ */
+function attributeError(node, sink, trail, message) {
+    sink.add({
+        code: CODES.badAttribute,
+        quality: "unsupported",
+        severity: "error",
+        message,
+        node: node.type,
+        location: trail.join("/"),
+    });
+}
+function checkAttributes(node, sink, trail) {
+    switch (node.type) {
+        case "heading": {
+            const level = node.attrs?.level;
+            if (!Number.isInteger(level) || level < 1 || level > 6)
+                attributeError(node, sink, trail, `heading level must be an integer 1-6, got ${String(level)}`);
+            break;
+        }
+        case "panel": {
+            const kind = node.attrs?.panelType;
+            if (typeof kind !== "string" || !PANEL_TYPES.has(kind))
+                attributeError(node, sink, trail, `panelType must be one of ${[...PANEL_TYPES].join(", ")}, got ${String(kind)}`);
+            break;
+        }
+        case "taskList":
+        case "taskItem":
+        case "decisionList":
+        case "decisionItem": {
+            if (typeof node.attrs?.localId !== "string")
+                attributeError(node, sink, trail, `${node.type} requires a string localId`);
+            break;
+        }
+        case "media": {
+            const kind = node.attrs?.type;
+            if (kind === "external") {
+                if (typeof node.attrs?.url !== "string")
+                    attributeError(node, sink, trail, "external media requires a url");
+            }
+            else if (kind === "file" || kind === "link") {
+                if (typeof node.attrs?.id !== "string")
+                    attributeError(node, sink, trail, `${String(kind)} media requires an id`);
+                if (typeof node.attrs?.collection !== "string")
+                    attributeError(node, sink, trail, `${String(kind)} media requires a collection`);
+            }
+            else {
+                attributeError(node, sink, trail, `media type must be external, file, or link, got ${String(kind)}`);
+            }
+            break;
+        }
+        case "text": {
+            // An empty text node is invalid ADF, which is why an empty paragraph is
+            // `content: []` rather than a paragraph holding empty text.
+            if (node.text === "")
+                attributeError(node, sink, trail, "a text node may not carry an empty string");
+            break;
+        }
+        default:
+            break;
+    }
+}
+function walk(node, sink, trail) {
+    const here = [...trail, node.type];
+    if (!FIDELITY[node.type]) {
+        sink.add({
+            code: CODES.unknownNode,
+            quality: "unsupported",
+            message: `Unrecognized ADF node type '${node.type}'`,
+            node: node.type,
+            location: trail.join("/"),
+            remediation: "This tool's content model does not know this node, so it cannot be validated or converted. Check for a newer cairn.",
+        });
+        return;
+    }
+    checkAttributes(node, sink, trail);
+    for (const mark of node.marks ?? []) {
+        if (MARK_FIDELITY[mark.type])
+            continue;
+        sink.add({
+            code: CODES.unknownMark,
+            quality: "unsupported",
+            message: `Unrecognized ADF mark '${mark.type}'`,
+            node: mark.type,
+            location: here.join("/"),
+        });
+    }
+    // Code block text carries no marks: the schema forbids it outright.
+    if (node.type === "codeBlock")
+        for (const child of node.content ?? [])
+            if (child.marks?.length)
+                sink.add({
+                    code: CODES.illegalContent,
+                    quality: "unsupported",
+                    severity: "error",
+                    message: "Text inside a code block may not carry marks",
+                    node: "text",
+                    location: here.join("/"),
+                });
+    const rule = CONTENT_MODEL[node.type];
+    const children = node.content ?? [];
+    if (rule) {
+        if (children.length < rule.minimum)
+            sink.add({
+                code: CODES.missingContent,
+                quality: "unsupported",
+                severity: "error",
+                message: `${node.type} requires at least ${rule.minimum} child, but has ${children.length}`,
+                node: node.type,
+                location: trail.join("/"),
+            });
+        if (rule.maximum !== undefined && children.length > rule.maximum)
+            sink.add({
+                code: CODES.illegalContent,
+                quality: "unsupported",
+                severity: "error",
+                message: `${node.type} allows at most ${rule.maximum} child, but has ${children.length}`,
+                node: node.type,
+                location: trail.join("/"),
+            });
+        for (const child of children)
+            if (!accepts(node.type, child.type))
+                sink.add({
+                    code: CODES.illegalContent,
+                    quality: "unsupported",
+                    severity: "error",
+                    message: `ADF does not allow ${child.type} inside ${node.type}`,
+                    node: child.type,
+                    location: here.join("/"),
+                });
+    }
+    for (const child of children)
+        walk(child, sink, here);
+}
+export function validateAdf(document) {
+    const sink = new DiagnosticSink();
+    const rule = CONTENT_MODEL.doc;
+    const children = document.content ?? [];
+    for (const child of children)
+        if (!accepts("doc", child.type) && FIDELITY[child.type])
+            sink.add({
+                code: CODES.illegalContent,
+                quality: "unsupported",
+                severity: "error",
+                message: `ADF does not allow ${child.type} at the top level of a document`,
+                node: child.type,
+                location: "doc",
+            });
+    if (children.length < rule.minimum)
+        sink.add({
+            code: CODES.missingContent,
+            quality: "unsupported",
+            severity: "error",
+            message: "A document requires content",
+            node: "doc",
+            location: "doc",
+        });
+    for (const child of children)
+        walk(child, sink, ["doc"]);
+    const diagnostics = sink.all();
+    const unknown = [
+        ...new Set(diagnostics
+            .filter((item) => item.code === CODES.unknownNode || item.code === CODES.unknownMark)
+            .map((item) => item.node ?? "")),
+    ]
+        .filter(Boolean)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return { diagnostics, unknown };
+}
+//# sourceMappingURL=validate.js.map

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

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

package/dist/mapping-quality.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How faithfully a concept survived a mapping between two formats.
+ *
+ * Shared by the agent-bundle renderer and the ADF converters. It lives here
+ * rather than in either one because both diagnostic families derive severity
+ * from it by the same rule, and a second copy would let the two drift.
+ */
+export type MappingQuality = "exact" | "approximate" | "unsupported";
+export type DiagnosticSeverity = "notice" | "warning" | "error";
+/**
+ * Derives severity from quality rather than choosing it per site.
+ *
+ * A caller that means "refuse" sets `severity: "error"` explicitly afterward,
+ * which is why an `unsupported` code can be either a warning (this feature does
+ * not cross over) or an error (this input is invalid): the quality describes the
+ * mapping, the severity describes the consequence.
+ */
+export declare function severityFor(quality: MappingQuality): DiagnosticSeverity;

package/dist/mapping-quality.js

@@ -0,0 +1,12 @@
+/**
+ * Derives severity from quality rather than choosing it per site.
+ *
+ * A caller that means "refuse" sets `severity: "error"` explicitly afterward,
+ * which is why an `unsupported` code can be either a warning (this feature does
+ * not cross over) or an error (this input is invalid): the quality describes the
+ * mapping, the severity describes the consequence.
+ */
+export function severityFor(quality) {
+    return quality === "exact" ? "notice" : "warning";
+}
+//# sourceMappingURL=mapping-quality.js.map

package/dist/mapping-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping-quality.js","sourceRoot":"","sources":["../src/mapping-quality.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAuB;IACjD,OAAO,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC"}

package/dist/usage/providers/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { UsageProvider } from "./types.js";
+export declare const cursorProvider: UsageProvider;