@rtl-first/audit 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @rtl-first/audit
+
+Scan any project for RTL readiness across the [five layers of RTL support](../../docs/for-contributors/methodology.md).
+
+## Usage
+
+```bash
+npx @rtl-first/audit ./my-project
+```
+
+## What it checks
+
+| Layer | What it scans | How |
+|-------|--------------|-----|
+| **1 — Text engine** | Rich-text editors (ProseMirror, Slate, etc.) | Checks package.json dependencies |
+| **2 — Direction logic** | `dir="rtl"`, DirectionProvider | Scans .ts/.tsx/.html files |
+| **3 — CSS layout** | Physical CSS properties | Counts margin-left, padding-right, etc. |
+| **4 — Translations** | ar.json existence and completeness | Compares with en.json |
+| **5 — Hardcoded text** | English strings in JSX | Scans .tsx/.jsx files |
+
+## Output
+
+```
+RTL Audit Report — my-project
+═══════════════════════════════════════
+
+Layer 1 — Text engine         ✅ No rich-text editor detected
+Layer 2 — Direction logic     ❌ No dir="rtl" on document root
+Layer 3 — CSS layout          ⚠️  423 files use physical properties
+Layer 4 — Translations        ⚠️  ar.json not found (en.json: 1,660 keys)
+Layer 5 — Hardcoded text      ❌ 89 hardcoded English strings in JSX
+
+RTL Readiness Score: 12/100
+```
+
+## Output formats
+
+```bash
+npx @rtl-first/audit ./project                    # Terminal (default)
+npx @rtl-first/audit ./project --format json       # JSON (for CI/CD)
+npx @rtl-first/audit ./project --format markdown   # Markdown (for issues)
+```
+
+## Zero dependencies
+
+This tool has no external dependencies. It uses only Node.js built-in modules.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rtl-first/audit",
+  "version": "0.1.0",
+  "description": "Scan any project for RTL readiness across all 5 layers",
+  "main": "src/index.js",
+  "bin": {
+    "rtl-audit": "src/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "start": "node src/cli.js"
+  },
+  "keywords": [
+    "rtl",
+    "right-to-left",
+    "arabic",
+    "hebrew",
+    "i18n",
+    "internationalization",
+    "audit",
+    "accessibility",
+    "css-logical-properties",
+    "bidi"
+  ],
+  "author": "Mohammad AlShammari <imohad>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/imohad/rtl-first",
+    "directory": "packages/rtl-audit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { runAudit } from './index.js';
+import { formatTerminal } from './formatters/terminal.js';
+import { formatJSON } from './formatters/json.js';
+import { formatMarkdown } from './formatters/markdown.js';
+
+const args = process.argv.slice(2);
+
+// Parse arguments
+let targetPath = '.';
+let format = 'terminal';
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--format' && args[i + 1]) {
+    format = args[i + 1];
+    i++;
+  } else if (args[i] === '--help' || args[i] === '-h') {
+    printHelp();
+    process.exit(0);
+  } else if (args[i] === '--version' || args[i] === '-v') {
+    console.log('0.1.0');
+    process.exit(0);
+  } else if (!args[i].startsWith('-')) {
+    targetPath = args[i];
+  }
+}
+
+const resolvedPath = resolve(targetPath);
+
+if (!existsSync(resolvedPath)) {
+  console.error(`Error: path "${resolvedPath}" does not exist.`);
+  process.exit(1);
+}
+
+// Run audit
+const report = runAudit(resolvedPath);
+
+// Format output
+const formatters = {
+  terminal: formatTerminal,
+  json: formatJSON,
+  markdown: formatMarkdown,
+};
+
+const formatter = formatters[format];
+if (!formatter) {
+  console.error(`Unknown format: "${format}". Use: terminal, json, markdown`);
+  process.exit(1);
+}
+
+console.log(formatter(report));
+
+function printHelp() {
+  console.log(`
+  @rtl-first/audit — Scan any project for RTL readiness
+
+  Usage:
+    rtl-audit [path] [options]
+
+  Arguments:
+    path                  Path to project directory (default: current dir)
+
+  Options:
+    --format <type>       Output format: terminal, json, markdown (default: terminal)
+    -h, --help            Show this help
+    -v, --version         Show version
+
+  Examples:
+    rtl-audit ./my-project
+    rtl-audit ./my-project --format json
+    rtl-audit ./my-project --format markdown > rtl-report.md
+  `);
+}

package/src/formatters/json.js

@@ -0,0 +1,6 @@
+/**
+ * Format audit report as JSON.
+ */
+export function formatJSON(report) {
+  return JSON.stringify(report, null, 2);
+}

package/src/formatters/markdown.js

