@markup-carve/pandoc-carve 0.1.0 → 0.1.3

package/README.md

@@ -62,16 +62,21 @@ 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.
+`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.
 
 ## API
 
 ```js
 import { carveToPandoc, carveToPandocJson } from '@markup-carve/pandoc-carve';
 
-const { doc, warnings } = carveToPandoc('Hello /world/!');
+const { doc, warnings, diagnostics } = 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? }]
 
 const json = carveToPandocJson('Hello /world/!'); // stringified doc
 ```
@@ -85,7 +90,7 @@ whether it arrives as an object or as JSON text:
 import { carveAstToPandoc, carveToCarveAst } from '@markup-carve/pandoc-carve';
 
 // A tree from carve-rs, carve-php, carve-go ... or `carve doc.crv --to-json`
-const { doc, warnings } = carveAstToPandoc(serializedAstJson);
+const { doc, warnings, diagnostics } = carveAstToPandoc(serializedAstJson);
 
 // The same exchange format, produced from source here
 const ast = carveToCarveAst('Hello /world/!');
@@ -98,7 +103,7 @@ serializer), so output formatting carries fmt's guarantees:
 ```js
 import { pandocToCarve, pandocToCarveAst } from '@markup-carve/pandoc-carve';
 
-const { carve, warnings } = pandocToCarve(pandocJsonString);
+const { carve, warnings, diagnostics } = pandocToCarve(pandocJsonString);
 
 // Preserve structured fields that Carve 0.1 source cannot spell, including
 // Pandoc's optional short figure/table caption.
@@ -109,8 +114,13 @@ Round-trips are tested as a hard gate: `carve -> pandoc AST -> carve` must
 render byte-identical HTML to the original source across the test corpus.
 For exact restoration of attribute placement (`{.lead}` on a paragraph or
 list), export with `carveToPandoc(src, { roundtrip: true })` or the CLI's
-`--roundtrip` flag - it stamps wrapper divs with a `carve-block` marker the
-importer uses, at the cost of that marker being visible in writer output.
+`--roundtrip` flag. In addition to the existing `carve-block` attribute marker,
+this preserves comments, typed citation fields, and unknown future Carve nodes
+with a versioned private Span/Div envelope. The native citation and readable
+unknown-node fallback remain usable by Pandoc. The marker may be visible in
+writer output and exact preservation is guaranteed only through Pandoc JSON.
+The complete format, safety checks, available source information, and filter
+semantics are documented in [the provenance envelope](docs/roundtrip-provenance.md).
 
 Pipe the JSON to pandoc yourself:
 
@@ -144,7 +154,7 @@ node -e "import('@markup-carve/pandoc-carve').then(m => process.stdout.write(m.c
 | `::: \|` line blocks (verse) | LineBlock, one entry per line, an empty entry per stanza break |
 | Ordered markers `1.` / `1)` / `a.` / `iv.` | OrderedList with the matching style and delimiter. Pandoc's example list `(@)` and its `(1)` marker have no Carve form and are reported |
 | A no-break space the parser resolved (`\ `) | U+00A0 (the engines publish a private-use sentinel for it) |
-| A reference link or image nothing defines (`[r][]`) | the literal source as text, which is what Carve renders, plus a warning naming the label - as an unresolved footnote already did |
+| A reference link, image or footnote nothing defines (`[r][]`, `[^f]`) | the literal source as text, which is what Carve renders, plus a warning naming the label |
 
 The complete node-by-node contract lives in the test goldens. Worked
 input/output pairs in both directions - including how interactive constructs
