@skmtc/core 0.0.984 → 0.16.1

package/esm/context/CoreContext.js

@@ -16,8 +16,8 @@ import { ParseContext } from './ParseContext.js';
 import * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import { ResultsHandler } from './ResultsHandler.js';
 import { ResultsLog } from '../helpers/ResultsLog.js';
-import { join } from '../deps/jsr.io/@std/path/1.1.3/join.js';
-import { bold, gray, red, yellow, blue } from '../deps/jsr.io/@std/fmt/1.0.8/colors.js';
+import { join } from '../deps/jsr.io/@std/path/1.1.4/join.js';
+import { bold, gray, red, yellow, blue } from '../deps/jsr.io/@std/fmt/1.0.10/colors.js';
 /**
  * The main orchestration class for the SKMTC transformation pipeline.
  *
@@ -42,11 +42,11 @@ import { bold, gray, red, yellow, blue } from '../deps/jsr.io/@std/fmt/1.0.8/col
  * });
  *
  * const result = await context.toArtifacts({
- *   documentObject: openApiDoc,
+ *   document: { type: 'oas', value: openApiDoc },
  *   settings: clientSettings,
  *   toGeneratorConfigMap: () => generators,
- *   prettier: prettierConfig,
- *   silent: false
+ *   silent: false,
+ *   stackTrail: new StackTrail(['gen'])
  * });
  * ```
  *
@@ -146,10 +146,14 @@ export class CoreContext {
      * ```
      */
     parse(documentObject, stackTrail) {
-        __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, documentObject), "f");
-        const oasDocument = __classPrivateFieldGet(this, _CoreContext_phase, "f").context.parse(stackTrail);
+        __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, { type: 'oas', value: documentObject }), "f");
+        const parsed = __classPrivateFieldGet(this, _CoreContext_phase, "f").context.parse(stackTrail);
+        if (parsed.type !== 'oas') {
+            // Unreachable: input was tagged 'oas' so the parsed branch must match.
+            throw new Error('CoreContext.parse: expected OAS parsed document');
+        }
         return {
-            oasDocument
+            oasDocument: parsed.value
         };
     }
     /**
@@ -164,48 +168,41 @@ export class CoreContext {
      * about the generation process, including file mappings, previews, and results.
      *
      * @param args - Configuration for the artifact generation
-     * @param args.documentObject - The OpenAPI v3 document to process
+     * @param args.document - The source document, discriminated by protocol
+     *   (`{ type: 'oas', value: OpenAPIV3.Document }` or
+     *   `{ type: 'gql', value: GqlDocument }`)
      * @param args.settings - Client settings for customization
      * @param args.toGeneratorConfigMap - Function returning generator configuration
-     * @param args.prettier - Optional Prettier configuration for code formatting
      * @param args.silent - Whether to suppress console output during generation
+     * @param args.stackTrail - Stack trail for distributed tracing
      * @returns Promise resolving to rendered artifacts and metadata
      *
      * @example Complete pipeline
      * ```typescript
+     * import { CoreContext, StackTrail, toModelEntry, toOasOperationEntry } from '@skmtc/core';
+     *
      * const context = new CoreContext({
      *   spanId: 'api-client-gen',
      *   silent: false
      * });
      *
-     * const result = await context.toArtifacts({
-     *   documentObject: openApiDoc,
+     * const result = context.toArtifacts({
+     *   document: { type: 'oas', value: openApiDoc },
      *   settings: {
-     *     basePath: './src/api',
-     *     skip: {
-     *       models: ['Internal*'],
-     *       operations: {
-     *         '/health': ['get'],
-     *         '/debug/**': ['*']
-     *       }
-     *     }
+     *     basePath: './src/api'
      *   },
      *   toGeneratorConfigMap: () => ({
-     *     models: {
-     *       generator: MyModelGenerator,
-     *       settings: { includeValidation: true }
-     *     },
-     *     operations: {
-     *       generator: MyOperationGenerator,
-     *       settings: { generateTypes: true }
-     *     }
+     *     'typescript-models': toModelEntry({
+     *       id: 'typescript-models',
+     *       transform: ({ context, refName }) => {}
+     *     }),
+     *     'api-client': toOasOperationEntry({
+     *       id: 'api-client',
+     *       transform: ({ context, operation }) => {}
+     *     })
      *   }),
-     *   prettier: {
-     *     semi: false,
-     *     singleQuote: true,
-     *     trailingComma: 'all'
-     *   },
-     *   silent: false
+     *   silent: false,
+     *   stackTrail: new StackTrail(['gen'])
      * });
      *
      * // Access generated artifacts
@@ -223,44 +220,85 @@ export class CoreContext {
      *
      * @throws Will throw an error if any phase of the pipeline fails
      */
