@ahoo-wang/wow-generator 9.2.0-rc.0

package/dist/api/configuration.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where the generator looks for its configuration when none is named.
+ */
+export declare const DEFAULT_CONFIG_PATH = "./wow-generator.config.json";
+/**
+ * The generator configuration, read from {@link DEFAULT_CONFIG_PATH} or the
+ * path `GeneratorOptions.configPath` names.
+ */
+export interface GeneratorConfiguration {
+    /**
+     * tag name -> api client configuration
+     */
+    apiClients?: Record<string, ApiClientConfiguration>;
+}
+export interface ApiClientConfiguration {
+    /**
+     * The path parameters the client leaves out, because an interceptor fills
+     * them.
+     *
+     * Default: `['tenantId', 'ownerId']` for a Wow document (one with
+     * `x-wow-context-alias` or aggregates), whose CoSec interceptor fills them;
+     * none for any other document.
+     */
+    ignorePathParameters?: string[];
+    /**
+     * Method names by operationId, overriding the name derived from it. Use it
+     * when two operations of one tag derive the same name.
+     */
+    methodNames?: Record<string, string>;
+}

package/dist/api/errors.d.cts

@@ -0,0 +1,41 @@
+/**
+ * What a generation failure is about, which decides the CLI's exit code.
+ *
+ * - `input`: the OpenAPI document cannot be read, fetched or parsed, or it is
+ *   not an OpenAPI 3 document.
+ * - `configuration`: the generator configuration cannot be read, parsed or
+ *   understood.
+ * - `specification`: the document was read, but it describes something the
+ *   generator cannot turn into code that compiles: a dangling, cyclic or
+ *   external reference, names that collide after normalisation, malformed Wow
+ *   metadata.
+ * - `output`: the output directory cannot be written as asked: its manifest
+ *   (`.wow-generator.json`) is corrupt, a path resolves outside it, or writing
+ *   or deleting a file fails.
+ */
+export type GeneratorErrorKind = 'input' | 'configuration' | 'specification' | 'output';
+/**
+ * Exit codes of the `wow-generator` CLI. Anything the generator did not
+ * anticipate exits with {@link EXIT_CODES.internal}.
+ */
+export declare const EXIT_CODES: {
+    readonly success: 0;
+    readonly internal: 1;
+    readonly input: 2;
+    readonly configuration: 3;
+    readonly specification: 4;
+    readonly output: 5;
+    readonly interrupted: 130;
+};
+/**
+ * A failure the user can act on. Its message is written as one line that
+ * names what went wrong and where; the CLI prints it without a stack trace.
+ */
+export declare class GeneratorError extends Error {
+    readonly kind: GeneratorErrorKind;
+    constructor(kind: GeneratorErrorKind, message: string, options?: ErrorOptions);
+    /** The CLI exit code this failure maps to. */
+    get exitCode(): number;
+}
+/** Renders an error as the tail of a sentence. */
+export declare function errorMessage(error: unknown): string;

package/dist/api/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What a generation failure is about, which decides the CLI's exit code.
+ *
+ * - `input`: the OpenAPI document cannot be read, fetched or parsed, or it is
+ *   not an OpenAPI 3 document.
+ * - `configuration`: the generator configuration cannot be read, parsed or
+ *   understood.
+ * - `specification`: the document was read, but it describes something the
+ *   generator cannot turn into code that compiles: a dangling, cyclic or
+ *   external reference, names that collide after normalisation, malformed Wow
+ *   metadata.
+ * - `output`: the output directory cannot be written as asked: its manifest
+ *   (`.wow-generator.json`) is corrupt, a path resolves outside it, or writing
+ *   or deleting a file fails.
+ */
+export type GeneratorErrorKind = 'input' | 'configuration' | 'specification' | 'output';
+/**
+ * Exit codes of the `wow-generator` CLI. Anything the generator did not
+ * anticipate exits with {@link EXIT_CODES.internal}.
+ */
+export declare const EXIT_CODES: {
+    readonly success: 0;
+    readonly internal: 1;
+    readonly input: 2;
+    readonly configuration: 3;
+    readonly specification: 4;
+    readonly output: 5;
+    readonly interrupted: 130;
+};
+/**
+ * A failure the user can act on. Its message is written as one line that
+ * names what went wrong and where; the CLI prints it without a stack trace.
+ */
+export declare class GeneratorError extends Error {
+    readonly kind: GeneratorErrorKind;
+    constructor(kind: GeneratorErrorKind, message: string, options?: ErrorOptions);
+    /** The CLI exit code this failure maps to. */
+    get exitCode(): number;
+}
+/** Renders an error as the tail of a sentence. */
+export declare function errorMessage(error: unknown): string;

package/dist/api/logger.d.cts

