@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/scripts/scan-nextjs.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * scan-nextjs.mjs - CLI scan for Next.js violations.
+ * Usage: node scripts/scan-nextjs.mjs [path] [--json]
+ * Exit: 0=clean, 1=errors, 2=scan failed
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateNextComponent } from '../src/lib/validators/nextjs/next-component-validator.js';
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const pathArg = args.find(a => !a.startsWith('--'));
+const targetPath = pathArg ? resolve(pathArg) : resolve('src');
+
+function checkUseEffectFetch(content, filePath) {
+  const issues = [];
+  if (/useEffect\s*\(\s*(?:async\s+)?\(\s*\)\s*=>/.test(content) && /\bfetch\s*\(/.test(content)) {
+    issues.push({
+      type: 'error',
+      message: "useEffect used for data fetching — use Server Components or TanStack Query (useQuery) instead",
+      suggestion: "Replace with a Server Component fetch or TanStack Query useQuery hook",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+function checkDefaultExport(content, filePath) {
+  const issues = [];
+  const fileName = filePath.split('/').pop() ?? '';
+  const SPECIAL = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx'];
+  if (!SPECIAL.includes(fileName) && /^export\s+default\s+/m.test(content) && fileName.endsWith('.tsx')) {
+    issues.push({
+      type: 'warning',
+      message: `Default export in '${fileName}' — prefer named exports for easier refactoring`,
+      suggestion: "Change to: export function ComponentName() {}",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+function findTsxFiles(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (['node_modules', '.next', 'dist', '.git'].includes(entry.name)) continue;
+    if (entry.isDirectory()) {
+      results.push(...findTsxFiles(fullPath));
+    } else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function main() {
+  if (!existsSync(targetPath)) {
+    const msg = `Error: Path does not exist: ${targetPath}`;
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: msg, exitCode: 2 }));
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  let files;
+  try {
+    files = findTsxFiles(targetPath);
+  } catch (err) {
+    const msg = `Error scanning directory: ${err.message}`;
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: msg, exitCode: 2 }));
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  const normalizedTarget = targetPath.replace(/\\/g, '/');
+
+  const allIssues = [];
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    const normalizedFile = filePath.replace(/\\/g, '/');
+    const relPath = normalizedFile.startsWith(normalizedTarget)
+      ? normalizedFile.slice(normalizedTarget.length).replace(/^\//, '')
+      : normalizedFile;
+
+    const issues = [
+      ...validateNextComponent(content, relPath),
+      ...checkUseEffectFetch(content, relPath),
+      ...checkDefaultExport(content, relPath),
+    ];
+    allIssues.push(...issues);
+  }
+
+  const errors = allIssues.filter(i => i.type === 'error');
+  const warnings = allIssues.filter(i => i.type === 'warning');
+
+  if (jsonMode) {
+    const out = JSON.stringify({
+      files: files.length,
+      issues: allIssues.map(i => ({
+        severity: i.type,
+        message: i.message,
+        file: i.file,
+        line: i.line ?? null,
+        suggestion: i.suggestion ?? null,
+      })),
+      errors: errors.length,
+      warnings: warnings.length,
+      exitCode: errors.length > 0 ? 1 : 0,
+    }, null, 2);
+    process.stdout.write(out + '\n');
+    process.exit(errors.length > 0 ? 1 : 0);
+  }
+
+  const displayPath = targetPath.replace(process.cwd().replace(/\\/g, '/'), '.').replace(/\\/g, '/');
+  console.log(`🔍 Scanning ${displayPath} (${files.length} file${files.length !== 1 ? "s" : ""})...`);
+  console.log("");
+
+  if (allIssues.length === 0) {
+    console.log(`✅ No issues found — ${files.length} file${files.length !== 1 ? "s" : ""} scanned`);
+    console.log(`Summary: ${files.length} files scanned | 0 issues (0 critical, 0 high, 0 medium)`);
+    process.exit(0);
+  }
+
+  if (errors.length > 0) {
+    console.log(`CRITICAL (${errors.length})`);
+    for (const issue of errors) {
+      const loc = issue.line ? `:${issue.line}` : "";
+      console.log(`  ${issue.file}${loc}  — ${issue.message}`);
+      if (issue.suggestion) console.log(`    → ${issue.suggestion}`);
+    }
+    console.log('');
+  }
+
+  if (warnings.length > 0) {
+    console.log(`HIGH/MEDIUM (${warnings.length})`);
+    for (const issue of warnings) {
+      console.log(`  ${issue.file}  — ${issue.message}`);
+    }
+    console.log('');
+  }
+
+  const cleanFiles = files.length - new Set(allIssues.map(i => i.file)).size;
+  if (cleanFiles > 0) {
+    console.log(`✅ No issues found in ${cleanFiles} file${cleanFiles !== 1 ? "s" : ""}`);
+  }
+
+  console.log(`Summary: ${files.length} files scanned | ${allIssues.length} issue${allIssues.length !== 1 ? "s" : ""} (${errors.length} critical, ${warnings.length} high/medium)`);
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();

package/src/commands/project/doctor.js

@@ -411,7 +411,58 @@ export async function doctorCommand(options = {}) {
   // Check agents.json
   const agentsPath = join(morphPath, 'framework', 'agents.json');
   if (await pathExists(agentsPath)) {
-    checks.push({ name: 'agents.json', status: 'ok' });
+    try {
+      const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const agentEntries = Object.entries(agentsData.agents || {})
+        .filter(([k]) => !k.startsWith('_comment'));
+      const actualCount = agentEntries.length;
+      const declaredCount = agentsData.total_agents;
+
+      // Check 1: total_agents matches actual count
+      if (actualCount !== declaredCount) {
+        checks.push({
+          name: 'agents.json count',
+          status: 'warn',
+          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
+        });
+        hasWarnings = true;
+      } else {
+        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
+      }
+
+      // Check 2: required tier-2 agents present
+      const requiredTier2 = ['standards-architect', 'dotnet-senior', 'infra-architect', 'domain-architect'];
+      const missingTier2 = requiredTier2.filter(id => !agentsData.agents[id]);
+      if (missingTier2.length > 0) {
+        checks.push({
+          name: 'agents.json required agents',
+          status: 'error',
+          msg: `Missing required agents: ${missingTier2.join(', ')}`
+        });
+        hasErrors = true;
+      } else {
+        checks.push({ name: 'agents.json required agents', status: 'ok' });
+      }
+
+      // Check 3: tier counts sum matches total
+      const tierCounts = [1, 2, 3, 4].map(t =>
+        agentEntries.filter(([, v]) => v.tier === t).length
+      );
+      const tierSum = tierCounts.reduce((a, b) => a + b, 0);
+      if (tierSum !== actualCount) {
+        checks.push({
+          name: 'agents.json tier counts',
+          status: 'warn',
+          msg: `Tier counts sum to ${tierSum} but total is ${actualCount}`
+        });
+        hasWarnings = true;
+      } else {
+        checks.push({ name: 'agents.json tier counts', status: 'ok' });
+      }
+    } catch {
+      checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
   } else {
     checks.push({ name: 'agents.json', status: 'missing' });
     hasErrors = true;

package/src/commands/project/init.js

@@ -4,7 +4,6 @@ import ora from 'ora';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import {
-  getContentDir,
   copyDirectory,
   copyFile,
   pathExists,
@@ -13,9 +12,7 @@ import {
   ensureDir,
   writeFile,
   readFile,
-  updateGitignore,
-  createSymlink,
-  createDirectoryLink
+  updateGitignore
 } from '../../utils/file-copier.js';
 import { saveProjectMorphVersion, getInstalledCLIVersion } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
@@ -122,7 +119,6 @@ Run \`morph-spec detect\` to analyze your project.
     await writeFile(contextReadme, readmeContent);
 
     // 5. Copy framework templates (project-local overrides start from framework defaults)
-    const contentDir = getContentDir();
     const frameworkTemplatesSrc = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
     const templatesDest = join(frameworkDestDir, 'templates');
     let templatesCopied = false;
@@ -151,14 +147,12 @@ Run \`morph-spec detect\` to analyze your project.
       await copyFile(agentsSrc, agentsDest);
     }
 
-    // 8. Copy .claude commands and create symlinks for skills
+    // 8. Copy .claude commands and install skills
     // Source: framework/ (canonical for all stacks)
     spinner.text = 'Setting up Claude Code integration...';
     const frameworkDir = join(import.meta.dirname, '..', '..', '..', 'framework');
     const claudeDest = join(targetPath, '.claude');
 
-    let symlinkCount = 0;
-    let copyCount = 0;
     let commandsCopied = false;
 
     // Copy commands directory (slash commands): framework/commands/ → .claude/commands/
@@ -171,55 +165,6 @@ Run \`morph-spec detect\` to analyze your project.
       logger.warn('  ⚠ framework/commands/ source missing — commands not installed');
     }
 
-    // Create directory links for skill categories (or copy if linking fails)
-    // Source: framework/skills/ → .claude/skills/
-    {
-      const skillsSrc = join(frameworkDir, 'skills');
-      const skillsDest = join(claudeDest, 'skills');
-
-      if (await pathExists(skillsSrc)) {
-        await ensureDir(skillsDest);
-
-        const entries = await fs.readdir(skillsSrc, { withFileTypes: true });
-
-        let linkedCategories = 0;
-        let copiedCategories = 0;
-        let totalSkillFiles = 0;
-
-        // Link category directories (specialists/, infra/, checklists/, etc.)
-        for (const entry of entries) {
-          if (entry.isDirectory()) {
-            const categorySrc = join(skillsSrc, entry.name);
-            const categoryDest = join(skillsDest, entry.name);
-
-            // Count .md files for reporting
-            const categoryEntries = await fs.readdir(categorySrc, { withFileTypes: true });
-            const mdFiles = categoryEntries.filter(e => e.isFile() && e.name.endsWith('.md'));
-            totalSkillFiles += mdFiles.length;
-
-            const result = await createDirectoryLink(categorySrc, categoryDest);
-            if (result === 'copy') {
-              copiedCategories++;
-            } else {
-              linkedCategories++;
-            }
-          } else if (entry.isFile() && entry.name.endsWith('.md')) {
-            // Handle .md files in skills root
-            totalSkillFiles++;
-            const result = await createSymlink(join(skillsSrc, entry.name), join(skillsDest, entry.name), 'file');
-            if (result === 'symlink') {
-              linkedCategories++;
-            } else {
-              copiedCategories++;
-            }
-          }
-        }
-
-        symlinkCount = linkedCategories > 0 ? totalSkillFiles : 0;
-        copyCount = linkedCategories === 0 ? totalSkillFiles : 0;
-      }
-    }
-
     // 9a. Install path-scoped rules to .claude/rules/ (native Claude Code pattern)
     spinner.text = 'Installing path-scoped rules to .claude/rules/...';
     const rulesSrc = join(frameworkDir, 'rules');
@@ -236,7 +181,8 @@ Run \`morph-spec detect\` to analyze your project.
 
     // 9b2. Install tier-1/2 agents as native Claude Code subagents in .claude/agents/
     spinner.text = 'Installing native subagents to .claude/agents/...';
-    await installAgents(targetPath, frameworkDir);
+    const detectedStackForAgents = config.project.stack ?? null;
+    await installAgents(targetPath, frameworkDir, { projectStack: detectedStackForAgents });
 
     // 9b2b. Install level-2 domain agents as native Claude Code subagents in .claude/agents/
     await installDomainAgents(targetPath, frameworkDir);
@@ -341,6 +287,19 @@ Run \`morph-spec detect\` to analyze your project.
 
         if (structure?.stack && structure.stack !== 'unknown') {
           detectedStack = structure.stack;
+
+          // Persist detected stack to config.json
+          if (structure?.stack && structure.stack !== 'unknown') {
+            config.project.stack = structure.stack;
+          }
+          if (structure?.architecture && structure.architecture !== 'unknown') {
+            config.project.architecture = structure.architecture;
+          }
+          if (structure?.uiLibrary) {
+            config.project.uiLibrary = structure.uiLibrary;
+          }
+          await writeJson(configPath, config);
+
           spinner.stop();
           logger.blank();
           logger.header('Existing Project Detected');
@@ -542,13 +501,8 @@ Run \`morph-spec detect\` to analyze your project.
       }
     }
 
-    if (symlinkCount > 0) {
-      const linkType = process.platform === 'win32' ? 'junction-linked' : 'symlinked';
-      logger.dim(`  ✓ .claude/skills/ (${symlinkCount} ${linkType})`);
-    } else if (copyCount > 0) {
-      logger.dim(`  ✓ .claude/skills/ (${copyCount} copied)`);
-      logger.warn(`  ⚠ Directory links not supported (copied instead). Skills won't auto-update.`);
-    }
+    logger.dim('  ✓ .claude/skills/ (installed as skill directories)');
+    logger.dim('  ✓ .claude/agents/ (native subagents installed)');
 
     logger.blank();
 

package/src/commands/project/update.js

@@ -14,8 +14,6 @@ import {
   copyFile,
   pathExists,
   ensureDir,
-  createDirectoryLink,
-  createSymlink,
   readJson,
   writeJson
 } from '../../utils/file-copier.js';
@@ -239,8 +237,6 @@ export async function updateCommand(options) {
     const frameworkDir = join(__dirname, '..', '..', '..', 'framework');
     const claudeDest = join(targetPath, '.claude');
 
-    let symlinkCount = 0;
-    let copyCount = 0;
     let commandsCopied = false;
 
     // Copy commands directory (slash commands): framework/commands/ → .claude/commands/
@@ -253,62 +249,18 @@ export async function updateCommand(options) {
       logger.warn('  ⚠ framework/commands/ source missing — commands not updated');
     }
 
-    // Create directory links for skill categories (or copy if linking fails)
-    // Source: framework/skills/ → .claude/skills/
-    {
-      const skillsSrc = join(frameworkDir, 'skills');
-      const skillsDest = join(claudeDest, 'skills');
-
-      if (await pathExists(skillsSrc)) {
-        await ensureDir(skillsDest);
-
-        const entries = await fs.readdir(skillsSrc, { withFileTypes: true });
-
-        let linkedCategories = 0;
-        let copiedCategories = 0;
-        let totalSkillFiles = 0;
-
-        // Link category directories (specialists/, infra/, checklists/, etc.)
-        for (const entry of entries) {
-          if (entry.isDirectory()) {
-            const categorySrc = join(skillsSrc, entry.name);
-            const categoryDest = join(skillsDest, entry.name);
-
-            // Count .md files for reporting
-            const categoryEntries = await fs.readdir(categorySrc, { withFileTypes: true });
-            const mdFiles = categoryEntries.filter(e => e.isFile() && e.name.endsWith('.md'));
-            totalSkillFiles += mdFiles.length;
-
-            const result = await createDirectoryLink(categorySrc, categoryDest);
-            if (result === 'copy') {
-              copiedCategories++;
-            } else {
-              linkedCategories++;
-            }
-          } else if (entry.isFile() && entry.name.endsWith('.md')) {
-            // Handle .md files in skills root
-            totalSkillFiles++;
-            const result = await createSymlink(join(skillsSrc, entry.name), join(skillsDest, entry.name), 'file');
-            if (result === 'symlink') {
-              linkedCategories++;
-            } else {
-              copiedCategories++;
-            }
-          }
-        }
-
-        symlinkCount = linkedCategories > 0 ? totalSkillFiles : 0;
-        copyCount = linkedCategories === 0 ? totalSkillFiles : 0;
-      }
-    }
-
     // Sync morph skills to .claude/skills/ for native Claude Code discovery
     updateSpinner.text = 'Syncing morph skills to .claude/skills/...';
     await installSkills(targetPath);
 
     // Sync native subagents to .claude/agents/
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
-    await installAgents(targetPath, frameworkDir);
+    let projectStack = null;
+    try {
+      const cfg = await readJson(join(morphPath, 'config', 'config.json'));
+      projectStack = cfg?.project?.stack ?? null;
+    } catch { /* ignore — config may not exist yet */ }
+    await installAgents(targetPath, frameworkDir, { projectStack });
     await installDomainAgents(targetPath, frameworkDir);
 
     // Sync path-scoped rules to .claude/rules/
@@ -365,16 +317,8 @@ export async function updateCommand(options) {
     logger.dim('  ✓ .morph/framework/agents.json');
     if (commandsCopied) logger.dim('  ✓ .claude/commands/');
 
-    if (symlinkCount > 0) {
-      const linkType = process.platform === 'win32' ? 'junction-linked' : 'symlinked';
-      logger.dim(`  ✓ .claude/skills/ (${symlinkCount} ${linkType})`);
-    } else if (copyCount > 0) {
-      logger.dim(`  ✓ .claude/skills/ (${copyCount} copied)`);
-      logger.warn(`  ⚠ Directory links not supported (copied instead). Skills won't auto-update.`);
-    }
-
     logger.dim(`  ✓ .claude/settings.local.json (${hooksResult.installed} hooks installed)`);
-    logger.dim('  ✓ .claude/skills/ (flat .md for /skill-name discovery)');
+    logger.dim('  ✓ .claude/skills/ (skills installed as directories)');
     logger.dim('  ✓ .claude/agents/ (native subagents refreshed)');
     logger.dim('  ✓ .claude/rules/ (path-scoped rules synced)');
     logger.dim('  ✓ .claude/CLAUDE.md (runtime quick reference)');

package/src/lib/detectors/claude-config-detector.js

@@ -144,9 +144,7 @@ function detectCustomSkills(globalClaudeDir, projectClaudeDir) {
     for (const file of walkMdFiles(projectSkills)) {
       const name = extractSkillName(file);
       // Skip morph-spec framework skills (they're managed by init)
-      if (file.includes('level-0-meta') || file.includes('level-1-workflows') ||
-          file.includes('level-2-domains') || file.includes('level-3-technologies') ||
-          file.includes('level-4-patterns')) {
+      if (file.includes('level-0-meta') || file.includes('level-1-workflows')) {
         continue;
       }
       skills.push({

package/src/lib/standards/standards-context-injector.js

@@ -44,6 +44,11 @@ const AGENT_STANDARDS_MAP = {
     'backend/database/ef-core',
     'backend/api/rest'
   ],
+  'infra-architect': [
+    'core/architecture',
+    'core/coding'
+  ],
+  // Tier 3: Specialists - Infrastructure Squad
   'azure-architect': [
     'infrastructure/azure/azure', // Stack-specific
     'core/architecture',

package/src/lib/validators/nextjs/index.js

@@ -0,0 +1,6 @@
+/**
+ * Next.js Validators
+ *
+ * Validators specific to Next.js App Router patterns.
+ */
+export { validateNextComponent, validateNextComponentFiles } from './next-component-validator.js';

package/src/lib/validators/nextjs/next-component-validator.js

@@ -0,0 +1,181 @@
+import { glob } from 'glob';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Next.js Component Validator
+ *
+ * Validates .tsx files for:
+ * 1. Unnecessary 'use client' directives (no interactivity)
+ * 2. Missing 'use client' when React hooks are used
+ * 3. File naming convention (kebab-case)
+ *
+ * @module next-component-validator
+ */
+
+// ============================================
+// CONSTANTS
+// ============================================
+
+/** Hooks/patterns that require 'use client' */
+const CLIENT_HOOKS = ['useState', 'useEffect', 'useRef', 'useReducer', 'useCallback', 'useMemo', 'useContext'];
+
+/** Event handler patterns that indicate interactivity (hooks are checked via CLIENT_HOOKS) */
+const EVENT_HANDLER_PATTERNS = [
+  /\bonClick\b/,
+  /\bonChange\b/,
+  /\bonSubmit\b/,
+  /\bonFocus\b/,
+  /\bonBlur\b/,
+  /\bonKeyDown\b/,
+];
+
+/** Next.js special files exempt from naming checks */
+const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
+
+// ============================================
+// MAIN VALIDATION FUNCTION
+// ============================================
+
+/**
+ * @typedef {Object} ValidationIssue
+ * @property {'error' | 'warning' | 'info'} type
+ * @property {string} message
+ * @property {string} [suggestion]
+ * @property {string} file
+ * @property {number} [line]
+ */
+
+/**
+ * Validates a Next.js component file.
+ *
+ * @param {string} content - File content
+ * @param {string} filePath - Relative file path
+ * @returns {ValidationIssue[]}
+ */
+export function validateNextComponent(content, filePath) {
+  const issues = [];
+
+  // Only validate .tsx and .ts files
+  if (!filePath.endsWith('.tsx') && !filePath.endsWith('.ts')) {
+    return issues;
+  }
+
+  // Skip non-component utility files (no JSX, no hooks)
+  const hasJsx = /(?<![a-zA-Z0-9])<[A-Z][a-zA-Z]*[\s/>]|(?<![a-zA-Z0-9])<[a-z][a-z]+[\s>/]/.test(content);
+  const hasHooks = CLIENT_HOOKS.some(hook => content.includes(hook));
+
+  if (!hasJsx && !hasHooks) {
+    return issues;
+  }
+
+  const hasUseClient = /^'use client';?|^"use client";?/.test(content.trimStart());
+
+  // Check 1: use client present but no interactivity
+  if (hasUseClient) {
+    const hasEventHandlers = EVENT_HANDLER_PATTERNS.some(pattern => pattern.test(content));
+    const hasClientHooks = CLIENT_HOOKS.some(hook => new RegExp(`\\b${hook}\\b`).test(content));
+    if (!hasEventHandlers && !hasClientHooks) {
+      issues.push({
+        type: 'warning',
+        message: "'use client' directive present but no interactivity detected (no hooks, no event handlers)",
+        suggestion: "Remove 'use client' to make this a Server Component, or add interactive behavior",
+        file: filePath,
+      });
+    }
+  }
+
+  // Check 2: hooks used without use client
+  if (!hasUseClient) {
+    const usedHooks = CLIENT_HOOKS.filter(hook => new RegExp(`\\b${hook}\\b`).test(content));
+    if (usedHooks.length > 0) {
+      issues.push({
+        type: 'error',
+        message: `React hook(s) used (${usedHooks.join(', ')}) without 'use client' directive`,
+        suggestion: "Add 'use client' as the first line of the file",
+        file: filePath,
+        line: 1,
+      });
+    }
+  }
+
+  // Check 3: file naming convention (kebab-case)
+  const fileName = filePath.split('/').pop() ?? '';
+  const isSpecialFile = NEXTJS_SPECIAL_FILES.includes(fileName);
+
+  if (!isSpecialFile && fileName.endsWith('.tsx')) {
+    const baseName = fileName.replace('.tsx', '');
+    const hasUpperCase = /[A-Z]/.test(baseName);
+    if (hasUpperCase) {
+      issues.push({
+        type: 'warning',
+        message: `Component file '${fileName}' should use kebab-case naming`,
+        suggestion: `Rename to '${toKebabCase(baseName)}.tsx'`,
+        file: filePath,
+      });
+    }
+  }
+
+  return issues;
+}
+
+// ============================================
+// HELPERS
+// ============================================
+
+function toKebabCase(str) {
+  return str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+
+// ============================================
+// PROJECT-LEVEL SCANNER
+// ============================================
+
+/**
+ * Validates all Next.js component files in a project directory.
+ * Wraps validateNextComponent for use in validation-runner.js.
+ *
+ * @param {string} projectPath - Root path of the project
+ * @param {Object} _options - Validator options (unused, for interface compatibility)
+ * @returns {Promise<{ errors: number, warnings: number, issues: Array }>}
+ */
+export async function validateNextComponentFiles(projectPath, _options = {}) {
+  const result = { errors: 0, warnings: 0, issues: [] };
+
+  // Find all .tsx and .ts files under src/
+  const srcDir = join(projectPath, 'src');
+  const normalizedSrc = srcDir.replace(/\\/g, '/');
+  const pattern = normalizedSrc + '/**/*.{tsx,ts}';
+  const files = await glob(pattern, { ignore: ['**/node_modules/**', '**/.next/**'] });
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    // Make path relative for cleaner output
+    const normFilePath = filePath.replace(/\\/g, '/');
+    const relPath = normFilePath.replace(projectPath.replace(/\\/g, '/') + '/', '');
+    const fileIssues = validateNextComponent(content, relPath);
+
+    for (const issue of fileIssues) {
+      result.issues.push({
+        level: issue.type,
+        message: issue.message,
+        file: issue.file,
+        line: issue.line,
+        solution: issue.suggestion,
+      });
+      if (issue.type === 'error') result.errors++;
+      else if (issue.type === 'warning') result.warnings++;
+    }
+  }
+
+  return result;
+}