@skmtc/core 0.0.984 → 0.16.1

package/script/dsl/Definition.d.ts

@@ -1,220 +1,52 @@
 import type { GenerateContextType } from '../context/generateTypes.js';
-import type { Identifier } from './Identifier.js';
-import { ContentBase } from './ContentBase.js';
+import type { IdentifierBase } from './IdentifierBase.js';
+import { SnippetBase } from './SnippetBase.js';
 import type { GeneratedValue } from './GeneratedValue.js';
 /**
- * Constructor arguments for {@link Definition}.
+ * Constructor arguments for {@link DefinitionBase}.
  *
  * @template V - The type of generated value this definition contains
  */
-type ConstructorArgs<V extends GeneratedValue> = {
+type DefinitionBaseArgs<V extends GeneratedValue> = {
     /** The generation context providing pipeline access */
     context: GenerateContextType;
-    /** Optional description for JSDoc comments */
-    description?: string;
     /** The identifier for this definition */
-    identifier: Identifier;
+    identifier: IdentifierBase;
     /** The generated value content */
     value: V;
-    /** Whether to skip the export keyword */
-    noExport?: boolean;
 };
 /**
- * Represents a complete code definition in the SKMTC DSL system.
- *
- * The `Definition` class is the primary output unit of generators, representing
- * a complete piece of generated code (like an interface, function, or constant).
- * It combines an identifier, generated content, and optional metadata into a
- * formatted code definition with proper TypeScript syntax.
- *
- * This class automatically handles export statements, type annotations, and
- * JSDoc comment generation, making it the building block for all generated
- * code artifacts.
- *
- * ## Key Features
- *
- * - **Automatic Exports**: Handles export keyword based on configuration
- * - **Type Safety**: Preserves type information through generic parameters
- * - **JSDoc Integration**: Automatic comment generation from descriptions
- * - **Entity Type Support**: Handles different definition types (const, type, etc.)
- * - **Identifier Management**: Integrates with the Identifier system for naming
- *
- * @template V - The type of generated value (preserves generator-specific types)
- *
- * @example Basic interface definition
- * ```typescript
- * import { Definition, Identifier } from '@skmtc/core';
- *
- * const userInterface = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createType('User'),
- *   description: 'Represents a user in the system',
- *   value: {
- *     generatorKey: 'typescript-interfaces',
- *     content: `{
- *       id: string;
- *       name: string;
- *       email: string;
- *     }`
- *   }
- * });
- *
- * console.log(userInterface.toString());
- * //
- * // Represents a user in the system
- * //
- * // export type User = {
- * //   id: string;
- * //   name: string;
- * //   email: string;
- * // };
- * ```
- *
- * @example Function definition with parameters
- * ```typescript
- * const apiFunction = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createVariable('fetchUser', 'Promise<User>'),
- *   description: 'Fetches a user by ID from the API',
- *   value: {
- *     generatorKey: 'api-client',
- *     content: `async (id: string) => {
- *       const response = await fetch(\`/api/users/\${id}\`);
- *       return response.json();
- *     }`
- *   }
- * });
- *
- * console.log(apiFunction.toString());
- * //
- * //  Fetches a user by ID from the API
- * //
- * // export const fetchUser: Promise<User> = async (id: string) => {
- * //   const response = await fetch(`/api/users/${id}`);
- * //   return response.json();
- * // };
- * ```
- *
- * @example Non-exported definition
- * ```typescript
- * const helperFunction = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createVariable('validateEmail'),
- *   value: {
- *     generatorKey: 'utilities',
- *     content: `(email: string): boolean => {
- *       return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email);
- *     }`
- *   },
- *   noExport: true // Internal helper, not exported
- * });
- *
- * console.log(helperFunction.toString());
- * // const validateEmail = (email: string): boolean => {
- * //   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
- * // };
- * ```
- *
- * @example Using in generator classes
- * ```typescript
- * import { ModelBase, Definition, Identifier } from '@skmtc/core';
- *
- * class TypeScriptInterface extends ModelBase {
- *   toDefinition(): Definition {
- *     const schema = this.context.getSchema(this.refName);
- *
- *     return new Definition({
- *       context: this.context,
- *       identifier: Identifier.createType(this.refName),
- *       description: schema.description,
- *       value: {
- *         generatorKey: this.generatorKey,
- *         content: this.generateInterfaceBody(schema)
- *       }
- *     });
- *   }
- * }
- * ```
+ * The language-neutral coordination surface of a registered, named
+ * definition.
+ *
+ * The cross-generator cache reads only this surface — the definition's
+ * `identifier` (the `(name, exportPath)` cache key), its `value`, and the
+ * `generatorKey` (via {@link SnippetBase}) for the integrity check. How a
+ * definition renders — the `export const X = …` wrapper, JSDoc, the
+ * export/visibility keyword — is the concrete subclass's concern, so
+ * `toString()` is abstract here.
+ *
+ * Concrete rendering subclasses live in the language packages
+ * (`TsDefinition` in `@skmtc/lang-typescript`); Drivers construct them
+ * through the `Lang` factories (`lang.toDefinition`).
  */
-export declare class Definition<V extends GeneratedValue = GeneratedValue> extends ContentBase {
+export declare abstract class DefinitionBase<V extends GeneratedValue = GeneratedValue> extends SnippetBase {
     /** The identifier for this definition */
-    identifier: Identifier;
-    /** Optional description for JSDoc comments */
-    description: string | undefined;
+    identifier: IdentifierBase;
     /** The generated value content */
     value: V;
-    /** Whether to skip the export keyword */
-    noExport?: boolean;
-    /**
-     * Creates a new Definition instance.
-     *
-     * @param args - Definition configuration
-     * @param args.context - Generation context for pipeline access
-     * @param args.identifier - The identifier (name and type info) for this definition
-     * @param args.value - The generated content value
-     * @param args.description - Optional description for JSDoc comments
-     * @param args.noExport - Whether to omit the export keyword (default: false)
-     *
-     * @example
-     * ```typescript
-     * const constant = new Definition({
-     *   context: generateContext,
-     *   identifier: Identifier.createVariable('API_BASE_URL', 'string'),
-     *   description: 'Base URL for all API requests',
-     *   value: {
-     *     generatorKey: 'constants',
-     *     content: "'https://api.example.com'"
-     *   }
-     * });
-     * ```
-     */
-    constructor({ context, identifier, value, description, noExport }: ConstructorArgs<V>);
-    /**
-     * Generates the complete TypeScript definition code.
-     *
-     * This method produces a properly formatted TypeScript definition with:
-     * - Optional JSDoc comments from the description
-     * - Export keyword (unless noExport is true)
-     * - Entity type (const, type, function, etc.)
-     * - Identifier with optional type annotation
-     * - Generated value content
-     *
-     * The output follows TypeScript syntax conventions and can be written
-     * directly to a .ts file.
-     *
-     * @returns The complete TypeScript definition as a string
-     *
-     * @example Type definition
-     * ```typescript
-     * const typeDef = new Definition({
-     *   context,
-     *   identifier: Identifier.createType('Status'),
-     *   description: 'Possible status values',
-     *   value: { generatorKey: 'types', content: "'pending' | 'complete' | 'failed'" }
-     * });
-     *
-     * console.log(typeDef.toString());
-     * //
-     * // Possible status values
-     * //
-     * // export type Status = 'pending' | 'complete' | 'failed';
-     * ```
-     *
-     * @example Constant definition
-     * ```typescript
-     * const constDef = new Definition({
-     *   context,
-     *   identifier: Identifier.createVariable('DEFAULT_TIMEOUT', 'number'),
-     *   value: { generatorKey: 'config', content: '5000' }
-     * });
-     *
-     * console.log(constDef.toString());
-     * // export const DEFAULT_TIMEOUT: number = 5000;
-     * ```
-     *
-     * @todo Move syntax to typescript package to enable language-agnostic use
-     */
-    toString(): string;
+    constructor({ context, identifier, value }: DefinitionBaseArgs<V>);
+    /** Renders the definition's code. Implemented by the concrete subclass. */
+    abstract toString(): string;
 }
+/**
+ * Arguments for {@link Definable.toDefinition}.
+ */
+export type ToDefinitionArgs = {
+    /** The identifier the definition is registered under. */
+    identifier: IdentifierBase;
+    /** Whether to omit the export keyword. */
+    noExport?: boolean;
+};
 export {};
 //# sourceMappingURL=Definition.d.ts.map

package/script/dsl/Definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,uDAAuD;IACvD,OAAO,EAAE,mBAAmB,CAAA;IAC5B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IACtB,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IACR,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,WAAW;IACpF,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IAEtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAE/B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IAER,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IASrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACM,QAAQ,IAAI,MAAM;CAa5B"}
+{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;GAIG;AACH,KAAK,kBAAkB,CAAC,CAAC,SAAS,cAAc,IAAI;IAClD,uDAAuD;IACvD,OAAO,EAAE,mBAAmB,CAAA;IAC5B,yCAAyC;IACzC,UAAU,EAAE,cAAc,CAAA;IAC1B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;CACT,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,cAAc,CAClC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,WAAW;IACnB,yCAAyC;IACzC,UAAU,EAAE,cAAc,CAAA;IAE1B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;gBAEI,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAOjE,2EAA2E;aACzD,QAAQ,IAAI,MAAM;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yDAAyD;IACzD,UAAU,EAAE,cAAc,CAAA;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}

package/script/dsl/Definition.js

@@ -1,150 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Definition = void 0;
-const ContentBase_js_1 = require("./ContentBase.js");
-const withDescription_js_1 = require("../typescript/withDescription.js");
+exports.DefinitionBase = void 0;
+const SnippetBase_js_1 = require("./SnippetBase.js");
 /**
- * Represents a complete code definition in the SKMTC DSL system.
- *
- * The `Definition` class is the primary output unit of generators, representing
- * a complete piece of generated code (like an interface, function, or constant).
- * It combines an identifier, generated content, and optional metadata into a
- * formatted code definition with proper TypeScript syntax.
- *
- * This class automatically handles export statements, type annotations, and
- * JSDoc comment generation, making it the building block for all generated
- * code artifacts.
- *
- * ## Key Features
- *
- * - **Automatic Exports**: Handles export keyword based on configuration
- * - **Type Safety**: Preserves type information through generic parameters
- * - **JSDoc Integration**: Automatic comment generation from descriptions
- * - **Entity Type Support**: Handles different definition types (const, type, etc.)
- * - **Identifier Management**: Integrates with the Identifier system for naming
- *
- * @template V - The type of generated value (preserves generator-specific types)
- *
- * @example Basic interface definition
- * ```typescript
- * import { Definition, Identifier } from '@skmtc/core';
- *
- * const userInterface = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createType('User'),
- *   description: 'Represents a user in the system',
- *   value: {
- *     generatorKey: 'typescript-interfaces',
- *     content: `{
- *       id: string;
- *       name: string;
- *       email: string;
- *     }`
- *   }
- * });
- *
- * console.log(userInterface.toString());
- * //
- * // Represents a user in the system
- * //
- * // export type User = {
- * //   id: string;
- * //   name: string;
- * //   email: string;
- * // };
- * ```
- *
- * @example Function definition with parameters
- * ```typescript
- * const apiFunction = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createVariable('fetchUser', 'Promise<User>'),
- *   description: 'Fetches a user by ID from the API',
- *   value: {
- *     generatorKey: 'api-client',
- *     content: `async (id: string) => {
- *       const response = await fetch(\`/api/users/\${id}\`);
- *       return response.json();
- *     }`
- *   }
- * });
- *
- * console.log(apiFunction.toString());
- * //
- * //  Fetches a user by ID from the API
- * //
- * // export const fetchUser: Promise<User> = async (id: string) => {
- * //   const response = await fetch(`/api/users/${id}`);
- * //   return response.json();
- * // };
- * ```
- *
- * @example Non-exported definition
- * ```typescript
- * const helperFunction = new Definition({
- *   context: generateContext,
- *   identifier: Identifier.createVariable('validateEmail'),
- *   value: {
- *     generatorKey: 'utilities',
- *     content: `(email: string): boolean => {
- *       return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email);
- *     }`
- *   },
- *   noExport: true // Internal helper, not exported
- * });
- *
- * console.log(helperFunction.toString());
- * // const validateEmail = (email: string): boolean => {
- * //   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
- * // };
- * ```
- *
- * @example Using in generator classes
- * ```typescript
- * import { ModelBase, Definition, Identifier } from '@skmtc/core';
- *
- * class TypeScriptInterface extends ModelBase {
- *   toDefinition(): Definition {
- *     const schema = this.context.getSchema(this.refName);
- *
- *     return new Definition({
- *       context: this.context,
- *       identifier: Identifier.createType(this.refName),
- *       description: schema.description,
- *       value: {
- *         generatorKey: this.generatorKey,
- *         content: this.generateInterfaceBody(schema)
- *       }
- *     });
- *   }
- * }
- * ```
+ * The language-neutral coordination surface of a registered, named
+ * definition.
+ *
+ * The cross-generator cache reads only this surface — the definition's
+ * `identifier` (the `(name, exportPath)` cache key), its `value`, and the
+ * `generatorKey` (via {@link SnippetBase}) for the integrity check. How a
+ * definition renders — the `export const X = …` wrapper, JSDoc, the
+ * export/visibility keyword — is the concrete subclass's concern, so
+ * `toString()` is abstract here.
+ *
+ * Concrete rendering subclasses live in the language packages
+ * (`TsDefinition` in `@skmtc/lang-typescript`); Drivers construct them
+ * through the `Lang` factories (`lang.toDefinition`).
  */
-class Definition extends ContentBase_js_1.ContentBase {
-    /**
-     * Creates a new Definition instance.
-     *
-     * @param args - Definition configuration
-     * @param args.context - Generation context for pipeline access
-     * @param args.identifier - The identifier (name and type info) for this definition
-     * @param args.value - The generated content value
-     * @param args.description - Optional description for JSDoc comments
-     * @param args.noExport - Whether to omit the export keyword (default: false)
-     *
-     * @example
-     * ```typescript
-     * const constant = new Definition({
-     *   context: generateContext,
-     *   identifier: Identifier.createVariable('API_BASE_URL', 'string'),
-     *   description: 'Base URL for all API requests',
-     *   value: {
-     *     generatorKey: 'constants',
-     *     content: "'https://api.example.com'"
-     *   }
-     * });
-     * ```
-     */
-    constructor({ context, identifier, value, description, noExport }) {
+class DefinitionBase extends SnippetBase_js_1.SnippetBase {
+    constructor({ context, identifier, value }) {
         super({ context, generatorKey: value.generatorKey });
         /** The identifier for this definition */
         Object.defineProperty(this, "identifier", {
@@ -153,13 +27,6 @@ class Definition extends ContentBase_js_1.ContentBase {
             writable: true,
             value: void 0
         });
-        /** Optional description for JSDoc comments */
-        Object.defineProperty(this, "description", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         /** The generated value content */
         Object.defineProperty(this, "value", {
             enumerable: true,
@@ -167,71 +34,8 @@ class Definition extends ContentBase_js_1.ContentBase {
             writable: true,
             value: void 0
         });
-        /** Whether to skip the export keyword */
-        Object.defineProperty(this, "noExport", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         this.value = value;
         this.identifier = identifier;
-        this.description = description;
-        this.noExport = noExport;
-    }
-    /**
-     * Generates the complete TypeScript definition code.
-     *
-     * This method produces a properly formatted TypeScript definition with:
-     * - Optional JSDoc comments from the description
-     * - Export keyword (unless noExport is true)
-     * - Entity type (const, type, function, etc.)
-     * - Identifier with optional type annotation
-     * - Generated value content
-     *
-     * The output follows TypeScript syntax conventions and can be written
-     * directly to a .ts file.
-     *
-     * @returns The complete TypeScript definition as a string
-     *
-     * @example Type definition
-     * ```typescript
-     * const typeDef = new Definition({
-     *   context,
-     *   identifier: Identifier.createType('Status'),
-     *   description: 'Possible status values',
-     *   value: { generatorKey: 'types', content: "'pending' | 'complete' | 'failed'" }
-     * });
-     *
-     * console.log(typeDef.toString());
-     * //
-     * // Possible status values
-     * //
-     * // export type Status = 'pending' | 'complete' | 'failed';
-     * ```
-     *
-     * @example Constant definition
-     * ```typescript
-     * const constDef = new Definition({
-     *   context,
-     *   identifier: Identifier.createVariable('DEFAULT_TIMEOUT', 'number'),
-     *   value: { generatorKey: 'config', content: '5000' }
-     * });
-     *
-     * console.log(constDef.toString());
-     * // export const DEFAULT_TIMEOUT: number = 5000;
-     * ```
-     *
-     * @todo Move syntax to typescript package to enable language-agnostic use
-     */
-    toString() {
-        const identifier = this.identifier.typeName
-            ? `${this.identifier.name}: ${this.identifier.typeName}`
-            : this.identifier.name;
-        // @TODO move syntax to typescript package to enable language agnostic use
-        return (0, withDescription_js_1.withDescription)(`${this.noExport ? '' : 'export '}${this.identifier.entityType} ${identifier} = ${this.value};\n`, {
-            description: this.description
-        });
     }
 }
-exports.Definition = Definition;
+exports.DefinitionBase = DefinitionBase;

package/script/dsl/FileBase.d.ts

@@ -0,0 +1,42 @@
+import type { DefinitionBase } from './Definition.js';
+/**
+ * The language-neutral coordination surface shared by the engine and
+ * every `@skmtc/lang-*` package's concrete file subclass.
+ *
+ * The engine (`GenerateContext` and the cross-generator cache) only ever
+ * reads this surface — the file's `path` and its `definitions` map. It
+ * never reads a file's language-specific output state (imports,
+ * re-exports) or its rendered string, which is what keeps the engine
+ * language-blind. A language package subclasses `FileBase`, adds its own
+ * output state, and implements `toString()` to render itself.
+ *
+ * `JsonFile` extends this too — a JSON file is a `FileBase` whose
+ * `definitions` map stays empty and whose `toString()` serialises its
+ * content. (See notes/lang: "JSON is a degenerate language".)
+ *
+ * Lives in its own leaf module (only a type-only `DefinitionBase` import)
+ * so that `File` and `JsonFile` — which both `extends FileBase` — can
+ * import it without forming a value-level import cycle through `File.ts`.
+ */
+export declare abstract class FileBase {
+    /** The file path for this generated file */
+    path: string;
+    /** Map of definition names to their Definition objects */
+    definitions: Map<string, DefinitionBase>;
+    constructor({ path }: {
+        path: string;
+    });
+    /**
+     * Add a definition, deduplicating by identifier name (first write wins).
+     *
+     * Neutral: the engine's `register` calls this on the abstract base, so it
+     * works for every language's file. Per-language duplication rules (e.g.
+     * TypeScript declaration merging — a class and its `declare namespace`
+     * sharing a name) belong in the language's file subclass, which overrides
+     * this method.
+     */
+    addDefinition(definition: DefinitionBase): void;
+    /** Renders the file's complete contents. Implemented by the subclass. */
+    abstract toString(): string;
+}
+//# sourceMappingURL=FileBase.d.ts.map

package/script/dsl/FileBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileBase.d.ts","sourceRoot":"","sources":["../../src/dsl/FileBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,QAAQ;IAC5B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IAEZ,0DAA0D;IAC1D,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;gBAE5B,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE;IAKtC;;;;;;;;OAQG;IACH,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI;IAM/C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,IAAI,MAAM;CAC5B"}

package/script/dsl/FileBase.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileBase = void 0;
+/**
+ * The language-neutral coordination surface shared by the engine and
+ * every `@skmtc/lang-*` package's concrete file subclass.
+ *
+ * The engine (`GenerateContext` and the cross-generator cache) only ever
+ * reads this surface — the file's `path` and its `definitions` map. It
+ * never reads a file's language-specific output state (imports,
+ * re-exports) or its rendered string, which is what keeps the engine
+ * language-blind. A language package subclasses `FileBase`, adds its own
+ * output state, and implements `toString()` to render itself.
+ *
+ * `JsonFile` extends this too — a JSON file is a `FileBase` whose
+ * `definitions` map stays empty and whose `toString()` serialises its
+ * content. (See notes/lang: "JSON is a degenerate language".)
+ *
+ * Lives in its own leaf module (only a type-only `DefinitionBase` import)
+ * so that `File` and `JsonFile` — which both `extends FileBase` — can
+ * import it without forming a value-level import cycle through `File.ts`.
+ */
+class FileBase {
+    constructor({ path }) {
+        /** The file path for this generated file */
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Map of definition names to their Definition objects */
+        Object.defineProperty(this, "definitions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.path = path;
+        this.definitions = new Map();
+    }
+    /**
+     * Add a definition, deduplicating by identifier name (first write wins).
+     *
+     * Neutral: the engine's `register` calls this on the abstract base, so it
+     * works for every language's file. Per-language duplication rules (e.g.
+     * TypeScript declaration merging — a class and its `declare namespace`
+     * sharing a name) belong in the language's file subclass, which overrides
+     * this method.
+     */
+    addDefinition(definition) {
+        if (!this.definitions.has(definition.identifier.name)) {
+            this.definitions.set(definition.identifier.name, definition);
+        }
+    }
+}
+exports.FileBase = FileBase;

package/script/dsl/GeneratedValue.d.ts

@@ -1,4 +1,4 @@
-import type { Definition } from './Definition.js';
+import type { DefinitionBase } from './Definition.js';
 import type { Stringable } from './Stringable.js';
 import type { GeneratorKey } from './GeneratorKeys.js';
 /**
@@ -16,5 +16,5 @@ export type GeneratedValue = Stringable & {
  *
  * @template V - The generated value type extending GeneratedValue
  */
-export type GeneratedDefinition<V extends GeneratedValue> = Definition<V>;
+export type GeneratedDefinition<V extends GeneratedValue> = DefinitionBase<V>;
 //# sourceMappingURL=GeneratedValue.d.ts.map

package/script/dsl/GeneratedValue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeneratedValue.d.ts","sourceRoot":"","sources":["../../src/dsl/GeneratedValue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IACxC,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"GeneratedValue.d.ts","sourceRoot":"","sources":["../../src/dsl/GeneratedValue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IACxC,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,CAAA"}