@@ -197,20 +207,23 @@ a processor with neither extension enabled would render.
   against `resources/ast-schema.json` can still be incoherent - the bridge
   checks it itself rather than trusting a green validator.
 - A pandoc table with block content in a cell (a list, two paragraphs, a code
-  block) is imported as `::: list-table` rather than a pipe table. PART 9 §16's
-  pipe-table cell holds inlines, so there is no pipe form for it, and the
-  extension's cells are list items that hold full blocks. Structure is
-  preserved; three things the extension does not spell are reported instead -
-  per-column alignment, a foot, and a body group's intermediate header rows.
-  It converts back to the pandoc table by default; `listTable: false` returns
-  the degraded div instead.
-- A pandoc table with ROW-HEAD COLUMNS takes the same route on the source path,
-  because `header-cols=N` is exactly pandoc's `RowHeadColumns` and a pipe table
-  cannot say it. Only when every body group agrees on the count: `header-cols`
-  is one number for the whole table, so a table whose bodies differ keeps the
-  pipe form rather than come back with row headers ADDED to the rows that had
-  none. The AST path keeps the plain table, where `rowGroups` carries the whole
-  partition and nothing has to be traded for it.
+  block) is imported as `::: list-table` rather than a pipe table, and that is
+  now the ONLY reason a table leaves the pipe form. PART 9 §16's pipe-table cell
+  holds inlines, so there is no pipe form for it, and the extension's cells are
+  list items that hold full blocks. Structure is preserved; what the extension
+  cannot spell is reported instead - a body group's attributes, a body boundary
+  no header row marks, and body groups that disagree on their row-head column
+  count. It converts back to the pandoc table by default; `listTable: false`
+  returns the degraded div instead.
+- A pandoc table with ROW-HEAD COLUMNS stays a pipe table. `RowHeadColumns` says
+  the leading N cells of every body row are row headers, and a pipe table says
+  that per cell: `|= Mercury | 4,879.4 |` is a `<th scope="row">`. Marking the
+  cells needs no extension and round-trips, because the export direction derives
+  the count back from the leading run.
+- On the way out, one TableBody per RUN of body rows that agree on that leading
+  run. Pandoc's `RowHeadColumns` is a count on a body and a `Table` holds a list
+  of bodies, so rows that disagree are simply different bodies. A table whose
+  body rows all agree emits exactly one body, as before.
 - Pandoc `SmallCaps` has no Carve node and is not getting one: it imports as a
   `[text]{.smallcaps}` span, with a warning saying so. The span is not a dead
   end, though - the export direction reads that class back as `SmallCaps`, the
@@ -247,7 +260,9 @@ a processor with neither extension enabled would render.
   those two fields on the way back - the label table is section 4.2's, it lives
   in the engine, and a second copy here would drift. The locator TEXT round-
   trips byte for byte, so re-parsing the emitted source with the citations
-  extension restores the typed pair. A group whose items mix `AuthorInText` and
+  extension restores the typed pair. With `roundtrip: true`, the private
+  provenance wrapper retains the original typed fields directly while its
+  enclosed native `Cite` remains available to citeproc. A group whose items mix `AuthorInText` and
   `NormalCitation` cannot be spelled in Carve (the integral `+` is a property of
   the whole cluster) and is imported as integral with a warning.
 - Pandoc keeps its bibliography in document metadata, not in the AST, so
@@ -264,11 +279,18 @@ a processor with neither extension enabled would render.
   lists, lists of maps, scalars, booleans - round-trips too.
 - A `rowGroups` partition (a foot, several body groups, a body's own header
   rows or row-head columns) survives into the exchange AST, so
-  `pandocToCarveAst` hands it on whole - but PART 9 section 16's pipe table
-  spells only a leading run of header rows, so `pandocToCarve` flattens the
-  rest into body rows and says so. Row-head columns are the exception - they
-  have a list-table spelling and take it (above). Use the AST entry point when
-  a foot or a second body group has to survive.
+  `pandocToCarveAst` hands it on whole. `pandocToCarve` spells most of it too: a
+  pipe table states its head and foot row counts on its attribute line
+  (`{header-rows=2 footer-rows=1}`) and marks its row headers on the cells, so
+  what flattens into body rows is a second body group and a body's own
+  intermediate header rows and attributes - reported, not dropped quietly. Use
+  the AST entry point when a second body group has to survive.
+- Stating the foot states the whole partition, and a stated partition is ONE
+  body. A body carries one `RowHeadColumns`, so when the body rows disagree on
+  how many leading cells are row headers, a table with a foot cannot keep them:
+  the reader takes a count every row agrees on, and the disagreement is reported
+  from both directions. Without a foot the reader splits a body at every change
+  and every run survives.
 - A marker on a HEAD cell (`|=> Name |`) is the column's alignment and becomes
   pandoc's `ColSpec`; a marker on a BODY cell (`|> 12 |`) aligns that cell alone
   and becomes the cell's own `Alignment`. The two are not interchangeable: a
