@skmtc/core 0.28.4 → 0.28.6

package/esm/dsl/webhook/types.d.ts

@@ -4,6 +4,7 @@ import type { ContentSettings } from '../ContentSettings.js';
 import type { GenerateContextType } from '../../context/generateTypes.js';
 import type { IdentifierType } from '../IdentifierType.js';
 import type { GeneratedValue } from '../GeneratedValue.js';
+import type { ProjectionOptionsArg } from '../../types/ProjectionOptions.js';
 /**
  * External constructor signature for a webhook projection class.
  *
@@ -14,11 +15,11 @@ import type { GeneratedValue } from '../GeneratedValue.js';
  * `operation` — webhooks are a distinct subject ({@link OasWebhook}),
  * so the field name and type differ even though the shape matches.
  */
-export type WebhookProjectionConstructorArgs<EnrichmentType = undefined> = {
+export type WebhookProjectionConstructorArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     context: GenerateContextType;
     settings: ContentSettings<EnrichmentType>;
     webhook: OasWebhook;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 export type TransformWebhookArgs = {
     context: GenerateContextType;
     webhook: OasWebhook;
@@ -55,33 +56,34 @@ export type ToWebhookMappingArgs = {
     variant: string;
 };
 /**
- * Arguments for a webhook projection's `toIdentifierName` — the pure,
- * cache-key-source half of the old `toIdentifier`.
+ * Arguments for a webhook projection's `toIdentifierName`. Fold `options` into the name when the output
+ * depends on them: definitions are cached by name and export path.
  */
-export type ToWebhookIdentifierNameArgs<EnrichmentType = undefined> = {
+export type ToWebhookIdentifierNameArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     webhook: OasWebhook;
     enrichments: EnrichmentType;
     /** Webhook variant the identifier should disambiguate (see {@link Variant}) */
     variant: string;
-};
-export type ToWebhookExportPathArgs<EnrichmentType = undefined> = {
+} & ProjectionOptionsArg<ProjectionOptions>;
+export type ToWebhookExportPathArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     webhook: OasWebhook;
     enrichments: EnrichmentType;
     /** Webhook variant the export path should disambiguate (see {@link Variant}) */
     variant: string;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 /**
  * Static structural type of a webhook projection class.
  *
  * Captures both the instance side (`new(...) => V`) and the static side
  * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
  * `toEnrichments`). Passed as a type parameter to
- * `context.insertWebhook(...)`.
+ * `context.insertWebhook(...)`. `ProjectionOptions` is the caller options
+ * the class declares; the Drivers infer it from the constructor and statics.
  */
-export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = {
     prototype: V;
 } & {
-    new ({ context, settings, webhook }: WebhookProjectionConstructorArgs<EnrichmentType>): V;
+    new ({ context, settings, webhook, options }: WebhookProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): V;
     id: string;
     type: 'webhook';
     /**
@@ -92,7 +94,7 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      */
     lang: Lang;
     /** Pure: the cache-key name. */
-    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Context-aware, overridable: the non-`name` parts of the identifier,
      * derived from the webhook. The engine assembles
@@ -100,7 +102,7 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      * ...toIdentifierType(webhook, context) })`.
      */
     toIdentifierType: (webhook: OasWebhook, context: GenerateContextType) => IdentifierType;
-    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     toEnrichments: ({ webhook, context }: ToWebhookEnrichmentsArgs) => EnrichmentType;
     /**
      * Family-level capability predicate, surfaced as a static by
@@ -111,4 +113,3 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      */
     isSupported?: (args: IsSupportedWebhookArgs) => boolean;
 } & Function;
-//# sourceMappingURL=types.d.ts.map

package/esm/enrichments/EnrichmentAudit.d.ts

@@ -76,4 +76,3 @@ export declare class EnrichmentAudit {
  */
 export declare const hasVariantEnrichment: (block: unknown, variant: string) => boolean;
 export {};
-//# sourceMappingURL=EnrichmentAudit.d.ts.map

package/esm/enrichments/EnrichmentWarning.d.ts

@@ -69,4 +69,3 @@ export declare const enrichmentWarning: v.GenericSchema<EnrichmentWarning>;
  * segments visually distinct even when they contain dots or slashes.
  */
 export declare const formatEnrichmentPath: (path: readonly string[]) => string;
-//# sourceMappingURL=EnrichmentWarning.d.ts.map

package/esm/enrichments/findUnknownKeys.d.ts

@@ -37,4 +37,3 @@ export type UnknownKey = {
  * the subsequent `v.parse` throws on those as before.
  */
 export declare const findUnknownKeys: (schema: unknown, value: unknown) => UnknownKey[];
-//# sourceMappingURL=findUnknownKeys.d.ts.map

package/esm/enrichments/parseEnrichmentUmbrella.d.ts

@@ -60,4 +60,3 @@ type ParseEnrichmentUmbrellaArgs<EnrichmentType> = {
  */
 export declare const parseEnrichmentUmbrella: <EnrichmentType>({ context, generatorId, subjectSegments, schema }: ParseEnrichmentUmbrellaArgs<EnrichmentType>) => EnrichmentType;
 export {};
-//# sourceMappingURL=parseEnrichmentUmbrella.d.ts.map

package/esm/enrichments/readEnrichments.d.ts

@@ -66,4 +66,3 @@ export declare const toGeneratorEnrichment: <EnrichmentType>(context: Enrichment
  */
 export declare const toStackEnrichment: <EnrichmentType>(context: EnrichmentReadContext, schema: v.GenericSchema<EnrichmentType>) => EnrichmentType;
 export {};
-//# sourceMappingURL=readEnrichments.d.ts.map

package/esm/enrichments/toEnrichmentDescriptor.d.ts

@@ -139,4 +139,3 @@ export declare const toEnrichmentFields: (schema: v.GenericSchema | undefined) =
  * sits above it in the editor UI, since the variant axis is core-owned.
  */
 export declare const toEnrichmentDescriptor: (entry: EnrichmentSource) => EnrichmentDescriptor;
-//# sourceMappingURL=toEnrichmentDescriptor.d.ts.map

package/esm/enrichments/valibotShape.d.ts

@@ -48,4 +48,3 @@ export declare const unwrap: (schema: ValibotSchemaShape) => {
  * would silently break the lookup.
  */
 export declare const baseOf: (schema: ValibotSchemaShape) => ValibotSchemaShape;
-//# sourceMappingURL=valibotShape.d.ts.map

package/esm/enrichments/validateConfig.d.ts

@@ -57,4 +57,3 @@ export type EnrichmentValidationIssue = {
  * entry-like objects.
  */
 export declare const validateConfig: (enrichments: GeneratorEnrichments | undefined, sources: readonly EnrichmentSource[]) => EnrichmentValidationIssue[];
-//# sourceMappingURL=validateConfig.d.ts.map

package/esm/gql/_helpers/recordAppliedDirectives.d.ts

@@ -22,4 +22,3 @@ export type RecordAppliedDirectivesArgs = {
  * pure-runtime constructions, so we guard.
  */
 export declare const recordAppliedDirectives: ({ astNode, stackTrail, context }: RecordAppliedDirectivesArgs) => void;
-//# sourceMappingURL=recordAppliedDirectives.d.ts.map

package/esm/gql/_helpers/unwrapType.d.ts

@@ -36,4 +36,3 @@ export type UnwrappedType = {
  * peeled outermost first. This walks the chain and records the bookkeeping.
  */
 export declare const unwrapType: (type: GraphQLType) => UnwrappedType;
-//# sourceMappingURL=unwrapType.d.ts.map

package/esm/gql/argument/GqlArgument.d.ts

@@ -52,4 +52,3 @@ export declare class GqlArgument extends OasBase {
     readonly deprecationReason: string | undefined;
     constructor(fields: GqlArgumentFields, context?: ParseContextType);
 }
-//# sourceMappingURL=GqlArgument.d.ts.map

package/esm/gql/document/GqlDocument.d.ts

@@ -90,4 +90,3 @@ export declare class GqlDocument {
      */
     removeItem(stackTrail: StackTrail): unknown;
 }
-//# sourceMappingURL=GqlDocument.d.ts.map

package/esm/gql/document/parseGqlDocument.d.ts

@@ -30,4 +30,3 @@ export type ParseGqlDocumentArgs = {
 export declare const parseGqlDocument: ({ options, context, stackTrail }: ParseGqlDocumentArgs) => {
     fields: GqlDocumentFields;
 };
-//# sourceMappingURL=parseGqlDocument.d.ts.map

package/esm/gql/enum/toEnumType.d.ts

@@ -26,4 +26,3 @@ export type ToEnumTypeArgs = {
  * threaded for future diagnostic reporting; today the function is pure.
  */
 export declare const toEnumType: ({ enumType, nullable, context, stackTrail }: ToEnumTypeArgs) => OasString;
-//# sourceMappingURL=toEnumType.d.ts.map

package/esm/gql/field/toFieldSchema.d.ts

@@ -35,4 +35,3 @@ export type ToFieldSchemaArgs = {
  * `OasArray.nullable` and the inner schema's nullability.
  */
 export declare const toFieldSchema: ({ type, context, stackTrail }: ToFieldSchemaArgs) => OasSchema | OasRef<"schema">;
-//# sourceMappingURL=toFieldSchema.d.ts.map

package/esm/gql/input/toInputType.d.ts

@@ -25,4 +25,3 @@ export type ToInputTypeArgs = {
  * `default` slot when present.
  */
 export declare const toInputType: ({ inputType, context, stackTrail }: ToInputTypeArgs) => OasObject;
-//# sourceMappingURL=toInputType.d.ts.map

package/esm/gql/interface/toInterfaceUnion.d.ts

@@ -25,4 +25,3 @@ export type ToInterfaceUnionArgs = {
  * generators select whichever they prefer.
  */
 export declare const toInterfaceUnion: ({ interfaceType, context, stackTrail }: ToInterfaceUnionArgs) => OasUnion;
-//# sourceMappingURL=toInterfaceUnion.d.ts.map

package/esm/gql/object/toObjectType.d.ts

@@ -20,4 +20,3 @@ export type ToObjectTypeArgs = {
  * model so the user would otherwise have no signal that they exist.
  */
 export declare const toObjectType: ({ objectType, context, stackTrail }: ToObjectTypeArgs) => OasObject;
-//# sourceMappingURL=toObjectType.d.ts.map

package/esm/gql/operation/GqlOperation.d.ts

@@ -60,4 +60,3 @@ export declare class GqlOperation extends OasBase {
      */
     get identifier(): string;
 }
-//# sourceMappingURL=GqlOperation.d.ts.map

package/esm/gql/operation/synthesizeArgsObject.d.ts

@@ -19,4 +19,3 @@ import { OasObject } from '../../oas/object/Object.js';
  * generator-specific output assumptions.
  */
 export declare const synthesizeArgsObject: (operation: GqlOperation) => OasObject | undefined;
-//# sourceMappingURL=synthesizeArgsObject.d.ts.map

package/esm/gql/operation/toRootField.d.ts

@@ -23,4 +23,3 @@ export type ToRootFieldArgs = {
  * runs through {@link toFieldSchema} like any other field type.
  */
 export declare const toRootField: ({ rootKind, field, context, stackTrail }: ToRootFieldArgs) => GqlOperation;
-//# sourceMappingURL=toRootField.d.ts.map

package/esm/gql/registry/GqlRegistry.d.ts

@@ -67,4 +67,3 @@ export declare class GqlRegistry {
      */
     removeSchema(refName: RefName): boolean;
 }
-//# sourceMappingURL=GqlRegistry.d.ts.map

package/esm/gql/rootType/GqlRootTypes.d.ts

@@ -12,4 +12,3 @@ export type GqlRootTypes = {
     mutation?: RefName;
     subscription?: RefName;
 };
-//# sourceMappingURL=GqlRootTypes.d.ts.map

package/esm/gql/scalar/toScalarType.d.ts

@@ -30,4 +30,3 @@ export type ToScalarTypeArgs = {
  * without an API change.
  */
 export declare const toScalarType: ({ scalar, nullable, context, stackTrail }: ToScalarTypeArgs) => OasSchema;
-//# sourceMappingURL=toScalarType.d.ts.map

package/esm/gql/union/toUnionType.d.ts

@@ -21,4 +21,3 @@ export type ToUnionTypeArgs = {
  * pruned at the end of parsing.
  */
 export declare const toUnionType: ({ unionType, context, stackTrail }: ToUnionTypeArgs) => OasUnion;
-//# sourceMappingURL=toUnionType.d.ts.map

package/esm/helpers/ResultsLog.d.ts

@@ -198,4 +198,3 @@ export declare class ResultsLog {
      */
     toTree(): ResultsItem;
 }
-//# sourceMappingURL=ResultsLog.d.ts.map

package/esm/helpers/applyGeneratedSuffix.d.ts

@@ -40,4 +40,3 @@ export declare const applyGeneratedSuffix: (path: string, suffix: string) => str
  * flow to compute the owned name of a generated file.
  */
 export declare const removeGeneratedSuffix: (path: string, suffix: string) => string;
-//# sourceMappingURL=applyGeneratedSuffix.d.ts.map

package/esm/helpers/collateExamples.d.ts

@@ -9,6 +9,16 @@ type CollatedExampleArgs = {
     objectSchema: OasSchema | OasRef<'schema'> | undefined;
     /** Current recursion depth (used to prevent infinite loops) */
     depth: number;
+    /**
+     * The `$ref` pointers already entered on THIS path, used to cut reference
+     * cycles. Callers start collation without it; the function threads it.
+     *
+     * Path-scoped rather than global on purpose. A global set would also stop a
+     * cycle, and would additionally drop the example for the SECOND of two
+     * sibling uses of the same schema — silently emptying samples on every
+     * document that reuses a type, which is most of them.
+     */
+    seen?: ReadonlySet<string>;
 };
 /**
  * Recursively collates and builds example values from OpenAPI schemas.
@@ -155,6 +165,5 @@ type CollatedExampleArgs = {
  * }
  * ```
  */
-export declare const collateExamples: ({ objectSchema, depth }: CollatedExampleArgs) => unknown;
+export declare const collateExamples: ({ objectSchema, depth, seen }: CollatedExampleArgs) => unknown;
 export {};
-//# sourceMappingURL=collateExamples.d.ts.map

package/esm/helpers/collateExamples.js

@@ -145,7 +145,7 @@ import { isEmpty } from './isEmpty.js';
  * }
  * ```
  */
-export const collateExamples = ({ objectSchema, depth }) => {
+export const collateExamples = ({ objectSchema, depth, seen }) => {
     if (!objectSchema) {
         return undefined;
     }
@@ -154,9 +154,21 @@ export const collateExamples = ({ objectSchema, depth }) => {
     }
     switch (objectSchema.type) {
         case 'ref': {
+            // A schema that reaches itself has no finite example, so the recursive
+            // key is omitted and collation continues around it.
+            //
+            // Without this the cycle simply pads the path until the depth limit
+            // throws, roughly sixteen steps in — so a self-referential schema and a
+            // legitimately deep one fail identically, and a caller that only wanted a
+            // sample body gets an exception instead. Cutting the cycle here is what
+            // makes the depth limit mean what it says.
+            if (seen?.has(objectSchema.$ref)) {
+                return undefined;
+            }
             return collateExamples({
                 objectSchema: objectSchema.resolve(),
-                depth: depth + 1
+                depth: depth + 1,
+                seen: new Set(seen ?? []).add(objectSchema.$ref)
             });
         }
         case 'object': {
@@ -170,7 +182,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
                 }
                 const propertyExample = collateExamples({
                     objectSchema: value,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (propertyExample) {
                     output[key] = propertyExample;
@@ -184,7 +197,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
             }
             const itemsExample = collateExamples({
                 objectSchema: objectSchema.items,
-                depth: depth + 1
+                depth: depth + 1,
+                seen
             });
             return itemsExample ? [itemsExample] : undefined;
         }
@@ -202,7 +216,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
             for (const member of objectSchema.members) {
                 const unionExample = collateExamples({
                     objectSchema: member,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (unionExample) {
                     return unionExample;

package/esm/helpers/formatNumber.d.ts

@@ -95,4 +95,3 @@
  */
 import "../_dnt.polyfills.js";
 export declare const formatNumber: (value: number, locales?: Intl.LocalesArgument) => string;
-//# sourceMappingURL=formatNumber.d.ts.map

package/esm/helpers/isEmpty.d.ts

@@ -3,4 +3,3 @@
  */
 import "../_dnt.polyfills.js";
 export declare const isEmpty: (value: object) => boolean;
-//# sourceMappingURL=isEmpty.d.ts.map

package/esm/helpers/isGeneratorName.d.ts

@@ -1,2 +1 @@
 export declare const isGeneratorName: (name: string) => boolean;
-//# sourceMappingURL=isGeneratorName.d.ts.map

package/esm/helpers/isImported.d.ts

@@ -79,4 +79,3 @@
  * ```
  */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;
