@postxl/generator 1.4.1 → 1.5.0

package/dist/generator-manager.class.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeneratorManager = void 0;
 const utils_1 = require("@postxl/utils");
 const branded_types_1 = require("./helpers/branded.types");
+const generator_context_1 = require("./generator.context");
 /**
  * The GeneratorManager coordinates the generation process across multiple Generators.
  *
@@ -144,6 +145,10 @@ class GeneratorManager {
                 // Not all generators extend the context and hence do not need to return it.
                 // Therefore, if the generator does not return the context, we use the original context.
                 context = (await generator.register(context)) ?? context;
+                // Register phases typically rebuild `context.models` as a fresh Map with
+                // extended per-model contexts. Re-sync `targetModels` so it points at
+                // the same (or narrowed) extended entries rather than a stale reference.
+                context = (0, generator_context_1.syncTargetModels)(context);
             }
             catch (error) {
                 throw new Error(`Generator ${(0, utils_1.yellow)(generator.id)} failed during register phase: ${error instanceof Error ? error.message : String(error)}`, { cause: error });

package/dist/generator.context.d.ts

@@ -22,6 +22,18 @@ export type Context = {
      * Each generator can extend these contexts with its own content.
      */
     models: Map<Schema.ModelName, ModelContext>;
+    /**
+     * Subset of `models` that per-model generation should target. Same reference as
+     * `models` by default; only the `-m <names...>` CLI flag narrows it to a smaller
+     * set. Generators that iterate models to write one file per model should read
+     * `targetModels`; generators that iterate to contribute to an aggregate file,
+     * or that do cross-model lookups via `.get(name)`, should stay on `models`.
+     *
+     * The narrowing is sourced from `options.targetModelNames` and re-synced by
+     * the `GeneratorManager` after every register phase, so it survives generators
+     * that rebuild the `models` map.
+     */
+    targetModels: Map<Schema.ModelName, ModelContext>;
     /**
      * Contains the context for each schema enum.
      * Each generator can extend these contexts with its own content.
@@ -144,12 +156,21 @@ export type GeneratorOptions = {
      * Default: undefined (no filtering)
      */
     filePattern?: string;
