openapi-contract-kit 0.0.1 → 0.0.4

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

@@ -0,0 +1,82 @@
+export type UnknownRecord = Record<string, unknown>;
+export type JsonPrimitive = boolean | null | number | string;
+export type SchemaType = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string';
+export type DocumentContext = {
+    readonly documentPath: string;
+    readonly pointer: string;
+};
+export type ResolvedReference = DocumentContext & {
+    readonly canonicalKey: string;
+    readonly value: unknown;
+};
+export type BooleanSchema = {
+    readonly booleanSchema: boolean;
+    readonly location: string;
+};
+export type SchemaProperty = {
+    readonly name: string;
+    readonly required: boolean;
+    readonly schema: NormalizedSchema;
+};
+export type StandardSchema = {
+    readonly additionalProperties: boolean | NormalizedSchema;
+    readonly allOf: readonly NormalizedSchema[];
+    readonly anyOf: readonly NormalizedSchema[];
+    readonly booleanSchema: null;
+    readonly constValue: JsonPrimitive | undefined;
+    readonly enumValues: readonly JsonPrimitive[] | null;
+    readonly exclusiveMaximum: number | null;
+    readonly exclusiveMinimum: number | null;
+    readonly format: 'email' | null;
+    readonly items: NormalizedSchema | null;
+    readonly location: string;
+    readonly maximum: number | null;
+    readonly maxLength: number | null;
+    readonly minimum: number | null;
+    readonly minLength: number | null;
+    readonly oneOf: readonly NormalizedSchema[];
+    readonly pattern: string | null;
+    readonly properties: readonly SchemaProperty[];
+    readonly reference: string | null;
+    readonly types: readonly SchemaType[] | null;
+};
+export type NormalizedSchema = BooleanSchema | StandardSchema;
+export type SchemaEntry = {
+    readonly canonicalKey: string;
+    readonly name: string;
+    readonly schema: NormalizedSchema;
+};
+export type ResponseModel = {
+    readonly isSuccess: boolean;
+    readonly schemaName: string | null;
+    readonly status: number;
+};
+export type OperationModel = {
+    readonly method: string;
+    readonly name: string;
+    readonly operationId: string;
+    readonly path: string;
+    readonly request: {
+        readonly schemaName: string | null;
+    };
+    readonly responses: readonly ResponseModel[];
+};
+export type OpenApiModel = {
+    readonly operations: readonly OperationModel[];
+    readonly schemas: readonly SchemaEntry[];
+};
+export type GeneratorConfig = {
+    readonly configPath: string;
+    readonly outDir: string;
+    readonly runtimeImport: string;
+    readonly specPath: string;
+};
+export type GenerateOpenApiRuntimeOptions = {
+    readonly argv?: readonly string[];
+    readonly cwd?: string;
+};
+export type GenerateOpenApiRuntimeResult = {
+    readonly operationCount: number;
+    readonly operationNames: readonly string[];
+    readonly schemaCount: number;
+};

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

@@ -0,0 +1,5 @@
+type OutputOptions = {
+    readonly protectedPaths?: readonly string[];
+};
+export declare function writeGeneratedOutput(outDir: string, files: ReadonlyMap<string, string>, options?: OutputOptions): Promise<void>;
+export {};

package/dist/src/generator/writeOutput.js

