@uniformdev/transformer 1.1.39 → 1.1.41

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command18 } from "commander";
+import { Command as Command20 } from "commander";
 
 // src/cli/commands/propagate-root-component-property.ts
 import { Command } from "commander";
@@ -1611,6 +1611,11 @@ function walkAndRegenerate(value, currentPath) {
   return value;
 }
 
+// src/core/utils.ts
+function splitList(value) {
+  return value.split(/[,;|]/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
 // src/core/services/property-propagator.service.ts
 var PropertyPropagatorService = class {
   constructor(fileSystem, componentService, compositionService, logger) {
@@ -1654,7 +1659,7 @@ var PropertyPropagatorService = class {
     this.logger.info(`Loading component: ${targetComponentType}`);
     const { component: targetComponent, filePath: targetFilePath } = await this.componentService.loadComponent(fullComponentsDir, targetComponentType, findOptions);
     this.logger.debug(`Loaded target component "${targetComponentType}" from ${targetFilePath}`);
-    const propertyNames = property.split("|").map((p) => p.trim()).filter((p) => p.length > 0);
+    const propertyNames = splitList(property);
     const resolvedParams = [];
     const resolvedNames = [];
     for (const { sourceType, sourceComponent } of sourceComponents) {
@@ -1892,7 +1897,7 @@ var PropertyPropagatorService = class {
     };
   }
   parsePipeSeparatedValues(value, strict) {
-    const entries = value.split("|").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+    const entries = splitList(value);
     const normalized = [];
     for (const entry of entries) {
       const exists = normalized.some(
@@ -3850,7 +3855,7 @@ var ComponentAdderService = class {
     return id1.toLowerCase() === id2.toLowerCase();
   }
   parseParentComponentTypes(parentComponentType) {
-    return parentComponentType.split("|").map((t) => t.trim()).filter((t) => t.length > 0);
+    return splitList(parentComponentType);
   }
   matchesAnyParentType(instanceType, parentTypes, strict) {
     return parentTypes.some((pt) => this.compareIds(instanceType, pt, strict));
@@ -4123,8 +4128,7 @@ var ComponentAdderService = class {
     }
     const newInstance = {
       type: componentTypeInPattern,
-      _pattern: pattern.componentPatternId,
-      _id: randomUUID()
+      _pattern: pattern.componentPatternId
     };
     const compositionsResult = await this.addComponentToDirectory(
       fullCompositionsDir,
@@ -4238,13 +4242,19 @@ var ComponentAdderService = class {
           continue;
         }
         const rootInstance = composition.composition;
+        const rootPath = `${rootInstance._id ?? ""}${rootInstance.type}`;
         let modified = false;
         if (this.matchesAnyParentType(rootInstance.type, parentTypes, strict)) {
           if (!rootInstance.slots) {
             rootInstance.slots = {};
           }
           const instanceCopy = JSON.parse(JSON.stringify(newInstance));
-          this.regenerateInstanceIds(instanceCopy);
+          if (instanceCopy._pattern !== void 0) {
+            const slotIndex = rootInstance.slots[slot]?.length ?? 0;
+            instanceCopy._id = computeGuidHash(`${rootPath}.${slot}[${slotIndex}]${instanceCopy.type}`);
+          } else {
+            this.regenerateInstanceIds(instanceCopy);
+          }
           this.addComponentToSlot(rootInstance.slots, slot, instanceCopy);
           modified = true;
         }
@@ -4254,7 +4264,8 @@ var ComponentAdderService = class {
             parentTypes,
             slot,
             newInstance,
-            strict
+            strict,
+            rootPath
           );
           if (nestedModified) {
             modified = true;
@@ -4285,17 +4296,24 @@ var ComponentAdderService = class {
     }
     return filesModified;
   }
-  addComponentToNestedSlots(slots, parentTypes, slot, newInstance, strict) {
+  addComponentToNestedSlots(slots, parentTypes, slot, newInstance, strict, pathPrefix) {
     let modified = false;
-    for (const slotInstances of Object.values(slots)) {
+    for (const [slotName, slotInstances] of Object.entries(slots)) {
       if (!Array.isArray(slotInstances)) continue;
-      for (const instance of slotInstances) {
+      for (let i = 0; i < slotInstances.length; i++) {
+        const instance = slotInstances[i];
+        const instancePath = `${pathPrefix}.${slotName}[${i}]${instance.type}`;
         if (this.matchesAnyParentType(instance.type, parentTypes, strict)) {
           if (!instance.slots) {
             instance.slots = {};
           }
           const instanceCopy = JSON.parse(JSON.stringify(newInstance));
-          this.regenerateInstanceIds(instanceCopy);
+          if (instanceCopy._pattern !== void 0) {
+            const slotIndex = instance.slots[slot]?.length ?? 0;
+            instanceCopy._id = computeGuidHash(`${instancePath}.${slot}[${slotIndex}]${instanceCopy.type}`);
+          } else {
+            this.regenerateInstanceIds(instanceCopy);
+          }
           this.addComponentToSlot(instance.slots, slot, instanceCopy);
           modified = true;
         }
@@ -4305,7 +4323,8 @@ var ComponentAdderService = class {
             parentTypes,
             slot,
             newInstance,
-            strict
+            strict,
+            instancePath
           );
           if (nestedModified) {
             modified = true;
@@ -4480,7 +4499,7 @@ var SlotPropagatorService = class {
     }
     this.logger.info(`Loading component: ${targetComponentType}`);
     const { component: targetComponent, filePath: targetFilePath } = await this.componentService.loadComponent(fullComponentsDir, targetComponentType, findOptions);
-    const slotNames = slot.split("|").map((s) => s.trim()).filter((s) => s.length > 0);
+    const slotNames = splitList(slot);
     const resolvedSlots = [];
     const resolvedSlotIds = [];
     for (const { sourceType, sourceComponent } of sourceComponents) {
@@ -4655,7 +4674,7 @@ var SlotPropagatorService = class {
     instance.slots[slotName].push(...components);
   }
   parsePipeSeparatedValues(value, strict) {
-    const entries = value.split("|").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+    const entries = splitList(value);
     const normalized = [];
     for (const entry of entries) {
       const exists = normalized.some(
@@ -4802,8 +4821,8 @@ function createConvertCompositionsToEntriesCommand() {
       logger
     );
     try {
-      const compositionTypes = options.compositionTypes.split("|").map((t) => t.trim()).filter((t) => t.length > 0);
-      const parsePipeSeparated = (value) => value ? [...new Set(value.split("|").map((t) => t.trim()).filter((t) => t.length > 0))] : [];
+      const compositionTypes = splitList(options.compositionTypes);
+      const parsePipeSeparated = (value) => value ? [...new Set(splitList(value))] : [];
       const componentsToReferences = parsePipeSeparated(options.componentsToReferences);
       const componentsToBlocks = parsePipeSeparated(options.componentsToBlocks);
       const slotsToReferences = parsePipeSeparated(options.slotsToReferences);
@@ -5115,7 +5134,7 @@ function createRemoveParameterCommand() {
     const fileSystem = new FileSystemService();
     const componentService = new ComponentService(fileSystem);
     const remover = new ParameterRemoverService(fileSystem, componentService, logger);
-    const rawTypes = options.componentType.split("|").map((t) => t.trim()).filter(Boolean);
+    const rawTypes = splitList(options.componentType);
     const hasWildcard = rawTypes.includes("*");
     let componentTypes;
     if (hasWildcard) {
@@ -5426,7 +5445,7 @@ function createRemoveFieldCommand() {
     const fileSystem = new FileSystemService();
     const componentService = new ComponentService(fileSystem);
     const remover = new FieldRemoverService(fileSystem, componentService, logger);
-    const rawTypes = options.componentType.split("|").map((t) => t.trim()).filter(Boolean);
+    const rawTypes = splitList(options.componentType);
     const componentTypes = rawTypes.includes("*") ? ["*"] : rawTypes;
     const aggregate = {
       compositionsModified: 0,
@@ -6353,7 +6372,7 @@ function createRemoveOrphanEntriesCommand() {
     };
     const logger = new Logger();
     logger.info(`rootContentTypes: ${options.rootContentTypes}`);
-    const rootContentTypes = options.rootContentTypes.split("|").map((t) => t.trim()).filter(Boolean);
+    const rootContentTypes = splitList(options.rootContentTypes);
     const fileSystem = new FileSystemService();
     const service = new OrphanEntryRemoverService(fileSystem, logger);
     const result = await service.remove({
@@ -6380,7 +6399,16 @@ var UnusedContentTypeRemoverService = class {
     this.logger = logger;
   }
   async remove(options) {
-    const { rootDir, contentTypesDir, entriesDir, whatIf, strict } = options;
+    const {
+      rootDir,
+      contentTypesDir,
+      entriesDir,
+      compositionsDir,
+      compositionPatternsDir,
+      componentPatternsDir,
+      whatIf,
+      strict
+    } = options;
     const contentTypesDirFull = this.fileSystem.resolvePath(rootDir, contentTypesDir);
     const entriesDirFull = this.fileSystem.resolvePath(rootDir, entriesDir);
     const ctDirExists = await this.fileSystem.fileExists(contentTypesDirFull);
@@ -6428,6 +6456,27 @@ var UnusedContentTypeRemoverService = class {
           continue;
         }
         usedTypeIds.add(entryData.entry.type);
+        const fields = entryData.entry.fields;
+        if (fields && typeof fields === "object") {
+          this.extractBlockTypesFromParameters(fields, usedTypeIds);
+        }
+      }
+    }
+    const dirsToScan = [
+      { dir: this.fileSystem.resolvePath(rootDir, compositionsDir), label: compositionsDir },
+      {
+        dir: this.fileSystem.resolvePath(rootDir, compositionPatternsDir),
+        label: compositionPatternsDir
+      },
+      {
+        dir: this.fileSystem.resolvePath(rootDir, componentPatternsDir),
+        label: componentPatternsDir
+      }
+    ];
+    for (const { dir, label } of dirsToScan) {
+      const blockTypes = await this.collectBlockTypesFromDir(dir, label);
+      for (const t of blockTypes) {
+        usedTypeIds.add(t);
       }
     }
     let removedContentTypes = 0;
@@ -6454,6 +6503,73 @@ var UnusedContentTypeRemoverService = class {
       retainedContentTypes
     };
   }
+  async collectBlockTypesFromDir(dir, label) {
+    const types = /* @__PURE__ */ new Set();
+    const dirExists = await this.fileSystem.fileExists(dir);
+    if (!dirExists) return types;
+    const files = await this.fileSystem.findFiles(dir, "**/*.{json,yaml,yml}");
+    for (const filePath of files) {
+      let data;
+      try {
+        data = await this.fileSystem.readFile(filePath);
+      } catch {
+        this.logger.warn(`Could not read ${label} file: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      this.extractBlockTypesFromFile(data, types);
+    }
+    return types;
+  }
+  extractBlockTypesFromFile(data, types) {
+    if (!data || typeof data !== "object") return;
+    const comp = data.composition;
+    if (!comp || typeof comp !== "object") return;
+    const node = comp;
+    this.extractBlockTypesFromNode(node, types);
+    const overrides = node._overrides;
+    if (overrides && typeof overrides === "object") {
+      for (const override of Object.values(overrides)) {
+        if (!override || typeof override !== "object") continue;
+        const params = override.parameters;
+        if (params && typeof params === "object") {
+          this.extractBlockTypesFromParameters(params, types);
+        }
+      }
+    }
+  }
+  extractBlockTypesFromNode(node, types) {
+    const params = node.parameters;
+    if (params && typeof params === "object") {
+      this.extractBlockTypesFromParameters(params, types);
+    }
+    const slots = node.slots;
+    if (slots && typeof slots === "object") {
+      for (const slotInstances of Object.values(slots)) {
+        if (!Array.isArray(slotInstances)) continue;
+        for (const instance of slotInstances) {
+          if (instance && typeof instance === "object") {
+            this.extractBlockTypesFromNode(instance, types);
+          }
+        }
+      }
+    }
+  }
+  extractBlockTypesFromParameters(params, types) {
+    for (const param of Object.values(params)) {
+      if (!param || typeof param !== "object") continue;
+      const p = param;
+      if (p.type === "$block" && Array.isArray(p.value)) {
+        for (const item of p.value) {
+          if (item && typeof item === "object") {
+            const blockType = item.type;
+            if (typeof blockType === "string") {
+              types.add(blockType);
+            }
+          }
+        }
+      }
+    }
+  }
   isUsed(contentTypeId, usedTypeIds, strict) {
     if (strict) {
       return usedTypeIds.has(contentTypeId);
@@ -6484,6 +6600,9 @@ function createRemoveUnusedContentTypesCommand() {
       rootDir: options.rootDir,
       contentTypesDir: options.contentTypesDir,
       entriesDir: options.entriesDir,
+      compositionsDir: options.compositionsDir,
+      compositionPatternsDir: options.compositionPatternsDir,
+      componentPatternsDir: options.componentPatternsDir,
       whatIf: options.whatIf ?? false,
       strict: options.strict ?? false
     });
@@ -6494,10 +6613,400 @@ function createRemoveUnusedContentTypesCommand() {
   return command;
 }
 
+// src/cli/commands/remove-unused-component-types.ts
+import { Command as Command18 } from "commander";
+
+// src/core/services/unused-component-type-remover.service.ts
+var UnusedComponentTypeRemoverService = class {
+  constructor(fileSystem, logger) {
+    this.fileSystem = fileSystem;
+    this.logger = logger;
+  }
+  async remove(options) {
+    const {
+      rootDir,
+      componentsDir,
+      compositionsDir,
+      compositionPatternsDir,
+      componentPatternsDir,
+      whatIf,
+      strict,
+      excludeComponentTypes = []
+    } = options;
+    const componentsDirFull = this.fileSystem.resolvePath(rootDir, componentsDir);
+    const ctDirExists = await this.fileSystem.fileExists(componentsDirFull);
+    if (!ctDirExists) {
+      this.logger.warn(`Components directory not found: ${componentsDir} \u2014 nothing to do`);
+      return { totalComponentTypes: 0, removedComponentTypes: 0, retainedComponentTypes: 0 };
+    }
+    const componentFiles = await this.fileSystem.findFiles(componentsDirFull, "*.{json,yaml,yml}");
+    if (componentFiles.length === 0) {
+      this.logger.warn("No component files found \u2014 nothing to do");
+      return { totalComponentTypes: 0, removedComponentTypes: 0, retainedComponentTypes: 0 };
+    }
+    this.logger.info(`Found ${componentFiles.length} component file(s)`);
+    const componentMap = /* @__PURE__ */ new Map();
+    for (const filePath of componentFiles) {
+      let comp;
+      try {
+        comp = await this.fileSystem.readFile(filePath);
+      } catch {
+        this.logger.warn(`Could not read component file: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      if (!comp?.id) {
+        this.logger.warn(`Component file missing id: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      componentMap.set(filePath, { filePath, id: comp.id });
+    }
+    const usedTypeIds = /* @__PURE__ */ new Set();
+    await this.collectTypesFromDirectory(
+      this.fileSystem.resolvePath(rootDir, compositionsDir),
+      usedTypeIds,
+      "compositions"
+    );
+    await this.collectTypesFromDirectory(
+      this.fileSystem.resolvePath(rootDir, compositionPatternsDir),
+      usedTypeIds,
+      "composition patterns"
+    );
+    await this.collectTypesFromDirectory(
+      this.fileSystem.resolvePath(rootDir, componentPatternsDir),
+      usedTypeIds,
+      "component patterns"
+    );
+    await this.collectAllowedComponents(componentFiles, usedTypeIds);
+    this.logger.info(`Found ${usedTypeIds.size} referenced component type(s) across all sources`);
+    let removedComponentTypes = 0;
+    let retainedComponentTypes = 0;
+    for (const { filePath, id } of componentMap.values()) {
+      const isUsed = this.isUsed(id, usedTypeIds, strict);
+      const isExcluded = excludeComponentTypes.some(
+        (ex) => strict ? ex === id : ex.toLowerCase() === id.toLowerCase()
+      );
+      if (isUsed || isExcluded) {
+        retainedComponentTypes++;
+      } else {
+        const relPath = this.fileSystem.joinPath(
+          componentsDir,
+          this.fileSystem.getBasename(filePath)
+        );
+        this.logger.action(whatIf, "DELETE", relPath);
+        if (!whatIf) {
+          this.fileSystem.deleteFile(filePath);
+        }
+        removedComponentTypes++;
+      }
+    }
+    return {
+      totalComponentTypes: componentMap.size,
+      removedComponentTypes,
+      retainedComponentTypes
+    };
+  }
+  async collectTypesFromDirectory(dirPath, usedTypeIds, label) {
+    const dirExists = await this.fileSystem.fileExists(dirPath);
+    if (!dirExists) {
+      return;
+    }
+    let files;
+    try {
+      files = await this.fileSystem.findFiles(dirPath, "**/*.{json,yaml,yml}");
+    } catch {
+      return;
+    }
+    if (files.length === 0) {
+      return;
+    }
+    this.logger.info(`Scanning ${files.length} file(s) in ${label}`);
+    for (const filePath of files) {
+      let composition;
+      try {
+        composition = await this.fileSystem.readFile(filePath);
+      } catch {
+        this.logger.warn(`Could not read file: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      if (!composition?.composition) continue;
+      this.collectTypesFromTree(composition.composition, usedTypeIds);
+    }
+  }
+  collectTypesFromTree(node, usedTypeIds) {
+    if (node.type) {
+      usedTypeIds.add(node.type);
+    }
+    if (node.slots) {
+      for (const slotInstances of Object.values(node.slots)) {
+        if (!Array.isArray(slotInstances)) continue;
+        for (const instance of slotInstances) {
+          if (instance && typeof instance === "object") {
+            this.collectTypesFromTree(
+              instance,
+              usedTypeIds
+            );
+          }
+        }
+      }
+    }
+  }
+  async collectAllowedComponents(componentFiles, usedTypeIds) {
+    for (const filePath of componentFiles) {
+      let comp;
+      try {
+        comp = await this.fileSystem.readFile(filePath);
+      } catch {
+        continue;
+      }
+      if (!comp?.slots) continue;
+      for (const slot of comp.slots) {
+        if (!slot.allowedComponents) continue;
+        for (const allowedType of slot.allowedComponents) {
+          usedTypeIds.add(allowedType);
+        }
+      }
+    }
+  }
+  isUsed(componentId, usedTypeIds, strict) {
+    if (strict) {
+      return usedTypeIds.has(componentId);
+    }
+    const lower = componentId.toLowerCase();
+    for (const used of usedTypeIds) {
+      if (used.toLowerCase() === lower) return true;
+    }
+    return false;
+  }
+};
+
+// src/cli/commands/remove-unused-component-types.ts
+function createRemoveUnusedComponentTypesCommand() {
+  const command = new Command18("remove-unused-component-types");
+  command.description(
+    "Removes component definition files that are not referenced in any composition, pattern, or allowedComponents list."
+  ).option(
+    "--excludeComponentTypes <types>",
+    'Pipe-separated list of component type IDs to keep even if unused (e.g. "Hero|Button")'
+  ).action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const options = {
+      ...globalOpts
+    };
+    const logger = new Logger();
+    logger.info(`rootDir: ${options.rootDir}`);
+    logger.info(`componentsDir: ${options.componentsDir}`);
+    logger.info(`compositionsDir: ${options.compositionsDir}`);
+    logger.info(`compositionPatternsDir: ${options.compositionPatternsDir}`);
+    logger.info(`componentPatternsDir: ${options.componentPatternsDir}`);
+    logger.info(`excludeComponentTypes: ${options.excludeComponentTypes ?? ""}`);
+    const excludeComponentTypes = options.excludeComponentTypes ? splitList(options.excludeComponentTypes) : [];
+    const fileSystem = new FileSystemService();
+    const service = new UnusedComponentTypeRemoverService(fileSystem, logger);
+    const result = await service.remove({
+      rootDir: options.rootDir,
+      componentsDir: options.componentsDir,
+      compositionsDir: options.compositionsDir,
+      compositionPatternsDir: options.compositionPatternsDir,
+      componentPatternsDir: options.componentPatternsDir,
+      whatIf: options.whatIf ?? false,
+      strict: options.strict ?? false,
+      excludeComponentTypes
+    });
+    logger.success(
+      `Removed ${result.removedComponentTypes} unused component type(s). ${result.retainedComponentTypes} component type(s) retained.`
+    );
+  });
+  return command;
+}
+
+// src/cli/commands/generate-missing-project-map-nodes.ts
+import { Command as Command19 } from "commander";
+
+// src/core/services/generate-missing-project-map-nodes.service.ts
+var GenerateMissingProjectMapNodesService = class {
+  constructor(fileSystem, logger) {
+    this.fileSystem = fileSystem;
+    this.logger = logger;
+  }
+  async generate(options) {
+    const { rootDir, projectMapNodesDir, compositionsDir, rootContentTypes, whatIf, strict } = options;
+    const nodesDirFull = this.fileSystem.resolvePath(rootDir, projectMapNodesDir);
+    const nodesDirExists = await this.fileSystem.fileExists(nodesDirFull);
+    if (!nodesDirExists) {
+      this.logger.warn(`Project map nodes directory not found: ${projectMapNodesDir} \u2014 nothing to do`);
+      return { generatedCount: 0, alreadyCoveredCount: 0 };
+    }
+    const nodeFiles = await this.fileSystem.findFiles(nodesDirFull, "**/*.{json,yaml,yml}");
+    if (nodeFiles.length === 0) {
+      this.logger.warn("No project map node files found \u2014 nothing to do");
+      return { generatedCount: 0, alreadyCoveredCount: 0 };
+    }
+    this.logger.info(`Loaded ${nodeFiles.length} project map node(s)`);
+    const allNodes = [];
+    for (const filePath of nodeFiles) {
+      let node;
+      try {
+        node = await this.fileSystem.readFile(filePath);
+      } catch {
+        this.logger.warn(`Could not read project map node file: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      if (!node?.path) {
+        this.logger.warn(`Project map node missing path field: ${filePath} \u2014 skipping`);
+        continue;
+      }
+      allNodes.push({ filePath, node });
+    }
+    const existingPaths = new Set(allNodes.map(({ node }) => node.path));
+    const compositionsDirFull = this.fileSystem.resolvePath(rootDir, compositionsDir);
+    const compositionIdToType = /* @__PURE__ */ new Map();
+    const compositionsDirExists = await this.fileSystem.fileExists(compositionsDirFull);
+    if (!compositionsDirExists) {
+      this.logger.warn(`Compositions directory not found: ${compositionsDir} \u2014 no source nodes will match`);
+    } else {
+      const compositionFiles = await this.fileSystem.findFiles(
+        compositionsDirFull,
+        "**/*.{json,yaml,yml}"
+      );
+      for (const filePath of compositionFiles) {
+        let comp;
+        try {
+          comp = await this.fileSystem.readFile(filePath);
+        } catch {
+          this.logger.warn(`Could not read composition file: ${filePath} \u2014 skipping`);
+          continue;
+        }
+        if (comp?.composition?._id && comp?.composition?.type) {
+          compositionIdToType.set(comp.composition._id, comp.composition.type);
+        }
+      }
+    }
+    const sourceNodes = allNodes.filter(({ node }) => {
+      if (!node.compositionId) return false;
+      const rootType = compositionIdToType.get(node.compositionId);
+      if (!rootType) {
+        this.logger.warn(
+          `No composition found for compositionId "${node.compositionId}" (node path: ${node.path}) \u2014 skipping`
+        );
+        return false;
+      }
+      return this.matchesContentType(rootType, rootContentTypes, strict);
+    });
+    this.logger.info(`${sourceNodes.length} node(s) match root content types`);
+    const ancestorPaths = /* @__PURE__ */ new Set();
+    for (const { node } of sourceNodes) {
+      for (const ancestor of this.computeAncestorPaths(node.path)) {
+        ancestorPaths.add(ancestor);
+      }
+    }
+    const missingPaths = [];
+    let alreadyCoveredCount = 0;
+    for (const ancestorPath of ancestorPaths) {
+      if (existingPaths.has(ancestorPath)) {
+        alreadyCoveredCount++;
+      } else {
+        missingPaths.push(ancestorPath);
+      }
+    }
+    this.logger.info(
+      `Collected ${ancestorPaths.size} unique ancestor path(s), ${alreadyCoveredCount} already covered`
+    );
+    let generatedCount = 0;
+    for (const missingPath of missingPaths) {
+      const fileName = this.pathToFileName(missingPath);
+      const nodeId = this.pathToNodeId(missingPath);
+      const destFilePath = this.fileSystem.resolvePath(nodesDirFull, fileName);
+      const relPath = this.fileSystem.joinPath(projectMapNodesDir, fileName);
+      this.logger.action(whatIf, "CREATE", `${relPath} (path: ${missingPath}, type: group)`);
+      if (!whatIf) {
+        const newNode = {
+          id: nodeId,
+          path: missingPath,
+          type: "group"
+        };
+        await this.fileSystem.writeFile(destFilePath, newNode);
+      }
+      generatedCount++;
+    }
+    return { generatedCount, alreadyCoveredCount };
+  }
+  computeAncestorPaths(nodePath) {
+    const segments = nodePath.split("/").filter((s) => s.length > 0);
+    const ancestors = [];
+    ancestors.push("/");
+    for (let i = 1; i < segments.length; i++) {
+      ancestors.push("/" + segments.slice(0, i).join("/"));
+    }
+    return ancestors;
+  }
+  pathToNodeId(nodePath) {
+    if (nodePath === "/") return "pmn-group-root";
+    const slug = nodePath.split("/").filter((s) => s.length > 0).join("-");
+    return `pmn-group-${slug}`;
+  }
+  pathToFileName(nodePath) {
+    if (nodePath === "/") return "root-node.yaml";
+    const slug = nodePath.split("/").filter((s) => s.length > 0).join("-");
+    return `${slug}-node.yaml`;
+  }
+  matchesContentType(rootType, rootContentTypes, strict) {
+    for (const ct of rootContentTypes) {
+      if (strict) {
+        if (rootType === ct) return true;
+      } else {
+        if (rootType.toLowerCase() === ct.toLowerCase()) return true;
+      }
+    }
+    return false;
+  }
+};
+
+// src/cli/commands/generate-missing-project-map-nodes.ts
+function createGenerateMissingProjectMapNodesCommand() {
+  const command = new Command19("generate-missing-project-map-nodes");
+  command.description(
+    "Creates group project map nodes for ancestor path segments that are missing from the project map. Only paths reachable from compositions whose root type matches --rootContentTypes are considered."
+  ).option(
+    "--rootContentTypes <types>",
+    'Pipe-separated list of root component types identifying the leaf-page compositions whose ancestor paths should be filled in (e.g. "BlogPost|NewsArticle")'
+  ).hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    const requiredOptions = [{ name: "rootContentTypes", flag: "--rootContentTypes" }];
+    const missing = requiredOptions.filter((opt) => !opts[opt.name]).map((opt) => opt.flag);
+    if (missing.length > 0) {
+      console.error(`error: missing required options: ${missing.join(", ")}`);
+      process.exit(1);
+    }
+  }).action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const options = {
+      ...globalOpts,
+      rootContentTypes: opts.rootContentTypes
+    };
+    const logger = new Logger();
+    logger.info(`rootContentTypes: ${options.rootContentTypes}`);
+    const rootContentTypes = splitList(options.rootContentTypes);
+    const fileSystem = new FileSystemService();
+    const service = new GenerateMissingProjectMapNodesService(fileSystem, logger);
+    const result = await service.generate({
+      rootDir: options.rootDir,
+      projectMapNodesDir: options.projectMapNodesDir,
+      compositionsDir: options.compositionsDir,
+      rootContentTypes,
+      whatIf: options.whatIf ?? false,
+      strict: options.strict ?? false
+    });
+    logger.success(
+      `Created ${result.generatedCount} missing project map node(s). ${result.alreadyCoveredCount} ancestor path(s) already existed.`
+    );
+  });
+  return command;
+}
+
 // package.json
 var package_default = {
   name: "@uniformdev/transformer",
-  version: "1.1.39",
+  version: "1.1.41",
   description: "CLI tool for transforming Uniform.dev serialization files offline",
   type: "module",
   bin: {
@@ -6566,7 +7075,7 @@ var package_default = {
 };
 
 // src/cli/index.ts
-var program = new Command18();
+var program = new Command20();
 var appVersion = package_default.version;
 console.error(`uniform-transform v${appVersion}`);
 program.name("uniform-transform").description("CLI tool for transforming Uniform.dev serialization files offline").version(appVersion);
@@ -6579,6 +7088,9 @@ program.requiredOption("--rootDir <path>", "Path to the serialization project ro
   "Project map definitions directory name",
   "projectMapDefinition"
 ).option("--projectMapNodesDir <dir>", "Project map nodes directory name", "projectMapNode").option("--quirksDir <dir>", "Quirks directory name", "quirk");
+program.hook("preAction", (_thisCommand, actionCommand) => {
+  console.error(`[INFO] ${actionCommand.name()} args: ${JSON.stringify(actionCommand.optsWithGlobals())}`);
+});
 program.addCommand(createPropagateRootComponentPropertyCommand());
 program.addCommand(createFindCompositionPatternCandidatesCommand());
 program.addCommand(createUnpackSerializationCommand());
@@ -6596,5 +7108,7 @@ program.addCommand(createAddContentTypeFieldCommand());
 program.addCommand(createFlattenBlockFieldCommand());
 program.addCommand(createRemoveOrphanEntriesCommand());
 program.addCommand(createRemoveUnusedContentTypesCommand());
+program.addCommand(createRemoveUnusedComponentTypesCommand());
+program.addCommand(createGenerateMissingProjectMapNodesCommand());
 program.parse();
 //# sourceMappingURL=index.js.map