+    /**
+     * Optional set of model names to narrow generation to. When set, per-model
+     * generators iterate only these models (via `context.targetModels`) and the
+     * VFS safety-net drops any per-model writes for models outside this set.
+     *
+     * Default: undefined (all models).
+     */
+    targetModelNames?: ReadonlySet<Schema.ModelName>;
 };
 export type ExtendContext<Context, ContextExtension> = Context & ContextExtension;
 export type ExtendModelContext<Context, ModelContextExtension> = Context extends {
     models: Map<infer K, infer V>;
-} ? Omit<Context, 'models'> & {
+} ? Omit<Context, 'models' | 'targetModels'> & {
     models: Map<K, V & ModelContextExtension>;
+    targetModels: Map<K, V & ModelContextExtension>;
 } : never;
 export type ExtendEnumContext<Context, EnumContextExtension> = Context extends {
     enums: Map<infer K, infer V>;
@@ -165,6 +186,13 @@ export type InferEnumContext<Context> = Context extends {
     enums: Map<any, infer V>;
 } ? V : never;
 export declare function prepareBaseContext(schema: Schema.ProjectSchema, opts?: Partial<GeneratorOptions>): Context;
+/**
+ * Given a fresh `models` Map and the requested narrowing on
+ * `ctx.options.targetModelNames` (if any), produce a `targetModels` Map that
+ * matches. Called by the GeneratorManager after every register phase to keep
+ * `targetModels` pointing at the latest extended contexts.
+ */
+export declare function syncTargetModels<C extends Context>(ctx: C): C;
 /**
  * Helper function for tests to create a mock schema.
  */

package/dist/generator.context.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareBaseContext = prepareBaseContext;
+exports.syncTargetModels = syncTargetModels;
 exports.mockSchema = mockSchema;
 exports.mockSchemaWithDefaultModels = mockSchemaWithDefaultModels;
 exports.getBaseModelContext = getBaseModelContext;
@@ -56,14 +57,61 @@ function prepareBaseContext(schema, opts = defaultGeneratorOptions) {
     for (const enumSchema of schema.enums.values()) {
         enums.set(enumSchema.name, getBaseEnumContext(enumSchema));
     }
+    const targetModelNames = effectiveTargetModelNames(options.targetModelNames, models);
+    const targetModels = targetModelNames ? filterModelMapByNames(models, targetModelNames) : models;
+    const vfsOptions = {};
+    if (options.filePattern) {
+        vfsOptions.filePattern = options.filePattern;
+    }
+    if (targetModelNames) {
+        vfsOptions.targetModelNames = targetModelNames;
+        vfsOptions.allModelNames = new Set(models.keys());
+    }
     return {
         schema: schema,
-        vfs: new vfs_class_1.VirtualFileSystem(options.filePattern ? { filePattern: options.filePattern } : undefined),
+        vfs: new vfs_class_1.VirtualFileSystem(Object.keys(vfsOptions).length > 0 ? vfsOptions : undefined),
         models,
+        targetModels,
         enums,
         options,
     };
 }
+/**
+ * Given a fresh `models` Map and the requested narrowing on
+ * `ctx.options.targetModelNames` (if any), produce a `targetModels` Map that
+ * matches. Called by the GeneratorManager after every register phase to keep
+ * `targetModels` pointing at the latest extended contexts.
+ */
+function syncTargetModels(ctx) {
+    const targetModelNames = effectiveTargetModelNames(ctx.options?.targetModelNames, ctx.models);
+    if (!targetModelNames) {
+        return ctx.targetModels === ctx.models ? ctx : { ...ctx, targetModels: ctx.models };
+    }
+    return { ...ctx, targetModels: filterModelMapByNames(ctx.models, targetModelNames) };
+}
+/**
+ * Returns the requested narrowing if it actually narrows the given `models`
+ * map; returns `undefined` when no narrowing was requested or the requested set
+ * already covers every current model (no real narrowing).
+ */
+function effectiveTargetModelNames(requested, models) {
+    if (!requested) {
+        return undefined;
+    }
+    if (requested.size === models.size && [...requested].every((n) => models.has(n))) {
+        return undefined;
+    }
+    return requested;
+}
+function filterModelMapByNames(models, names) {
+    const out = new Map();
+    for (const [name, model] of models) {
+        if (names.has(name)) {
+            out.set(name, model);
+        }
+    }
+    return out;
+}
 /**
  * Helper function for tests to create a mock schema.
  */

package/dist/utils/classify-path.d.ts

@@ -0,0 +1,26 @@
+export type PathClassification = {
+    kind: 'per-model';
+    model: string;
+} | {
+    kind: 'aggregate-or-unknown';
+};
+/**
+ * Classifies a VFS path as "per-model" (a file that belongs to exactly one
+ * model from `allModelNames`) or "aggregate-or-unknown" (everything else).
+ *
+ * Algorithm:
+ *  1. Take the basename, strip every extension segment.
+ *  2. Split the remaining stem on `.`, `-`, `_`, and camelCase boundaries.
+ *  3. For each token, case-insensitive match against `allModelNames`.
+ *  4. Exactly one distinct model matched → `per-model`.
+ *  5. Zero or multiple distinct matches → `aggregate-or-unknown`.
+ *
+ * The conservative multi-match treatment means cross-model files like
+ * `post-country-link.ts` keep falling through as "aggregate-or-unknown" — the
+ * safety-net in the VFS will then keep the file, which is the correct default.
+ *
+ * Used by the VFS safety-net: when a `targetModelNames` filter is active, the
+ * VFS drops writes classified as `per-model` for models not in the target set.
+ * Aggregate-or-unknown writes always pass through.
+ */
+export declare function classifyPath(path: string, allModelNames: ReadonlySet<string>): PathClassification;

package/dist/utils/classify-path.js

@@ -0,0 +1,103 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyPath = classifyPath;
+const Path = __importStar(require("./path"));
+/**
+ * Classifies a VFS path as "per-model" (a file that belongs to exactly one
+ * model from `allModelNames`) or "aggregate-or-unknown" (everything else).
+ *
+ * Algorithm:
+ *  1. Take the basename, strip every extension segment.
+ *  2. Split the remaining stem on `.`, `-`, `_`, and camelCase boundaries.
+ *  3. For each token, case-insensitive match against `allModelNames`.
+ *  4. Exactly one distinct model matched → `per-model`.
+ *  5. Zero or multiple distinct matches → `aggregate-or-unknown`.
+ *
+ * The conservative multi-match treatment means cross-model files like
+ * `post-country-link.ts` keep falling through as "aggregate-or-unknown" — the
+ * safety-net in the VFS will then keep the file, which is the correct default.
+ *
+ * Used by the VFS safety-net: when a `targetModelNames` filter is active, the
+ * VFS drops writes classified as `per-model` for models not in the target set.
+ * Aggregate-or-unknown writes always pass through.
+ */
+function classifyPath(path, allModelNames) {
+    if (allModelNames.size === 0) {
+        return { kind: 'aggregate-or-unknown' };
+    }
+    const basename = Path.fileName(Path.normalize(path));
+    const dotIdx = basename.indexOf('.');
+    const stem = dotIdx === -1 ? basename : basename.slice(0, dotIdx);
+    if (stem.length === 0) {
+        return { kind: 'aggregate-or-unknown' };
+    }
+    const tokens = tokenize(stem);
+    if (tokens.length === 0) {
+        return { kind: 'aggregate-or-unknown' };
+    }
+    const lowerModelByName = new Map();
+    for (const name of allModelNames) {
+        lowerModelByName.set(name.toLowerCase(), name);
+    }
+    const matched = new Set();
+    for (const token of tokens) {
+        const hit = lowerModelByName.get(token.toLowerCase());
+        if (hit) {
+            matched.add(hit);
+        }
+    }
+    if (matched.size === 1) {
+        return { kind: 'per-model', model: matched.values().next().value };
+    }
+    return { kind: 'aggregate-or-unknown' };
+}
+function tokenize(stem) {
+    const out = [];
+    // Split on `.`, `-`, `_` first.
+    for (const chunk of stem.split(/[.\-_]+/)) {
+        if (chunk.length === 0) {
+            continue;
+        }
+        // Split remaining chunk on camelCase boundaries (lower→upper, and
+        // consecutive-uppercase→upper+lower transitions for acronym-capable names).
+        for (const part of chunk.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/)) {
+            if (part.length > 0) {
+                out.push(part);
+            }
+        }
+    }
+    return out;
+}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
+export * from './classify-path';
 export * from './custom-blocks';
 export * from './jsdoc';
 export * from './lint';

