@adhd/apigen-engine-naming 0.1.1

package/README.md

@@ -0,0 +1,18 @@
+# @adhd/apigen-engine-naming
+
+Naming and identifier helpers for apigen — case conversion, file-name normalization,
+namespace/project id derivation, export collision detection, and the §9.1 envelope-key
+conventions. Pure TypeScript (**platform: shared**).
+
+Part of [apigen](../README.md).
+
+## Public API
+
+```ts
+import { toKebab, toCamel, toPascal, toSnake, normalizeFileName, project, checkCollisions, CollisionDetectedError, envelopeKey, envelopeCliFlag, envelopeEnvVar, envelopeMetaKey } from '@adhd/apigen-engine-naming';
+```
+
+- **case helpers** — `toKebab` / `toCamel` / `toPascal` / `toSnake`, `normalizeFileName`.
+- **`project(...)`** — derive the namespace/id for a source.
+- **`checkCollisions(...)`** — detect duplicate export ids (throws `CollisionDetectedError`).
+- **envelope keys** — map an envelope field to its CLI flag / env var / MCP `_meta` key.

package/index.d.ts

@@ -0,0 +1,2 @@
+export { toKebab, toCamel, toPascal, toSnake, normalizeFileName, project, httpVerb, checkCollisions, CollisionDetectedError, envelopeKey, envelopeCliFlag, envelopeEnvVar, envelopeMetaKey, sanitizeIdentifier, } from './lib/naming';
+export type { TransportProjection, HttpVerb, ProjectionConfig, CollisionError, } from './lib/naming';

package/index.js

@@ -0,0 +1,3 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});require("ts-morph");require("node:fs");require("node:path");require("ts-json-schema-generator");const y=new Set(["string","number","boolean","integer"]);function C(e){if(typeof e!="object"||e===null)return!1;const t=e;if(t.$ref!==void 0||t.oneOf||t.anyOf||t.allOf)return!1;const{type:n}=t;return typeof n=="string"?y.has(n):Array.isArray(n)?n.every(r=>y.has(r)||r==="null"):Array.isArray(t.enum)&&t.enum.length>0?t.enum.every(r=>["string","number","boolean"].includes(typeof r)):!1}function P(e){if(!e||typeof e!="object")return!1;const t=e.properties;return t===void 0||typeof t!="object"||t===null?!1:Object.values(t).every(C)}const k={"decimal.js":"Decimal"};function x(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}Object.entries(k).map(([e,t])=>({pattern:new RegExp(`import\\(["'][^"']*${x(e)}[^"']*["']\\)\\.\\w+`,"g"),key:t}));function h(e){return e.words.join("-")}function _(e){return e.words.map((t,n)=>n===0?t:E(t)).join("")}function v(e){return e.words.map(E).join("")}function $(e){return e.words.join("_")}function w(e){return e.replace(/\.[^.]+$/,"").replace(/[._]+/g,"-")}function b(e,t={}){var l,u;const n=[e.namespace,...e.path],r=e.safe||P(e.input)?"GET":"POST",a=((u=(l=t.http)==null?void 0:l.verb)==null?void 0:u[e.id])??r,p="/"+n.map(s=>h(s)).join("/"),c=n.map(s=>$(s)).join("_"),i=n.map(s=>$(s)).slice(0,-1).join("."),g=v(n[n.length-2]??n[0]),f=v(n[n.length-1]),d=n.map(s=>h(s));return{http:{verb:a,route:p},mcp:{name:c},grpc:{package:i,service:g,method:f},cli:{path:d}}}function K(e,t,n){var a,p;const r=(p=(a=n.http)==null?void 0:a.verb)==null?void 0:p[e];return r==="GET"||r==="POST"?r:t["x-apigen-safe"]?"GET":"POST"}class j extends Error{constructor(t){const n=t.map(r=>`  [${r.transport}] "${r.target}" ← ${r.ids[0]} vs ${r.ids[1]}`);super(`apigen-naming: ${t.length} projection collision(s) detected:
+${n.join(`
+`)}`),this.name="CollisionDetectedError",this.collisions=t}}function M(e,t={}){const n=new Map,r=new Map,a=new Map,p=new Map,c=[];for(const o of e){const i=b(o,t),g=`${i.http.verb} ${i.http.route}`,f=n.get(g);f!==void 0&&f!==o.id?c.push({transport:"http",target:g,ids:[f,o.id]}):n.set(g,o.id);const d=r.get(i.mcp.name);d!==void 0&&d!==o.id?c.push({transport:"mcp",target:i.mcp.name,ids:[d,o.id]}):r.set(i.mcp.name,o.id);const l=`${i.grpc.package}.${i.grpc.service}/${i.grpc.method}`,u=a.get(l);u!==void 0&&u!==o.id?c.push({transport:"grpc",target:l,ids:[u,o.id]}):a.set(l,o.id);const s=i.cli.path.join(" "),m=p.get(s);m!==void 0&&m!==o.id?c.push({transport:"cli",target:s,ids:[m,o.id]}):p.set(s,o.id)}if(c.length>0)throw new j(c)}function S(e,t){return`x-${e}-${t}`}function O(e,t){return`--${e}-${t}`}function T(e,t){const n=r=>r.toUpperCase().replace(/-/g,"_");return e==="adhd"?`APIGEN_${n(t)}`:`APIGEN_${n(e)}_${n(t)}`}const A=S;function z(e){let t=e.replace(/[^a-zA-Z0-9_$]/g,"_");return(t===""||/^[0-9]/.test(t))&&(t=`_${t}`),t}function E(e){return e.length===0?e:e[0].toUpperCase()+e.slice(1)}exports.CollisionDetectedError=j;exports.checkCollisions=M;exports.envelopeCliFlag=O;exports.envelopeEnvVar=T;exports.envelopeKey=S;exports.envelopeMetaKey=A;exports.httpVerb=K;exports.normalizeFileName=w;exports.project=b;exports.sanitizeIdentifier=z;exports.toCamel=_;exports.toKebab=h;exports.toPascal=v;exports.toSnake=$;

