@adhd/apigen-core-client 0.2.1 → 0.3.0

package/lib/extract-invoker.d.ts

@@ -0,0 +1,90 @@
+import { Plugin } from './plugin';
+import { Operation } from './descriptor';
+
+/**
+ * One source unit to extract. Deliberately host-neutral — describes WHAT is
+ * being extracted, not HOW (no ts-morph/ts-json-schema-generator names leak
+ * in; a future per-language subprocess extractor speaks the same shape).
+ */
+export interface ExtractCall {
+    /**
+     * Absolute path to the source artifact for this language's extractor (a
+     * `.d.ts`/`.ts` file today; a directory/module root for a future
+     * subprocess-based extractor — the contract doesn't care which).
+     */
+    source: string;
+    /** Declared owning language runtime tag, e.g. 'ts' | 'py' | 'rust' (SPEC §4 host). */
+    host: string;
+    /** Namespace segment (SPEC §4). Casing-neutral. */
+    namespace?: string;
+    /**
+     * Free-form, extractor-specific options (e.g. a tsconfig path for TS today;
+     * a venv path for Python tomorrow). Opaque to the onion — read only by the
+     * terminal extractor step (and by cache layers that need identity signals).
+     */
+    extractorOptions?: Record<string, unknown>;
+    /**
+     * Opt-in caller-supplied identity tag for cache-key purposes (e.g. a
+     * monorepo's own content-addressed build hash). Absence is fine — a cache
+     * layer must compute its own key when absent, never trust an unverified
+     * hint from an untrusted caller.
+     */
+    versionHint?: string;
+}
+/**
+ * Extraction's RESULT is already the host-neutral descriptor shape SPEC §4
+ * defines — reuse it verbatim, do not invent a parallel result type.
+ */
+export type ExtractResult = Operation[];
+/** A stage-agnostic middleware step: receives the call, owns the continuation. */
+export type ExtractMiddleware = (call: ExtractCall, next: () => Promise<ExtractResult>) => Promise<ExtractResult>;
+/**
+ * Generic right-fold onion composition around an arbitrary innermost service.
+ * Identical composition algebra to the dispatch invoker's `reduceRight`
+ * (`apigen-engine-runtime`'s `invoke.ts`): `middlewares` are composed
+ * outermost-first (index 0 runs first); a middleware that returns without
+ * calling `next` short-circuits all downstream middlewares and the core.
+ */
+export declare function composeOnion<TCall, TResult>(middlewares: readonly ((call: TCall, next: () => Promise<TResult>) => Promise<TResult>)[], core: (call: TCall) => Promise<TResult>): (call: TCall) => Promise<TResult>;
+/**
+ * Compose an extract-stage invoker: `middlewares` (e.g. a cache layer)
+ * wrapping the terminal `runExtractor` step. Mirrors the dispatch stage's
+ * `createPackageInvoker` for the extract stage — the terminal step is "run
+ * the real extractor for `call.host`" instead of "run dispatch".
+ *
+ * A cache layer sits ABOVE `runExtractor`, so a cache HIT never invokes it —
+ * which is what makes this correct whether `runExtractor` is an in-process
+ * function today or a spawned subprocess tomorrow.
+ */
+export declare function createExtractInvoker(middlewares: readonly ExtractMiddleware[], runExtractor: (call: ExtractCall) => Promise<ExtractResult>): (call: ExtractCall) => Promise<ExtractResult>;
+/**
+ * Mirrors `createPackageInvoker`'s (`apigen-engine-runtime`'s
+ * `package-invoker.ts:124`) role for the extract stage (design doc Revision 2,
+ * R2.6 item 2 / implementation spec R2-2): pulls every loaded plugin's
+ * `extractLayer` capability — in declaration order, outermost-first, the
+ * identical composition rule `--use` layer ordering already follows on the
+ * dispatch side — and wraps `runExtractor` with them via {@link createExtractInvoker}.
+ *
+ * A plugin with no `extractLayer` capability (the common case today — nothing
+ * ships one yet) is filtered out silently; passing an empty `plugins` array
+ * (or a list where none declare `extractLayer`) degrades to `runExtractor`
+ * itself, unwrapped — a pure pass-through with zero behavioural change from
+ * calling `runExtractor` directly (R2-3's "byte-identical on MISS" guarantee).
+ *
+ * @param plugins      - The loaded `--use` plugin objects (or an explicit host-
+ *                       constructed list, e.g. backlog's `extractStagePlugins()`).
+ * @param runExtractor - The terminal extraction step (today: an in-process
+ *                       ts-morph `extract()` call; SPEC §12: potentially a
+ *                       spawned per-language subprocess later).
+ * @param opts         - This invocation's flat `--opt key=value` bag (the
+ *                       SAME bag already passed to `TargetCapability.generate`
+ *                       — apigen-cli has one flat bag per invocation, not a
+ *                       per-plugin-id namespaced one). Passed to each
+ *                       plugin's `extractLayer.createLayer(opts)` when
+ *                       present (`plugin.ts`'s `ExtractLayerCapability` doc);
+ *                       a plugin with only a static `.layer` ignores it.
+ *                       Defaults to `{}` — every existing call site (and
+ *                       every plugin with no opts-dependent behaviour)
+ *                       behaves identically whether this is passed or not.
+ */
+export declare function createExtractInvokerFromPlugins(plugins: readonly Plugin[], runExtractor: (call: ExtractCall) => Promise<ExtractResult>, opts?: Record<string, unknown>): (call: ExtractCall) => Promise<ExtractResult>;

