@skmtc/core 0.28.5 → 0.28.7

package/esm/context/GenerateContext.js

@@ -9,19 +9,22 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _GenerateContext_instances, _GenerateContext_files, _GenerateContext_previews, _GenerateContext_captureChannel, _GenerateContext_enrichmentAudit, _GenerateContext_reportSkippedEnrichment, _GenerateContext_schemaRefNames, _GenerateContext_subjectDefaults, _GenerateContext_runOasOperationGenerator, _GenerateContext_runWebhookGenerator, _GenerateContext_runGqlOperationGenerator, _GenerateContext_runModelGenerator, _GenerateContext_addPreview, _GenerateContext_toContentSettingsExportPath, _GenerateContext_ejectedBySuffixedPath_get, _GenerateContext_ejectedBySuffixedPathCache;
+var _GenerateContext_instances, _GenerateContext_files, _GenerateContext_previews, _GenerateContext_captureChannel, _GenerateContext_enrichmentAudit, _GenerateContext_reportSkippedEnrichment, _GenerateContext_schemaRefNames, _GenerateContext_subjectDefaults, _GenerateContext_runOasOperationGenerator, _GenerateContext_runWebhookGenerator, _GenerateContext_runGqlOperationGenerator, _GenerateContext_runModelGenerator, _GenerateContext_addPreview, _GenerateContext_toContentSettingsExportPath, _GenerateContext_ejectedBySuffixedPath_get, _GenerateContext_ejectedBySuffixedPathCache, _GenerateContext_findContainer, _GenerateContext_toContainer;
 import { normalize } from '../deps/jsr.io/@std/path/1.1.6/normalize.js';
 import { applyGeneratedSuffix, DEFAULT_GENERATED_SUFFIX } from '../helpers/applyGeneratedSuffix.js';
 import { OasOperationDriver } from '../dsl/operation/oas/OasOperationDriver.js';
 import { WebhookDriver } from '../dsl/webhook/WebhookDriver.js';
 import { GqlOperationDriver } from '../dsl/operation/gql/GqlOperationDriver.js';
 import { ModelDriver } from '../dsl/model/ModelDriver.js';
+import { readProjectionOptions } from '../types/ProjectionOptions.js';
+import { toInsertOptions, toPeerInsertOptions } from '../types/InsertOptions.js';
 import { ContentSettings } from '../dsl/ContentSettings.js';
 import { DEFAULT_VARIANT } from '../types/Variant.js';
 import { toVariantList } from '../helpers/toVariantList.js';
 import get from 'lodash-es/get.js';
 import { Inserted } from '../dsl/Inserted.js';
 import { CodeFileBase } from '../dsl/CodeFileBase.js';
+import { isDefinitionContainer } from '../dsl/DefinitionContainer.js';
 import { JsonFile } from '../dsl/JsonFile.js';
 import { MarkdownFile } from '../dsl/MarkdownFile.js';
 import invariant from 'tiny-invariant';