package/index.mjs

@@ -0,0 +1,148 @@
+import "ts-morph";
+import "node:fs";
+import "node:path";
+import "ts-json-schema-generator";
+const h = /* @__PURE__ */ new Set(["string", "number", "boolean", "integer"]);
+function j(e) {
+  if (typeof e != "object" || e === null)
+    return !1;
+  const t = e;
+  if (t.$ref !== void 0 || t.oneOf || t.anyOf || t.allOf)
+    return !1;
+  const { type: n } = t;
+  return typeof n == "string" ? h.has(n) : Array.isArray(n) ? n.every((r) => h.has(r) || r === "null") : Array.isArray(t.enum) && t.enum.length > 0 ? t.enum.every((r) => ["string", "number", "boolean"].includes(typeof r)) : !1;
+}
+function S(e) {
+  if (!e || typeof e != "object")
+    return !1;
+  const t = e.properties;
+  return t === void 0 || typeof t != "object" || t === null ? !1 : Object.values(t).every(
+    j
+  );
+}
+const E = {
+  "decimal.js": "Decimal"
+};
+function x(e) {
+  return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+Object.entries(E).map(([e, t]) => ({
+  // Matches: import("...{modSpec}...").<anyMemberName>  (single or double quotes)
+  // The module specifier appears inside an absolute path, so we allow any
+  // characters between the quote and the specifier, and between the specifier
+  // and the closing quote. The trailing member accessor (`.default`, `.Decimal`,
+  // …) is matched generically (`\w+`) rather than anchored to one spelling —
+  // see the doc comment above for why.
+  pattern: new RegExp(
+    `import\\(["'][^"']*${x(e)}[^"']*["']\\)\\.\\w+`,
+    "g"
+  ),
+  key: t
+}));
+function $(e) {
+  return e.words.join("-");
+}
+function M(e) {
+  return e.words.map((t, n) => n === 0 ? t : b(t)).join("");
+}
+function v(e) {
+  return e.words.map(b).join("");
+}
+function y(e) {
+  return e.words.join("_");
+}
+function T(e) {
+  return e.replace(/\.[^.]+$/, "").replace(/[._]+/g, "-");
+}
+function P(e, t = {}) {
+  var l, u;
+  const n = [e.namespace, ...e.path], r = e.safe || S(e.input) ? "GET" : "POST", p = ((u = (l = t.http) == null ? void 0 : l.verb) == null ? void 0 : u[e.id]) ?? r, a = "/" + n.map((s) => $(s)).join("/"), c = n.map((s) => y(s)).join("_"), i = n.map((s) => y(s)).slice(0, -1).join("."), g = v(n[n.length - 2] ?? n[0]), f = v(n[n.length - 1]), m = n.map((s) => $(s));
+  return {
+    http: { verb: p, route: a },
+    mcp: { name: c },
+    grpc: { package: i, service: g, method: f },
+    cli: { path: m }
+  };
+}
+function G(e, t, n) {
+  var p, a;
+  const r = (a = (p = n.http) == null ? void 0 : p.verb) == null ? void 0 : a[e];
+  return r === "GET" || r === "POST" ? r : t["x-apigen-safe"] ? "GET" : "POST";
+}
+class _ extends Error {
+  constructor(t) {
+    const n = t.map(
+      (r) => `  [${r.transport}] "${r.target}" ← ${r.ids[0]} vs ${r.ids[1]}`
+    );
+    super(
+      `apigen-naming: ${t.length} projection collision(s) detected:
+${n.join(`
+`)}`
+    ), this.name = "CollisionDetectedError", this.collisions = t;
+  }
+}
+function K(e, t = {}) {
+  const n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), c = [];
+  for (const o of e) {
+    const i = P(o, t), g = `${i.http.verb} ${i.http.route}`, f = n.get(g);
+    f !== void 0 && f !== o.id ? c.push({
+      transport: "http",
+      target: g,
+      ids: [f, o.id]
+    }) : n.set(g, o.id);
+    const m = r.get(i.mcp.name);
+    m !== void 0 && m !== o.id ? c.push({
+      transport: "mcp",
+      target: i.mcp.name,
+      ids: [m, o.id]
+    }) : r.set(i.mcp.name, o.id);
+    const l = `${i.grpc.package}.${i.grpc.service}/${i.grpc.method}`, u = p.get(l);
+    u !== void 0 && u !== o.id ? c.push({
+      transport: "grpc",
+      target: l,
+      ids: [u, o.id]
+    }) : p.set(l, o.id);
+    const s = i.cli.path.join(" "), d = a.get(s);
+    d !== void 0 && d !== o.id ? c.push({
+      transport: "cli",
+      target: s,
+      ids: [d, o.id]
+    }) : a.set(s, o.id);
+  }
+  if (c.length > 0)
+    throw new _(c);
+}
+function w(e, t) {
+  return `x-${e}-${t}`;
+}
+function z(e, t) {
+  return `--${e}-${t}`;
+}
+function N(e, t) {
+  const n = (r) => r.toUpperCase().replace(/-/g, "_");
+  return e === "adhd" ? `APIGEN_${n(t)}` : `APIGEN_${n(e)}_${n(t)}`;
+}
+const D = w;
+function U(e) {
+  let t = e.replace(/[^a-zA-Z0-9_$]/g, "_");
+  return (t === "" || /^[0-9]/.test(t)) && (t = `_${t}`), t;
+}
+function b(e) {
+  return e.length === 0 ? e : e[0].toUpperCase() + e.slice(1);
+}
+export {
+  _ as CollisionDetectedError,
+  K as checkCollisions,
+  z as envelopeCliFlag,
+  N as envelopeEnvVar,
+  w as envelopeKey,
+  D as envelopeMetaKey,
+  G as httpVerb,
+  T as normalizeFileName,
+  P as project,
+  U as sanitizeIdentifier,
+  M as toCamel,
+  $ as toKebab,
+  v as toPascal,
+  y as toSnake
+};

