@cosyte/cli 0.0.5 → 0.1.0

package/dist/io-C9bSG2zF.d.ts

@@ -0,0 +1,381 @@
+import { Readable } from 'node:stream';
+
+/**
+ * The `cosyte` CLI **exit-code contract**: a designed, documented surface that CI pipelines and
+ * shell scripts branch on. `0` is the conventional success status; the codes from `65` up are the
+ * values the Unix `sysexits.h` header assigns to the constants named beside them; `1` and `2` are
+ * this CLI's own, because that header defines no constant for either.
+ *
+ * The load-bearing rule: **the CLI never prints a reassuring line and exits `0` on input it could not
+ * handle.** An undetectable format, an unreadable file, a parser that throws, or a consumer that
+ * closed the output stream before the output arrived each map to a distinct, stable non-zero code,
+ * never a silent success.
+ *
+ * | Code | Name       | Meaning                                                              |
+ * |------|------------|----------------------------------------------------------------------|
+ * | `0`  | `OK`       | success: the operation completed; `validate` found the input **valid** |
+ * | `1`  | `INVALID`  | operation-level failure: `validate` found the input **invalid**, or `redact` could not de-identify every locus (this CLI's own value; a real, expected CI signal: the tool worked, the operation did not complete) |
+ * | `2`  | `USAGE`    | usage error: unknown command, bad flag, missing argument (this CLI's own value) |
+ * | `65` | `DATAERR`  | data error: input could not be parsed / format not detected (EX_DATAERR) |
+ * | `66` | `NOINPUT`  | no input: the file does not exist or is unreadable (EX_NOINPUT)     |
+ * | `69` | `UNAVAILABLE` | a required capability is not wired for this input: e.g. `redact` on a format `@cosyte/deid` has no adapter for (EX_UNAVAILABLE) |
+ * | `70` | `SOFTWARE` | internal error: an unexpected exception, i.e. a bug (EX_SOFTWARE)   |
+ * | `74` | `IOERR`    | output error: the output stream closed before the CLI had finished writing to it, the shape a downstream consumer that exits early produces (EX_IOERR) |
+ *
+ * The load-bearing `validate` rule: a **parseable-but-invalid** message is exit `1`, never exit `0`.
+ * The CLI must never print a reassuring line and exit green on a bad message. Exit `65` is reserved
+ * for input that could not be **parsed** at all (a distinct signal from "parsed, but does not
+ * conform").
+ *
+ * @packageDocumentation
+ */
+/**
+ * The stable exit-code map. Adding a code is a documented, tested change to the CLI's contract;
+ * renaming or repurposing one is a breaking change.
+ *
+ * @example
+ * ```ts
+ * import { EXIT } from "@cosyte/cli";
+ *
+ * process.exitCode = EXIT.OK; // => 0
+ * ```
+ */
+declare const EXIT: {
+    /** Success: the operation completed; `validate` found the input **valid**. */
+    readonly OK: 0;
+    /** Operation-level failure: `validate` found the input **invalid** (parseable but non-conformant),
+     * or `redact` could not de-identify every locus: a real, expected CI signal that the tool worked
+     * and the operation did not complete. Never emitted for unparseable input (that is `DATAERR`). */
+    readonly INVALID: 1;
+    /** Usage error: unknown command, bad flag, missing argument. A value specific to this CLI, not a
+     * `sysexits.h` constant. */
+    readonly USAGE: 2;
+    /** Data error: input could not be parsed or its format could not be detected (`EX_DATAERR`). */
+    readonly DATAERR: 65;
+    /** No input: the named file does not exist or is unreadable (`EX_NOINPUT`). */
+    readonly NOINPUT: 66;
+    /** Unavailable: a required capability is not wired for this input (e.g. `redact` on a format
+     * `@cosyte/deid` has no adapter for, or with that optional library absent), a distinct non-zero
+     * signal that is never a fake success (`EX_UNAVAILABLE`). */
+    readonly UNAVAILABLE: 69;
+    /** Internal error: an unexpected exception (a bug), distinct from a handled bad input (`EX_SOFTWARE`). */
+    readonly SOFTWARE: 70;
+    /** Output error: the stream the CLI was writing to closed before the output had been delivered, so
+     * the consumer holds nothing or holds only part of the answer. The shape a downstream consumer
+     * that exits early produces (a pager quit, a `head` that has seen enough). A handled condition the
+     * consumer owns, never a defect in the CLI, so it is deliberately distinct from `SOFTWARE`
+     * (`EX_IOERR`). */
+    readonly IOERR: 74;
+};
+/**
+ * A value from {@link EXIT}: the exit code a CLI invocation resolves to.
+ */
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+/**
+ * The result of running a CLI invocation, as data: decoupled from `process` so the whole command
+ * tree is testable. The thin `bin` entry writes {@link RunResult.stdout} to `process.stdout`,
+ * {@link RunResult.stderr} to `process.stderr`, and exits with {@link RunResult.exit}.
+ *
+ * The two channels carry the CLI's PHI posture: **stdout is the data channel** (the
+ * user's explicit request: the parsed model), while **stderr is value-free**: codes and positions
+ * only, never an input value.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A fully-resolved CLI invocation.
+ *
+ * @example
+ * ```ts
+ * import { EXIT, type RunResult } from "@cosyte/cli";
+ *
+ * const r: RunResult = { stdout: "{}\n", stderr: "", exit: EXIT.OK };
+ * r.exit; // => 0
+ * ```
+ */
+interface RunResult {
+    /** The data channel: the parsed model or requested output. May contain the user's data by design. */
+    readonly stdout: string;
+    /** The diagnostic channel is **value-free**: codes, positions, file paths, format names only. */
+    readonly stderr: string;
+    /** The exit code the invocation resolves to. */
+    readonly exit: ExitCode;
+}
+
+/**
+ * The CLI's **value-free diagnostic channel**. Every error the CLI raises on its own behalf carries a
+ * stable `CLI_*` code, a fixed exit code, and a **PHI-safe** message built only from positional /
+ * structural context: a segment or field index, a byte offset, a file path, a format name, a warning
+ * code. **A diagnostic never echoes an input value** (a name, a DOB, an MRN, a result). This is the
+ * parsers' "warning = code + position, never a value" rule applied at the CLI edge.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable **CLI diagnostic code** registry: errors the CLI owns (routing, I/O, argument handling),
+ * distinct from the wrapped library's own warning/issue codes which are passed through unchanged.
+ * Each code is its own value (`key === value`) so the set survives `Object.values(...)`; renaming or
+ * removing one is a **breaking change** because scripts branch on the stderr text.
+ *
+ * @example
+ * ```ts
+ * import { CLI_CODES } from "@cosyte/cli";
+ *
+ * if (diagnostic.code === CLI_CODES.CLI_FORMAT_UNDETECTED) {
+ *   // ask the user for --format
+ * }
+ * ```
+ */
+declare const CLI_CODES: {
+    /** A required argument was missing or a flag was invalid. Exit `2`. */
+    readonly CLI_USAGE: "CLI_USAGE";
+    /** The named file does not exist or could not be read. Exit `66`. */
+    readonly CLI_NO_INPUT: "CLI_NO_INPUT";
+    /** The input was empty, no bytes to detect or parse. Exit `65`. */
+    readonly CLI_EMPTY_INPUT: "CLI_EMPTY_INPUT";
+    /** No format signature matched; the CLI will not guess. Names the candidates, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_UNDETECTED: "CLI_FORMAT_UNDETECTED";
+    /** More than one format signature matched; the CLI will not guess. Names the candidates, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_AMBIGUOUS: "CLI_FORMAT_AMBIGUOUS";
+    /** A recognised format whose parser does not support the requested operation (e.g. `parse` on a
+     * format wired only for `inspect`). Names the format + operation, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_UNSUPPORTED: "CLI_FORMAT_UNSUPPORTED";
+    /** The optional parser package for a recognised format is not installed. The six breadth parsers
+     * (dicom/x12/ccda/ncpdp/astm/mllp) are `optionalDependencies`: normally installed, but if
+     * one is absent the CLI degrades to this value-free signal rather than crashing. Exit `69`. */
+    readonly CLI_PARSER_UNAVAILABLE: "CLI_PARSER_UNAVAILABLE";
+    /** The wrapped parser rejected the input. Positional context only, never the offending bytes. Exit `65`. */
+    readonly CLI_PARSE_FAILED: "CLI_PARSE_FAILED";
+    /** The input is larger than the documented size limit the CLI reads in one invocation. Raised
+     * against the running byte count while the input is read, so the refusal always arrives before an
+     * allocation ceiling could. Names the limit, never the input. Exit `65`, never `70`. */
+    readonly CLI_INPUT_TOO_LARGE: "CLI_INPUT_TOO_LARGE";
+    /** The output stream could not be written: a consumer that closes the pipe ends the invocation
+     * here rather than as an unhandled platform error, whether it went away part way through a record
+     * stream or before a single-result write was delivered. Names no input, and never the platform's
+     * own error text. Exit `74`. */
+    readonly CLI_OUTPUT_WRITE_FAILED: "CLI_OUTPUT_WRITE_FAILED";
+    /** The BYO ConceptMap supplied to `map-codes` is not valid JSON or not a loadable FHIR ConceptMap.
+     * Names the stable terminology-loader code, never the map's bytes. Exit `65`. */
+    readonly CLI_MAP_INVALID: "CLI_MAP_INVALID";
+    /** A command whose ground-layer library does not cover the resolved format (e.g. `redact` on a
+     * format `@cosyte/deid` ships no adapter for). Never a fake success: a distinct, value-free
+     * "unavailable" signal. Exit `69`. */
+    readonly CLI_NOT_IMPLEMENTED: "CLI_NOT_IMPLEMENTED";
+    /** The delegated de-identifier reported that it could not handle every element of the input (a
+     * fail-closed `blocked` locus, or its own fatal). The run is **not** a de-identified copy, so no
+     * output is emitted: an operation-level failure, never a bug. Names loci and codes, never a
+     * value. Exit `1`. */
+    readonly CLI_DEID_INCOMPLETE: "CLI_DEID_INCOMPLETE";
+    /** An unexpected internal error (a bug). Exit `70`. */
+    readonly CLI_INTERNAL: "CLI_INTERNAL";
+};
+/**
+ * A value from {@link CLI_CODES}: the stable code carried by a {@link CliError}.
+ */
+type CliCode = (typeof CLI_CODES)[keyof typeof CLI_CODES];
+/**
+ * A typed, PHI-safe CLI error. Its {@link CliError.message | message} is **value-free by
+ * construction**: callers must build it from codes, indices, offsets, format names, and file paths,
+ * never from an input value. It carries the {@link ExitCode} the invocation resolves to.
+ *
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT } from "@cosyte/cli";
+ *
+ * throw new CliError(CLI_CODES.CLI_NO_INPUT, EXIT.NOINPUT, "cannot read the named file");
+ * ```
+ */
+declare class CliError extends Error {
+    /** The stable diagnostic code. */
+    readonly code: CliCode;
+    /** The exit code this error resolves the invocation to. */
+    readonly exit: ExitCode;
+    /**
+     * @param code - A stable {@link CliCode}.
+     * @param exit - The {@link ExitCode} to resolve to.
+     * @param message - A **value-free** explanation (positional/structural context only, never PHI).
+     */
+    constructor(code: CliCode, exit: ExitCode, message: string);
+}
+/**
+ * Render a {@link CliError} as a single value-free `stderr` line: `cosyte: <CODE>: <message>`. The
+ * message is already value-free by the {@link CliError} contract; this only prefixes the tool name
+ * and the code so scripts and humans can branch on a stable token.
+ *
+ * @param err - The CLI error to render.
+ * @returns The stderr line (no trailing newline).
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT, formatDiagnostic } from "@cosyte/cli";
+ *
+ * formatDiagnostic(new CliError(CLI_CODES.CLI_USAGE, EXIT.USAGE, "missing <file> argument"));
+ * // => "cosyte: CLI_USAGE: missing <file> argument"
+ * ```
+ */
+declare function formatDiagnostic(err: CliError): string;
+/**
+ * Resolve a {@link CliError} into a value-free {@link RunResult}: empty `stdout` (nothing reaches the
+ * data channel on an error), the rendered diagnostic on `stderr`, and the error's exit code. The
+ * single place the CLI turns an owned error into a result, so every command and the dispatcher render
+ * errors identically.
+ *
+ * @param err - The CLI error to resolve.
+ * @returns The value-free {@link RunResult}.
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT, errorResult } from "@cosyte/cli";
+ *
+ * errorResult(new CliError(CLI_CODES.CLI_USAGE, EXIT.USAGE, "missing <file>")).exit; // => 2
+ * ```
+ */
+declare function errorResult(err: CliError): RunResult;
+/**
+ * Coerce an unknown thrown value into a {@link CliError}. A {@link CliError} passes through; anything
+ * else becomes a `CLI_INTERNAL` / {@link EXIT.SOFTWARE} error whose message is a **fixed, value-free
+ * string**: the original message is deliberately discarded so a parser exception that embedded input
+ * bytes can never reach stderr.
+ *
+ * @param err - The caught value.
+ * @returns A {@link CliError} safe to render to stderr.
+ * @example
+ * ```ts
+ * import { toCliError } from "@cosyte/cli";
+ *
+ * toCliError(new Error("boom")).code; // => "CLI_INTERNAL"
+ * ```
+ */
+declare function toCliError(err: unknown): CliError;
+
+/**
+ * Input I/O for the CLI: read the bytes to operate on from a **file argument** or from **stdin**
+ * (`-`), with a value-free failure mode. The CLI never writes a temp file and never logs to a file;
+ * this module only *reads*.
+ *
+ * Reading comes in two shapes. The **whole-input** readers ({@link readFileBytes},
+ * {@link readStreamBytes}) hand a command one buffer, which is what a single-message command wants.
+ * The **chunk** readers ({@link fileChunks}, {@link streamChunks}) hand it an async stream of chunks,
+ * which is what a multi-record command wants: it can emit a record's output before the rest of the
+ * input has arrived, and the CLI's own size limit can be enforced against the **running total**
+ * rather than after an oversized input has already been assembled.
+ *
+ * The reader functions are injected into the command layer as {@link RunDeps} so the whole dispatch
+ * path is testable without touching `process`: the real `process.stdin` wiring lives in the thin
+ * `bin` entry, and so does the one function in {@link RunDeps} that writes rather than reads.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The injectable I/O side-effects the dispatcher needs. Kept tiny and pure-ish so tests drive the
+ * CLI end to end with in-memory fakes and no real filesystem, stdin or stdout.
+ *
+ * The two whole-input readers are required; the chunk readers and the output sink are **optional**,
+ * and a caller that omits them still gets identical output. They are the difference between reading
+ * a stream as it arrives and being handed one buffer: with them, a multi-record `parse` emits each
+ * record as it is produced and refuses an over-limit input while it is still arriving; without them,
+ * the same code path runs over a single chunk and returns its output on the result's `stdout` as
+ * before.
+ */
+interface RunDeps {
+    /** Read a file's bytes, or raise a `CLI_NO_INPUT` {@link CliError} if it cannot be read. */
+    readonly readFile: (path: string) => Promise<Uint8Array>;
+    /** Read all of stdin's bytes. */
+    readonly readStdin: () => Promise<Uint8Array>;
+    /** Optional: open a file as a stream of byte chunks (see {@link fileChunks}). */
+    readonly openFile?: (path: string) => AsyncIterable<Uint8Array>;
+    /** Optional: open stdin as a stream of byte chunks (see {@link streamChunks}). */
+    readonly openStdin?: () => AsyncIterable<Uint8Array>;
+    /**
+     * Optional: write one piece of the data channel **as it is produced**. When present, a multi-record
+     * `parse` writes each record's NDJSON line through here instead of accumulating them, and the
+     * returned result's `stdout` is empty because the output has already been delivered. May throw (a
+     * consumer that closed the pipe); the caller turns that into a value-free
+     * `CLI_OUTPUT_WRITE_FAILED`.
+     */
+    readonly writeStdout?: (chunk: string) => void;
+}
+/**
+ * Read a file into bytes, mapping any read failure to a **value-free** `CLI_NO_INPUT` /
+ * {@link EXIT.NOINPUT} error. The path is structural context (the user supplied it), so it may appear
+ * in the message; the file *contents* never do.
+ *
+ * A file whose size already exceeds `limit` is refused **before it is read**, with the value-free
+ * over-limit data error, so an oversized file is never allocated in the first place. The size is read
+ * from the **open descriptor** rather than from the path, so what is measured and what is read are the
+ * same file even if the path is replaced in between.
+ *
+ * @param path - The file path to read.
+ * @param limit - The maximum number of bytes to accept. Defaults to {@link MAX_INPUT_BYTES}.
+ * @returns The file bytes.
+ * @throws {CliError} `CLI_NO_INPUT` (exit `66`) when the file is missing, a directory, or unreadable;
+ *   `CLI_INPUT_TOO_LARGE` (exit `65`) when it is larger than `limit`.
+ * @example
+ * ```ts throws
+ * import { readFileBytes } from "@cosyte/cli";
+ *
+ * await readFileBytes("/no/such/file"); // throws CliError CLI_NO_INPUT
+ * ```
+ */
+declare function readFileBytes(path: string, limit?: number): Promise<Uint8Array>;
+/**
+ * Drain a readable stream (e.g. `process.stdin`) into a single byte buffer, refusing an over-limit
+ * stream against the **running total**: the read is abandoned the moment the accumulated size passes
+ * `limit`, so the bytes past it are never allocated and no platform allocation ceiling is ever
+ * reached.
+ *
+ * @param stream - The readable stream to drain.
+ * @param limit - The maximum number of bytes to accept. Defaults to {@link MAX_INPUT_BYTES}.
+ * @returns The concatenated bytes.
+ * @throws {CliError} `CLI_INPUT_TOO_LARGE` (exit `65`) as soon as the running total passes `limit`.
+ * @example
+ * ```ts
+ * import { Readable } from "node:stream";
+ * import { readStreamBytes } from "@cosyte/cli";
+ *
+ * const bytes = await readStreamBytes(Readable.from([Buffer.from("MSH|")]));
+ * bytes.length; // => 4
+ * ```
+ */
+declare function readStreamBytes(stream: Readable, limit?: number): Promise<Uint8Array>;
+/**
+ * Open a readable stream (e.g. `process.stdin`) as a stream of byte **chunks**, in arrival order.
+ * Unlike {@link readStreamBytes} this never concatenates: the consumer decides what to keep, which is
+ * what lets a multi-record command emit a record before the rest of the input has been read.
+ *
+ * @param stream - The readable stream to iterate.
+ * @returns An async iterable of the stream's chunks, string chunks encoded as UTF-8.
+ * @example
+ * ```ts
+ * import { Readable } from "node:stream";
+ * import { streamChunks } from "@cosyte/cli";
+ *
+ * const seen: number[] = [];
+ * for await (const c of streamChunks(Readable.from([Buffer.from("MS"), Buffer.from("H|")]))) {
+ *   seen.push(c.length);
+ * }
+ * seen.length; // => 2
+ * ```
+ */
+declare function streamChunks(stream: Readable): AsyncGenerator<Uint8Array>;
+/**
+ * Open a file as a stream of byte **chunks**, with the same value-free failure mode as
+ * {@link readFileBytes}: a missing, unreadable or non-file path is a `CLI_NO_INPUT` error, never a
+ * raw filesystem exception.
+ *
+ * @param path - The file path to read.
+ * @returns An async iterable of the file's chunks.
+ * @throws {CliError} `CLI_NO_INPUT` (exit `66`) when the file cannot be opened or read.
+ * @example
+ * ```ts throws
+ * import { fileChunks } from "@cosyte/cli";
+ *
+ * for await (const chunk of fileChunks("/no/such/file")) chunk.length; // throws CLI_NO_INPUT
+ * ```
+ */
+declare function fileChunks(path: string): AsyncGenerator<Uint8Array>;
+
+export { type CliCode as C, EXIT as E, type RunDeps as R, CliError as a, type RunResult as b, CLI_CODES as c, type ExitCode as d, errorResult as e, fileChunks as f, formatDiagnostic as g, readStreamBytes as h, readFileBytes as r, streamChunks as s, toCliError as t };