-    toArtifacts({ documentObject, settings, toGeneratorConfigMap, stackTrail, prettier }) {
+    toArtifacts({ document, settings, toGeneratorConfigMap, stackTrail, attribution }) {
         try {
-            const oasDocument = stackTrail.trace('parse', st => {
-                __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, documentObject), "f");
-                return __classPrivateFieldGet(this, _CoreContext_phase, "f").context.parse(st);
-            });
+            // Parse phase: one unified ParseContext handles both protocols
+            // via its internal protocol-discriminated state. `parse()` returns
+            // a SkmtcParsedDocument; we collect issues from `context.issues`.
+            const phase = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, document);
+            __classPrivateFieldSet(this, _CoreContext_phase, phase, "f");
+            const parsedDocument = stackTrail.trace('parse', st => phase.context.parse(st));
+            // The shared attribution capture channel: snippets constructed
+            // during generate hold the GenerateContext, whose `captureSink`
+            // reads this slot; RenderContext flips it around the one capturing
+            // render. One object per run wires the two phases together.
+            const captureChannel = { sink: undefined };
             const { files, previews, mappings } = stackTrail.trace('generate', st => {
                 __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupGeneratePhase).call(this, {
                     toGeneratorConfigMap,
-                    oasDocument,
-                    settings
+                    document: parsedDocument,
+                    settings,
+                    captureChannel
                 }), "f");
                 return __classPrivateFieldGet(this, _CoreContext_phase, "f").context.toArtifacts(st);
             });
+            // Render is a single capture pass: it renders each File once and,
+            // when `attribution.postPass` is configured, simultaneously captures
+            // the producer occurrence tree and emits sidecars + the generation
+            // map (folded into `RenderContext.render`). No separate pre-render
+            // post-pass, no re-render — the old `_rendered` cache that faked
+            // "render once" across two passes is gone.
             const renderOutput = stackTrail.trace('render', st => {
                 __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupRenderPhase).call(this, {
                     files,
                     previews,
                     mappings,
-                    prettier,
-                    basePath: settings?.basePath
+                    basePath: settings?.basePath,
+                    attribution,
+                    captureChannel
                 }), "f");
                 return __classPrivateFieldGet(this, _CoreContext_phase, "f").context.render(st);
             });
             return {
                 ...renderOutput,
-                results: __classPrivateFieldGet(this, _CoreContext_results, "f").toTree()
+                results: __classPrivateFieldGet(this, _CoreContext_results, "f").toTree(),
+                parseIssues: phase.context.issues
             };
         }
         catch (error) {
             console.error(error);
             this.logger.error(error);
+            // Surface the fatal error as a synthesized parse-issue so
+            // downstream consumers (CLI `generate`, the manifest writer)
+            // can tell a successful 0-file run apart from a crashed run.
+            // Before this, the catch returned `parseIssues: []` and an
+            // empty `artifacts`, which read on the CLI side as "everything
+            // generated, just nothing emitted" — silent failure.
+            //
+            // We pull whatever parse-phase issues were already recorded
+            // before the throw, so any incremental diagnostics aren't lost,
+            // and append the top-level failure on the end. Protocol is
+            // hardcoded to 'oas' because the synthesized issue is
+            // post-protocol-dispatch and we don't have a discriminator at
+            // this catch site; OAS is the more common case and the
+            // location format ('toArtifacts') is unambiguous regardless.
+            const priorIssues = __classPrivateFieldGet(this, _CoreContext_phase, "f")?.type === 'parse' ? __classPrivateFieldGet(this, _CoreContext_phase, "f").context.issues : [];
+            const message = error instanceof Error ? error.message : String(error);
+            const fatalIssue = {
+                protocol: 'oas',
+                level: 'error',
+                type: 'INVALID_SCHEMA',
+                location: 'toArtifacts',
+                message: `Top-level toArtifacts failure: ${message}`,
+                cause: error
+            };
             return {
                 artifacts: {},
                 files: {},
                 previews: {},
                 mappings: {},
-                results: __classPrivateFieldGet(this, _CoreContext_results, "f").toTree()
+                results: __classPrivateFieldGet(this, _CoreContext_results, "f").toTree(),
+                parseIssues: [...priorIssues, fatalIssue]
             };
         }
         finally {
@@ -271,6 +309,97 @@ export class CoreContext {
             });
         }
     }
