@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/lib/cli/detector/constants.mjs

@@ -0,0 +1,135 @@
+/**
+ * Static configuration sets and known-marker tables for the project context
+ * detector. Centralized so workspace traversal, UI signal analysis, and stack
+ * detection share one source of truth.
+ */
+
+import { FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES } from './design-evidence.mjs';
+
+export const WORKSPACE_SCAN_MAX_DEPTH = 3;
+export const WORKSPACE_SCAN_MAX_DIRECTORIES = 120;
+
+export const WORKSPACE_SCAN_IGNORE_DIRECTORY_NAMES = new Set([
+  ...FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES,
+  '.agent-context',
+  '.agents',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.idea',
+  '.vscode',
+  '.windsurf',
+  '.zed',
+]);
+
+export const WORKSPACE_CONTAINER_DIRECTORY_NAMES = new Set([
+  'admin', 'admins',
+  'api', 'apis',
+  'app', 'apps',
+  'backend', 'backends',
+  'client', 'clients',
+  'dashboard', 'dashboards',
+  'frontend', 'frontends',
+  'mobile', 'mobiles',
+  'package', 'packages', 'pkg',
+  'server', 'servers',
+  'service', 'services',
+  'site', 'sites',
+  'ui', 'web',
+  'worker', 'workers',
+]);
+
+export const WORKSPACE_ROOT_MARKER_FILE_NAMES = new Set([
+  'lerna.json',
+  'nx.json',
+  'pnpm-workspace.yaml',
+  'turbo.json',
+]);
+
+export const DIRECT_UI_MARKER_NAMES = [
+  'src',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+  'tailwind.config.js',
+  'tailwind.config.mjs',
+  'tailwind.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+  'react-native.config.js',
+  'app',
+  'pages',
+  'components',
+  'public',
+  'styles',
+  'android',
+  'ios',
+  'index.html',
+];
+
+export const PROJECT_MARKER_FILE_NAMES = new Set([
+  'Cargo.toml',
+  'Gemfile',
+  'build.gradle',
+  'build.gradle.kts',
+  'composer.json',
+  'go.mod',
+  'package.json',
+  'pom.xml',
+  'pubspec.yaml',
+  'pyproject.toml',
+  'react-native.config.js',
+  'requirements.txt',
+  'tsconfig.json',
+  ...DIRECT_UI_MARKER_NAMES,
+]);
+
+export const INTERNAL_GOVERNANCE_SURFACE_NAMES = new Set([
+  '.agent-context',
+  '.agent-instructions.md',
+  '.agentic-backup',
+  '.agents',
+  '.clauderc',
+  '.cursorrules',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.instructions.md',
+  '.vscode',
+  '.windsurf',
+  '.windsurfrules',
+  '.zed',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'GEMINI.md',
+  'mcp.json',
+]);
+
+const WORKSPACE_KEYWORD_FRAGMENTS = [
+  'admin', 'api', 'app', 'backend', 'client', 'dashboard',
+  'frontend', 'mobile', 'package', 'server', 'service',
+  'site', 'ui', 'web', 'worker',
+];
+
+export function looksLikeWorkspaceSearchCandidate(directoryName) {
+  const normalizedDirectoryName = String(directoryName || '').trim().toLowerCase();
+
+  if (!normalizedDirectoryName) {
+    return false;
+  }
+
+  if (WORKSPACE_CONTAINER_DIRECTORY_NAMES.has(normalizedDirectoryName)) {
+    return true;
+  }
+
+  return WORKSPACE_KEYWORD_FRAGMENTS.some((keyword) => normalizedDirectoryName.includes(keyword));
+}
+
+export function hasProjectMarkers(markerNames) {
+  return Array.from(markerNames).some((markerName) => (
+    PROJECT_MARKER_FILE_NAMES.has(markerName)
+    || markerName.endsWith('.csproj')
+    || markerName.endsWith('.sln')
+  ));
+}

package/lib/cli/detector/design-evidence/collector.mjs

