@adhd/apigen-core-client 0.1.0

package/lib/apigen-core.d.ts

@@ -0,0 +1 @@
+export declare function apigenCore(): string;

package/lib/compose-schemas.d.ts

@@ -0,0 +1,31 @@
+import { GeneratedSchemas, ComposedSchemas } from './types';
+
+interface SlimMiddleware {
+    id: string;
+    envelope?: Record<string, unknown>;
+}
+/**
+ * Merges domain schemas with middleware envelope fields.
+ *
+ * The `data: {}` wrapper **property** is always present, even for zero-param
+ * functions, so `{"data": {}}` still validates for callers who send it out of
+ * habit or symmetry. FEAT-APIGEN-023: the wrapper is only listed in the outer
+ * `required` array when the function actually has ≥1 required domain param
+ * (`domainRequired.length > 0`) — mirroring the exact same condition already
+ * used for the nested `data` schema's own `required`. A truly zero-parameter
+ * function's published schema therefore does not force callers to send an
+ * empty `data: {}` (or the whole envelope, if no middleware requires anything
+ * else). Override a middleware with `false` to suppress its envelope
+ * contribution for a specific function [inv:false-suppresses-middleware].
+ *
+ * BUG-APIGEN-017: both the top-level (envelope + data) object and the nested
+ * `data` object are generated with `additionalProperties: false` so MCP hosts
+ * (and any other JSON-Schema-validating consumer) reject unknown parameters
+ * instead of silently discarding them.
+ *
+ * BUG-APIGEN-020: the top-level schema also carries a `description` that
+ * documents the `data` envelope + any transport-envelope fields — see
+ * {@link buildEnvelopeDescription}.
+ */
+export declare function composeSchemas(domainSchemas: GeneratedSchemas, middlewares: ReadonlyArray<SlimMiddleware>, overrides?: Record<string, Record<string, boolean>>): ComposedSchemas;
+export {};

package/lib/descriptor.d.ts

