icore 1.0.14 → 1.0.16

package/dist/{options.js → options/parser.js}

@@ -1,10 +1,9 @@
 "use strict";
 /**
- * The option schema module validates raw option values against declarative
+ * The option parser module validates raw option values against declarative
  * primitive option contracts.
  *
  * Allowed here:
- * - defining string, boolean, and number option contracts;
  * - applying and validating default values;
  * - producing typed option values and user-provided metadata;
  *
@@ -12,18 +11,10 @@
  * application-specific validation rules.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeOptionsSchema = mergeOptionsSchema;
 exports.parseOptions = parseOptions;
 exports.parseOptionsDetailed = parseOptionsDetailed;
-const errors_1 = require("./errors");
-/**
- * Merges option schemas while preserving literal option definition types.
- *
- * Later schemas override earlier schemas with the same option name.
- */
-function mergeOptionsSchema(schema, ...schemas) {
-    return Object.assign({}, schema, ...schemas);
-}
+exports.parseOptionsSubsetDetailed = parseOptionsSubsetDetailed;
+const icore_error_1 = require("../errors/icore-error");
 /**
  * Validates raw option values against a declarative option schema.
  */
@@ -67,6 +58,25 @@ function parseOptionsDetailed(schema, values) {
         provided: provided
     };
 }
