cesr-ts 0.6.0 → 0.8.0

package/README.md

@@ -25,16 +25,27 @@ const annotated = annotate(text, { domainHint: "txt", pretty: true });
 ## CLI usage
 
 ```bash
-npx cesr-annotate --in mystream.cesr --pretty
+npm exec --package cesr-ts -- tephra annotate --in mystream.cesr --pretty
+npm exec --package cesr-ts -- tephra validate --in mystream.cesr
+npm exec --package cesr-ts -- tephra bench --in mystream.cesr --iterations 20 --warmup 3
 ```
 
-## Deno CLI usage (from source)
+After global install:
 
 ```bash
-deno task cesr:annotate --in mystream.cesr --pretty
+tephra annotate --in mystream.cesr --pretty
+tephra validate --in mystream.cesr
+tephra bench --in mystream.cesr --iterations 20 --warmup 3
 ```
 
-## Benchmarking (from source)
+## Deno CLI usage (from repository root)
+
+```bash
+deno task tephra:annotate --in mystream.cesr --pretty
+deno task tephra:validate --in mystream.cesr
+```
+
+## Benchmarking (from repository root)
 
 Run standard parser benchmark baselines:
 
@@ -45,8 +56,8 @@ deno task bench:cesr
 Run a benchmark on an arbitrary stream:
 
 ```bash
-deno task bench:cesr:parser --in ../../samples/cesr-streams/CESR_1_0-oor-auth-vc.cesr
-cat ../../samples/cesr-streams/CESR_1_0-oor-auth-vc.cesr | deno task bench:cesr:parser --iterations 20 --warmup 3
+deno task tephra:bench --in ../../samples/cesr-streams/CESR_1_0-oor-auth-vc.cesr
+cat ../../samples/cesr-streams/CESR_1_0-oor-auth-vc.cesr | deno task tephra:bench --iterations 20 --warmup 3
 ```
 
 ## Using cesr-ts through tufa

package/esm/mod.js

@@ -1,3 +1,4 @@
+/** cesr-ts npm package root entrypoint. */
 import "./_dnt.polyfills.js";
 export * from "./src/index.js";
 export * from "./src/version.js";

package/esm/src/{annotate/cli.js → cli/commands/annotate.js}

@@ -1,5 +1,7 @@
-import { annotate } from "./annotator.js";
+import { annotate } from "../../annotate/annotator.js";
 const TEXT_DECODER = new TextDecoder();
+const ANNOTATE_USAGE = "Usage: tephra annotate [--in <path>] [--out <path>] [--qb2] [--pretty]";
+/** Parse `tephra annotate` command-line flags without performing IO. */
 function parseArgs(args) {
     const out = { qb2: false, pretty: false };
     for (let i = 0; i < args.length; i++) {
@@ -28,52 +30,21 @@ function parseArgs(args) {
             i++;
             continue;
         }
-        if (arg === "--help" || arg === "-h") {
-            throw new Error("Usage: cesr-annotate [--in <path>] [--out <path>] [--qb2] [--pretty]");
-        }
         throw new Error(`Unknown argument: ${arg}`);
     }
     return out;
 }
 /**
- * Read a full `ReadableStream` into one contiguous byte buffer.
+ * Execute `tephra annotate`.
  *
- * This is the shared browser/runtime-neutral helper used by annotate CLI
- * shims that expose stdin as a web stream instead of synchronous file APIs.
+ * The command preserves the old standalone annotation behavior while moving it
+ * under the package-level dispatcher.
  */