@@ -71,7 +74,7 @@ import { formatEnrichmentPath } from '../enrichments/EnrichmentWarning.js';
  * ```
  */
 const isGqlInsertOperationArgs = (args) => args.operation.oasType === 'gqlOperation';
-const isGqlToOperationSettingsArgs = (args) => args.operation.oasType === 'gqlOperation';
+const isGqlToOperationSettingsFields = (args) => args.operation.oasType === 'gqlOperation';
 /** A non-null object — the subject-scope leaf of an enrichment-defaults umbrella
  *  (`{ fields, title, … }`). Narrows `unknown` without an `as` cast. */
 const isEnrichmentLeaf = (value) => typeof value === 'object' && value !== null;
@@ -517,7 +520,7 @@ export class GenerateContext {
      *
      * @mutates this.files
      */
-    register({ imports = [], reExports = [], definitions, custom, destinationPath }) {
+    register({ imports = [], reExports = [], definitions, custom, destinationPath, into }) {
         const normalizedPath = normalize(destinationPath);
         const currentFile = this.getFile(normalizedPath);
         // `register` never creates files — it speaks pure data and the engine
@@ -537,9 +540,20 @@ export class GenerateContext {
         // policy — are code-file concerns owned by the language subclass.
         // `JsonFile` (no definitions/imports) is skipped by the guard.
         if (currentFile instanceof CodeFileBase) {
+            // Definitions may land in the file or inside a declaration in it;
+            // imports, re-exports and `custom` are always the file's. Resolved
+            // only when a definition is actually placed — `into` alongside
+            // imports alone must not throw for a container nothing needed. The
+            // test is the same one the loop below applies: the array is
+            // `(DefinitionBase | undefined)[]`, so a non-zero length is not
+            // proof that anything lands.
+            const placesADefinition = definitions?.some(definition => definition !== undefined) ?? false;
+            const place = into === undefined || !placesADefinition
+                ? currentFile
+                : __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContainer).call(this, currentFile, into, normalizedPath);
             definitions?.forEach(definition => {
                 if (definition) {
-                    currentFile.addDefinition(definition);
+                    place.addDefinition(definition);
                 }
             });
             if (imports.length > 0) {
@@ -563,29 +577,13 @@ export class GenerateContext {
      * @mutates this.files
      */
     insertOperation(args) {
-        // Default to the canonical variant. Callers who explicitly thread
-        // a variant (e.g. variants-aware Projections threading
-        // `this.settings.variant`) override this default.
-        const variant = args.variant ?? DEFAULT_VARIANT;
+        // The Driver defaults `variant` and `noExport` and reads the caller's
+        // options off the call.
         if (isGqlInsertOperationArgs(args)) {
-            const { settings, definition } = new GqlOperationDriver({
-                context: this,
-                projection: args.projection,
-                operation: args.operation,
-                destinationPath: args.destinationPath,
-                noExport: args.noExport ?? false,
-                variant
-            });
+            const { settings, definition } = new GqlOperationDriver({ ...args, context: this });
             return new Inserted({ settings, definition });
         }
-        const { settings, definition } = new OasOperationDriver({
-            context: this,
-            projection: args.projection,
-            operation: args.operation,
-            destinationPath: args.destinationPath,
-            noExport: args.noExport ?? false,
-            variant
-        });
+        const { settings, definition } = new OasOperationDriver({ ...args, context: this });
         return new Inserted({ settings, definition });
     }
     /**
@@ -594,27 +592,19 @@ export class GenerateContext {
      * protocol discrimination.
      */
     insertWebhook(args) {
-        const variant = args.variant ?? DEFAULT_VARIANT;
-        const { settings, definition } = new WebhookDriver({
-            context: this,
-            projection: args.projection,
-            webhook: args.webhook,
-            destinationPath: args.destinationPath,
-            noExport: args.noExport ?? false,
-            variant
-        });
+        const { settings, definition } = new WebhookDriver({ ...args, context: this });
         return new Inserted({ settings, definition });
     }
     /**
      * Insert a normalized model: dispatch to {@link insertModel} when the schema
      * is a `$ref`, otherwise produce a one-off definition under `fallbackName`.
      */
-    insertNormalizedModel(projection, { schema, fallbackName, destinationPath }, { noExport = false, variant } = {}) {
+    insertNormalizedModel(projection, { schema, fallbackName, destinationPath }, ...rest) {
+        const insertOptions = toPeerInsertOptions(rest);
         if (schema.isRef()) {
             const { definition } = this.insertModel(projection, schema.toRefName(), {
-                destinationPath,
-                noExport,
-                variant
+                ...insertOptions,
+                destinationPath
             });
             // @TODO Using mapped types would help avoid generics casting
             return definition;
@@ -647,7 +637,7 @@ export class GenerateContext {
             context: this,
             identifier: projection.createIdentifier(fallbackName),
             value,
-            noExport
+            noExport: insertOptions.noExport
         });
         this.register({ definitions: [definition], destinationPath: normalizedPath });
         // @TODO Using mapped types would help avoid generics casting
@@ -662,19 +652,15 @@ export class GenerateContext {
      *
      * @mutates this.files
      */
-    insertModel(projection, refName, { destinationPath, noExport = false, variant } = {}) {
-        // Default to the canonical variant. Callers who explicitly thread
-        // a variant (e.g. variants-aware Projections threading
-        // `this.settings.variant`) override this default.
-        const resolvedVariant = variant ?? DEFAULT_VARIANT;
+    insertModel(projection, refName, ...rest) {
+        // The Driver defaults `variant` and `noExport` and reads the caller's
+        // options off the call.
         const { settings, definition } = new ModelDriver({
             context: this,
             projection,
             refName,
-            destinationPath,
             rootRef: refName,
-            noExport,
-            variant: resolvedVariant
+            ...toInsertOptions(rest)
         });
         return new Inserted({ settings, definition });
     }
@@ -684,9 +670,12 @@ export class GenerateContext {
      * `toEnrichments` against the
      * given operation.
      */
-    toOperationContentSettings(args) {
-        const variant = args.variant ?? DEFAULT_VARIANT;
-        if (isGqlToOperationSettingsArgs(args)) {
+    toOperationContentSettings(settingsArgs) {
+        const variant = settingsArgs.variant ?? DEFAULT_VARIANT;
+        const options = readProjectionOptions(settingsArgs);
+        // The subject is narrowed on the plain fields; the options slot is read once above.
+        const args = settingsArgs;
+        if (isGqlToOperationSettingsFields(args)) {
             const enrichments = args.projection.toEnrichments({
                 operation: args.operation,
                 context: this,
@@ -697,14 +686,16 @@ export class GenerateContext {
                     name: args.projection.toIdentifierName({
                         operation: args.operation,
                         enrichments,
-                        variant
+                        variant,
+                        options
                     }),
                     ...args.projection.toIdentifierType(args.operation, this)
                 }),
                 exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, args.projection.toExportPath({
                     operation: args.operation,
                     enrichments,
-                    variant
+                    variant,
+                    options
                 })),
                 enrichments,
                 variant
@@ -720,15 +711,20 @@ export class GenerateContext {
                 name: args.projection.toIdentifierName({
                     operation: args.operation,
                     enrichments,
-                    variant
+                    variant,
+                    options
                 }),
                 ...args.projection.toIdentifierType(args.operation, this)
             }),
-            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, args.projection.toExportPath({
-                operation: args.operation,
-                enrichments,
-                variant
-            })),
+            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, 
+            // A member has no file of its own: the Driver passes its container's.
+            args.exportPath ??
+                args.projection.toExportPath({
+                    operation: args.operation,
+                    enrichments,
+                    variant,
+                    options
+                })),
             enrichments,
             variant
         });
@@ -740,6 +736,7 @@ export class GenerateContext {
      */
     toWebhookContentSettings(args) {
         const variant = args.variant ?? DEFAULT_VARIANT;
+        const options = readProjectionOptions(args);
         const enrichments = args.projection.toEnrichments({
             webhook: args.webhook,
             context: this,
@@ -750,14 +747,16 @@ export class GenerateContext {
                 name: args.projection.toIdentifierName({
                     webhook: args.webhook,
                     enrichments,
-                    variant
+                    variant,
+                    options
                 }),
                 ...args.projection.toIdentifierType(args.webhook, this)
             }),
             exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, args.projection.toExportPath({
                 webhook: args.webhook,
                 enrichments,
-                variant
+                variant,
+                options
             })),
             enrichments,
             variant
@@ -771,14 +770,16 @@ export class GenerateContext {
      * identifier is assembled through the projection's language
      * (`lang.toIdentifier`).
      */
-    toModelContentSettings({ refName, projection, variant = DEFAULT_VARIANT }) {
+    toModelContentSettings(args) {
+        const { refName, projection, variant = DEFAULT_VARIANT } = args;
+        const options = readProjectionOptions(args);
         const enrichments = projection.toEnrichments({ refName, context: this, variant });
         return new ContentSettings({
             identifier: projection.lang.toIdentifier({
-                name: projection.toIdentifierName({ refName, enrichments, variant }),
+                name: projection.toIdentifierName({ refName, enrichments, variant, options }),
                 ...projection.toIdentifierType(refName, this)
             }),
-            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, projection.toExportPath({ refName, enrichments, variant })),
+            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, projection.toExportPath({ refName, enrichments, variant, options })),
             enrichments,
             variant
         });
@@ -811,12 +812,20 @@ export class GenerateContext {
      * @param { name, exportPath }
      * @returns Matching definition if found or `undefined` otherwise
      */
-    findDefinition({ name, exportPath }) {
+    findDefinition({ name, exportPath, into }) {
         // Pure lookup — no file is created on a miss. Definitions live on the
         // code-file subclass, so narrow; a non-code file (`JsonFile`) has none.
         // The cache wants the single primary for the name → first match.
         const file = this.getFile(exportPath);
-        return file instanceof CodeFileBase ? file.findDefinitions({ name })?.[0] : undefined;
+        if (!(file instanceof CodeFileBase)) {
+            return undefined;
+        }
+        // Resolve the place, then ask it once — the same two steps `register`
+        // takes. A miss on the container is a miss on the member: nothing is
+        // created here, and a member cannot exist before the definition holding
+        // it.
+        const place = into === undefined ? file : __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_findContainer).call(this, file, into);
+        return place?.findDefinitions({ name })?.[0];
     }
 }
 _GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(), _GenerateContext_captureChannel = new WeakMap(), _GenerateContext_enrichmentAudit = new WeakMap(), _GenerateContext_ejectedBySuffixedPathCache = new WeakMap(), _GenerateContext_instances = new WeakSet(), _GenerateContext_reportSkippedEnrichment = function _GenerateContext_reportSkippedEnrichment(block, variant, path) {
@@ -1168,6 +1177,16 @@ _GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(
         })), "f");
     }
     return __classPrivateFieldGet(this, _GenerateContext_ejectedBySuffixedPathCache, "f");
+}, _GenerateContext_findContainer = function _GenerateContext_findContainer(file, into) {
+    const definition = file.findDefinitions({ name: into })?.[0];
+    return definition && isDefinitionContainer(definition.value) ? definition.value : undefined;
+}, _GenerateContext_toContainer = function _GenerateContext_toContainer(file, into, path) {
+    const definition = file.findDefinitions({ name: into })?.[0];
+    invariant(definition, `Cannot register into '${into}' in '${path}' — no declaration of that name exists. ` +
+        `Register the container before its members, or look it up with findDefinition first.`);
+    invariant(isDefinitionContainer(definition.value), `Cannot register into '${into}' in '${path}' — that declaration does not hold members. ` +
+        `Its value must implement addDefinition and findDefinitions.`);
+    return definition.value;
 };
 /**
  * Match a `(path, method, variant)` tuple against an operation-shaped

package/esm/context/ParseContext.d.ts

@@ -212,4 +212,3 @@ export declare class ParseContext {
      */
     logSkippedFields({ skipped, stackTrail, parent, parentType, type }: LogSkippedValuesArgs): void;
 }
-//# sourceMappingURL=ParseContext.d.ts.map

package/esm/context/ParseIssue.d.ts

@@ -97,4 +97,3 @@ export type ParseIssue = {
     location: string;
     message: string;
 };
-//# sourceMappingURL=ParseIssue.d.ts.map

package/esm/context/RenderContext.d.ts

@@ -185,4 +185,3 @@ export declare class RenderContext {
     pick({ name, exportPath }: PickArgs): DefinitionBase | undefined;
 }
 export {};
-//# sourceMappingURL=RenderContext.d.ts.map

package/esm/context/ResultsHandler.d.ts

@@ -108,4 +108,3 @@ export declare class ResultsHandler extends BaseHandler implements LogHandlerBas
      */
     destroy(): void;
 }
-//# sourceMappingURL=ResultsHandler.d.ts.map

package/esm/context/StackTrail.d.ts

@@ -206,4 +206,3 @@ export declare class StackTrail {
      */
     toString(): string;
 }
-//# sourceMappingURL=StackTrail.d.ts.map