package/dist/utils/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./classify-path"), exports);
 __exportStar(require("./custom-blocks"), exports);
 __exportStar(require("./jsdoc"), exports);
 __exportStar(require("./lint"), exports);

package/dist/utils/lockfile.d.ts

@@ -27,6 +27,8 @@ export type LockEntry = Checksum | EjectedSentinel;
 declare const zLockFile: z.ZodPipe<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PXL.PosixPath", "out">, z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PXL.Checksum", "out">, z.ZodLiteral<"ejected">]>>, z.ZodTransform<Map<string & z.core.$brand<"PXL.PosixPath">, LockEntry>, Record<string & z.core.$brand<"PXL.PosixPath">, (string & z.core.$brand<"PXL.Checksum">) | "ejected">>>;
 type LockFile = z.infer<typeof zLockFile>;
 export declare function isEjected(entry: LockEntry | undefined): entry is EjectedSentinel;
-export declare function writeLockFile(lockFilePath: string, vfs: VirtualFileSystem): Promise<void>;
+export declare function writeLockFile(lockFilePath: string, vfs: VirtualFileSystem, opts?: {
+    selectiveGeneration?: boolean;
+}): Promise<void>;
 export declare function readLockFile(lockFilePath: string): Promise<LockFile | undefined>;
 export {};

package/dist/utils/lockfile.js

@@ -65,7 +65,7 @@ const zLockFile = zod_1.z
 function isEjected(entry) {
     return entry === exports.EJECTED_SENTINEL;
 }
