@adhd/apigen-core-client 0.1.0

package/lib/schema-builders/ts-json-schema.d.ts

@@ -0,0 +1,65 @@
+import { InternalExtractionSession } from '../extraction-session';
+import { Project, SourceFile } from 'ts-morph';
+
+/**
+ * Canonical JSON-Schema fragments for TS built-in scalar types.
+ * Keyed by the exact type-text string the extractor emits.
+ *
+ * Mappings follow §3 / §12–13 of the apigen-logical-types DESIGN:
+ *   Date        → format:date-time  (RFC 3339 UTC; Date.prototype.toJSON already emits this)
+ *   bigint      → format:int64      (decimal string to avoid JS f64 precision loss)
+ *   Uint8Array  → format:byte       (base64 standard + padding)
+ *   Buffer      → format:byte       (Node.js Buffer; same wire as Uint8Array)
+ *   URL         → format:uri
+ *   RegExp      → format:regex
+ *   Decimal     → format:decimal    (decimal.js Decimal; arbitrary-precision decimal string)
+ *
+ * Map / Set are handled in later states (lt-extract-nominal / lt-scalars).
+ *
+ * NOTE on Decimal: ts-morph emits different type-text strings for the same
+ * Decimal class depending on how the user imports it:
+ *   - `import { Decimal } from 'decimal.js'`  → `"Decimal"`  (keyed directly below)
+ *   - `import Decimal from 'decimal.js'`       → qualified import path like
+ *     `import("/path/to/decimal.js/decimal").default`
+ *   - `import { Decimal as D2 } from 'decimal.js'` / `import D2 from 'decimal.js'`
+ *                                              → `"D2"` (local alias)
+ * All forms are normalised to the "Decimal" key before this map is consulted:
+ *   - qualified-import form: handled by `normalizeTypeText` regex
+ *   - alias form:            handled by the alias map from `extractScalarAliases`
+ * See `normalizeTypeText` and `extractScalarAliases`.
+ */
+export declare const SCALAR_SCHEMAS: Readonly<Record<string, Record<string, unknown>>>;
+/**
+ * Scan a source file's import declarations and return a map of
+ *   `localName → canonicalScalarKey`
+ * for any import whose module specifier is in MODULE_SCALAR_MAP and whose
+ * local name differs from the canonical key.
+ *
+ * Examples:
+ *   `import { Decimal as D2 } from 'decimal.js'`  → { D2: 'Decimal' }
+ *   `import MyDec from 'decimal.js'`               → { MyDec: 'Decimal' }
+ *   `import Decimal from 'decimal.js'`             → {}  (no alias needed)
+ *   `import { Decimal } from 'decimal.js'`         → {}  (no alias needed)
+ *
+ * The returned map is consumed by normalizeTypeText and morphFallback so that
+ * aliased external scalar types are recognised at ANY nesting depth.
+ */
+export declare function extractScalarAliases(sf: SourceFile): ReadonlyMap<string, string>;
+/**
+ * Attempts ts-json-schema-generator first; falls back to morphFallback for
+ * inline/anonymous types.
+ *
+ * When `session` is supplied, results are memoized per
+ * `(sourceFile, tsconfig, typeText)` for the session's lifetime — the
+ * orchestrator's extract + generateSchemas double pass over the same file, and
+ * repeated parameter types across functions, all become Map hits. Cached
+ * fragments are shared by reference; callers treat schemas as immutable.
+ *
+ * BUG-APIGEN-CORE-003 (cache-stampede fix): `session.schemaCache` stores the
+ * in-flight/resolved `Promise<Schema>` itself — not just the resolved value
+ * — and stores it SYNCHRONOUSLY before anything is awaited, so concurrent
+ * identical requests (e.g. `morph-walk.ts`'s `Promise.all` over union
+ * variants) join ONE computation instead of each redundantly recomputing.
+ * See the in-function comments below for the mechanism.
+ */
+export declare function buildSchema(_project: Project, sf: SourceFile, typeText: string, tsconfig?: string, session?: InternalExtractionSession, _ancestors?: ReadonlySet<string>): Promise<Record<string, unknown>>;

package/lib/schema-builders/union.d.ts