package/lib/extraction-session.d.ts

@@ -82,6 +82,24 @@ export declare function fileVersion(pathStr: string): string;
 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;
+/**
+ * FEAT-002: absolute paths of every LOCAL (non-`node_modules`) file
+ * transitively imported by `entryPath`, in deterministic (sorted) order.
+ *
+ * Host-neutral, path-in/paths-out — the same `collectReferencedFiles` walk the
+ * session uses for its own invalidation, exposed so a persistent IR cache can
+ * content-hash the entry file's ENTIRE dependency graph for a stable,
+ * cross-machine cache key (an imported file's content is part of what the
+ * extractor's output depends on; a key covering only the entry file would
+ * falsely HIT after a type in an imported file changed).
+ *
+ * Uses a process-lifetime singleton Project with syntactic-only module
+ * resolution (no lib.d.ts parse, no type checking) so repeated key
+ * computations stay cheap. If the entry file was loaded before and has since
+ * changed on disk it is refreshed first, matching the walk's own
+ * refresh-before-descend behavior for visited targets.
+ */
+export declare function collectLocalImportPaths(entryPath: string): string[];
 /**
  * Create a fresh {@link ExtractionSession}.
  *

package/lib/format-alias.d.ts

@@ -0,0 +1,35 @@
+import { TypeNode } from 'ts-morph';
+
+/**
+ * Detects a `@format` JSDoc annotation on a plain, non-generic reference to a
+ * user-defined scalar type alias (e.g. `/** @format decimal *\/ type X =
+ * string;` referenced as a param/return type `X`), and returns the format
+ * string if found.
+ *
+ * Deliberately narrow — returns `undefined` (never throws) for every case
+ * outside this one:
+ *   - `typeNode` absent, or not a `TypeReference` node at all (covers plain
+ *     keyword types like `string`/`number`, array/tuple/union/etc. syntax).
+ *   - A generic reference (`Array<X>`, `Foo<T>`, …) — out of scope per spec;
+ *     the RESOLVED type at the call site must still flow through the
+ *     existing `Type#getText()` path unchanged.
+ *   - A qualified name (`Foo.Bar`) — only plain identifiers are considered.
+ *   - The identifier has no resolvable symbol, or none of its declarations is
+ *     a `TypeAliasDeclaration` (this alone already excludes interfaces,
+ *     classes, enums, and generic type parameters — none of those are ever a
+ *     `TypeAliasDeclaration`).
+ *   - The alias's own underlying type is not a plain scalar (string / number
+ *     / boolean) — guards against ever attaching `format` onto a structural
+ *     / object alias.
+ *   - No `@format` JSDoc tag is present on the alias declaration.
+ *
+ * Wrapped in a try/catch: this is an enhancement to extraction, never a
+ * required path, and must never crash extraction on an unexpected ts-morph
+ * API failure.
+ *
+ * @param typeNode - The syntactic type-node for a parameter or return type
+ *   (e.g. `paramDecl?.getTypeNode()`, `sig.getDeclaration()?.getReturnTypeNode()`),
+ *   as opposed to the RESOLVED `Type` that `Type#getText()` operates on.
+ * @returns The trimmed `@format` JSDoc comment text, or `undefined`.
+ */
+export declare function detectFormatAnnotatedAlias(typeNode: TypeNode | undefined): string | undefined;

package/lib/plugin.d.ts

@@ -1,3 +1,4 @@
+import { ExtractMiddleware } from './extract-invoker';
 import { PluginLanguage } from './types';
 import { Operation, OperationKind, JSONSchema, TypeText } from './descriptor';
 
