@markup-carve/pandoc-carve 0.1.4 → 0.1.5

package/README.md

@@ -46,6 +46,12 @@ pandoc-carve doc.crv -t latex -s -o doc.tex
 # Just the Pandoc JSON AST (no pandoc needed)
 pandoc-carve doc.crv -t json
 
+# Expand contained includes; named files default to their own directory
+pandoc-carve book/main.crv -t json --include-root "$PWD/book"
+
+# Keep directives literal for a named file
+pandoc-carve book/main.crv -t json --no-includes
+
 # Read from stdin, pass extra args through to pandoc after --
 cat doc.crv | pandoc-carve - -t latex -- --toc
 
@@ -62,25 +68,51 @@ carve doc.crv --to-json | pandoc-carve - -f carve-json -t latex
 ```
 
 Anything Carve cannot map faithfully is reported on stderr as a
-`pandoc-carve: degraded ...` warning - nothing degrades silently. For migration
-automation, `--diagnostics report.json` writes the same findings as structured
-JSON without mixing them into document output. `--fail-on-loss` exits with code
-3 for `lossy` or `unsupported` findings, while harmless `normalized` findings
-do not fail CI. Use `--diagnostics -` for JSON on stderr.
+`pandoc-carve: degraded ...` warning - nothing degrades silently. Unresolved or
+refused includes are reported as dropped, while safe include renames and heading
+clamps are normalized. For migration
+automation, `--diagnostics report.json` writes the same findings in a versioned
+`{ schemaVersion, sourceFormat, diagnostics }` JSON envelope without mixing
+them into document output. `--fail-on-loss` exits with code 3 for degraded or
+dropped findings, while preserved and normalized findings do not fail CI.
+Imports through a Pandoc reader other than `-f json` also exit
+3 because fidelity before the Pandoc JSON boundary cannot be verified; stderr
+names that worst-case gate explicitly. Use `--diagnostics -` for JSON on stderr.
 
 ## API
 
 ```js
 import { carveToPandoc, carveToPandocJson } from '@markup-carve/pandoc-carve';
 
-const { doc, warnings, diagnostics } = carveToPandoc('Hello /world/!');
+const { doc, warnings, diagnostics, report } = carveToPandoc('Hello /world/!');
 // doc = { 'pandoc-api-version': [1, 23, 1], meta: {...}, blocks: [...] }
 // warnings = ['degraded: ...'] for lossy constructs
-// diagnostics = [{ code, direction, severity, message, details?, path?, sourceLocation? }]
+// diagnostics = [{ code, direction, class, severity, fidelity, confidence, message, ... }]
+// report = { schemaVersion: 2, sourceFormat: 'carve', diagnostics }
 
 const json = carveToPandocJson('Hello /world/!'); // stringified doc
 ```
 
+String conversion leaves `{{ path }}` directives literal. File-backed hosts can
+opt into contained expansion and receive warnings and dependency identities:
+
+```js
+import { readFileSync } from 'node:fs';
+import { carveToPandocWithIncludes } from '@markup-carve/pandoc-carve/node';
+
+const sourcePath = '/srv/book/main.crv';
+const result = carveToPandocWithIncludes(readFileSync(sourcePath, 'utf8'), {
+  includeRoot: '/srv/book',
+  sourcePath,
+});
+// includeWarnings and suppressedIncludeWarnings describe expansion diagnostics;
+// dependencies contains resolved and unresolved include identities.
+```
+
+Both API paths must be absolute, and `sourcePath` must stay inside
+`includeRoot`. The CLI accepts ordinary relative input paths but requires an
+absolute `--include-root`. Stdin stays literal unless that option is supplied.
+
 What the converter reads is the **serialized AST of the Carve spec's PART 12**
 (the shape `resources/ast-schema.json` pins), not any implementation's runtime
 tree - so a document another engine already parsed converts the same way,
@@ -103,7 +135,7 @@ serializer), so output formatting carries fmt's guarantees:
 ```js
 import { pandocToCarve, pandocToCarveAst } from '@markup-carve/pandoc-carve';
 
-const { carve, warnings, diagnostics } = pandocToCarve(pandocJsonString);
+const { carve, warnings, diagnostics, report } = pandocToCarve(pandocJsonString);
 
 // Preserve structured fields that Carve 0.1 source cannot spell, including
 // Pandoc's optional short figure/table caption.
@@ -173,7 +205,8 @@ every target that emits a resolvable URL. Pandoc's targets are not HTML, but
 `pandoc -f json -t html` is one command away - passing the scheme through here
 would not be a narrower policy, it would be the same sink one step removed.
 
-The diagnostic is `lossy`, so `--fail-on-loss` stops on it and a caller reading
+The diagnostic class is `lossy`, so `--fail-on-loss` stops on its dropped
+fidelity and a caller reading
 `diagnostics` can act on it. The scheme list and the scheme probe are mirrored
 from the engine rather than invented, and a test drives the engine's own writer
 over both to keep the mirror honest - the probe strips control characters and
@@ -356,16 +389,4 @@ a processor with neither extension enabled would render.
 
 ## Development
 