@@ -0,0 +1,74 @@
+import { X_APIGEN_LOGICAL } from '@adhd/apigen-base-logical';
+
+/**
+ * One variant of a discriminated union.
+ *
+ *   - `className`       the PascalCase class name matching its `$defs` key
+ *                       (produced by `buildNominalSchema`'s `defKey` output).
+ *   - `discriminantValue` the literal string value of the discriminant property
+ *                       on this variant (e.g. `"dog"` for `kind:"dog"`).
+ */
+export interface UnionVariant {
+    /** The class name — must match the `$defs` key produced by `nominal.ts`. */
+    className: string;
+    /**
+     * The literal discriminant value for this variant (the `const` value on the
+     * discriminant property in the variant's $def, e.g. `"dog"` for `kind:"dog"`).
+     */
+    discriminantValue: string;
+}
+/**
+ * Everything `buildUnionSchema` needs to emit the union fragment.
+ */
+export interface UnionInfo {
+    /**
+     * Name of the shared const-tag property that discriminates the variants,
+     * e.g. `"kind"`.
+     */
+    discriminatorPropertyName: string;
+    /** Ordered list of union variants; must contain at least two entries. */
+    variants: UnionVariant[];
+}
+/**
+ * The JSON Schema fragment for a discriminated union per DESIGN §4.1:
+ *
+ * ```json
+ * {
+ *   "oneOf": [ {"$ref":"#/$defs/Dog"}, {"$ref":"#/$defs/Cat"} ],
+ *   "discriminator": {
+ *     "propertyName": "kind",
+ *     "mapping": { "dog": "#/$defs/Dog", "cat": "#/$defs/Cat" }
+ *   },
+ *   "x-apigen-logical": "union"
+ * }
+ * ```
+ */
+export interface UnionSchema {
+    oneOf: Array<{
+        $ref: string;
+    }>;
+    discriminator: {
+        propertyName: string;
+        mapping: Record<string, string>;
+    };
+    [X_APIGEN_LOGICAL]: 'union';
+}
+/**
+ * Given a discriminated-union descriptor, emit the canonical OpenAPI-compatible
+ * `oneOf` + `discriminator` + `x-apigen-logical:"union"` schema fragment.
+ *
+ * Each variant is referenced via `$ref` (`#/$defs/<ClassName>`) — the caller is
+ * responsible for ensuring each variant's `$def` is registered in the descriptor
+ * (via `buildNominalSchema` from `nominal.ts`).
+ *
+ * Per DESIGN §4.1 `[inv:hints-advisory]`: `x-apigen-logical:"union"` is advisory.
+ * The structural contract (the `oneOf` + `discriminator`) is the authoritative
+ * wire representation and MUST be usable without the `x-apigen-*` key.
+ *
+ * @throws {Error} When `variants` is empty or contains a single entry (a
+ *   one-variant "union" is not a union).
+ *
+ * @param info - Discriminated union descriptor.
+ * @returns The `oneOf` + `discriminator` schema fragment for inline use.
+ */
+export declare function buildUnionSchema(info: UnionInfo): UnionSchema;

package/lib/source-language.d.ts

@@ -0,0 +1,81 @@
+import { PluginLanguage } from './types';
+
+/**
+ * Derive the canonical {@link PluginLanguage} tag for a source file from its
+ * extension.
+ *
+ * Returns `undefined` when the extension is not recognised — callers should
+ * treat an unknown extension as "no plugin will consume this file" rather than
+ * guessing.
+ *
+ * @example
+ * ```ts
+ * languageOfSource('src/api.ts')   // → 'ts'
+ * languageOfSource('src/api.tsx')  // → 'ts'
+ * languageOfSource('src/api.py')   // → 'py'
+ * languageOfSource('src/api.go')   // → 'go'
+ * languageOfSource('README.md')    // → undefined
+ * ```
+ */
+export declare function languageOfSource(file: string): PluginLanguage | undefined;
+/**
+ * The minimal plugin shape that the routing helpers need to inspect.
+ *
+ * Both the v1 `OutputPlugin` and the v2 `Plugin` satisfy this interface
+ * because `language` is defined on both (as an optional field).
+ */
+export interface LanguageAwarePlugin {
+    /** @see {@link PluginLanguage} */
+    language?: PluginLanguage;
+}
+/**
+ * Return the effective language for a plugin — the declared `language` if set,
+ * or `'ts'` as the documented default for back-compat.
+ *
+ * @param plugin - Any plugin that may declare `language`.
+ */
+export declare function effectiveLanguage(plugin: LanguageAwarePlugin): PluginLanguage;
+/**
+ * Returns `true` when the given plugin should consume `file`.
+ *
+ * A plugin consumes a file when:
+ *   1. The file's extension maps to a known {@link PluginLanguage}, AND
+ *   2. That language matches the plugin's effective language (declared or
+ *      defaulting to `'ts'`).
+ *
+ * Files with unrecognised extensions are never routed to any plugin.
+ *
+ * @param plugin - The plugin to test.
+ * @param file   - Absolute or relative path to the source file.
+ *
+ * @example
+ * ```ts
+ * pluginConsumesSource({ language: 'ts' }, 'src/api.ts')  // → true
+ * pluginConsumesSource({ language: 'ts' }, 'src/api.py')  // → false
+ * pluginConsumesSource({ language: 'py' }, 'src/api.py')  // → true
+ * pluginConsumesSource({},                 'src/api.ts')  // → true  (default 'ts')
+ * ```
+ */
+export declare function pluginConsumesSource(plugin: LanguageAwarePlugin, file: string): boolean;
+/**
+ * Filter `files` to the subset whose language matches the given plugin.
+ *
+ * This is the primary entry-point for the `serve` command's dispatch loop:
+ * call once per plugin to obtain the slice of changed/watched files it should
+ * re-process.
+ *
+ * @param plugin - The plugin to route for.
+ * @param files  - All candidate source files.
+ * @returns        The subset of `files` the plugin should consume (may be empty).
+ *
+ * @example
+ * ```ts
+ * const all = ['src/api.ts', 'src/api.py', 'src/utils.mts', 'README.md']
+ * sourcesForPlugin({ language: 'ts' }, all)
+ * // → ['src/api.ts', 'src/utils.mts']
+ *
+ * sourcesForPlugin({ language: 'py' }, all)
+ * // → ['src/api.py']
+ * ```
+ */
+export declare function sourcesForPlugin(plugin: LanguageAwarePlugin, files: readonly string[]): string[];