@@ -248,6 +249,58 @@ export interface LayerCapability {
      */
     layer(call: Call, next: Next): Promise<Result> | AsyncIterable<Chunk>;
 }
+/**
+ * **`extractLayer`** capability — wrap the EXTRACT stage (design doc
+ * `extract-stage-onion-and-ir-cache.md` Revision 2, R2.6 item 1), not the
+ * dispatch stage `LayerCapability` above wraps.
+ *
+ * Same right-fold onion algebra as `LayerCapability.layer` — composed via
+ * {@link createExtractInvokerFromPlugins} in `extract-invoker.ts`, outermost
+ * plugin first — but typed against `ExtractCall`/`ExtractResult`
+ * (`extract-invoker.ts`), never the dispatch-shaped `Call`/`Result`. This is
+ * the deliberate, accepted "two Call shapes" asymmetry: `ExtractCall` has no
+ * `domainArgs`/`envelope`/`operation.id` to view-cast into a dispatch `Call`,
+ * so an extract-stage plugin (e.g. `@adhd/apigen-plugin-ir-cache`) declares
+ * this capability rather than reusing `layer`.
+ *
+ * A plugin may declare BOTH `layer` and `extractLayer` (they compose in their
+ * own, independent stages) or `extractLayer` alongside `target` (e.g. the
+ * ir-cache plugin: `extractLayer` for RUNTIME CACHE mode via `--use`,
+ * `target` for ARTIFACT mode via `--type`).
+ *
+ * **`createLayer` vs `layer` — the `--opt` gap fix.** A `Plugin` object is a
+ * static value with no per-invocation lifecycle hook, so a plain `layer`
+ * middleware built once at module-import time can never see a caller's
+ * `--use <id> --opt cache=<path>` value (unlike `TargetCapability.generate`/
+ * `MountCapability.operations`, which already receive `opts` as an explicit
+ * call-time parameter). `createLayer`, when present, is called ONCE per
+ * plugin at invoker-construction time (`createExtractInvokerFromPlugins`)
+ * with that invocation's flat `--opt` bag (the same bag already threaded to
+ * `TargetCapability.generate`'s `opts` — apigen-cli has exactly one flat
+ * `--opt` bag per invocation, not a per-plugin-id namespaced one; see
+ * `readUseOptions`'s `UseOptions` bag in `apigen-engine-runtime` for the
+ * dispatch-side per-plugin-id shape, which nothing in apigen-cli populates
+ * today, so this deliberately does not invent that infrastructure) and takes
+ * precedence over the static `layer`, which stays as the fallback for a
+ * plugin with no opts-dependent behaviour (or as an already-configured
+ * middleware a HOST builds directly via a factory, e.g.
+ * `entrypoint/backlog/src/server.ts`'s `backlogIrCachePlugin()`).
+ */
+export interface ExtractLayerCapability {
+    /**
+     * A ready-to-use extract-stage middleware — same short-circuit rule as
+     * `LayerCapability.layer`. Used when `createLayer` is absent, or by a host
+     * that constructs its own already-configured `Plugin` object directly
+     * (bypassing `--opt` entirely).
+     */
+    layer?: ExtractMiddleware;
+    /**
+     * Opts-aware factory: builds the middleware from this invocation's `--opt`
+     * bag. Preferred over `layer` by `createExtractInvokerFromPlugins` when
+     * both are present.
+     */
+    createLayer?: (opts: Record<string, unknown>) => ExtractMiddleware;
+}
 /**
  * Runtime dispatch options a {@link MountHostBridge} hands back to a mount
  * plugin's handler — structurally equivalent to `apigen-engine-runtime`'s
@@ -536,5 +589,15 @@ export interface Plugin<Opts = Record<string, unknown>> {
          * fields it needs and *read/write* them in its layer function.
          */
         envelope?: EnvelopeCapability;
+        /**
+         * Extract-layer capability — wrap the EXTRACT stage (design doc Revision
+         * 2, R2.6 item 1), not the dispatch stage `layer` above wraps.
+         *
+         * Loaded by `--use <plugin>` and composed via
+         * `createExtractInvokerFromPlugins` (`extract-invoker.ts`) — the single
+         * call site is `entrypoint/apigen-cli`'s `orchestrator.ts`'s
+         * `extractSource()`.
+         */
+        extractLayer?: ExtractLayerCapability;
     };
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adhd/apigen-core-client",
-  "version": "0.2.1",
+  "version": "0.3.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.1.0"
+    "@adhd/apigen-base-logical": "^0.1.1"
   },
   "main": "./index.js",
   "module": "./index.mjs",