-async function writeLockFile(lockFilePath, vfs) {
+async function writeLockFile(lockFilePath, vfs, opts = {}) {
     const newLockFileMap = await vfsToLockFile(vfs);
     const existingLockFile = await readLockFile(lockFilePath);
     if (existingLockFile) {
@@ -80,6 +80,13 @@ async function writeLockFile(lockFilePath, vfs) {
             // that don't match the current filter (they were out of scope for this run).
             if (vfs.filePattern && !vfs.matchesPattern(filePath) && !newLockFileMap.has(filePath)) {
                 newLockFileMap.set(filePath, entry);
+                continue;
+            }
+            // Selective generation (`-m`): any lock entry not produced by this run is
+            // deliberately out of scope — preserve it as-is. Sync skips matching entries
+            // so nothing on disk is deleted. A subsequent full regeneration rewrites the lock cleanly.
+            if (opts.selectiveGeneration && !newLockFileMap.has(filePath)) {
+                newLockFileMap.set(filePath, entry);
             }
         }
     }

package/dist/utils/sync.d.ts

@@ -67,6 +67,14 @@ type SyncParams = {
     lockFilePath: string;
     diskFilePath: string;
     force: boolean;
+    /**
+     * When true, any lock-file entry that is not in the current VFS is considered
+     * out of scope for this run: sync does not touch it (no delete, no force
+     * overwrite) and the lock file preserves the entry as-is. A subsequent full
+     * regeneration reconciles the lock cleanly. Set this when the CLI narrows
+     * generation via `-m <names...>`.
+     */
+    selectiveGeneration?: boolean;
 };
 /**
  * Error returned when files with unresolved merge conflicts are detected
@@ -109,7 +117,7 @@ export type SyncResults = {
  * merge conflict markers. If found, the sync will abort immediately and return an error with the
  * list of files that need to be resolved before generation can continue.
  */
-export declare function sync({ vfs, lockFilePath, diskFilePath, force }: SyncParams): Promise<SyncResults>;
+export declare function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, }: SyncParams): Promise<SyncResults>;
 type FileState = {
     state: 'empty';
 } | {

package/dist/utils/sync.js

@@ -121,9 +121,9 @@ const Path = __importStar(require("./path"));
  * merge conflict markers. If found, the sync will abort immediately and return an error with the
  * list of files that need to be resolved before generation can continue.
  */
-async function sync({ vfs, lockFilePath, diskFilePath, force }) {
+async function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, }) {
     const diskPathNormalized = Path.normalize(diskFilePath);
-    const files = await getFilesStates({ vfs, lockFilePath, diskFilePath });
+    const files = await getFilesStates({ vfs, lockFilePath, diskFilePath, selectiveGeneration: !!selectiveGeneration });
     // Check for unresolved merge conflicts before writing any files
     const filesWithConflicts = findFilesWithMergeConflicts(files);
     if (filesWithConflicts.length > 0 && !force) {
@@ -165,7 +165,7 @@ async function sync({ vfs, lockFilePath, diskFilePath, force }) {
         });
         tasks.push(task);
     }
-    tasks.push(limit(() => (0, lockfile_1.writeLockFile)(lockFilePath, vfs)));
+    tasks.push(limit(() => (0, lockfile_1.writeLockFile)(lockFilePath, vfs, selectiveGeneration ? { selectiveGeneration: true } : {})));
     await Promise.all(tasks);
     return { success: true, ...result };
 }
@@ -262,7 +262,7 @@ function lockEntryToFileState(entry) {
     }
     return { state: 'hash', hash: entry };
 }