-export async function readAllReadable(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        while (true) {
-            const { value, done } = await reader.read();
-            if (done)
-                break;
-            if (value) {
-                chunks.push(value);
-                total += value.length;
-            }
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    const out = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        out.set(chunk, offset);
-        offset += chunk.length;
+export async function annotateCommand(args, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        await io.writeStdout(`${ANNOTATE_USAGE}\n`);
+        return 0;
     }
-    return out;
-}
-/**
- * Execute the standalone annotate CLI against the provided IO boundary.
- *
- * Error reporting is intentionally normalized here so runtime-specific entry
- * points can stay as thin bootstraps.
- */
-export async function annotateCli(args, io) {
     try {
         const options = parseArgs(args);
         const inputBytes = options.inPath
@@ -95,7 +66,7 @@ export async function annotateCli(args, io) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        await io.writeStderr(`cesr annotate error: ${message}\n`);
+        await io.writeStderr(`tephra annotate error: ${message}\n`);
         return 1;
     }
 }

package/esm/src/cli/commands/bench.js

@@ -0,0 +1,137 @@
+import { benchmarkCesrParser } from "../../bench/parser-benchmark.js";
+const BENCH_USAGE = "Usage: tephra bench [--in <path>] [--iterations <n>] [--warmup <n>] [--chunk-size <bytes>] [--framed] [--compat] [--allow-errors] [--json]";
+/** Parse non-negative integer flags used for sizing and warmup controls. */
+function parseNonNegativeInt(argName, value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${argName} must be a non-negative integer`);
+    }
+    return parsed;
+}
+/** Parse strictly positive integer flags used for measured iteration count. */
+function parsePositiveInt(argName, value) {
+    const parsed = parseNonNegativeInt(argName, value);
+    if (parsed <= 0) {
+        throw new Error(`${argName} must be greater than 0`);
+    }
+    return parsed;
+}
+/** Parse `tephra bench` command-line flags without performing IO. */
+function parseArgs(args) {
+    const out = {
+        iterations: 50,
+        warmupIterations: 5,
+        chunkSize: 0,
+        framed: false,
+        attachmentDispatchMode: "strict",
+        allowErrors: false,
+        json: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--in") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error("Missing value for --in");
+            out.inPath = next;
+            i++;
+            continue;
+        }
+        if (arg === "--iterations") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error("Missing value for --iterations");
+            out.iterations = parsePositiveInt("--iterations", next);
+            i++;
+            continue;
+        }
+        if (arg === "--warmup") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error("Missing value for --warmup");
+            out.warmupIterations = parseNonNegativeInt("--warmup", next);
+            i++;
+            continue;
+        }
+        if (arg === "--chunk-size") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error("Missing value for --chunk-size");
+            out.chunkSize = parseNonNegativeInt("--chunk-size", next);
+            i++;
+            continue;
+        }
+        if (arg === "--framed") {
+            out.framed = true;
+            continue;
+        }
+        if (arg === "--compat") {
+            out.attachmentDispatchMode = "compat";
+            continue;
+        }
+        if (arg === "--allow-errors") {
+            out.allowErrors = true;
+            continue;
+        }
+        if (arg === "--json") {
+            out.json = true;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return out;
+}
+/** Render human-readable benchmark output for terminal workflows. */
+function formatHumanReadable(sourceLabel, result) {
+    const chunkLabel = result.chunkSize === result.bytesPerIteration
+        ? "full stream"
+        : `${result.chunkSize} bytes`;
+    return [
+        "CESR parser benchmark",
+        `source: ${sourceLabel}`,
+        `iterations: ${result.iterations} (warmup: ${result.warmupIterations})`,
+        `input bytes/iteration: ${result.bytesPerIteration}`,
+        `chunk size: ${chunkLabel}`,
+        `frames/iteration: ${(result.totalFrames / result.iterations).toFixed(2)}`,
+        `errors/iteration: ${(result.totalErrors / result.iterations).toFixed(2)}`,
+        `avg iteration: ${result.avgIterationMs.toFixed(3)} ms`,
+        `throughput: ${result.throughputMiBPerSec.toFixed(3)} MiB/s`,
+        `frame rate: ${result.framesPerSec.toFixed(2)} frames/s`,
+    ].join("\n");
+}
+/** Execute `tephra bench` using the existing parser benchmark engine. */
+export async function benchCommand(args, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        await io.writeStdout(`${BENCH_USAGE}\n`);
+        return 0;
+    }
+    try {
+        const options = parseArgs(args);
+        const sourceLabel = options.inPath ? options.inPath : "stdin";
+        const inputBytes = options.inPath
+            ? await io.readFile(options.inPath)
+            : await io.readStdin();
+        const result = benchmarkCesrParser(inputBytes, {
+            iterations: options.iterations,
+            warmupIterations: options.warmupIterations,
+            chunkSize: options.chunkSize,
+            parserOptions: {
+                framed: options.framed,
+                attachmentDispatchMode: options.attachmentDispatchMode,
+            },
+            failOnParseError: !options.allowErrors,
+        });
+        if (options.json) {
+            await io.writeStdout(`${JSON.stringify({ source: sourceLabel, ...result })}\n`);
+            return 0;
+        }
+        const rendered = formatHumanReadable(sourceLabel, result);
+        await io.writeStdout(`${rendered}\n`);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await io.writeStderr(`tephra bench error: ${message}\n`);
+        return 1;
+    }
+}

package/esm/src/cli/commands/validate.js

@@ -0,0 +1,154 @@
+import { parseBytes } from "../../core/parser-engine.js";
+const VALIDATE_USAGE = "Usage: tephra validate [--in <path>] [--framed] [--compat] [--json]";
+/** Parse `tephra validate` command-line flags without performing IO. */
+function parseArgs(args) {
+    const out = {
+        framed: false,
+        attachmentDispatchMode: "strict",
+        json: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--in") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error("Missing value for --in");
+            out.inPath = next;
+            i++;
+            continue;
+        }
+        if (arg === "--framed") {
+            out.framed = true;
+            continue;
+        }
+        if (arg === "--compat") {
+            out.attachmentDispatchMode = "compat";
+            continue;
+        }
+        if (arg === "--json") {
+            out.json = true;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return out;
+}
+/**
+ * Convert parser errors into stable validation report entries.
+ *
+ * Parser error classes may carry useful location fields, but the CLI should not
+ * expose entire internal error objects as JSON. This function keeps the stable
+ * public fields and includes offset/context only when the parser supplied them.
+ */
+function describeError(error) {
+    const detail = {
+        name: error.name || "Error",
+        message: error.message,
+    };
+    const maybeParserError = error;
+    if (typeof maybeParserError.offset === "number") {
+        detail.offset = maybeParserError.offset;
+    }
+    if (typeof maybeParserError.context === "string") {
+        detail.context = maybeParserError.context;
+    }
+    return detail;
+}
+/**
+ * Count frames, attachment groups, and parser errors for one input stream.
+ *
+ * `tephra validate` is strict by default because a validation command should fail
+ * on ambiguous attachment dispatch. `--compat` intentionally relaxes that mode
+ * for streams that still rely on legacy mixed-major attachment behavior.
+ *
+ * Empty input is reported as a validation failure even though the parser has no
+ * malformed bytes to diagnose. A zero-frame stream is not useful evidence that a
+ * CESR payload is valid.
+ */
+function validateBytes(bytes, source, options) {
+    const events = parseBytes(bytes, {
+        framed: options.framed,
+        attachmentDispatchMode: options.attachmentDispatchMode,
+    });
+    const frames = events.filter((event) => event.type === "frame");
+    const errors = events
+        .filter((event) => event.type === "error")
+        .map((event) => describeError(event.error));
+    const attachmentGroupCount = frames.reduce((count, event) => count + event.frame.attachments.length, 0);
+    if (frames.length === 0 && errors.length === 0) {
+        errors.push({
+            name: "NoFramesError",
+            message: "No CESR frames parsed",
+        });
+    }
+    return {
+        ok: errors.length === 0,
+        source,
+        bytes: bytes.length,
+        frameCount: frames.length,
+        attachmentGroupCount,
+        errorCount: errors.length,
+        errors,
+    };
+}
+/** Render successful human-readable validation output. */
+function formatSuccess(report) {
+    return [
+        "CESR validation passed",
+        `source: ${report.source}`,
+        `bytes: ${report.bytes}`,
+        `frames: ${report.frameCount}`,
+        `attachment groups: ${report.attachmentGroupCount}`,
+    ].join("\n");
+}
+/** Render human-readable validation failure output with per-error details. */
+function formatFailure(report) {
+    const lines = [
+        "CESR validation failed",
+        `source: ${report.source}`,
+        `bytes: ${report.bytes}`,
+        `frames: ${report.frameCount}`,
+        `attachment groups: ${report.attachmentGroupCount}`,
+        `errors: ${report.errorCount}`,
+    ];
+    for (const error of report.errors) {
+        lines.push(`- ${error.name}: ${error.message}`);
+        if (error.offset !== undefined) {
+            lines.push(`  offset: ${error.offset}`);
+        }
+        if (error.context) {
+            lines.push(`  context: ${error.context}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Execute `tephra validate` against file input or stdin. */
+export async function validateCommand(args, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        await io.writeStdout(`${VALIDATE_USAGE}\n`);
+        return 0;
+    }
+    try {
+        const options = parseArgs(args);
+        const source = options.inPath ? options.inPath : "stdin";
+        const inputBytes = options.inPath
+            ? await io.readFile(options.inPath)
+            : await io.readStdin();
+        const report = validateBytes(inputBytes, source, options);
+        if (options.json) {
+            await io.writeStdout(`${JSON.stringify(report)}\n`);
+        }
+        else if (report.ok) {
+            await io.writeStdout(`${formatSuccess(report)}\n`);
+        }
+        else {
+            await io.writeStderr(`${formatFailure(report)}\n`);
+        }
+        return report.ok ? 0 : 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await io.writeStderr(`tephra validate error: ${message}\n`);
+        return 1;
+    }
+}

package/esm/src/cli/io-node.js

@@ -0,0 +1,45 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { stderr, stdin, stdout } from "node:process";
+/** Read Node stdin into one contiguous byte buffer for command execution. */
+async function readNodeStdin() {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stdin) {
+        const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+        chunks.push(bytes);
+        total += bytes.length;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** Write text to a Node stream and wait for completion or backpressure error. */
+async function writeNodeStream(stream, text) {
+    await new Promise((resolve, reject) => {
+        stream.write(text, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+/** Create the Node runtime IO adapter for the package-level `tephra` CLI. */
+export function createNodeCliIo() {
+    return {
+        readFile: async (path) => {
+            const data = await readFile(path);
+            return new Uint8Array(data);
+        },
+        writeTextFile: async (path, text) => {
+            await writeFile(path, text, "utf8");
+        },
+        readStdin: readNodeStdin,
+        writeStdout: (text) => writeNodeStream(stdout, text),
+        writeStderr: (text) => writeNodeStream(stderr, text),
+    };
+}

package/esm/src/cli/main.js

@@ -0,0 +1,42 @@
+import { annotateCommand } from "./commands/annotate.js";
+import { benchCommand } from "./commands/bench.js";
+import { validateCommand } from "./commands/validate.js";
+const COMMANDS = {
+    annotate: annotateCommand,
+    validate: validateCommand,
+    bench: benchCommand,
+};
+const TEPHRA_USAGE = [
+    "Usage: tephra <command> [options]",
+    "",
+    "Commands:",
+    "  annotate   Annotate a CESR stream",
+    "  validate   Validate a CESR stream",
+    "  bench      Benchmark CESR parser throughput",
+    "",
+    "Run `tephra <command> --help` for command-specific options.",
+].join("\n");
+/**
+ * Execute the package-level `tephra` CLI dispatcher.
+ *
+ * This function owns only command selection and top-level usage behavior. Each
+ * subcommand receives the already-selected argument tail plus a runtime-neutral
+ * IO adapter, so command behavior remains identical under Deno and Node.
+ */
+export async function tephraCli(args, io) {
+    const [command, ...commandArgs] = args;
+    if (command === "--help" || command === "-h") {
+        await io.writeStdout(`${TEPHRA_USAGE}\n`);
+        return 0;
+    }
+    if (!command) {
+        await io.writeStderr(`${TEPHRA_USAGE}\n`);
+        return 1;
+    }
+    const handler = COMMANDS[command];
+    if (!handler) {
+        await io.writeStderr(`Unknown tephra command: ${command}\n${TEPHRA_USAGE}\n`);
+        return 1;
+    }
+    return await handler(commandArgs, io);
+}

package/esm/src/cli/node.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * npm executable entrypoint for the package-level `tephra` CLI.
+ *
+ * The CESR npm build discovers this file by the marker text in this comment and
+ * prepends a Node shebang after DNT emits JavaScript. Keep this launcher thin so
+ * Deno-only APIs do not leak into the Node executable path.
+ */
+import "../../_dnt.polyfills.js";
+import { argv, exit } from "node:process";
+import { createNodeCliIo } from "./io-node.js";
+import { tephraCli } from "./main.js";
+const code = await tephraCli(argv.slice(2), createNodeCliIo());
+exit(code);

package/esm/src/cli/types.js

@@ -0,0 +1 @@
+export {};

package/esm/src/core/parser-frame-parser.js

@@ -242,6 +242,9 @@ export class FrameParser {
             };
         }
         catch (_error) {
+            // Non-native body groups wrap one Matter primitive. If Serder hydration
+            // fails, expose the primitive body bytes only; callers that inspect the
+            // fallback should not see the surrounding group counter envelope.
             const raw = matter.raw;
             return {
                 frame: {