@markup-carve/pandoc-carve 0.1.2 → 0.1.4

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:
 
@@ -150,6 +160,35 @@ The complete node-by-node contract lives in the test goldens. Worked
 input/output pairs in both directions - including how interactive constructs
 degrade for print formats - are in [`examples/`](examples/README.md).
 
+## Dangerous URL schemes are blanked
+
+A link or image destination whose scheme Carve's spec denies (PART 9 §25 -
+`javascript:`, `vbscript:`, `data:`, `file:`, and the OS protocol-handler class
+such as `ms-msdt:`, `search-ms:`, `shell:`, `vscode:` and `jar:`) leaves this
+bridge as an **empty target**, and an `unsafe-url-scheme` diagnostic is emitted
+naming the scheme and the destination that was refused.
+
+Carve's own HTML, Markdown and ANSI writers all blank it, and the clause binds
+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
+`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
+Unicode whitespace before it reads a scheme, so `<U+202F>javascript:` and
+`java<DEL>script:` are caught along with the plain spelling.
+
+Nothing else is touched. An `https:`, `mailto:`, `tel:`, `ftp:`, relative or
+fragment destination reaches pandoc exactly as written, and emits no
+diagnostic.
+
+> [!NOTE]
+> This covers link and image **destinations**. An `{onclick=…}`, `{style=…}` or
+> `{srcdoc=…}` attribute, which Carve's HTML writer also refuses, still reaches
+> pandoc - see [#163](https://github.com/markup-carve/pandoc-carve/issues/163).
+
 ## Why a bridge, not a pandoc reader?
 
 A native `Text.Pandoc.Readers.Carve` upstream would be a fourth full Carve
@@ -197,13 +236,14 @@ 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.
+  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
@@ -249,7 +289,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
@@ -266,11 +308,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 - the pipe
-  table marks them on the cells (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
@@ -320,7 +369,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/attribute-sanitize.d.ts

@@ -0,0 +1,6 @@
+/** Attribute names Carve never emits, regardless of value. */
+export declare const DANGEROUS_ATTR_NAMES: readonly string[];
+/** Mirror of Carve's always-on PART 9 §25 attribute-name policy. */
+export declare function isDangerousAttrName(name: string): boolean;
+/** Mirror of Carve's always-on PART 9 §25 attribute-value policy. */
+export declare function renderedAttrValue(name: string, value: string): string;

package/dist/attribute-sanitize.js

@@ -0,0 +1,55 @@
+import { DANGEROUS_URL_SCHEMES, SCHEME_PROBE_STRIP_RE } from './url-scheme.js';
+/** Attribute names Carve never emits, regardless of value. */
+export const DANGEROUS_ATTR_NAMES = ['srcdoc', 'formaction'];
+const DANGEROUS_NAMES = new Set(DANGEROUS_ATTR_NAMES);
+const DANGEROUS_VALUE_SCHEMES = new Set(DANGEROUS_URL_SCHEMES);
+const ASCII_WHITESPACE = '\\t\\n\\f\\r ';
+const URL_LIST_SEPARATORS = new Map([
+    ['srcset', new RegExp(`[,${ASCII_WHITESPACE}]+`)],
+    ['imagesrcset', new RegExp(`[,${ASCII_WHITESPACE}]+`)],
+    ['ping', new RegExp(`[${ASCII_WHITESPACE}]+`)],
+    ['attributionsrc', new RegExp(`[${ASCII_WHITESPACE}]+`)],
+]);
+/** Mirror of Carve's always-on PART 9 §25 attribute-name policy. */
+export function isDangerousAttrName(name) {
+    const normalized = name.toLowerCase();
+    return normalized.startsWith('on') || DANGEROUS_NAMES.has(normalized);
+}
+function hasDeniedValueScheme(value) {
+    const colon = value.indexOf(':');
+    if (colon === -1)
+        return false;
+    const scheme = value.slice(0, colon).replace(SCHEME_PROBE_STRIP_RE, '').toLowerCase();
+    return DANGEROUS_VALUE_SCHEMES.has(scheme);
+}
+function decodeCssEscapes(value) {
+    return value.replace(/\\([0-9a-f]{1,6}\s?|[\s\S])/gi, (_match, escape) => {
+        if (!/^[0-9a-f]/i.test(escape))
+            return escape;
+        const codePoint = Number.parseInt(escape.trim(), 16);
+        return Number.isFinite(codePoint) && codePoint <= 0x10ffff
+            ? String.fromCodePoint(codePoint)
+            : '';
+    });
+}
+function hasDangerousCss(value) {
+    const compact = decodeCssEscapes(value.replace(/\/\*[\s\S]*?\*\//g, ''))
+        .toLowerCase()
+        .replace(/\s+/g, '');
+    return compact.includes('expression(')
+        || compact.includes('url(')
+        || compact.includes('@import')
+        || compact.includes('behavior:')
+        || compact.includes('-moz-binding');
+}
+/** Mirror of Carve's always-on PART 9 §25 attribute-value policy. */
+export function renderedAttrValue(name, value) {
+    if (hasDeniedValueScheme(value))
+        return '';
+    const separator = URL_LIST_SEPARATORS.get(name.toLowerCase());
+    if (separator && value.split(separator).some((part) => part !== '' && hasDeniedValueScheme(part)))
+        return '';
+    if (name.toLowerCase() === 'style' && hasDangerousCss(value))
+        return '';
+    return value;
+}

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 {
     /**