@adhd/apigen-core-client 0.1.4 → 0.2.0

package/lib/extract.d.ts

@@ -9,6 +9,19 @@ export interface ExtractOptions {
      * words are derived from the raw string. Defaults to `''`.
      */
     namespace?: string;
+    /**
+     * When `true`, omits the file-derived path segment (normally the source
+     * file's basename, e.g. `client-d` from `client.d.ts`) from every
+     * operation's `path`. Default `false` (unchanged behavior — the file
+     * segment disambiguates same-named exports across multiple source files
+     * within one extraction run). Set this only when the source is a single,
+     * stable file whose name is an extraction artifact, not a meaningful
+     * namespace component (e.g. a generated `.d.ts`) — dropping it can cause
+     * two same-named exports from different files to collide; the hard
+     * extract-time collision guard (`@adhd/apigen-engine-naming`'s
+     * `checkCollisions`) still catches that.
+     */
+    dropFileSegment?: boolean;
     /** Absolute path to a tsconfig.json for type resolution. Optional. */
     tsconfig?: string;
     /**

package/llms.txt

@@ -0,0 +1,85 @@
+# @adhd/apigen-core-client
+
+> Core apigen engine: TypeScript source → JSON Schema extraction, composition, and plugin contracts.
+
+## Functions
+
+- `extract(opts: ExtractOptions): Promise<Operation[]>` — v2 symbol-based extractor. Handles 6 export shapes (named fn, const/arrow, named-object, default named, anonymous default, CJS) + renamed exports. Produces canonical `Operation[]` with deterministic ids, JSON Schema input/output, and same-host TypeText sugar. Ctx first-param excluded by name match only.
+- `tokenize(raw: string): string[]` — Splits camelCase/PascalCase/kebab-case/snake_case into lower-cased words. Deterministic. Used for casing-neutral Segment construction.
+- `generateSchemas(opts: GenerateSchemasOptions): Promise<GeneratedSchemas>` — v1 schema extraction. Three export modes: named (default), default, named-object. Promise<T> unwrapped. Session-sharing for cache hits.
+- `composeSchemas(domain: GeneratedSchemas, middlewares: SlimMiddleware[], overrides?): ComposedSchemas` — Merges domain schemas with middleware envelope fields. Always wraps with data:{}. Only `false` suppresses a middleware.
+- `extractClasses(opts: ExtractClassesOptions): Promise<Operation[]>` — Class export extraction (SPEC §10). Static methods always extracted. Constructor + instance methods opt-in via includeInstances. Instance methods carry instanceId envelope.
+- `createExtractionSession(): ExtractionSession` — Per-run shared cache. One ts-morph Project per tsconfig, one schema generator per file, memoized schemas. dispose() releases per-run resources.
+- `clearPersistentProjectCache(): void` — Drops process-lifetime Project and schema caches.
+- `languageOfSource(file: string): PluginLanguage | undefined` — Extension → language tag (.ts→'ts', .py→'py', etc.). Undefined for unknown.
+- `pluginConsumesSource(plugin: LanguageAwarePlugin, file: string): boolean` — Does plugin's language match file's extension?
+- `sourcesForPlugin(plugin: LanguageAwarePlugin, files: string[]): string[]` — Filter files by plugin language. Primary serve dispatch entry-point.
+- `effectiveLanguage(plugin: LanguageAwarePlugin): PluginLanguage` — Declared language or default 'ts'.
+
+## Types
+
+### Descriptor (SPEC §4)
+- `Operation` — Canonical operation: id, host, namespace, path (Segment[]), kind, async, streaming, safe, input/output JSONSchema, envelope, typeText.
+- `OperationKind` — 'action' | 'query' | 'constructor' | 'instance-method'.
+- `Segment` — { raw: string, words: string[] }. Casing-neutral identity.
+- `JSONSchema` — JSON Schema 2020-12 fragment with $defs/$ref + ApigenSchemaHints.
+- `ApigenSchemaHints` — Advisory x-apigen-nominal, x-apigen-enum-repr, fidelity.
+- `TypeText` — { lang, input, output }. Same-host textual sugar. Null when unavailable.
+
+### v1 Plugin
+- `OutputPlugin` — { id, description, language?, optionsSchema?, generate(PluginInput): PluginOutput, run?(RunInput): Promise<void> }
+- `PluginInput` — { packages, outputDir, options, logger? }
+- `PluginOutput` — { files: {path,content}[], postCommands? }
+- `RunInput` — PluginInput + { signal?: AbortSignal }
+- `PluginLanguage` — 'ts' | 'py' | 'rust' | 'go' | 'java'
+
+### v2 Plugin (SPEC §7.1)
+- `Plugin<Opts>` — { id, description?, language?, optionsSchema?, capabilities: { target?, layer?, mount?, envelope? } }
+- `TargetCapability<Opts>` — { name, generate(Descriptor, Opts): File[], serve?(Descriptor, Harness, Opts): Promise<Server> }
+- `LayerCapability` — { envelopeFields?, layer(Call, Next): Promise<Result> | AsyncIterable<Chunk> }
+- `MountCapability` — { operations(Descriptor, opts?): MountedOperation[] }
+- `MountedOperation` — Operation + { transports?, handler(Call): unknown }
+- `EnvelopeCapability` — { request?, response? } — side-channel field schemas
+- `Call` — { operation, data, envelope, ctx(Extensions), transport, signal, raw? }
+- `Next` — () => Promise<Result> | AsyncIterable<Chunk>
+- `Transport` — 'http' | 'grpc' | 'mcp' | 'cli'
+- `Extensions` — { get<T>(key), set<T>(key, value) } — typed request-extensions map
+- `Descriptor` — { operations, host, namespace? } — merged canonical descriptor
+- `Harness` — { invoke(op, call): Promise<Result> | AsyncIterable<Chunk> }
+- `Server` — { close(): Promise<void> }
+- `File` — { path, content }
+
+### Schema
+- `GeneratedSchemas` — { metadata: { namespace, phase }, schemas: Record<name, { input, output, hasCtx? }> }
+- `ComposedSchemas` — Record<name, { input (includes envelope+data), output, hasCtx? }>
+- `GenerateSchemasOptions` — { sourceFile, exportMode?, namespace?, phase?, tsconfig?, session? }
+- `ExportMode` — { type: 'named' } | { type: 'default' } | { type: 'named-object', name: string }
+
+### Session
+- `ExtractionSession` — { dispose(), readonly stats: ISessionStats }
+- `ISessionStats` — { projectsBuilt, generatorsBuilt, schemaCacheHits, schemaCacheMisses }
+
+### Source Language
+- `LanguageAwarePlugin` — { language?: PluginLanguage }
+- `ExtractOptions` — { sourceFile, namespace?, tsconfig?, session? }
+- `ExtractClassesOptions` — { sourceFile, namespace?, tsconfig?, includeInstances?, session? }
+
+### Re-exported
+- `Logger` — re-exported from pino
+
+## Invariants
+- `ctx-name-only`: First param named `ctx` excluded by name, no type check. hasCtx flag recorded.
+- `data-wrapper-always-present`: composeSchemas always wraps with data:{}.
+- `false-suppresses-middleware`: Only `false` suppresses; null/undefined/0/'' do not.
+- `hints-advisory`: x-apigen-* hints are advisory. Removing them leaves valid schema.
+- `do-not-parallelize-buildSchema`: Synchronous CPU, morph-walk mutates shared SourceFile.
+- `language-agnostic-output`: Core does not restrict emitted file language.
+
+## Dependencies
+- ts-morph ^23.0.0, ts-json-schema-generator ^2.3.0, pino 10.3.1, typescript ^6.0.3, decimal.js ^10.4.3, @adhd/apigen-base-logical ^0.0.1
+
+## See also
+- [README.md](./README.md)
+- [CHANGELOG.md](./CHANGELOG.md)
+- [docs/reference/](./docs/reference/)
+- [docs/how-to/](./docs/how-to/)

package/package.json

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