openapi-contract-kit 0.0.1 → 0.0.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.0.4] - 2026-09-12
+
+- Lowered the supported Node.js baseline to Node 24 and added CI coverage for Node 24 and 26.
+
+## [0.0.3] - 2026-09-12
+
+- Fixed GitHub Release publishing from detached tag checkouts by disabling pnpm branch checks in the publish workflow.
+
+## [0.0.2] - 2026-09-12
+
+- Added linting to the development and CI workflows.
+- Streamlined the test workflow around the build and unit-test commands.
+- Updated the CI and publishing workflows for the current toolchain.
+
 ## [0.1.0] - 2026-09-11
 
 - Initial public release.

package/README.md

@@ -1,5 +1,7 @@
 # openapi-contract-kit
 
+[![CI](https://github.com/Clinsmann/openapi-contract-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Clinsmann/openapi-contract-kit/actions/workflows/ci.yml)
+
 JSON-first OpenAPI 3.1 contract generation and runtime validation for TypeScript applications.
 
 `openapi-contract-kit` reads a JSON OpenAPI document and generates:
@@ -14,9 +16,11 @@ JSON-first OpenAPI 3.1 contract generation and runtime validation for TypeScript
 ## Installation
 
 ```bash
-npm install --save-dev openapi-contract-kit
+pnpm add -D openapi-contract-kit
 ```
 
+Requires Node.js 24 or newer and pnpm 12.3.4.
+
 ## Quick start
 
 Create `openapi.config.json`:
@@ -42,7 +46,7 @@ Add a generation script:
 Generate contracts:
 
 ```bash
-npm run openapi:generate
+pnpm run openapi:generate
 ```
 
 ## Generated validation
@@ -59,6 +63,8 @@ if (!result.ok) {
 
 Validation errors contain a path, keyword, and message. Successful validation returns the original input without mutating or cloning it.
 
+The focused fixture and acceptance tests cover structural validation: object shape, declared fields, primitive types, arrays, nullability, references, unions, and additional-property behavior. They do not require form-level checks such as email format, string length, patterns, or numeric ranges. Those constraints remain available when declared in consumer schemas.
+
 ## Supported input
 
 The generator supports JSON OpenAPI 3.1 documents with objects, primitive types, nullable values, arrays, enums, constants, unions, local `$ref` references, additional-property rules, string and numeric constraints, and email format validation.
@@ -74,9 +80,11 @@ The generator supports JSON OpenAPI 3.1 documents with objects, primitive types,
 ## Development
 
 ```bash
-npm install
-npm test
-npm run pack:check
+pnpm install
+pnpm run lint
+pnpm run typecheck
+pnpm test
+pnpm run pack:check
 ```
 
 ## Versioning

package/dist/bin/openapi-contract-kit.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/openapi-contract-kit.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../src/generator/generateOpenApiRuntime.js';
+await main();

package/dist/src/cli/formatOutput.d.ts

@@ -0,0 +1,6 @@
+import type { GenerateOpenApiRuntimeResult } from '../generator/types.js';
+export type CliOutputStream = {
+    readonly isTTY?: boolean;
+};
+export declare function formatSuccessOutput(result: GenerateOpenApiRuntimeResult, stream: CliOutputStream): string;
+export declare function formatFailureOutput(message: string, stream: CliOutputStream): string;

package/dist/src/cli/formatOutput.js

@@ -0,0 +1,32 @@
+import { styleText } from 'node:util';
+function canUseColor(stream) {
+    return (stream.isTTY === true &&
+        process.env.NO_COLOR === undefined &&
+        process.env.TERM !== 'dumb');
+}
+function styleCliText(format, text, stream) {
+    return canUseColor(stream)
+        ? styleText(format, text, { validateStream: false })
+        : text;
+}
+function formatCount(count, singular) {
+    return `${count} ${singular}${count === 1 ? '' : 's'}`;
+}
+export function formatSuccessOutput(result, stream) {
+    if (stream.isTTY !== true) {
+        return `Generated ${result.schemaCount} schemas and ${result.operationCount} endpoints.\n`;
+    }
+    const marker = styleCliText('green', '✔', stream);
+    const heading = styleCliText('bold', 'OpenAPI generation complete', stream);
+    const schemas = styleCliText('dim', `Schemas:   ${formatCount(result.schemaCount, 'schema')}`, stream);
+    const endpoints = styleCliText('dim', `Endpoints: ${formatCount(result.operationCount, 'endpoint')}`, stream);
+    return `${marker} ${heading}\n\n  ${schemas}\n  ${endpoints}\n`;
+}
+export function formatFailureOutput(message, stream) {
+    if (stream.isTTY !== true) {
+        return `OpenAPI generation failed: ${message}\n`;
+    }
+    const marker = styleCliText('red', '✖', stream);
+    const heading = styleCliText('bold', 'OpenAPI generation failed', stream);
+    return `${marker} ${heading}\n\n  ${message}\n`;
+}

package/dist/src/generator/config.d.ts

@@ -0,0 +1,3 @@
+import type { GenerateOpenApiRuntimeOptions, GeneratorConfig, UnknownRecord } from './types.js';
+export declare function isRecord(value: unknown): value is UnknownRecord;
+export declare function resolveGeneratorConfig(options?: GenerateOpenApiRuntimeOptions): Promise<GeneratorConfig>;

package/dist/src/generator/config.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+const CONFIG_KEYS = new Set(['specPath', 'outDir', 'runtimeImport']);
+const FLAG_NAMES = new Map([
+    ['--config', 'configPath'],
+    ['--spec', 'specPath'],
+    ['--out', 'outDir'],
+    ['--runtime-import', 'runtimeImport'],
+]);
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseArguments(argv, cwd) {
+    const values = {};
+    for (let index = 0; index < argv.length; index += 2) {
+        const flag = argv[index];
+        const key = flag === undefined ? undefined : FLAG_NAMES.get(flag);
+        const value = argv[index + 1];
+        if (key === undefined) {
+            throw new Error(`Unknown argument "${flag ?? ''}"`);
+        }
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`Missing value for "${flag}"`);
+        }
+        values[key] = isAbsolute(value) ? value : resolve(cwd, value);
+    }
+    return values;
+}
+function requirePath(config, key, configPath) {
+    const value = config[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`Config "${configPath}" requires a non-empty "${key}"`);
+    }
+    return value;
+}
+export async function resolveGeneratorConfig(options = {}) {
+    const argv = options.argv ?? [];
+    const cwd = options.cwd ?? process.cwd();
+    const cli = parseArguments(argv, cwd);
+    const configPath = cli.configPath ?? resolve(cwd, 'openapi.config.json');
+    let config;
+    try {
+        config = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read OpenAPI config "${configPath}": ${message}`);
+    }
+    if (!isRecord(config)) {
+        throw new Error(`OpenAPI config "${configPath}" must contain an object`);
+    }
+    for (const key of Object.keys(config)) {
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`Unknown OpenAPI config key "${key}"`);
+        }
+    }
+    const configDirectory = dirname(configPath);
+    const resolveConfigPath = (key) => {
+        const value = requirePath(config, key, configPath);
+        return isAbsolute(value) ? value : resolve(configDirectory, value);
+    };
+    const runtimeImport = cli.runtimeImport ?? requirePath(config, 'runtimeImport', configPath);
+    if (runtimeImport.includes('\\') || runtimeImport.startsWith('.')) {
+        throw new Error(`Config "${configPath}" requires a package runtimeImport`);
+    }
+    return {
+        configPath,
+        specPath: cli.specPath ?? resolveConfigPath('specPath'),
+        outDir: cli.outDir ?? resolveConfigPath('outDir'),
+        runtimeImport,
+    };
+}

package/dist/src/generator/documents.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedReference, UnknownRecord } from './types.js';
+export declare function isRecord(value: unknown): value is UnknownRecord;
+export declare function escapePointerSegment(segment: string): string;
+export declare function pointerChild(pointer: string, segment: string | number): string;
+export declare function locationOf(documentPath: string, pointer: string): string;
+export declare function requireRecord(value: unknown, location: string, label: string): UnknownRecord;
+export declare class DocumentStore {
+    #private;
+    load(documentPath: string): Promise<UnknownRecord>;
+    resolveReference(reference: unknown, fromDocumentPath: string): Promise<ResolvedReference>;
+}

package/dist/src/generator/documents.js

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function escapePointerSegment(segment) {
+    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+export function pointerChild(pointer, segment) {
+    return `${pointer}/${escapePointerSegment(String(segment))}`;
+}
+export function locationOf(documentPath, pointer) {
+    return `${documentPath}#${pointer}`;
+}
+export function requireRecord(value, location, label) {
+    if (!isRecord(value)) {
+        throw new Error(`${label} at ${location} must be an object`);
+    }
+    return value;
+}
+export class DocumentStore {
+    #documents = new Map();
+    async load(documentPath) {
+        const absolutePath = resolve(documentPath);
+        const existing = this.#documents.get(absolutePath);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const pending = this.#read(absolutePath);
+        this.#documents.set(absolutePath, pending);
+        return pending;
+    }
+    async #read(documentPath) {
+        let source;
+        try {
+            source = await readFile(documentPath, 'utf8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Unable to read OpenAPI document "${documentPath}": ${message}`);
+        }
+        try {
+            const extension = extname(documentPath).toLowerCase();
+            if (extension !== '.json') {
+                throw new Error('Only JSON OpenAPI documents are supported');
+            }
+            return requireRecord(JSON.parse(source), documentPath, 'OpenAPI document');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Unable to parse OpenAPI document "${documentPath}": ${message}`);
+        }
+    }
+    async resolveReference(reference, fromDocumentPath) {
+        if (typeof reference !== 'string' || reference.length === 0) {
+            throw new Error(`Invalid $ref at ${fromDocumentPath}`);
+        }
+        if (/^[A-Za-z][A-Za-z\d+.-]*:/u.test(reference)) {
+            throw new Error(`Remote $ref "${reference}" is unsupported`);
+        }
+        const hashIndex = reference.indexOf('#');
+        const filePart = hashIndex === -1 ? reference : reference.slice(0, hashIndex);
+        const fragment = hashIndex === -1 ? '' : reference.slice(hashIndex + 1);
+        const documentPath = filePart.length === 0
+            ? fromDocumentPath
+            : resolve(dirname(fromDocumentPath), decodeURIComponent(filePart));
+        const document = await this.load(documentPath);
+        const decodedFragment = decodeURIComponent(fragment);
+        if (decodedFragment.length > 0 && !decodedFragment.startsWith('/')) {
+            throw new Error(`Anchor $ref "${reference}" is unsupported`);
+        }
+        let value = document;
+        for (const encodedSegment of decodedFragment.split('/').slice(1)) {
+            const segment = encodedSegment
+                .replaceAll('~1', '/')
+                .replaceAll('~0', '~');
+            if (!isRecord(value) && !Array.isArray(value)) {
+                throw new Error(`Unresolved $ref "${reference}" from ${fromDocumentPath}`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(value, segment)) {
+                throw new Error(`Unresolved $ref "${reference}" from ${fromDocumentPath}`);
+            }
+            value = Reflect.get(value, segment);
+        }
+        return {
+            canonicalKey: locationOf(documentPath, decodedFragment),
+            documentPath,
+            pointer: decodedFragment,
+            value,
+        };
+    }
+}

package/dist/src/generator/emitEndpoints.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorConfig, OpenApiModel } from './types.js';
+export declare function emitEndpointModules(model: OpenApiModel, config: GeneratorConfig): Map<string, string>;

package/{src/generator/emitEndpoints.mjs → dist/src/generator/emitEndpoints.js}

@@ -1,93 +1,64 @@
-import { join } from 'node:path';
-
 function renderResponseType(responses) {
-  if (responses.length === 0) {
-    return 'never';
-  }
-
-  return responses
-    .map(({ schemaName, status }) => {
-      const bodyType = schemaName ?? 'null';
-      return `{ readonly status: ${status}; readonly body: ${bodyType} }`;
+    if (responses.length === 0) {
+        return 'never';
+    }
+    return responses
+        .map(({ schemaName, status }) => {
+        const bodyType = schemaName ?? 'null';
+        return `{ readonly status: ${status}; readonly body: ${bodyType} }`;
     })
-    .join(' | ');
+        .join(' | ');
 }
-
 function renderStatusCases(responses) {
-  const lines = [];
-
-  for (const response of responses) {
-    lines.push(`    case ${response.status}: {`);
-    if (response.schemaName === null) {
-      lines.push(
-        `      if (parts.body !== null) {`,
-        `        return failure(['body'], 'nullBody', 'Expected a null response body');`,
-        `      }`,
-        `      return { ok: true, value: { status: ${response.status}, body: null } };`
-      );
-    } else {
-      lines.push(
-        `      const result = make${response.schemaName}(parts.body);`,
-        `      if (!result.ok) {`,
-        `        return result;`,
-        `      }`,
-        `      return { ok: true, value: { status: ${response.status}, body: result.value } };`
-      );
+    const lines = [];
+    for (const response of responses) {
+        lines.push(`    case ${response.status}: {`);
+        if (response.schemaName === null) {
+            lines.push(`      if (parts.body !== null) {`, `        return failure(['body'], 'nullBody', 'Expected a null response body');`, `      }`, `      return { ok: true, value: { status: ${response.status}, body: null } };`);
+        }
+        else {
+            lines.push(`      const result = make${response.schemaName}(parts.body);`, `      if (!result.ok) {`, `        return result;`, `      }`, `      return { ok: true, value: { status: ${response.status}, body: result.value } };`);
+        }
+        lines.push('    }');
     }
-    lines.push('    }');
-  }
-
-  lines.push(
-    `    default:`,
-    `      return failure(['status'], 'status', 'Undocumented response status');`
-  );
-  return lines.join('\n');
+    lines.push(`    default:`, `      return failure(['status'], 'status', 'Undocumented response status');`);
+    return lines.join('\n');
 }
-
-function emitEndpoint(operation, { outDir, runtimeImport }) {
-  const successResponses = operation.responses.filter(
-    (response) => response.isSuccess
-  );
-  const errorResponses = operation.responses.filter(
-    (response) => !response.isSuccess
-  );
-  const schemaNames = new Set();
-
-  if (operation.request.schemaName !== null) {
-    schemaNames.add(operation.request.schemaName);
-  }
-  for (const response of operation.responses) {
-    if (response.schemaName !== null) {
-      schemaNames.add(response.schemaName);
+function emitEndpoint(operation, config) {
+    const successResponses = operation.responses.filter((response) => response.isSuccess);
+    const errorResponses = operation.responses.filter((response) => !response.isSuccess);
+    const schemaNames = new Set();
+    if (operation.request.schemaName !== null) {
+        schemaNames.add(operation.request.schemaName);
     }
-  }
-
-  const sortedSchemaNames = [...schemaNames].sort();
-  const typeImport =
-    sortedSchemaNames.length === 0
-      ? ''
-      : `import type { ${sortedSchemaNames.join(', ')} } from '../quickpay-api';\n`;
-  const makerImports = sortedSchemaNames
-    .map((name) => `import { make${name} } from '../schemas/${name}';`)
-    .join('\n');
-  const requestType = operation.request.schemaName ?? 'null';
-  const requestMaker =
-    operation.request.schemaName === null
-      ? `export function makeRequest(input: unknown): Result<null> {
+    for (const response of operation.responses) {
+        if (response.schemaName !== null) {
+            schemaNames.add(response.schemaName);
+        }
+    }
+    const sortedSchemaNames = [...schemaNames].sort();
+    const typeImport = sortedSchemaNames.length === 0
+        ? ''
+        : `import type { ${sortedSchemaNames.join(', ')} } from '../quickpay-api';\n`;
+    const makerImports = sortedSchemaNames
+        .map((name) => `import { make${name} } from '../schemas/${name}';`)
+        .join('\n');
+    const requestType = operation.request.schemaName ?? 'null';
+    const requestMaker = operation.request.schemaName === null
+        ? `export function makeRequest(input: unknown): Result<null> {
   if (input !== null) {
     return failure([], 'nullBody', 'Expected null');
   }
 
   return { ok: true, value: null };
 }`
-      : `export const makeRequest = make${operation.request.schemaName};`;
-
-  return `/**
+        : `export const makeRequest = make${operation.request.schemaName};`;
+    return `/**
  * Generated by openapi-contract-kit.
  * Do not edit directly.
  */
 
-import type { Result, ValidationPath } from ${JSON.stringify(runtimeImport)};
+import type { Result, ValidationPath } from ${JSON.stringify(config.runtimeImport)};
 ${typeImport}${makerImports}${makerImports.length > 0 ? '\n' : ''}
 export const URL = ${JSON.stringify(operation.path)};
 export const METHOD = ${JSON.stringify(operation.method)};
@@ -171,12 +142,9 @@ export const makeResponse = Object.assign(makeAnyResponse, {
 });
 `;
 }
-
 export function emitEndpointModules(model, config) {
-  return new Map(
-    model.operations.map((operation) => [
-      `endpoints/${operation.name}.ts`,
-      emitEndpoint(operation, config),
-    ])
-  );
+    return new Map(model.operations.map((operation) => [
+        `endpoints/${operation.name}.ts`,
+        emitEndpoint(operation, config),
+    ]));
 }

package/dist/src/generator/emitMakers.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorConfig, OpenApiModel } from './types.js';
+export declare function emitSchemaMakers(model: OpenApiModel, config: GeneratorConfig): Map<string, string>;