@@ -0,0 +1,220 @@
+/**
+ * A JSON-Schema-2020-12 document fragment.
+ *
+ * The apigen type IR **is** JSON Schema 2020-12 with `$defs`/`$ref` — there is
+ * no separate or abstract type model and no new IR (SPEC §4, §16). Named types,
+ * discriminated unions / enum-with-data / `Result`/`Option` (`oneOf` + a `const`
+ * tag + `$ref`), nominal/branded types (a named `$def`), and recursion (`$ref`)
+ * are all represented here faithfully — exactly what `ts-json-schema-generator`
+ * and `schemars` already emit.
+ *
+ * Conventions baked into this IR:
+ * - **Big-int / decimal wire convention:** 64-bit integers and decimals exceed
+ *   JSON's `f64`, so they are **string-encoded** as `{ type: 'string', format:
+ *   'int64' }` (a serialization convention, not a schema-expressiveness gap).
+ * - **Optional extractor-derived hints** live under `x-apigen-*` keys (see
+ *   {@link ApigenSchemaHints}) and exist only so codegen can emit idiomatic
+ *   (vs accurate-but-verbose) clients; they are never required for correctness
+ *   and are never sourced from a source annotation (Tenet 1).
+ *
+ * Modeled as an open record because a JSON Schema is, structurally, an arbitrary
+ * keyword object. This mirrors how `input`/`output` are already typed in
+ * {@link GeneratedSchemas} / {@link ComposedSchemas} (`Record<string, unknown>`).
+ */
+export type JSONSchema = Record<string, unknown> & {
+    /** Reusable type definitions referenced via `$ref` (`#/$defs/Name`). */
+    $defs?: Record<string, JSONSchema>;
+    /**
+     * Reusable type definitions under the draft-07 spelling, referenced via
+     * `$ref` (`#/definitions/Name`). `ts-json-schema-generator` — the only
+     * `$ref`/definitions producer in this codebase today — always emits this
+     * key, never `$defs`; both are recognized structurally by extract.ts's
+     * `hoistNestedDefs` / compose-schemas.ts (BUG-APIGEN-029) and by Ajv.
+     */
+    definitions?: Record<string, JSONSchema>;
+    /** Reference to a definition, e.g. `#/$defs/User` (enables recursion). */
+    $ref?: string;
+} & ApigenSchemaHints;
+/**
+ * Optional, **extractor-derived** codegen hints carried inline on a
+ * {@link JSONSchema} (SPEC §4). These are advisory: a plugin MAY use them to
+ * emit idiomatic clients (e.g. a real enum, a branded type) and a codegen MAY
+ * warn on an unresolved generic — but correctness never depends on them, and
+ * they are never required. They are computed by the extractor, never written by
+ * a human in source (Tenet 1).
+ */
+export interface ApigenSchemaHints {
+    /**
+     * Marks a `$def` that originated from a nominal / branded type. Validation
+     * deliberately does NOT enforce nominality — on the wire a branded type *is*
+     * its base type — but codegen can re-introduce the brand for ergonomics.
+     */
+    'x-apigen-nominal'?: boolean;
+    /**
+     * How an enum-like type should be represented in idiomatic codegen, e.g. a
+     * native enum vs a string-literal union. Advisory only.
+     */
+    'x-apigen-enum-repr'?: 'enum' | 'union' | string;
+    /**
+     * Fidelity of this schema fragment relative to the source type:
+     * - `'full'`   — the schema captures the source type without loss.
+     * - `'lossy'`  — the source type could not be fully represented (the only
+     *   true residual is generic *factoring*: an unconstrained generic operation
+     *   isn't serializable, so it is out of scope by physics). Codegen MAY warn.
+     *
+     * Optional; absence means `'full'`.
+     */
+    fidelity?: 'full' | 'lossy';
+}
+/**
+ * A casing-neutral name segment (SPEC §4/§5).
+ *
+ * Identity is carried by the tokenized `words`; the original `raw` spelling is
+ * preserved so a same-host plugin can reproduce it, but every transport derives
+ * its own casing from `words` via `@adhd/apigen-naming` (kebab for HTTP/CLI,
+ * `_`-joined for MCP, Pascal for gRPC). Casing is therefore per-plugin, never
+ * baked into the descriptor.
+ */
+export interface Segment {
+    /** Original spelling as it appeared in source, e.g. `'humanizeBytes'`. */
+    raw: string;
+    /** Tokenized, lower-cased words, e.g. `['humanize', 'bytes']`. */
+    words: string[];
+}
+/**
+ * Language-tagged textual rendering of a type — optional same-host *sugar*
+ * (SPEC §4). For a TypeScript host this is the literal TS source of the type;
+ * non-host targets ignore it and rely on {@link JSONSchema} (`input`/`output`)
+ * instead. `null` when no textual form is available/relevant.
+ */
+export interface TypeText {
+    /** Language tag for `input`/`output` text, e.g. `'ts'`. */
+    lang: string;
+    /** Textual rendering of the input/params type. */
+    input: string;
+    /** Textual rendering of the output/return type (unwrapped). */
+    output: string;
+}
+/**
+ * Classification of an exported binding (SPEC §4).
+ *
+ * - `'action'`          — a callable export (function declaration, or an
+ *   arrow/const function). Served by invoking it.
+ * - `'query'`           — a **serializable-data** const (primitive or plain
+ *   serializable object/array — no functions / non-serializable values). Served
+ *   **live**: the descriptor carries the const's *type* (schema), not its value,
+ *   so env-/compute-dependent consts are never stale-at-extract.
+ * - `'constructor'`     — a class constructor (class export; see SPEC §10).
+ * - `'instance-method'` — a method on an exported class instance (SPEC §10).
+ *
+ * A non-serializable, non-callable export is **skipped + warned**, never
+ * emitted as an operation.
+ */
+export type OperationKind = 'action' | 'query' | 'constructor' | 'instance-method';
+/**
+ * The canonical operation descriptor — the neutral contract every extractor
+ * emits and every plugin consumes (SPEC §4).
+ *
+ * One `Operation` corresponds to one selected export (an `action`, a live
+ * `query`, or a class member per §10). The descriptor is host-agnostic: a
+ * TypeScript extractor, a Python extractor, and a Rust extractor all emit the
+ * same shape, and a single plugin can project a merged set of `Operation`s into
+ * any transport.
+ *
+ * @remarks
+ * The type IR for `input`/`output`/`envelope` is JSON Schema 2020-12 with
+ * `$defs`/`$ref` (see {@link JSONSchema}) — there is no separate IR.
+ */
+export interface Operation {
+    /**
+     * The canonical fully-qualified slug and cross-plugin reference key, derived
+     * purely from `namespace`/`path`, e.g. `'transform/humanize/humanize-bytes'`.
+     * Globally unique within a merged descriptor and never re-cased.
+     *
+     * **Deterministic, NOT refactor-stable.** Because `id` is a pure function of
+     * `namespace`/`path`, the same source always yields the same `id` — but moving
+     * or renaming a file/export re-mints it (and thus breaks any pinned
+     * `--exclude` id or generated client that referenced the old slug). This is
+     * accepted and documented; refactor-stability is an explicit **non-goal**. It
+     * is deliberately **not** papered over with a source `@id` annotation, which
+     * Tenet 1 forbids.
+     */
+    id: string;
+    /**
+     * The owning language runtime / host for this operation, e.g. `'ts'`,
+     * `'py'`, `'rust'`. Identifies which host's extractor produced it and which
+     * host can serve it same-process. Polyglot descriptors mix hosts.
+     */
+    host: string;
+    /**
+     * The package segment — sourced from `--namespace` or the tsconfig folder
+     * (SPEC §4/§5). Casing-neutral; transports derive their own casing from
+     * {@link Segment.words}.
+     */
+    namespace: Segment;
+    /**
+     * The hierarchical identity path: file → export… (SPEC §4/§5). For example a
+     * named export is `[file, name]`; a single default function is `[file]`; a
+     * default *object* is `[file, 'default', ...keys]` recursing into nested
+     * props. `index.*` drops its file segment. Each element is casing-neutral.
+     */
+    path: Segment[];
+    /** Classification of the underlying export — see {@link OperationKind}. */
+    kind: OperationKind;
+    /** True if the export is async (returns a `Promise`). */
+    async: boolean;
+    /**
+     * True if the export returns an `AsyncIterable` / `Generator` / `Stream`
+     * (streaming is implemented in v2, SPEC §11). The `output` schema describes
+     * the per-chunk element type with streaming unwrapped.
+     */
+    streaming: boolean;
+    /**
+     * Idempotent / no-side-effects hint (SPEC §4/§5).
+     *
+     * **Defaults from `kind`** (`query` → `true`, `action` → `false`) and is
+     * **overridable at projection time via config** (`--opt http.verb.<id>=GET`
+     * or `apigen.config`), never via a source annotation (Tenet 1). Drives the
+     * HTTP verb + cacheability (safe → GET, unsafe → POST) and gRPC
+     * idempotency-level (SPEC §5), decoupling the wire method from `kind`.
+     */
+    safe: boolean;
+    /**
+     * The params object as JSON Schema 2020-12 (see {@link JSONSchema}).
+     *
+     * This is the operation's input type directly: the `ctx` first param is
+     * excluded (by name match only, per the `ctx-name-only` invariant) and the
+     * middleware `data`-wrapper is **dissolved** — `input` is the bare domain
+     * params object, not the composed envelope. The request-side envelope lives
+     * separately in `envelope`.
+     */
+    input: JSONSchema;
+    /**
+     * The return type as JSON Schema 2020-12 (see {@link JSONSchema}), with
+     * `Promise<T>` and stream wrappers **unwrapped to `T`**. For a streaming
+     * operation this is the per-chunk element type.
+     */
+    output: JSONSchema;
+    /**
+     * The effective request-side envelope as JSON Schema 2020-12 — the
+     * middleware-contributed side-channel for this operation (e.g. a `session`
+     * field), merged across the active middleware with overrides applied. Empty
+     * (no envelope fields) when no middleware contributes to this operation.
+     */
+    envelope: JSONSchema;
+    /**
+     * Optional language-tagged textual type rendering (same-host sugar). `null`
+     * when unavailable; non-host targets ignore it. See {@link TypeText}.
+     */
+    typeText: TypeText | null;
+    /**
+     * True when the underlying export's first parameter is named `ctx`
+     * ([inv:ctx-name-only] — matched by name only, never by type). `ctx` is
+     * excluded from `input` like every other framework param, but this flag
+     * lets a runtime dispatcher re-inject it as the first call argument
+     * (BUG-APIGEN-001) — without it a caller with no session middleware would
+     * have its first REAL domain arg land in the `ctx` slot. Only meaningful
+     * for `kind: 'action'`; absent (`undefined`) for `query` and other kinds.
+     */
+    hasCtx?: boolean;
+}

