@team-codeme/crud-forge 0.0.0-stage → 1.0.0

package/src/templates/fuse-packs/access-control-tools/access-control-sync.js

@@ -0,0 +1,819 @@
+'use strict';
+
+/**
+ * Unified access-control + QA id sync.
+ *
+ * Usage:
+ *   node access-control-sync.js --dry-run
+ *   node access-control-sync.js --write
+ *   node access-control-sync.js --dry-run --qa-only
+ *   node access-control-sync.js --dry-run --access-only
+ *   node access-control-sync.js --write --rewrite-ids   # normalize legacy noisy ids (destructive)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  formatScreenNameFromPath,
+  extractScreenContent,
+  isExcludedFromContentIds,
+  deriveScreenId,
+  disambiguateDuplicateScreenIds,
+  generateScreenDescription,
+  generateComponentDescription,
+} = require('./lib/id-rules');
+const { parseHtmlAndInject } = require('./lib/html-scanner');
+const { buildScreenNavigationHierarchy } = require('./lib/hierarchy-scanner');
+
+const TOOLS_DIR = __dirname;
+const APPS_DIR = path.join(TOOLS_DIR, '../..');
+const MICRO_FUNCTIONS_DIR = path.join(APPS_DIR, 'micro-functions');
+const MICROSERVICE_DIR = path.join(APPS_DIR, 'microservice');
+const PAGES_DIR = path.join(APPS_DIR, 'pages');
+const OUTPUT_DIR = path.join(TOOLS_DIR, 'output');
+const OUTPUT_CSV_PATH = path.join(OUTPUT_DIR, 'screen-components.csv');
+const OUTPUT_HIERARCHY_PATH = path.join(OUTPUT_DIR, 'screen-navigation-map.json');
+const REPORT_PATH = path.join(OUTPUT_DIR, 'sync-report.json');
+// CRUDForge Fuse serves static assets from public/ (also mirrored under shared for tooling).
+const ASSETS_CSV_PATH = path.join(TOOLS_DIR, '../../../../../../../public/assets/screen-components.csv');
+const ASSETS_HIERARCHY_PATH = path.join(
+  TOOLS_DIR,
+  '../../../../../../../public/assets/screen-navigation-map.json'
+);
+const SHARED_CSV_PATH = path.join(TOOLS_DIR, '../screen-components.csv');
+const ADMIN_ROUTES_FILE = path.join(TOOLS_DIR, '../../../../routes.ts');
+
+const ACCESS_CTRL_IMPORT = "import { AccessCtrlPipe } from '@/app/core/auth';\n";
+const ACCESS_CTRL_PIPE = 'AccessCtrlPipe';
+
+function parseArgs(argv) {
+  const args = {
+    dryRun: true,
+    write: false,
+    qaOnly: false,
+    accessOnly: false,
+    rewriteIds: false,
+    pruneCsv: false,
+    // Default false for CRUDForge: keep nav-aligned {folder}/{entity} SCREEN values.
+    forceContentIds: false,
+    preferExistingScreen: true,
+  };
+
+  for (const arg of argv.slice(2)) {
+    if (arg === '--write') {
+      args.write = true;
+      args.dryRun = false;
+    } else if (arg === '--dry-run') {
+      args.dryRun = true;
+      args.write = false;
+    } else if (arg === '--qa-only') {
+      args.qaOnly = true;
+    } else if (arg === '--access-only') {
+      args.accessOnly = true;
+    } else if (arg === '--rewrite-ids') {
+      args.rewriteIds = true;
+    } else if (arg === '--prune-csv') {
+      args.pruneCsv = true;
+    } else if (arg === '--force-content-ids') {
+      args.forceContentIds = true;
+      args.preferExistingScreen = false;
+    } else if (arg === '--keep-existing-screen') {
+      args.forceContentIds = false;
+      args.preferExistingScreen = true;
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    }
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+Access Control & QA ID Sync
+
+  --dry-run               Report only (default). Writes output/sync-report.json
+  --write                 Apply HTML/TS/CSV changes
+  --qa-only               Only inject QA attributes (no accessCtrl / SCREEN)
+  --access-only           Only inject accessCtrl / SCREEN / CSV
+  --rewrite-ids           Normalize legacy noisy component ids (use with care)
+  --prune-csv             Drop CSV rows not rediscovered in this scan (write mode)
+  --force-content-ids     Rebuild SCREEN from heading + view (default on)
+  --keep-existing-screen  Do not rewrite existing SCREEN values
+
+Excluded from content rewrite (path/filename ids kept):
+  dad-mock-module, accessControlModule, notificationModule
+
+CRUDForge Fuse notes:
+  • Entity SCREEN ids stay {micro-functions|microservice}/{entity} (nav-aligned)
+  • Prefer --keep-existing-screen for generated entities; use content ids on custom pages
+  • Pipe import is AccessCtrlPipe from @/app/core/auth (template: accessCtrl)
+`);
+}
+
+function walkDir(dir, callback) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+  for (const file of fs.readdirSync(dir)) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkDir(fullPath, callback);
+    } else {
+      callback(fullPath);
+    }
+  }
+}
+
+function isAngularComponentSource(filePath, fileContent) {
+  if (!filePath.endsWith('.ts')) {
+    return false;
+  }
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  if (
+    normalizedPath.endsWith('.spec.ts') ||
+    normalizedPath.endsWith('.route.ts') ||
+    normalizedPath.endsWith('.routes.ts') ||
+    normalizedPath.includes('/services/') ||
+    normalizedPath.includes('/service/')
+  ) {
+    return false;
+  }
+  return fileContent.includes('@Component');
+}
+
+/**
+ * Unified page + micro-function include rules.
+ * Skips pure dialogs/confirmations; includes actions/filter/list/form/cards under pages.
+ */
+function shouldScanComponent(filePath, sourceType) {
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const fileName = path.basename(normalizedPath);
+
+  if (sourceType === 'micro-functions') {
+    return fileName.endsWith('.component.ts');
+  }
+
+  // pages: any component ts, excluding shared confirm dialogs only
+  if (normalizedPath.includes('/shared/confirmation')) {
+    return false;
+  }
+  return (
+    fileName.endsWith('.component.ts') ||
+    fileName === 'national.ts' ||
+    fileName === 'regional.ts' ||
+    fileName === 'warehouse.ts' ||
+    fileName === 'warehouse-building-details.ts' ||
+    fileName === 'stock-transfer-approval.ts' ||
+    fileName === 'new-warehouse-approval.ts' ||
+    fileName === 'damage-loss-approval.ts'
+  );
+}
+
+function resolveScanRoots() {
+  const roots = [];
+  if (fs.existsSync(APPS_DIR)) {
+    for (const entry of fs.readdirSync(APPS_DIR)) {
+      if (entry === 'shared' || entry === 'enums') continue;
+      const full = path.join(APPS_DIR, entry);
+      if (!fs.statSync(full).isDirectory()) continue;
+      roots.push({
+        name: entry,
+        dir: full,
+        sourceType: entry === 'pages' ? 'pages' : 'micro-functions',
+      });
+    }
+  }
+  // Ensure known roots even if empty (stable logging).
+  for (const known of [
+    { name: 'micro-functions', dir: MICRO_FUNCTIONS_DIR, sourceType: 'micro-functions' },
+    { name: 'microservice', dir: MICROSERVICE_DIR, sourceType: 'micro-functions' },
+    { name: 'pages', dir: PAGES_DIR, sourceType: 'pages' },
+  ]) {
+    if (!roots.some((r) => r.dir === known.dir) && fs.existsSync(known.dir)) {
+      roots.push(known);
+    }
+  }
+  return roots;
+}
+
+function collectComponentFiles() {
+  const componentFiles = [];
+  const seen = new Set();
+
+  for (const root of resolveScanRoots()) {
+    walkDir(root.dir, (filePath) => {
+      if (seen.has(filePath)) return;
+      seen.add(filePath);
+      const fileContent = fs.readFileSync(filePath, 'utf8');
+      if (
+        isAngularComponentSource(filePath, fileContent) &&
+        shouldScanComponent(filePath, root.sourceType)
+      ) {
+        componentFiles.push({ filePath, sourceType: root.sourceType, rootDir: root.dir, fileContent });
+      }
+    });
+  }
+
+  return componentFiles;
+}
+
+function findComponentClassHeader(tsContent) {
+  // Prefer the class that follows @Component(...) so we never inject into @Pipe classes
+  const componentClassMatch = tsContent.match(
+    /@Component\s*\([\s\S]*?\)\s*export\s+class\s+(\w+)[^{]*?\{/
+  );
+  if (componentClassMatch) {
+    return componentClassMatch[0].match(/export\s+class\s+\w+[^{]*?\{/)?.[0] || null;
+  }
+  return null;
+}
+
+function processComponentTs(tsFilePath, tsContent, screenId, write, options = {}) {
+  const { screenOnly = false } = options;
+  let content = tsContent;
+  let modified = false;
+  const changes = [];
+
+  const componentClassHeader = findComponentClassHeader(content);
+
+  // Detect SCREEN only inside the @Component class body when possible
+  let existingScreenInComponent = null;
+  let hasScreenGetter = false;
+  if (componentClassHeader) {
+    const afterHeaderIdx = content.indexOf(componentClassHeader) + componentClassHeader.length;
+    // Scan until next top-level export or end — simple window of 8k chars is enough for class fields
+    const classWindow = content.slice(afterHeaderIdx, afterHeaderIdx + 8000);
+    const screenInClass = classWindow.match(/^\s*(?:readonly\s+)?SCREEN\s*=\s*['"]([^'"]+)['"]/m);
+    if (screenInClass) {
+      existingScreenInComponent = screenInClass[1];
+    }
+    // Some filters expose SCREEN via getter + @Input() screenId — never inject a field there.
+    hasScreenGetter = /^\s*get\s+SCREEN\s*\(/m.test(classWindow);
+  }
+
+  if (hasScreenGetter) {
+    // Keep getter; align common @Input() screenId default when present.
+    const afterHeaderIdx = content.indexOf(componentClassHeader) + componentClassHeader.length;
+    const before = content.slice(0, afterHeaderIdx);
+    let after = content.slice(afterHeaderIdx);
+    const inputRe =
+      /(@Input\(\)\s+screenId\s*=\s*)['"][^'"]+['"]/;
+    if (inputRe.test(after)) {
+      const prev = (after.match(inputRe) || [])[0];
+      after = after.replace(inputRe, `$1'${screenId}'`);
+      if (prev && !prev.includes(`'${screenId}'`) && !prev.includes(`"${screenId}"`)) {
+        modified = true;
+        changes.push(`@Input() screenId → '${screenId}'`);
+      }
+    }
+    content = before + after;
+  } else if (!existingScreenInComponent) {
+    if (componentClassHeader) {
+      content = content.replace(
+        componentClassHeader,
+        `${componentClassHeader}\n    readonly SCREEN = '${screenId}';`
+      );
+      modified = true;
+      changes.push(`SCREEN='${screenId}'`);
+    }
+  } else if (existingScreenInComponent !== screenId && componentClassHeader) {
+    const afterHeaderIdx = content.indexOf(componentClassHeader) + componentClassHeader.length;
+    const before = content.slice(0, afterHeaderIdx);
+    let after = content.slice(afterHeaderIdx);
+    after = after.replace(
+      /((?:readonly\s+)?)SCREEN\s*=\s*['"][^'"]+['"]/,
+      `$1SCREEN = '${screenId}'`
+    );
+    content = before + after;
+    modified = true;
+    changes.push(`SCREEN '${existingScreenInComponent}' → '${screenId}'`);
+  }
+
+  if (!screenOnly) {
+    const hasAccessCtrlImport =
+      content.includes(`import { ${ACCESS_CTRL_PIPE}`) ||
+      content.includes(`${ACCESS_CTRL_PIPE} }`) ||
+      /import\s*\{[^}]*AccessCtrlPipe[^}]*\}\s*from\s*['"]@\/app\/core\/auth['"]/.test(content);
+    if (!hasAccessCtrlImport) {
+      content = ACCESS_CTRL_IMPORT + content;
+      modified = true;
+      changes.push(`import ${ACCESS_CTRL_PIPE}`);
+    }
+
+    const componentDecoratorMatch = content.match(/@Component\s*\(\s*\{([\s\S]*?)\}\s*\)/);
+    if (componentDecoratorMatch) {
+      let decoratorContent = componentDecoratorMatch[1];
+      let newDecoratorContent = decoratorContent;
+      let modifiedDecorator = false;
+
+      if (!decoratorContent.includes(ACCESS_CTRL_PIPE) && !decoratorContent.includes('ScreenCtrlPipe')) {
+        const importsMatch = newDecoratorContent.match(/imports\s*:\s*\[([\s\S]*?)\]/);
+        if (importsMatch) {
+          newDecoratorContent = newDecoratorContent.replace(
+            importsMatch[1],
+            `\n        ${ACCESS_CTRL_PIPE},${importsMatch[1]}`
+          );
+          modifiedDecorator = true;
+          changes.push(`imports ${ACCESS_CTRL_PIPE}`);
+        }
+      }
+
+      if (!decoratorContent.includes('CommonModule') && !decoratorContent.includes('NgIf')) {
+        if (!content.includes("from '@angular/common'") && !content.includes('from "@angular/common"')) {
+          content = `import { CommonModule } from '@angular/common';\n` + content;
+          changes.push('import CommonModule');
+        } else if (!content.includes('CommonModule')) {
+          const commonImportMatch = content.match(/import\s*\{([^}]+)\}\s*from\s*['"]@angular\/common['"]/);
+          if (commonImportMatch) {
+            content = content.replace(
+              commonImportMatch[0],
+              `import { CommonModule, ${commonImportMatch[1].trim()} } from '@angular/common'`
+            );
+            changes.push('add CommonModule to @angular/common import');
+          }
+        }
+
+        const importsMatch = newDecoratorContent.match(/imports\s*:\s*\[([\s\S]*?)\]/);
+        if (importsMatch && !newDecoratorContent.includes('CommonModule')) {
+          newDecoratorContent = newDecoratorContent.replace(
+            importsMatch[1],
+            `\n        CommonModule,${importsMatch[1]}`
+          );
+          modifiedDecorator = true;
+          changes.push('imports CommonModule');
+        }
+      }
+
+      if (modifiedDecorator) {
+        content = content.replace(decoratorContent, newDecoratorContent);
+        modified = true;
+      }
+    }
+  }
+
+  if (modified && write) {
+    fs.writeFileSync(tsFilePath, content, 'utf8');
+  }
+
+  return { modified, changes, content };
+}
+
+function readExistingCsv() {
+  if (!fs.existsSync(OUTPUT_CSV_PATH)) {
+    return [];
+  }
+  const rawCsv = fs.readFileSync(OUTPUT_CSV_PATH, 'utf8');
+  const lines = rawCsv.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  const mappings = [];
+  for (let i = 1; i < lines.length; i++) {
+    const parts = parseCsvLine(lines[i]);
+    if (parts.length >= 5) {
+      mappings.push({
+        screenName: parts[0],
+        screenId: parts[1],
+        componentName: parts[2],
+        componentId: parts[3],
+        componentType: parts[4],
+        description: parts[5] || '',
+      });
+    }
+  }
+  return mappings;
+}
+
+/** Minimal CSV line parser that respects quoted commas. */
+function parseCsvLine(line) {
+  const parts = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (char === ',' && !inQuotes) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+  parts.push(current.trim());
+  return parts;
+}
+
+function csvEscape(value) {
+  const text = String(value ?? '');
+  return `"${text.replace(/"/g, '""')}"`;
+}
+
+function csvLinesFormat(mappings) {
+  const csvLines = ['screenName,screenId,componentName,componentId,componentType,description'];
+  mappings.forEach((m) => {
+    csvLines.push(
+      [
+        csvEscape(m.screenName),
+        csvEscape(m.screenId),
+        csvEscape(m.componentName),
+        csvEscape(m.componentId),
+        csvEscape(m.componentType),
+        csvEscape(m.description || ''),
+      ].join(',')
+    );
+  });
+  return csvLines.join('\n') + '\n';
+}
+
+function withDescription(row) {
+  if (row.description && String(row.description).trim()) {
+    return row;
+  }
+  const description =
+    row.componentType === 'SCREEN' || row.componentId === row.screenId
+      ? generateScreenDescription(row.screenId, row.screenName)
+      : generateComponentDescription(
+          row.componentId,
+          row.componentName,
+          row.componentType,
+          row.screenId
+        );
+  return { ...row, description };
+}
+
+function mergeCsv(existing, discovered, prune) {
+  const keyOf = (m) => `${m.screenId}::${m.componentId}`;
+  const existingByKey = new Map(existing.map((m) => [keyOf(m), m]));
+  const discoveredKeys = new Set(discovered.map(keyOf));
+
+  const enrich = (disc) => {
+    const prev = existingByKey.get(keyOf(disc));
+    // Prefer freshly generated description from scan (includes on-screen heading).
+    const next = withDescription({
+      ...disc,
+      description: disc.description && String(disc.description).trim() ? disc.description : '',
+    });
+    if (prev && prev.description && String(prev.description).startsWith('[manual] ')) {
+      return { ...next, description: prev.description };
+    }
+    return next;
+  };
+
+  let finalMappings;
+  if (prune) {
+    finalMappings = discovered.map(enrich);
+  } else {
+    finalMappings = existing.map((ext) => {
+      if (!ext.description || !String(ext.description).trim()) {
+        return withDescription(ext);
+      }
+      return ext;
+    });
+    for (const disc of discovered) {
+      const key = keyOf(disc);
+      const idx = finalMappings.findIndex((ext) => keyOf(ext) === key);
+      if (idx === -1) {
+        finalMappings.push(enrich(disc));
+      } else {
+        finalMappings[idx] = enrich({ ...finalMappings[idx], ...disc, description: disc.description || '' });
+      }
+    }
+  }
+
+  finalMappings.sort((a, b) => {
+    if (a.screenName !== b.screenName) {
+      return a.screenName.localeCompare(b.screenName);
+    }
+    if (a.componentType === 'SCREEN' && b.componentType !== 'SCREEN') return -1;
+    if (a.componentType !== 'SCREEN' && b.componentType === 'SCREEN') return 1;
+    return a.componentId.localeCompare(b.componentId);
+  });
+
+  const existingKeys = new Set(existing.map(keyOf));
+  const added = discovered.filter((d) => !existingKeys.has(keyOf(d)));
+  const stale = existing.filter((e) => !discoveredKeys.has(keyOf(e)));
+
+  return { finalMappings, added, stale };
+}
+
+function scan(args) {
+  const injectAccess = !args.qaOnly;
+  const injectQa = !args.accessOnly;
+
+  console.log(
+    `Access-control sync (${args.write ? 'WRITE' : 'DRY-RUN'})` +
+      ` access=${injectAccess} qa=${injectQa} rewriteIds=${args.rewriteIds}`
+  );
+
+  const componentFiles = collectComponentFiles();
+  console.log(`Found ${componentFiles.length} component files`);
+
+  const report = {
+    mode: args.write ? 'write' : 'dry-run',
+    scannedComponents: 0,
+    templatesUpdated: [],
+    templatesWouldUpdate: [],
+    tsUpdated: [],
+    tsWouldUpdate: [],
+    skippedNoise: 0,
+    discoveries: [],
+    screenIds: new Set(),
+    duplicateScreenIds: {},
+    errors: [],
+  };
+
+  const allDiscoveries = [];
+  const workItems = [];
+
+  // Phase 1: resolve provisional screen ids (content-based where allowed).
+  for (const entry of componentFiles) {
+    const { filePath: tsFile, fileContent, sourceType } = entry;
+    const classMatch = fileContent.match(/export\s+class\s+(\w+)[^{]*?\{/);
+    if (!classMatch) {
+      continue;
+    }
+    const className = classMatch[1];
+    if (className.toLowerCase().includes('confirm') && className.toLowerCase().includes('dialog')) {
+      continue;
+    }
+
+    report.scannedComponents++;
+
+    const templateUrlMatch = fileContent.match(/templateUrl\s*:\s*['"]([^'"]+)['"]/);
+    let templateContent = '';
+    let htmlPath = '';
+    if (templateUrlMatch) {
+      htmlPath = path.join(path.dirname(tsFile), templateUrlMatch[1]);
+      if (fs.existsSync(htmlPath)) {
+        templateContent = fs.readFileSync(htmlPath, 'utf8');
+      } else {
+        report.errors.push(`Missing template: ${htmlPath}`);
+      }
+    }
+
+    const excluded = isExcludedFromContentIds(tsFile);
+    const content = extractScreenContent(templateContent);
+    const deriveOpts = {
+      htmlContent: templateContent,
+      forceContentIds: args.forceContentIds && !excluded,
+      preferExistingScreen: excluded || args.preferExistingScreen,
+    };
+    const screenId = deriveScreenId(fileContent, tsFile, className, path, deriveOpts);
+    const pathScreenName = formatScreenNameFromPath(entry.rootDir || APPS_DIR, tsFile, path);
+    const screenName = content.title
+      ? `I-${content.title.replace(/^I-\s*/i, '').trim()}`
+      : pathScreenName;
+
+    workItems.push({
+      tsFile,
+      fileContent,
+      className,
+      templateContent,
+      htmlPath,
+      excluded,
+      content,
+      deriveOpts,
+      screenId,
+      screenName,
+      sourceType,
+    });
+  }
+
+  // Phase 2: soft disambiguate content collisions with entity prefix (non-excluded).
+  const idCounts = new Map();
+  for (const item of workItems) {
+    idCounts.set(item.screenId, (idCounts.get(item.screenId) || 0) + 1);
+  }
+  for (const item of workItems) {
+    if ((idCounts.get(item.screenId) || 0) <= 1 || item.excluded) {
+      continue;
+    }
+    const disambiguated = deriveScreenId(item.fileContent, item.tsFile, item.className, path, {
+      ...item.deriveOpts,
+      disambiguateWithEntity: true,
+    });
+    if (disambiguated && disambiguated !== item.screenId) {
+      item.screenId = disambiguated;
+    }
+  }
+
+  // Phase 2b: hard disambiguate remaining clones (cross-module + excluded collisions).
+  const dupFix = disambiguateDuplicateScreenIds(workItems, path);
+  report.duplicateScreenIdResolutions = dupFix.allResolutions
+    .filter((r) => !r.keptPrimary)
+    .map((r) => ({
+      from: r.from,
+      to: r.to,
+      file: path.relative(process.cwd(), r.tsFile),
+    }));
+
+  report.duplicateScreenIds = { ...dupFix.remainingDuplicates };
+  for (const item of workItems) {
+    report.screenIds.add(item.screenId);
+  }
+
+  // Phase 3: inject HTML/TS + collect discoveries.
+  for (const item of workItems) {
+    const { tsFile, fileContent, templateContent, htmlPath, content, screenId, screenName } = item;
+    let htmlModified = false;
+    let discoveries = [];
+
+    if (templateContent && htmlPath) {
+      const parsed = parseHtmlAndInject(templateContent, screenId, screenName, {
+        injectAccess,
+        injectQa,
+        rewriteIds: args.rewriteIds,
+      });
+
+      report.skippedNoise += parsed.skipped.length;
+      discoveries = parsed.discoveries;
+      htmlModified = parsed.modified;
+
+      if (htmlModified) {
+        const rel = path.relative(process.cwd(), htmlPath);
+        if (args.write) {
+          fs.writeFileSync(htmlPath, parsed.html, 'utf8');
+          report.templatesUpdated.push(rel);
+        } else {
+          report.templatesWouldUpdate.push(rel);
+        }
+      }
+    }
+
+    if (discoveries.length > 0 || /SCREEN\s*=/.test(fileContent) || htmlModified) {
+      allDiscoveries.push({
+        screenName,
+        screenId,
+        componentName: 'Screen Access',
+        componentId: screenId,
+        componentType: 'SCREEN',
+        description: generateScreenDescription(screenId, screenName, content.title),
+      });
+      allDiscoveries.push(...discoveries);
+    }
+
+    if (injectAccess) {
+      const existingScreen = (fileContent.match(/^\s*(?:readonly\s+)?SCREEN\s*=\s*['"]([^'"]+)['"]/im) || [])[1];
+      const hasScreenGetter = /^\s*get\s+SCREEN\s*\(/m.test(fileContent);
+      const needsScreenFix = existingScreen && existingScreen !== screenId;
+      const needsTsBootstrap = htmlModified;
+      // Getter-based SCREEN (e.g. filter screenId Input) — still allow default realignment.
+      const needsScreenWrite = hasScreenGetter
+        ? true
+        : !existingScreen || needsScreenFix;
+
+      if (needsScreenWrite || needsTsBootstrap) {
+        const tsResult = processComponentTs(tsFile, fileContent, screenId, args.write, {
+          screenOnly: needsScreenWrite && !needsTsBootstrap,
+        });
+        if (tsResult.modified) {
+          const tsRel = path.relative(process.cwd(), tsFile);
+          if (args.write) {
+            report.tsUpdated.push({ file: tsRel, changes: tsResult.changes });
+          } else {
+            report.tsWouldUpdate.push({ file: tsRel, changes: tsResult.changes });
+          }
+        }
+      }
+    }
+  }
+
+  // Dedupe discoveries
+  const seen = new Set();
+  const uniqueDiscoveries = [];
+  for (const d of allDiscoveries) {
+    const key = `${d.screenId}::${d.componentId}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    uniqueDiscoveries.push(d);
+  }
+
+  const existing = readExistingCsv();
+  const { finalMappings, added, stale } = mergeCsv(existing, uniqueDiscoveries, args.pruneCsv && args.write);
+
+  // Phase 4: route + template hierarchy (page hosts → embedded SCREEN children)
+  const hierarchy = buildScreenNavigationHierarchy({
+    workItems,
+    appsRoot: APPS_DIR,
+    adminRoutesFile: ADMIN_ROUTES_FILE,
+  });
+
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+  fs.writeFileSync(OUTPUT_HIERARCHY_PATH, JSON.stringify(hierarchy, null, 2), 'utf8');
+
+  if (args.write && injectAccess) {
+    const csvContent = csvLinesFormat(finalMappings);
+    fs.writeFileSync(OUTPUT_CSV_PATH, csvContent, 'utf8');
+    fs.mkdirSync(path.dirname(ASSETS_CSV_PATH), { recursive: true });
+    fs.writeFileSync(ASSETS_CSV_PATH, csvContent, 'utf8');
+    fs.writeFileSync(ASSETS_HIERARCHY_PATH, JSON.stringify(hierarchy, null, 2), 'utf8');
+    try {
+      fs.writeFileSync(SHARED_CSV_PATH, csvContent, 'utf8');
+    } catch {
+      // optional mirror next to tools
+    }
+  } else if (injectAccess) {
+    const assetsDir = path.dirname(ASSETS_HIERARCHY_PATH);
+    if (fs.existsSync(assetsDir)) {
+      fs.writeFileSync(ASSETS_HIERARCHY_PATH, JSON.stringify(hierarchy, null, 2), 'utf8');
+    }
+  }
+
+  const serializableReport = {
+    ...report,
+    screenIds: [...report.screenIds].sort(),
+    discoveryCount: uniqueDiscoveries.length,
+    screenCount: uniqueDiscoveries.filter((d) => d.componentType === 'SCREEN').length,
+    buttonCount: uniqueDiscoveries.filter((d) => d.componentType === 'BUTTON').length,
+    csvWouldAdd: added.slice(0, 50),
+    csvWouldAddCount: added.length,
+    csvStaleCount: stale.length,
+    csvStaleSample: stale.slice(0, 30),
+    duplicateScreenIdCount: Object.keys(report.duplicateScreenIds).length,
+    duplicateScreenIdResolutions: report.duplicateScreenIdResolutions || [],
+    templatesWouldUpdateCount: report.templatesWouldUpdate.length,
+    templatesUpdatedCount: report.templatesUpdated.length,
+    sampleDiscoveries: uniqueDiscoveries.filter((d) => d.componentType === 'BUTTON').slice(0, 40),
+    hierarchy: {
+      pageCount: hierarchy.stats.pageCount,
+      embedEdgeCount: hierarchy.stats.embedEdgeCount,
+      unresolvedCount: hierarchy.stats.unresolvedCount,
+      resolvedWithoutScreenCount: hierarchy.stats.resolvedWithoutScreenCount || 0,
+      astComponentCount: hierarchy.stats.astComponentCount || 0,
+      classification: hierarchy.classification || null,
+      samplePages: hierarchy.pages.slice(0, 15),
+      unresolvedSample: hierarchy.unresolved.slice(0, 40),
+      resolvedWithoutScreenSample: (hierarchy.resolvedWithoutScreen || []).slice(0, 40),
+      output: path.relative(process.cwd(), OUTPUT_HIERARCHY_PATH),
+    },
+  };
+
+  fs.writeFileSync(REPORT_PATH, JSON.stringify(serializableReport, null, 2), 'utf8');
+
+  console.log('');
+  console.log('── Summary ──────────────────────────────────');
+  console.log(`Components scanned:     ${report.scannedComponents}`);
+  console.log(`Unique screenIds:       ${report.screenIds.size}`);
+  console.log(`Duplicate screenIds:    ${Object.keys(report.duplicateScreenIds).length}`);
+  if ((report.duplicateScreenIdResolutions || []).length > 0) {
+    console.log(
+      `Duplicate ids resolved: ${report.duplicateScreenIdResolutions.length} (module/path uniquified)`
+    );
+  }
+  console.log(`Discoveries (unique):   ${uniqueDiscoveries.length}`);
+  console.log(`  SCREEN rows:          ${serializableReport.screenCount}`);
+  console.log(`  BUTTON rows:          ${serializableReport.buttonCount}`);
+  console.log(`Noise skipped:          ${report.skippedNoise}`);
+  console.log(
+    `Templates ${args.write ? 'updated' : 'would update'}: ${
+      args.write ? report.templatesUpdated.length : report.templatesWouldUpdate.length
+    }`
+  );
+  console.log(`CSV new rows:           ${added.length}`);
+  console.log(`CSV stale rows:         ${stale.length}`);
+  console.log(`Hierarchy pages:        ${hierarchy.stats.pageCount}`);
+  console.log(`Hierarchy embed edges:  ${hierarchy.stats.embedEdgeCount}`);
+  console.log(`Hierarchy unresolved:   ${hierarchy.stats.unresolvedCount}`);
+  console.log(
+    `Hierarchy resolved (no SCREEN): ${hierarchy.stats.resolvedWithoutScreenCount || 0}`
+  );
+  console.log(`Hierarchy map:          ${path.relative(process.cwd(), OUTPUT_HIERARCHY_PATH)}`);
+  console.log(`Report:                 ${path.relative(process.cwd(), REPORT_PATH)}`);
+
+  if (Object.keys(report.duplicateScreenIds).length > 0) {
+    console.log('');
+    console.log('⚠ Duplicate SCREEN ids remaining after disambiguation:');
+    for (const [id, files] of Object.entries(report.duplicateScreenIds).slice(0, 10)) {
+      console.log(`  ${id}`);
+      for (const f of files) {
+        console.log(`    - ${path.relative(process.cwd(), f)}`);
+      }
+    }
+  }
+
+  console.log('');
+  if (!args.write) {
+    console.log('Dry-run only. Re-run with --write to apply.');
+  } else {
+    console.log('Write complete.');
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+  scan(args);
+}
+
+main();