@@ -0,0 +1,61 @@
+/**
+ * Where a generation reports what it does.
+ *
+ * Each method takes a message and, optionally, values to print after it, as
+ * `console.log` does. A run calls:
+ *
+ * - `debug` for every step and detail;
+ * - `info` for the outcome of the run;
+ * - `warn` for something it carried on past, but that the user probably did
+ *   not intend; `GenerationResult.warnings` counts these calls;
+ * - `error` for a failure.
+ */
+export interface Logger {
+    debug(message: string, ...params: unknown[]): void;
+    info(message: string, ...params: unknown[]): void;
+    warn(message: string, ...params: unknown[]): void;
+    error(message: string, ...params: unknown[]): void;
+}
+/**
+ * How much a {@link ConsoleLogger} prints.
+ *
+ * - `quiet`: warnings and errors only.
+ * - `normal`: also `info`, the outcome of the run.
+ * - `verbose`: also `debug`, every detail, with timestamps.
+ */
+export type LogLevel = 'quiet' | 'normal' | 'verbose';
+export interface ConsoleLoggerOptions {
+    /** Defaults to `normal`. */
+    readonly level?: LogLevel;
+    /**
+     * Prefix lines with symbols. Defaults to true on a TTY unless `NO_COLOR`
+     * is set, so CI logs and pipes stay plain.
+     */
+    readonly decorate?: boolean;
+}
+/**
+ * Console logger for the CLI.
+ *
+ * Details go to `debug`, which only `verbose` prints; the default prints the
+ * outcome, warnings and errors, so a warning is not lost among hundreds of
+ * detail lines.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly level;
+    private readonly decorate;
+    constructor(options?: ConsoleLoggerOptions);
+    private format;
+    debug(message: string, ...params: unknown[]): void;
+    info(message: string, ...params: unknown[]): void;
+    warn(message: string, ...params: unknown[]): void;
+    error(message: string, ...params: unknown[]): void;
+}
+/**
+ * Logger that prints nothing.
+ */
+export declare class SilentLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}

package/dist/api/logger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where a generation reports what it does.
+ *
+ * Each method takes a message and, optionally, values to print after it, as
+ * `console.log` does. A run calls:
+ *
+ * - `debug` for every step and detail;
+ * - `info` for the outcome of the run;
+ * - `warn` for something it carried on past, but that the user probably did
+ *   not intend; `GenerationResult.warnings` counts these calls;
+ * - `error` for a failure.
+ */
+export interface Logger {
+    debug(message: string, ...params: unknown[]): void;
+    info(message: string, ...params: unknown[]): void;
+    warn(message: string, ...params: unknown[]): void;
+    error(message: string, ...params: unknown[]): void;
+}
+/**
+ * How much a {@link ConsoleLogger} prints.
+ *
+ * - `quiet`: warnings and errors only.
+ * - `normal`: also `info`, the outcome of the run.
+ * - `verbose`: also `debug`, every detail, with timestamps.
+ */
+export type LogLevel = 'quiet' | 'normal' | 'verbose';
+export interface ConsoleLoggerOptions {
+    /** Defaults to `normal`. */
+    readonly level?: LogLevel;
+    /**
+     * Prefix lines with symbols. Defaults to true on a TTY unless `NO_COLOR`
+     * is set, so CI logs and pipes stay plain.
+     */
+    readonly decorate?: boolean;
+}
+/**
+ * Console logger for the CLI.
+ *
+ * Details go to `debug`, which only `verbose` prints; the default prints the
+ * outcome, warnings and errors, so a warning is not lost among hundreds of
+ * detail lines.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly level;
+    private readonly decorate;
+    constructor(options?: ConsoleLoggerOptions);
+    private format;
+    debug(message: string, ...params: unknown[]): void;
+    info(message: string, ...params: unknown[]): void;
+    warn(message: string, ...params: unknown[]): void;
+    error(message: string, ...params: unknown[]): void;
+}
+/**
+ * Logger that prints nothing.
+ */
+export declare class SilentLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}

package/dist/api/options.d.cts

@@ -0,0 +1,47 @@
+import { Logger } from './logger.cjs';
+/**
+ * How much of each schema a generated model's doc comment carries.
+ *
+ * - `summary`: title, description, schema key, format, default, example and
+ *   constraints.
+ * - `full`: the summary plus the complete JSON schema.
+ */
+export type SchemaDocs = 'summary' | 'full';
+/**
+ * Options of a `CodeGenerator` run.
+ */
+export interface GeneratorOptions {
+    /** Path or http(s) URL of the OpenAPI 3 document. */
+    readonly inputPath: string;
+    /** Directory the generated files are written to. */
+    readonly outputDir: string;
+    /**
+     * Path or URL of the generator configuration. When omitted, the generator
+     * reads `./wow-generator.config.json` if it exists.
+     */
+    readonly configPath?: string;
+    /**
+     * The project's `tsconfig.json`. Its compiler options decide how the
+     * generator resolves the modules it imports while it tidies the output.
+     */
+    readonly tsConfigFilePath?: string;
+    /** Receives progress, warnings and errors. Defaults to a `ConsoleLogger` at the `normal` level. */
+    readonly logger?: Logger;
+    /** Request headers used when `inputPath` or `configPath` is an http(s) URL. */
+    readonly headers?: Record<string, string>;
+    /** Milliseconds before fetching an http(s) document is abandoned. Defaults to 30000. */
+    readonly timeoutMs?: number;
+    /** How much of each schema the model doc comments carry. Defaults to `summary`. */
+    readonly schemaDocs?: SchemaDocs;
+}
+/**
+ * What a generation produced.
+ */
+export interface GenerationResult {
+    /** Absolute paths of the files written, sorted. */
+    readonly files: readonly string[];
+    /** The configuration read, or undefined when none was found. */
+    readonly configPath?: string;
+    /** How many warnings the run logged. */
+    readonly warnings: number;
+}

