@etus/seven-skill 0.1.0-beta.1

package/cli/engine/detect-antipatterns.mjs

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+/**
+ * Public API facade for the Seven anti-pattern detector. Runtime engines live
+ * under cli/engine/engines/. Importing this module gives programmatic access;
+ * running it directly invokes the CLI.
+ */
+
+import { detectCli } from './cli/main.mjs'
+
+export {
+  ANTIPATTERNS,
+  RULE_ENGINE_SUPPORT,
+  RULE_EXEMPTIONS,
+  getAntipattern,
+  getRulesForCategory,
+  getRuleEngineSupport,
+  getRuleExemption,
+  getRuleIds,
+} from './registry/seven-antipatterns.mjs'
+export { CHECKS, runChecks } from './rules/checks.mjs'
+export { finding } from './findings.mjs'
+export { detectText } from './engines/regex/detect-text.mjs'
+export { detectHtml } from './engines/static-html/detect-html.mjs'
+export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs'
+export {
+  walkDir,
+  findOwningPackageName,
+  buildImportGraph,
+  detectFrameworkConfig,
+  isPortListening,
+  SCANNABLE_EXTENSIONS,
+  HTML_EXTENSIONS,
+  SKIP_DIRS,
+  FRAMEWORK_CONFIGS,
+} from './node/file-system.mjs'
+export { detectCli, formatFindings, collectFindings } from './cli/main.mjs'
+
+const invokedDirectly =
+  process.argv[1]?.endsWith('detect-antipatterns.mjs') ||
+  process.argv[1]?.endsWith('detect-antipatterns.mjs/')
+if (invokedDirectly) detectCli()

package/cli/engine/engines/browser/detect-url.mjs

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { finding } from '../../findings.mjs'
+
+// ─── Browser engine ─────────────────────────────────────────────────────────
+// Live-URL detector. Renders the page with Puppeteer (an optionalDependency),
+// injects the generated browser bundle (cli/engine/detect-antipatterns-
+// browser.js — registry + checks + the in-browser detector concatenated into
+// one IIFE), and calls `window.sevenDetect()`. Every element is checked with
+// the real `getComputedStyle`, so cascade-, layout-, and runtime-CSS-
+// dependent drift surfaces — the deep DOM walk static analysis cannot do.
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const BROWSER_BUNDLE_PATH = path.resolve(__dirname, '..', '..', 'detect-antipatterns-browser.js')
+
+async function loadPuppeteer() {
+  try {
+    const mod = await import('puppeteer')
+    return mod.default || mod
+  } catch {
+    throw new Error(
+      'The browser engine needs the optional `puppeteer` dependency. Install it with `pnpm add -D puppeteer`, or scan local files instead of a URL.'
+    )
+  }
+}
+
+function readBrowserBundle() {
+  try {
+    return fs.readFileSync(BROWSER_BUNDLE_PATH, 'utf-8')
+  } catch {
+    throw new Error(
+      `Browser detector bundle not found at ${BROWSER_BUNDLE_PATH}. Rebuild it with \`node build/build-browser-detector.mjs\`.`
+    )
+  }
+}
+
+// CI runners (GitHub Actions Ubuntu) block unprivileged user namespaces, so
+// Chrome cannot initialize its sandbox there. Disable the sandbox only in CI.
+function launchArgs() {
+  return process.env['CI'] ? ['--no-sandbox', '--disable-setuid-sandbox'] : []
+}
+
+/**
+ * Scan one already-loaded page: inject the bundle, run the in-browser
+ * detector, normalize the findings. Shared by the one-shot and reusable paths.
+ */
+async function scanPage(page, url, browserBundle, options = {}) {
+  const { ruleIds = null, only = null } = options
+  await page.evaluate(browserBundle)
+  const raw = await page.evaluate(() => {
+    if (typeof window.sevenDetect !== 'function') return []
+    return window.sevenDetect()
+  })
+  const restrict = ruleIds || only
+  let findings = raw.map((f) => finding(f.type, url, f.detail))
+  if (restrict && restrict.length > 0) {
+    findings = findings.filter((f) => restrict.includes(f.antipattern))
+  }
+  return findings
+}
+
+/**
+ * Long-lived browser detector for scanning several URLs in one process.
+ * @returns {Promise<{ browser: object, detectUrl: Function, close: Function }>}
+ */
+export async function createBrowserDetector(options = {}) {
+  const puppeteer = await loadPuppeteer()
+  const browserBundle = readBrowserBundle()
+  const browser = await puppeteer.launch({ headless: true, args: launchArgs() })
+  const viewport = options.viewport || { width: 1280, height: 800 }
+  return {
+    browser,
+    async detectUrl(url, scanOptions = {}) {
+      const page = await browser.newPage()
+      try {
+        await page.setViewport(viewport)
+        await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 })
+        return await scanPage(page, url, browserBundle, scanOptions)
+      } finally {
+        await page.close().catch(() => {})
+      }
+    },
+    async close() {
+      await browser.close().catch(() => {})
+    },
+  }
+}
+
+/**
+ * One-shot URL scan. Boots a browser, scans, tears down.
+ * @param {string} url
+ * @param {{ ruleIds?: string[], only?: string[] }} [options]
+ * @returns {Promise<Array>} normalized findings
+ */
+export async function detectUrl(url, options = {}) {
+  const detector = await createBrowserDetector()
+  try {
+    return await detector.detectUrl(url, options)
+  } finally {
+    await detector.close()
+  }
+}