package/lib/extract-classes.d.ts

@@ -0,0 +1,37 @@
+import { ExtractionSession } from './extraction-session';
+import { Operation } from './descriptor';
+
+export interface ExtractClassesOptions {
+    /** Absolute path to the TypeScript (or JavaScript) source file. */
+    sourceFile: string;
+    /**
+     * Namespace segment (from `--namespace` or tsconfig folder). Casing-neutral
+     * words are derived from the raw string. Defaults to `''`.
+     */
+    namespace?: string;
+    /** Absolute path to a tsconfig.json for type resolution. Optional. */
+    tsconfig?: string;
+    /**
+     * When true, extract constructor + instance-method ops in addition to static
+     * method ops. Off by default (opt-in per SPEC §10).
+     */
+    includeInstances?: boolean;
+    /**
+     * Optional per-run shared cache (see `createExtractionSession` in
+     * `@adhd/apigen-core-client). When absent, a private session is created and
+     * disposed before returning (previous behaviour, no retention).
+     */
+    session?: ExtractionSession;
+}
+/**
+ * Walks `opts.sourceFile` and emits canonical `Operation[]` descriptors for
+ * all exported class members per SPEC §10.
+ *
+ * Static methods are always extracted (they are stateless function-shaped ops).
+ * Constructor + instance methods require `opts.includeInstances = true`.
+ *
+ * @param opts - Extraction options.
+ * @returns Resolved array of canonical operations (static ops + optionally
+ *   constructor + instance-method ops).
+ */
+export declare function extractClasses(opts: ExtractClassesOptions): Promise<Operation[]>;