package/dist/api/options.d.ts

@@ -0,0 +1,47 @@
+import { Logger } from './logger.js';
+/**
+ * How much of each schema a generated model's doc comment carries.
+ *
+ * - `summary`: title, description, schema key, format, default, example and
+ *   constraints.
+ * - `full`: the summary plus the complete JSON schema.
+ */
+export type SchemaDocs = 'summary' | 'full';
+/**
+ * Options of a `CodeGenerator` run.
+ */
+export interface GeneratorOptions {
+    /** Path or http(s) URL of the OpenAPI 3 document. */
+    readonly inputPath: string;
+    /** Directory the generated files are written to. */
+    readonly outputDir: string;
+    /**
+     * Path or URL of the generator configuration. When omitted, the generator
+     * reads `./wow-generator.config.json` if it exists.
+     */
+    readonly configPath?: string;
+    /**
+     * The project's `tsconfig.json`. Its compiler options decide how the
+     * generator resolves the modules it imports while it tidies the output.
+     */
+    readonly tsConfigFilePath?: string;
+    /** Receives progress, warnings and errors. Defaults to a `ConsoleLogger` at the `normal` level. */
+    readonly logger?: Logger;
+    /** Request headers used when `inputPath` or `configPath` is an http(s) URL. */
+    readonly headers?: Record<string, string>;
+    /** Milliseconds before fetching an http(s) document is abandoned. Defaults to 30000. */
+    readonly timeoutMs?: number;
+    /** How much of each schema the model doc comments carry. Defaults to `summary`. */
+    readonly schemaDocs?: SchemaDocs;
+}
+/**
+ * What a generation produced.
+ */
+export interface GenerationResult {
+    /** Absolute paths of the files written, sorted. */
+    readonly files: readonly string[];
+    /** The configuration read, or undefined when none was found. */
+    readonly configPath?: string;
+    /** How many warnings the run logged. */
+    readonly warnings: number;
+}

package/dist/cli/program.d.cts

@@ -0,0 +1,35 @@
+import { Command, CommanderError } from 'commander';
+/** Collects the values of an option given more than once, such as `--header`. */
+export declare function collect(value: string, previous?: string[]): string[];
+/**
+ * Sets up the CLI program with all commands and options.
+ *
+ * Commander does not exit the process: a usage error (a missing required
+ * option, an unknown option or command, a missing argument, no command at
+ * all) is thrown as a `CommanderError`, which {@link runCLI} maps to an exit
+ * code.
+ *
+ * @param target - The program to set up; commander's global one by default.
+ * Settings made on it before this call, such as `configureOutput`, reach the
+ * `generate` command too.
+ * @returns The configured commander program instance
+ */
+export declare function setupCLI(target?: Command): Command;
+/**
+ * The exit code of a command line commander stopped at: 0 for `--help`,
+ * `help` and `--version`; {@link EXIT_CODES.input} for a usage error, which
+ * commander has already reported. A usage error is an invalid command line,
+ * the same category as an invalid option value such as `--timeout abc`.
+ */
+export declare function commanderExitCode(error: CommanderError): number;
+/**
+ * Parses the command line and runs the command it names. The `generate`
+ * command sets the process exit code itself; a command line commander stops
+ * at sets it to {@link commanderExitCode}.
+ *
+ * @param args - The arguments after the executable and script;
+ * `process.argv` by default
+ * @param target - The program to run; {@link setupCLI} on commander's global
+ * one by default
+ */
+export declare function runCLI(args?: readonly string[], target?: Command): Promise<void>;

package/dist/cli/program.d.ts