-//# sourceMappingURL=isImported.d.ts.map

package/esm/helpers/matchPackage.d.ts

@@ -0,0 +1,54 @@
+import type { ModulePackage } from '../types/Settings.js';
+/**
+ * Arguments for {@link matchPackage}.
+ */
+export type MatchPackageArgs = {
+    /** The artifact path to locate, in any spelling — see {@link toWorkspacePath} */
+    path: string;
+    /** `settings.packages`; roots may nest and may be listed in any order */
+    packages: ModulePackage[] | undefined;
+};
+/**
+ * The packages a path belongs to. Both carry a canonical `rootPath`.
+ *
+ * Package roots may nest — a nested root is a subpath export of the package
+ * around it — so one path can sit under several roots. They nest as a chain
+ * (each is an ancestor of the next), and the two ends of the chain answer the
+ * two questions a language package asks.
+ */
+export type PackageMatch = {
+    /**
+     * The widest root containing the path — the package. Decides whether an
+     * import is intra-package: every file in the package shares one alias,
+     * rooted here.
+     */
+    outermost: ModulePackage;
+    /**
+     * The narrowest root containing the path — the subpath. Its `moduleName` is
+     * what a file outside the package imports (`@acme/sdk/models`); its folders
+     * are what a Kotlin `package` directive starts after.
+     */
+    innermost: ModulePackage;
+};
+/**
+ * Finds the package roots containing `path`, or `undefined` when no root does.
+ *
+ * Roots are compared as folders in canonical spelling, so `./packages/sdk/`,
+ * `@/packages/sdk` and `packages/sdk` are one root, and the order of
+ * `packages` never matters. A root contains itself, so a directory import
+ * of a root (`packages/sdk/src/models`, its barrel) belongs to that root.
+ * `packages` is expected to have passed the {@link clientSettings} schema,
+ * which rejects duplicate roots and the workspace root.
+ *
+ * @example
+ * ```typescript
+ * const packages = [
+ *   { rootPath: 'packages/sdk/src', moduleName: '@acme/sdk' },
+ *   { rootPath: 'packages/sdk/src/models', moduleName: '@acme/sdk/models' }
+ * ]
+ * matchPackage({ path: '@/packages/sdk/src/models/User.ts', packages })
+ * // { outermost: { rootPath: 'packages/sdk/src', … }, innermost: { rootPath: 'packages/sdk/src/models', … } }
+ * matchPackage({ path: 'zod', packages }) // undefined
+ * ```
+ */
+export declare const matchPackage: ({ path, packages }: MatchPackageArgs) => PackageMatch | undefined;

