@etus/seven-skill 0.1.0-beta.1

package/cli/bin/seven.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// 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.
+
+/**
+ * Seven CLI entry.
+ *
+ *   npx seven detect [file-or-dir-or-url...]   Scan for design anti-patterns
+ *   npx seven skills help|install|check        Manage the Seven skill
+ *   npx seven --help
+ *   npx seven --version
+ *
+ * Exit codes: 0 clean / 1 usage error / 2 findings present.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const args = process.argv.slice(2)
+const command = args[0]
+
+function printUsage() {
+  process.stdout.write(`Usage: seven <command> [options]
+
+Commands:
+  detect [file-or-dir-or-url...]   Scan for Seven design anti-patterns
+  skills help                      List the Seven skill and its commands
+  skills install                   Copy the built skill into ./.claude/skills
+  skills check                     Report skill install status
+
+Options:
+  --help       Show this help message
+  --version    Show version number
+
+Run 'seven detect --help' for detector options.
+`)
+}
+
+if (!command || command === '--help' || command === '-h') {
+  printUsage()
+  process.exit(0)
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'))
+  process.stdout.write(`${pkg.version}\n`)
+  process.exit(0)
+}
+
+if (command === 'detect') {
+  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)]
+  const { detectCli } = await import('../engine/cli/main.mjs')
+  await detectCli()
+} else if (command === 'skills') {
+  const { run } = await import('./commands/skills.mjs')
+  await run(args.slice(1))
+} else if (command === 'help') {
+  printUsage()
+  process.exit(0)
+} else {
+  // Bare `seven src/` shorthand: treat unknown leading args as detect targets.
+  process.argv = [process.argv[0], process.argv[1], ...args]
+  const { detectCli } = await import('../engine/cli/main.mjs')
+  await detectCli()
+}

package/cli/engine/browser/injected/index.mjs

@@ -0,0 +1,84 @@
+// 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.
+
+/*
+ * In-browser detector. This file is NOT a standalone module — it is
+ * concatenated by build/build-browser-detector.mjs into a single IIFE bundle
+ * (cli/engine/detect-antipatterns-browser.js) together with the registry,
+ * color helpers, constants, and the rule checks. It therefore references
+ * those symbols (`checkElement*DOM`, `checkPageQualityDOM`,
+ * `checkHtmlPatterns`) as free identifiers resolved within the bundle scope.
+ *
+ * The browser engine (engines/browser/detect-url.mjs) injects the bundle into
+ * a Puppeteer page and calls `window.sevenDetect()`. Each element is checked
+ * with the live `getComputedStyle`, so cascade-, layout-, and runtime-CSS-
+ * dependent drift surfaces — the per-element work the static-html engine does
+ * against a resolved cascade, here against the real browser.
+ *
+ * Impeccable's injected script also carries an inspector overlay, decoration,
+ * visual-contrast capture, and the Chrome-extension bridge. Those are
+ * extension UI, not detection — Seven has no extension, so they are omitted.
+ */
+
+;(function sevenInstallBrowserDetector() {
+  if (typeof window === 'undefined') return
+
+  function collectFindings() {
+    const out = []
+    const push = (arr) => {
+      if (!arr) return
+      for (const f of arr) out.push({ type: f.id, detail: f.snippet })
+    }
+
+    for (const el of document.querySelectorAll('*')) {
+      if (el === document.body || el === document.documentElement) continue
+      const tag = el.tagName ? el.tagName.toLowerCase() : ''
+      if (tag === 'script' || tag === 'style' || tag === 'head' || tag === 'meta' || tag === 'link') {
+        continue
+      }
+      try {
+        push(checkElementBordersDOM(el))
+        push(checkElementColorsDOM(el))
+        push(checkElementGlowDOM(el))
+        push(checkElementMotionDOM(el))
+        push(checkElementTactilePressDOM(el))
+        push(checkElementPillOnButtonDOM(el))
+        push(checkElementLucideIconDOM(el))
+        push(checkElementQualityDOM(el))
+      } catch {
+        // A malformed element must not abort the whole scan.
+      }
+    }
+
+    try {
+      push(checkPageQualityDOM())
+    } catch {
+      /* page-quality check failed — continue */
+    }
+
+    try {
+      // Regex-on-markup checks over the fully rendered HTML.
+      push(checkHtmlPatterns(document.documentElement.outerHTML))
+    } catch {
+      /* html-pattern check failed — continue */
+    }
+
+    return out
+  }
+
+  /**
+   * Public entry the browser engine calls. Returns a flat array of
+   * { type, detail } findings; detect-url.mjs maps it to normalized findings.
+   */
+  window.sevenDetect = function sevenDetect() {
+    try {
+      return collectFindings()
+    } catch {
+      return []
+    }
+  }
+
+  // Alias kept for parity with the impeccable browser API surface.
+  window.sevenScan = window.sevenDetect
+})()