@@ -0,0 +1,35 @@
+import { Command, CommanderError } from 'commander';
+/** Collects the values of an option given more than once, such as `--header`. */
+export declare function collect(value: string, previous?: string[]): string[];
+/**
+ * Sets up the CLI program with all commands and options.
+ *
+ * Commander does not exit the process: a usage error (a missing required
+ * option, an unknown option or command, a missing argument, no command at
+ * all) is thrown as a `CommanderError`, which {@link runCLI} maps to an exit
+ * code.
+ *
+ * @param target - The program to set up; commander's global one by default.
+ * Settings made on it before this call, such as `configureOutput`, reach the
+ * `generate` command too.
+ * @returns The configured commander program instance
+ */
+export declare function setupCLI(target?: Command): Command;
+/**
+ * The exit code of a command line commander stopped at: 0 for `--help`,
+ * `help` and `--version`; {@link EXIT_CODES.input} for a usage error, which
+ * commander has already reported. A usage error is an invalid command line,
+ * the same category as an invalid option value such as `--timeout abc`.
+ */
+export declare function commanderExitCode(error: CommanderError): number;
+/**
+ * Parses the command line and runs the command it names. The `generate`
+ * command sets the process exit code itself; a command line commander stops
+ * at sets it to {@link commanderExitCode}.
+ *
+ * @param args - The arguments after the executable and script;
+ * `process.argv` by default
+ * @param target - The program to run; {@link setupCLI} on commander's global
+ * one by default
+ */
+export declare function runCLI(args?: readonly string[], target?: Command): Promise<void>;

package/dist/cli/runGenerate.d.cts

@@ -0,0 +1,65 @@
+import { Logger } from '../api/logger.cjs';
+import { Seams } from '../pipeline/seams.cjs';
+/**
+ * Options of the `generate` command, as commander parses them.
+ */
+export interface GenerateCommandOptions {
+    input: string;
+    output: string;
+    config?: string;
+    tsConfigFilePath?: string;
+    /** `Name: value` request headers for an http(s) input or configuration. */
+    header?: string[];
+    /** Milliseconds, as typed on the command line. */
+    timeout?: string;
+    /** `summary` or `full`. */
+    schemaDocs?: string;
+    /** Exit with a non-zero code when the run logged a warning. */
+    strict?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+}
+/**
+ * Validates the input path or URL.
+ *
+ * Any file path is accepted here and checked when it is read. A URL must use
+ * http or https; its host is not restricted, because the generator runs on
+ * the developer's own machine against a document they chose, and fetching an
+ * intranet service's `/v3/api-docs` is the common case.
+ *
+ * @param input - Input path or URL
+ * @returns true if valid
+ */
+export declare function validateInput(input: string): boolean;
+/**
+ * Parses `Name: value` header arguments.
+ *
+ * @param headers - The raw `--header` values
+ * @returns The headers by name
+ * @throws GeneratorError of kind `input` for a value without a name
+ */
+export declare function parseHeaders(headers?: readonly string[]): Record<string, string>;
+/**
+ * Runs the `generate` command.
+ *
+ * @param options - The parsed command options
+ * @param logger - Where to report; a console logger at the level the options ask for by default
+ * @param seams - What the package hands the generator beyond the options;
+ * a run stopped by the {@link SIGNAL_SEAM} exits with
+ * {@link EXIT_CODES.interrupted}
+ * @returns The exit code: see {@link EXIT_CODES}
+ */
+export declare function runGenerate(options: GenerateCommandOptions, logger?: Logger, seams?: Seams): Promise<number>;
+/**
+ * Action handler for the generate command: runs it and sets the process exit
+ * code.
+ *
+ * Ctrl-C stops the run at its next step and exits with
+ * {@link EXIT_CODES.interrupted}. A run that has begun writing finishes
+ * writing its files, then stops: it removes no stale file and leaves the
+ * manifest as the last complete run wrote it, so the manifest never records
+ * a run that did not finish. A second Ctrl-C ends the process at once.
+ *
+ * @param options - Command options
+ */
+export declare function generateAction(options: GenerateCommandOptions): Promise<void>;

package/dist/cli/runGenerate.d.ts