+/**
+ * Validates only raw option values known by the given schema and leaves the
+ * remaining raw options untouched.
+ */
+function parseOptionsSubsetDetailed(schema, values) {
+    const subsetValues = {};
+    const rest = {};
+    for (const [name, value] of Object.entries(values)) {
+        if (Object.hasOwn(schema, name)) {
+            subsetValues[name] = value;
+            continue;
+        }
+        rest[name] = value;
+    }
+    return {
+        ...parseOptionsDetailed(schema, subsetValues),
+        rest
+    };
+}
 function parseOptionValue(name, definition, value) {
     if (definition.type === 'string') {
         return parseStringOption(name, definition, value);
@@ -189,13 +199,13 @@ function assertChoice(name, choices, value, source = 'value') {
     throw createInvalidOptionChoiceError(name, choices, value, message);
 }
 function createUnexpectedArgumentError(name) {
-    return new errors_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
+    return new icore_error_1.IcoreError('UNEXPECTED_ARGUMENT', `Unexpected argument '--${name}'`, {
         argument: `--${name}`,
         option: name
     });
 }
 function createExpectedRequiredArgumentError(name) {
-    return new errors_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
+    return new icore_error_1.IcoreError('EXPECTED_REQUIRED_ARGUMENT', `Expected required argument '--${name}'`, {
         argument: `--${name}`,
         option: name
     });
@@ -213,14 +223,14 @@ function createExpectedDefaultError(name, expected, value) {
     });
 }
 function createInvalidOptionTypeError(name, message, details) {
-    return new errors_1.IcoreError('INVALID_OPTION_TYPE', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_TYPE', message, {
         argument: `--${name}`,
         option: name,
         ...details
     });
 }
 function createInvalidOptionChoiceError(name, choices, value, message) {
-    return new errors_1.IcoreError('INVALID_OPTION_CHOICE', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_CHOICE', message, {
         argument: `--${name}`,
         option: name,
         choices: [...choices],
@@ -228,7 +238,7 @@ function createInvalidOptionChoiceError(name, choices, value, message) {
     });
 }
 function createInvalidOptionDefaultError(name, message, details) {
-    return new errors_1.IcoreError('INVALID_OPTION_DEFAULT', message, {
+    return new icore_error_1.IcoreError('INVALID_OPTION_DEFAULT', message, {
         argument: `--${name}`,
         option: name,
         ...details

package/dist/{options.d.ts → options/schema.d.ts}

@@ -1,18 +1,21 @@
 /**
- * The option schema module validates raw option values against declarative
- * primitive option contracts.
+ * The option schema module defines declarative primitive option contracts and
+ * their inferred TypeScript result types.
  *
  * Allowed here:
- * - defining string, boolean, and number option contracts;
- * - applying and validating default values;
- * - producing typed option values and user-provided metadata;
+ * - string, boolean, and number option contracts;
+ * - schema merge mechanics;
+ * - inferred parsed option and provided-option types;
  *
- * This file must not contain argv tokenization, command resolution, or
- * application-specific validation rules.
+ * This file must not contain argv tokenization, value validation, or command
+ * resolution.
  */
 type OptionBase<TType extends string, TValue> = {
+    /** Primitive option kind. */
     type: TType;
+    /** One-letter short alias. */
     alias?: string;
+    /** Requires an explicit value. */
     required?: boolean;
     default?: TValue;
 };
@@ -30,6 +33,7 @@ export type RawOptionValue = string | boolean;
  * is declared with `as const`.
  */
 export type StringOption<TChoices extends readonly string[] = readonly string[]> = OptionBase<'string', TChoices[number] | string> & {
+    /** Allowed string values. */
     choices?: TChoices;
 };
 /**
@@ -39,6 +43,7 @@ export type StringOption<TChoices extends readonly string[] = readonly string[]>
  * syntax is enforced.
  */
 export type BooleanOption = OptionBase<'boolean', boolean> & {
+    /** Restricts boolean syntax. */
     syntax?: 'flag';
 };
 /**
@@ -48,9 +53,13 @@ export type BooleanOption = OptionBase<'boolean', boolean> & {
  * bounds.
  */
 export type NumberOption<TChoices extends readonly number[] = readonly number[]> = OptionBase<'number', TChoices[number] | number> & {
+    /** Allowed numeric values. */
     choices?: TChoices;
+    /** Requires a whole number. */
     integer?: boolean;
+    /** Inclusive lower bound. */
     min?: number;
+    /** Inclusive upper bound. */
     max?: number;
 };
 /**
@@ -109,26 +118,10 @@ export type InferOptions<TSchema extends OptionsSchema> = {
 export type InferProvidedOptions<TSchema extends OptionsSchema> = {
     [TName in keyof TSchema]: boolean;
 };
-/**
- * Detailed option parsing result with values and user-provided metadata.
- */
-export type ParseOptionsResult<TSchema extends OptionsSchema> = {
-    options: InferOptions<TSchema>;
-    provided: InferProvidedOptions<TSchema>;
-};
 /**
  * Merges option schemas while preserving literal option definition types.
  *
  * Later schemas override earlier schemas with the same option name.
  */
 export declare function mergeOptionsSchema<const TSchema extends OptionsSchema, const TSchemas extends readonly OptionsSchema[]>(schema: TSchema, ...schemas: TSchemas): MergeOptionsSchemas<readonly [TSchema, ...TSchemas]>;
-/**
- * Validates raw option values against a declarative option schema.
- */
-export declare function parseOptions<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): InferOptions<TSchema>;
-/**
- * Validates raw option values and returns parsed values with user-provided
- * metadata.
- */
-export declare function parseOptionsDetailed<const TSchema extends OptionsSchema>(schema: TSchema, values: Record<string, RawOptionValue>): ParseOptionsResult<TSchema>;
 export {};

package/dist/options/schema.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * The option schema module defines declarative primitive option contracts and
+ * their inferred TypeScript result types.
+ *
+ * Allowed here:
+ * - string, boolean, and number option contracts;
+ * - schema merge mechanics;
+ * - inferred parsed option and provided-option types;
+ *
+ * This file must not contain argv tokenization, value validation, or command
+ * resolution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeOptionsSchema = mergeOptionsSchema;
+/**
+ * Merges option schemas while preserving literal option definition types.
+ *
+ * Later schemas override earlier schemas with the same option name.
+ */
+function mergeOptionsSchema(schema, ...schemas) {
+    return Object.assign({}, schema, ...schemas);
+}

package/dist/output/facade.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The output facade exposes semantic stdout and stderr write operations.
+ *
+ * Allowed here:
+ * - creating stdout/stderr writer channels;
+ * - delegating `write` to stdout and `error` to stderr;
+ *
+ * This file must not contain command semantics, rendering rules, or
+ * application-specific diagnostics.
+ */
+import type { BackpressureTextSink, TextWriter } from './text-writer';
+export type Output = {
+    /** Writes regular output. */
+    write(chunk: string): unknown | Promise<unknown>;
+    /** Writes diagnostic output. */
+    error(chunk: string): unknown | Promise<unknown>;
+    stdout: TextWriter;
+    stderr: TextWriter;
+};
+export type OutputOptions = {
+    stdout?: BackpressureTextSink;
+    stderr?: BackpressureTextSink;
+};
+/**
+ * Creates semantic output methods while keeping raw stdout/stderr channels
+ * available for lower-level integrations.
+ */
+export declare function createOutput(options?: OutputOptions): Output;

package/dist/output/facade.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * The output facade exposes semantic stdout and stderr write operations.
+ *
+ * Allowed here:
+ * - creating stdout/stderr writer channels;
+ * - delegating `write` to stdout and `error` to stderr;
+ *
+ * This file must not contain command semantics, rendering rules, or
+ * application-specific diagnostics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOutput = createOutput;
+const node_writer_1 = require("./node-writer");
+/**
+ * Creates semantic output methods while keeping raw stdout/stderr channels
+ * available for lower-level integrations.
+ */
+function createOutput(options = {}) {
+    const stdout = (0, node_writer_1.createStdoutWriter)(options.stdout);
+    const stderr = (0, node_writer_1.createStderrWriter)(options.stderr);
+    return {
+        write(chunk) {
+            return stdout.write(chunk);
+        },
+        error(chunk) {
+            return stderr.write(chunk);
+        },
+        stdout,
+        stderr
+    };
+}

package/dist/output/node-writer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Node writer module exposes stdout and stderr text writer factories.
+ *
+ * Allowed here:
+ * - binding Node-compatible writable streams to text writers;
+ *
+ * This file must not contain rendering rules or command semantics.
+ */
+import { type BackpressureTextSink, type TextWriter } from './text-writer';
+/**
+ * Creates a stdout writer from an already selected Node-compatible sink.
+ */
+export declare function createStdoutWriter(stdout?: BackpressureTextSink): TextWriter;
+/**
+ * Creates a stderr writer from an already selected Node-compatible sink.
+ */
+export declare function createStderrWriter(stderr?: BackpressureTextSink): TextWriter;

package/dist/output/node-writer.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * The Node writer module exposes stdout and stderr text writer factories.
+ *
+ * Allowed here:
+ * - binding Node-compatible writable streams to text writers;
+ *
+ * This file must not contain rendering rules or command semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStdoutWriter = createStdoutWriter;
+exports.createStderrWriter = createStderrWriter;
+const text_writer_1 = require("./text-writer");
+/**
+ * Creates a stdout writer from an already selected Node-compatible sink.
+ */
+function createStdoutWriter(stdout = process.stdout) {
+    return (0, text_writer_1.createBackpressureTextWriter)(stdout);
+}
+/**
+ * Creates a stderr writer from an already selected Node-compatible sink.
+ */
+function createStderrWriter(stderr = process.stderr) {
+    return (0, text_writer_1.createBackpressureTextWriter)(stderr);
+}

package/dist/output/text-writer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The text writer module adapts writable text sinks to backpressure-aware
+ * writer contracts.
+ *
+ * Allowed here:
+ * - the minimal text writer contract;
+ * - promise-returning sink support;
+ * - Node-style `drain` waiting when a writable sink reports backpressure;
+ *
+ * This file must not contain stdout/stderr selection or command semantics.
+ */
+export type TextWriter = {
+    write(chunk: string): unknown | Promise<unknown>;
+};
+/**
+ * Minimal writable stream shape accepted by icore output adapters.
+ */
+export type BackpressureTextSink = {
+    write(chunk: string): unknown;
+    /** Optional `drain` event hook. */
+    once?(event: 'drain', listener: () => void): unknown;
+};
+/**
+ * Creates a text writer that preserves writable-stream backpressure.
+ *
+ * Promise-returning sinks are awaited, and Node-style sinks returning `false`
+ * are resumed after their next `drain` event.
+ */
+export declare function createBackpressureTextWriter(sink: BackpressureTextSink): TextWriter;

package/dist/output/text-writer.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * The text writer module adapts writable text sinks to backpressure-aware
+ * writer contracts.
+ *
+ * Allowed here:
+ * - the minimal text writer contract;
+ * - promise-returning sink support;
+ * - Node-style `drain` waiting when a writable sink reports backpressure;
+ *
+ * This file must not contain stdout/stderr selection or command semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBackpressureTextWriter = createBackpressureTextWriter;
+/**
+ * Creates a text writer that preserves writable-stream backpressure.
+ *
+ * Promise-returning sinks are awaited, and Node-style sinks returning `false`
+ * are resumed after their next `drain` event.
+ */
+function createBackpressureTextWriter(sink) {
+    return {
+        async write(chunk) {
+            const writeResult = sink.write(chunk);
+            if (isPromiseLike(writeResult)) {
+                await writeResult;
+                return;
+            }
+            if (writeResult !== false) {
+                return;
+            }
+            if (typeof sink.once !== 'function') {
+                return;
+            }
+            await waitForDrain(sink.once.bind(sink));
+        }
+    };
+}
+function isPromiseLike(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && 'then' in value
+        && typeof value.then === 'function');
+}
+function waitForDrain(onceDrain) {
+    return new Promise((resolve) => {
+        onceDrain('drain', resolve);
+    });
+}

package/dist/presentation/facade.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The presentation facade exposes reusable terminal view and rendering
+ * mechanics as a small semantic surface.
+ *
+ * Allowed here:
+ * - creating presentation view factories;
+ * - wiring generic JSON, CSV, and text table renderers;
+ * - exposing a single `render` method for terminal app composition;
+ *
+ * This file must not contain application report mapping, command execution, or
+ * stdout/stderr delivery.
+ */
+import { presentationFormats, type PresentationFormat } from './format-options';
+import { type CsvRow, type PresentationResult, type PresentationViewFactory, type TextTableRow } from './view';
+export type PresentationRenderers = {
+    json: {
+        render(value: unknown): string;
+    };
+    table: {
+        render(rows: readonly TextTableRow[]): string;
+    };
+    csv: {
+        render(rows: readonly CsvRow[]): string;
+        renderRow(row: CsvRow): string;
+    };
+};
+export type Presentation = PresentationViewFactory & {
+    formats: typeof presentationFormats;
+    render(result: PresentationResult, format?: PresentationFormat): string;
+    renderers: PresentationRenderers;
+};
+export type { PresentationResult } from './view';
+/**
+ * Creates the presentation facade used by terminal applications.
+ *
+ * The facade owns generic rendering mechanics only; callers still map their
+ * domain objects to presentation views.
+ */
+export declare function createPresentation(): Presentation;

package/dist/presentation/facade.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The presentation facade exposes reusable terminal view and rendering
+ * mechanics as a small semantic surface.
+ *
+ * Allowed here:
+ * - creating presentation view factories;
+ * - wiring generic JSON, CSV, and text table renderers;
+ * - exposing a single `render` method for terminal app composition;
+ *
+ * This file must not contain application report mapping, command execution, or
+ * stdout/stderr delivery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPresentation = createPresentation;
+const format_options_1 = require("./format-options");
+const csv_1 = require("./renderers/csv");
+const json_1 = require("./renderers/json");
+const table_1 = require("./renderers/table");
+const result_renderer_1 = require("./result-renderer");
+const view_1 = require("./view");
+/**
+ * Creates the presentation facade used by terminal applications.
+ *
+ * The facade owns generic rendering mechanics only; callers still map their
+ * domain objects to presentation views.
+ */
+function createPresentation() {
+    const viewFactory = (0, view_1.createPresentationViewFactory)();
+    return {
+        ...viewFactory,
+        formats: format_options_1.presentationFormats,
+        render: result_renderer_1.renderPresentationResult,
+        renderers: {
+            json: {
+                render: json_1.renderJson
+            },
+            table: {
+                render: table_1.renderTextTable
+            },
+            csv: {
+                render: csv_1.renderCsv,
+                renderRow: csv_1.renderCsvRow
+            }
+        }
+    };
+}

package/dist/presentation/format-options.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The presentation format options module defines shared output format
+ * contracts for terminal commands.
+ *
+ * Allowed here:
+ * - supported presentation format names;
+ * - reusable option schema for `--format`;
+ * - format guards for terminal app composition;
+ *
+ * This file must not contain rendering logic or command execution.
+ */
+/**
+ * Supported output formats for the shared terminal presentation renderer.
+ */
+export declare const presentationFormats: readonly ["json", "table", "csv"];
+/**
+ * Reusable `--format` option schema for commands that return presentation
+ * results.
+ */
+export declare const presentationFormatOptions: {
+    readonly format: {
+        readonly type: "string";
+        readonly choices: readonly ["json", "table", "csv"];
+        readonly default: "table";
+    };
+};
+export type PresentationFormat = typeof presentationFormats[number];
+/**
+ * Narrows unknown option values to supported presentation formats.
+ */
+export declare function isPresentationFormat(value: unknown): value is PresentationFormat;

package/dist/presentation/format-options.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * The presentation format options module defines shared output format
+ * contracts for terminal commands.
+ *
+ * Allowed here:
+ * - supported presentation format names;
+ * - reusable option schema for `--format`;
+ * - format guards for terminal app composition;
+ *
+ * This file must not contain rendering logic or command execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presentationFormatOptions = exports.presentationFormats = void 0;
+exports.isPresentationFormat = isPresentationFormat;
+/**
+ * Supported output formats for the shared terminal presentation renderer.
+ */
+exports.presentationFormats = ['json', 'table', 'csv'];
+/**
+ * Reusable `--format` option schema for commands that return presentation
+ * results.
+ */
+exports.presentationFormatOptions = {
+    format: {
+        type: 'string',
+        choices: exports.presentationFormats,
+        default: 'table'
+    }
+};
+/**
+ * Narrows unknown option values to supported presentation formats.
+ */
+function isPresentationFormat(value) {
+    return typeof value === 'string'
+        && exports.presentationFormats.includes(value);
+}

package/dist/presentation/renderers/csv.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The CSV renderer module converts generic CSV rows to terminal text.
+ *
+ * Allowed here:
+ * - CSV row joining;
+ * - CSV cell escaping for comma, quote, and newline values;
+ *
+ * This file must not contain application report mapping.
+ */
+import type { CsvRow } from '../view';
+/**
+ * Renders one CSV row while escaping cells that require quoting.
+ */
+export declare function renderCsvRow(values: CsvRow): string;
+/**
+ * Renders CSV rows with the trailing newline expected by terminal output.
+ */
+export declare function renderCsv(rows: readonly CsvRow[]): string;

package/dist/presentation/renderers/csv.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * The CSV renderer module converts generic CSV rows to terminal text.
+ *
+ * Allowed here:
+ * - CSV row joining;
+ * - CSV cell escaping for comma, quote, and newline values;
+ *
+ * This file must not contain application report mapping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCsvRow = renderCsvRow;
+exports.renderCsv = renderCsv;
+/**
+ * Renders one CSV row while escaping cells that require quoting.
+ */
+function renderCsvRow(values) {
+    return values.map(renderCsvValue).join(',');
+}
+/**
+ * Renders CSV rows with the trailing newline expected by terminal output.
+ */
+function renderCsv(rows) {
+    if (rows.length === 0) {
+        return '';
+    }
+    return `${rows.map(renderCsvRow).join('\n')}\n`;
+}
+function renderCsvValue(value) {
+    const text = String(value);
+    if (!/[",\n]/.test(text)) {
+        return text;
+    }
+    return `"${text.replaceAll('"', '""')}"`;
+}

package/dist/presentation/renderers/json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The JSON renderer module converts terminal presentation values to formatted
+ * JSON text.
+ *
+ * Allowed here:
+ * - generic JSON stringification for already prepared values;
+ *
+ * This file must not contain domain-specific scalar formatting.
+ */
+/**
+ * Renders an already prepared value as pretty JSON with a trailing newline.
+ */
+export declare function renderJson(value: unknown): string;

package/dist/presentation/renderers/json.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * The JSON renderer module converts terminal presentation values to formatted
+ * JSON text.
+ *
+ * Allowed here:
+ * - generic JSON stringification for already prepared values;
+ *
+ * This file must not contain domain-specific scalar formatting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderJson = renderJson;
+/**
+ * Renders an already prepared value as pretty JSON with a trailing newline.
+ */
+function renderJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}

package/dist/presentation/renderers/table.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The text table renderer module converts text rows to aligned terminal text.
+ *
+ * Allowed here:
+ * - computing column widths;
+ * - rendering already prepared string cells;
+ *
+ * This file must not contain domain-specific scalar formatting.
+ */
+import type { TextTableRow } from '../view';
+/**
+ * Renders prepared text rows as an aligned table without changing cell values.
+ */
+export declare function renderTextTable(rows: readonly TextTableRow[]): string;