package/esm/helpers/matchPackage.js

@@ -0,0 +1,35 @@
+import { isUnderRoot, toWorkspacePath } from './toWorkspacePath.js';
+/**
+ * Finds the package roots containing `path`, or `undefined` when no root does.
+ *
+ * Roots are compared as folders in canonical spelling, so `./packages/sdk/`,
+ * `@/packages/sdk` and `packages/sdk` are one root, and the order of
+ * `packages` never matters. A root contains itself, so a directory import
+ * of a root (`packages/sdk/src/models`, its barrel) belongs to that root.
+ * `packages` is expected to have passed the {@link clientSettings} schema,
+ * which rejects duplicate roots and the workspace root.
+ *
+ * @example
+ * ```typescript
+ * const packages = [
+ *   { rootPath: 'packages/sdk/src', moduleName: '@acme/sdk' },
+ *   { rootPath: 'packages/sdk/src/models', moduleName: '@acme/sdk/models' }
+ * ]
+ * matchPackage({ path: '@/packages/sdk/src/models/User.ts', packages })
+ * // { outermost: { rootPath: 'packages/sdk/src', … }, innermost: { rootPath: 'packages/sdk/src/models', … } }
+ * matchPackage({ path: 'zod', packages }) // undefined
+ * ```
+ */
+export const matchPackage = ({ path, packages = [] }) => {
+    // Every root here contains the same path, so the roots nest: each is a
+    // prefix of the next. Ordering by length is therefore ordering by depth,
+    // outermost first.
+    const containing = packages
+        .map(({ rootPath, moduleName }) => ({ rootPath: toWorkspacePath(rootPath), moduleName }))
+        .filter(modulePackage => isUnderRoot({ path, rootPath: modulePackage.rootPath }))
+        .sort((a, b) => a.rootPath.length - b.rootPath.length);
+    if (containing.length === 0) {
+        return undefined;
+    }
+    return { outermost: containing[0], innermost: containing[containing.length - 1] };
+};

