markdown-to-adf 0.2.1

package/dist/utils/inline-parser.js

@@ -0,0 +1,174 @@
+/**
+ * Utilities for parsing inline markdown-it tokens into ADF inline nodes.
+ */
+import { text, hardBreak } from '../builders/nodes.js';
+import { strong, em, code as codeMark, strike, link } from '../builders/marks.js';
+export function parseInlineTokens(tokens, options) {
+    if (!tokens || tokens.length === 0) {
+        return { nodes: [], taskChecked: false };
+    }
+    const nodes = [];
+    const marks = [];
+    let taskChecked = false;
+    const pushText = (value, activeMarks) => {
+        if (value === '')
+            return;
+        const last = nodes[nodes.length - 1];
+        if (last && last.type === 'text' && areMarksEqual(last.marks, activeMarks)) {
+            nodes[nodes.length - 1] = text(last.text + value, activeMarks.length > 0 ? activeMarks : undefined);
+            return;
+        }
+        nodes.push(text(value, activeMarks.length > 0 ? activeMarks : undefined));
+    };
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'text': {
+                pushText(token.content, marks.slice());
+                break;
+            }
+            case 'code_inline': {
+                pushText(token.content, [...marks, codeMark()]);
+                break;
+            }
+            case 'softbreak': {
+                if (options.preserveLineBreaks) {
+                    nodes.push(hardBreak());
+                }
+                else {
+                    pushText(' ', marks.slice());
+                }
+                break;
+            }
+            case 'hardbreak': {
+                nodes.push(hardBreak());
+                break;
+            }
+            case 'strong_open': {
+                marks.push(strong());
+                break;
+            }
+            case 'strong_close': {
+                popMark(marks, 'strong');
+                break;
+            }
+            case 'em_open': {
+                marks.push(em());
+                break;
+            }
+            case 'em_close': {
+                popMark(marks, 'em');
+                break;
+            }
+            case 's_open':
+            case 'del_open': {
+                marks.push(strike());
+                break;
+            }
+            case 's_close':
+            case 'del_close': {
+                popMark(marks, 'strike');
+                break;
+            }
+            case 'link_open': {
+                const href = getAttr(token, 'href');
+                const title = getAttr(token, 'title');
+                if (href) {
+                    marks.push(link(href, title ?? undefined));
+                }
+                break;
+            }
+            case 'link_close': {
+                popMark(marks, 'link');
+                break;
+            }
+            case 'html_inline': {
+                if (options.stripTaskCheckbox) {
+                    const checkbox = parseTaskCheckbox(token.content);
+                    if (checkbox.isCheckbox) {
+                        if (checkbox.checked)
+                            taskChecked = true;
+                        break;
+                    }
+                }
+                break;
+            }
+            case 'image': {
+                const src = getAttr(token, 'src');
+                const alt = token.content || getAttr(token, 'alt');
+                if (src) {
+                    pushText(alt || src, [...marks, link(src)]);
+                }
+                else if (alt) {
+                    pushText(alt, marks.slice());
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return { nodes, taskChecked };
+}
+function popMark(marks, type) {
+    for (let i = marks.length - 1; i >= 0; i--) {
+        if (marks[i]?.type === type) {
+            marks.splice(i, 1);
+            return;
+        }
+    }
+}
+function areMarksEqual(left, right) {
+    if (!left || left.length === 0) {
+        return right.length === 0;
+    }
+    if (left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i++) {
+        const a = left[i];
+        const b = right[i];
+        if (a.type !== b.type)
+            return false;
+        const aAttrs = 'attrs' in a ? a.attrs : undefined;
+        const bAttrs = 'attrs' in b ? b.attrs : undefined;
+        if (!shallowEqual(aAttrs, bAttrs))
+            return false;
+    }
+    return true;
+}
+function shallowEqual(left, right) {
+    if (!left && !right)
+        return true;
+    if (!left || !right)
+        return false;
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    if (leftKeys.length !== rightKeys.length)
+        return false;
+    for (const key of leftKeys) {
+        if (left[key] !== right[key])
+            return false;
+    }
+    return true;
+}
+function getAttr(token, name) {
+    if (typeof token.attrGet === 'function') {
+        return token.attrGet(name);
+    }
+    if (!token.attrs)
+        return null;
+    for (const attr of token.attrs) {
+        if (attr[0] === name) {
+            return attr[1] ?? null;
+        }
+    }
+    return null;
+}
+function parseTaskCheckbox(html) {
+    const isCheckbox = /type=["']checkbox["']/i.test(html);
+    if (!isCheckbox) {
+        return { isCheckbox: false, checked: false };
+    }
+    const checked = /checked(=|\s|>)/i.test(html);
+    return { isCheckbox: true, checked };
+}
+//# sourceMappingURL=inline-parser.js.map

package/dist/utils/inline-parser.js.map

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

package/docs/compatibility.md

@@ -0,0 +1,30 @@
+# Compatibility Guide
+
+This library targets Jira Cloud ADF behavior and applies conservative conversions for different contexts.
+
+## Presets
+
+| Preset    | Intended context             |
+| --------- | ---------------------------- |
+| `comment` | Issue comments               |
+| `task`    | Task-type issue descriptions |
+| `story`   | Story/Epic descriptions      |
+| `default` | Safe default across contexts |
+
+## Node Compatibility
+
+| Markdown feature | ADF output    | `comment`         | `task`            | `story` | Notes                                       |
+| ---------------- | ------------- | ----------------- | ----------------- | ------- | ------------------------------------------- |
+| Headings         | `heading`     | Converted to bold | Converted to bold | Allowed | Strict mode throws for incompatible presets |
+| Paragraphs       | `paragraph`   | ✅                | ✅                | ✅      |                                             |
+| Bullet lists     | `bulletList`  | ✅                | ✅                | ✅      |                                             |
+| Ordered lists    | `orderedList` | ✅                | ✅                | ✅      |                                             |
+| Task lists       | `taskList`    | ✅                | ✅                | ✅      | Inline-only in ADF                          |
+| Code blocks      | `codeBlock`   | ✅                | ✅                | ✅      |                                             |
+| Block quotes     | `blockQuote`  | ✅                | ✅                | ✅      |                                             |
+| Tables           | `table`       | ✅ (risky)        | ✅                | ✅      | `comment` warns by default                  |
+| Horizontal rules | —             | ❌                | ❌                | ❌      | Strict mode throws                          |
+
+## Risky Nodes
+
+Some nodes are valid but known to be inconsistent in certain Jira views. Use `warnOnRiskyNodes` or the `comment` preset to surface warnings.

package/docs/presets.md

@@ -0,0 +1,22 @@
+# Presets
+
+Presets tune the converter for different Jira contexts.
+
+## `comment`
+
+- Converts headings to bold paragraphs.
+- Enables `warnOnRiskyNodes` by default.
+
+## `task`
+
+- Converts headings to bold paragraphs.
+- Conservative defaults.
+
+## `story`
+
+- Allows headings.
+- Full feature support.
+
+## `default`
+
+- Safe defaults intended to work in most contexts.

package/docs/warnings.md

@@ -0,0 +1,20 @@
+# Warnings
+
+The warnings API surfaces lossy conversions or risky nodes so you can log, audit, or enforce policies.
+
+## Types
+
+- `lossy_conversion`: a supported input was downgraded (e.g., headings to bold).
+- `unsupported_feature`: the input could not be represented (e.g., horizontal rules).
+- `invalid_syntax`: the input contained invalid Markdown.
+- `risky_feature`: valid ADF that is known to behave inconsistently in some contexts.
+
+## Usage
+
+```ts
+import { markdownToAdfWithWarnings } from 'markdown-to-adf';
+
+const { adf, warnings } = markdownToAdfWithWarnings(markdown, {
+  preset: 'comment',
+});
+```

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "markdown-to-adf",
+  "version": "0.2.1",
+  "description": "Convert Markdown to Atlassian Document Format (ADF) with context-aware presets for Jira",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && bun test"
+  },
+  "keywords": [
+    "markdown",
+    "adf",
+    "atlassian",
+    "jira",
+    "confluence",
+    "document-format",
+    "converter",
+    "parser",
+    "typescript"
+  ],
+  "author": "Christian Gilan <cgilan@twilio.com>",
+  "license": "MIT",
+  "dependencies": {
+    "markdown-it": "^14.0.0",
+    "markdown-it-task-lists": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/markdown-it": "^13.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.9.0",
+    "@typescript-eslint/parser": "^7.9.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.2.5",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/califlower/markdown-to-adf.git"
+  }
+}