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

package/src/templates/fuse-packs/access-control-tools/lib/id-rules.js

@@ -0,0 +1,1095 @@
+'use strict';
+
+/**
+ * Shared ID rules for access-control + QA injection.
+ *
+ * Convention:
+ *   screenId      = entity/page key (from SCREEN or filename)
+ *   componentId   = {verb}[-{noun}]           e.g. save, open-filter, export-excel
+ *   qaId          = qa-{screenId}__{componentId}
+ *   accessCtrl    = SCREEN | accessCtrl: '{componentId}'
+ */
+
+const GENERIC_SCREEN_SEGMENTS = new Set([
+  'actions',
+  'action',
+  'list',
+  'lists',
+  'filter',
+  'filters',
+  'form',
+  'forms',
+  'detail',
+  'details',
+  'dialog',
+  'dialogs',
+  'shared',
+  'component',
+  'components',
+  'page',
+  'pages',
+  'panel',
+  'panels',
+  'create',
+  'edit',
+  'update',
+  'new',
+  'view',
+  'card',
+  'cards',
+]);
+
+/** Click / method patterns that must never become RBAC or QA targets. */
+const NOISE_ACTION_PATTERNS = [
+  /^\$?event\.stoppropagation$/i,
+  /^stoppropagation$/i,
+  /^onbackdropclick$/i,
+  /^presentation$/i,
+  /^null$/i,
+  /^true$/i,
+  /^false$/i,
+];
+
+/** Exact slugified actions to skip (chrome / non-permission UI). */
+const NOISE_ACTIONS = new Set([
+  'event-stop-propagation',
+  'stop-propagation',
+  'on-backdrop-click',
+  'on-search-term-change',
+  'toggle-pin',
+  'set-flag-menu-row',
+  'set-flag-color',
+  'isexporting',
+  'is-exporting',
+]);
+
+/**
+ * Map raw method / emit names → stable semantic componentId verbs.
+ * Keys are slugified (kebab-case) method names without args.
+ */
+const SEMANTIC_ACTION_MAP = {
+  'on-cancel': 'cancel',
+  cancel: 'cancel',
+  'close-drawer': 'close-drawer',
+  'close-filter-drawer': 'close-filter',
+  'clear-filters': 'clear-filters',
+  'clear-field': 'clear-field',
+  'clear-all': 'clear-filters',
+  'filter-click-emit': 'open-filter',
+  'filter-click': 'open-filter',
+  filter: 'open-filter',
+  'new-click-emit': 'create',
+  'new-click': 'create',
+  new: 'create',
+  add: 'create',
+  'open-drawer-create': 'create',
+  'toggle-view-mode': 'toggle-view',
+  'set-view-mode': 'toggle-view',
+  'view-mode': 'toggle-view',
+  'toggle-filter': 'open-filter',
+  columns: 'open-columns',
+  'column-preferences': 'open-columns',
+  'export-all-data': 'export-all',
+  'export-filtered-data': 'export-filtered',
+  'export-to-excel': 'export-excel',
+  'export-to-pdf': 'export-pdf',
+  'export-excel': 'export-excel',
+  'export-pdf': 'export-pdf',
+  'generate-pdf': 'export-pdf',
+  'reset-column-preferences': 'reset-columns',
+  'open-column-preferences': 'open-columns',
+  'open-form-drawer': 'edit',
+  'view-details-for-element': 'view',
+  'view-details': 'view',
+  delete: 'delete',
+  'toggle-active': 'toggle-active',
+  'go-back': 'go-back',
+  'on-card-activate': 'open',
+  'on-view-details': 'view',
+  'on-edit': 'edit',
+  'copy-token-number': 'copy-token',
+  'assign-to-me': 'assign-to-me',
+  action: 'submit', // type=submit / bare mat-button fallback refined later
+};
+
+const SCREEN_NAME_OVERRIDES = {
+  'user-management': 'I-Users',
+  institute: 'I-Institutions',
+  toplevel: 'I-Association Board',
+  'stakeholder-business': 'I-Stackholders',
+};
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '');
+}
+
+function camelToKebab(text) {
+  return String(text || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_.]/g, '-')
+    .toLowerCase();
+}
+
+function resolveMeaningfulSegment(segments) {
+  for (let index = segments.length - 1; index >= 0; index--) {
+    const segment = segments[index];
+    if (!GENERIC_SCREEN_SEGMENTS.has(segment)) {
+      return segment;
+    }
+  }
+  return segments[segments.length - 1] || '';
+}
+
+function formatScreenName(folderName) {
+  if (SCREEN_NAME_OVERRIDES[folderName]) {
+    return SCREEN_NAME_OVERRIDES[folderName];
+  }
+  const words = folderName.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1));
+  return 'I-' + words.join(' ');
+}
+
+function formatScreenNameFromPath(baseDir, filePath, pathModule) {
+  const relativeDir = pathModule.relative(baseDir, pathModule.dirname(filePath));
+  const segments = relativeDir.split(pathModule.sep).filter(Boolean);
+  const meaningfulSegment = resolveMeaningfulSegment(segments);
+  return formatScreenName(meaningfulSegment || pathModule.basename(pathModule.dirname(filePath)));
+}
+
+const VIEW_SUFFIXES = [
+  'column-preferences',
+  'status-dialog',
+  'form-page',
+  'actions',
+  'filter',
+  'detail',
+  'drawer',
+  'dialog',
+  'list',
+  'form',
+  'card',
+  'page',
+  'panel',
+  'section',
+];
+
+/**
+ * Pull human-facing copy from a template for unique ids + matrix descriptions.
+ * Prefers the first real h1/h2 title (Angular bindings stripped).
+ */
+function extractScreenContent(htmlContent) {
+  const html = String(htmlContent || '');
+  const candidates = [];
+
+  const headingRe = /<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/gi;
+  let match;
+  while ((match = headingRe.exec(html)) !== null) {
+    const text = cleanTemplateText(match[1]);
+    if (text) {
+      candidates.push(text);
+    }
+  }
+
+  if (!candidates.length) {
+    const titleRe = /<(?:div|span|p)\b[^>]*class="[^"]*(?:text-3xl|truncate text-3xl|page-title|screen-title)[^"]*"[^>]*>([\s\S]*?)<\//gi;
+    while ((match = titleRe.exec(html)) !== null) {
+      const text = cleanTemplateText(match[1]);
+      if (text) {
+        candidates.push(text);
+      }
+    }
+  }
+
+  const title = candidates[0] || '';
+  return {
+    title,
+    titles: candidates,
+    snippet: title,
+  };
+}
+
+function cleanTemplateText(raw) {
+  return String(raw || '')
+    .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+    .replace(/@if\s*\([\s\S]*?\)\s*\{[\s\S]*?\}/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function detectViewSuffix(fileName) {
+  const base = String(fileName || '')
+    .replace(/\.component$/i, '')
+    .toLowerCase();
+  for (const suffix of VIEW_SUFFIXES) {
+    if (base === suffix || base.endsWith(`-${suffix}`)) {
+      return suffix;
+    }
+  }
+  return '';
+}
+
+/**
+ * Trailing title words that are marketing chrome, not the product entity.
+ * Keeps nav grants aligned: "Regional Office Registration" → regional-office(-list).
+ * Do not strip "management" (e.g. User Management).
+ */
+const TITLE_TRAILING_NOISE = new Set([
+  'registration',
+  'register',
+  'master',
+  'portal',
+  'overview',
+  'screen',
+  'module',
+  'records',
+  'record',
+  'listing',
+]);
+
+/** Headings too generic to own a unique screen id — use path-canonical instead. */
+const GENERIC_CONTENT_TITLES = new Set([
+  'advanced-filters',
+  'advanced-filter',
+  'filters',
+  'filter',
+  'search',
+  'actions',
+  'details',
+  'detail',
+  'form',
+  'list',
+  'card',
+  'dialog',
+  'drawer',
+  'loading',
+  'error',
+  'confirm',
+  'confirmation',
+]);
+
+function isGenericContentTitle(title) {
+  const slug = slugify(title);
+  if (!slug) {
+    return true;
+  }
+  if (GENERIC_CONTENT_TITLES.has(slug)) {
+    return true;
+  }
+  // Single generic token
+  if (GENERIC_CONTENT_TITLES.has(slug.replace(/-panel$/, '').replace(/-dialog$/, ''))) {
+    return true;
+  }
+  return false;
+}
+
+function entitySegmentFromPath(tsFilePath) {
+  const normalized = String(tsFilePath || '').replace(/\\/g, '/');
+  const match = normalized.match(/\/entities\/([^/]+)\//);
+  if (match) {
+    return match[1];
+  }
+  const pages = normalized.match(/\/pages\/([^/]+)\//);
+  return pages ? pages[1] : '';
+}
+
+/**
+ * micro-functions module slug for cross-module SCREEN disambiguation.
+ * identityAccessModule → identity-access, referenceModule → reference
+ */
+function moduleSegmentFromPath(tsFilePath) {
+  const normalized = String(tsFilePath || '').replace(/\\/g, '/');
+  const match = normalized.match(/\/micro-functions\/([^/]+)\//);
+  if (!match) {
+    return '';
+  }
+  const raw = match[1].replace(/Module$/i, '');
+  return slugify(raw.replace(/([a-z0-9])([A-Z])/g, '$1-$2'));
+}
+
+/**
+ * Lower = keep the shared id when clones collide.
+ * Prefer Keycloak-stable identityAccess, then routed referenceModule, then domain modules.
+ */
+function duplicatePrimaryRank(tsFilePath) {
+  const normalized = String(tsFilePath || '').replace(/\\/g, '/');
+  if (normalized.includes('/identityAccessModule/')) {
+    return 0;
+  }
+  if (normalized.includes('/referenceModule/')) {
+    return 1;
+  }
+  if (normalized.includes('/warehouseModule/')) {
+    return 2;
+  }
+  if (normalized.includes('/millerModule/')) {
+    return 3;
+  }
+  if (normalized.includes('/paddy-selling-and-movement/')) {
+    return 4;
+  }
+  if (normalized.includes('/notificationModule/')) {
+    return 5;
+  }
+  if (normalized.includes('/dad-mock-module/')) {
+    return 9;
+  }
+  return 6;
+}
+
+/**
+ * When multiple work items share a SCREEN id, keep one primary and rewrite the rest
+ * to path/module-unique ids. Never invent content titles — path/module only.
+ *
+ * @param {Array<{ tsFile: string, screenId: string }>} workItems mutated in place
+ * @param {object} pathModule node:path
+ * @returns {{ resolved: Array<{ from: string, to: string, tsFile: string, keptPrimary: boolean }>, remainingDuplicates: Record<string, string[]> }}
+ */
+function disambiguateDuplicateScreenIds(workItems, pathModule) {
+  const resolved = [];
+  const byId = new Map();
+  for (const item of workItems || []) {
+    if (!item?.screenId) {
+      continue;
+    }
+    const list = byId.get(item.screenId) || [];
+    list.push(item);
+    byId.set(item.screenId, list);
+  }
+
+  const used = new Set(
+    [...byId.keys()].filter((id) => (byId.get(id) || []).length === 1)
+  );
+  // Primaries of duplicate groups also keep their id in `used`.
+  for (const [screenId, group] of byId.entries()) {
+    if (group.length <= 1) {
+      continue;
+    }
+    group.sort((a, b) => {
+      const rank = duplicatePrimaryRank(a.tsFile) - duplicatePrimaryRank(b.tsFile);
+      if (rank !== 0) {
+        return rank;
+      }
+      // Prefer a file that already embeds this id in source (Keycloak-stable).
+      const aHas = new RegExp(`SCREEN\\s*=\\s*['"]${screenId}['"]`).test(a.fileContent || '');
+      const bHas = new RegExp(`SCREEN\\s*=\\s*['"]${screenId}['"]`).test(b.fileContent || '');
+      if (aHas !== bHas) {
+        return aHas ? -1 : 1;
+      }
+      return String(a.tsFile).localeCompare(String(b.tsFile));
+    });
+    const primary = group[0];
+    used.add(primary.screenId);
+    resolved.push({
+      from: screenId,
+      to: screenId,
+      tsFile: primary.tsFile,
+      keptPrimary: true,
+    });
+
+    for (let i = 1; i < group.length; i++) {
+      const item = group[i];
+      const pathId = deriveCanonicalScreenId(item.tsFile, pathModule);
+      const moduleSlug = moduleSegmentFromPath(item.tsFile);
+      const entity = slugify(entitySegmentFromPath(item.tsFile));
+      const candidates = [];
+      if (pathId) {
+        candidates.push(pathId);
+      }
+      if (moduleSlug && pathId && !pathId.startsWith(`${moduleSlug}-`)) {
+        candidates.push(`${moduleSlug}-${pathId}`);
+      }
+      if (moduleSlug && entity) {
+        const fileName = pathModule
+          .basename(item.tsFile, '.ts')
+          .replace(/\.component$/, '');
+        if (fileName && !fileName.startsWith(`${moduleSlug}-`)) {
+          candidates.push(`${moduleSlug}-${fileName}`);
+        }
+        candidates.push(`${moduleSlug}-${entity}-${detectViewSuffix(fileName) || 'screen'}`);
+      }
+      candidates.push(`${moduleSlug || 'dup'}-${pathId || 'screen'}-${i}`);
+
+      let next = '';
+      for (const candidate of candidates) {
+        if (candidate && !used.has(candidate)) {
+          next = candidate;
+          break;
+        }
+      }
+      if (!next) {
+        next = `dup-${slugify(pathModule.basename(item.tsFile, '.ts'))}-${i}`;
+      }
+      // Final uniqueness guard
+      let unique = next;
+      let n = 2;
+      while (used.has(unique)) {
+        unique = `${next}-${n}`;
+        n++;
+      }
+      resolved.push({
+        from: screenId,
+        to: unique,
+        tsFile: item.tsFile,
+        keptPrimary: false,
+      });
+      item.screenId = unique;
+      used.add(unique);
+    }
+  }
+
+  const remainingDuplicates = {};
+  const recount = new Map();
+  for (const item of workItems || []) {
+    if (!item?.screenId) {
+      continue;
+    }
+    recount.set(item.screenId, (recount.get(item.screenId) || 0) + 1);
+  }
+  for (const item of workItems || []) {
+    if (!item?.screenId || (recount.get(item.screenId) || 0) <= 1) {
+      continue;
+    }
+    const list = remainingDuplicates[item.screenId] || [];
+    list.push(item.tsFile);
+    remainingDuplicates[item.screenId] = list;
+  }
+
+  return { resolved: resolved.filter((r) => !r.keptPrimary || r.from !== r.to), remainingDuplicates, allResolutions: resolved };
+}
+
+/** Modules that keep path/filename SCREEN ids (no content-based rewrite). */
+const CONTENT_ID_EXCLUDED_PATH_PARTS = [
+  '/dad-mock-module/',
+  '/accessControlModule/',
+  '/notificationModule/',
+];
+
+function isExcludedFromContentIds(tsFilePath) {
+  const normalized = String(tsFilePath || '').replace(/\\/g, '/');
+  return CONTENT_ID_EXCLUDED_PATH_PARTS.some((part) => normalized.includes(part));
+}
+
+/**
+ * Build a unique, human-readable screen id from page title + view type.
+ * Example: "Regional Office Registration" + list → regional-office-list
+ */
+function deriveContentScreenId(contentTitle, fileName, pathFallback) {
+  const view = detectViewSuffix(fileName);
+  let base = slugify(contentTitle);
+  if (!base) {
+    return pathFallback || '';
+  }
+
+  // Drop trailing view words already present in the title slug.
+  for (const suffix of VIEW_SUFFIXES) {
+    if (base.endsWith(`-${suffix}`)) {
+      base = base.slice(0, -(suffix.length + 1));
+      break;
+    }
+  }
+
+  // Drop one trailing noise token (Registration, Portal, …).
+  const parts = base.split('-').filter(Boolean);
+  while (parts.length > 1 && TITLE_TRAILING_NOISE.has(parts[parts.length - 1])) {
+    parts.pop();
+  }
+  base = parts.join('-');
+
+  if (view && base) {
+    return `${base}-${view}`;
+  }
+  return base || pathFallback || '';
+}
+
+/**
+ * Path-aware unique screen id. Prefer this over a bare filename so cloned
+ * entities (collecter / dad-mock / pages mirrors) do not collide.
+ */
+function deriveCanonicalScreenId(tsFilePath, pathModule) {
+  const normalized = tsFilePath.replace(/\\/g, '/');
+  const fileName = pathModule.basename(tsFilePath, '.ts').replace(/\.component$/, '');
+
+  const reportColPref = normalized.match(/\/pages\/reports\/([^/]+)\/list\/column-preferences-dialog/);
+  if (reportColPref) {
+    return `${reportColPref[1]}-column-preferences`;
+  }
+
+  if (fileName === 'region-floating-actions') {
+    return 'region-floating-actions';
+  }
+
+  // Service modules nested beneath the common micro-functions container.
+  const serviceEntity = normalized.match(
+    /\/modules\/apps\/micro-functions\/([^/]+)\/entities\/([^/]+)\//
+  );
+  if (serviceEntity) {
+    return `${serviceEntity[1]}/${serviceEntity[2]}`;
+  }
+
+  // CRUDForge Fuse entities: apps/{micro-functions|microservice}/{entity}/…
+  // Keep SCREEN aligned with nav ACL ids: `{folder}/{entity}`.
+  const crudforgeEntity = normalized.match(
+    /\/modules\/apps\/(micro-functions|microservice)\/([^/]+)\//
+  );
+  if (crudforgeEntity) {
+    return `${crudforgeEntity[1]}/${crudforgeEntity[2]}`;
+  }
+
+  // Identity Regional Office lives under entities/region but product ids are regional-office-*.
+  if (normalized.includes('/identityAccessModule/entities/region/')) {
+    const orgTree = normalized.match(/\/region-org-tree-drawer\/([^/]+)/);
+    if (orgTree) {
+      return `regional-office-${fileName.replace(/^region-/, '')}`;
+    }
+    if (fileName.startsWith('region-')) {
+      return `regional-office-${fileName.slice('region-'.length)}`;
+    }
+    if (fileName === 'region') {
+      return 'regional-office';
+    }
+    return fileName.startsWith('regional-office') ? fileName : `regional-office-${fileName}`;
+  }
+
+  if (normalized.includes('/modules/apps/pages/')) {
+    if (normalized.includes('/pages/reports/warehouse-capacity/')) {
+      return `report-${fileName}`;
+    }
+    if (
+      normalized.includes('/pages/stock-transfer/') ||
+      normalized.includes('/pages/paddy-selling-and-movement/') ||
+      normalized.includes('/pages/purchase-policy/') ||
+      normalized.includes('/pages/purchasing-rate-card/')
+    ) {
+      return fileName.startsWith('page-') ? fileName : `page-${fileName}`;
+    }
+    // Brand / vendor nested under dashboard components (e.g. …/components/PMB/<card>/)
+    const nestedBrand = normalized.match(/\/components\/([^/]+)\/([^/]+)\//);
+    if (
+      nestedBrand &&
+      nestedBrand[2] === fileName &&
+      slugify(nestedBrand[1]) &&
+      slugify(nestedBrand[1]) !== fileName
+    ) {
+      return `${slugify(nestedBrand[1])}-${fileName}`;
+    }
+    return fileName;
+  }
+
+  const orgTree = normalized.match(
+    /\/(region-org-tree-drawer|stakeholder-business-org-tree-drawer)\/([^/]+)/
+  );
+  if (orgTree) {
+    const scope = orgTree[1] === 'region-org-tree-drawer' ? 'regional-office' : 'stakeholder-business';
+    return `${scope}-${fileName}`;
+  }
+
+  if (normalized.includes('/dad-mock-module/entities/')) {
+    const entityMatch = normalized.match(/\/entities\/([^/]+)\//);
+    const entity = entityMatch ? entityMatch[1] : '';
+    if (['district', 'gn', 'region'].includes(entity)) {
+      return fileName.startsWith('dad-') ? fileName : `dad-${fileName}`;
+    }
+  }
+
+  const entityMatch = normalized.match(/\/entities\/([^/]+)\//);
+  if (entityMatch) {
+    const entity = entityMatch[1];
+    if (entity.endsWith('-collecter')) {
+      const baseEntity = entity.replace(/-collecter$/, '');
+      if (fileName === 'intake-status-dialog') {
+        return `${entity}-status-dialog`;
+      }
+      if (fileName === baseEntity || fileName.startsWith(`${baseEntity}-`)) {
+        return fileName.replace(new RegExp(`^${baseEntity}`), entity);
+      }
+      return `${entity}-${fileName}`;
+    }
+  }
+
+  return fileName;
+}
+
+/**
+ * Resolve screen id.
+ *
+ * Included modules (default when forceContentIds):
+ *   heading + view → human id (rewrites existing SCREEN), else path-canonical
+ *
+ * Excluded modules (dad-mock / accessControl / notification):
+ *   keep existing SCREEN, else path-canonical (never content rewrite)
+ */
+function deriveScreenId(fileContent, tsFilePath, className, pathModule, options = {}) {
+  const htmlContent = options.htmlContent || '';
+  const excluded = isExcludedFromContentIds(tsFilePath);
+  const forceContentIds = Boolean(options.forceContentIds) && !excluded;
+  const preferExisting = excluded || options.preferExistingScreen !== false;
+  const fileName = pathModule.basename(tsFilePath, '.ts').replace(/\.component$/, '');
+  const existing = (String(fileContent || '').match(/SCREEN\s*=\s*['"]([^'"]+)['"]/i) || [])[1];
+  const pathCanonical = deriveCanonicalScreenId(tsFilePath, pathModule);
+  const normalizedPath = String(tsFilePath || '').replace(/\\/g, '/');
+
+  // Identity Regional Office: product SCREEN ids are regional-office-* even when
+  // headings still say "Region Details" / similar.
+  if (normalizedPath.includes('/identityAccessModule/entities/region/')) {
+    return pathCanonical || existing || fileName;
+  }
+
+  const content = extractScreenContent(htmlContent);
+  const useContentTitle = !excluded && content.title && !isGenericContentTitle(content.title);
+  let contentId = useContentTitle
+    ? deriveContentScreenId(content.title, fileName, pathCanonical)
+    : '';
+
+  // Optional disambiguator when the same heading appears on multiple entities.
+  if (options.disambiguateWithEntity && contentId) {
+    const entity = slugify(entitySegmentFromPath(tsFilePath));
+    if (entity && !contentId.startsWith(`${entity}-`)) {
+      contentId = `${entity}-${contentId}`;
+    }
+  }
+
+  // Excluded / stable mode: never thrash Keycloak-facing ids.
+  if (excluded || (preferExisting && existing && !forceContentIds)) {
+    return existing || pathCanonical || fileName;
+  }
+
+  // Rewrite / create human-readable ids from on-screen title.
+  if (forceContentIds) {
+    return contentId || pathCanonical || existing || fileName;
+  }
+
+  if (!existing && contentId) {
+    return contentId;
+  }
+
+  if (pathCanonical) {
+    return pathCanonical;
+  }
+
+  if (existing) {
+    return existing;
+  }
+
+  if (fileName) {
+    return fileName;
+  }
+
+  return className
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/-component$/, '');
+}
+
+function extractRawAction(tagContent) {
+  const clickMatch = tagContent.match(/(?:\(click\)|on-click|\[click\])\s*=\s*["']([^"']+)["']/);
+  if (clickMatch) {
+    const raw = clickMatch[1].trim();
+    // Strip args: foo($event) / bar.emit() / baz(element)
+    const method = raw.replace(/\(.*$/, '').replace(/\.emit$/, '').trim();
+    if (method && !NOISE_ACTION_PATTERNS.some((re) => re.test(method.replace(/\s+/g, '')))) {
+      return camelToKebab(method);
+    }
+    if (NOISE_ACTION_PATTERNS.some((re) => re.test(raw.replace(/\s+/g, '')))) {
+      return { skip: true, reason: 'noise-click', raw };
+    }
+  }
+
+  const tooltipMatch = tagContent.match(/matTooltip\s*=\s*["']([^"']+)["']/i);
+  if (tooltipMatch) {
+    return slugify(tooltipMatch[1]);
+  }
+
+  const ariaLabelMatch = tagContent.match(/aria-label\s*=\s*["']([^"']+)["']/i);
+  if (ariaLabelMatch) {
+    return slugify(ariaLabelMatch[1]);
+  }
+
+  const routerMatch = tagContent.match(/routerLink\s*=\s*["']([^"']+)["']/i);
+  if (routerMatch) {
+    return slugify(routerMatch[1].replace(/^\//, '').replace(/\//g, '-'));
+  }
+
+  // Button text between > and < on same-ish tag context is hard; use type/role hints
+  if (/\btype\s*=\s*["']submit["']/i.test(tagContent)) {
+    return 'submit';
+  }
+  if (/matMenuTriggerFor/i.test(tagContent)) {
+    return 'open-menu';
+  }
+  if (/matStepperNext/i.test(tagContent)) {
+    return 'next-step';
+  }
+  if (/matStepperPrevious/i.test(tagContent)) {
+    return 'prev-step';
+  }
+
+  return '';
+}
+
+function isNoiseAction(actionSlug) {
+  if (!actionSlug) {
+    return true;
+  }
+  if (NOISE_ACTIONS.has(actionSlug)) {
+    return true;
+  }
+  if (actionSlug.includes('stop-propagation')) {
+    return true;
+  }
+  if (actionSlug.includes('backdrop-click')) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve a componentId (without qa- prefix).
+ * Returns null when the tag should be skipped.
+ *
+ * - rewriteIds=false: keep existing accessCtrl / data-component-id verbatim (stable)
+ * - rewriteIds=true: normalize legacy noisy ids to clean {verb} form
+ * - no existing id: generate clean semantic id for new injections
+ */
+function resolveComponentId(tagContent, screenId, options = {}) {
+  const { rewriteIds = false } = options;
+
+  // Prefer explicit data-action override
+  const dataAction = tagContent.match(/data-action\s*=\s*["']([^"']+)["']/i);
+  if (dataAction) {
+    return slugify(dataAction[1]);
+  }
+
+  const accessCtrlMatch = tagContent.match(/accessCtrl\s*:\s*['"]([^'"]+)['"]/);
+  if (accessCtrlMatch) {
+    const existing = accessCtrlMatch[1];
+    if (rewriteIds) {
+      return normalizeLegacyComponentId(existing, screenId);
+    }
+    // Still skip if the existing id is pure noise
+    const normalized = normalizeLegacyComponentId(existing, screenId);
+    if (normalized === null) {
+      return null;
+    }
+    return existing.replace(/^qa-/, '');
+  }
+
+  const dataComponentId = tagContent.match(/data-component-id\s*=\s*["']([^"']+)["']/i);
+  if (dataComponentId) {
+    const existing = dataComponentId[1];
+    if (rewriteIds) {
+      return normalizeLegacyComponentId(existing, screenId);
+    }
+    const normalized = normalizeLegacyComponentId(existing, screenId);
+    if (normalized === null) {
+      return null;
+    }
+    return existing.replace(/^qa-/, '');
+  }
+
+  const raw = extractRawAction(tagContent);
+  if (raw && typeof raw === 'object' && raw.skip) {
+    return null;
+  }
+
+  let action = typeof raw === 'string' ? raw : '';
+  if (!action) {
+    const tagNameMatch = tagContent.match(/^<([a-zA-Z0-9-]+)/);
+    const tagName = tagNameMatch ? tagNameMatch[1].toLowerCase() : '';
+    if (tagName === 'a') {
+      action = 'link';
+    } else if (tagName === 'button' || /mat-(raised-|icon-|stroked-|flat-|mini-)?button/i.test(tagContent)) {
+      action = 'action';
+    } else {
+      return null;
+    }
+  }
+
+  action = slugify(action).replace(/-(btn|button)$/, '');
+  if (isNoiseAction(action)) {
+    return null;
+  }
+
+  if (SEMANTIC_ACTION_MAP[action]) {
+    action = SEMANTIC_ACTION_MAP[action];
+  }
+
+  // Strip redundant screen fragment from action
+  const coreScreenId = screenId.replace(/-(list|form|filter|actions|detail|card)$/, '');
+  if (action.endsWith(`-${screenId}`)) {
+    action = action.slice(0, -(screenId.length + 1));
+  }
+  if (action.endsWith(`-${coreScreenId}`)) {
+    action = action.slice(0, -(coreScreenId.length + 1));
+  }
+
+  action = slugify(action) || 'action';
+  return action;
+}
+
+/** Strip legacy `-screenId-btn` / `-N-btn` suffixes to the clean verb form. */
+function normalizeLegacyComponentId(componentId, screenId) {
+  let id = String(componentId || '');
+  id = id.replace(/^qa-/, '');
+  id = id.replace(/-\d+-btn$/, '').replace(/-btn$/, '');
+
+  if (screenId && id.endsWith(`-${screenId}`)) {
+    id = id.slice(0, -(screenId.length + 1));
+  }
+
+  const coreScreenId = screenId.replace(/-(list|form|filter|actions|detail|card)$/, '');
+  if (coreScreenId && id.endsWith(`-${coreScreenId}`)) {
+    id = id.slice(0, -(coreScreenId.length + 1));
+  }
+
+  id = slugify(id);
+  if (SEMANTIC_ACTION_MAP[id]) {
+    id = SEMANTIC_ACTION_MAP[id];
+  }
+  if (isNoiseAction(id)) {
+    return null;
+  }
+  return id || null;
+}
+
+function toQaId(screenId, componentId) {
+  return `qa-${screenId}__${componentId}`;
+}
+
+function deduceComponentName(componentId, screenId) {
+  if (componentId === screenId) {
+    return 'Screen Access';
+  }
+  const lower = componentId.toLowerCase();
+  if (lower === 'create' || lower === 'add' || lower === 'new' || lower.includes('create')) return 'Create';
+  if (lower === 'edit' || lower.includes('edit') || lower.includes('update')) return 'Edit';
+  if (lower === 'delete' || lower.includes('delete') || lower.includes('remove')) return 'Delete';
+  if (lower.includes('reset') && lower.includes('password')) return 'Reset Password';
+  if (lower.includes('change') && lower.includes('password')) return 'Change Password';
+  if (lower === 'toggle-view' || lower === 'view-mode') return 'Toggle View';
+  if (lower === 'open-columns' || lower === 'columns') return 'Columns';
+  if (lower === 'view' || lower.includes('view') || lower.includes('detail')) return 'View';
+  if (lower === 'submit' || lower === 'save') return 'Save';
+  if (lower === 'cancel') return 'Cancel';
+  if (lower === 'open-filter' || lower === 'filter') return 'Filter';
+  if (lower.startsWith('export')) return 'Export';
+
+  return componentId
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function deduceComponentType(componentId, screenId) {
+  if (componentId === screenId) {
+    return 'SCREEN';
+  }
+  if (componentId.toLowerCase().includes('panel')) {
+    return 'PANEL';
+  }
+  return 'BUTTON';
+}
+
+function ensureUniqueId(baseId, usedIds) {
+  if (!usedIds.has(baseId)) {
+    usedIds.add(baseId);
+    return baseId;
+  }
+  let counter = 2;
+  let candidate = `${baseId}-${counter}`;
+  while (usedIds.has(candidate)) {
+    counter++;
+    candidate = `${baseId}-${counter}`;
+  }
+  usedIds.add(candidate);
+  return candidate;
+}
+
+function titleCaseFromSlug(slug) {
+  return String(slug || '')
+    .replace(/^i-/i, '')
+    .replace(/^(dad-|ref-|page-|report-)/, '')
+    .split('-')
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function entityLabelFromScreenId(screenId) {
+  let id = String(screenId || '');
+  id = id.replace(/^(dad-|ref-|page-|report-)/, '');
+  id = id.replace(
+    /-(list|form|filter|actions|detail|card|form-page|drawer|dialog|page|section|panel|status-dialog|column-preferences)$/g,
+    ''
+  );
+  id = id.replace(/-collecter$/, ' Collector');
+  return titleCaseFromSlug(id) || 'This feature';
+}
+
+const VIEW_TYPE_PHRASES = {
+  list: 'master list screen used to search, browse, and manage records',
+  form: 'form screen used to create or edit a record',
+  'form-page': 'full-page form used to create or edit a record',
+  filter: 'filter panel used to narrow down records on this screen',
+  actions: 'toolbar actions for this screen (search, filter, create, view mode)',
+  detail: 'detail screen showing full information for a single record',
+  card: 'card view item for a single record in this feature',
+  drawer: 'side drawer related to this feature',
+  dialog: 'dialog used for a focused action in this feature',
+  page: 'application page for this feature',
+  section: 'section of a larger screen for this feature',
+  panel: 'panel within this feature',
+  'column-preferences': 'dialog to choose which table columns are visible',
+  'status-dialog': 'dialog to update or view status for this feature',
+};
+
+/**
+ * Human-readable description for Permission Matrix (non-technical readers).
+ * When `contentTitle` is present (from the template heading), it is included
+ * so the matrix row matches what users see on the screen.
+ */
+function generateScreenDescription(screenId, screenName, contentTitle) {
+  const id = String(screenId || '');
+  const entity = entityLabelFromScreenId(id);
+  const friendlyName = String(screenName || '')
+    .replace(/^I-/, '')
+    .trim();
+  const onScreen = String(contentTitle || '').trim();
+
+  const prefixes = [];
+  if (id.startsWith('dad-')) {
+    prefixes.push('DAD mock');
+  }
+  if (id.startsWith('ref-')) {
+    prefixes.push('reference data');
+  }
+  if (id.startsWith('page-')) {
+    prefixes.push('custom page');
+  }
+  if (id.startsWith('report-')) {
+    prefixes.push('report');
+  }
+
+  let viewKey = '';
+  for (const key of Object.keys(VIEW_TYPE_PHRASES)) {
+    if (id.endsWith(`-${key}`) || id === key) {
+      viewKey = key;
+      break;
+    }
+  }
+
+  const scope = prefixes.length ? `${prefixes.join(' ')} ` : '';
+  const viewPhrase = VIEW_TYPE_PHRASES[viewKey];
+  const headline = onScreen || friendlyName || entity;
+
+  if (viewPhrase) {
+    if (onScreen) {
+      return `${scope}${onScreen} — ${viewPhrase}.`;
+    }
+    return `${scope}${entity}: ${viewPhrase}.`;
+  }
+
+  if (onScreen) {
+    return `${scope}${onScreen} screen. Controls who can open and use this area.`;
+  }
+
+  if (friendlyName && friendlyName.toLowerCase() !== entity.toLowerCase()) {
+    return `${scope}${friendlyName} (${entity}) screen. Controls who can open and use this area.`;
+  }
+
+  return `${scope}${headline} screen. Controls who can open and use this area.`;
+}
+
+function indefiniteArticle(noun) {
+  const word = String(noun || '').trim();
+  return /^[aeiou]/i.test(word) ? 'an' : 'a';
+}
+
+function generateComponentDescription(componentId, componentName, componentType, screenId) {
+  if (componentType === 'SCREEN' || componentId === screenId) {
+    return generateScreenDescription(screenId, '');
+  }
+
+  const action = String(componentName || titleCaseFromSlug(componentId) || 'Action').trim();
+  const entity = entityLabelFromScreenId(screenId);
+  const article = indefiniteArticle(entity);
+  const lower = String(componentId || '').toLowerCase();
+
+  if (lower === 'create' || lower === 'add') {
+    return `Allows creating ${article} new ${entity} record.`;
+  }
+  if (lower === 'edit' || lower.startsWith('edit')) {
+    return `Allows editing an existing ${entity} record.`;
+  }
+  if (lower === 'delete' || lower.startsWith('delete') || lower.startsWith('remove')) {
+    return `Allows deleting ${article} ${entity} record.`;
+  }
+  if (lower === 'view' || lower.startsWith('view')) {
+    return `Allows viewing ${entity} details.`;
+  }
+  if (lower === 'submit' || lower === 'save') {
+    return `Allows saving changes on the ${entity} form.`;
+  }
+  if (lower === 'cancel') {
+    return `Allows cancelling and closing the ${entity} form without saving.`;
+  }
+  if (lower === 'open-filter') {
+    return `Allows opening filters for the ${entity} list.`;
+  }
+  if (lower.startsWith('export')) {
+    return `Allows exporting ${entity} data.`;
+  }
+  if (lower === 'toggle-view') {
+    return `Allows switching between table and card view for ${entity}.`;
+  }
+  if (lower === 'reset-columns') {
+    return `Allows resetting visible table columns for ${entity}.`;
+  }
+  if (lower === 'clear-filters' || lower === 'clear-field' || lower === 'close-filter') {
+    return `Allows managing filters on the ${entity} screen.`;
+  }
+
+  return `Allows the "${action}" action on the ${entity} screen.`;
+}
+
+module.exports = {
+  GENERIC_SCREEN_SEGMENTS,
+  NOISE_ACTIONS,
+  SEMANTIC_ACTION_MAP,
+  VIEW_SUFFIXES,
+  TITLE_TRAILING_NOISE,
+  GENERIC_CONTENT_TITLES,
+  CONTENT_ID_EXCLUDED_PATH_PARTS,
+  slugify,
+  isGenericContentTitle,
+  entitySegmentFromPath,
+  moduleSegmentFromPath,
+  duplicatePrimaryRank,
+  disambiguateDuplicateScreenIds,
+  camelToKebab,
+  resolveMeaningfulSegment,
+  formatScreenName,
+  formatScreenNameFromPath,
+  extractScreenContent,
+  detectViewSuffix,
+  isExcludedFromContentIds,
+  deriveContentScreenId,
+  deriveCanonicalScreenId,
+  deriveScreenId,
+  extractRawAction,
+  isNoiseAction,
+  resolveComponentId,
+  normalizeLegacyComponentId,
+  toQaId,
+  deduceComponentName,
+  deduceComponentType,
+  ensureUniqueId,
+  titleCaseFromSlug,
+  entityLabelFromScreenId,
+  generateScreenDescription,
+  generateComponentDescription,
+};