@@ -0,0 +1,256 @@
+/**
+ * Top-level orchestrator for the design evidence scan. Resolves which roots to
+ * scan, walks the filesystem, and aggregates results from the inspection
+ * passes into a single summary plus a flat metrics object that downstream
+ * consumers (detector + UI rubric calibration) read.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  ANIMATION_PATTERN,
+  ARBITRARY_BREAKPOINT_PATTERN,
+  COLOR_PATTERN,
+  CSS_VARIABLE_DEFINITION_PATTERN,
+  CSS_VARIABLE_REFERENCE_PATTERN,
+  DURATION_PATTERN,
+  FONT_FAMILY_PATTERN,
+  FONT_SIZE_PATTERN,
+  FRONTEND_FILE_SCAN_LIMIT,
+  FRONTEND_FILE_SIZE_LIMIT_BYTES,
+  FRONTEND_SCAN_DIRECTORY_NAMES,
+  LETTER_SPACING_PATTERN,
+  LINE_HEIGHT_PATTERN,
+  MEDIA_QUERY_PATTERN,
+  MEDIA_WIDTH_PATTERN,
+  PROP_DRILLING_PATTERN,
+  RAW_RADIUS_PATTERN,
+  RAW_SHADOW_PATTERN,
+  RAW_SPACING_PATTERN,
+  TAILWIND_BREAKPOINT_PATTERN,
+  TRANSITION_PATTERN,
+} from './constants.mjs';
+import { collectFrontendSourceFilePaths, registerSurfaceFile } from './file-traversal.mjs';
+import { collectStructuredAttributeEvidence } from './structured-attribute-evidence.mjs';
+import { createDesignEvidenceSummary } from './summary.mjs';
+import {
+  categorizeCssVariable,
+  countPatternMatches,
+  incrementCountMap,
+  inferColorKind,
+  pushSampleValue,
+} from './utility-helpers.mjs';
+
+function resolveCandidateDirectoryPaths(targetDirectoryPath, markerNames, scanRootDirectoryPaths) {
+  const candidateDirectoryPaths = FRONTEND_SCAN_DIRECTORY_NAMES
+    .filter((directoryName) => markerNames.has(directoryName))
+    .map((directoryName) => path.join(targetDirectoryPath, directoryName));
+  const explicitScanRootDirectoryPaths = Array.isArray(scanRootDirectoryPaths)
+    ? scanRootDirectoryPaths.filter(
+      (scanRootDirectoryPath) => typeof scanRootDirectoryPath === 'string' && scanRootDirectoryPath.trim().length > 0,
+    )
+    : [];
+  if (explicitScanRootDirectoryPaths.length > 0) {
+    return Array.from(new Set(explicitScanRootDirectoryPaths));
+  }
+  if (candidateDirectoryPaths.length > 0) {
+    return candidateDirectoryPaths;
+  }
+  return [targetDirectoryPath];
+}
+
+export async function collectFrontendDesignEvidence({
+  targetDirectoryPath,
+  markerNames,
+  scanRootDirectoryPaths = [],
+}) {
+  const resolvedCandidateDirectoryPaths = resolveCandidateDirectoryPaths(
+    targetDirectoryPath,
+    markerNames,
+    scanRootDirectoryPaths,
+  );
+  const scannedFilePaths = [];
+  const scanRootRelativePaths = resolvedCandidateDirectoryPaths
+    .map((candidateDirectoryPath) => (
+      path.relative(targetDirectoryPath, candidateDirectoryPath).replace(/\\/g, '/') || '.'
+    ));
+  const designEvidenceSummary = createDesignEvidenceSummary(scanRootRelativePaths);
+  const cssVariableSamples = new Set();
+  const colorSamples = new Set();
+  const spacingSamples = new Set();
+  const radiusSamples = new Set();
+  const shadowSamples = new Set();
+  const fontFamilySamples = new Set();
+  const fontSizeSamples = new Set();
+  const lineHeightSamples = new Set();
+  const letterSpacingSamples = new Set();
+  const durationSamples = new Set();
+  const structuredClassAttributeSamples = new Set();
+  const structuredInlineStyleSamples = new Set();
+  const structuredUtilityFamilySamples = new Set();
+  const seenSurfaceFiles = new Set();
+  let hardcodedColorCount = 0;
+  let propDrillingCandidateCount = 0;
+  let mediaQueryCount = 0;
+  let tailwindBreakpointUsageCount = 0;
+  let arbitraryBreakpointCount = 0;
+  const uniqueMediaWidths = new Set();
+
+  for (const candidateDirectoryPath of resolvedCandidateDirectoryPaths) {
+    await collectFrontendSourceFilePaths(candidateDirectoryPath, scannedFilePaths);
+    if (scannedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+      break;
+    }
+  }
+
+  designEvidenceSummary.scannedFileCount = scannedFilePaths.length;
+
+  for (const scannedFilePath of scannedFilePaths) {
+    let sourceText;
+
+    try {
+      const fileStat = await fs.stat(scannedFilePath);
+      if (fileStat.size > FRONTEND_FILE_SIZE_LIMIT_BYTES) {
+        continue;
+      }
+
+      sourceText = await fs.readFile(scannedFilePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    registerSurfaceFile(designEvidenceSummary, targetDirectoryPath, scannedFilePath, seenSurfaceFiles);
+    collectStructuredAttributeEvidence(
+      sourceText,
+      designEvidenceSummary,
+      structuredClassAttributeSamples,
+      structuredInlineStyleSamples,
+      structuredUtilityFamilySamples,
+    );
+
+    for (const cssVariableMatch of sourceText.matchAll(CSS_VARIABLE_DEFINITION_PATTERN)) {
+      designEvidenceSummary.cssVariables.definitionCount += 1;
+      const variableName = cssVariableMatch[1];
+      const categoryKey = categorizeCssVariable(variableName);
+      incrementCountMap(designEvidenceSummary.cssVariables.categoryCounts, categoryKey);
+      pushSampleValue(designEvidenceSummary.cssVariables.sampleNames, variableName, cssVariableSamples);
+    }
+
+    for (const cssVariableReferenceMatch of sourceText.matchAll(CSS_VARIABLE_REFERENCE_PATTERN)) {
+      designEvidenceSummary.cssVariables.referenceCount += 1;
+      pushSampleValue(
+        designEvidenceSummary.cssVariables.sampleNames,
+        cssVariableReferenceMatch[1],
+        cssVariableSamples,
+      );
+    }
+
+    for (const colorMatch of sourceText.matchAll(COLOR_PATTERN)) {
+      const colorValue = colorMatch[0];
+      hardcodedColorCount += 1;
+      designEvidenceSummary.colors.hardcodedCount += 1;
+      incrementCountMap(designEvidenceSummary.colors.kindCounts, inferColorKind(colorValue));
+      pushSampleValue(designEvidenceSummary.colors.sampleValues, colorValue, colorSamples);
+    }
+
+    propDrillingCandidateCount += countPatternMatches(sourceText, PROP_DRILLING_PATTERN);
+    mediaQueryCount += countPatternMatches(sourceText, MEDIA_QUERY_PATTERN);
+    tailwindBreakpointUsageCount += countPatternMatches(sourceText, TAILWIND_BREAKPOINT_PATTERN);
+    arbitraryBreakpointCount += countPatternMatches(sourceText, ARBITRARY_BREAKPOINT_PATTERN);
+    designEvidenceSummary.tailwind.breakpointUsageCount += countPatternMatches(sourceText, TAILWIND_BREAKPOINT_PATTERN);
+    designEvidenceSummary.tailwind.arbitraryBreakpointCount += countPatternMatches(sourceText, ARBITRARY_BREAKPOINT_PATTERN);
+
+    for (const rawSpacingMatch of sourceText.matchAll(RAW_SPACING_PATTERN)) {
+      designEvidenceSummary.spacing.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.spacing.sampleValues, rawSpacingMatch[1], spacingSamples);
+    }
+
+    for (const rawRadiusMatch of sourceText.matchAll(RAW_RADIUS_PATTERN)) {
+      designEvidenceSummary.radius.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.radius.sampleValues, rawRadiusMatch[1], radiusSamples);
+    }
+
+    for (const rawShadowMatch of sourceText.matchAll(RAW_SHADOW_PATTERN)) {
+      designEvidenceSummary.shadow.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.shadow.sampleValues, rawShadowMatch[1], shadowSamples);
+    }
+
+    for (const fontFamilyMatch of sourceText.matchAll(FONT_FAMILY_PATTERN)) {
+      designEvidenceSummary.typography.fontFamilyCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.fontFamilySamples, fontFamilyMatch[1], fontFamilySamples);
+    }
+
+    for (const fontSizeMatch of sourceText.matchAll(FONT_SIZE_PATTERN)) {
+      designEvidenceSummary.typography.fontSizeCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.fontSizeSamples, fontSizeMatch[1], fontSizeSamples);
+    }
+
+    for (const lineHeightMatch of sourceText.matchAll(LINE_HEIGHT_PATTERN)) {
+      designEvidenceSummary.typography.lineHeightCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.lineHeightSamples, lineHeightMatch[1], lineHeightSamples);
+    }
+
+    for (const letterSpacingMatch of sourceText.matchAll(LETTER_SPACING_PATTERN)) {
+      designEvidenceSummary.typography.letterSpacingCount += 1;
+      pushSampleValue(
+        designEvidenceSummary.typography.letterSpacingSamples,
+        letterSpacingMatch[1],
+        letterSpacingSamples,
+      );
+    }
+
+    designEvidenceSummary.motion.transitionCount += countPatternMatches(sourceText, TRANSITION_PATTERN);
+    designEvidenceSummary.motion.animationCount += countPatternMatches(sourceText, ANIMATION_PATTERN);
+
+    for (const durationMatch of sourceText.matchAll(DURATION_PATTERN)) {
+      designEvidenceSummary.motion.durationCount += 1;
+      pushSampleValue(designEvidenceSummary.motion.durationSamples, durationMatch[0], durationSamples);
+    }
+
+    for (const mediaWidthMatch of sourceText.matchAll(MEDIA_WIDTH_PATTERN)) {
+      uniqueMediaWidths.add(mediaWidthMatch[1]);
+    }
+  }
+
+  designEvidenceSummary.tailwind.utilityFamilyCounts = {
+    ...designEvidenceSummary.structuredInspection.utilityFamilyCounts,
+  };
+  designEvidenceSummary.tailwind.utilityFamilySamples = [
+    ...designEvidenceSummary.structuredInspection.utilityFamilySamples,
+  ];
+
+  designEvidenceSummary.tokenBypassSignals = {
+    hardcodedColorCount: designEvidenceSummary.colors.hardcodedCount,
+    rawSpacingCount: designEvidenceSummary.spacing.rawValueCount,
+    rawRadiusCount: designEvidenceSummary.radius.rawValueCount,
+    rawShadowCount: designEvidenceSummary.shadow.rawValueCount,
+    inlineHardcodedColorCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.hardcodedColorCount,
+    inlineRawSpacingCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawSpacingCount,
+    inlineRawRadiusCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawRadiusCount,
+    inlineRawShadowCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawShadowCount,
+    inlineCssVariableReferenceCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.cssVariableReferenceCount,
+  };
+
+  return {
+    frontendEvidenceMetrics: {
+      scannedFileCount: scannedFilePaths.length,
+      hardcodedColorCount,
+      propDrillingCandidateCount,
+      mediaQueryCount,
+      tailwindBreakpointUsageCount,
+      arbitraryBreakpointCount,
+      uniqueMediaWidthCount: uniqueMediaWidths.size,
+      structuredClassAttributeCount: designEvidenceSummary.structuredInspection.classAttributeCount,
+      boundClassExpressionCount: designEvidenceSummary.structuredInspection.boundClassExpressionCount,
+      inlineStyleObjectCount: designEvidenceSummary.structuredInspection.inlineStyleObjectCount,
+      inlineStyleBindingCount: designEvidenceSummary.structuredInspection.inlineStyleBindingCount,
+      inlineStyleTokenBypassCount:
+        designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.hardcodedColorCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawSpacingCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawRadiusCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawShadowCount,
+    },
+    designEvidenceSummary,
+  };
+}

package/lib/cli/detector/design-evidence/constants.mjs

@@ -0,0 +1,39 @@
+/**
+ * Static configuration and regex patterns for the lightweight static design
+ * evidence scan. Kept in one place so the scanner internals stay pattern-driven
+ * and reviewable.
+ */
+
+export const FRONTEND_SCAN_DIRECTORY_NAMES = ['src', 'app', 'pages', 'components', 'styles'];
+export const FRONTEND_SCAN_FILE_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.vue', '.css', '.scss', '.sass',
+]);
+export const FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES = new Set([
+  '.git', 'node_modules', '.next', 'dist', 'build', 'coverage',
+]);
+export const FRONTEND_FILE_SCAN_LIMIT = 200;
+export const FRONTEND_FILE_SIZE_LIMIT_BYTES = 200_000;
+export const DESIGN_EVIDENCE_SAMPLE_LIMIT = 12;
+
+export const COLOR_PATTERN = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]+\)|hsla?\([^)]+\)|oklch\([^)]+\)/g;
+export const PROP_DRILLING_PATTERN = /<[A-Z][A-Za-z0-9_.:-]*(?:\s+[A-Za-z0-9_:-]+=\{[^}]+\}){5,}/g;
+export const MEDIA_QUERY_PATTERN = /@media\b/g;
+export const TAILWIND_BREAKPOINT_PATTERN = /\b(?:sm|md|lg|xl|2xl):/g;
+export const ARBITRARY_BREAKPOINT_PATTERN = /\b(?:min|max)-\[[^\]]+\]:/g;
+export const CSS_VARIABLE_DEFINITION_PATTERN = /--([a-zA-Z0-9-_]+)\s*:/g;
+export const CSS_VARIABLE_REFERENCE_PATTERN = /var\(--([a-zA-Z0-9-_]+)\)/g;
+export const RAW_SPACING_PATTERN = /\b(?:margin|padding|gap|column-gap|row-gap|min-width|max-width|min-height|max-height|width|height|top|right|bottom|left|inset|spaceBetween|paddingInline|paddingBlock|marginInline|marginBlock|gapX|gapY|spaceX|spaceY)\b[^;\n:]*[:=]\s*['"`{(]*(-?[0-9.]+(?:px|rem|em|vh|vw))/gi;
+export const RAW_RADIUS_PATTERN = /\b(?:border-radius|borderRadius)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em)|9999px)/gi;
+export const RAW_SHADOW_PATTERN = /\b(?:box-shadow|boxShadow)\b[^;\n:]*[:=]\s*['"`{(]*([^;\n}]+)/gi;
+export const FONT_FAMILY_PATTERN = /\b(?:font-family|fontFamily)\b[^;\n:]*[:=]\s*['"`{(]*([^;\n}]+)/gi;
+export const FONT_SIZE_PATTERN = /\b(?:font-size|fontSize)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em))/gi;
+export const LINE_HEIGHT_PATTERN = /\b(?:line-height|lineHeight)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em)?)/gi;
+export const LETTER_SPACING_PATTERN = /\b(?:letter-spacing|letterSpacing)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.-]+(?:px|rem|em))/gi;
+export const TRANSITION_PATTERN = /\btransition(?:-[a-z]+)?\b/g;
+export const ANIMATION_PATTERN = /\banimation(?:-[a-z]+)?\b/g;
+export const DURATION_PATTERN = /\b\d+(?:\.\d+)?m?s\b/g;
+export const MEDIA_WIDTH_PATTERN = /\((?:min|max)-width:\s*([0-9.]+(?:px|rem|em))\)/g;
+export const STRING_CLASS_ATTRIBUTE_PATTERN = /\b(?:className|class)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\}|\{"([^"]*)"\}|\{'([^']*)'\})/g;
+export const EXPRESSION_CLASS_ATTRIBUTE_PATTERN = /\b(?:className|class|:class)\s*=\s*\{([^}\n]+)\}/g;
+export const JSX_INLINE_STYLE_PATTERN = /\bstyle\s*=\s*\{\{([\s\S]*?)\}\}/g;
+export const VUE_INLINE_STYLE_PATTERN = /\b:style\s*=\s*["']\{([^"']*)\}["']/g;