-async function getFilesStates({ vfs, lockFilePath, diskFilePath, }) {
+async function getFilesStates({ vfs, lockFilePath, diskFilePath, selectiveGeneration, }) {
     const lockFile = await (0, lockfile_1.readLockFile)(lockFilePath);
     const files = new Map();
     const diskPathNormalized = Path.normalize(diskFilePath);
@@ -286,6 +286,11 @@ async function getFilesStates({ vfs, lockFilePath, diskFilePath, }) {
             if (!vfs.matchesPattern(filePath)) {
                 continue;
             }
+            // Selective generation: any lock entry not in the VFS is out of scope for
+            // this run. Sync must not touch it (no delete, no force overwrite).
+            if (selectiveGeneration) {
+                continue;
+            }
             const lock = lockEntryToFileState(entry);
             const disk = await getDiskFileState(Path.join(diskPathNormalized, filePath));
             files.set(filePath, { virtual, lock, disk });

package/dist/utils/vfs.class.d.ts

@@ -10,6 +10,17 @@ export type VFSOptions = {
      * When specified, only files matching this pattern will be stored in the VFS.
      */
     filePattern?: string;
+    /**
+     * Optional target model names for the selective-generation safety net.
+     * When set, writes classified as "per-model X" for X not in this set are dropped.
+     * Requires `allModelNames` to be set.
+     */
+    targetModelNames?: ReadonlySet<string>;
+    /**
+     * Full set of model names in the project. Required whenever `targetModelNames`
+     * is set; used by the path classifier to decide whether a write is per-model.
+     */
+    allModelNames?: ReadonlySet<string>;
 };
 /**
  * The virtual file system (VFS) represents a file system that can be manipulated in memory.

package/dist/utils/vfs.class.js

@@ -37,6 +37,7 @@ exports.VirtualFileSystem = void 0;
 const minimatch_1 = require("minimatch");
 const fs = __importStar(require("node:fs/promises"));
 const utils_1 = require("@postxl/utils");
+const classify_path_1 = require("./classify-path");
 const fs_utils_1 = require("./fs-utils");
 const Path = __importStar(require("./path"));
 /**
@@ -67,6 +68,8 @@ const Path = __importStar(require("./path"));
 class VirtualFileSystem {
     #files = new Map();
     #filePattern;
+    #targetModelNames;
+    #allModelNames;
     /**
      * Constructs a new VirtualFileSystem.
      *
@@ -74,6 +77,16 @@ class VirtualFileSystem {
      */
     constructor(options) {
         this.#filePattern = options?.filePattern;
+        // Only activate the classifier when narrowing is actually in effect —
+        // absent targetModelNames, or a target set that already covers every model,
+        // means "keep everything" and the classifier can be skipped entirely.
+        if (options?.targetModelNames &&
+            options.allModelNames &&
+            options.targetModelNames.size > 0 &&
+            options.targetModelNames.size < options.allModelNames.size) {
+            this.#targetModelNames = options.targetModelNames;
+            this.#allModelNames = options.allModelNames;
+        }
     }
     /**
      * Returns all file names in the VFS.
@@ -108,16 +121,33 @@ class VirtualFileSystem {
         const normalizedPattern = this.#filePattern.startsWith('/') ? this.#filePattern.slice(1) : this.#filePattern;
         return (0, minimatch_1.minimatch)(normalizedPath, normalizedPattern, { dot: true, matchBase: false });
     }
+    /**
+     * Safety net for `-m` selective generation: if the write is classified as
+     * per-model for a model outside the target set, drop it. Returns true when
+     * the write should proceed, false when it should be skipped.
+     */
+    #matchesTargetModels(filePath) {
+        if (!this.#targetModelNames || !this.#allModelNames) {
+            return true;
+        }
+        const classification = (0, classify_path_1.classifyPath)(filePath, this.#allModelNames);
+        if (classification.kind === 'aggregate-or-unknown') {
+            return true;
+        }
+        return this.#targetModelNames.has(classification.model);
+    }
     /**
      * Writes the given content to the specified path.
      * If a file pattern is set, only files matching the pattern will be stored.
      */
     write(path, content) {
         const posixPath = Path.normalize(path);
-        // Skip files that don't match the pattern
         if (!this.matchesPattern(posixPath)) {
             return;
         }
+        if (!this.#matchesTargetModels(posixPath)) {
+            return;
+        }
         this.#files.set(posixPath, content);
     }
     /**
@@ -150,10 +180,12 @@ class VirtualFileSystem {
         const basePath = Path.normalize(targetPath);
         for (const [filePath, content] of vfs.files) {
             const combinedPath = Path.join(basePath, filePath);
-            // Skip files that don't match the pattern
             if (!this.matchesPattern(combinedPath)) {
                 continue;
             }
+            if (!this.#matchesTargetModels(combinedPath)) {
+                continue;
+            }
             this.#files.set(combinedPath, content);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postxl/generator",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Core package that orchestrates the code generation of a PXL project",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -46,7 +46,7 @@
     "jszip": "3.10.1",
     "minimatch": "^10.2.2",
     "p-limit": "3.1.0",
-    "@postxl/schema": "^1.10.1",
+    "@postxl/schema": "^1.11.0",
     "@postxl/utils": "^1.4.0"
   },
   "devDependencies": {