+    /**
+     * Capability-only sibling of {@link toArtifacts}: parse the document, then
+     * evaluate each generator's `isSupported` over its subjects — no transform,
+     * no render. Returns the subjects each generator supports, plus parse issues.
+     */
+    toSupportedSubjects({ document, settings, toGeneratorConfigMap, stackTrail }) {
+        try {
+            const phase = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, document);
+            __classPrivateFieldSet(this, _CoreContext_phase, phase, "f");
+            const parsedDocument = stackTrail.trace('parse', st => phase.context.parse(st));
+            const subjects = stackTrail.trace('generate', () => {
+                // Capability probing never renders, so the capture interval never
+                // opens — a throwaway channel satisfies the wiring.
+                const generatePhase = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupGeneratePhase).call(this, {
+                    toGeneratorConfigMap,
+                    document: parsedDocument,
+                    settings,
+                    captureChannel: { sink: undefined }
+                });
+                __classPrivateFieldSet(this, _CoreContext_phase, generatePhase, "f");
+                return generatePhase.context.toSupportedSubjects();
+            });
+            return { subjects, parseIssues: phase.context.issues };
+        }
+        catch (error) {
+            this.logger.error(error);
+            const priorIssues = __classPrivateFieldGet(this, _CoreContext_phase, "f")?.type === 'parse' ? __classPrivateFieldGet(this, _CoreContext_phase, "f").context.issues : [];
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                subjects: {},
+                parseIssues: [
+                    ...priorIssues,
+                    {
+                        protocol: 'oas',
+                        level: 'error',
+                        type: 'INVALID_SCHEMA',
+                        location: 'toSupportedSubjects',
+                        message: `Top-level toSupportedSubjects failure: ${message}`,
+                        cause: error
+                    }
+                ]
+            };
+        }
+    }
+    /**
+     * Seed-values sibling of {@link toSupportedSubjects}: parse the document, then
+     * call each generator's `toEnrichmentDefaults` over its supported subjects —
+     * no transform, no render. Returns the default enrichment values keyed by the
+     * `client.json#settings.enrichments` routing, plus parse issues. Fails open
+     * like {@link toArtifacts}: a bad schema surfaces as a `parseIssue` and the
+     * defaults map is returned empty.
+     */
+    toEnrichmentDefaults({ document, settings, toGeneratorConfigMap, stackTrail }) {
+        try {
+            const phase = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, document);
+            __classPrivateFieldSet(this, _CoreContext_phase, phase, "f");
+            const parsedDocument = stackTrail.trace('parse', st => phase.context.parse(st));
+            const enrichmentDefaults = stackTrail.trace('generate', () => {
+                // Seeding never renders, so the capture interval never opens — a
+                // throwaway channel satisfies the wiring.
+                const generatePhase = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupGeneratePhase).call(this, {
+                    toGeneratorConfigMap,
+                    document: parsedDocument,
+                    settings,
+                    captureChannel: { sink: undefined }
+                });
+                __classPrivateFieldSet(this, _CoreContext_phase, generatePhase, "f");
+                return generatePhase.context.toEnrichmentDefaults();
+            });
+            return { enrichmentDefaults, parseIssues: phase.context.issues };
+        }
+        catch (error) {
+            this.logger.error(error);
+            const priorIssues = __classPrivateFieldGet(this, _CoreContext_phase, "f")?.type === 'parse' ? __classPrivateFieldGet(this, _CoreContext_phase, "f").context.issues : [];
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                enrichmentDefaults: {},
+                parseIssues: [
+                    ...priorIssues,
+                    {
+                        protocol: 'oas',
+                        level: 'error',
+                        type: 'INVALID_SCHEMA',
+                        location: 'toEnrichmentDefaults',
+                        message: `Top-level toEnrichmentDefaults failure: ${message}`,
+                        cause: error
+                    }
+                ]
+            };
+        }
+    }
     /**
      * Captures a result at the current execution position in the stack trail.
      *
@@ -339,31 +468,33 @@ _CoreContext_phase = new WeakMap(), _CoreContext_results = new WeakMap(), _CoreC
         }
     });
     return log.getLogger(spanId);
-}, _CoreContext_setupParsePhase = function _CoreContext_setupParsePhase(documentObject) {
+}, _CoreContext_setupParsePhase = function _CoreContext_setupParsePhase(input) {
     const parseContext = new ParseContext({
-        documentObject,
+        input,
         logger: this.logger,
         silent: this.silent
     });
     return { type: 'parse', context: parseContext };
-}, _CoreContext_setupGeneratePhase = function _CoreContext_setupGeneratePhase({ oasDocument, settings, toGeneratorConfigMap }) {
+}, _CoreContext_setupGeneratePhase = function _CoreContext_setupGeneratePhase({ document, settings, toGeneratorConfigMap, captureChannel }) {
     const generateContext = new GenerateContext({
-        oasDocument,
+        document,
         settings,
         logger: this.logger,
         captureCurrentResult: this.captureCurrentResult.bind(this),
-        toGeneratorConfigMap
+        toGeneratorConfigMap,
+        captureChannel
     });
     return { type: 'generate', context: generateContext };
-}, _CoreContext_setupRenderPhase = function _CoreContext_setupRenderPhase({ files, previews, mappings, prettier, basePath }) {
+}, _CoreContext_setupRenderPhase = function _CoreContext_setupRenderPhase({ files, previews, mappings, basePath, attribution, captureChannel }) {
     const renderContext = new RenderContext({
         files,
         previews,
         mappings,
-        prettierConfig: prettier,
         basePath,
         logger: this.logger,
-        captureCurrentResult: this.captureCurrentResult.bind(this)
+        captureCurrentResult: this.captureCurrentResult.bind(this),
+        attribution,
+        captureChannel
     });
     return { type: 'render', context: renderContext };
 };