@@ -0,0 +1,65 @@
+import { Logger } from '../api/logger.js';
+import { Seams } from '../pipeline/seams.js';
+/**
+ * Options of the `generate` command, as commander parses them.
+ */
+export interface GenerateCommandOptions {
+    input: string;
+    output: string;
+    config?: string;
+    tsConfigFilePath?: string;
+    /** `Name: value` request headers for an http(s) input or configuration. */
+    header?: string[];
+    /** Milliseconds, as typed on the command line. */
+    timeout?: string;
+    /** `summary` or `full`. */
+    schemaDocs?: string;
+    /** Exit with a non-zero code when the run logged a warning. */
+    strict?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+}
+/**
+ * Validates the input path or URL.
+ *
+ * Any file path is accepted here and checked when it is read. A URL must use
+ * http or https; its host is not restricted, because the generator runs on
+ * the developer's own machine against a document they chose, and fetching an
+ * intranet service's `/v3/api-docs` is the common case.
+ *
+ * @param input - Input path or URL
+ * @returns true if valid
+ */
+export declare function validateInput(input: string): boolean;
+/**
+ * Parses `Name: value` header arguments.
+ *
+ * @param headers - The raw `--header` values
+ * @returns The headers by name
+ * @throws GeneratorError of kind `input` for a value without a name
+ */
+export declare function parseHeaders(headers?: readonly string[]): Record<string, string>;
+/**
+ * Runs the `generate` command.
+ *
+ * @param options - The parsed command options
+ * @param logger - Where to report; a console logger at the level the options ask for by default
+ * @param seams - What the package hands the generator beyond the options;
+ * a run stopped by the {@link SIGNAL_SEAM} exits with
+ * {@link EXIT_CODES.interrupted}
+ * @returns The exit code: see {@link EXIT_CODES}
+ */
+export declare function runGenerate(options: GenerateCommandOptions, logger?: Logger, seams?: Seams): Promise<number>;
+/**
+ * Action handler for the generate command: runs it and sets the process exit
+ * code.
+ *
+ * Ctrl-C stops the run at its next step and exits with
+ * {@link EXIT_CODES.interrupted}. A run that has begun writing finishes
+ * writing its files, then stops: it removes no stale file and leaves the
+ * manifest as the last complete run wrote it, so the manifest never records
+ * a run that did not finish. A second Ctrl-C ends the process at once.
+ *
+ * @param options - Command options
+ */
+export declare function generateAction(options: GenerateCommandOptions): Promise<void>;