@@ -0,0 +1,103 @@
+/**
+ * Format audit report as Markdown — ready to paste into a GitHub issue.
+ */
+export function formatMarkdown(report) {
+  const lines = [];
+
+  lines.push(`## RTL Audit Report — ${report.projectName}`);
+  lines.push('');
+  lines.push(`*Generated by [rtl-first](https://github.com/imohad/rtl-first) v${report.version}*`);
+  lines.push('');
+  lines.push(`**RTL Readiness Score: ${report.score.total}/100 (${report.score.grade})**`);
+  lines.push('');
+
+  // Summary table
+  lines.push('| Layer | Status | Summary |');
+  lines.push('|-------|--------|---------|');
+
+  const layers = [
+    { key: 'layer1', name: 'Text engine', data: report.layers.layer1 },
+    { key: 'layer2', name: 'Direction logic', data: report.layers.layer2 },
+    { key: 'layer3', name: 'CSS layout', data: report.layers.layer3 },
+    { key: 'layer4', name: 'Translations', data: report.layers.layer4 },
+    { key: 'layer5', name: 'Hardcoded text', data: report.layers.layer5 },
+  ];
+
+  for (const { name, data } of layers) {
+    const icon = data.status === 'pass' ? '✅' : data.status === 'warn' ? '⚠️' : '❌';
+    lines.push(`| ${name} | ${icon} | ${data.summary} |`);
+  }
+
+  lines.push('');
+
+  // Details per layer
+  for (const { key, name, data } of layers) {
+    if (data.status === 'pass') continue;
+
+    lines.push(`### ${name}`);
+    lines.push('');
+    lines.push(data.detail);
+    lines.push('');
+
+    if (key === 'layer3' && data.breakdown) {
+      const entries = Object.entries(data.breakdown).slice(0, 8);
+      if (entries.length > 0) {
+        lines.push('| Property | Occurrences |');
+        lines.push('|----------|------------|');
+        for (const [prop, count] of entries) {
+          lines.push(`| \`${prop}\` | ${count} |`);
+        }
+        lines.push('');
+      }
+    }
+
+    if (key === 'layer4' && data.gaps) {
+      for (const gap of data.gaps.slice(0, 3)) {
+        if (gap.targetPath) {
+          lines.push(`- \`en.json\`: ${gap.sourceKeyCount} keys`);
+          lines.push(`- \`ar.json\`: ${gap.targetKeyCount} keys (${gap.missingKeys} missing)`);
+        } else {
+          lines.push(`- \`en.json\`: ${gap.sourceKeyCount} keys`);
+          lines.push(`- \`ar.json\`: **not found**`);
+        }
+      }
+      lines.push('');
+    }
+
+    if (key === 'layer5' && data.findings) {
+      lines.push('<details>');
+      lines.push(`<summary>Hardcoded strings (${data.count} found)</summary>`);
+      lines.push('');
+      for (const f of data.findings.slice(0, 20)) {
+        lines.push(`- \`${f.file}:${f.line}\` — "${f.text}"`);
+      }
+      if (data.count > 20) {
+        lines.push(`- ... and ${data.count - 20} more`);
+      }
+      lines.push('');
+      lines.push('</details>');
+      lines.push('');
+    }
+
+    if (data.fix) {
+      lines.push(`**Fix:** \`${data.fix}\``);
+      lines.push('');
+    }
+  }
+
+  // Priority
+  if (report.priority.length > 0) {
+    lines.push('### Recommended priority');
+    lines.push('');
+    for (let i = 0; i < report.priority.length; i++) {
+      lines.push(`${i + 1}. ${report.priority[i]}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push('*Methodology: [The Five Layers of RTL Readiness](https://github.com/imohad/rtl-first/blob/main/docs/for-contributors/methodology.md)*');
+
+  return lines.join('\n');
+}

package/src/formatters/terminal.js

@@ -0,0 +1,126 @@
+/**
+ * Format audit report for terminal output with colors and box drawing.
+ */
+export function formatTerminal(report) {
+  const lines = [];
+  const W = 56;
+
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+  const red = (s) => `\x1b[31m${s}\x1b[0m`;
+  const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+  const green = (s) => `\x1b[32m${s}\x1b[0m`;
+  const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+
+  const statusIcon = (status) => {
+    if (status === 'pass') return green('✅');
+    if (status === 'warn') return yellow('⚠️ ');
+    return red('❌');
+  };
+
+  const statusLabel = (status) => {
+    if (status === 'pass') return green('PASS');
+    if (status === 'warn') return yellow('WARN');
+    return red('FAIL');
+  };
+
+  // Header
+  lines.push('');
+  lines.push(bold(`  RTL Audit Report — ${report.projectName}`));
+  lines.push(dim(`  Generated by rtl-first v${report.version}`));
+  lines.push(dim('  ═'.repeat(28)));
+  lines.push('');
+
+  // Layer 1
+  const l1 = report.layers.layer1;
+  lines.push(`  ${statusIcon(l1.status)} ${bold('Layer 1 — Text engine')}        ${statusLabel(l1.status)}`);
+  lines.push(`     ${l1.summary}`);
+  if (l1.engines && l1.engines.length > 0) {
+    for (const e of l1.engines) {
+      lines.push(dim(`     → ${e.name}: ${e.bidiNote}`));
+    }
+  }
+  lines.push('');
+
+  // Layer 2
+  const l2 = report.layers.layer2;
+  lines.push(`  ${statusIcon(l2.status)} ${bold('Layer 2 — Direction logic')}    ${statusLabel(l2.status)}`);
+  lines.push(`     ${l2.summary}`);
+  if (l2.fix) lines.push(dim(`     → ${l2.fix}`));
+  if (l2.uiLibraries && l2.uiLibraries.length > 0) {
+    lines.push(dim(`     UI libraries: ${l2.uiLibraries.join(', ')}`));
+  }
+  lines.push('');
+
+  // Layer 3
+  const l3 = report.layers.layer3;
+  lines.push(`  ${statusIcon(l3.status)} ${bold('Layer 3 — CSS layout')}         ${statusLabel(l3.status)}`);
+  lines.push(`     ${l3.summary}`);
+  if (l3.breakdown && Object.keys(l3.breakdown).length > 0) {
+    const top5 = Object.entries(l3.breakdown).slice(0, 5);
+    for (const [prop, count] of top5) {
+      lines.push(dim(`     ${prop}: ${count} occurrences`));
+    }
+  }
+  if (l3.fix) lines.push(dim(`     → Fix: ${l3.fix}`));
+  lines.push('');
+
+  // Layer 4
+  const l4 = report.layers.layer4;
+  lines.push(`  ${statusIcon(l4.status)} ${bold('Layer 4 — Translations')}       ${statusLabel(l4.status)}`);
+  lines.push(`     ${l4.summary}`);
+  if (l4.gaps && l4.gaps.length > 0) {
+    for (const gap of l4.gaps.slice(0, 3)) {
+      if (gap.targetPath) {
+        lines.push(dim(`     en: ${gap.sourceKeyCount} keys → ar: ${gap.targetKeyCount} keys (${gap.missingKeys} missing)`));
+      } else {
+        lines.push(dim(`     en: ${gap.sourceKeyCount} keys → ar.json: not found`));
+      }
+    }
+  }
+  if (l4.fix) lines.push(dim(`     → Fix: ${l4.fix}`));
+  lines.push('');
+
+  // Layer 5
+  const l5 = report.layers.layer5;
+  lines.push(`  ${statusIcon(l5.status)} ${bold('Layer 5 — Hardcoded text')}     ${statusLabel(l5.status)}`);
+  lines.push(`     ${l5.summary}`);
+  if (l5.findings && l5.findings.length > 0) {
+    for (const f of l5.findings.slice(0, 5)) {
+      lines.push(dim(`     ${f.file}:${f.line} → "${f.text}"`));
+    }
+    if (l5.count > 5) {
+      lines.push(dim(`     ... and ${l5.count - 5} more`));
+    }
+  }
+  lines.push('');
+
+  // Score
+  lines.push(dim('  ─'.repeat(28)));
+  lines.push('');
+
+  const grade = report.score.grade;
+  const gradeColor = grade === 'A' ? green : grade === 'B' ? green : grade === 'C' ? yellow : red;
+  lines.push(`  ${bold('RTL Readiness Score:')} ${gradeColor(bold(`${report.score.total}/100`))} ${gradeColor(`(${grade})`)}`);
+  lines.push('');
+
+  // Score breakdown
+  lines.push(dim(`     Layer 1: ${report.score.breakdown.layer1}/30  Layer 2: ${report.score.breakdown.layer2}/25  Layer 3: ${Math.round(report.score.breakdown.layer3)}/20`));
+  lines.push(dim(`     Layer 4: ${Math.round(report.score.breakdown.layer4)}/15  Layer 5: ${Math.round(report.score.breakdown.layer5)}/10`));
+  lines.push('');
+
+  // Priority
+  if (report.priority.length > 0) {
+    lines.push(`  ${bold('Priority order:')}`);
+    for (let i = 0; i < report.priority.length; i++) {
+      lines.push(cyan(`     ${i + 1}. ${report.priority[i]}`));
+    }
+    lines.push('');
+    lines.push(dim('  Tip: Open an issue before submitting any PR.'));
+    lines.push(dim('  Guide: https://github.com/imohad/rtl-first'));
+  }
+
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/index.js

@@ -0,0 +1,61 @@
+import { basename } from 'path';
+import { scanLayer1 } from './scanners/layer1-text-engine.js';
+import { scanLayer2 } from './scanners/layer2-direction.js';
+import { scanLayer3 } from './scanners/layer3-css.js';
+import { scanLayer4 } from './scanners/layer4-translations.js';
+import { scanLayer5 } from './scanners/layer5-hardcoded.js';
+import { computeScore } from './score.js';
+
+/**
+ * Run a full RTL audit on a project directory.
+ * @param {string} projectPath - Absolute path to the project root
+ * @returns {object} Complete audit report
+ */
+export function runAudit(projectPath) {
+  const projectName = basename(projectPath);
+
+  const layer1 = scanLayer1(projectPath);
+  const layer2 = scanLayer2(projectPath);
+  const layer3 = scanLayer3(projectPath);
+  const layer4 = scanLayer4(projectPath);
+  const layer5 = scanLayer5(projectPath);
+
+  const layers = { layer1, layer2, layer3, layer4, layer5 };
+  const score = computeScore(layers);
+
+  return {
+    version: '0.1.0',
+    projectName,
+    projectPath,
+    timestamp: new Date().toISOString(),
+    score,
+    layers,
+    priority: computePriority(layers),
+  };
+}
+
+/**
+ * Determine which layers to fix first based on current state.
+ */
+function computePriority(layers) {
+  const order = [];
+
+  // Layer 2 is almost always the first thing to fix
+  if (layers.layer2.status !== 'pass') order.push('Layer 2 — Direction logic');
+
+  // Layer 4 next — translations are safe and welcome
+  if (layers.layer4.status !== 'pass') order.push('Layer 4 — Translations');
+
+  // Layer 5 — hardcoded strings
+  if (layers.layer5.status !== 'pass') order.push('Layer 5 — Hardcoded text');
+
+  // Layer 3 — CSS, best done with codemod
+  if (layers.layer3.status !== 'pass') order.push('Layer 3 — CSS layout');
+
+  // Layer 1 — text engine, only if detected
+  if (layers.layer1.status === 'warn' || layers.layer1.status === 'fail') {
+    order.push('Layer 1 — Text engine (requires proposal)');
+  }
+
+  return order;
+}

package/src/scanners/layer1-text-engine.js

@@ -0,0 +1,82 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { findFiles } from '../utils/walker.js';
+
+const TEXT_ENGINES = {
+  'prosemirror-model': { name: 'ProseMirror', bidiNote: 'Requires explicit BiDi configuration' },
+  'prosemirror-view': { name: 'ProseMirror', bidiNote: 'Requires explicit BiDi configuration' },
+  '@tiptap/core': { name: 'TipTap (ProseMirror)', bidiNote: 'Requires explicit BiDi configuration' },
+  'slate': { name: 'Slate', bidiNote: 'BiDi support depends on implementation' },
+  'slate-react': { name: 'Slate', bidiNote: 'BiDi support depends on implementation' },
+  '@codemirror/state': { name: 'CodeMirror 6', bidiNote: 'Has built-in BiDi support' },
+  'codemirror': { name: 'CodeMirror', bidiNote: 'Check version — v6 has better BiDi' },
+  'quill': { name: 'Quill', bidiNote: 'Limited BiDi support' },
+  'monaco-editor': { name: 'Monaco', bidiNote: 'Good BiDi support (VS Code editor)' },
+  '@blocksuite/block-std': { name: 'BlockSuite', bidiNote: 'ProseMirror-based — BiDi not configured by default' },
+  '@blocksuite/blocks': { name: 'BlockSuite', bidiNote: 'ProseMirror-based — BiDi not configured by default' },
+};
+
+/**
+ * Scan for rich-text editor engines in the project.
+ */
+export function scanLayer1(projectPath) {
+  const packageFiles = findFiles(projectPath, 'package.json', 5);
+  const detected = new Map(); // name → { packages, bidiNote }
+
+  for (const pkgPath of packageFiles) {
+    try {
+      const content = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = {
+        ...content.dependencies,
+        ...content.devDependencies,
+        ...content.peerDependencies,
+      };
+
+      for (const [pkg, info] of Object.entries(TEXT_ENGINES)) {
+        if (allDeps[pkg]) {
+          if (!detected.has(info.name)) {
+            detected.set(info.name, { packages: [], bidiNote: info.bidiNote });
+          }
+          detected.get(info.name).packages.push(pkg);
+        }
+      }
+    } catch {
+      // Skip invalid package.json files
+    }
+  }
+
+  if (detected.size === 0) {
+    return {
+      status: 'pass',
+      summary: 'No rich-text editor detected',
+      detail: 'This project does not appear to use a complex text editor. RTL support can start from Layer 2.',
+      engines: [],
+    };
+  }
+
+  const engines = [];
+  for (const [name, info] of detected) {
+    engines.push({
+      name,
+      packages: [...new Set(info.packages)],
+      bidiNote: info.bidiNote,
+    });
+  }
+
+  // Check if any detected engines have known BiDi issues
+  const hasRiskyEngine = engines.some(e =>
+    e.name.includes('ProseMirror') ||
+    e.name.includes('BlockSuite') ||
+    e.name.includes('Slate') ||
+    e.name.includes('Quill')
+  );
+
+  return {
+    status: hasRiskyEngine ? 'warn' : 'pass',
+    summary: `Detected: ${engines.map(e => e.name).join(', ')}`,
+    detail: hasRiskyEngine
+      ? 'This project uses a text editor that may need BiDi configuration. Check Layer 1 before proceeding with surface-level RTL changes.'
+      : 'Detected text editors appear to have reasonable BiDi support.',
+    engines,
+  };
+}

package/src/scanners/layer2-direction.js

@@ -0,0 +1,108 @@
+import { readFileSync } from 'fs';
+import { walkFiles, findFiles } from '../utils/walker.js';
+
+const DIRECTION_PATTERNS = [
+  { pattern: /dir\s*=\s*["']rtl["']/i, label: 'dir="rtl" attribute' },
+  { pattern: /\.dir\s*=\s*["']rtl["']/i, label: 'JavaScript dir assignment' },
+  { pattern: /documentElement\.dir/i, label: 'document.documentElement.dir' },
+  { pattern: /applyDocumentLanguage/i, label: 'applyDocumentLanguage()' },
+  { pattern: /DirectionProvider/i, label: 'DirectionProvider' },
+  { pattern: /useDirection/i, label: 'useDirection hook' },
+  { pattern: /direction:\s*['"]rtl['"]/, label: 'CSS direction: rtl' },
+  { pattern: /i18n.*dir/i, label: 'i18n direction config' },
+];
+
+// UI libraries that need DirectionProvider
+const UI_LIBS = {
+  '@radix-ui/react-direction': 'Radix UI (has DirectionProvider)',
+  '@radix-ui/themes': 'Radix UI Themes',
+  '@chakra-ui/react': 'Chakra UI (has direction support)',
+  '@mantine/core': 'Mantine (has direction support)',
+  'antd': 'Ant Design (has ConfigProvider direction)',
+};
+
+/**
+ * Scan for RTL direction logic in the project.
+ */
+export function scanLayer2(projectPath) {
+  const codeFiles = walkFiles(projectPath, ['.ts', '.tsx', '.js', '.jsx', '.html', '.vue', '.svelte']);
+  const found = [];
+  const missing = [];
+
+  // Check for direction patterns in code
+  for (const filePath of codeFiles) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      for (const { pattern, label } of DIRECTION_PATTERNS) {
+        if (pattern.test(content)) {
+          found.push({ file: filePath, pattern: label });
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  // Check for UI libraries that need direction configuration
+  const detectedLibs = [];
+  const packageFiles = findFiles(projectPath, 'package.json', 5);
+
+  for (const pkgPath of packageFiles) {
+    try {
+      const content = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = { ...content.dependencies, ...content.devDependencies };
+
+      for (const [pkg, label] of Object.entries(UI_LIBS)) {
+        if (allDeps[pkg]) detectedLibs.push(label);
+      }
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  // Determine status
+  const hasDirectionLogic = found.length > 0;
+  const hasDirectionProvider = found.some(f =>
+    f.pattern.includes('DirectionProvider') || f.pattern.includes('direction config')
+  );
+  const needsDirectionProvider = detectedLibs.length > 0 && !hasDirectionProvider;
+
+  if (hasDirectionLogic && !needsDirectionProvider) {
+    return {
+      status: 'pass',
+      summary: `Direction logic found (${found.length} patterns)`,
+      detail: 'This project has direction detection and configuration.',
+      found: dedup(found),
+      uiLibraries: detectedLibs,
+    };
+  }
+
+  if (hasDirectionLogic && needsDirectionProvider) {
+    return {
+      status: 'warn',
+      summary: 'Direction logic exists but may be incomplete',
+      detail: `Found direction patterns but ${detectedLibs.join(', ')} may need DirectionProvider wrapping.`,
+      found: dedup(found),
+      uiLibraries: detectedLibs,
+    };
+  }
+
+  return {
+    status: 'fail',
+    summary: 'No direction logic found',
+    detail: 'No dir="rtl" detection, no DirectionProvider, no language-aware direction switching.',
+    found: [],
+    uiLibraries: detectedLibs,
+    fix: 'Add document.documentElement.dir = "rtl" when RTL locale is active. If using Radix UI, wrap app in DirectionProvider.',
+  };
+}
+
+function dedup(items) {
+  const seen = new Set();
+  return items.filter(item => {
+    const key = item.pattern;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/scanners/layer3-css.js

@@ -0,0 +1,92 @@
+import { readFileSync } from 'fs';
+import { walkFiles } from '../utils/walker.js';
+
+const PHYSICAL_PROPERTIES = [
+  { pattern: /margin-left\s*:/g, replacement: 'margin-inline-start', label: 'margin-left' },
+  { pattern: /margin-right\s*:/g, replacement: 'margin-inline-end', label: 'margin-right' },
+  { pattern: /padding-left\s*:/g, replacement: 'padding-inline-start', label: 'padding-left' },
+  { pattern: /padding-right\s*:/g, replacement: 'padding-inline-end', label: 'padding-right' },
+  { pattern: /border-left\s*:/g, replacement: 'border-inline-start', label: 'border-left' },
+  { pattern: /border-right\s*:/g, replacement: 'border-inline-end', label: 'border-right' },
+  { pattern: /border-left-width\s*:/g, replacement: 'border-inline-start-width', label: 'border-left-width' },
+  { pattern: /border-right-width\s*:/g, replacement: 'border-inline-end-width', label: 'border-right-width' },
+  { pattern: /(?<![a-zA-Z-])left\s*:\s*(?!.*(?:calc|var|env))/g, replacement: 'inset-inline-start', label: 'left (positional)' },
+  { pattern: /(?<![a-zA-Z-])right\s*:\s*(?!.*(?:calc|var|env))/g, replacement: 'inset-inline-end', label: 'right (positional)' },
+  { pattern: /text-align\s*:\s*left/g, replacement: 'text-align: start', label: 'text-align: left' },
+  { pattern: /text-align\s*:\s*right/g, replacement: 'text-align: end', label: 'text-align: right' },
+];
+
+// camelCase variants for CSS-in-JS
+const CAMELCASE_PROPERTIES = [
+  { pattern: /marginLeft\s*:/g, label: 'marginLeft (JS)' },
+  { pattern: /marginRight\s*:/g, label: 'marginRight (JS)' },
+  { pattern: /paddingLeft\s*:/g, label: 'paddingLeft (JS)' },
+  { pattern: /paddingRight\s*:/g, label: 'paddingRight (JS)' },
+  { pattern: /borderLeft\s*:/g, label: 'borderLeft (JS)' },
+  { pattern: /borderRight\s*:/g, label: 'borderRight (JS)' },
+];
+
+/**
+ * Scan for physical CSS properties that should be logical.
+ */
+export function scanLayer3(projectPath) {
+  const cssFiles = walkFiles(projectPath, ['.css', '.scss', '.less', '.sass']);
+  const codeFiles = walkFiles(projectPath, ['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte']);
+  const allFiles = [...cssFiles, ...codeFiles];
+
+  const counts = {};
+  let totalOccurrences = 0;
+  let filesWithIssues = 0;
+  const allProperties = [...PHYSICAL_PROPERTIES, ...CAMELCASE_PROPERTIES];
+
+  for (const filePath of allFiles) {
+    let fileHasIssues = false;
+
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+
+      for (const { pattern, label } of allProperties) {
+        // Reset regex lastIndex
+        pattern.lastIndex = 0;
+        const matches = content.match(pattern);
+        if (matches && matches.length > 0) {
+          counts[label] = (counts[label] || 0) + matches.length;
+          totalOccurrences += matches.length;
+          fileHasIssues = true;
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+
+    if (fileHasIssues) filesWithIssues++;
+  }
+
+  if (totalOccurrences === 0) {
+    return {
+      status: 'pass',
+      summary: 'No physical CSS properties found',
+      detail: 'This project uses logical CSS properties or has no directional styling.',
+      filesScanned: allFiles.length,
+      filesWithIssues: 0,
+      totalOccurrences: 0,
+      breakdown: {},
+    };
+  }
+
+  // Sort by count descending
+  const sorted = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .reduce((obj, [k, v]) => ({ ...obj, [k]: v }), {});
+
+  return {
+    status: totalOccurrences > 50 ? 'fail' : 'warn',
+    summary: `${filesWithIssues} files use physical CSS properties (${totalOccurrences} occurrences)`,
+    detail: `Run @rtl-first/codemod to convert physical properties to logical properties.`,
+    filesScanned: allFiles.length,
+    filesWithIssues,
+    totalOccurrences,
+    breakdown: sorted,
+    fix: 'npx @rtl-first/codemod --dry-run ./src',
+  };
+}

package/src/scanners/layer4-translations.js

@@ -0,0 +1,276 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { findFiles } from '../utils/walker.js';
+
+const RTL_LOCALES = ['ar', 'he', 'fa', 'ur', 'ps', 'sd', 'yi'];
+const I18N_DIR_NAMES = ['i18n', 'locales', 'lang', 'languages', 'translations', 'resources', 'messages'];
+
+/**
+ * Scan for translation file completeness.
+ * Supports two patterns:
+ *   1. Flat files: locales/en.json, locales/ar.json
+ *   2. Locale folders: i18n/en-US/*.json, i18n/ar-TN/*.json (Dify, Next.js style)
+ */
+export function scanLayer4(projectPath) {
+  // Strategy 1: Look for locale folder pattern (en-US/, ar-TN/, etc.)
+  const folderResult = scanLocaleFolders(projectPath);
+  if (folderResult) return folderResult;
+
+  // Strategy 2: Look for flat file pattern (en.json, ar.json)
+  const flatResult = scanFlatFiles(projectPath);
+  if (flatResult) return flatResult;
+
+  return {
+    status: 'warn',
+    summary: 'No i18n files detected',
+    detail: 'Could not find locale files. The project may not use i18n, or may use a non-standard file structure.',
+    sourceFiles: [],
+    targetFiles: [],
+    gaps: [],
+  };
+}
+
+/**
+ * Strategy 1: Locale folders like i18n/en-US/*.json, i18n/ar-TN/*.json
+ */
+function scanLocaleFolders(projectPath) {
+  // Find directories that contain locale subdirectories
+  for (const dirName of I18N_DIR_NAMES) {
+    const candidates = findI18nDirs(projectPath, dirName, 5);
+
+    for (const i18nDir of candidates) {
+      let entries;
+      try { entries = readdirSync(i18nDir, { withFileTypes: true }); } catch { continue; }
+
+      const subdirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+
+      // Find English source directory
+      const enDir = subdirs.find(d => d.startsWith('en'));
+      if (!enDir) continue;
+
+      // Find Arabic/RTL target directory
+      const arDir = subdirs.find(d => RTL_LOCALES.some(loc => d.startsWith(loc)));
+
+      const enPath = join(i18nDir, enDir);
+      const arPath = arDir ? join(i18nDir, arDir) : null;
+
+      // Count keys across all JSON files in the locale folder
+      const enKeys = countKeysInFolder(enPath);
+      const arKeys = arPath ? countKeysInFolder(arPath) : { total: 0, files: [] };
+
+      if (enKeys.total === 0) continue;
+
+      // Build per-file gap report
+      const gaps = [];
+      for (const fileInfo of enKeys.files) {
+        const arFile = arKeys.files.find(f => f.name === fileInfo.name);
+        const arCount = arFile ? arFile.count : 0;
+        gaps.push({
+          sourcePath: fileInfo.path,
+          targetPath: arFile ? arFile.path : null,
+          sourceKeyCount: fileInfo.count,
+          targetKeyCount: arCount,
+          missingKeys: fileInfo.count - arCount,
+        });
+      }
+
+      const totalMissing = enKeys.total - arKeys.total;
+      const coverage = ((arKeys.total / enKeys.total) * 100).toFixed(1);
+
+      if (arPath && totalMissing === 0) {
+        return {
+          status: 'pass',
+          summary: `Arabic translations complete — ${arDir} (${arKeys.total} keys)`,
+          detail: `${enDir} and ${arDir} have matching key counts across ${enKeys.files.length} files.`,
+          sourceLocale: enDir,
+          targetLocale: arDir,
+          sourceFiles: enKeys.files.map(f => f.path),
+          targetFiles: arKeys.files.map(f => f.path),
+          gaps,
+        };
+      }
+
+      if (arPath && totalMissing > 0) {
+        return {
+          status: 'warn',
+          summary: `Arabic ${coverage}% complete — ${totalMissing} keys missing (${arDir})`,
+          detail: `${enDir}: ${enKeys.total} keys → ${arDir}: ${arKeys.total} keys across ${enKeys.files.length} files.`,
+          sourceLocale: enDir,
+          targetLocale: arDir,
+          sourceFiles: enKeys.files.map(f => f.path),
+          targetFiles: arKeys.files.map(f => f.path),
+          gaps: gaps.filter(g => g.missingKeys > 0),
+        };
+      }
+
+      return {
+        status: 'fail',
+        summary: `No Arabic translation folder (${enDir} has ${enKeys.total} keys)`,
+        detail: `Found ${enDir} with ${enKeys.files.length} locale files but no Arabic locale folder.`,
+        sourceLocale: enDir,
+        targetLocale: null,
+        sourceFiles: enKeys.files.map(f => f.path),
+        targetFiles: [],
+        gaps,
+        fix: `Create ${i18nDir}/ar/ directory with translated JSON files matching ${enDir}/.`,
+      };
+    }
+  }
+
+  return null; // No locale folders found
+}
+
+/**
+ * Strategy 2: Flat files like locales/en.json, locales/ar.json
+ */
+function scanFlatFiles(projectPath) {
+  const enFiles = findFiles(projectPath, 'en.json', 8);
+  if (enFiles.length === 0) return null;
+
+  const results = [];
+
+  for (const enPath of enFiles) {
+    try {
+      const enContent = JSON.parse(readFileSync(enPath, 'utf-8'));
+      const enKeys = flattenKeys(enContent);
+
+      // Look for ar.json in the same directory
+      const arPath = enPath.replace(/\/en\.json$/, '/ar.json');
+      let arKeys = [];
+      let arExists = false;
+
+      try {
+        const arContent = JSON.parse(readFileSync(arPath, 'utf-8'));
+        arKeys = flattenKeys(arContent);
+        arExists = true;
+      } catch {
+        // ar.json doesn't exist
+      }
+
+      results.push({
+        sourcePath: enPath,
+        targetPath: arExists ? arPath : null,
+        sourceKeyCount: enKeys.length,
+        targetKeyCount: arKeys.length,
+        missingKeys: enKeys.length - arKeys.length,
+      });
+    } catch {
+      // Skip unparseable JSON
+    }
+  }
+
+  if (results.length === 0) return null;
+
+  const totalSource = results.reduce((s, r) => s + r.sourceKeyCount, 0);
+  const totalTarget = results.reduce((s, r) => s + r.targetKeyCount, 0);
+  const totalMissing = totalSource - totalTarget;
+  const hasArabic = results.some(r => r.targetPath !== null);
+
+  if (hasArabic && totalMissing === 0) {
+    return {
+      status: 'pass',
+      summary: `Arabic translations complete (${totalTarget} keys)`,
+      detail: 'ar.json exists and covers all keys from en.json.',
+      gaps: results,
+    };
+  }
+
+  if (hasArabic && totalMissing > 0) {
+    const coverage = ((totalTarget / totalSource) * 100).toFixed(1);
+    return {
+      status: 'warn',
+      summary: `Arabic ${coverage}% complete — ${totalMissing} keys missing`,
+      detail: `en.json: ${totalSource} keys → ar.json: ${totalTarget} keys.`,
+      gaps: results,
+    };
+  }
+
+  return {
+    status: 'fail',
+    summary: `No Arabic translation found (en.json has ${totalSource} keys)`,
+    detail: 'ar.json does not exist.',
+    gaps: results,
+    fix: 'Create ar.json in the same directory as en.json with translated strings.',
+  };
+}
+
+/**
+ * Find i18n directories by name within the project.
+ */
+function findI18nDirs(dir, targetName, maxDepth, depth = 0) {
+  const results = [];
+  if (depth > maxDepth) return results;
+
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'vendor', 'coverage']);
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP.has(entry.name)) continue;
+      if (entry.name === targetName) {
+        results.push(join(dir, entry.name));
+      }
+      results.push(...findI18nDirs(join(dir, entry.name), targetName, maxDepth, depth + 1));
+    }
+  } catch {
+    // Skip unreadable dirs
+  }
+
+  return results;
+}
+
+/**
+ * Count translation keys across all JSON files in a locale folder.
+ */
+function countKeysInFolder(folderPath) {
+  const files = [];
+  let total = 0;
+
+  try {
+    for (const entry of readdirSync(folderPath)) {
+      if (!entry.endsWith('.json')) continue;
+      const filePath = join(folderPath, entry);
+      try {
+        const content = JSON.parse(readFileSync(filePath, 'utf-8'));
+        const count = countKeysDeep(content);
+        files.push({ name: entry, path: filePath, count });
+        total += count;
+      } catch {
+        // Skip invalid JSON
+      }
+    }
+  } catch {
+    // Folder unreadable
+  }
+
+  return { total, files };
+}
+
+function countKeysDeep(obj) {
+  let count = 0;
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      count += countKeysDeep(value);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Flatten a nested JSON object into dot-notation keys.
+ */
+function flattenKeys(obj, prefix = '') {
+  const keys = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      keys.push(...flattenKeys(value, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+  return keys;
+}

package/src/scanners/layer5-hardcoded.js

@@ -0,0 +1,162 @@
+import { readFileSync } from 'fs';
+import { relative } from 'path';
+import { walkFiles } from '../utils/walker.js';
+
+// Strings that are NOT hardcoded user-facing text
+const IGNORE_PATTERNS = [
+  /^[a-z][a-zA-Z0-9]*$/, // camelCase identifiers
+  /^[A-Z][A-Z0-9_]*$/, // CONSTANT_CASE
+  /^[a-z-]+$/, // kebab-case (CSS classes, data attributes)
+  /^(https?:\/\/|mailto:|tel:)/, // URLs
+  /^[./#]/, // Paths
+  /^\d+/, // Numbers
+  /^(true|false|null|undefined)$/, // Literals
+  /^(div|span|button|input|form|label|img|svg|path|a|p|h[1-6])$/, // HTML tags
+  /^(GET|POST|PUT|DELETE|PATCH)$/, // HTTP methods
+  /^(string|number|boolean|object|function)$/, // Types
+  /^(px|rem|em|vh|vw|%|auto|none|inherit|flex|grid|block|inline)$/, // CSS values
+  /^(onClick|onChange|onSubmit|className|style|key|ref|id|type|name|value|placeholder)$/, // React props
+  /^data-/, // Data attributes
+  /^aria-/, // ARIA attributes
+  /^[{}<>()\[\]|&=+\-*\/\\;:,.'"`~!@#$%^?]+$/, // Symbols only
+];
+
+// Minimum word count to consider a string as user-facing text
+const MIN_WORDS = 2;
+const MAX_RESULTS = 50;
+
+/**
+ * Scan JSX/TSX files for hardcoded English strings.
+ */
+export function scanLayer5(projectPath) {
+  const files = walkFiles(projectPath, ['.tsx', '.jsx']);
+  const findings = [];
+
+  for (const filePath of files) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        // Skip imports, comments, and type definitions
+        if (isSkippableLine(line)) continue;
+
+        // Find string literals in JSX context
+        const strings = extractJSXStrings(line);
+
+        for (const str of strings) {
+          if (isLikelyUserFacing(str)) {
+            findings.push({
+              file: relative(projectPath, filePath),
+              line: i + 1,
+              text: str.length > 60 ? str.substring(0, 60) + '...' : str,
+            });
+          }
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+
+    // Cap results for performance
+    if (findings.length >= MAX_RESULTS * 2) break;
+  }
+
+  const limited = findings.slice(0, MAX_RESULTS);
+
+  if (findings.length === 0) {
+    return {
+      status: 'pass',
+      summary: 'No hardcoded English strings detected in JSX',
+      detail: 'All user-facing text appears to use i18n keys.',
+      count: 0,
+      findings: [],
+    };
+  }
+
+  return {
+    status: findings.length > 20 ? 'fail' : 'warn',
+    summary: `${findings.length} hardcoded English strings found in JSX`,
+    detail: 'These strings should be replaced with i18n translation keys.',
+    count: findings.length,
+    findings: limited,
+    fix: 'Replace hardcoded strings with t() or equivalent i18n function calls.',
+  };
+}
+
+/**
+ * Extract string literals that appear in JSX context (between > and <, or in attributes).
+ */
+function extractJSXStrings(line) {
+  const strings = [];
+
+  // Match strings between JSX tags: >Some text<
+  const jsxTextPattern = />\s*([A-Z][^<>{]*?)\s*</g;
+  let match;
+  while ((match = jsxTextPattern.exec(line)) !== null) {
+    const text = match[1].trim();
+    if (text.length > 0) strings.push(text);
+  }
+
+  // Match string literals in JSX: {"Some text"} or {'Some text'}
+  const jsxExprPattern = /\{["']([A-Z][^"']*?)["']\}/g;
+  while ((match = jsxExprPattern.exec(line)) !== null) {
+    strings.push(match[1].trim());
+  }
+
+  // Match title="Some text", placeholder="Some text", alt="Some text" etc.
+  const attrPattern = /(?:title|placeholder|alt|label|aria-label|description)\s*=\s*["']([A-Z][^"']*?)["']/g;
+  while ((match = attrPattern.exec(line)) !== null) {
+    strings.push(match[1].trim());
+  }
+
+  return strings;
+}
+
+/**
+ * Check if a string looks like user-facing text that should be translated.
+ */
+function isLikelyUserFacing(str) {
+  if (!str || str.length < 3) return false;
+
+  // Check against ignore patterns
+  for (const pattern of IGNORE_PATTERNS) {
+    if (pattern.test(str)) return false;
+  }
+
+  // Count words
+  const words = str.split(/\s+/).filter(w => w.length > 0);
+  if (words.length < MIN_WORDS) return false;
+
+  // Must contain at least one ASCII letter
+  if (!/[a-zA-Z]/.test(str)) return false;
+
+  // Must start with uppercase (user-facing text convention)
+  if (!/^[A-Z]/.test(str)) return false;
+
+  return true;
+}
+
+/**
+ * Check if a line should be skipped entirely.
+ */
+function isSkippableLine(line) {
+  const trimmed = line.trim();
+  return (
+    trimmed.startsWith('import ') ||
+    trimmed.startsWith('export type') ||
+    trimmed.startsWith('export interface') ||
+    trimmed.startsWith('//') ||
+    trimmed.startsWith('*') ||
+    trimmed.startsWith('/*') ||
+    trimmed.startsWith('console.') ||
+    trimmed.startsWith('throw ') ||
+    trimmed.includes('.test(') ||
+    trimmed.includes('.spec(') ||
+    trimmed.includes('describe(') ||
+    trimmed.includes('it(') ||
+    trimmed.includes('expect(')
+  );
+}

package/src/score.js

@@ -0,0 +1,89 @@
+/**
+ * Compute RTL Readiness Score (0-100) from layer results.
+ *
+ * Weight distribution:
+ *   Layer 1 — Text engine:     30 points
+ *   Layer 2 — Direction logic:  25 points
+ *   Layer 3 — CSS layout:       20 points
+ *   Layer 4 — Translations:     15 points
+ *   Layer 5 — Hardcoded text:   10 points
+ *
+ * Total: 100 points
+ */
+export function computeScore(layers) {
+  const scores = {
+    layer1: scoreLayer1(layers.layer1),
+    layer2: scoreLayer2(layers.layer2),
+    layer3: scoreLayer3(layers.layer3),
+    layer4: scoreLayer4(layers.layer4),
+    layer5: scoreLayer5(layers.layer5),
+  };
+
+  const total = scores.layer1 + scores.layer2 + scores.layer3 + scores.layer4 + scores.layer5;
+
+  return {
+    total: Math.round(total),
+    breakdown: scores,
+    grade: getGrade(total),
+  };
+}
+
+function scoreLayer1(result) {
+  const MAX = 30;
+  if (result.status === 'pass' && result.engines.length === 0) return MAX; // No editor = no issue
+  if (result.status === 'pass') return MAX; // Editor with good BiDi
+  if (result.status === 'warn') return MAX * 0.4; // Editor with unknown BiDi
+  return 0; // Editor with known BiDi issues
+}
+
+function scoreLayer2(result) {
+  const MAX = 25;
+  if (result.status === 'pass') return MAX;
+  if (result.status === 'warn') return MAX * 0.5;
+  return 0;
+}
+
+function scoreLayer3(result) {
+  const MAX = 20;
+  if (result.status === 'pass') return MAX;
+  if (result.totalOccurrences === 0) return MAX;
+
+  // Gradual degradation based on number of physical properties
+  if (result.totalOccurrences < 10) return MAX * 0.8;
+  if (result.totalOccurrences < 50) return MAX * 0.5;
+  if (result.totalOccurrences < 200) return MAX * 0.2;
+  return 0;
+}
+
+function scoreLayer4(result) {
+  const MAX = 15;
+  if (result.status === 'pass') return MAX;
+
+  // If translations exist but incomplete, score proportionally
+  if (result.gaps && result.gaps.length > 0) {
+    const totalSource = result.gaps.reduce((s, g) => s + g.sourceKeyCount, 0);
+    const totalTarget = result.gaps.reduce((s, g) => s + g.targetKeyCount, 0);
+    if (totalSource > 0) {
+      return MAX * (totalTarget / totalSource);
+    }
+  }
+
+  if (result.status === 'warn') return MAX * 0.3;
+  return 0;
+}
+
+function scoreLayer5(result) {
+  const MAX = 10;
+  if (result.status === 'pass') return MAX;
+  if (result.count < 5) return MAX * 0.7;
+  if (result.count < 20) return MAX * 0.4;
+  return 0;
+}
+
+function getGrade(score) {
+  if (score >= 90) return 'A';
+  if (score >= 75) return 'B';
+  if (score >= 55) return 'C';
+  if (score >= 35) return 'D';
+  return 'F';
+}

package/src/utils/walker.js

@@ -0,0 +1,81 @@
+import { readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', '.nuxt',
+  'coverage', '.nyc_output', '.turbo', '.cache', 'vendor',
+  '__pycache__', '.svelte-kit', '.output', 'out',
+]);
+
+/**
+ * Walk a directory tree and yield file paths matching given extensions.
+ * @param {string} dir - Root directory
+ * @param {string[]} extensions - File extensions to include (e.g. ['.ts', '.tsx'])
+ * @param {number} maxDepth - Maximum directory depth (default: 15)
+ * @returns {string[]} Array of matching file paths
+ */
+export function walkFiles(dir, extensions, maxDepth = 15) {
+  const results = [];
+  walk(dir, extensions, results, 0, maxDepth);
+  return results;
+}
+
+function walk(dir, extensions, results, depth, maxDepth) {
+  if (depth > maxDepth) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // Skip directories we can't read
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.') continue;
+
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      walk(join(dir, entry.name), extensions, results, depth + 1, maxDepth);
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name).toLowerCase();
+      if (extensions.includes(ext)) {
+        results.push(join(dir, entry.name));
+      }
+    }
+  }
+}
+
+/**
+ * Find a file by name in a directory (non-recursive or shallow recursive).
+ * @param {string} dir - Directory to search
+ * @param {string} fileName - Exact filename to find
+ * @param {number} maxDepth - How deep to search (default: 3)
+ * @returns {string[]} Array of matching paths
+ */
+export function findFiles(dir, fileName, maxDepth = 3) {
+  const results = [];
+  findRecursive(dir, fileName, results, 0, maxDepth);
+  return results;
+}
+
+function findRecursive(dir, fileName, results, depth, maxDepth) {
+  if (depth > maxDepth) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.') continue;
+
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      findRecursive(join(dir, entry.name), fileName, results, depth + 1, maxDepth);
+    } else if (entry.isFile() && entry.name === fileName) {
+      results.push(join(dir, entry.name));
+    }
+  }
+}