package/lib/types.d.ts

@@ -0,0 +1,87 @@
+import { Operation } from './descriptor';
+import { Logger } from 'pino';
+
+export interface GeneratedSchemas {
+    metadata: {
+        namespace: string;
+        phase: string;
+    };
+    schemas: Record<string, {
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+        hasCtx?: boolean;
+        safe?: boolean;
+    }>;
+}
+export type ComposedSchemas = Record<string, {
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    hasCtx?: boolean;
+    'x-apigen-safe'?: boolean;
+}>;
+export type ExportMode = {
+    type: 'named';
+} | {
+    type: 'default';
+} | {
+    type: 'named-object';
+    name: string;
+};
+export interface PluginInput {
+    packages: Array<{
+        id: string;
+        schemas: ComposedSchemas;
+        importPath: string;
+        fns?: Record<string, (...args: unknown[]) => unknown>;
+        createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+    }>;
+    outputDir: string;
+    options: Record<string, unknown>;
+    /**
+     * Shared structured logger (pino). Built once by the CLI and threaded through
+     * the pipeline + plugins. Always targets stderr or a file — never stdout —
+     * so the MCP stdio JSON-RPC channel stays clean. Plugins should fall back to
+     * a default stderr logger when this is absent.
+     */
+    logger?: Logger;
+}
+export interface PluginOutput {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    postCommands?: string[];
+}
+export interface RunInput extends PluginInput {
+    signal?: AbortSignal;
+    /**
+     * BUG-APIGEN-024: the full merged `Operation[]` descriptor (the same set
+     * `buildDescriptor()` produces), threaded through so a `--use` mount plugin
+     * (e.g. `apigen-plugin-openapi`) can build its real `Descriptor` instead of
+     * the empty-`operations` stub `collectMountRoutes()` used to synthesize.
+     * Absent for non-TS-extraction run paths (e.g. py-flask), where mount
+     * plugins have nothing extracted to describe.
+     */
+    operations?: Operation[];
+}
+/** Source-language tags understood by apigen's routing layer. */
+export type PluginLanguage = 'ts' | 'py' | 'rust' | 'go' | 'java';
+export interface OutputPlugin {
+    id: string;
+    description: string;
+    /**
+     * The source language this plugin consumes.
+     *
+     * Used by the `serve` command to route each source file to the plugin(s)
+     * whose `language` matches its extension (`.ts`/`.tsx`/`.mts`/`.cts` → `'ts'`,
+     * `.py` → `'py'`, etc.).
+     *
+     * Defaults to `'ts'` when omitted for backward-compatibility with plugins
+     * authored before this field was introduced.  All first-party plugins
+     * explicitly declare `language: 'ts'`.
+     */
+    language?: PluginLanguage;
+    optionsSchema?: Record<string, unknown>;
+    generate(input: PluginInput): PluginOutput | Promise<PluginOutput>;
+    run?(input: RunInput): Promise<void>;
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@adhd/apigen-core-client",
+  "version": "0.1.0",
+  "dependencies": {
+    "ts-morph": "^23.0.0",
+    "ts-json-schema-generator": "^2.3.0",
+    "pino": "10.3.1",
+    "typescript": "^6.0.3",
+    "@adhd/apigen-base-logical": "^0.0.1"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}