-The test suite converts the whole shared spec corpus, which arrives as a
-submodule:
-
-```sh
-git clone --recurse-submodules https://github.com/markup-carve/pandoc-carve
-# or, in an existing clone:
-git submodule update --init
-npm ci && npm test
-```
-
-Without the submodule the corpus tests FAIL rather than skip - a skipped corpus
-reads like a converted one, which is how a stack overflow reachable from a
-two-word document stayed live on the published package.
+Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).

package/dist/ast-json.js

@@ -47,6 +47,8 @@ const CHILD_FIELDS = [
     'shortCaption',
     'title',
     'target',
+    'old',
+    'new',
 ];
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -107,6 +109,19 @@ function normalize(node) {
             // reads the wire has no reason to know the other spelling existed.
             set('type', 'critic_comment');
             break;
+        case 'substitution': {
+            if (!Array.isArray(current['old']) && typeof current['oldText'] === 'string') {
+                set('old', [{ type: 'text', value: current['oldText'] }]);
+            }
+            if (!Array.isArray(current['new']) && typeof current['newText'] === 'string') {
+                set('new', [{ type: 'text', value: current['newText'] }]);
+            }
+            if (current['oldText'] !== undefined || current['newText'] !== undefined) {
+                const { oldText: _oldText, newText: _newText, ...rest } = out ?? { ...node };
+                out = rest;
+            }
+            break;
+        }
         case 'footnote': {
             // The pre-split inline node (carve#405), whose name COLLIDES with
             // the wire `footnote` - which is the DEFINITION block, carrying

package/dist/cli.js

@@ -8,9 +8,11 @@
  *
  * Everything after `--` is passed through to pandoc verbatim.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { carveAstToPandoc, carveToPandoc } from './index.js';
-import { hasLoss } from './diagnostics.js';
+import { carveToPandocWithIncludes } from './includes.js';
+import { hasLoss, migrationReport } from './diagnostics.js';
 function usage(exitCode) {
     const text = `Usage: pandoc-carve <input | -> [options] [-- pandoc-args...]
 
@@ -36,6 +38,8 @@ Common options:
                      human warnings are suppressed)
   --fail-on-loss     exit 3 when lossy or unsupported diagnostics are present
   --symbols FILE     JSON map resolving :name: symbols to text (export)
+  --include-root DIR containment root for includes (defaults to input folder)
+  --no-includes      leave include directives literal
   --pandoc PATH      pandoc executable (default: $PANDOC or "pandoc")
   -h, --help         show this help
 `;
@@ -50,6 +54,7 @@ function parseArgs(argv) {
         roundtrip: false,
         listTable: true,
         citations: true,
+        includes: true,
         failOnLoss: false,
         pandocPath: process.env.PANDOC ?? 'pandoc',
         passthrough: [],
@@ -88,6 +93,12 @@ function parseArgs(argv) {
         else if (a === '--symbols') {
             args.symbolsFile = argv[++i] ?? usage(1);
         }
+        else if (a === '--include-root') {
+            args.includeRoot = argv[++i] ?? usage(1);
+        }
+        else if (a === '--no-includes') {
+            args.includes = false;
+        }
         else if (a === '--diagnostics') {
             args.diagnosticsFile = argv[++i] ?? usage(1);
         }
@@ -112,6 +123,9 @@ function parseArgs(argv) {
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    if (args.from && args.from !== 'carve' && (args.includeRoot || !args.includes)) {
+        throw new Error('--include-root and --no-includes only apply to Carve source input');
+    }
     // `carve` and `carve-json` are the two EXPORT inputs - Carve source, and the
     // serialized AST any engine writes with --to-json. Every other `-f` names a
     // pandoc reader, which is the import direction.
@@ -128,17 +142,38 @@ async function main() {
         citations: args.citations,
         symbols,
     };
-    const { doc, warnings, diagnostics } = args.from === 'carve-json'
-        ? carveAstToPandoc(source, options)
-        : carveToPandoc(source, options);
-    report(args, warnings, diagnostics);
+    if (args.includeRoot && !path.isAbsolute(args.includeRoot)) {
+        throw new Error('--include-root must be an absolute path');
+    }
+    let includeResult;
+    let converted;
+    if (args.from === 'carve-json') {
+        converted = carveAstToPandoc(source, options);
+    }
+    else if (args.includes && (args.input !== '-' || args.includeRoot)) {
+        includeResult = carveToPandocWithIncludes(source, {
+            includeRoot: path.resolve(args.includeRoot ?? path.dirname(args.input)),
+            ...(args.input === '-' ? {} : { sourcePath: path.resolve(args.input) }),
+        }, options);
+        converted = includeResult;
+    }
+    else {
+        converted = carveToPandoc(source, options);
+    }
+    const includeWarnings = includeResult?.includeWarnings ?? [];
+    const suppressedIncludeWarnings = includeResult?.suppressedIncludeWarnings ?? 0;
+    const { doc, warnings, diagnostics } = converted;
+    const root = args.includeRoot ?? (args.input === '-' ? undefined : path.dirname(path.resolve(args.input)));
+    const includeDiagnostics = diagnosticsForIncludes(includeWarnings, suppressedIncludeWarnings, root);
+    const allDiagnostics = [...diagnostics, ...includeDiagnostics];
+    report(args, warnings, allDiagnostics, 'carve', includeWarnings, suppressedIncludeWarnings, root);
     const json = JSON.stringify(doc);
     if (args.to === 'json') {
         if (args.output)
             writeFileSync(args.output, json + '\n');
         else
             process.stdout.write(json + '\n');
-        if (args.failOnLoss && hasLoss(diagnostics))
+        if (args.failOnLoss && hasLoss(allDiagnostics))
             process.exitCode = 3;
         return;
     }
@@ -172,7 +207,7 @@ async function main() {
         }
         throw result.error;
     }
-    process.exit(result.status || (args.failOnLoss && hasLoss(diagnostics) ? 3 : 0));
+    process.exit(result.status || (args.failOnLoss && hasLoss(allDiagnostics) ? 3 : 0));
 }
 /** Reverse direction: pandoc-readable input -> Carve source. */
 async function importToCarve(args) {
@@ -201,17 +236,29 @@ async function importToCarve(args) {
     }
     const { pandocToCarve } = await import('./index.js');
     const { carve, warnings, diagnostics } = pandocToCarve(json);
-    report(args, warnings, diagnostics);
+    const reportDiagnostics = args.from === 'json' ? diagnostics : [
+        ...diagnostics,
+        {
+            code: 'fidelity-unverified',
+            direction: 'pandoc-to-carve',
+            class: 'unsupported',
+            severity: 'error',
+            fidelity: 'dropped',
+            confidence: 'fallback',
+            message: 'Fidelity before the Pandoc JSON boundary was not reported; dropped is a conservative worst-case release-gate classification',
+        },
+    ];
+    report(args, warnings, reportDiagnostics, 'pandoc-json');
     if (args.output)
         writeFileSync(args.output, carve);
     else
         process.stdout.write(carve);
-    if (args.failOnLoss && hasLoss(diagnostics))
+    if (args.failOnLoss && hasLoss(reportDiagnostics))
         process.exitCode = 3;
 }
-function report(args, warnings, diagnostics) {
+function report(args, warnings, diagnostics, sourceFormat, includeWarnings = [], suppressedIncludeWarnings = 0, includeRoot) {
     if (args.diagnosticsFile !== undefined) {
-        const json = JSON.stringify(diagnostics, null, 2) + '\n';
+        const json = JSON.stringify(migrationReport(diagnostics, sourceFormat), null, 2) + '\n';
         if (args.diagnosticsFile === '-')
             process.stderr.write(json);
         else
@@ -220,6 +267,72 @@ function report(args, warnings, diagnostics) {
     }
     for (const warning of warnings)
         process.stderr.write(`pandoc-carve: degraded: ${warning}\n`);
+    for (const warning of includeWarnings) {
+        const file = displayIncludeFile(warning.file, includeRoot, args.input);
+        process.stderr.write(`pandoc-carve: ${file}:${warning.line}:${warning.column} ${warning.rule} - ${warning.message}\n`);
+    }
+    if (suppressedIncludeWarnings) {
+        process.stderr.write(`pandoc-carve: ${suppressedIncludeWarnings} additional include warning(s) suppressed\n`);
+    }
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.code === 'fidelity-unverified') {
+            process.stderr.write(`pandoc-carve: dropped: ${diagnostic.message}\n`);
+        }
+    }
+}
+function diagnosticsForIncludes(warnings, suppressed, root) {
+    const diagnostics = warnings.map((warning) => {
+        const normalized = NORMALIZED_INCLUDE_RULES.has(warning.rule);
+        const file = warning.file ? displayIncludeFile(warning.file, root, '') : undefined;
+        return {
+            code: warning.rule,
+            direction: 'carve-to-pandoc',
+            class: normalized ? 'normalized' : 'lossy',
+            severity: normalized ? 'info' : 'error',
+            fidelity: normalized ? 'normalized' : 'dropped',
+            confidence: 'exact',
+            message: warning.message,
+            details: {
+                ...(file ? { file } : {}),
+                line: warning.line,
+                column: warning.column,
+            },
+        };
+    });
+    if (suppressed)
+        diagnostics.push({
+            code: 'include-warnings-suppressed',
+            direction: 'carve-to-pandoc',
+            class: 'degraded',
+            severity: 'warning',
+            fidelity: 'degraded',
+            confidence: 'exact',
+            message: `${suppressed} additional include warning(s) suppressed`,
+            details: { count: suppressed },
+        });
+    return diagnostics;
+}
+const NORMALIZED_INCLUDE_RULES = new Set([
+    'include-footnote-rename',
+    'include-heading-clamp',
+    'include-heading-id-rename',
+]);
+function displayIncludeFile(file, root, fallback) {
+    if (!file || !root)
+        return fallback;
+    const canonicalRoot = realpathSync(root);
+    let canonicalFile = file;
+    try {
+        canonicalFile = realpathSync(file);
+    }
+    catch {
+        // A resolver may report an unresolved identity. Keep it contained below.
+    }
+    const relative = path.relative(canonicalRoot, canonicalFile);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return '[outside-include-root]';
+    }
+    return `[include-root]/${relative || '.'}`;
 }
 main().catch((err) => {
     process.stderr.write(`pandoc-carve: ${err instanceof Error ? err.message : String(err)}\n`);

package/dist/convert.d.ts

@@ -11,11 +11,12 @@
  */
 import type { CarveAstDocument } from './ast-json.js';
 import * as P from './pandoc.js';
-import { type ConversionDiagnostic } from './diagnostics.js';
+import { type ConversionDiagnostic, type MigrationReport } from './diagnostics.js';
 export interface ConvertResult {
     doc: P.PandocDoc;
     warnings: string[];
     diagnostics: ConversionDiagnostic[];
+    report: MigrationReport;
 }
 export interface ConvertOptions {
     /**

package/dist/convert.js

@@ -11,7 +11,7 @@
  */
 import * as P from './pandoc.js';
 import { readRowGroups } from './row-groups.js';
-import { diagnostic } from './diagnostics.js';
+import { diagnostic, migrationReport } from './diagnostics.js';
 import { provenanceAttr } from './provenance.js';
 import { blankDeniedDestination, probeScheme } from './url-scheme.js';
 import { isDangerousAttrName, renderedAttrValue } from './attribute-sanitize.js';
@@ -710,13 +710,13 @@ function inline(ctx, n) {
         case 'delete':
             return [P.Span(P.attr(undefined, ['deletion']), kids(ctx, n))];
         case 'substitution': {
-            const oldText = textInlines(String(n.oldText ?? ''));
-            const newText = textInlines(String(n.newText ?? ''));
+            const oldContent = Array.isArray(n.old) ? inlines(ctx, n.old) : [];
+            const newContent = Array.isArray(n.new) ? inlines(ctx, n.new) : [];
             return [
                 P.Span(P.attr(undefined, ['substitution']), [
-                    P.Span(P.attr(undefined, ['deletion']), oldText),
+                    P.Span(P.attr(undefined, ['deletion']), oldContent),
                     P.Str('→'),
-                    P.Span(P.attr(undefined, ['insertion']), newText),
+                    P.Span(P.attr(undefined, ['insertion']), newContent),
                 ]),
             ];
         }
@@ -2038,6 +2038,7 @@ export function convert(ast, options = {}) {
     // sits relative to its target.
     collectCrossrefTargets(ctx, body, new Map());
     const meta = parseMeta(ctx, frontmatter);
+    const diagnostics = ctx.diagnostics;
     return {
         doc: {
             'pandoc-api-version': [...P.PANDOC_API_VERSION],
@@ -2045,7 +2046,8 @@ export function convert(ast, options = {}) {
             blocks: blocks(ctx, body),
         },
         warnings: ctx.warnings,
-        diagnostics: ctx.diagnostics,
+        diagnostics,
+        report: migrationReport(diagnostics, 'carve'),
     };
 }
 /**

package/dist/diagnostics.d.ts

@@ -1,10 +1,16 @@
 export type DiagnosticDirection = 'carve-to-pandoc' | 'pandoc-to-carve';
-export type DiagnosticSeverity = 'lossy' | 'degraded' | 'normalized' | 'unsupported';
+export type DiagnosticClass = 'lossy' | 'degraded' | 'normalized' | 'unsupported';
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+export type MigrationFidelity = 'preserved' | 'normalized' | 'degraded' | 'dropped';
+export type MigrationConfidence = 'exact' | 'inferred' | 'fallback';
 export interface ConversionDiagnostic {
     /** Stable, machine-readable identifier. */
     code: string;
     direction: DiagnosticDirection;
+    class: DiagnosticClass;
     severity: DiagnosticSeverity;
+    fidelity: MigrationFidelity;
+    confidence: MigrationConfidence;
     message: string;
     /** Construct-specific values useful to migration tooling. */
     details?: Record<string, unknown>;
@@ -14,4 +20,10 @@ export interface ConversionDiagnostic {
     sourceLocation?: unknown;
 }
 export declare function diagnostic(direction: DiagnosticDirection, message: string, details?: Record<string, unknown>, sourceLocation?: unknown): ConversionDiagnostic;
+export interface MigrationReport {
+    schemaVersion: 2;
+    sourceFormat: string;
+    diagnostics: ConversionDiagnostic[];
+}
+export declare function migrationReport(diagnostics: ConversionDiagnostic[], sourceFormat?: string): MigrationReport;
 export declare function hasLoss(diagnostics: ConversionDiagnostic[]): boolean;

package/dist/diagnostics.js

@@ -1,49 +1,57 @@
 // Ordered from specific to general. Codes are API: add rules, never rename them.
 const RULES = [
-    { test: /^comment:/, code: 'comment-dropped', severity: 'lossy' },
-    { test: /^inline: unknown node type/, code: 'unknown-carve-inline', severity: 'degraded' },
-    { test: /^block: unknown node type/, code: 'unknown-carve-block', severity: 'degraded' },
-    { test: /^inline: pandoc node/, code: 'unsupported-pandoc-inline', severity: 'unsupported' },
-    { test: /^block: pandoc node/, code: 'unsupported-pandoc-block', severity: 'unsupported' },
-    { test: /^citation: .*typed locator/, code: 'citation-locator-flattened', severity: 'normalized' },
-    { test: /^citation: .*suppresses its author/, code: 'citation-mode-normalized', severity: 'normalized' },
-    { test: /^Cite mixes /, code: 'citation-mode-normalized', severity: 'normalized' },
-    { test: /^Cite mapped /, code: 'citation-bibliography-not-emitted', severity: 'degraded' },
-    { test: /^SmallCaps /, code: 'smallcaps-degraded', severity: 'degraded' },
-    { test: /^short caption:/, code: 'short-caption-source-unavailable', severity: 'unsupported' },
-    { test: /^figure:/, code: 'figure-unwrapped', severity: 'degraded' },
-    { test: /^figure group: short caption/, code: 'figure-group-short-caption-dropped', severity: 'lossy' },
-    { test: /^frontmatter: format/, code: 'frontmatter-format-unsupported', severity: 'unsupported' },
-    { test: /^frontmatter: line/, code: 'frontmatter-line-skipped', severity: 'lossy' },
-    { test: /^frontmatter: value/, code: 'frontmatter-value-skipped', severity: 'lossy' },
-    { test: /^meta: .*empty/, code: 'metadata-empty-blocks-skipped', severity: 'lossy' },
-    { test: /^meta:/, code: 'metadata-value-skipped', severity: 'lossy' },
-    { test: /^definition list: looseness/, code: 'definition-list-looseness-widened', severity: 'normalized' },
-    { test: /^definition list:/, code: 'definition-entry-skipped', severity: 'lossy' },
-    { test: /^ordered list:/, code: 'ordered-list-marker-normalized', severity: 'normalized' },
-    { test: /^list: an empty item/, code: 'empty-list-item-spelled', severity: 'normalized' },
-    { test: /^task state:/, code: 'task-state-dropped', severity: 'lossy' },
-    { test: /^math: attributes/, code: 'math-attributes-dropped', severity: 'lossy' },
-    { test: /^symbol:/, code: 'symbol-unresolved', severity: 'degraded' },
-    { test: /^url: a denied scheme/, code: 'unsafe-url-scheme', severity: 'lossy' },
-    { test: /^attribute: unsafe name/, code: 'unsafe-attribute-name', severity: 'lossy' },
-    { test: /^attribute: unsafe value/, code: 'unsafe-attribute-value', severity: 'lossy' },
-    { test: /^extension:/, code: 'inline-extension-degraded', severity: 'degraded' },
-    { test: /missing definition/, code: 'reference-unresolved', severity: 'degraded' },
-    { test: /^crossref:/, code: 'crossref-unresolved', severity: 'degraded' },
-    { test: /^list-table: structure/, code: 'list-table-structure-degraded', severity: 'degraded' },
-    { test: /^list-table: the short caption/, code: 'list-table-short-caption-dropped', severity: 'lossy' },
-    { test: /^list-table: a body group's attributes/, code: 'list-table-body-attributes-dropped', severity: 'lossy' },
-    { test: /^list-table: the table's .* body groups/, code: 'list-table-body-groups-merged', severity: 'normalized' },
-    { test: /^list-table: the body groups disagree/, code: 'list-table-row-heads-normalized', severity: 'normalized' },
-    { test: /^list-table: rowspan/, code: 'list-table-rowspan-clipped', severity: 'lossy' },
-    { test: /^table: a row header outside/, code: 'table-row-head-outside-leading-run', severity: 'lossy' },
-    { test: /^table: block-level/, code: 'table-cell-blocks-flattened', severity: 'lossy' },
-    { test: /^table: attributes on/, code: 'table-continuation-attributes-dropped', severity: 'lossy' },
-    { test: /^table: colspan continuation/, code: 'table-colspan-origin-missing', severity: 'degraded' },
-    { test: /^table: rowspan crossing/, code: 'table-rowspan-clipped', severity: 'lossy' },
-    { test: /^table: rowspan continuation/, code: 'table-rowspan-origin-missing', severity: 'degraded' },
-    { test: /^table:/, code: 'table-groups-normalized', severity: 'normalized' },
+    { test: /^comment:/, code: 'comment-dropped', class: 'lossy' },
+    { test: /^inline: unknown node type/, code: 'unknown-carve-inline', class: 'degraded' },
+    { test: /^block: unknown node type/, code: 'unknown-carve-block', class: 'degraded' },
+    { test: /^inline: pandoc node/, code: 'unsupported-pandoc-inline', class: 'unsupported' },
+    { test: /^block: pandoc node/, code: 'unsupported-pandoc-block', class: 'unsupported' },
+    { test: /^citation: .*typed locator/, code: 'citation-locator-flattened', class: 'normalized' },
+    { test: /^citation: .*suppresses its author/, code: 'citation-mode-normalized', class: 'normalized' },
+    { test: /^Cite mixes /, code: 'citation-mode-normalized', class: 'normalized' },
+    { test: /^Cite mapped /, code: 'citation-bibliography-not-emitted', class: 'degraded' },
+    { test: /^SmallCaps /, code: 'smallcaps-degraded', class: 'degraded' },
+    { test: /^short caption:/, code: 'short-caption-source-unavailable', class: 'unsupported' },
+    { test: /^figure:/, code: 'figure-unwrapped', class: 'degraded' },
+    { test: /^figure group: short caption/, code: 'figure-group-short-caption-dropped', class: 'lossy' },
+    { test: /^frontmatter: format/, code: 'frontmatter-format-unsupported', class: 'unsupported' },
+    { test: /^frontmatter: block content/, code: 'frontmatter-block-content-dropped', class: 'lossy' },
+    { test: /^frontmatter: line/, code: 'frontmatter-line-skipped', class: 'lossy' },
+    { test: /^frontmatter: value/, code: 'frontmatter-value-skipped', class: 'lossy' },
+    { test: /^meta: .*empty/, code: 'metadata-empty-blocks-skipped', class: 'lossy' },
+    { test: /^meta:/, code: 'metadata-value-skipped', class: 'lossy' },
+    { test: /^definition list: looseness/, code: 'definition-list-looseness-widened', class: 'normalized' },
+    { test: /^definition list:/, code: 'definition-entry-skipped', class: 'lossy' },
+    { test: /^ordered list:/, code: 'ordered-list-marker-normalized', class: 'normalized' },
+    { test: /^list: an empty item/, code: 'empty-list-item-spelled', class: 'normalized' },
+    { test: /^task state:/, code: 'task-state-dropped', class: 'lossy' },
+    { test: /^math: attributes/, code: 'math-attributes-dropped', class: 'lossy' },
+    { test: /^symbol:/, code: 'symbol-unresolved', class: 'degraded' },
+    { test: /^url: a denied scheme/, code: 'unsafe-url-scheme', class: 'lossy' },
+    { test: /^attribute: unsafe name/, code: 'unsafe-attribute-name', class: 'lossy' },
+    { test: /^attribute: unsafe value/, code: 'unsafe-attribute-value', class: 'lossy' },
+    { test: /^extension:/, code: 'inline-extension-degraded', class: 'degraded' },
+    { test: /^(?:link|image|footnote): missing definition/, code: 'reference-unresolved', class: 'degraded' },
+    { test: /^crossref:/, code: 'crossref-unresolved', class: 'degraded' },
+    { test: /^list-table: structure/, code: 'list-table-structure-degraded', class: 'degraded' },
+    { test: /^list-table: the short caption/, code: 'list-table-short-caption-dropped', class: 'lossy' },
+    { test: /^list-table: a body group's attributes/, code: 'list-table-body-attributes-dropped', class: 'lossy' },
+    { test: /^list-table: the table's .* body groups/, code: 'list-table-body-groups-merged', class: 'normalized' },
+    { test: /^list-table: the body groups disagree/, code: 'list-table-row-heads-normalized', class: 'normalized' },
+    { test: /^list-table: rowspan/, code: 'list-table-rowspan-clipped', class: 'lossy' },
+    { test: /^table: a row header outside/, code: 'table-row-head-outside-leading-run', class: 'lossy' },
+    { test: /^table: block-level/, code: 'table-cell-blocks-flattened', class: 'lossy' },
+    { test: /^table: attributes on/, code: 'table-continuation-attributes-dropped', class: 'lossy' },
+    { test: /^table: colspan continuation/, code: 'table-colspan-origin-missing', class: 'degraded' },
+    { test: /^table: rowspan crossing/, code: 'table-rowspan-clipped', class: 'lossy' },
+    { test: /^table: rowspan continuation/, code: 'table-rowspan-origin-missing', class: 'degraded' },
+    { test: /^table: .*padded with empty cells/, code: 'table-groups-normalized', class: 'normalized' },
+    { test: /^table: a cell holds block content/, code: 'table-groups-normalized', class: 'normalized' },
+    { test: /^table: .*converted with the implicit head\/body split/, code: 'table-row-groups-invalid', class: 'degraded' },
+    { test: /^table: .*preserved in the Carve AST as `rowGroups`/, code: 'table-groups-flattened', class: 'degraded' },
+    { test: /^table: a foot row's row header is dropped/, code: 'table-foot-row-header-dropped', class: 'lossy' },
+    { test: /^table: the body rows disagree on how many leading cells/, code: 'table-row-heads-degraded', class: 'degraded' },
+    { test: /^table: the rows of a declared body group disagree/, code: 'table-row-heads-degraded', class: 'degraded' },
+    { test: /^table:/, code: 'table-unclassified-loss', class: 'unsupported' },
 ];
 export function diagnostic(direction, message, details, sourceLocation) {
     const rule = RULES.find((candidate) => candidate.test.test(message));
@@ -53,12 +61,22 @@ export function diagnostic(direction, message, details, sourceLocation) {
     return {
         code: rule.code,
         direction,
-        severity: rule.severity,
+        class: rule.class,
+        severity: rule.class === 'normalized' ? 'info' : rule.class === 'degraded' ? 'warning' : 'error',
+        fidelity: rule.class === 'normalized'
+            ? 'normalized'
+            : rule.class === 'degraded'
+                ? 'degraded'
+                : 'dropped',
+        confidence: 'inferred',
         message,
         ...(Object.keys(inferred).length ? { details: inferred } : {}),
         ...(sourceLocation !== undefined ? { sourceLocation } : {}),
     };
 }
+export function migrationReport(diagnostics, sourceFormat = 'pandoc-json') {
+    return { schemaVersion: 2, sourceFormat, diagnostics };
+}
 function inferDetails(message) {
     const details = {};
     const nodeType = /node(?: type)? "([^"]+)"/.exec(message)?.[1];
@@ -79,5 +97,5 @@ function inferDetails(message) {
     return details;
 }
 export function hasLoss(diagnostics) {
-    return diagnostics.some((item) => item.severity === 'lossy' || item.severity === 'unsupported');
+    return diagnostics.some((item) => item.fidelity === 'degraded' || item.fidelity === 'dropped');
 }

package/dist/includes.d.ts

@@ -0,0 +1,14 @@
+import * as carve from '@markup-carve/carve';
+import { type ParseOptions } from './parse-options.js';
+import type { ConvertOptions, ConvertResult } from './convert.js';
+export interface IncludeConversionOptions {
+    includeRoot: string;
+    sourcePath?: string;
+}
+export interface IncludeConversionResult extends ConvertResult {
+    includeWarnings: carve.IncludeWarning[];
+    suppressedIncludeWarnings: number;
+    dependencies: carve.IncludeDependency[];
+}
+/** Convert file-backed Carve source after contained include expansion. */
+export declare function carveToPandocWithIncludes(source: string, include: IncludeConversionOptions, options?: ConvertOptions & ParseOptions): IncludeConversionResult;

package/dist/includes.js

@@ -0,0 +1,35 @@
+import * as carve from '@markup-carve/carve';
+import { fileSystemResolver } from '@markup-carve/carve/node';
+import path from 'node:path';
+import { toCarveAst } from './ast-json.js';
+import { carveAstToPandoc } from './index.js';
+import { parseExtensions } from './parse-options.js';
+/** Convert file-backed Carve source after contained include expansion. */
+export function carveToPandocWithIncludes(source, include, options) {
+    if (!path.isAbsolute(include.includeRoot)) {
+        throw new Error('includeRoot must be an absolute path');
+    }
+    if (include.sourcePath && !path.isAbsolute(include.sourcePath)) {
+        throw new Error('sourcePath must be an absolute path');
+    }
+    if (include.sourcePath) {
+        const relative = path.relative(include.includeRoot, include.sourcePath);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new Error('input file must be inside --include-root');
+        }
+    }
+    const extensions = parseExtensions(options);
+    const expanded = carve.expandIncludes(carve.parse(source, { extensions, positions: true }), source, {
+        resolve: fileSystemResolver(include.includeRoot),
+        ...(include.sourcePath ? { sourcePath: include.sourcePath } : {}),
+        extensions,
+    });
+    const serializer = carve.toAstJson;
+    const converted = carveAstToPandoc(toCarveAst(expanded.doc, serializer), options);
+    return {
+        ...converted,
+        includeWarnings: expanded.warnings,
+        suppressedIncludeWarnings: expanded.suppressedWarnings,
+        dependencies: expanded.dependencies,
+    };
+}

package/dist/index.d.ts

@@ -3,11 +3,12 @@ import { type ConvertOptions, type ConvertResult } from './convert.js';
 import { type ParseOptions } from './parse-options.js';
 import type { PandocDoc } from './pandoc.js';
 import type { ConversionDiagnostic } from './diagnostics.js';
+import { type MigrationReport } from './diagnostics.js';
 export { PANDOC_API_VERSION, type PandocDoc } from './pandoc.js';
 export type { ConvertOptions, ConvertResult } from './convert.js';
 export type { ParseOptions } from './parse-options.js';
 export type { ReverseResult } from './reverse.js';
-export type { ConversionDiagnostic, DiagnosticDirection, DiagnosticSeverity } from './diagnostics.js';
+export type { ConversionDiagnostic, DiagnosticClass, DiagnosticDirection, DiagnosticSeverity, MigrationConfidence, MigrationFidelity, MigrationReport } from './diagnostics.js';
 export type { CarveAstDocument, CarveAstNode } from './ast-json.js';
 /**
  * Parse Carve source to the serialized AST of PART 12 - the shape
@@ -46,6 +47,7 @@ export declare function pandocToCarve(doc: PandocDoc | string): {
     carve: string;
     warnings: string[];
     diagnostics: ConversionDiagnostic[];
+    report: MigrationReport;
 };
 /**
  * Convert Pandoc to the canonical Carve exchange AST without forcing it through
@@ -56,4 +58,5 @@ export declare function pandocToCarveAst(doc: PandocDoc | string): {
     ast: CarveAstDocument;
     warnings: string[];
     diagnostics: ConversionDiagnostic[];
+    report: MigrationReport;
 };

package/dist/index.js

@@ -3,6 +3,7 @@ import { normalizeCarveAst, parseCarveAst, toCarveAst } from './ast-json.js';
 import { convert } from './convert.js';
 import { parseExtensions } from './parse-options.js';
 import { pandocToCarve as reverse } from './reverse.js';
+import { migrationReport } from './diagnostics.js';
 export { PANDOC_API_VERSION } from './pandoc.js';
 /**
  * The engine's own serializer, when the installed engine has one.
@@ -16,6 +17,54 @@ export { PANDOC_API_VERSION } from './pandoc.js';
  * version does not have fails at link time, before any check could run.
  */
 const engineSerializer = carve.toAstJson;
+let rendererReadsInlineSubstitutions;
+function engineRenderTree(ast) {
+    rendererReadsInlineSubstitutions ??= (() => {
+        const parsed = carve.parse('{~/old/~>/new/~}');
+        const probe = (engineSerializer ? engineSerializer(parsed) : parsed);
+        const children = Array.isArray(probe['children']) ? probe['children'] : [];
+        const paragraph = children[0];
+        const substitution = Array.isArray(paragraph?.['children'])
+            ? paragraph['children'].find((node) => node?.type === 'substitution')
+            : undefined;
+        return Array.isArray(substitution?.['old']) && Array.isArray(substitution?.['new']);
+    })();
+    return rendererReadsInlineSubstitutions ? ast : legacySubstitutions(ast);
+}
+function legacySubstitutions(value) {
+    if (Array.isArray(value))
+        return value.map(legacySubstitutions);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const node = value;
+    if (node['type'] === 'substitution') {
+        const { old, new: replacement, ...rest } = node;
+        const legacyRest = Object.fromEntries(Object.entries(rest).map(([key, child]) => [key, legacySubstitutions(child)]));
+        return {
+            ...legacyRest,
+            // The published renderer cannot express inline structure in these
+            // fields. This lossy view exists only at that legacy API boundary;
+            // the returned and converted ASTs retain the arrays.
+            oldText: inlineText(old),
+            newText: inlineText(replacement),
+        };
+    }
+    return Object.fromEntries(Object.entries(node).map(([key, child]) => [key, legacySubstitutions(child)]));
+}
+function inlineText(value) {
+    if (!Array.isArray(value))
+        return '';
+    return value.map((node) => {
+        if (typeof node !== 'object' || node === null)
+            return '';
+        const inline = node;
+        if (inline['type'] === 'text')
+            return String(inline['value'] ?? '');
+        if (inline['type'] === 'soft_break' || inline['type'] === 'hard_break')
+            return '\n';
+        return inlineText(inline['children']);
+    }).join('');
+}
 /**
  * Parse Carve source to the serialized AST of PART 12 - the shape
  * `resources/ast-schema.json` pins, and the shape every engine's `--to-json`
@@ -77,9 +126,10 @@ export function pandocToCarve(doc) {
     const parsed = typeof doc === 'string' ? JSON.parse(doc) : doc;
     const { ast, warnings, diagnostics } = reverse(parsed);
     return {
-        carve: carve.renderCarve(ast),
+        carve: carve.renderCarve(engineRenderTree(ast)),
         warnings,
         diagnostics,
+        report: migrationReport(diagnostics),
     };
 }
 /**
@@ -90,5 +140,5 @@ export function pandocToCarve(doc) {
 export function pandocToCarveAst(doc) {
     const parsed = typeof doc === 'string' ? JSON.parse(doc) : doc;
     const { ast, warnings, diagnostics } = reverse(parsed, 'ast');
-    return { ast: toCarveAst(ast, engineSerializer), warnings, diagnostics };
+    return { ast: toCarveAst(ast, engineSerializer), warnings, diagnostics, report: migrationReport(diagnostics) };
 }

package/dist/reverse.js

@@ -346,7 +346,7 @@ function span(ctx, c) {
             if (parts.length === 2) {
                 const [oldC, newC] = parts.map((p) => p.c[1]);
                 return [
-                    { type: 'substitution', oldText: stringify(oldC), newText: stringify(newC) },
+                    { type: 'substitution', old: inlines(ctx, oldC), new: inlines(ctx, newC) },
                 ];
             }
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markup-carve/pandoc-carve",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Carve to Pandoc bridge: convert Carve markup to Pandoc's JSON AST and reach every pandoc output format (LaTeX, Typst, DOCX, PDF, ...)",
   "keywords": [
     "carve",
@@ -21,6 +21,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./node": {
+      "types": "./dist/includes.d.ts",
+      "import": "./dist/includes.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -38,7 +42,8 @@
   "scripts": {
     "build": "tsc",
     "examples:build": "npm run build && node scripts/build-examples.mjs",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "check:importer-fixtures": "node scripts/check-importer-fixtures.mjs",
+    "test": "npm run check:importer-fixtures && npm run build && node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -50,7 +55,7 @@
     "source": "https://github.com/markup-carve/pandoc-carve"
   },
   "dependencies": {
-    "@markup-carve/carve": "^0.1.5"
+    "@markup-carve/carve": "^0.1.7"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",