package/lib/naming.d.ts

@@ -0,0 +1,239 @@
+import { Segment, Operation } from '@adhd/apigen-core-client';
+
+/**
+ * Returns a kebab-case rendering of a {@link Segment}'s tokenized words.
+ *
+ * Used by HTTP routes (`/transform/humanize/humanize-bytes`) and CLI commands
+ * (`transform humanize humanize-bytes`).
+ *
+ * @example toKebab({ raw: 'humanizeBytes', words: ['humanize', 'bytes'] })
+ *   // → 'humanize-bytes'
+ */
+export declare function toKebab(seg: Segment): string;
+/**
+ * Returns a camelCase rendering of a {@link Segment}'s tokenized words.
+ *
+ * @example toCamel({ raw: 'humanizeBytes', words: ['humanize', 'bytes'] })
+ *   // → 'humanizeBytes'
+ */
+export declare function toCamel(seg: Segment): string;
+/**
+ * Returns a PascalCase rendering of a {@link Segment}'s tokenized words.
+ *
+ * Used by gRPC service/method names (`HumanizeBytes`).
+ *
+ * @example toPascal({ raw: 'humanizeBytes', words: ['humanize', 'bytes'] })
+ *   // → 'HumanizeBytes'
+ */
+export declare function toPascal(seg: Segment): string;
+/**
+ * Returns a snake_case rendering of a {@link Segment}'s tokenized words.
+ *
+ * @example toSnake({ raw: 'humanizeBytes', words: ['humanize', 'bytes'] })
+ *   // → 'humanize_bytes'
+ */
+export declare function toSnake(seg: Segment): string;
+/**
+ * Normalises a raw file name segment to a kebab-case path component.
+ *
+ * Rules (SPEC §5):
+ * - Strip extension.
+ * - Dots and underscores → hyphens (`file.name.ts` → `file-name`).
+ *
+ * @example normalizeFileName('file.name.ts') // → 'file-name'
+ * @example normalizeFileName('my_util.js')   // → 'my-util'
+ */
+export declare function normalizeFileName(raw: string): string;
+/**
+ * Result of a full per-transport projection for one {@link Operation}.
+ */
+export interface TransportProjection {
+    /** HTTP: full route (e.g. `POST /transform/humanize/humanize-bytes`). */
+    http: {
+        verb: HttpVerb;
+        route: string;
+    };
+    /** MCP: flat tool name joined with `_` (e.g. `transform_humanize_humanize_bytes`). */
+    mcp: {
+        name: string;
+    };
+    /**
+     * gRPC: dotted package + Pascal service (file segment) + Pascal method (export segment).
+     * e.g. `{ package: 'transform.humanize', service: 'Humanize', method: 'HumanizeBytes' }`.
+     */
+    grpc: {
+        package: string;
+        service: string;
+        method: string;
+    };
+    /** CLI: ordered kebab command segments (e.g. `['transform', 'humanize', 'humanize-bytes']`). */
+    cli: {
+        path: string[];
+    };
+}
+export type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Per-operation override configuration for projection.
+ *
+ * Pass at generate/run time via `--opt http.verb.<id>=GET` or a project
+ * config file. **Never** modify source (Tenet 1).
+ */
+export interface ProjectionConfig {
+    /**
+     * Override the HTTP verb for specific operations by their canonical `id`.
+     *
+     * Example: `{ 'transform/humanize/humanize-bytes': 'GET' }`.
+     */
+    http?: {
+        verb?: Record<string, HttpVerb>;
+    };
+}
+/**
+ * Projects one {@link Operation} to all transport targets per SPEC §5.
+ *
+ * Verb derivation: `safe → GET`, `!safe → POST` — then overridable via
+ * {@link ProjectionConfig}. **Never** derived from `kind`.
+ *
+ * FEAT-APIGEN-022: also hoists to `GET` when `op.input`'s domain params are
+ * ALL "properly typed primitives" (or zero params) per
+ * {@link isPrimitiveOnlyInputSchema}, even when `op.safe` is `false` — this
+ * is the single decision point every transport (HTTP directly here for gRPC/
+ * openapi/mcp paths that read `op` directly; HTTP express/fastify indirectly
+ * via the `x-apigen-safe` stamp {@link httpVerb} reads, computed identically
+ * in `compose-schemas.ts`) inherits from, so auto-hoist logic is never
+ * duplicated per plugin.
+ *
+ * @param op     The canonical operation descriptor.
+ * @param config Optional projection overrides (e.g. http.verb per id).
+ */
+export declare function project(op: Operation, config?: ProjectionConfig): TransportProjection;
+/**
+ * Resolves the effective HTTP verb for an already-`ComposedSchemas`-shaped
+ * function schema (`{ input, output, 'x-apigen-safe'?, … }`).
+ *
+ * This is the SINGLE definition every HTTP-emitting plugin
+ * (`apigen-plugin-api-express`'s `run.ts`/`generate.ts`, `apigen-plugin-api-
+ * fastify`'s `run.ts`/`generate.ts`) must import instead of re-declaring —
+ * previously duplicated verbatim at all four call sites (BUG-APIGEN-025's
+ * root-cause finding). Precedence:
+ *
+ *   1. `config.http.verb[fnId]` — the manual `--opt http.verb.<id>=GET`
+ *      override (Tenet 1: expressed at generate/run time, never in source).
+ *      **Always wins**, even against auto-detected `x-apigen-safe: true`.
+ *   2. `schema['x-apigen-safe']` — stamped by `composeSchemas()`
+ *      (`op.safe` OR the FEAT-APIGEN-022 primitive-param-shape auto-hoist;
+ *      see `compose-schemas.ts` / `get-safety.ts`).
+ *   3. Falls back to `'POST'` when neither is present.
+ *
+ * @param fnId   The `<pkgId>:<fnName>` key used in the override map.
+ * @param schema The composed schema entry (or any object carrying an
+ *               `x-apigen-safe` boolean at its top level).
+ * @param config Projection overrides.
+ */
+export declare function httpVerb(fnId: string, schema: Record<string, unknown>, config: ProjectionConfig): 'GET' | 'POST';
+/**
+ * A collision detected between two operations that project to the same target.
+ */
+export interface CollisionError {
+    /** The transport where the collision occurred. */
+    transport: 'http' | 'mcp' | 'grpc' | 'cli';
+    /** The projected target string that both operations map to. */
+    target: string;
+    /** The two distinct operation ids that collide. */
+    ids: [string, string];
+}
+/**
+ * Thrown when {@link checkCollisions} finds two operations that project to
+ * the same transport target. This is a **hard extract-time error** (SPEC §5) —
+ * never silent last-writer-wins.
+ */
+export declare class CollisionDetectedError extends Error {
+    readonly collisions: CollisionError[];
+    constructor(collisions: CollisionError[]);
+}
+/**
+ * Runs the uniqueness invariant over a merged descriptor array (SPEC §5).
+ *
+ * Checks every transport target (HTTP route+verb, MCP name, gRPC
+ * package+service+method, CLI path) across all operations. Two distinct `id`s
+ * that project to the same target in **any** transport constitute a hard
+ * extract-time error — {@link CollisionDetectedError} is thrown.
+ *
+ * Call this **once** over the full merged descriptor after all operations have
+ * been built. Guards the default-object recursion + multi-file glob cases.
+ *
+ * @param operations The merged set of operations to check.
+ * @param config     Optional projection overrides (passed through to `project`).
+ * @throws {CollisionDetectedError} if any two distinct ids project to the same target.
+ */
+export declare function checkCollisions(operations: Operation[], config?: ProjectionConfig): void;
+/**
+ * Computes the canonical **HTTP / gRPC metadata / MCP `_meta`** key for an
+ * envelope field, following the `x-<pluginId>-<field>` convention (SPEC §9.1).
+ *
+ * Builtin fields (pluginId = `'adhd'`) drop the plugin segment and use
+ * `x-adhd-<field>` (per SPEC §9.1, rule 3).
+ *
+ * The **same key** is used for HTTP headers, gRPC metadata (ASCII value), and
+ * MCP `_meta` entries — one mental model across all k/v carriers (rule 1).
+ *
+ * For **binary gRPC metadata** append `-bin` to the returned key and base64-
+ * encode the value; that detail lives in the gRPC transport adapter, not here.
+ *
+ * @example envelopeKey('auth', 'session')   // → 'x-auth-session'
+ * @example envelopeKey('adhd', 'trace-id')  // → 'x-adhd-trace-id'
+ */
+export declare function envelopeKey(pluginId: string, field: string): string;
+/**
+ * Computes the **CLI flag name** for an envelope field (SPEC §9.1, rule 2).
+ *
+ * Surface: `--<pluginId>-<field>` (e.g. `--auth-session`).
+ * Builtin fields (`pluginId = 'adhd'`) use `--adhd-<field>`.
+ *
+ * @example envelopeCliFlag('auth', 'session')  // → '--auth-session'
+ * @example envelopeCliFlag('adhd', 'trace-id') // → '--adhd-trace-id'
+ */
+export declare function envelopeCliFlag(pluginId: string, field: string): string;
+/**
+ * Computes the **environment variable name** for an envelope field
+ * (SPEC §9.1, rule 2). CLI flag takes precedence over env when both present.
+ *
+ * Surface: `APIGEN_<PLUGINID>_<FIELD>` (upper-cased, hyphens → underscores).
+ * Builtin fields (pluginId = `'adhd'`) drop the plugin segment and use
+ * `APIGEN_<FIELD>` (SPEC §9.1, rule 3).
+ *
+ * @example envelopeEnvVar('auth', 'session')   // → 'APIGEN_AUTH_SESSION'
+ * @example envelopeEnvVar('adhd', 'trace-id')  // → 'APIGEN_TRACE_ID'
+ */
+export declare function envelopeEnvVar(pluginId: string, field: string): string;
+/**
+ * Computes the **MCP `_meta` key** for an envelope field — the same
+ * `x-<pluginId>-<field>` string used in HTTP/gRPC (SPEC §9.1, rule 1).
+ *
+ * This is an explicit alias of {@link envelopeKey} with a transport-specific
+ * name so call sites are self-documenting.
+ *
+ * @example envelopeMetaKey('auth', 'session') // → 'x-auth-session'
+ */
+export declare const envelopeMetaKey: typeof envelopeKey;
+/**
+ * Sanitizes an arbitrary id (e.g. a discovered package id, derived verbatim
+ * from a source directory name) into a valid TypeScript/JavaScript identifier
+ * for use in generated import-namespace / variable-name positions.
+ *
+ * Repo convention mandates hyphenated package names (`dispatch-cli`,
+ * `pkg-a`, …), so any generator that splices an id directly into an
+ * identifier position (`import * as ${id}_ns from …`) produces a hard parse
+ * error (`Expected "from" but found "-"`) the moment a hyphenated id is
+ * used. This is the single source of truth for that sanitisation — no
+ * transport-specific plugin may re-derive its own copy (BUG-APIGEN-032).
+ *
+ * Only the emitted *identifier* positions need sanitizing — the raw id
+ * should still be used verbatim anywhere it appears as a string literal
+ * (e.g. a schema-key namespace like `'dispatch-cli:validate'`).
+ *
+ * @example sanitizeIdentifier('dispatch-cli') // → 'dispatch_cli'
+ * @example sanitizeIdentifier('pkg-a')        // → 'pkg_a'
+ * @example sanitizeIdentifier('123abc')       // → '_123abc'
+ */
+export declare function sanitizeIdentifier(id: string): string;

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@adhd/apigen-engine-naming",
+  "version": "0.1.1",
+  "dependencies": {
+    "@adhd/apigen-core-client": "^0.1.0"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}