package/lib/extract.d.ts

@@ -0,0 +1,43 @@
+import { ExtractionSession } from './extraction-session';
+import { Operation } from './descriptor';
+
+export interface ExtractOptions {
+    /** Absolute path to the TypeScript (or JavaScript) source file. */
+    sourceFile: string;
+    /**
+     * Namespace segment (from `--namespace` or tsconfig folder). Casing-neutral
+     * words are derived from the raw string. Defaults to `''`.
+     */
+    namespace?: string;
+    /** Absolute path to a tsconfig.json for type resolution. Optional. */
+    tsconfig?: string;
+    /**
+     * Optional per-run shared cache (see {@link createExtractionSession}).
+     * When supplied, the ts-morph Project, built schema generators, and computed
+     * schemas are shared with every other extraction call in the same run — and
+     * released together by `session.dispose()`. When absent, a private session is
+     * created and disposed before returning (previous behaviour, no retention).
+     */
+    session?: ExtractionSession;
+}
+/**
+ * Walks `opts.sourceFile` and emits canonical `Operation[]` descriptors.
+ *
+ * Handles all six shapes in the export-shape matrix. Each operation is named
+ * by the **exported symbol** in source — never by position or internal name.
+ *
+ * @param opts - Extraction options.
+ * @returns Resolved array of canonical operations.
+ */
+export declare function extract(opts: ExtractOptions): Promise<Operation[]>;
+/**
+ * Tokenises a camelCase / PascalCase / kebab-case / snake_case identifier into
+ * lower-cased words. Used to build casing-neutral {@link Segment} records.
+ *
+ * Examples:
+ *   'humanizeBytes'   → ['humanize', 'bytes']
+ *   'HTMLParser'      → ['html', 'parser']
+ *   'my-util'         → ['my', 'util']
+ *   'SOME_CONST'      → ['some', 'const']
+ */
+export declare function tokenize(raw: string): string[];