package/cli/engine/engines/regex/detect-text.mjs

@@ -0,0 +1,508 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+import { isFullPage } from '../../shared/page.mjs'
+import { finding } from '../../findings.mjs'
+import { profileFindings, profileStep } from '../../profile/profiler.mjs'
+import { runChecks } from '../../rules/checks.mjs'
+
+// ─── Regex engine ───────────────────────────────────────────────────────────
+// Source-file detector. Two pipelines run over the raw file text:
+//  1. The Seven text checks (`runChecks`) — font, token, type-hint, fuchsia,
+//     pt-PT vocab, pure black/white, emoji, em-dash. They scan the whole file,
+//     so inline style= and class= attributes are covered without extraction.
+//  2. Regex matchers + page analyzers — the CSS/Tailwind shapes of the
+//     element- and page-level rules (side stripe, gradient text, bounce
+//     easing, layout transition, monotonous spacing, flat hierarchy, centered
+//     everything, glow). These mirror what the static-html cascade resolves,
+//     so a CSS or JSX file with no live document still surfaces the drift.
+// This is the default engine for non-HTML files and for `--fast` mode.
+
+const hasRounded = (line) => /\brounded(?:-\w+)?\b/.test(line)
+const hasBorderRadius = (line) => /border-radius/i.test(line)
+const isSafeElement = (line) =>
+  /<(?:blockquote|nav[\s>]|pre[\s>]|code[\s>]|a\s|input[\s>]|span[\s>])/i.test(line)
+
+function isNeutralBorderColor(str) {
+  const m = str.match(/solid\s+(#[0-9a-f]{3,8}|rgba?\([^)]+\)|\w+)/i)
+  if (!m) return false
+  const c = m[1].toLowerCase()
+  if (['gray', 'grey', 'silver', 'white', 'black', 'transparent', 'currentcolor'].includes(c)) return true
+  const hex = c.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/)
+  if (hex) {
+    const [r, g, b] = [parseInt(hex[1], 16), parseInt(hex[2], 16), parseInt(hex[3], 16)]
+    return Math.max(r, g, b) - Math.min(r, g, b) < 30
+  }
+  const shex = c.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])$/)
+  if (shex) {
+    const [r, g, b] = [
+      parseInt(shex[1] + shex[1], 16),
+      parseInt(shex[2] + shex[2], 16),
+      parseInt(shex[3] + shex[3], 16),
+    ]
+    return Math.max(r, g, b) - Math.min(r, g, b) < 30
+  }
+  return false
+}
+
+// A Tailwind border class carrying a real hue or a Seven semantic color —
+// i.e. an accent, not a neutral structural divider. `border-muted`,
+// `border-border`, `border-gray-*` are neutral and never a side-stripe.
+const COLORED_BORDER_CLASS_RE =
+  /\bborder-(?:[lrtbxy]-)?(?:(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}|primary|secondary|destructive|warning|success|info|accent|brand)\b/
+const hasColoredSideAccent = (line) => COLORED_BORDER_CLASS_RE.test(line)
+
+// Per-line matchers — each emits one Seven rule ID. `test(match, line)` gates
+// the hit; `fmt(match, line)` builds the snippet.
+const REGEX_MATCHERS = [
+  // --- Side-stripe border ---
+  // A Tailwind side border is a stripe only when it is >=2px AND carries a
+  // colored accent. A bare `border-l-2` (default/neutral color) is a
+  // structural divider, not the AI side-tab anti-pattern.
+  {
+    id: 'side-stripe-border',
+    regex: /\bborder-[lr]-(\d+)\b/g,
+    test: (m, line) => +m[1] >= 2 && hasColoredSideAccent(line),
+    fmt: (m) => m[0],
+  },
+  {
+    id: 'side-stripe-border',
+    regex: /border-(?:left|right)\s*:\s*(\d+)px\s+solid[^;]*/gi,
+    test: (m, line) => {
+      if (isSafeElement(line)) return false
+      if (isNeutralBorderColor(m[0])) return false
+      return +m[1] >= 2
+    },
+    fmt: (m) => m[0].replace(/\s*;?\s*$/, ''),
+  },
+  {
+    id: 'side-stripe-border',
+    regex: /border-(?:left|right)-width\s*:\s*(\d+)px/gi,
+    test: (m, line) => !isSafeElement(line) && +m[1] >= 2,
+    fmt: (m) => m[0],
+  },
+  {
+    id: 'side-stripe-border',
+    regex: /border-inline-(?:start|end)\s*:\s*(\d+)px\s+solid/gi,
+    test: (m, line) => !isSafeElement(line) && +m[1] >= 2,
+    fmt: (m) => m[0],
+  },
+  {
+    id: 'side-stripe-border',
+    regex: /border-inline-(?:start|end)-width\s*:\s*(\d+)px/gi,
+    test: (m, line) => !isSafeElement(line) && +m[1] >= 2,
+    fmt: (m) => m[0],
+  },
+  {
+    id: 'side-stripe-border',
+    regex: /border(?:Left|Right)\s*[:=]\s*["'`](\d+)px\s+solid/g,
+    test: (m) => +m[1] >= 2,
+    fmt: (m) => m[0],
+  },
+  // --- Pill on button ---
+  {
+    id: 'pill-on-button',
+    regex: /<button\b[^>]*\brounded-full\b[^>]*>/gi,
+    test: () => true,
+    fmt: () => 'rounded-full on <button>',
+  },
+  {
+    id: 'pill-on-button',
+    regex: /<button\b[^>]*border-radius\s*:\s*9999/gi,
+    test: () => true,
+    fmt: () => 'border-radius: 9999 on <button>',
+  },
+  // --- Decorative gradient text ---
+  {
+    id: 'gradient-text-decorative',
+    regex: /background-clip\s*:\s*text|-webkit-background-clip\s*:\s*text/gi,
+    test: (m, line) => /gradient/i.test(line),
+    fmt: () => 'background-clip: text + gradient',
+  },
+  {
+    id: 'gradient-text-decorative',
+    regex: /\bbg-clip-text\b/g,
+    test: (m, line) => /\bbg-gradient-to-/i.test(line),
+    fmt: () => 'bg-clip-text + bg-gradient',
+  },
+  // --- Gray on colored background ---
+  {
+    id: 'gray-on-color',
+    regex: /\btext-(?:gray|slate|zinc|neutral|stone)-(\d+)\b/g,
+    test: (m, line) =>
+      /\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/.test(
+        line
+      ),
+    fmt: (m, line) => {
+      const bg = line.match(
+        /\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/
+      )
+      return `${m[0]} on ${bg?.[0] || '?'}`
+    },
+  },
+  // --- Bounce / elastic easing ---
+  {
+    id: 'bounce-easing',
+    regex: /\banimate-bounce\b/g,
+    test: () => true,
+    fmt: () => 'animate-bounce (Tailwind)',
+  },
+  {
+    id: 'bounce-easing',
+    regex: /animation(?:-name)?\s*:\s*[^;]*\b(bounce|elastic|wobble|jiggle|spring)\b/gi,
+    test: () => true,
+    fmt: (m) => m[0],
+  },
+  {
+    id: 'bounce-easing',
+    regex: /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g,
+    test: (m) => {
+      const y1 = parseFloat(m[2])
+      const y2 = parseFloat(m[4])
+      return y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1
+    },
+    fmt: (m) => `cubic-bezier(${m[1]}, ${m[2]}, ${m[3]}, ${m[4]})`,
+  },
+  // --- Layout property transition ---
+  {
+    id: 'layout-transition',
+    regex: /transition\s*:\s*([^;{}]+)/gi,
+    test: (m) => {
+      const val = m[1].toLowerCase()
+      if (/\ball\b/.test(val)) return false
+      return /\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding\b|\bmargin\b/.test(val)
+    },
+    fmt: (m) => {
+      const found = m[1].match(
+        /\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi
+      )
+      return `transition: ${found ? found.join(', ') : m[1].trim()}`
+    },
+  },
+  {
+    id: 'layout-transition',
+    regex: /transition-property\s*:\s*([^;{}]+)/gi,
+    test: (m) => {
+      const val = m[1].toLowerCase()
+      if (/\ball\b/.test(val)) return false
+      return /\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding\b|\bmargin\b/.test(val)
+    },
+    fmt: (m) => {
+      const found = m[1].match(
+        /\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi
+      )
+      return `transition-property: ${found ? found.join(', ') : m[1].trim()}`
+    },
+  },
+]
+
+// Whole-file analyzers — one per page-level rule. Each returns an array of
+// `finding(...)` records and runs only when the content is a full page.
+const REGEX_ANALYZERS = [
+  // Flat type hierarchy
+  (content, filePath) => {
+    const sizes = new Set()
+    const REM = 16
+    let m
+    const sizeRe = /font-size\s*:\s*([\d.]+)(px|rem|em)\b/gi
+    while ((m = sizeRe.exec(content)) !== null) {
+      const px = m[2] === 'px' ? +m[1] : +m[1] * REM
+      if (px > 0 && px < 200) sizes.add(Math.round(px * 10) / 10)
+    }
+    const clampRe = /font-size\s*:\s*clamp\(\s*([\d.]+)(px|rem|em)\s*,\s*[^,]+,\s*([\d.]+)(px|rem|em)\s*\)/gi
+    while ((m = clampRe.exec(content)) !== null) {
+      sizes.add(Math.round((m[2] === 'px' ? +m[1] : +m[1] * REM) * 10) / 10)
+      sizes.add(Math.round((m[4] === 'px' ? +m[3] : +m[3] * REM) * 10) / 10)
+    }
+    const TW = {
+      'text-xs': 12, 'text-sm': 14, 'text-base': 16, 'text-lg': 18, 'text-xl': 20,
+      'text-2xl': 24, 'text-3xl': 30, 'text-4xl': 36, 'text-5xl': 48, 'text-6xl': 60,
+      'text-7xl': 72, 'text-8xl': 96, 'text-9xl': 128,
+    }
+    for (const [cls, px] of Object.entries(TW)) {
+      if (new RegExp(`\\b${cls}\\b`).test(content)) sizes.add(px)
+    }
+    if (sizes.size < 3) return []
+    const sorted = [...sizes].sort((a, b) => a - b)
+    const ratio = sorted[sorted.length - 1] / sorted[0]
+    if (ratio >= 2.0) return []
+    const lines = content.split('\n')
+    let line = 1
+    for (let i = 0; i < lines.length; i++) {
+      if (/font-size/i.test(lines[i]) || /\btext-(?:xs|sm|base|lg|xl|\d)/i.test(lines[i])) {
+        line = i + 1
+        break
+      }
+    }
+    return [
+      finding(
+        'flat-type-hierarchy',
+        filePath,
+        `Sizes: ${sorted.map((s) => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)`,
+        line
+      ),
+    ]
+  },
+  // Monotonous spacing
+  (content, filePath) => {
+    const vals = []
+    let m
+    const pxRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi
+    while ((m = pxRe.exec(content)) !== null) {
+      const v = +m[1]
+      if (v > 0 && v < 200) vals.push(v)
+    }
+    const remRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi
+    while ((m = remRe.exec(content)) !== null) {
+      const v = Math.round(parseFloat(m[1]) * 16)
+      if (v > 0 && v < 200) vals.push(v)
+    }
+    const gapRe = /gap\s*:\s*(\d+)px/gi
+    while ((m = gapRe.exec(content)) !== null) vals.push(+m[1])
+    const twRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g
+    while ((m = twRe.exec(content)) !== null) vals.push(+m[1] * 4)
+    const rounded = vals.map((v) => Math.round(v / 4) * 4)
+    if (rounded.length < 10) return []
+    const counts = {}
+    for (const v of rounded) counts[v] = (counts[v] || 0) + 1
+    const maxCount = Math.max(...Object.values(counts))
+    const pct = maxCount / rounded.length
+    const unique = [...new Set(rounded)].filter((v) => v > 0)
+    if (pct <= 0.6 || unique.length > 3) return []
+    const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0]
+    return [
+      finding(
+        'monotonous-spacing',
+        filePath,
+        `~${dominant}px used ${maxCount}/${rounded.length} times (${Math.round(pct * 100)}%)`
+      ),
+    ]
+  },
+  // Everything centered
+  (content, filePath) => {
+    const lines = content.split('\n')
+    let centered = 0
+    let total = 0
+    for (const line of lines) {
+      if (/<(?:h[1-6]|p|div|li|button)\b[^>]*>/i.test(line) && line.trim().length > 20) {
+        total++
+        if (/text-align\s*:\s*center/i.test(line) || /\btext-center\b/.test(line)) centered++
+      }
+    }
+    if (total < 5 || centered / total <= 0.7) return []
+    return [
+      finding(
+        'everything-centered',
+        filePath,
+        `${centered}/${total} text elements centered (${Math.round((centered / total) * 100)}%)`
+      ),
+    ]
+  },
+  // Glow on a dark surface
+  (content, filePath) => {
+    const darkBgRe = /background(?:-color)?\s*:\s*(?:#(?:0[0-9a-f]|1[0-9a-f]|2[0-3])[0-9a-f]{4}\b|#(?:0|1)[0-9a-f]{2}\b|rgb\(\s*(\d{1,2})\s*,\s*(\d{1,2})\s*,\s*(\d{1,2})\s*\))/gi
+    const twDarkBg = /\bbg-(?:gray|slate|zinc|neutral|stone)-(?:9\d{2}|800)\b/
+    const hasDarkBg = darkBgRe.test(content) || twDarkBg.test(content)
+    if (!hasDarkBg) return []
+    const shadowRe = /box-shadow\s*:\s*([^;{}]+)/gi
+    let m
+    while ((m = shadowRe.exec(content)) !== null) {
+      const val = m[1]
+      const colorMatch = val.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/)
+      if (!colorMatch) continue
+      const [r, g, b] = [+colorMatch[1], +colorMatch[2], +colorMatch[3]]
+      if (Math.max(r, g, b) - Math.min(r, g, b) < 30) continue
+      const pxVals = [...val.matchAll(/(\d+)px|(?<![.\d])\b(0)\b(?![.\d])/g)].map((p) => +(p[1] || p[2]))
+      if (pxVals.length >= 3 && pxVals[2] > 4) {
+        const lines = content.substring(0, m.index).split('\n')
+        return [finding('shadows-not-borders', filePath, `colored glow (rgb(${r},${g},${b})) on dark page`, lines.length)]
+      }
+    }
+    return []
+  },
+]
+
+// Rule IDs in REGEX_ANALYZERS index order — used to gate analyzers by ruleIds
+// and to label profiler events.
+const ANALYZER_RULE_IDS = [
+  'flat-type-hierarchy',
+  'monotonous-spacing',
+  'everything-centered',
+  'shadows-not-borders',
+]
+
+// ─── Style-block / CSS-in-JS extraction ─────────────────────────────────────
+
+function extractStyleBlocks(content, ext) {
+  ext = ext.toLowerCase()
+  if (ext !== '.vue' && ext !== '.svelte') return []
+  const blocks = []
+  const re = /<style[^>]*>([\s\S]*?)<\/style>/gi
+  let m
+  while ((m = re.exec(content)) !== null) {
+    const before = content.substring(0, m.index)
+    const startLine = before.split('\n').length + 1
+    blocks.push({ content: m[1], startLine })
+  }
+  return blocks
+}
+
+const CSS_IN_JS_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx'])
+
+function extractCSSinJS(content, ext) {
+  ext = ext.toLowerCase()
+  if (!CSS_IN_JS_EXTENSIONS.has(ext)) return []
+  const blocks = []
+  const re = /(?:styled(?:\.\w+|\([^)]+\))|css)\s*`([\s\S]*?)`/g
+  let m
+  while ((m = re.exec(content)) !== null) {
+    const before = content.substring(0, m.index)
+    const startLine = before.split('\n').length
+    blocks.push({ content: m[1], startLine })
+  }
+  return blocks
+}
+
+function runRegexMatchers(lines, filePath, lineOffset = 0, blockContext = null, options = {}) {
+  const { profile, phase = 'regex-matchers', ruleIds = null } = options || {}
+  const findings = []
+  const matchers = ruleIds ? REGEX_MATCHERS.filter((m) => ruleIds.includes(m.id)) : REGEX_MATCHERS
+  const scan = (matcher) => {
+    const matches = []
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      matcher.regex.lastIndex = 0
+      let m
+      while ((m = matcher.regex.exec(line)) !== null) {
+        const context = blockContext
+          ? lines.slice(Math.max(0, i - 3), Math.min(lines.length, i + 4)).join(' ')
+          : line
+        if (matcher.test(m, context)) {
+          matches.push(finding(matcher.id, filePath, matcher.fmt(m, context), i + 1 + lineOffset))
+        }
+      }
+    }
+    return matches
+  }
+  for (const matcher of matchers) {
+    if (!profile) {
+      findings.push(...scan(matcher))
+      continue
+    }
+    findings.push(
+      ...profileFindings(
+        profile,
+        { engine: 'regex', phase, ruleId: matcher.id, target: filePath },
+        () => scan(matcher)
+      )
+    )
+  }
+  return findings
+}
+
+/**
+ * @param {string} content  raw file text
+ * @param {string} filePath path reported in findings
+ * @param {{ ruleIds?: string[], profile?: object }} [options]
+ * @returns {Array} normalized findings
+ */
+function detectText(content, filePath, options = {}) {
+  const { ruleIds = null, profile } = options || {}
+  const findings = []
+  const lines = content.split('\n')
+  const ext = filePath ? (filePath.match(/\.\w+$/)?.[0] || '').toLowerCase() : ''
+
+  // Pipeline 1: the Seven text checks over the whole file.
+  const textFindings = profile
+    ? profileFindings(
+        profile,
+        { engine: 'regex', phase: 'text-checks', ruleId: 'seven-text-checks', target: filePath },
+        () => runChecks(content, ruleIds).map((r) => finding(r.id, filePath, r.snippet, r.line))
+      )
+    : runChecks(content, ruleIds).map((r) => finding(r.id, filePath, r.snippet, r.line))
+  findings.push(...textFindings)
+
+  // Pipeline 2: regex matchers over the source, plus extracted style blocks.
+  const cssLike = new Set(['.css', '.scss', '.less'])
+  findings.push(
+    ...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
+      profile,
+      phase: 'source',
+      ruleIds,
+    })
+  )
+
+  const styleBlocks = profile
+    ? profileStep(
+        profile,
+        { engine: 'regex', phase: 'extract', ruleId: 'style-blocks', target: filePath },
+        () => extractStyleBlocks(content, ext)
+      )
+    : extractStyleBlocks(content, ext)
+  for (const block of styleBlocks) {
+    const blockLines = block.content.split('\n')
+    findings.push(
+      ...runRegexMatchers(blockLines, filePath, block.startLine - 1, true, {
+        profile,
+        phase: 'style-block',
+        ruleIds,
+      })
+    )
+  }
+
+  const cssJsBlocks = profile
+    ? profileStep(
+        profile,
+        { engine: 'regex', phase: 'extract', ruleId: 'css-in-js', target: filePath },
+        () => extractCSSinJS(content, ext)
+      )
+    : extractCSSinJS(content, ext)
+  for (const block of cssJsBlocks) {
+    const blockLines = block.content.split('\n')
+    findings.push(
+      ...runRegexMatchers(blockLines, filePath, block.startLine - 1, true, {
+        profile,
+        phase: 'css-in-js',
+        ruleIds,
+      })
+    )
+  }
+
+  // Deduplicate (same antipattern + snippet within 2 lines).
+  const deduped = []
+  for (const f of findings) {
+    const isDupe = deduped.some(
+      (d) => d.antipattern === f.antipattern && d.snippet === f.snippet && Math.abs(d.line - f.line) <= 2
+    )
+    if (!isDupe) deduped.push(f)
+  }
+
+  // Pipeline 3: page-level analyzers — only on full pages.
+  if (isFullPage(content)) {
+    for (let i = 0; i < REGEX_ANALYZERS.length; i++) {
+      const ruleId = ANALYZER_RULE_IDS[i] || `analyzer-${i + 1}`
+      if (ruleIds && !ruleIds.includes(ruleId)) continue
+      const analyzer = REGEX_ANALYZERS[i]
+      deduped.push(
+        ...profileFindings(
+          profile,
+          { engine: 'regex', phase: 'page-analyzer', ruleId, target: filePath },
+          () => analyzer(content, filePath)
+        )
+      )
+    }
+  }
+
+  return deduped
+}
+
+export {
+  REGEX_MATCHERS,
+  REGEX_ANALYZERS,
+  ANALYZER_RULE_IDS,
+  extractStyleBlocks,
+  extractCSSinJS,
+  runRegexMatchers,
+  detectText,
+}