@skmtc/core 0.0.983 → 0.16.1

package/esm/types/Preview.js

@@ -1,91 +1,100 @@
 /**
  * @fileoverview Preview and Mapping System for SKMTC Core
  *
- * This module provides comprehensive types and utilities for creating preview
- * interfaces and mapping configurations for generated code. The preview system
- * enables interactive demonstrations of generated APIs, forms, tables, and
- * other UI components within development tools and documentation.
+ * Types and Valibot schemas for the preview and mapping systems. Generators
+ * may emit a {@link PreviewModule} and/or a {@link MappingModule} per
+ * operation or model; the dispatcher pairs each module with a `*Source`
+ * descriptor so tooling can trace generated code back to its origin in the
+ * source schema.
  *
- * The mapping system provides metadata about how OpenAPI operations and models
- * translate to generated code, enabling rich tooling experiences and
- * reverse-engineering capabilities.
+ * ## Source descriptors
  *
- * ## Key Features
+ * The `source` discriminated union narrows on `type`:
  *
- * - **Interactive Previews**: Rich preview interfaces for generated components
- * - **Source Mapping**: Traceability from generated code back to OpenAPI sources
- * - **UI Grouping**: Organized grouping of related UI components (forms, tables, inputs)
- * - **Generator Integration**: Deep integration with the generator pipeline
- * - **Type Safety**: Comprehensive validation and type safety throughout
+ * - `oasOperation` — carries `operationPath` and `operationMethod` (HTTP)
+ * - `gqlOperation` — carries `rootKind` and `fieldName` (GraphQL)
+ * - `model` — carries `refName` (protocol-neutral)
  *
- * @example Creating operation previews
+ * @example Building an OAS operation source
  * ```typescript
- * import type { PreviewModule, OperationSource } from '@skmtc/core/Preview';
+ * import type { OasOperationSource } from '@skmtc/core/Preview';
  *
- * const operationSource: OperationSource = {
- *   type: 'operation',
+ * const source: OasOperationSource = {
+ *   type: 'oasOperation',
  *   generatorId: 'react-forms',
  *   operationPath: '/users',
- *   operationMethod: 'POST'
+ *   operationMethod: 'post'
  * };
+ * ```
+ *
+ * @example Building a GraphQL operation source
+ * ```typescript
+ * import type { GqlOperationSource } from '@skmtc/core/Preview';
  *
- * const preview: PreviewModule = {
- *   title: 'Create User Form',
- *   description: 'Interactive form for creating new users',
- *   group: 'forms',
- *   source: operationSource,
- *   moduleName: 'CreateUserForm',
- *   exportName: 'default'
+ * const source: GqlOperationSource = {
+ *   type: 'gqlOperation',
+ *   generatorId: 'react-forms',
+ *   rootKind: 'mutation',
+ *   fieldName: 'createUser'
  * };
  * ```
  *
- * @example Creating model previews
+ * @example Building a model source
  * ```typescript
- * import type { PreviewModule, ModelSource } from '@skmtc/core/Preview';
+ * import type { ModelSource } from '@skmtc/core/Preview';
  *
- * const modelSource: ModelSource = {
+ * const source: ModelSource = {
  *   type: 'model',
  *   generatorId: 'typescript-types',
- *   refName: 'User'
- * };
- *
- * const preview: PreviewModule = {
- *   title: 'User Type Definition',
- *   description: 'TypeScript interface for User model',
- *   group: 'tables',
- *   source: modelSource,
- *   moduleName: 'UserTypes',
- *   exportName: 'User'
+ *   refName: 'User',
+ *   variant: 'main'
  * };
  * ```
  *
- * @example Working with mappings
+ * @example Pairing a module with a source
  * ```typescript
- * import type { MappingModule } from '@skmtc/core/Preview';
+ * import type { Preview, PreviewModule } from '@skmtc/core/Preview';
  *
- * const mapping: MappingModule = {
- *   source: operationSource,
- *   moduleName: 'UserApi',
- *   exportName: 'createUser',
- *   generatedPath: './src/generated/UserApi.ts'
+ * const module: PreviewModule = {
+ *   name: 'CreateUserForm',
+ *   exportPath: './generated/forms/CreateUserForm.tsx',
+ *   group: 'forms'
  * };
+ *
+ * const preview: Preview = { module, source };
  * ```
  *
  * @module Preview
  */
+import "../_dnt.polyfills.js";
 import { method } from './Method.js';
 import * as v from 'valibot';
 /**
- * Valibot schema for validating operation source objects.
+ * Valibot schema for validating OAS operation source objects.
  *
- * Validates operation source structures including type, generator ID,
- * operation path, and HTTP method information.
+ * Validates the `oasOperation` source variant — type, generator ID,
+ * operation path, and HTTP method. See {@link gqlOperationSource} for the
+ * GraphQL counterpart.
  */