package/lib/extraction-session.d.ts

@@ -0,0 +1,97 @@
+import { Project, SourceFile } from 'ts-morph';
+
+/** Counters proving how much work a session actually did — used by perf regression tests. */
+export interface ISessionStats {
+    /** ts-morph Projects constructed (one per distinct tsconfig per session). */
+    projectsBuilt: number;
+    /** ts-json-schema-generator generators (full TS programs) constructed. */
+    generatorsBuilt: number;
+    /**
+     * buildSchema calls answered from the session schema cache — includes both
+     * a call that found an already-RESOLVED entry and a call that joined an
+     * already-IN-FLIGHT promise for the same key (BUG-APIGEN-CORE-003:
+     * in-flight dedup — see `schemaCache`'s doc comment below).
+     */
+    schemaCacheHits: number;
+    /** buildSchema calls that had to start a new computation (cache miss). */
+    schemaCacheMisses: number;
+}
+/**
+ * A per-run cache shared across `extract()` / `extractClasses()` / the
+ * orchestrator. Create one per logical run with
+ * {@link createExtractionSession}, pass it to every extraction call in that
+ * run, and `dispose()` it when the run's outputs have been consumed.
+ *
+ * Passing a session is optional everywhere — calls without one create a
+ * private session internally and dispose it before returning, so existing
+ * consumers are unaffected.
+ */
+export interface ExtractionSession {
+    /** Drop every cached Project / generator / schema so the run's memory is collectible. */
+    dispose(): void;
+    /** Live work counters (see {@link ISessionStats}). */
+    readonly stats: ISessionStats;
+}
+/** Cached built generator entry: `version` is the file's `mtimeMs:size` snapshot. */
+export type BuiltGenerator = {
+    createSchema(type: string): unknown;
+};
+type GeneratorEntry = {
+    version: string;
+    gen: BuiltGenerator;
+};
+declare const INTERNAL: unique symbol;
+/** Full internal surface — package-private (not exported from the index). */
+export interface InternalExtractionSession extends ExtractionSession {
+    [INTERNAL]: true;
+    /** One ts-morph Project per distinct tsconfig path ('' for none). */
+    projectFor(tsconfig?: string): Project;
+    /** Add-or-reuse the SourceFile for `filePath` in the session's Project. */
+    sourceFileFor(filePath: string, tsconfig?: string): SourceFile;
+    /**
+     * Memoized buildSchema results, key = `${sfPath}\0${tsconfig ?? ''}\0${typeText}`.
+     *
+     * BUG-APIGEN-CORE-003: values are the in-flight/resolved `Promise`, not the
+     * resolved value itself, and are stored SYNCHRONOUSLY (before the underlying
+     * computation is awaited) — this is what makes concurrent identical requests
+     * (e.g. `morph-walk.ts`'s `Promise.all(members.map(...))` over union variants
+     * that share a nested type like `SharedArrayBuffer`) share one computation
+     * instead of each independently missing the cache and recomputing. See
+     * `buildSchema()` in `schema-builders/ts-json-schema.ts` for the write side.
+     */
+    readonly schemaCache: Map<string, Promise<Record<string, unknown>>>;
+    /** Memoized per-SourceFile import-alias maps (extractScalarAliases). */
+    readonly aliasCache: WeakMap<SourceFile, ReadonlyMap<string, string>>;
+    /** Memoized per-SourceFile zod-import check (sourceFileHasZodImport). */
+    readonly zodImportCache: WeakMap<SourceFile, boolean>;
+    /** One built generator per `${path}\0${tsconfig ?? ''}` — latest version only. */
+    readonly generatorCache: Map<string, GeneratorEntry>;
+    /** Memoized `mtimeMs:size` snapshot per file path (a run is a snapshot). */
+    statVersion(pathStr: string): string;
+}
+/** Compute a file's `mtimeMs:size` version string (uncached). */
+export declare function fileVersion(pathStr: string): string;
+/** Persistent-schema accessor for buildSchema (package-private).
+ *
+ * Computes a composite version stamp that includes the entry file's version
+ * AND the versions of all referenced files tracked by the persistent Project
+ * tier.  Previously only the entry file's version was checked, so a type
+ * imported from another file that changed without the entry file changing was
+ * not detected (DEBT-APIGEN-CACHE-001).
+ */
+export declare function persistentSchemasFor(sfPath: string, tsconfig: string | undefined, version: string): Map<string, Record<string, unknown>>;
+/** Drop the process-lifetime Project + schema caches (tests / explicit memory reclaim). */
+export declare function clearPersistentProjectCache(): void;
+/**
+ * Create a fresh {@link ExtractionSession}.
+ *
+ * One session = one run = one snapshot of the source tree. Reusing a session
+ * across file edits is unsupported by design (invalidation is "new session").
+ */
+export declare function createExtractionSession(): ExtractionSession;
+/**
+ * Recover the internal surface from a public {@link ExtractionSession}.
+ * Package-private — deliberately NOT exported from the package index.
+ */
+export declare function internalSession(session: ExtractionSession): InternalExtractionSession;
+export {};