package/cli/engine/cli/main.mjs

@@ -0,0 +1,215 @@
+// 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 { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs'
+import { detectHtml } from '../engines/static-html/detect-html.mjs'
+import { detectText } from '../engines/regex/detect-text.mjs'
+import {
+  HTML_EXTENSIONS,
+  detectFrameworkConfig,
+  findOwningPackageName,
+  isPortListening,
+  walkDir,
+} from '../node/file-system.mjs'
+import { FIXTURES_PATH_SEGMENT } from '../shared/constants.mjs'
+import { getRuleExemption, getRuleIds } from '../registry/seven-antipatterns.mjs'
+
+// ─── Exemption resolution ───────────────────────────────────────────────────
+// Decide which rules may run against a given file. Test fixtures are always
+// fully scanned. Otherwise a rule is skipped when the file sits in an exempt
+// package (resolved by the nearest package.json name) or under an exempt path
+// segment. This keeps the detector quiet on token-defining and skill-defining
+// source while still catching real consumer drift.
+
+function allowedRulesForFile(filePath, only = null, skip = null) {
+  let base = only && only.length > 0 ? getRuleIds().filter((id) => only.includes(id)) : getRuleIds()
+  if (skip && skip.length > 0) base = base.filter((id) => !skip.includes(id))
+  if (filePath.includes(FIXTURES_PATH_SEGMENT)) return base
+  const pkgName = findOwningPackageName(filePath)
+  return base.filter((id) => {
+    const exemption = getRuleExemption(id)
+    if (exemption.skipPathSegments.some((seg) => filePath.includes(seg))) return false
+    if (pkgName && exemption.skipPackages.has(pkgName)) return false
+    return true
+  })
+}
+
+// ─── Output formatting ──────────────────────────────────────────────────────
+
+export function formatFindings(findings, jsonMode) {
+  if (jsonMode) return JSON.stringify(findings, null, 2)
+  if (findings.length === 0) return 'No anti-patterns found.'
+
+  const grouped = {}
+  for (const f of findings) {
+    if (!grouped[f.file]) grouped[f.file] = []
+    grouped[f.file].push(f)
+  }
+  const out = []
+  for (const [file, items] of Object.entries(grouped)) {
+    out.push(`\n${file}`)
+    for (const item of items) {
+      out.push(`  ${item.line ? `line ${item.line}: ` : ''}[${item.antipattern}] ${item.snippet}`)
+      out.push(`    -> ${item.description}`)
+    }
+  }
+  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found.`)
+  return out.join('\n')
+}
+
+// ─── Per-target scanning ────────────────────────────────────────────────────
+
+async function scanFile(filePath, { fast = false, only = null, skip = null } = {}) {
+  const ext = path.extname(filePath).toLowerCase()
+  const ruleIds = allowedRulesForFile(filePath, only, skip)
+  if (ruleIds.length === 0) return []
+  if (!fast && HTML_EXTENSIONS.has(ext)) {
+    return detectHtml(filePath, { ruleIds })
+  }
+  let content
+  try {
+    content = fs.readFileSync(filePath, 'utf-8')
+  } catch {
+    return []
+  }
+  return detectText(content, filePath, { ruleIds })
+}
+
+/**
+ * Programmatic scan. Resolves each path (URL, file, or directory), routes it
+ * to the matching engine, applies per-file rule exemptions, and returns the
+ * combined findings. No formatting, no process.exit — `detectCli` wraps this.
+ *
+ * @param {string[]} paths
+ * @param {{ fast?: boolean, only?: string[], skip?: string[] }} [options]
+ * @returns {Promise<Array>} normalized findings
+ */
+export async function collectFindings(paths, options = {}) {
+  const { fast = false, only = null, skip = null } = options
+  const urlTargets = paths.filter((t) => /^https?:\/\//i.test(t))
+  const browserDetector = urlTargets.length > 1 ? await createBrowserDetector() : null
+  const findings = []
+  const restrict = (raw) => {
+    let out = raw
+    if (only && only.length > 0) out = out.filter((f) => only.includes(f.antipattern))
+    if (skip && skip.length > 0) out = out.filter((f) => !skip.includes(f.antipattern))
+    return out
+  }
+  try {
+    for (const target of paths) {
+      if (/^https?:\/\//i.test(target)) {
+        const scan = browserDetector ? (u) => browserDetector.detectUrl(u, { only }) : (u) => detectUrl(u, { only })
+        findings.push(...restrict(await scan(target)))
+        continue
+      }
+      const resolved = path.resolve(target)
+      let stat
+      try {
+        stat = fs.statSync(resolved)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) {
+        for (const file of walkDir(resolved)) {
+          findings.push(...(await scanFile(file, { fast, only, skip })))
+        }
+      } else if (stat.isFile()) {
+        findings.push(...(await scanFile(resolved, { fast, only, skip })))
+      }
+    }
+  } finally {
+    if (browserDetector) await browserDetector.close()
+  }
+  return findings
+}
+
+function printUsage() {
+  process.stdout.write(`Usage: seven detect [options] [file-or-dir-or-url...]
+
+Scan files or URLs for Seven Design System anti-patterns.
+
+Options:
+  --fast        Regex-only mode (skip linked-stylesheet resolution)
+  --json        Output results as JSON
+  --only=<ids>  Comma-separated rule IDs to run (default: all)
+  --help        Show this help message
+
+Detection engines:
+  Source files   Regex scan of the file text
+  HTML files     Static-HTML scan, resolves <link rel=stylesheet>
+  URLs           Browser render via Puppeteer (auto-detected; optional dep)
+
+Examples:
+  seven detect src/
+  seven detect packages/ui/src/components/Button
+  seven detect index.html
+  seven detect https://localhost:5173
+  seven detect --fast --json .
+`)
+}
+
+export async function detectCli() {
+  let args = process.argv.slice(2)
+  if (args[0] === 'detect') args = args.slice(1)
+  const jsonMode = args.includes('--json')
+  const helpMode = args.includes('--help') || args.includes('-h')
+  const fastMode = args.includes('--fast')
+  const onlyArg = args.find((a) => a.startsWith('--only='))
+  const only = onlyArg ? onlyArg.slice(7).split(',').map((s) => s.trim()).filter(Boolean) : null
+  const skipArg = args.find((a) => a.startsWith('--skip='))
+  const skip = skipArg ? skipArg.slice(7).split(',').map((s) => s.trim()).filter(Boolean) : null
+  const targets = args.filter((a) => !a.startsWith('-'))
+
+  if (helpMode) {
+    printUsage()
+    process.exit(0)
+  }
+
+  const paths = targets.length > 0 ? targets : [process.cwd()]
+
+  // One-time framework dev-server nudge for directory scans.
+  if (!jsonMode) {
+    for (const target of paths) {
+      if (/^https?:\/\//i.test(target)) continue
+      let stat
+      try {
+        stat = fs.statSync(path.resolve(target))
+      } catch {
+        continue
+      }
+      if (!stat.isDirectory()) continue
+      const fwConfig = detectFrameworkConfig(path.resolve(target))
+      if (!fwConfig) continue
+      const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint)
+      if (probe.listening && probe.matched) {
+        process.stderr.write(
+          `\n${fwConfig.name} dev server detected on localhost:${fwConfig.port}.\n` +
+            `For results that include runtime CSS, scan the running site:\n` +
+            `  npx seven detect http://localhost:${fwConfig.port}\n\n`
+        )
+      }
+    }
+  }
+
+  let findings = []
+  try {
+    findings = await collectFindings(paths, { fast: fastMode, only, skip })
+  } catch (e) {
+    process.stderr.write(`detect failed: ${e?.message ?? e}\n`)
+    process.exit(1)
+  }
+
+  if (findings.length > 0) {
+    const text = formatFindings(findings, jsonMode)
+    if (jsonMode) process.stdout.write(text + '\n')
+    else process.stderr.write(text + '\n')
+    process.exit(2)
+  }
+  if (jsonMode) process.stdout.write('[]\n')
+  else process.stdout.write('No anti-patterns found.\n')
+  process.exit(0)
+}