@usejourney/codegen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 femoral <me@femoral.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+interface Operation {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly operationId: string;
+}
+interface OpenApiDocument {
+    readonly openapi?: string;
+    readonly swagger?: string;
+    readonly paths?: Record<string, Record<string, {
+        operationId?: string;
+    } | unknown> | undefined>;
+}
+
+declare function collectOperations(doc: OpenApiDocument): Operation[];
+declare function renderEndpointsFile(operations: Operation[]): string;
+
+interface PrefixLintFinding {
+    majority: {
+        prefix: string;
+        count: number;
+    };
+    minority: {
+        prefix: string;
+        count: number;
+    };
+    message: string;
+}
+/**
+ * Flags specs where one or two operations sit under a top-level prefix that
+ * the rest of the API doesn't share. Catches the `/api/v1/foo` typo when 30
+ * other ops live under `/v1/...` — common when an OpenAPI is hand-assembled.
+ *
+ * Heuristic: take the first path segment of every operation, bucket counts.
+ * If the dominant bucket holds ≥80% and the smallest other bucket holds
+ * ≤20% on a corpus of ≥5 operations, return a finding. Multi-prefix specs
+ * with a balanced split fall through silently.
+ */
+declare function findPrefixOutliers(operations: ReadonlyArray<Operation>): PrefixLintFinding | null;
+
+declare function loadSpec(specPath: string): Promise<OpenApiDocument>;
+
+/**
+ * Derive a stable JS identifier for an operation. When `operationId` is a valid
+ * identifier we trust it verbatim — users chose that name intentionally. Otherwise
+ * derive from method + path, e.g. `GET /v1/accounts/{id}` → `getV1AccountsById`.
+ */
+declare function operationName(method: string, path: string, operationId: string | undefined): string;
+
+interface GenerateOptions {
+    /** Path to the OpenAPI spec file (YAML or JSON). */
+    specPath: string;
+    /** Directory where `endpoints.ts` and `models.ts` are written. */
+    outDir: string;
+}
+interface GenerateResult {
+    modelsPath: string;
+    endpointsPath: string;
+    operationCount: number;
+}
+declare function generate(opts: GenerateOptions): Promise<GenerateResult>;
+
+export { type GenerateOptions, type GenerateResult, type Operation, type PrefixLintFinding, collectOperations, findPrefixOutliers, generate, loadSpec, operationName, renderEndpointsFile };

package/dist/index.js