package/esm/helpers/naming.d.ts

@@ -70,4 +70,3 @@ export declare const toArgsName: (operation: OasOperation) => string;
  * ```
  */
 export declare const toMethodVerb: (method: Method) => string;
-//# sourceMappingURL=naming.d.ts.map

package/esm/helpers/nearestKey.d.ts

@@ -15,4 +15,3 @@
  * `undefined` — a key that exists needs no suggestion.
  */
 export declare const nearestKey: (target: string, candidates: Iterable<string>) => string | undefined;
-//# sourceMappingURL=nearestKey.d.ts.map

package/esm/helpers/parseModuleName.d.ts

@@ -180,4 +180,3 @@ export type ParsedModuleName = {
  * ```
  */
 export declare const parseModuleName: (moduleName: string) => ParsedModuleName;
-//# sourceMappingURL=parseModuleName.d.ts.map

package/esm/helpers/refFns.d.ts

@@ -169,4 +169,3 @@ export declare const isRef: (value: unknown) => value is Ref;
  */
 export declare const toGetRef: (oasDocument: OpenAPIV3.Document) => ({ $ref }: ReferenceObject) => OpenAPIV3.SchemaObject;
 export {};
-//# sourceMappingURL=refFns.d.ts.map

package/esm/helpers/strings.d.ts

@@ -124,4 +124,3 @@ type CamelCaseOptions = {
  */
 export declare const camelCase: (str: string, { upperFirst, retainUnderscores }?: CamelCaseOptions) => string;
 export {};
-//# sourceMappingURL=strings.d.ts.map