@birdapi/velinstyle 0.8.0 → 0.9.0

package/cli/perf-audit.js

@@ -0,0 +1,174 @@
+/**
+ * Performance audit for static HTML — images, scripts, inline styles.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, extname, relative } from 'path';
+
+const DEFAULT_IGNORE = ['node_modules', 'dist', '.git', '.next', 'build'];
+
+export function walkHtmlFiles(dir, ignore = DEFAULT_IGNORE) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (ignore.includes(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...walkHtmlFiles(full, ignore));
+    else if (extname(entry.name).toLowerCase() === '.html') results.push(full);
+  }
+  return results;
+}
+
+function lineOf(content, index) {
+  return content.slice(0, index).split('\n').length;
+}
+
+/**
+ * @param {string} html
+ * @param {{ file?: string }} meta
+ */
+export function auditHtml(html, meta = {}) {
+  const issues = [];
+  const file = meta.file || '';
+  const lines = html.split('\n');
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+
+    const imgTags = [...line.matchAll(/<img\b[^>]*>/gi)];
+    for (const m of imgTags) {
+      const tag = m[0];
+      const hasW = /\bwidth\s*=/i.test(tag);
+      const hasH = /\bheight\s*=/i.test(tag);
+      const hasStyleDim = /style\s*=\s*["'][^"']*(?:width|height)\s*:/i.test(tag);
+      if (!hasW && !hasH && !hasStyleDim) {
+        issues.push({
+          id: 'img-missing-dimensions',
+          severity: 'warning',
+          message: '<img> without width/height causes layout shift (CLS).',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<img\b/i, '<img width="800" height="450"'),
+        });
+      }
+      if (!/\bloading\s*=/i.test(tag) && !/\bfetchpriority\s*=\s*["']high["']/i.test(tag)) {
+        issues.push({
+          id: 'img-no-lazy',
+          severity: 'info',
+          message: 'Consider loading="lazy" for below-fold images.',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<img\b/i, '<img loading="lazy"'),
+        });
+      }
+    }
+
+    const scriptTags = [...line.matchAll(/<script\b[^>]*>/gi)];
+    for (const m of scriptTags) {
+      const tag = m[0];
+      if (/\bsrc\s*=/i.test(tag) && !/\bdefer\b/i.test(tag) && !/\basync\b/i.test(tag) && !/\btype\s*=\s*["']module["']/i.test(tag)) {
+        issues.push({
+          id: 'script-no-defer',
+          severity: 'warning',
+          message: 'External <script> without defer/async blocks parsing.',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<script\b/i, '<script defer'),
+        });
+      }
+    }
+
+    if (/\sstyle\s*=\s*["'][^"']{120,}["']/i.test(line)) {
+      issues.push({
+        id: 'large-inline-style',
+        severity: 'info',
+        message: 'Large inline style block. Prefer external CSS.',
+        line: ln,
+        file,
+        fixable: false,
+      });
+    }
+  });
+
+  if (/@font-face/i.test(html) && !/font-display\s*:\s*swap/i.test(html)) {
+    issues.push({
+      id: 'font-display-swap',
+      severity: 'info',
+      message: 'Add font-display: swap to @font-face rules.',
+      file,
+      line: 1,
+      fixable: false,
+    });
+  }
+
+  if (/velinstyle-components\.min\.js/i.test(html) && /velin-(?:modal|toast|tabs)/i.test(html) === false) {
+    issues.push({
+      id: 'unused-velin-import',
+      severity: 'info',
+      message: 'Full component bundle loaded. Consider @birdapi/velinstyle/runtime for tree-shaking.',
+      file,
+      line: 1,
+      fixable: false,
+    });
+  }
+
+  return issues;
+}
+
+export function auditPath(targetPath) {
+  const files = walkHtmlFiles(targetPath);
+  const issues = [];
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    issues.push(...auditHtml(html, { file }));
+  }
+  return { issues, files };
+}
+
+export function formatTextReport(issues, files) {
+  const lines = [`Performance audit — ${files.length} HTML file(s)\n`];
+  if (issues.length === 0) {
+    lines.push('No performance issues found.');
+    return lines.join('\n');
+  }
+  for (const i of issues) {
+    const loc = i.line ? `${relative(process.cwd(), i.file)}:${i.line}` : i.file;
+    lines.push(`[${i.severity}] ${i.id} — ${loc}`);
+    lines.push(`  ${i.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function fixPath(targetPath, { write = false, dryRun = true } = {}) {
+  const { issues } = auditPath(targetPath);
+  const fixable = issues.filter((i) => i.fixable && typeof i.fix === 'function');
+  const byFile = {};
+  for (const issue of fixable) {
+    if (!byFile[issue.file]) byFile[issue.file] = [];
+    byFile[issue.file].push(issue);
+  }
+  const changes = [];
+  for (const [file, fileIssues] of Object.entries(byFile)) {
+    const original = readFileSync(file, 'utf-8');
+    const lines = original.split('\n');
+    fileIssues.sort((a, b) => b.line - a.line);
+    const applied = [];
+    for (const issue of fileIssues) {
+      const idx = issue.line - 1;
+      if (idx < 0 || idx >= lines.length) continue;
+      const next = issue.fix(lines[idx]);
+      if (next !== lines[idx]) {
+        lines[idx] = next;
+        applied.push(issue.id);
+      }
+    }
+    const content = lines.join('\n');
+    if (content !== original) {
+      if (write && !dryRun) writeFileSync(file, content, 'utf-8');
+      changes.push({ file, changes: applied });
+    }
+  }
+  return { ok: true, changes, dryRun: dryRun && !write };
+}

package/cli/pii-scanner.js

@@ -0,0 +1,134 @@
+/**
+ * PII / secrets detection for velinstyle scan (--only pii).
+ */
+
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+const PLACEHOLDER_EMAILS = new Set([
+  'user@example.com',
+  'test@example.com',
+  'admin@example.com',
+  'email@example.com',
+  'you@example.com',
+  'name@example.com',
+  '{{email}}',
+  '{{EMAIL}}',
+]);
+
+const SECRET_PATTERNS = [
+  { re: /\b(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{8,}['"]/i, rule: 'pii/hardcoded-secret', msg: 'Possible API key in source.' },
+  { re: /\b(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{4,}['"]/i, rule: 'pii/hardcoded-secret', msg: 'Possible password/secret in source.' },
+  { re: /\bAKIA[0-9A-Z]{16}\b/, rule: 'pii/hardcoded-secret', msg: 'AWS access key pattern detected.' },
+  { re: /\bsk_(?:live|test)_[0-9a-zA-Z]{16,}\b/, rule: 'pii/hardcoded-secret', msg: 'Stripe secret key pattern detected.' },
+  { re: /\bghp_[0-9a-zA-Z]{36,}\b/, rule: 'pii/hardcoded-secret', msg: 'GitHub token pattern detected.' },
+];
+
+export function isPlaceholderEmail(email) {
+  const lower = email.toLowerCase();
+  if (PLACEHOLDER_EMAILS.has(lower)) return true;
+  if (/@example\.(com|org|net)$/i.test(email)) return true;
+  if (/@test\.(com|local)$/i.test(email)) return true;
+  if (/@localhost$/i.test(email)) return true;
+  return false;
+}
+
+export function maskEmail(email, placeholder = 'user@example.com') {
+  return placeholder;
+}
+
+export function fixHardcodedEmailLine(line, placeholder = 'user@example.com') {
+  return line.replace(EMAIL_RE, (match) => {
+    if (isPlaceholderEmail(match)) return match;
+    return placeholder;
+  });
+}
+
+export function scanPIIHTML(content, file, options = {}) {
+  const issues = [];
+  const lines = content.split('\n');
+  const placeholder = options.fixEmailPlaceholder || 'user@example.com';
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+    if (/\/\/|\/\*|\*\/|<!--/.test(line) && !/@/.test(line.replace(/<!--.*-->/, ''))) {
+      /* still scan — emails in comments are PII too */
+    }
+
+    const emails = [...line.matchAll(EMAIL_RE)].map((m) => m[0]);
+    for (const email of emails) {
+      if (isPlaceholderEmail(email)) continue;
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/hardcoded-email',
+        message: `Hardcoded email "${email}" found. Use env/config or <velin-email>.`,
+        fixable: true,
+        fix: (currentLine) => fixHardcodedEmailLine(currentLine, placeholder),
+      });
+    }
+
+    const hasMailto = /mailto:/i.test(line);
+    const emailRe = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/;
+    if (hasMailto && emailRe.test(line)) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 2,
+        rule: 'pii/mailto-in-source',
+        message: 'mailto: link exposes email in HTML. Consider <velin-email> for obfuscation.',
+        fixable: false,
+      });
+    }
+  });
+
+  return issues;
+}
+
+export function scanPIIJS(content, file) {
+  const issues = [];
+  const lines = content.split('\n');
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+
+    for (const { re, rule, msg } of SECRET_PATTERNS) {
+      if (re.test(line)) {
+        issues.push({
+          file,
+          line: ln,
+          severity: 0,
+          rule,
+          message: msg,
+          fixable: false,
+        });
+      }
+    }
+
+    const emails = [...line.matchAll(EMAIL_RE)].map((m) => m[0]);
+    for (const email of emails) {
+      if (isPlaceholderEmail(email)) continue;
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/hardcoded-email',
+        message: `Hardcoded email "${email}" in JavaScript.`,
+        fixable: true,
+        fix: (currentLine) => fixHardcodedEmailLine(currentLine),
+      });
+    }
+
+    if (/localStorage\.setItem\s*\([^)]*@/.test(line) || /sessionStorage\.setItem\s*\([^)]*@/.test(line)) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/localstorage-pii',
+        message: 'Storing email-like data in Web Storage may violate privacy policies.',
+        fixable: false,
+      });
+    }
+  });
+
+  return issues;
+}

package/cli/scanner-rules-data.js

@@ -0,0 +1,62 @@
+/**
+ * Scanner rule metadata for documentation and tooling.
+ * Scan logic lives in scanner.js / pii-scanner.js / perf-audit.js.
+ */
+
+/** @typedef {{ id: string, category: string, severity: string, message: string, fixHint?: string }} ScannerRuleMeta */
+
+/** @type {ScannerRuleMeta[]} */
+export const SCANNER_RULES = [
+  // Security — HTML
+  { id: 'security/no-inline-handler', category: 'security', severity: 'warning', message: 'Inline event handler found. Use addEventListener() instead.', fixHint: 'Move handler to JS module.' },
+  { id: 'security/no-javascript-url', category: 'security', severity: 'error', message: 'javascript: URL detected. XSS vector.', fixHint: 'Use button + script or href to safe URL.' },
+  { id: 'security/safe-external-link', category: 'security', severity: 'warning', message: 'target="_blank" without rel="noopener noreferrer".', fixHint: 'Add rel="noopener noreferrer" — auto-fix with --fix.' },
+  { id: 'security/no-meta-refresh', category: 'security', severity: 'error', message: '<meta http-equiv="refresh"> can redirect without consent.', fixHint: 'Use server redirect or JS with user action.' },
+  { id: 'security/no-inline-style', category: 'security', severity: 'warning', message: 'Inline style attribute increases XSS surface.', fixHint: 'Use VelinStyle utility classes.' },
+  { id: 'security/no-data-html-uri', category: 'security', severity: 'error', message: 'data:text/html URI can execute script.', fixHint: 'Avoid data: HTML URIs in href/src.' },
+  { id: 'security/dangerous-target', category: 'security', severity: 'warning', message: '<form target="_blank"> is unusual.', fixHint: 'Use same-tab navigation.' },
+  { id: 'security/integrity-missing', category: 'security', severity: 'info', message: 'External <script> without integrity (SRI).', fixHint: 'Add integrity + crossorigin for CDN scripts.' },
+  { id: 'security/csp-meta', category: 'security', severity: 'info', message: 'No CSP meta tag found.', fixHint: 'Add Content-Security-Policy header or meta.' },
+  // Security — JS
+  { id: 'security/no-raw-innerhtml', category: 'security', severity: 'warning', message: 'Direct innerHTML without sanitization.', fixHint: 'Use escapeHTML() from @birdapi/velinstyle/sanitize.' },
+  { id: 'security/no-document-write', category: 'security', severity: 'error', message: 'document.write() is dangerous.', fixHint: 'Use DOM APIs or template elements.' },
+  { id: 'security/no-eval', category: 'security', severity: 'error', message: 'eval() is a critical risk.', fixHint: 'Never use eval in production code.' },
+  { id: 'security/no-function-constructor', category: 'security', severity: 'error', message: 'new Function() equals eval().', fixHint: 'Refactor to static functions.' },
+  { id: 'security/postmessage-wildcard', category: 'security', severity: 'warning', message: 'postMessage with targetOrigin "*".', fixHint: 'Specify exact target origin.' },
+  // PII
+  { id: 'pii/hardcoded-email', category: 'pii', severity: 'warning', message: 'Hardcoded email in source.', fixHint: 'Use env/config or <velin-email>. --fix masks to placeholder.' },
+  { id: 'pii/mailto-in-source', category: 'pii', severity: 'info', message: 'mailto: exposes email in HTML.', fixHint: 'Consider <velin-email> obfuscation.' },
+  { id: 'pii/hardcoded-secret', category: 'pii', severity: 'error', message: 'Possible API key or secret in source.', fixHint: 'Use environment variables or secret manager.' },
+  { id: 'pii/localstorage-pii', category: 'pii', severity: 'warning', message: 'Email-like data in Web Storage.', fixHint: 'Avoid storing PII in localStorage.' },
+  // A11y
+  { id: 'a11y/html-lang', category: 'a11y', severity: 'error', message: '<html> missing lang attribute.', fixHint: 'Add lang="de" or appropriate locale — --fix.' },
+  { id: 'a11y/img-alt', category: 'a11y', severity: 'error', message: '<img> without alt.', fixHint: 'Add alt text or alt="" for decorative images.' },
+  { id: 'a11y/img-decorative', category: 'a11y', severity: 'warning', message: 'Decorative <img alt=""> without aria-hidden.', fixHint: 'Add aria-hidden="true" when visible text carries the meaning.' },
+  { id: 'a11y/velin-icon-label', category: 'a11y', severity: 'warning', message: 'velin-icon in icon-only button without label.', fixHint: 'Add label="…" on <velin-icon>.' },
+  { id: 'a11y/sparkline-label', category: 'a11y', severity: 'warning', message: 'velin-sparkline without accessible name.', fixHint: 'Add label attribute or wrap in <figure><figcaption>.' },
+  { id: 'a11y/skeleton-text', category: 'a11y', severity: 'warning', message: 'velin-skeleton on non-empty element.', fixHint: 'Use skeleton only on empty placeholders.' },
+  { id: 'a11y/button-label', category: 'a11y', severity: 'warning', message: '<button> without visible text or aria-label.', fixHint: 'Add text or aria-label.' },
+  { id: 'a11y/input-label', category: 'a11y', severity: 'warning', message: '<input> without label association.', fixHint: 'Use <label for> or aria-label.' },
+  { id: 'a11y/skip-link', category: 'a11y', severity: 'warning', message: 'No skip link for keyboard users.', fixHint: 'Add .velin-skip-link to #main — --fix when id="main" exists.' },
+  { id: 'a11y/landmark-main', category: 'a11y', severity: 'warning', message: 'No <main> landmark.', fixHint: 'Wrap primary content in <main>.' },
+  { id: 'a11y/heading-order', category: 'a11y', severity: 'warning', message: 'Heading levels skip (e.g. h2 → h4).', fixHint: 'Use sequential heading levels.' },
+  { id: 'a11y/interactive-aria-hidden', category: 'a11y', severity: 'error', message: 'Interactive element with aria-hidden="true".', fixHint: 'Remove aria-hidden or use inert.' },
+  { id: 'a11y/iframe-title', category: 'a11y', severity: 'error', message: '<iframe> without title.', fixHint: 'Add descriptive title attribute.' },
+  { id: 'a11y/autocomplete-auth', category: 'a11y', severity: 'warning', message: 'Auth field missing autocomplete (WCAG 2.2).', fixHint: 'Add autocomplete="username" or "current-password".' },
+  { id: 'a11y/invalid-describedby', category: 'a11y', severity: 'warning', message: 'aria-invalid without aria-describedby.', fixHint: 'Link to error message element id.' },
+  // CSS
+  { id: 'css/var-fallback', category: 'css', severity: 'info', message: 'CSS variable without fallback in var().', fixHint: 'Use var(--velin-*, fallback).' },
+  { id: 'css/z-index-token', category: 'css', severity: 'warning', message: 'Raw z-index instead of --velin-z-* token.', fixHint: 'Use tokens from z-index.css — --fix suggests token.' },
+  { id: 'css/no-important', category: 'css', severity: 'info', message: '!important usage.', fixHint: 'Prefer @layer and specificity.' },
+  { id: 'css/vendor-prefix', category: 'css', severity: 'info', message: 'Unnecessary vendor prefix.', fixHint: 'Lightning CSS handles autoprefixing.' },
+];
+
+/** @type {ScannerRuleMeta[]} */
+export const PERF_RULES = [
+  { id: 'perf/img-missing-dimensions', category: 'perf', severity: 'warning', message: '<img> without width/height causes CLS.', fixHint: 'Add width and height attributes — perf fix.' },
+  { id: 'perf/img-no-lazy', category: 'perf', severity: 'info', message: 'Consider loading="lazy" for below-fold images.', fixHint: 'Add loading="lazy".' },
+  { id: 'perf/script-no-defer', category: 'perf', severity: 'warning', message: 'External script without defer/async.', fixHint: 'Add defer or type="module".' },
+  { id: 'perf/large-inline-style', category: 'perf', severity: 'info', message: 'Large inline style block.', fixHint: 'Move to external CSS.' },
+  { id: 'perf/font-display-swap', category: 'perf', severity: 'info', message: '@font-face without font-display: swap.', fixHint: 'Add font-display: swap.' },
+  { id: 'perf/unused-velin-import', category: 'perf', severity: 'info', message: 'Full component bundle loaded.', fixHint: 'Use @birdapi/velinstyle/runtime for tree-shaking.' },
+];

package/cli/scanner.js

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
 import { join, relative, extname } from 'path';
 import { applyFixes, fixSafeExternalLinkLine, fixZIndexLine } from './apply-fixes.js';
+import { scanPIIHTML, scanPIIJS } from './pii-scanner.js';
+
+export { SCANNER_RULES, PERF_RULES } from './scanner-rules-data.js';
 
 const SEVERITY = { error: 0, warning: 1, info: 2 };
 const SEVERITY_LABEL = { 0: 'ERROR', 1: 'WARNING', 2: 'INFO' };
@@ -197,8 +200,10 @@ function scanSecurityJS(content, file) {
 
 function issueCategory(rule) {
   if (rule.startsWith('security/')) return 'security';
+  if (rule.startsWith('pii/')) return 'pii';
   if (rule.startsWith('a11y/')) return 'a11y';
   if (rule.startsWith('css/')) return 'css';
+  if (rule.startsWith('perf/')) return 'perf';
   return 'other';
 }
 
@@ -222,13 +227,25 @@ function scanA11yHTML(content, file) {
 
     const imgMatches = line.matchAll(/<img\b[^>]*>/gi);
     for (const m of imgMatches) {
-      if (!/\balt\s*=/i.test(m[0])) {
+      const tag = m[0];
+      if (!/\balt\s*=/i.test(tag)) {
         issues.push({
           file, line: ln, severity: 0,
           rule: 'a11y/img-alt',
           message: '<img> without alt attribute. Add alt="" for decorative or descriptive text.',
           fixable: false,
         });
+      } else if (
+        /\balt\s*=\s*["']\s*["']/i.test(tag)
+        && !/\baria-hidden\s*=\s*["']true["']/i.test(tag)
+        && !/\brole\s*=\s*["']presentation["']/i.test(tag)
+      ) {
+        issues.push({
+          file, line: ln, severity: 1,
+          rule: 'a11y/img-decorative',
+          message: 'Decorative <img alt=""> should include aria-hidden="true" so assistive tech ignores it consistently.',
+          fixable: false,
+        });
       }
     }
 
@@ -244,6 +261,31 @@ function scanA11yHTML(content, file) {
       }
     }
 
+    if (/<button\b[^>]*>[\s\S]*<velin-icon\b/i.test(line) && /<velin-icon\b(?![^>]*\blabel\s*=)/i.test(line)) {
+      issues.push({
+        file, line: ln, severity: 1,
+        rule: 'a11y/velin-icon-label',
+        message: '<velin-icon> inside icon-only <button> should have a label attribute.',
+        fixable: false,
+      });
+    }
+    if (/<velin-sparkline\b/i.test(line) && !/<velin-sparkline\b[^>]*\blabel\s*=/i.test(line) && !/<figcaption/i.test(line)) {
+      issues.push({
+        file, line: ln, severity: 1,
+        rule: 'a11y/sparkline-label',
+        message: '<velin-sparkline> needs label or a parent <figure> with <figcaption>.',
+        fixable: false,
+      });
+    }
+    if (/\bvelin-skeleton\b/i.test(line) && />\s*[^<\s][^<]+</i.test(line)) {
+      issues.push({
+        file, line: ln, severity: 1,
+        rule: 'a11y/skeleton-text',
+        message: 'velin-skeleton on elements with visible text may hide content from assistive tech.',
+        fixable: false,
+      });
+    }
+
     const inputMatches = line.matchAll(/<input\b[^>]*>/gi);
     for (const m of inputMatches) {
       const tag = m[0];
@@ -312,6 +354,27 @@ function scanA11yHTML(content, file) {
         });
       }
     }
+
+    if (/<form\b/i.test(line) && /type\s*=\s*["'](?:password|email)["']/i.test(line)) {
+      const formCtx = content.slice(Math.max(0, content.indexOf(line) - 800), content.indexOf(line) + 200);
+      if (/type\s*=\s*["']password["']/i.test(formCtx) && !/autocomplete\s*=/i.test(line) && !/autocomplete\s*=/i.test(formCtx)) {
+        issues.push({
+          file, line: ln, severity: 1,
+          rule: 'a11y/autocomplete-auth',
+          message: 'Auth field missing autocomplete (WCAG 2.2 / 1.3.5). Add autocomplete="username" or "current-password".',
+          fixable: false,
+        });
+      }
+    }
+
+    if (/aria-invalid\s*=\s*["']true["']/i.test(line) && !/aria-describedby/i.test(line)) {
+      issues.push({
+        file, line: ln, severity: 1,
+        rule: 'a11y/invalid-describedby',
+        message: 'aria-invalid without aria-describedby linking to error help text.',
+        fixable: false,
+      });
+    }
   });
 
   return issues;
@@ -396,10 +459,13 @@ export function scan(targetPath, options = {}) {
 
   let allIssues = [];
 
+  const fixEmailPlaceholder = options.fixEmailPlaceholder || 'user@example.com';
+
   for (const file of htmlFiles) {
     const content = readFileSync(file, 'utf-8');
     allIssues.push(...scanSecurityHTML(content, file));
     allIssues.push(...scanA11yHTML(content, file));
+    allIssues.push(...scanPIIHTML(content, file, { fixEmailPlaceholder }));
   }
 
   for (const file of cssFiles) {
@@ -410,6 +476,7 @@ export function scan(targetPath, options = {}) {
   for (const file of jsFiles) {
     const content = readFileSync(file, 'utf-8');
     allIssues.push(...scanSecurityJS(content, file));
+    allIssues.push(...scanPIIJS(content, file));
   }
 
   allIssues = allIssues.filter(i => i.severity <= minSeverity);

package/cli/search-index.js

@@ -0,0 +1,163 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, dirname, relative, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+const TITLE_RE = /^#\s+<([^>]+)>|^#\s+(.+)$/m;
+const H1_RE = /^#\s+(.+)$/m;
+
+function excerptFromMd(text, max = 160) {
+  const lines = text.split('\n');
+  for (const line of lines) {
+    if (line.startsWith('#') || !line.trim() || line.startsWith('|') || line.startsWith('<!--')) continue;
+    return line.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').replace(/`/g, '').trim().slice(0, max);
+  }
+  return '';
+}
+
+function slugId(category, name) {
+  return `${category}:${name}`.replace(/\s+/g, '-').toLowerCase();
+}
+
+function walkFiles(dir, cb) {
+  if (!existsSync(dir)) return;
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) walkFiles(full, cb);
+    else cb(full);
+  }
+}
+
+function collectMarkdown(dir, category, urlPrefix, weight = 1) {
+  const entries = [];
+  if (!existsSync(dir)) return entries;
+  walkFiles(dir, (full) => {
+    const name = basename(full);
+    if (!name.endsWith('.md') || name === 'README.md') return;
+    const text = readFileSync(full, 'utf-8');
+    const tagMatch = text.match(TITLE_RE);
+    const h1Match = text.match(H1_RE);
+    const title = tagMatch
+      ? (tagMatch[1] || tagMatch[2] || basename(name, '.md')).trim()
+      : (h1Match ? h1Match[1] : basename(name, '.md')).replace(/`/g, '').trim();
+    const rel = relative(dir, full).replace(/\\/g, '/');
+    const base = basename(name, '.md');
+    entries.push({
+      id: slugId(category, base),
+      title,
+      excerpt: excerptFromMd(text),
+      url: `${urlPrefix}${rel.replace(/\.md$/, '.html')}`,
+      category,
+      keywords: [base, category, title],
+      weight,
+    });
+  });
+  return entries;
+}
+
+function collectHtmlSamples(dirs) {
+  const entries = [];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    const walk = (folder) => {
+      for (const ent of readdirSync(folder, { withFileTypes: true })) {
+        const full = join(folder, ent.name);
+        if (ent.isDirectory()) walk(full);
+        else if (ent.name.endsWith('.html')) {
+          const text = readFileSync(full, 'utf-8');
+          const titleM = text.match(/<title>([^<]+)<\/title>/i);
+          const h1M = text.match(/<h1[^>]*>([^<]+)<\/h1>/i);
+          const title = (h1M?.[1] || titleM?.[1] || ent.name).replace(/<[^>]+>/g, '').trim();
+          const rel = relative(PKG_ROOT, full).replace(/\\/g, '/');
+          entries.push({
+            id: slugId('examples', rel),
+            title,
+            excerpt: rel,
+            url: rel,
+            category: 'examples',
+            keywords: [ent.name, 'sample', 'example'],
+            weight: 0.85,
+          });
+        }
+      }
+    };
+    walk(dir);
+  }
+  return entries;
+}
+
+function collectCliApi(manifestPath) {
+  const entries = [];
+  if (!existsSync(manifestPath)) return entries;
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  for (const cmd of manifest.commands || []) {
+    entries.push({
+      id: slugId('api', cmd.name || cmd.id),
+      title: `CLI: ${cmd.name || cmd.id}`,
+      excerpt: cmd.summary || cmd.description || '',
+      url: `docs/generated/cli/commands.html#${cmd.name || cmd.id}`,
+      category: 'api',
+      keywords: ['cli', cmd.name, ...(cmd.aliases || [])],
+      weight: 1.1,
+    });
+  }
+  return entries;
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.outFile]
+ * @param {string} [options.generatedDir]
+ * @param {string[]} [options.extraHtmlDirs]
+ */
+export function buildSearchIndex(options = {}) {
+  const generatedDir = options.generatedDir || join(PKG_ROOT, 'docs', 'generated');
+  const outFile = options.outFile || join(PKG_ROOT, 'dist', 'search-index.json');
+
+  const entries = [
+    ...collectMarkdown(join(generatedDir, 'components'), 'components', 'docs/generated/components/', 1.3),
+    ...collectMarkdown(join(generatedDir, 'tokens'), 'docs', 'docs/generated/tokens/', 1),
+    ...collectMarkdown(join(generatedDir, 'utilities'), 'docs', 'docs/generated/utilities/', 1),
+    ...collectMarkdown(join(generatedDir, 'cli'), 'api', 'docs/generated/cli/', 1.15),
+    ...collectMarkdown(join(generatedDir, 'rules'), 'docs', 'docs/generated/rules/', 0.95),
+    ...collectMarkdown(join(generatedDir, 'a11y'), 'docs', 'docs/generated/a11y/', 1),
+    ...collectMarkdown(join(generatedDir, 'attributes'), 'docs', 'docs/generated/attributes/', 1.2),
+    ...collectCliApi(join(PKG_ROOT, 'cli', 'cli-manifest.json')),
+    ...collectHtmlSamples([
+      join(PKG_ROOT, 'samples'),
+      join(PKG_ROOT, 'examples'),
+      ...(options.extraHtmlDirs || []),
+    ]),
+  ];
+
+  const seen = new Set();
+  const unique = [];
+  for (const e of entries) {
+    if (seen.has(e.id)) continue;
+    seen.add(e.id);
+    unique.push(e);
+  }
+
+  unique.sort((a, b) => a.title.localeCompare(b.title));
+
+  const payload = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    entries: unique,
+  };
+
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, JSON.stringify(payload, null, 2), 'utf-8');
+  return { ok: true, count: unique.length, outFile };
+}
+
+export function searchIndexMain(argv = process.argv.slice(2)) {
+  const outIdx = argv.indexOf('--out');
+  const extraIdx = argv.indexOf('--extra-html');
+  const outFile = outIdx !== -1 && argv[outIdx + 1] ? argv[outIdx + 1] : join(PKG_ROOT, 'dist', 'search-index.json');
+  const extra = extraIdx !== -1 && argv[extraIdx + 1] ? argv[extraIdx + 1].split(',') : [];
+  const result = buildSearchIndex({ outFile, extraHtmlDirs: extra });
+  console.log(`Wrote ${result.count} search entries → ${result.outFile}`);
+}