@markup-carve/pandoc-carve 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * pandoc-carve CLI.
+ *
+ *   pandoc-carve doc.crv -t latex -o doc.tex
+ *   pandoc-carve doc.crv -t json            # emit Pandoc JSON, no pandoc needed
+ *   cat doc.crv | pandoc-carve - -t typst -- --toc
+ *
+ * Everything after `--` is passed through to pandoc verbatim.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * pandoc-carve CLI.
+ *
+ *   pandoc-carve doc.crv -t latex -o doc.tex
+ *   pandoc-carve doc.crv -t json            # emit Pandoc JSON, no pandoc needed
+ *   cat doc.crv | pandoc-carve - -t typst -- --toc
+ *
+ * Everything after `--` is passed through to pandoc verbatim.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { carveAstToPandoc, carveToPandoc } from './index.js';
+function usage(exitCode) {
+    const text = `Usage: pandoc-carve <input | -> [options] [-- pandoc-args...]
+
+Export (Carve -> anything pandoc writes):
+  -t, --to FORMAT    output format (default: json; any pandoc writer, or pdf)
+  -f carve-json      input is a SERIALIZED Carve AST (spec PART 12) rather than
+                     Carve source, as written by any engine's "carve --to-json"
+
+Import (anything pandoc reads -> Carve):
+  -f, --from FORMAT  input format (any pandoc reader, or json); output is Carve
+
+Common options:
+  -o, --output FILE  output file (default: stdout; required for -t pdf)
+  -s, --standalone   produce a standalone document (pandoc -s; export only)
+  --roundtrip        stamp export with markers so a later import restores
+                     attribute placement exactly (visible in writer output)
+  --no-list-table    keep ::: list-table blocks as the degraded div a processor
+                     without the extension renders (export; default converts
+                     them to real tables)
+  --no-citations     read [@key] as an @mention rather than a citation
+                     (export from Carve source; default reads citations)
+  --symbols FILE     JSON map resolving :name: symbols to text (export)
+  --pandoc PATH      pandoc executable (default: $PANDOC or "pandoc")
+  -h, --help         show this help
+`;
+    (exitCode === 0 ? process.stdout : process.stderr).write(text);
+    process.exit(exitCode);
+}
+function parseArgs(argv) {
+    const args = {
+        input: '',
+        to: 'json',
+        standalone: false,
+        roundtrip: false,
+        listTable: true,
+        citations: true,
+        pandocPath: process.env.PANDOC ?? 'pandoc',
+        passthrough: [],
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === '--') {
+            args.passthrough = argv.slice(i + 1);
+            break;
+        }
+        else if (a === '-h' || a === '--help') {
+            usage(0);
+        }
+        else if (a === '-t' || a === '--to') {
+            args.to = argv[++i] ?? usage(1);
+        }
+        else if (a === '-f' || a === '--from') {
+            args.from = argv[++i] ?? usage(1);
+        }
+        else if (a === '-o' || a === '--output') {
+            args.output = argv[++i] ?? usage(1);
+        }
+        else if (a === '-s' || a === '--standalone') {
+            args.standalone = true;
+        }
+        else if (a === '--roundtrip') {
+            args.roundtrip = true;
+        }
+        else if (a === '--no-list-table') {
+            args.listTable = false;
+        }
+        else if (a === '--no-citations') {
+            args.citations = false;
+        }
+        else if (a === '--symbols') {
+            args.symbolsFile = argv[++i] ?? usage(1);
+        }
+        else if (a === '--pandoc') {
+            args.pandocPath = argv[++i] ?? usage(1);
+        }
+        else if (!args.input) {
+            args.input = a;
+        }
+        else {
+            process.stderr.write(`pandoc-carve: unexpected argument: ${a}\n`);
+            usage(1);
+        }
+        i++;
+    }
+    if (!args.input)
+        usage(1);
+    return args;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // `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.
+    if (args.from && args.from !== 'carve' && args.from !== 'carve-json') {
+        return importToCarve(args);
+    }
+    const source = args.input === '-' ? readFileSync(0, 'utf8') : readFileSync(args.input, 'utf8');
+    const symbols = args.symbolsFile
+        ? JSON.parse(readFileSync(args.symbolsFile, 'utf8'))
+        : undefined;
+    const options = {
+        roundtrip: args.roundtrip,
+        listTable: args.listTable,
+        citations: args.citations,
+        symbols,
+    };
+    const { doc, warnings } = args.from === 'carve-json'
+        ? carveAstToPandoc(source, options)
+        : carveToPandoc(source, options);
+    for (const w of warnings) {
+        process.stderr.write(`pandoc-carve: degraded: ${w}\n`);
+    }
+    const json = JSON.stringify(doc);
+    if (args.to === 'json') {
+        if (args.output)
+            writeFileSync(args.output, json + '\n');
+        else
+            process.stdout.write(json + '\n');
+        return;
+    }
+    const { spawnSync } = await import('node:child_process');
+    const pandocArgs = ['-f', 'json'];
+    if (args.to === 'pdf') {
+        if (!args.output) {
+            process.stderr.write('pandoc-carve: -t pdf requires -o <file.pdf>\n');
+            process.exit(1);
+        }
+        // pandoc has no "pdf" writer name; the .pdf output path selects it.
+    }
+    else {
+        pandocArgs.push('-t', args.to);
+    }
+    if (args.standalone)
+        pandocArgs.push('-s');
+    if (args.output)
+        pandocArgs.push('-o', args.output);
+    pandocArgs.push(...args.passthrough);
+    const result = spawnSync(args.pandocPath, pandocArgs, {
+        input: json,
+        stdio: ['pipe', 'inherit', 'inherit'],
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === 'ENOENT') {
+            process.stderr.write(`pandoc-carve: pandoc executable not found ("${args.pandocPath}"). Install pandoc or use --pandoc PATH / $PANDOC. (-t json needs no pandoc.)\n`);
+            process.exit(2);
+        }
+        throw result.error;
+    }
+    process.exit(result.status ?? 0);
+}
+/** Reverse direction: pandoc-readable input -> Carve source. */
+async function importToCarve(args) {
+    let json;
+    if (args.from === 'json') {
+        json = args.input === '-' ? readFileSync(0, 'utf8') : readFileSync(args.input, 'utf8');
+    }
+    else {
+        const { spawnSync } = await import('node:child_process');
+        const pandocArgs = ['-f', args.from, '-t', 'json', ...args.passthrough];
+        const input = args.input === '-' ? readFileSync(0) : readFileSync(args.input);
+        const result = spawnSync(args.pandocPath, pandocArgs, {
+            input,
+            encoding: 'utf8',
+            maxBuffer: 256 * 1024 * 1024,
+        });
+        if (result.error && result.error.code === 'ENOENT') {
+            process.stderr.write(`pandoc-carve: pandoc executable not found ("${args.pandocPath}"). Install pandoc or use --pandoc PATH / $PANDOC. (-f json needs no pandoc.)\n`);
+            process.exit(2);
+        }
+        if (result.status !== 0) {
+            process.stderr.write(result.stderr ?? '');
+            process.exit(result.status ?? 1);
+        }
+        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`);
+    }
+    if (args.output)
+        writeFileSync(args.output, carve);
+    else
+        process.stdout.write(carve);
+}
+main().catch((err) => {
+    process.stderr.write(`pandoc-carve: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/convert.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Carve AST -> Pandoc JSON AST.
+ *
+ * Walks the SERIALIZED AST that PART 12 of the Carve spec defines - the shape
+ * `spec/resources/ast-schema.json` pins, as written by any engine's
+ * `--to-json` - and emits a Pandoc document (api-version 1.23.1). It is not the
+ * runtime tree of any particular implementation: `src/ast-json.ts` maps that on
+ * the way in, so every node type and field name switched on below is spec
+ * surface. Anything that cannot be mapped faithfully degrades to a classed
+ * Span/Div and reports a warning - nothing degrades silently.
+ */
+import type { CarveAstDocument } from './ast-json.js';
+import * as P from './pandoc.js';
+export interface ConvertResult {
+    doc: P.PandocDoc;
+    warnings: string[];
+}
+export interface ConvertOptions {
+    /**
+     * Stamp attr-wrapper Divs with a `carve-block` key-value marker so the
+     * reverse direction can restore the attrs onto the inner block. Off by
+     * default: the marker would otherwise leak into pandoc writer output
+     * (e.g. `carve-block="paragraph"` on an HTML div).
+     */
+    roundtrip?: boolean;
+    /**
+     * Resolve `:name:` symbols to replacement text (mirrors the renderer's
+     * symbols map). Unresolved symbols degrade to a classed Span + warning.
+     */
+    symbols?: Record<string, string>;
+    /**
+     * Convert `::: list-table` blocks to real Pandoc tables (the listTable
+     * extension's semantics) instead of the degraded Div-of-lists form.
+     * Pandoc cells hold full blocks, so nothing is flattened.
+     *
+     * ON by default, because the REVERSE direction writes a list-table
+     * unprompted: `pandocToCarve` reaches for it whenever a pandoc table has a
+     * cell holding blocks or row-head columns, which a pipe table cannot spell.
+     * With this off, that table came back as a `Div` of nested lists - the
+     * bridge lost, on the way in, a construct it had itself chosen on the way
+     * out. Set it false to get the literal `Div` a processor without the
+     * extension enabled would render.
+     */
+    listTable?: boolean;
+    /**
+     * Parse Carve source to the exchange AST's `children`, for the one place a
+     * conversion has to read source rather than a tree: block content in
+     * metadata (`abstract: |`), whose value is Carve markup inside a YAML
+     * string.
+     *
+     * Supplied as a hook rather than imported, because this module converts a
+     * SERIALIZED AST from any engine and has no engine of its own. Without it
+     * a block scalar is reported and skipped, which is what it always did.
+     */
+    parseBlocks?: (source: string) => unknown[];
+}
+export declare function convert(ast: CarveAstDocument, options?: ConvertOptions): ConvertResult;