@@ -318,7 +340,3 @@ 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.
-
-## License
-
-MIT

package/dist/cli.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { carveAstToPandoc, carveToPandoc } from './index.js';
+import { hasLoss } from './diagnostics.js';
 function usage(exitCode) {
     const text = `Usage: pandoc-carve <input | -> [options] [-- pandoc-args...]
 
@@ -31,6 +32,9 @@ Common options:
                      them to real tables)
   --no-citations     read [@key] as an @mention rather than a citation
                      (export from Carve source; default reads citations)
+  --diagnostics FILE write structured diagnostics as JSON (use - for stderr;
+                     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)
   --pandoc PATH      pandoc executable (default: $PANDOC or "pandoc")
   -h, --help         show this help
@@ -46,6 +50,7 @@ function parseArgs(argv) {
         roundtrip: false,
         listTable: true,
         citations: true,
+        failOnLoss: false,
         pandocPath: process.env.PANDOC ?? 'pandoc',
         passthrough: [],
     };
@@ -83,6 +88,12 @@ function parseArgs(argv) {
         else if (a === '--symbols') {
             args.symbolsFile = argv[++i] ?? usage(1);
         }
+        else if (a === '--diagnostics') {
+            args.diagnosticsFile = argv[++i] ?? usage(1);
+        }
+        else if (a === '--fail-on-loss') {
+            args.failOnLoss = true;
+        }
         else if (a === '--pandoc') {
             args.pandocPath = argv[++i] ?? usage(1);
         }
@@ -117,18 +128,18 @@ async function main() {
         citations: args.citations,
         symbols,
     };
-    const { doc, warnings } = args.from === 'carve-json'
+    const { doc, warnings, diagnostics } = args.from === 'carve-json'
         ? carveAstToPandoc(source, options)
         : carveToPandoc(source, options);
-    for (const w of warnings) {
-        process.stderr.write(`pandoc-carve: degraded: ${w}\n`);
-    }
+    report(args, warnings, diagnostics);
     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))
+            process.exitCode = 3;
         return;
     }
     const { spawnSync } = await import('node:child_process');
@@ -161,7 +172,7 @@ async function main() {
         }
         throw result.error;
     }
-    process.exit(result.status ?? 0);
+    process.exit(result.status || (args.failOnLoss && hasLoss(diagnostics) ? 3 : 0));
 }
 /** Reverse direction: pandoc-readable input -> Carve source. */
 async function importToCarve(args) {
@@ -189,14 +200,26 @@ async function importToCarve(args) {
         json = result.stdout;
     }
     const { pandocToCarve } = await import('./index.js');
-    const { carve, warnings } = pandocToCarve(json);
-    for (const w of warnings) {
-        process.stderr.write(`pandoc-carve: degraded: ${w}\n`);
-    }
+    const { carve, warnings, diagnostics } = pandocToCarve(json);
+    report(args, warnings, diagnostics);
     if (args.output)
         writeFileSync(args.output, carve);
     else
         process.stdout.write(carve);
+    if (args.failOnLoss && hasLoss(diagnostics))
+        process.exitCode = 3;
+}
+function report(args, warnings, diagnostics) {
+    if (args.diagnosticsFile !== undefined) {
+        const json = JSON.stringify(diagnostics, null, 2) + '\n';
+        if (args.diagnosticsFile === '-')
+            process.stderr.write(json);
+        else
+            writeFileSync(args.diagnosticsFile, json);
+        return;
+    }
+    for (const warning of warnings)
+        process.stderr.write(`pandoc-carve: degraded: ${warning}\n`);
 }
 main().catch((err) => {
     process.stderr.write(`pandoc-carve: ${err instanceof Error ? err.message : String(err)}\n`);

package/dist/convert.d.ts

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