package/lib/cli/detector/design-evidence/file-traversal.mjs

@@ -0,0 +1,83 @@
+/**
+ * Filesystem traversal and surface-file classification for the design evidence
+ * scan. Bounded by FRONTEND_FILE_SCAN_LIMIT so the scan never blows up on huge
+ * monorepos.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  DESIGN_EVIDENCE_SAMPLE_LIMIT,
+  FRONTEND_FILE_SCAN_LIMIT,
+  FRONTEND_SCAN_FILE_EXTENSIONS,
+  FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES,
+} from './constants.mjs';
+
+export async function collectFrontendSourceFilePaths(directoryPath, collectedFilePaths = []) {
+  if (collectedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+    return collectedFilePaths;
+  }
+
+  let directoryEntries;
+  try {
+    directoryEntries = await fs.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return collectedFilePaths;
+  }
+
+  for (const directoryEntry of directoryEntries) {
+    if (collectedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+      break;
+    }
+
+    if (directoryEntry.isDirectory()) {
+      if (FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES.has(directoryEntry.name)) {
+        continue;
+      }
+
+      await collectFrontendSourceFilePaths(path.join(directoryPath, directoryEntry.name), collectedFilePaths);
+      continue;
+    }
+
+    const fileExtension = path.extname(directoryEntry.name).toLowerCase();
+    if (FRONTEND_SCAN_FILE_EXTENSIONS.has(fileExtension)) {
+      collectedFilePaths.push(path.join(directoryPath, directoryEntry.name));
+    }
+  }
+
+  return collectedFilePaths;
+}
+
+export function registerSurfaceFile(summary, targetDirectoryPath, scannedFilePath, seenSurfaceFiles) {
+  const relativeFilePath = path.relative(targetDirectoryPath, scannedFilePath).replace(/\\/g, '/');
+  const normalizedBaseName = path.basename(scannedFilePath, path.extname(scannedFilePath)).toLowerCase();
+  const looksLikeComponent = /[A-Z]/.test(path.basename(scannedFilePath, path.extname(scannedFilePath)))
+    || relativeFilePath.includes('/components/')
+    || relativeFilePath.startsWith('components/');
+  const looksLikePage = normalizedBaseName === 'page'
+    || normalizedBaseName === 'index'
+    || relativeFilePath.includes('/pages/')
+    || relativeFilePath.startsWith('pages/')
+    || relativeFilePath.includes('/app/');
+  const looksLikeLayout = normalizedBaseName === 'layout' || relativeFilePath.includes('/layouts/');
+
+  if (looksLikeComponent) {
+    summary.componentInventory.componentFileCount += 1;
+  }
+
+  if (looksLikePage) {
+    summary.componentInventory.pageFileCount += 1;
+  }
+
+  if (looksLikeLayout) {
+    summary.componentInventory.layoutFileCount += 1;
+  }
+
+  if ((looksLikeComponent || looksLikePage || looksLikeLayout) && !seenSurfaceFiles.has(relativeFilePath)) {
+    seenSurfaceFiles.add(relativeFilePath);
+    if (summary.componentInventory.surfaceFileSamples.length < DESIGN_EVIDENCE_SAMPLE_LIMIT) {
+      summary.componentInventory.surfaceFileSamples.push(relativeFilePath);
+    }
+  }
+}

package/lib/cli/detector/design-evidence/structured-attribute-evidence.mjs

@@ -0,0 +1,117 @@
+/**
+ * Structured attribute-aware inspection: counts class attributes, bound class
+ * expressions, JSX/Vue inline styles, and Tailwind utility families seen in the
+ * source. These metrics complement the raw regex pass with a structurally
+ * aware view that better matches modern frontend authorship patterns.
+ */
+
+import {
+  COLOR_PATTERN,
+  CSS_VARIABLE_REFERENCE_PATTERN,
+  EXPRESSION_CLASS_ATTRIBUTE_PATTERN,
+  JSX_INLINE_STYLE_PATTERN,
+  RAW_RADIUS_PATTERN,
+  RAW_SHADOW_PATTERN,
+  RAW_SPACING_PATTERN,
+  STRING_CLASS_ATTRIBUTE_PATTERN,
+  VUE_INLINE_STYLE_PATTERN,
+} from './constants.mjs';
+import {
+  countPatternMatches,
+  getFirstDefinedCapture,
+  incrementCountMap,
+  inferUtilityFamily,
+  normalizeEvidenceSample,
+  pushSampleValue,
+} from './utility-helpers.mjs';
+
+function collectTailwindUtilityFamilies(classValue, utilityFamilyCounts, utilityFamilySamples, utilityFamilySampleSet) {
+  for (const utilityToken of String(classValue || '').split(/\s+/g)) {
+    const utilityFamily = inferUtilityFamily(utilityToken);
+    if (!utilityFamily) {
+      continue;
+    }
+
+    incrementCountMap(utilityFamilyCounts, utilityFamily);
+    pushSampleValue(utilityFamilySamples, utilityFamily, utilityFamilySampleSet);
+  }
+}
+
+function applyInlineStyleInspection(styleSourceText, summary, styleSampleSet) {
+  const normalizedStyleSource = normalizeEvidenceSample(styleSourceText);
+  pushSampleValue(summary.structuredInspection.inlineStyleSamples, normalizedStyleSource, styleSampleSet);
+
+  const hardcodedColorCount = countPatternMatches(styleSourceText, COLOR_PATTERN);
+  const rawSpacingCount = countPatternMatches(styleSourceText, RAW_SPACING_PATTERN);
+  const rawRadiusCount = countPatternMatches(styleSourceText, RAW_RADIUS_PATTERN);
+  const rawShadowCount = countPatternMatches(styleSourceText, RAW_SHADOW_PATTERN);
+  const cssVariableReferenceCount = countPatternMatches(styleSourceText, CSS_VARIABLE_REFERENCE_PATTERN);
+
+  summary.structuredInspection.inlineTokenBypassSignals.hardcodedColorCount += hardcodedColorCount;
+  summary.structuredInspection.inlineTokenBypassSignals.rawSpacingCount += rawSpacingCount;
+  summary.structuredInspection.inlineTokenBypassSignals.rawRadiusCount += rawRadiusCount;
+  summary.structuredInspection.inlineTokenBypassSignals.rawShadowCount += rawShadowCount;
+  summary.structuredInspection.inlineTokenBypassSignals.cssVariableReferenceCount += cssVariableReferenceCount;
+}
+
+export function collectStructuredAttributeEvidence(
+  sourceText,
+  summary,
+  classSampleSet,
+  styleSampleSet,
+  utilityFamilySampleSet,
+) {
+  for (const classAttributeMatch of sourceText.matchAll(STRING_CLASS_ATTRIBUTE_PATTERN)) {
+    const classValue = getFirstDefinedCapture(classAttributeMatch.slice(1));
+    if (!classValue) {
+      continue;
+    }
+
+    summary.structuredInspection.classAttributeCount += 1;
+    pushSampleValue(
+      summary.structuredInspection.classAttributeSamples,
+      normalizeEvidenceSample(classValue),
+      classSampleSet,
+    );
+    collectTailwindUtilityFamilies(
+      classValue,
+      summary.structuredInspection.utilityFamilyCounts,
+      summary.structuredInspection.utilityFamilySamples,
+      utilityFamilySampleSet,
+    );
+  }
+
+  for (const expressionClassAttributeMatch of sourceText.matchAll(EXPRESSION_CLASS_ATTRIBUTE_PATTERN)) {
+    const expressionValue = getFirstDefinedCapture(expressionClassAttributeMatch.slice(1));
+    if (!expressionValue) {
+      continue;
+    }
+
+    summary.structuredInspection.boundClassExpressionCount += 1;
+    pushSampleValue(
+      summary.structuredInspection.classAttributeSamples,
+      normalizeEvidenceSample(expressionValue),
+      classSampleSet,
+    );
+  }
+
+  for (const inlineStyleMatch of sourceText.matchAll(JSX_INLINE_STYLE_PATTERN)) {
+    const inlineStyleSource = getFirstDefinedCapture(inlineStyleMatch.slice(1));
+    if (!inlineStyleSource) {
+      continue;
+    }
+
+    summary.structuredInspection.inlineStyleObjectCount += 1;
+    applyInlineStyleInspection(inlineStyleSource, summary, styleSampleSet);
+  }
+
+  for (const vueInlineStyleMatch of sourceText.matchAll(VUE_INLINE_STYLE_PATTERN)) {
+    const inlineStyleSource = getFirstDefinedCapture(vueInlineStyleMatch.slice(1));
+    if (!inlineStyleSource) {
+      continue;
+    }
+
+    summary.structuredInspection.inlineStyleBindingCount += 1;
+    applyInlineStyleInspection(inlineStyleSource, summary, styleSampleSet);
+  }
+}