genoc 0.3.0 → 0.4.1

package/dist/cli/app.js

@@ -8,8 +8,9 @@ const command = buildCommand({
             outputDir: {
                 kind: 'parsed',
                 parse: String,
-                brief: 'Directory to write generated files',
+                brief: 'Directory to write generated files (or set outputDir in the config file)',
                 placeholder: 'dir',
+                optional: true,
             },
             methodNameStrategy: {
                 kind: 'enum',
@@ -26,8 +27,8 @@ const command = buildCommand({
             },
             strictVersion: {
                 kind: 'boolean',
-                default: true,
-                brief: 'Enable strict version checking',
+                brief: 'Warn when --spec-version mismatches the detected version (default: true)',
+                optional: true,
             },
             runtimeImportPath: {
                 kind: 'parsed',
@@ -43,14 +44,32 @@ const command = buildCommand({
                 optional: true,
                 placeholder: 'url',
             },
+            config: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Path to a genoc config file (.genocrc.yml / .genocrc.json); skips discovery',
+                optional: true,
+                placeholder: 'path',
+            },
+            project: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Run only the named client from a multi-client config',
+                optional: true,
+                placeholder: 'name',
+            },
+        },
+        aliases: {
+            o: 'outputDir',
         },
         positional: {
             kind: 'tuple',
             parameters: [
                 {
-                    brief: 'Path or URL to OpenAPI 3.0 or 3.1 spec (JSON/YAML)',
+                    brief: 'Path or URL to OpenAPI 3.0 or 3.1 spec (JSON/YAML); omit to use a config file',
                     parse: String,
                     placeholder: 'spec',
+                    optional: true,
                 },
             ],
         },

package/dist/cli/config-loader.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedConfig } from './config-schema.js';
+export interface LoadConfigFileOptions {
+    /** Explicit config file path (`--config`); skips discovery when set. */
+    explicitPath?: string;
+    /** Directory to start discovery from; defaults to `process.cwd()`. */
+    searchDir?: string;
+}
+export interface LoadedConfigFile {
+    config: ParsedConfig;
+    filepath: string;
+}
+/**
+ * Load the genoc config file. With `explicitPath`, loads exactly that file
+ * (skipping discovery). Otherwise discovers `.genocrc.yml` / `.genocrc.json`
+ * walking up from `searchDir` (default `process.cwd()`), stopping at the git
+ * boundary (fs root fallback). Returns `null` when no config file is found;
+ * throws `UserError` for parse errors, schema violations, empty documents,
+ * and duplicate resolved output dirs.
+ */
+export declare function loadConfigFile(options?: LoadConfigFileOptions): Promise<LoadedConfigFile | null>;

package/dist/cli/config-loader.js

@@ -0,0 +1,186 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { lilconfig } from 'lilconfig';
+import { parse as parseYaml } from 'yaml';
+import { isUrl } from '../utils/url.js';
+import { parseConfig } from './config-schema.js';
+import { UserError } from './errors.js';
+const SEARCH_PLACES = ['.genocrc.yml', '.genocrc.json'];
+const SUPPORTED_EXTENSIONS = ['.yml', '.json'];
+function formatYamlError(filepath, err) {
+    const message = err instanceof Error ? err.message.split('\n')[0] : String(err);
+    // yaml@2 exposes the error mark via `linePos` (1-based), not `.line`.
+    const mark = err.linePos?.[0];
+    const location = mark === undefined ? '' : ` at line ${mark.line}, column ${mark.col}`;
+    return new UserError(`Failed to parse config file ${filepath}: YAML error${location}: ${message}`);
+}
+function yamlLoader(filepath, content) {
+    try {
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw formatYamlError(filepath, err);
+    }
+}
+function jsonLoader(filepath, content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        throw new UserError(`Failed to parse config file ${filepath} as JSON: ${err.message}`);
+    }
+}
+function createSearcher(stopDir) {
+    return lilconfig('genoc', {
+        searchPlaces: SEARCH_PLACES,
+        loaders: {
+            '.yml': yamlLoader,
+            '.json': jsonLoader,
+        },
+        stopDir,
+        // Surface empty files as results so they become UserErrors instead of
+        // being silently skipped during the upward search.
+        ignoreEmptySearchPlaces: false,
+        cache: false,
+    });
+}
+/**
+ * Nearest directory at or above `searchDir` containing a `.git` marker — the
+ * inclusive stop boundary for discovery. Falls back to the fs root when no
+ * git repository is found.
+ */
+function findGitBoundary(searchDir) {
+    let dir = searchDir;
+    for (;;) {
+        if (existsSync(path.join(dir, '.git'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return path.parse(searchDir).root;
+        }
+        dir = parent;
+    }
+}
+function resolvePathValue(value, configDir) {
+    if (isUrl(value) || path.isAbsolute(value)) {
+        return value;
+    }
+    return path.resolve(configDir, value);
+}
+function resolveConfigPaths(config, configDir) {
+    if ('clients' in config) {
+        const clients = {};
+        for (const [name, entry] of Object.entries(config.clients)) {
+            clients[name] = {
+                ...entry,
+                input: resolvePathValue(entry.input, configDir),
+                outputDir: resolvePathValue(entry.outputDir, configDir),
+            };
+        }
+        return { clients };
+    }
+    const flat = { ...config };
+    if (flat.input !== undefined) {
+        flat.input = resolvePathValue(flat.input, configDir);
+    }
+    if (flat.outputDir !== undefined) {
+        flat.outputDir = resolvePathValue(flat.outputDir, configDir);
+    }
+    return flat;
+}
+/**
+ * Re-validate unique `outputDir`s on resolved absolute paths. The schema-level
+ * check inside `parseConfig` compares raw strings only, so `./src/a` and
+ * `a/../src/a` pass it yet would clobber each other's fixed output filenames.
+ */
+function validateResolvedOutputDirs(config) {
+    if (!('clients' in config)) {
+        return;
+    }
+    const byOutputDir = new Map();
+    for (const [name, entry] of Object.entries(config.clients)) {
+        const names = byOutputDir.get(entry.outputDir) ?? [];
+        names.push(name);
+        byOutputDir.set(entry.outputDir, names);
+    }
+    for (const [outputDir, names] of byOutputDir) {
+        if (names.length > 1) {
+            throw new UserError(`Invalid genocrc configuration: duplicate outputDir '${outputDir}' used by clients ${names
+                .map((name) => `'${name}'`)
+                .join(' and ')}; each client must have a unique output directory.`);
+        }
+    }
+}
+function finalizeLoadedConfig(rawConfig, filepath, isEmpty) {
+    if (isEmpty || rawConfig === null || rawConfig === undefined) {
+        throw new UserError(`Config file is empty: ${filepath}`);
+    }
+    const parsed = parseConfig(rawConfig);
+    const config = resolveConfigPaths(parsed, path.dirname(filepath));
+    validateResolvedOutputDirs(config);
+    return { config, filepath };
+}
+async function loadFromExplicitPath(explicitPath) {
+    const filepath = path.resolve(explicitPath);
+    let stats;
+    try {
+        stats = statSync(filepath);
+    }
+    catch {
+        throw new UserError(`Config file not found: ${filepath}`);
+    }
+    if (stats.isDirectory()) {
+        throw new UserError(`Config path is a directory, not a config file: ${filepath}`);
+    }
+    const ext = path.extname(filepath);
+    if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+        throw new UserError(`Unsupported config file extension "${ext}": ${filepath}. ` +
+            `Supported extensions: ${SUPPORTED_EXTENSIONS.join(', ')}`);
+    }
+    const searcher = createSearcher(findGitBoundary(path.dirname(filepath)));
+    try {
+        const result = await searcher.load(filepath);
+        if (result === null) {
+            throw new UserError(`Failed to load config file: ${filepath}`);
+        }
+        return finalizeLoadedConfig(result.config, result.filepath, result.isEmpty === true);
+    }
+    catch (err) {
+        if (err instanceof UserError) {
+            throw err;
+        }
+        throw new UserError(`Failed to read config file ${filepath}: ${err.message}`);
+    }
+}
+async function discoverConfigFile(searchDir) {
+    const startDir = path.resolve(searchDir);
+    const searcher = createSearcher(findGitBoundary(startDir));
+    try {
+        const result = await searcher.search(startDir);
+        if (result === null || result.filepath === '') {
+            return null;
+        }
+        return finalizeLoadedConfig(result.config, result.filepath, result.isEmpty === true);
+    }
+    catch (err) {
+        if (err instanceof UserError) {
+            throw err;
+        }
+        throw new UserError(`Failed to load config file during discovery: ${err.message}`);
+    }
+}
+/**
+ * Load the genoc config file. With `explicitPath`, loads exactly that file
+ * (skipping discovery). Otherwise discovers `.genocrc.yml` / `.genocrc.json`
+ * walking up from `searchDir` (default `process.cwd()`), stopping at the git
+ * boundary (fs root fallback). Returns `null` when no config file is found;
+ * throws `UserError` for parse errors, schema violations, empty documents,
+ * and duplicate resolved output dirs.
+ */
+export async function loadConfigFile(options = {}) {
+    if (options.explicitPath !== undefined) {
+        return loadFromExplicitPath(options.explicitPath);
+    }
+    return discoverConfigFile(options.searchDir ?? process.cwd());
+}

package/dist/cli/config-schema.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+/**
+ * Zod-based validation for the genoc config file (`.genocrc.yml` / `.genocrc.json`).
+ *
+ * Two mutually exclusive shapes:
+ *  - flat (single client): the 7 generator option keys, all optional at the schema level
+ *    (requiredness is positional: file config XOR CLI flags fill them in).
+ *  - multi (multi client): ONLY a `clients` key at the root; each entry REQUIRES
+ *    `input` + `outputDir`, with the 5 strategy options optional.
+ *
+ * `requesterModuleName` is deliberately excluded — it is a dead field and must not
+ * be advertised in the config file schema.
+ */
+export declare const METHOD_NAME_STRATEGIES: readonly ["path-based", "operationId", "operationId-with-fallback"];
+/** Flat (single client) config: the 7 option keys, all optional, nothing else allowed. */
+export declare const flatConfigSchema: z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+    outputDir: z.ZodOptional<z.ZodString>;
+    methodNameStrategy: z.ZodOptional<z.ZodEnum<{
+        operationId: "operationId";
+        "operationId-with-fallback": "operationId-with-fallback";
+        "path-based": "path-based";
+    }>>;
+    specVersion: z.ZodOptional<z.ZodString>;
+    strictVersion: z.ZodOptional<z.ZodBoolean>;
+    runtimeImportPath: z.ZodOptional<z.ZodString>;
+    proxy: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One `clients` map entry: `input` + `outputDir` required, strategy options optional. */
+declare const clientEntrySchema: z.ZodObject<{
+    methodNameStrategy: z.ZodOptional<z.ZodEnum<{
+        operationId: "operationId";
+        "operationId-with-fallback": "operationId-with-fallback";
+        "path-based": "path-based";
+    }>>;
+    specVersion: z.ZodOptional<z.ZodString>;
+    strictVersion: z.ZodOptional<z.ZodBoolean>;
+    runtimeImportPath: z.ZodOptional<z.ZodString>;
+    proxy: z.ZodOptional<z.ZodString>;
+    input: z.ZodString;
+    outputDir: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Multi-client config: ONLY `clients` at the root.
+ *
+ * The `superRefine` below checks raw string values pre-resolution: duplicate
+ * `outputDir`s are detected by exact raw string equality. Path resolution to
+ * absolute paths happens later in the config loader, which may add stricter
+ * post-resolution checks; at the schema level only raw equality applies
+ * (e.g. `./src/a` and `a/../src/a` are distinct here).
+ */
+export declare const multiClientConfigSchema: z.ZodObject<{
+    clients: z.ZodRecord<z.ZodString, z.ZodObject<{
+        methodNameStrategy: z.ZodOptional<z.ZodEnum<{
+            operationId: "operationId";
+            "operationId-with-fallback": "operationId-with-fallback";
+            "path-based": "path-based";
+        }>>;
+        specVersion: z.ZodOptional<z.ZodString>;
+        strictVersion: z.ZodOptional<z.ZodBoolean>;
+        runtimeImportPath: z.ZodOptional<z.ZodString>;
+        proxy: z.ZodOptional<z.ZodString>;
+        input: z.ZodString;
+        outputDir: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Union of both shapes. `parseConfig` dispatches on shape for precise error messages. */
+export declare const configSchema: z.ZodUnion<readonly [z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+    outputDir: z.ZodOptional<z.ZodString>;
+    methodNameStrategy: z.ZodOptional<z.ZodEnum<{
+        operationId: "operationId";
+        "operationId-with-fallback": "operationId-with-fallback";
+        "path-based": "path-based";
+    }>>;
+    specVersion: z.ZodOptional<z.ZodString>;
+    strictVersion: z.ZodOptional<z.ZodBoolean>;
+    runtimeImportPath: z.ZodOptional<z.ZodString>;
+    proxy: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    clients: z.ZodRecord<z.ZodString, z.ZodObject<{
+        methodNameStrategy: z.ZodOptional<z.ZodEnum<{
+            operationId: "operationId";
+            "operationId-with-fallback": "operationId-with-fallback";
+            "path-based": "path-based";
+        }>>;
+        specVersion: z.ZodOptional<z.ZodString>;
+        strictVersion: z.ZodOptional<z.ZodBoolean>;
+        runtimeImportPath: z.ZodOptional<z.ZodString>;
+        proxy: z.ZodOptional<z.ZodString>;
+        input: z.ZodString;
+        outputDir: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type FlatConfig = z.infer<typeof flatConfigSchema>;
+export type ClientEntry = z.infer<typeof clientEntrySchema>;
+export type MultiClientConfig = z.infer<typeof multiClientConfigSchema>;
+export type ParsedConfig = FlatConfig | MultiClientConfig;
+/**
+ * Parse and validate a raw config file document (already deserialized from YAML/JSON).
+ * Returns the parsed config, or throws a single `UserError` whose message names the
+ * offending key path, the problem, and the allowed keys.
+ */
+export declare function parseConfig(raw: unknown): ParsedConfig;
+export {};

package/dist/cli/config-schema.js

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+import { UserError } from './errors.js';
+/**
+ * Zod-based validation for the genoc config file (`.genocrc.yml` / `.genocrc.json`).
+ *
+ * Two mutually exclusive shapes:
+ *  - flat (single client): the 7 generator option keys, all optional at the schema level
+ *    (requiredness is positional: file config XOR CLI flags fill them in).
+ *  - multi (multi client): ONLY a `clients` key at the root; each entry REQUIRES
+ *    `input` + `outputDir`, with the 5 strategy options optional.
+ *
+ * `requesterModuleName` is deliberately excluded — it is a dead field and must not
+ * be advertised in the config file schema.
+ */
+export const METHOD_NAME_STRATEGIES = [
+    'path-based',
+    'operationId',
+    'operationId-with-fallback',
+];
+const FLAT_OPTION_KEYS = [
+    'input',
+    'outputDir',
+    'methodNameStrategy',
+    'specVersion',
+    'strictVersion',
+    'runtimeImportPath',
+    'proxy',
+];
+const methodNameStrategySchema = z.enum(METHOD_NAME_STRATEGIES);
+const baseOptionsSchema = z
+    .object({
+    input: z.string().optional(),
+    outputDir: z.string().optional(),
+    methodNameStrategy: methodNameStrategySchema.optional(),
+    specVersion: z.string().optional(),
+    strictVersion: z.boolean().optional(),
+    runtimeImportPath: z.string().optional(),
+    proxy: z.string().optional(),
+})
+    .strict();
+/** Flat (single client) config: the 7 option keys, all optional, nothing else allowed. */
+export const flatConfigSchema = baseOptionsSchema;
+/** One `clients` map entry: `input` + `outputDir` required, strategy options optional. */
+const clientEntrySchema = baseOptionsSchema
+    .extend({ input: z.string(), outputDir: z.string() })
+    .strict();
+const clientsSchema = z.record(z.string().min(1), clientEntrySchema);
+/**
+ * Multi-client config: ONLY `clients` at the root.
+ *
+ * The `superRefine` below checks raw string values pre-resolution: duplicate
+ * `outputDir`s are detected by exact raw string equality. Path resolution to
+ * absolute paths happens later in the config loader, which may add stricter
+ * post-resolution checks; at the schema level only raw equality applies
+ * (e.g. `./src/a` and `a/../src/a` are distinct here).
+ */
+export const multiClientConfigSchema = z
+    .object({ clients: clientsSchema })
+    .strict()
+    .superRefine((config, ctx) => {
+    const names = Object.keys(config.clients);
+    if (names.length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            message: "'clients' map must contain at least one client.",
+            path: ['clients'],
+        });
+        return;
+    }
+    const byOutputDir = new Map();
+    for (const [name, entry] of Object.entries(config.clients)) {
+        const list = byOutputDir.get(entry.outputDir) ?? [];
+        list.push(name);
+        byOutputDir.set(entry.outputDir, list);
+    }
+    for (const [outputDir, clientNames] of byOutputDir) {
+        if (clientNames.length > 1) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Duplicate outputDir '${outputDir}' used by clients ${clientNames
+                    .map((name) => `'${name}'`)
+                    .join(' and ')}; each client must have a unique output directory.`,
+                path: ['clients'],
+            });
+        }
+    }
+});
+/** Union of both shapes. `parseConfig` dispatches on shape for precise error messages. */
+export const configSchema = z.union([flatConfigSchema, multiClientConfigSchema]);
+const ROOT_ALLOWED_KEYS = [...FLAT_OPTION_KEYS, 'clients'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function formatKeyPath(path) {
+    return path.length === 0 ? 'configuration root' : `'${path.map(String).join('.')}'`;
+}
+function allowedKeysFor(path) {
+    if (path.length >= 2 && path[0] === 'clients') {
+        return FLAT_OPTION_KEYS.join(', ');
+    }
+    return ROOT_ALLOWED_KEYS.join(', ');
+}
+function valueAtPath(raw, path) {
+    let current = raw;
+    for (const segment of path) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[String(segment)];
+    }
+    return current;
+}
+function formatIssue(issue, parentPath, raw) {
+    const path = issue.path.length > 0 ? issue.path : parentPath;
+    if (issue.code === 'unrecognized_keys' && 'keys' in issue) {
+        const keys = issue.keys.map((key) => `'${key}'`).join(', ');
+        const plural = issue.keys.length > 1 ? 's' : '';
+        return `- unknown key${plural} ${keys} at ${formatKeyPath(path)}; allowed keys: ${allowedKeysFor(path)}`;
+    }
+    if (issue.code === 'invalid_key') {
+        return `- ${formatKeyPath(path)}: invalid client name; client names must be non-empty strings`;
+    }
+    if (issue.code === 'invalid_value') {
+        const received = valueAtPath(raw, path);
+        const receivedText = received === undefined ? '' : `; received '${String(received)}'`;
+        return `- ${formatKeyPath(path)}: ${issue.message}${receivedText}`;
+    }
+    return `- ${formatKeyPath(path)}: ${issue.message}`;
+}
+function formatIssues(issues, raw) {
+    const lines = [];
+    for (const issue of issues) {
+        if (issue.code === 'invalid_key') {
+            lines.push(formatIssue(issue, issue.path, raw));
+            continue;
+        }
+        const subIssues = issue.issues;
+        if (Array.isArray(subIssues) && subIssues.length > 0) {
+            for (const sub of subIssues) {
+                lines.push(formatIssue(sub, issue.path, raw));
+            }
+        }
+        else {
+            lines.push(formatIssue(issue, issue.path, raw));
+        }
+    }
+    return lines.join('\n');
+}
+function formatUserError(issues, raw) {
+    return new UserError(`Invalid genocrc configuration:\n${formatIssues(issues, raw)}`);
+}
+/**
+ * Parse and validate a raw config file document (already deserialized from YAML/JSON).
+ * Returns the parsed config, or throws a single `UserError` whose message names the
+ * offending key path, the problem, and the allowed keys.
+ */
+export function parseConfig(raw) {
+    if (raw === null || raw === undefined || (isRecord(raw) && Object.keys(raw).length === 0)) {
+        throw new UserError('Invalid genocrc configuration: no configuration keys found. ' +
+            `Add flat options (${FLAT_OPTION_KEYS.join(', ')}) for a single client ` +
+            `or a 'clients' map for multiple clients.`);
+    }
+    if (isRecord(raw) && 'clients' in raw) {
+        const flatKeys = FLAT_OPTION_KEYS.filter((key) => key in raw);
+        if (flatKeys.length > 0) {
+            throw new UserError(`Invalid genocrc configuration: cannot mix flat options (${flatKeys
+                .map((key) => `'${key}'`)
+                .join(', ')}) with a 'clients' map. Use EITHER flat options ` +
+                `(${FLAT_OPTION_KEYS.join(', ')}) for a single client OR a 'clients' map ` +
+                'for multiple clients — not both.');
+        }
+        const result = multiClientConfigSchema.safeParse(raw);
+        if (!result.success) {
+            throw formatUserError(result.error.issues, raw);
+        }
+        return result.data;
+    }
+    const result = flatConfigSchema.safeParse(raw);
+    if (!result.success) {
+        throw formatUserError(result.error.issues, raw);
+    }
+    return result.data;
+}

package/dist/cli/impl.d.ts

@@ -1,3 +1,11 @@
 import type { CommandContext } from '@stricli/core';
 import type { AppFlags as Flags } from './app.js';
-export default function (this: CommandContext, flags: Flags, spec: string): Promise<void | Error>;
+/**
+ * Display name for a target that does not come from a `clients` map entry:
+ * the spec filename base (`petstore.yaml` -> `petstore`, URL last segment for
+ * remote specs). Chosen over the outputDir basename because several targets
+ * can share an input spec, but the input is what identifies the client being
+ * generated in the failure/aggregation output.
+ */
+export declare function targetNameFromInput(input: string): string;
+export default function (this: CommandContext, flags: Flags, spec: string | undefined): Promise<void | Error>;