@@ -0,0 +1,158 @@
+// src/index.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import openapiTS, { astToString } from "openapi-typescript";
+
+// src/names.ts
+var INVALID = /[^a-zA-Z0-9]+/g;
+var IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function pascalCaseParts(input) {
+  return input.split(INVALID).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function operationName(method, path, operationId) {
+  if (operationId && IDENT_RE.test(operationId)) return operationId;
+  const cleanedPath = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/\//g, "_");
+  const pascal = pascalCaseParts(`${method}_${cleanedPath}`);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function uniqueName(base, taken) {
+  if (!taken.has(base)) {
+    taken.add(base);
+    return base;
+  }
+  let i = 2;
+  while (taken.has(`${base}${i}`)) i += 1;
+  const next = `${base}${i}`;
+  taken.add(next);
+  return next;
+}
+
+// src/types.ts
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options"
+];
+
+// src/emit-endpoints.ts
+function collectOperations(doc) {
+  const paths = doc.paths ?? {};
+  const taken = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    for (const method of HTTP_METHODS) {
+      const op = pathItem[method];
+      if (!op || typeof op !== "object") continue;
+      const rawId = op.operationId;
+      const id = uniqueName(
+        operationName(method, path, typeof rawId === "string" ? rawId : void 0),
+        taken
+      );
+      out.push({ method, path, operationId: id });
+    }
+  }
+  return out;
+}
+var HEADER = `// AUTO-GENERATED BY @usejourney/codegen \u2014 do not edit by hand.
+import type { EndpointRef } from "@usejourney/core";
+import type { paths } from "./models.js";
+
+type JsonResponse<P extends keyof paths, M extends keyof paths[P]> =
+  paths[P][M] extends { responses: infer R }
+    ? R extends { 200: { content: { "application/json": infer T } } } ? T
+    : R extends { 201: { content: { "application/json": infer T } } } ? T
+    : R extends { 202: { content: { "application/json": infer T } } } ? T
+    : unknown
+    : unknown;
+`;
+function renderEndpointsFile(operations) {
+  const entries = operations.map((op) => {
+    const methodUc = op.method.toUpperCase();
+    return `  ${op.operationId}: { method: "${methodUc}", path: "${op.path}", operationId: "${op.operationId}" } as unknown as EndpointRef<JsonResponse<"${op.path}", "${op.method}">>,`;
+  });
+  return [
+    HEADER,
+    "export const endpoints = {",
+    ...entries,
+    "} as const;",
+    "",
+    "export type EndpointName = keyof typeof endpoints;",
+    ""
+  ].join("\n");
+}
+
+// src/lint.ts
+function findPrefixOutliers(operations) {
+  if (operations.length < 5) return null;
+  const buckets = /* @__PURE__ */ new Map();
+  for (const op of operations) {
+    const first = firstSegment(op.path);
+    buckets.set(first, (buckets.get(first) ?? 0) + 1);
+  }
+  if (buckets.size < 2) return null;
+  const sorted = [...buckets.entries()].sort((a, b) => b[1] - a[1]);
+  const total = operations.length;
+  const [majPrefix, majCount] = sorted[0];
+  const [minPrefix, minCount] = sorted[sorted.length - 1];
+  if (majCount / total < 0.8) return null;
+  if (minCount / total > 0.2) return null;
+  return {
+    majority: { prefix: `/${majPrefix}`, count: majCount },
+    minority: { prefix: `/${minPrefix}`, count: minCount },
+    message: `journey: warning \u2014 ${minCount} operation(s) use prefix '/${minPrefix}' while ${majCount} use '/${majPrefix}'`
+  };
+}
+function firstSegment(path) {
+  const trimmed = path.replace(/^\/+/, "");
+  const idx = trimmed.indexOf("/");
+  return idx === -1 ? trimmed : trimmed.slice(0, idx);
+}
+
+// src/parse.ts
+import { readFile } from "fs/promises";
+import { extname } from "path";
+import yaml from "js-yaml";
+async function loadSpec(specPath) {
+  const raw = await readFile(specPath, "utf8");
+  const ext = extname(specPath).toLowerCase();
+  const doc = ext === ".json" ? JSON.parse(raw) : yaml.load(raw);
+  if (!doc || typeof doc !== "object") {
+    throw new Error(`Spec at ${specPath} did not parse to an object`);
+  }
+  const typed = doc;
+  if (!typed.openapi && !typed.swagger) {
+    throw new Error(`Spec at ${specPath} is missing "openapi"/"swagger" field`);
+  }
+  return typed;
+}
+
+// src/index.ts
+async function generate(opts) {
+  const doc = await loadSpec(opts.specPath);
+  const operations = collectOperations(doc);
+  const outlier = findPrefixOutliers(operations);
+  if (outlier) console.warn(outlier.message);
+  const ast = await openapiTS(doc);
+  const modelsSource = `// AUTO-GENERATED BY @usejourney/codegen \u2014 do not edit by hand.
+${astToString(ast)}`;
+  const endpointsSource = renderEndpointsFile(operations);
+  await mkdir(opts.outDir, { recursive: true });
+  const modelsPath = join(opts.outDir, "models.ts");
+  const endpointsPath = join(opts.outDir, "endpoints.ts");
+  await writeFile(modelsPath, modelsSource, "utf8");
+  await writeFile(endpointsPath, endpointsSource, "utf8");
+  return { modelsPath, endpointsPath, operationCount: operations.length };
+}
+export {
+  collectOperations,
+  findPrefixOutliers,
+  generate,
+  loadSpec,
+  operationName,
+  renderEndpointsFile
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@usejourney/codegen",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/femoral/journey.git",
+    "directory": "packages/codegen"
+  },
+  "homepage": "https://github.com/femoral/journey#readme",
+  "bugs": "https://github.com/femoral/journey/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "openapi-typescript": "^7.13.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}