-export const operationSource = v.object({
-    type: v.literal('operation'),
+export const oasOperationSource = v.object({
+    type: v.literal('oasOperation'),
     generatorId: v.string(),
     operationPath: v.string(),
-    operationMethod: method
+    operationMethod: method,
+    variant: v.string()
+});
+/**
+ * Valibot schema for validating GraphQL operation source objects.
+ *
+ * Sibling to {@link oasOperationSource} for the GraphQL protocol — validates
+ * `rootKind` and `fieldName` instead of `path` / `method`.
+ */
+export const gqlOperationSource = v.object({
+    type: v.literal('gqlOperation'),
+    generatorId: v.string(),
+    rootKind: v.picklist(['query', 'mutation', 'subscription']),
+    fieldName: v.string(),
+    variant: v.string()
 });
 /**
  * Valibot schema for validating model source objects.
@@ -96,37 +105,30 @@ export const operationSource = v.object({
 export const modelSource = v.object({
     type: v.literal('model'),
     generatorId: v.string(),
-    refName: v.string()
+    refName: v.string(),
+    variant: v.string()
 });
-/**
- * Valibot schema for validating preview group values.
- *
- * Validates preview group categories for UI organization.
- */
-export const previewGroup = v.picklist(['forms', 'tables', 'inputs']);
 /**
  * Valibot schema for validating preview module objects.
  *
- * Validates preview module structures including group, title, and description.
+ * Validates preview module structures: name, export path, and group.
  */
 export const previewModule = v.object({
     name: v.string(),
-    exportPath: v.string(),
-    group: previewGroup
+    exportPath: v.string()
 });
 /**
  * Valibot schema for validating mapping module objects.
  *
- * Validates mapping module structures for file relationship tracking.
+ * Validates mapping module structures: name, export path, group, item type
+ * (`'input'` | `'formatter'`), and schema reference.
  */
 export const mappingModule = v.object({
     name: v.string(),
     exportPath: v.string(),
-    group: previewGroup,
-    itemType: v.picklist(['input', 'formatter']),
     schema: v.string()
 });
-const source = v.variant('type', [operationSource, modelSource]);
+const source = v.variant('type', [oasOperationSource, gqlOperationSource, modelSource]);
 /**
  * Valibot schema for validating preview objects.
  *

package/esm/types/RefName.d.ts

@@ -68,6 +68,7 @@
  *
  * @module RefName
  */
+import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
 /**
  * Branded type representing a reference name for OpenAPI schemas.
@@ -97,7 +98,7 @@ import type { Brand } from './Brand.js';
  *
  * @example In generator contexts
  * ```typescript
- * class ModelGenerator extends ModelBase {
+ * class ModelGenerator extends ModelProjectionBase {
  *   constructor(args: { refName: RefName; ... }) {
  *     super(args);
  *     // this.refName is guaranteed to be a valid schema reference
@@ -107,7 +108,7 @@ import type { Brand } from './Brand.js';
  *     // RefName ensures we're working with valid schema identifiers
  *     const schemaName = this.refName; // Type: RefName
  *     return new Definition({
- *       identifier: Identifier.createType(schemaName),
+ *       identifier: createType(schemaName),
  *       // ...
  *     });
  *   }

package/esm/types/RefName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}

package/esm/types/RefName.js

@@ -68,4 +68,4 @@
  *
  * @module RefName
  */
-export {};
+import "../_dnt.polyfills.js";

package/esm/types/Results.d.ts

@@ -95,6 +95,7 @@
  *
  * @module Results
  */
+import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 /**
  * Type representing the possible outcomes of SKMTC processing operations.

package/esm/types/Results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC3E;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}
+{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC3E;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}

package/esm/types/Results.js

@@ -95,6 +95,7 @@
  *
  * @module Results
  */
+import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 /**
  * Valibot schema for validating ResultType values.

package/esm/types/Settings.d.ts

@@ -48,11 +48,17 @@
  *
  * @module Settings
  */
+import "../_dnt.polyfills.js";
 import { type GeneratorEnrichments } from './Enrichments.js';
 import * as v from 'valibot';
 import { type Method } from './Method.js';
 /**
  * Valibot schema for {@link ModulePackage}.
+ *
+ * `rootPath` must be a **forward** path: `client.json` `basePath` is
+ * the common on-disk anchor, so every package sits forward from it.
+ * A `..` segment means `basePath` was placed too deep — a misconfig
+ * that otherwise misplaces every artifact silently.
  */
 export declare const modulePackage: v.GenericSchema<ModulePackage>;
 /**
@@ -84,7 +90,10 @@ export type ModulePackage = {
 /**
  * Valibot schema for validating skip paths configuration.
  *
- * Validates path-to-methods mappings for skipping specific operations.
+ * Validates `path → method → variant[]` mappings for skipping specific
+ * operations. An empty variant array means "every variant of this
+ * method"; a populated array names the variants to deny. Methods
+ * absent from the inner record are unaffected.
  */
 export declare const skipPaths: v.GenericSchema<SkipPaths>;
 /**
@@ -93,48 +102,117 @@ export declare const skipPaths: v.GenericSchema<SkipPaths>;
  * Validates generator-to-skip-paths mappings for skipping operations by generator.
  */
 export declare const skipOperations: v.GenericSchema<SkipOperations>;
+/**
+ * Valibot schema for {@link SkipModelRefs}. Structurally identical to
+ * the operation-arm inner: `refName → variant[]`, with the same
+ * empty-array-means-"all variants" rule.
+ */
+export declare const skipModelRefs: v.GenericSchema<SkipModelRefs>;
 /**
  * Valibot schema for validating skip models configuration.
  *
- * Validates generator-to-model-names mappings for skipping specific models.
+ * Validates generator-to-skip-model-refs mappings for skipping specific
+ * models and variants by generator.
  */
 export declare const skipModels: v.GenericSchema<SkipModels>;
+/**
+ * Valibot schema for {@link IncludePaths}. Structurally identical to
+ * {@link skipPaths} — both map a path to a `method → variant[]` record
+ * — but kept distinct so docstrings can convey the opposite semantics
+ * (allow vs deny) and so the two shapes can diverge in the future
+ * without breaking the other.
+ */
+export declare const includePaths: v.GenericSchema<IncludePaths>;
+/**
+ * Valibot schema for {@link IncludeOperations}. Maps generator id to
+ * {@link IncludePaths}.
+ */
+export declare const includeOperations: v.GenericSchema<IncludeOperations>;
+/**
+ * Valibot schema for {@link IncludeModelRefs}. Sibling to
+ * {@link skipModelRefs} — `refName → variant[]`. Same shape, opposite
+ * semantics.
+ */
+export declare const includeModelRefs: v.GenericSchema<IncludeModelRefs>;
+/**
+ * Valibot schema for {@link IncludeModels}. Maps generator id to a
+ * `refName → variant[]` record.
+ */
+export declare const includeModels: v.GenericSchema<IncludeModels>;
 /**
  * Valibot schema for validating client settings configuration.
  *
  * Validates the complete client settings structure including base paths,
- * packages, skip configurations, and enrichments.
+ * packages, include/skip filters, and enrichments.
+ */
+/**
+ * Valibot schema for the gen-maps (`anchors`) settings block. Lives
+ * inside {@link clientSettings} as an optional field. See
+ * {@link AnchorsSettings} for the consumer-facing fields.
  */
+export declare const anchorsSettings: v.GenericSchema<AnchorsSettings>;
 export declare const clientSettings: v.GenericSchema<ClientSettings>;
 /**
- * Configuration for skipping specific HTTP methods on API paths.
+ * Configuration for skipping specific HTTP methods + variants on API paths.
  *
- * Maps path patterns to arrays of HTTP methods that should be excluded
- * from generation.
+ * Maps `path → method → variant[]`. The variant array uses these conventions:
+ *
+ * - `[]` (empty) means "every variant of this method" — the equivalent
+ *   of pre-variants `[method]`-only entries.
+ * - `['main', 'customer']` means "only those variants" — paired with
+ *   `include`, a way to opt in a subset; paired with `skip`, a way to
+ *   deny a subset.
+ * - Method key absent means "this method is not affected by the entry".
  *
  * @example
  * ```typescript
  * const skipPaths: SkipPaths = {
- *   '/admin/**': ['get', 'post'],
- *   '/debug': ['*']  // Skip all methods
+ *   '/admin/users': { get: [], post: [] },                // skip all variants of both
+ *   '/quotes/{id}': { patch: ['description', 'validity'] } // skip just two variants
+ * };
+ * ```
+ */
+export type SkipPaths = Record<string, Partial<Record<Method, string[]>>>;
+/**
+ * Configuration for skipping specific model refNames + variants.
+ *
+ * Maps `refName → variant[]`. The variant array uses the same
+ * conventions as {@link SkipPaths}:
+ *
+ * - `[]` (empty) means "every variant of this refName" — the equivalent
+ *   of pre-variants whole-model entries.
+ * - `['main', 'coercive']` means "only those variants" — paired with
+ *   `include`, a way to opt in a subset; paired with `skip`, a way to
+ *   deny a subset.
+ * - refName key absent means "this refName is not affected by the entry".
+ *
+ * @example
+ * ```typescript
+ * const skipModelRefs: SkipModelRefs = {
+ *   'InternalModel': [],              // skip all variants
+ *   'Customer':      ['coercive']     // skip just one variant
  * };
  * ```
  */
-export type SkipPaths = Record<string, Method[]>;
+export type SkipModelRefs = Record<string, string[]>;
 /**
  * Configuration for skipping model generation by generator type.
  *
- * Maps generator keys to arrays of model names that should be excluded.
+ * Maps generator keys to {@link SkipModelRefs} configurations for
+ * excluding specific models (and their variants) from generation.
+ *
+ * Model names are matched exactly against the schema's refName; variant
+ * names are matched exactly against the per-model variant key.
  *
  * @example
  * ```typescript
  * const skipModels: SkipModels = {
- *   'typescript-models': ['InternalModel', 'DebugInfo'],
- *   'validation': ['TempModel*']  // Supports glob patterns
+ *   'typescript-models': { 'InternalModel': [], 'DebugInfo': [] },
+ *   'validation':        { 'TempModel': [] }
  * };
  * ```
  */
-export type SkipModels = Record<string, string[]>;
+export type SkipModels = Record<string, SkipModelRefs>;
 /**
  * Configuration for skipping operation generation by generator type.
  *
@@ -159,6 +237,89 @@ export type SkipOperations = Record<string, SkipPaths>;
  * or a simple string pattern for broad exclusions.
  */
 export type Skip = SkipOperations | SkipModels | string;
+/**
+ * Allow-list counterpart to {@link SkipPaths}. Same `path → method →
+ * variant[]` shape and the same `[]`-means-"all variants" rule, but
+ * with opposite semantics: only matching `(path, method, variant)`
+ * tuples are admitted. Matching is exact on path, method, and variant
+ * name. No wildcards or globs.
+ *
+ * @example
+ * ```typescript
+ * const includePaths: IncludePaths = {
+ *   '/customers': { post: [] },                 // all variants of POST
+ *   '/quotes/{id}': { patch: ['description'] }  // only the 'description' variant
+ * };
+ * ```
+ */
+export type IncludePaths = Record<string, Partial<Record<Method, string[]>>>;
+/**
+ * Allow-list counterpart to {@link SkipModelRefs}. Same
+ * `refName → variant[]` shape and the same `[]`-means-"all variants"
+ * rule, but with opposite semantics: only matching `(refName, variant)`
+ * tuples are admitted. Matching is exact on refName and variant name.
+ * No wildcards or globs.
+ *
+ * @example
+ * ```typescript
+ * const includeModelRefs: IncludeModelRefs = {
+ *   'Customer': [],            // all variants of Customer
+ *   'Order':    ['coercive']   // only the 'coercive' variant of Order
+ * };
+ * ```
+ */
+export type IncludeModelRefs = Record<string, string[]>;
+/**
+ * Allow-list counterpart to {@link SkipModels}. Maps generator id to
+ * {@link IncludeModelRefs}.
+ *
+ * @example
+ * ```typescript
+ * const includeModels: IncludeModels = {
+ *   '@skmtc/gen-zod-variants': { 'Customer': [], 'Order': ['coercive'] }
+ * };
+ * ```
+ */
+export type IncludeModels = Record<string, IncludeModelRefs>;
+/**
+ * Allow-list counterpart to {@link SkipOperations}. Maps generator id
+ * to {@link IncludePaths}.
+ *
+ * @example
+ * ```typescript
+ * const includeOperations: IncludeOperations = {
+ *   '@skmtc/gen-shadcn-form': {
+ *     '/customers': ['post'],
+ *     '/locations': ['post']
+ *   }
+ * };
+ * ```
+ */
+export type IncludeOperations = Record<string, IncludePaths>;
+/**
+ * Union type representing allow-list filter entries. Mirrors the
+ * {@link Skip} shape so the two can be combined consistently in
+ * {@link ClientSettings}:
+ *
+ * - A string entry like `'@skmtc/gen-form'` includes the whole generator
+ *   (every operation/model it would otherwise emit).
+ * - An {@link IncludeOperations} entry includes specific (path, method)
+ *   pairs for one operation generator.
+ * - An {@link IncludeModels} entry includes specific refNames for one
+ *   model generator.
+ *
+ * **Presence is the gate.** When `include` is `undefined` or `[]`, no
+ * filter is active (everything emits as if no include were set).
+ * When `include` is set and non-empty, only generators / operations /
+ * models matching at least one entry will emit; everything else is
+ * silently filtered out.
+ *
+ * **Precedence vs `skip`:** `include` builds the candidate set, `skip`
+ * removes from it. An operation that's in both an `include` allow-list
+ * entry AND a `skip` deny-list entry is skipped. This mirrors
+ * `tsconfig.json`'s `include` + `exclude` pair.
+ */
+export type Include = IncludeOperations | IncludeModels | string;
 /**
  * Main configuration object for SKMTC client settings.
  *
@@ -180,36 +341,72 @@ export type Skip = SkipOperations | SkipModels | string;
  * };
  * ```
  *
- * @example Advanced configuration with packages
+ * @example Advanced configuration with enrichments
  * ```typescript
+ * // OAS enrichment hierarchy: generatorId → path → method → { table | form | input }
  * const settings: ClientSettings = {
  *   basePath: './generated',
  *   packages: [
  *     {
  *       rootPath: './packages/client',
  *       moduleName: '@company/api-client'
- *     },
- *     {
- *       rootPath: './packages/types',
- *       moduleName: '@company/api-types'
  *     }
  *   ],
  *   enrichments: {
- *     models: customModelEnrichments,
- *     operations: customOperationEnrichments
+ *     'react-forms': {
+ *       '/users': {
+ *         post: { form: { title: 'Create User', fields: [] } }
+ *       }
+ *     }
  *   },
  *   skip: [
  *     {
- *       'models': ['Internal*', 'Debug*'],
- *       'operations': {
- *         '/health': ['get'],
- *         '/metrics/**': ['*']
+ *       'api-client': {
+ *         '/health': ['get']
  *       }
  *     }
  *   ]
  * };
  * ```
+ *
+ * @example GraphQL enrichment hierarchy
+ * ```typescript
+ * // GraphQL enrichment hierarchy: generatorId → rootKind → fieldName → { table | form | input }
+ * const settings: ClientSettings = {
+ *   basePath: './generated',
+ *   enrichments: {
+ *     'react-forms': {
+ *       mutation: {
+ *         createUser: { form: { title: 'Create User', fields: [] } }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
  */
+/**
+ * Per-project gen-maps (`anchors`) configuration. Lives at
+ * `client.json#settings.anchors`.
+ *
+ * v1 honours the two fields below. Future fields (parser choice,
+ * gzip compression, map toggle) will land additively as the
+ * Phase G adapter swap and Phase D polish work proceeds.
+ */
+export type AnchorsSettings = {
+    /**
+     * Master switch. `true` emits a sidecar per generated source file
+     * and a project-level generation map. `false` (or omitted) runs
+     * generation as if gen-maps didn't exist — zero overhead.
+     */
+    enabled: boolean;
+    /**
+     * Output directory for sidecars + generation map, relative to
+     * `.skmtc/<project>/`. Defaults to `'.maps'` when omitted. The
+     * `skmtc init` template gitignores the `.maps` subtree by default
+     * since sidecars are build output, not source.
+     */
+    out?: string;
+};
 export type ClientSettings = {
     /** Base output path for generated files */
     basePath?: string;
@@ -217,8 +414,22 @@ export type ClientSettings = {
     packages?: ModulePackage[];
     /** Custom enrichments for extending generation */
     enrichments?: GeneratorEnrichments;
-    /** Array of skip configurations to exclude content */
+    /**
+     * Allow-list filter applied before {@link skip}. When set and
+     * non-empty, only generators / operations / models matching an
+     * entry are emitted; everything else is silently filtered out.
+     * See {@link Include} for the per-entry shape and precedence rules.
+     */
+    include?: Include[];
+    /** Array of skip (deny-list) configurations to exclude content */
     skip?: Skip[];
+    /**
+     * Gen-maps (`anchors`) configuration. When `enabled: true`, the CLI
+     * emits per-file sidecars and a generation map alongside the
+     * generated artifacts. Omitted by default; the feature is opt-in
+     * in v1. See {@link AnchorsSettings}.
+     */
+    anchors?: AnchorsSettings;
 };
 /**
  * Configuration for SKMTC client with optional project identification.

package/esm/types/Settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/types/Settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAGvD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAAyC,CAAA;AAE1F;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAmC,CAAA;AAE9F;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAA6C,CAAA;AAIhG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAMzD,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;IAC1B,kDAAkD;IAClD,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC,sDAAsD;IACtD,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAK/D,CAAA"}
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/types/Settings.ts"],"names":[],"mappings":"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"}