package/dist/cli.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./codeGenerator-DpDTDC4o.cjs");let t=require("path"),n=require("commander");var r=`9.2.0-rc.0`;function i(e){if(!e)return!1;let t;try{t=new URL(e)}catch{return!0}return/^[a-z]:$/i.test(t.protocol)?!0:t.protocol===`http:`||t.protocol===`https:`}function a(t=[]){let n={};for(let r of t){let t=r.indexOf(`:`),i=t>0?r.slice(0,t).trim():``;if(!i)throw new e.s(`input`,`Invalid --header "${r}": expected "Name: value".`);n[i]=r.slice(t+1).trim()}return n}function o(t){if(t===void 0)return;let n=Number(t);if(!Number.isInteger(n)||n<=0)throw new e.s(`input`,`Invalid --timeout "${t}": expected a positive number of milliseconds.`);return n}function s(t){if(t===void 0||t===`summary`)return`summary`;if(t===`full`)return`full`;throw new e.s(`input`,`Invalid --schema-docs "${t}": expected "summary" or "full".`)}function c(e){return e.verbose?`verbose`:e.quiet?`quiet`:`normal`}function l(t,n,r){if(n instanceof e.s)return t.error(n.message),r&&n.cause!==void 0&&t.error(`Caused by:`,n.cause),n.exitCode;let i=n instanceof Error?n.message:String(n);return t.error(`Code generation failed: ${i}`),r?t.error(``,n):t.error(`Rerun with --verbose for the stack trace, and report it at https://github.com/Ahoo-Wang/Wow/issues if the input is valid.`),e.o.internal}async function u(n,u=new e.i({level:c(n)}),d={}){if(!i(n.input))return u.error(`Invalid input "${n.input}": expected a file path or an http(s) URL.`),e.o.input;try{u.debug(`wow-generator v${r}`);let i={...d,inputPath:n.input,outputDir:n.output,configPath:n.config,tsConfigFilePath:n.tsConfigFilePath,headers:a(n.header),timeoutMs:o(n.timeout),schemaDocs:s(n.schemaDocs),logger:u},c=await new e.t(i).generate(),l=c.warnings?`, ${c.warnings} warning${c.warnings===1?``:`s`}`:``,f=c.configPath?` with ${(0,t.relative)(process.cwd(),c.configPath)||c.configPath}`:``;return u.info(`Generated ${c.files.length} files into ${n.output}${f}${l}`),n.strict&&c.warnings>0?(u.error(`--strict: the run logged ${c.warnings} warning${c.warnings===1?``:`s`}.`),e.o.specification):e.o.success}catch(t){return d[e.n]?.aborted?e.o.interrupted:l(u,t,!!n.verbose)}}async function d(t){let n=new AbortController;process.once(`SIGINT`,()=>{console.error(`Generation interrupted by user`),n.abort()}),process.exitCode=await u(t,void 0,{[e.n]:n.signal})}function f(e,t=[]){return[...t,e]}function p(t=n.program){return t.exitOverride(),t.name(`wow-generator`).description(`OpenAPI Specification TypeScript code generator for Wow`).version(r,`-v, --version`),t.command(`generate`).description(`Generate TypeScript code from OpenAPI specification`).requiredOption(`-i, --input <file>`,`Input OpenAPI specification file path or URL (http/https)`).option(`-o, --output <path>`,`Output directory path`,`src/generated`).option(`-c, --config <file>`,`Configuration file path (default: ${e.c})`).option(`-t, --ts-config-file-path <file>`,`TypeScript configuration file path`).option(`-H, --header <header>`,`Request header for an http(s) input or configuration, as "Name: value"; repeatable`,f).option(`--timeout <ms>`,`Milliseconds before fetching an http(s) input is abandoned (default: ${e.r})`).option(`--schema-docs <mode>`,`What model doc comments carry: "summary" (title, description, constraints) or "full" (also the JSON schema)`,`summary`).option(`--strict`,`Exit with code 4 when the run logs a warning`).option(`--verbose`,`Log every step, and the stack trace of a failure`).option(`--quiet`,`Log only warnings and errors`).action(d),t}function m(t){return t.exitCode===0?e.o.success:e.o.input}async function h(e,t=p()){try{e===void 0?await t.parseAsync():await t.parseAsync(e,{from:`user`})}catch(e){if(!(e instanceof n.CommanderError))throw e;process.exitCode=m(e)}}h(),exports.collect=f,exports.runCLI=h,exports.setupCLI=p;
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.cjs","names":["GeneratorError","EXIT_CODES","ConsoleLogger","CodeGenerator","relative","SIGNAL_SEAM","program","DEFAULT_CONFIG_PATH","DEFAULT_HTTP_TIMEOUT_MS","EXIT_CODES","CommanderError","require_codeGenerator","path","commander","VERSION","validateInput","input","url","parseHeaders","parsed","header","headers","separator","name","parseTimeout","timeout","value","parseSchemaDocs","schemaDocs","logLevel","options","reportFailure","error","logger","verbose","message","runGenerate","generatorOptions","seams","result","warnings","config","generateAction","interruption","collect","previous","setupCLI","target","commanderExitCode","runCLI","args"],"sources":["../src/version.ts","../src/cli/runGenerate.ts","../src/cli/program.ts","../src/cli.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// Replaced at build time with the `version` of this package's package.json\n// (`define` in vite.config.ts, which Vitest shares), so only the version string\n// reaches dist, not the manifest with its dependencies and workspace ranges.\ndeclare const __WOW_GENERATOR_VERSION__: string;\n\n/** The version of this package, as its package.json named it at build time. */\nexport const VERSION: string = __WOW_GENERATOR_VERSION__;\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { relative } from 'path';\nimport { VERSION } from '../version';\nimport { EXIT_CODES, GeneratorError } from '../api/errors';\nimport { CodeGenerator } from '../pipeline/codeGenerator';\nimport type { Logger, LogLevel } from '../api/logger';\nimport { ConsoleLogger } from '../api/logger';\nimport type { SchemaDocs } from '../api/options';\nimport type { SeamOptions, Seams } from '../pipeline/seams';\nimport { SIGNAL_SEAM } from '../pipeline/seams';\n\n/**\n * Options of the `generate` command, as commander parses them.\n */\nexport interface GenerateCommandOptions {\n  input: string;\n  output: string;\n  config?: string;\n  tsConfigFilePath?: string;\n  /** `Name: value` request headers for an http(s) input or configuration. */\n  header?: string[];\n  /** Milliseconds, as typed on the command line. */\n  timeout?: string;\n  /** `summary` or `full`. */\n  schemaDocs?: string;\n  /** Exit with a non-zero code when the run logged a warning. */\n  strict?: boolean;\n  verbose?: boolean;\n  quiet?: boolean;\n}\n\n/**\n * Validates the input path or URL.\n *\n * Any file path is accepted here and checked when it is read. A URL must use\n * http or https; its host is not restricted, because the generator runs on\n * the developer's own machine against a document they chose, and fetching an\n * intranet service's `/v3/api-docs` is the common case.\n *\n * @param input - Input path or URL\n * @returns true if valid\n */\nexport function validateInput(input: string): boolean {\n  if (!input) return false;\n  let url: URL;\n  try {\n    url = new URL(input);\n  } catch {\n    // Not a URL: a file path, which parseOpenAPI reads.\n    return true;\n  }\n  // A Windows path such as C:\\spec.json parses as a URL with scheme \"c:\".\n  if (/^[a-z]:$/i.test(url.protocol)) return true;\n  return url.protocol === 'http:' || url.protocol === 'https:';\n}\n\n/**\n * Parses `Name: value` header arguments.\n *\n * @param headers - The raw `--header` values\n * @returns The headers by name\n * @throws GeneratorError of kind `input` for a value without a name\n */\nexport function parseHeaders(\n  headers: readonly string[] = [],\n): Record<string, string> {\n  const parsed: Record<string, string> = {};\n  for (const header of headers) {\n    const separator = header.indexOf(':');\n    const name = separator > 0 ? header.slice(0, separator).trim() : '';\n    if (!name) {\n      throw new GeneratorError(\n        'input',\n        `Invalid --header \"${header}\": expected \"Name: value\".`,\n      );\n    }\n    parsed[name] = header.slice(separator + 1).trim();\n  }\n  return parsed;\n}\n\nfunction parseTimeout(timeout: string | undefined): number | undefined {\n  if (timeout === undefined) return undefined;\n  const value = Number(timeout);\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new GeneratorError(\n      'input',\n      `Invalid --timeout \"${timeout}\": expected a positive number of milliseconds.`,\n    );\n  }\n  return value;\n}\n\nfunction parseSchemaDocs(schemaDocs: string | undefined): SchemaDocs {\n  if (schemaDocs === undefined || schemaDocs === 'summary') return 'summary';\n  if (schemaDocs === 'full') return 'full';\n  throw new GeneratorError(\n    'input',\n    `Invalid --schema-docs \"${schemaDocs}\": expected \"summary\" or \"full\".`,\n  );\n}\n\nfunction logLevel(options: GenerateCommandOptions): LogLevel {\n  if (options.verbose) return 'verbose';\n  if (options.quiet) return 'quiet';\n  return 'normal';\n}\n\n/**\n * Reports a failure as one actionable line; the stack and the causes only\n * with `--verbose`.\n *\n * @returns The exit code the failure maps to\n */\nfunction reportFailure(\n  logger: Logger,\n  error: unknown,\n  verbose: boolean,\n): number {\n  if (error instanceof GeneratorError) {\n    logger.error(error.message);\n    if (verbose && error.cause !== undefined) {\n      logger.error('Caused by:', error.cause);\n    }\n    return error.exitCode;\n  }\n  const message = error instanceof Error ? error.message : String(error);\n  logger.error(`Code generation failed: ${message}`);\n  if (verbose) {\n    logger.error('', error);\n  } else {\n    logger.error(\n      'Rerun with --verbose for the stack trace, and report it at https://github.com/Ahoo-Wang/Wow/issues if the input is valid.',\n    );\n  }\n  return EXIT_CODES.internal;\n}\n\n/**\n * Runs the `generate` command.\n *\n * @param options - The parsed command options\n * @param logger - Where to report; a console logger at the level the options ask for by default\n * @param seams - What the package hands the generator beyond the options;\n * a run stopped by the {@link SIGNAL_SEAM} exits with\n * {@link EXIT_CODES.interrupted}\n * @returns The exit code: see {@link EXIT_CODES}\n */\nexport async function runGenerate(\n  options: GenerateCommandOptions,\n  logger: Logger = new ConsoleLogger({ level: logLevel(options) }),\n  seams: Seams = {},\n): Promise<number> {\n  if (!validateInput(options.input)) {\n    logger.error(\n      `Invalid input \"${options.input}\": expected a file path or an http(s) URL.`,\n    );\n    return EXIT_CODES.input;\n  }\n  try {\n    logger.debug(`wow-generator v${VERSION}`);\n    const generatorOptions: SeamOptions = {\n      ...seams,\n      inputPath: options.input,\n      outputDir: options.output,\n      configPath: options.config,\n      tsConfigFilePath: options.tsConfigFilePath,\n      headers: parseHeaders(options.header),\n      timeoutMs: parseTimeout(options.timeout),\n      schemaDocs: parseSchemaDocs(options.schemaDocs),\n      logger,\n    };\n    const result = await new CodeGenerator(generatorOptions).generate();\n    const warnings = result.warnings\n      ? `, ${result.warnings} warning${result.warnings === 1 ? '' : 's'}`\n      : '';\n    const config = result.configPath\n      ? ` with ${relative(process.cwd(), result.configPath) || result.configPath}`\n      : '';\n    logger.info(\n      `Generated ${result.files.length} files into ${options.output}${config}${warnings}`,\n    );\n    if (options.strict && result.warnings > 0) {\n      logger.error(\n        `--strict: the run logged ${result.warnings} warning${result.warnings === 1 ? '' : 's'}.`,\n      );\n      return EXIT_CODES.specification;\n    }\n    return EXIT_CODES.success;\n  } catch (error) {\n    if (seams[SIGNAL_SEAM]?.aborted) return EXIT_CODES.interrupted;\n    return reportFailure(logger, error, !!options.verbose);\n  }\n}\n\n/**\n * Action handler for the generate command: runs it and sets the process exit\n * code.\n *\n * Ctrl-C stops the run at its next step and exits with\n * {@link EXIT_CODES.interrupted}. A run that has begun writing finishes\n * writing its files, then stops: it removes no stale file and leaves the\n * manifest as the last complete run wrote it, so the manifest never records\n * a run that did not finish. A second Ctrl-C ends the process at once.\n *\n * @param options - Command options\n */\nexport async function generateAction(options: GenerateCommandOptions) {\n  const interruption = new AbortController();\n  process.once('SIGINT', () => {\n    console.error('Generation interrupted by user');\n    interruption.abort();\n  });\n  process.exitCode = await runGenerate(options, undefined, {\n    [SIGNAL_SEAM]: interruption.signal,\n  });\n}\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { Command } from 'commander';\nimport { CommanderError, program } from 'commander';\nimport { VERSION } from '../version';\nimport { DEFAULT_CONFIG_PATH } from '../api/configuration';\nimport { EXIT_CODES } from '../api/errors';\nimport { DEFAULT_HTTP_TIMEOUT_MS } from '../input/resources';\nimport { generateAction } from './runGenerate';\n\n/** Collects the values of an option given more than once, such as `--header`. */\nexport function collect(value: string, previous: string[] = []): string[] {\n  return [...previous, value];\n}\n\n/**\n * Sets up the CLI program with all commands and options.\n *\n * Commander does not exit the process: a usage error (a missing required\n * option, an unknown option or command, a missing argument, no command at\n * all) is thrown as a `CommanderError`, which {@link runCLI} maps to an exit\n * code.\n *\n * @param target - The program to set up; commander's global one by default.\n * Settings made on it before this call, such as `configureOutput`, reach the\n * `generate` command too.\n * @returns The configured commander program instance\n */\nexport function setupCLI(target: Command = program): Command {\n  // Before `command()`: a subcommand copies the exit override when it is\n  // created.\n  target.exitOverride();\n  // compat(fetcher): package.json also installs this CLI as `fetcher-generator`, the\n  // name existing scripts call; drop that bin alias in v10.\n  target\n    .name('wow-generator')\n    .description('OpenAPI Specification TypeScript code generator for Wow')\n    .version(VERSION, '-v, --version');\n\n  target\n    .command('generate')\n    .description('Generate TypeScript code from OpenAPI specification')\n    .requiredOption(\n      '-i, --input <file>',\n      'Input OpenAPI specification file path or URL (http/https)',\n    )\n    .option('-o, --output <path>', 'Output directory path', 'src/generated')\n    // No commander default: an omitted -c falls back to DEFAULT_CONFIG_PATH,\n    // which may be absent, while a path the user named has to exist.\n    .option(\n      '-c, --config <file>',\n      `Configuration file path (default: ${DEFAULT_CONFIG_PATH})`,\n    )\n    .option(\n      '-t, --ts-config-file-path <file>',\n      'TypeScript configuration file path',\n    )\n    .option(\n      '-H, --header <header>',\n      'Request header for an http(s) input or configuration, as \"Name: value\"; repeatable',\n      collect,\n    )\n    .option(\n      '--timeout <ms>',\n      `Milliseconds before fetching an http(s) input is abandoned (default: ${DEFAULT_HTTP_TIMEOUT_MS})`,\n    )\n    .option(\n      '--schema-docs <mode>',\n      'What model doc comments carry: \"summary\" (title, description, constraints) or \"full\" (also the JSON schema)',\n      'summary',\n    )\n    .option('--strict', 'Exit with code 4 when the run logs a warning')\n    .option('--verbose', 'Log every step, and the stack trace of a failure')\n    .option('--quiet', 'Log only warnings and errors')\n    .action(generateAction);\n\n  return target;\n}\n\n/**\n * The exit code of a command line commander stopped at: 0 for `--help`,\n * `help` and `--version`; {@link EXIT_CODES.input} for a usage error, which\n * commander has already reported. A usage error is an invalid command line,\n * the same category as an invalid option value such as `--timeout abc`.\n */\nexport function commanderExitCode(error: CommanderError): number {\n  return error.exitCode === 0 ? EXIT_CODES.success : EXIT_CODES.input;\n}\n\n/**\n * Parses the command line and runs the command it names. The `generate`\n * command sets the process exit code itself; a command line commander stops\n * at sets it to {@link commanderExitCode}.\n *\n * @param args - The arguments after the executable and script;\n * `process.argv` by default\n * @param target - The program to run; {@link setupCLI} on commander's global\n * one by default\n */\nexport async function runCLI(\n  args?: readonly string[],\n  target: Command = setupCLI(),\n): Promise<void> {\n  try {\n    if (args === undefined) {\n      await target.parseAsync();\n    } else {\n      await target.parseAsync(args, { from: 'user' });\n    }\n  } catch (error) {\n    if (!(error instanceof CommanderError)) throw error;\n    process.exitCode = commanderExitCode(error);\n  }\n}\n","#!/usr/bin/env node\n\n/**\n * CLI entry point of wow-generator: runs the program `cli/program.ts` sets\n * up on the process's command line.\n */\n\nimport { runCLI } from './cli/program';\n\nexport { collect, runCLI, setupCLI } from './cli/program';\n\nvoid runCLI();\n"],"mappings":"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"}

package/dist/cli.d.cts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point of wow-generator: runs the program `cli/program.ts` sets
+ * up on the process's command line.
+ */
+export { collect, runCLI, setupCLI } from './cli/program.cjs';

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point of wow-generator: runs the program `cli/program.ts` sets
+ * up on the process's command line.
+ */
+export { collect, runCLI, setupCLI } from './cli/program.js';