@@ -0,0 +1,141 @@
+import { access, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, parse, relative, } from 'node:path';
+const MANIFEST_FILE = '.openapi-runtime-manifest.json';
+const LEGACY_GENERATED_FILE = /^(?:quickpay-api\.ts|(?:endpoints|schemas)\/[^/]+\.ts)$/u;
+function isManifest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const files = Reflect.get(value, 'files');
+    return (Array.isArray(files) && files.every((file) => typeof file === 'string'));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listFiles(directory, prefix = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const relativePath = prefix.length === 0 ? entry.name : `${prefix}/${entry.name}`;
+        const absolutePath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(absolutePath, relativePath)));
+        }
+        else {
+            files.push(relativePath);
+        }
+    }
+    return files;
+}
+function validateGeneratedPath(path) {
+    if (path.length === 0 ||
+        isAbsolute(path) ||
+        path.split('/').some((segment) => segment === '..' || segment.length === 0)) {
+        throw new Error(`Unsafe generated output path "${path}"`);
+    }
+}
+function isAncestor(parent, child) {
+    const pathFromParent = relative(parent, child);
+    return (pathFromParent.length === 0 ||
+        (!pathFromParent.startsWith('..') && !isAbsolute(pathFromParent)));
+}
+function validateOutputRoot(outDir, protectedPaths) {
+    if (parse(outDir).root === outDir) {
+        throw new Error(`Unsafe OpenAPI output directory "${outDir}"`);
+    }
+    for (const protectedPath of protectedPaths) {
+        if (isAncestor(outDir, protectedPath)) {
+            throw new Error(`OpenAPI output directory "${outDir}" contains protected input "${protectedPath}"`);
+        }
+    }
+}
+async function validateExistingOutput(outDir) {
+    if (!(await exists(outDir))) {
+        return false;
+    }
+    const existingFiles = await listFiles(outDir);
+    if (existingFiles.length === 0) {
+        return true;
+    }
+    if (!existingFiles.includes(MANIFEST_FILE)) {
+        const unexpected = existingFiles.find((file) => !LEGACY_GENERATED_FILE.test(file));
+        if (unexpected !== undefined) {
+            throw new Error(`OpenAPI output directory contains unexpected file "${unexpected}"`);
+        }
+        return true;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(outDir, MANIFEST_FILE), 'utf8'));
+    }
+    catch {
+        throw new Error(`OpenAPI output manifest is invalid at ${outDir}`);
+    }
+    if (!isManifest(manifest)) {
+        throw new Error(`OpenAPI output manifest is invalid at ${outDir}`);
+    }
+    const ownedFiles = new Set([...manifest.files, MANIFEST_FILE]);
+    const unexpected = existingFiles.find((file) => !ownedFiles.has(file));
+    if (unexpected !== undefined) {
+        throw new Error(`OpenAPI output directory contains unexpected file "${unexpected}"`);
+    }
+    return true;
+}
+async function writeStage(stagePath, files) {
+    await mkdir(stagePath, { recursive: true });
+    for (const [relativePath, content] of files) {
+        validateGeneratedPath(relativePath);
+        const targetPath = join(stagePath, relativePath);
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, content);
+    }
+    const manifest = {
+        version: 1,
+        files: [...files.keys()].sort(),
+    };
+    await writeFile(join(stagePath, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+export async function writeGeneratedOutput(outDir, files, options = {}) {
+    const protectedPaths = options.protectedPaths ?? [];
+    validateOutputRoot(outDir, protectedPaths);
+    const hadExistingOutput = await validateExistingOutput(outDir);
+    const parent = dirname(outDir);
+    await mkdir(parent, { recursive: true });
+    const swapRoot = await mkdtemp(join(parent, `.${basename(outDir)}.openapi-runtime-`));
+    const stagedOutput = join(swapRoot, 'next');
+    const previousOutput = join(swapRoot, 'previous');
+    let movedPreviousOutput = false;
+    try {
+        await writeStage(stagedOutput, files);
+        if (hadExistingOutput) {
+            await rename(outDir, previousOutput);
+            movedPreviousOutput = true;
+        }
+        try {
+            await rename(stagedOutput, outDir);
+        }
+        catch (error) {
+            if (movedPreviousOutput && !(await exists(outDir))) {
+                await rename(previousOutput, outDir);
+                movedPreviousOutput = false;
+            }
+            throw error;
+        }
+        if (movedPreviousOutput) {
+            await rm(previousOutput, { force: true, recursive: true });
+            movedPreviousOutput = false;
+        }
+    }
+    finally {
+        if (movedPreviousOutput && !(await exists(outDir))) {
+            await rename(previousOutput, outDir);
+        }
+        await rm(swapRoot, { force: true, recursive: true });
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { generateOpenApiRuntime, main, } from './generator/generateOpenApiRuntime.js';
+export type { GenerateOpenApiRuntimeOptions, GenerateOpenApiRuntimeResult, } from './generator/types.js';

package/dist/src/index.js

@@ -0,0 +1 @@
+export { generateOpenApiRuntime, main, } from './generator/generateOpenApiRuntime.js';

package/dist/src/runtime.d.ts

@@ -0,0 +1,14 @@
+export type ValidationPath = readonly (string | number)[];
+export type ValidationIssue = {
+    readonly path: ValidationPath;
+    readonly keyword: string;
+    readonly message: string;
+};
+export type Result<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ValidationIssue[];
+};
+export type MakeResult<T> = Result<T>;

package/dist/src/runtime.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,41 +1,43 @@
 {
   "name": "openapi-contract-kit",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Generate type-safe TypeScript contracts and runtime validators from JSON OpenAPI 3.1 documents.",
   "type": "module",
   "license": "MIT",
   "engines": {
-    "node": ">=20.11"
+    "node": ">=24.0.0"
   },
-  "main": "./src/index.mjs",
-  "types": "./src/index.d.ts",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "bin": {
-    "openapi-contract-kit": "./bin/openapi-contract-kit.mjs"
+    "openapi-contract-kit": "./dist/bin/openapi-contract-kit.js"
   },
   "exports": {
     ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.mjs"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
     },
     "./runtime": {
-      "types": "./src/runtime.d.ts",
-      "import": "./src/runtime.mjs"
+      "types": "./dist/src/runtime.d.ts",
+      "import": "./dist/src/runtime.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
-    "bin",
-    "src",
+    "dist/bin",
+    "dist/src",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "pack:check": "npm pack --dry-run"
-  },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.10.0",
+    "prettier": "^3.9.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^5.0.0"
   },
   "repository": {
     "type": "git",
@@ -54,5 +56,15 @@
     "api-contracts",
     "json-schema",
     "cli"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test:unit": "vitest run test/generateOpenApiRuntime.test.ts test/model.test.ts --pool=forks",
+    "test": "pnpm run build && pnpm run test:unit",
+    "pack:check": "pnpm run build && pnpm pack --dry-run"
+  }
+}

package/bin/openapi-contract-kit.mjs

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

package/src/generator/config.mjs

@@ -1,92 +0,0 @@
-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'],
-]);
-
-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_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({
-  argv = [],
-  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/src/generator/documents.mjs

@@ -1,119 +0,0 @@
-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');
-      }
-      const value = JSON.parse(source);
-      return requireRecord(value, 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,
-    };
-  }
-}