package/lib/get-safety.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Structural check over a bare domain-input JSON Schema — the exact shape
+ * carried as `Operation.input` (and, unchanged, as `GeneratedSchemas.schemas
+ * [fn].input` — orchestrator.ts's Step 5 passes `op.input` straight through):
+ * `{ type: 'object', properties, required }`.
+ *
+ * Returns `true` iff every declared property is a "properly typed primitive"
+ * (`string`/`number`/`boolean`/`integer`, optionally unioned with `null`) —
+ * including the zero-property case (vacuously true). Absence of a
+ * `properties` key at all (as opposed to an explicit empty object) is NOT the
+ * same as zero params — it means the input shape was never populated, so this
+ * returns `false` rather than assume eligibility.
+ */
+export declare function isPrimitiveOnlyInputSchema(input: Record<string, unknown> | undefined | null): boolean;

package/lib/param-defaults.d.ts

@@ -0,0 +1,36 @@
+import { Node, ParameterDeclaration } from 'ts-morph';
+
+/**
+ * Extracts the raw source text of a parameter's default value.
+ *
+ * @param paramDecl - The parameter's own declaration, when resolvable (may be
+ *   `null`/`undefined` for parameters reached only through a `Signature`
+ *   whose declaration could not be narrowed to a `ParameterDeclaration`).
+ * @param paramName - The parameter's name, used to match a JSDoc `@param` tag.
+ * @param jsDocSource - The enclosing function-like node (FunctionDeclaration,
+ *   VariableStatement, ExportAssignment, …) whose leading JSDoc comment may
+ *   carry a bracketed default for this parameter.
+ * @returns The raw default-value text (e.g. `"'auto'"`, `"0"`, `"false"`), or
+ *   `undefined` when no default could be found.
+ */
+export declare function extractParamDefault(paramDecl: ParameterDeclaration | null | undefined, paramName: string, jsDocSource?: Node | null): string | undefined;
+/**
+ * Coerces a raw TS/JSDoc default-value literal into a properly-typed JSON
+ * value so it can be emitted verbatim as a JSON-Schema `default`.
+ *
+ * Handles quoted string literals (`'auto'`, `"auto"`, `` `auto` ``), the
+ * `true`/`false`/`null` keywords, numeric literals, and falls back to
+ * `JSON.parse` (array/object literals) before giving up and returning the
+ * trimmed raw text (e.g. an enum-member reference apigen can't evaluate
+ * statically).
+ */
+export declare function coerceDefaultLiteral(raw: string): unknown;
+/**
+ * Applies an extracted default onto a built parameter schema in place:
+ * sets the native JSON-Schema `default` keyword and appends a human-readable
+ * `(default: <value>)` note to `description` (preserving any existing text).
+ *
+ * A no-op when the coerced value is `undefined` (an explicit `= undefined`
+ * initializer carries no useful default to advertise).
+ */
+export declare function applyParamDefault(schema: Record<string, unknown>, rawDefault: string): void;