@pyreon/cli 0.16.0 → 0.18.0

package/src/doctor/gates/pyreon-patterns.ts

@@ -0,0 +1,70 @@
+/**
+ * pyreon-patterns gate — wraps `@pyreon/compiler:detectPyreonPatterns`.
+ *
+ * Catches "using Pyreon wrong" mistakes — 12 detector codes today
+ * (for-missing-by, props-destructured, signal-write-as-call, etc.).
+ * The detector matches the anti-patterns catalogue in
+ * `.claude/rules/anti-patterns.md` (entries tagged `[detector: ...]`)
+ * 1:1 — so the user reading the doctor output gets the same advice
+ * as someone running `validate` via MCP.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import {
+  detectPyreonPatterns,
+  hasPyreonPatterns,
+} from '@pyreon/compiler'
+
+import type { Finding, GateResult } from '../types'
+import { collectSourceFiles } from '../utils/walk'
+
+export interface PyreonPatternsGateOptions {
+  cwd: string
+}
+
+export const runPyreonPatternsGate = async (
+  opts: PyreonPatternsGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const files = collectSourceFiles(opts.cwd)
+
+  for (const file of files) {
+    let code: string
+    try {
+      code = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    if (!hasPyreonPatterns(code)) continue
+
+    const relPath = path.relative(opts.cwd, file)
+    const diagnostics = detectPyreonPatterns(code, relPath)
+
+    for (const diag of diagnostics) {
+      findings.push({
+        category: 'correctness',
+        severity: 'warning',
+        code: `pyreon-patterns/${diag.code}`,
+        gate: 'pyreon-patterns',
+        message: diag.message,
+        location: {
+          path: file,
+          relPath,
+          line: diag.line,
+          column: diag.column,
+        },
+        fix: diag.suggested,
+      })
+    }
+  }
+
+  return {
+    gate: 'pyreon-patterns',
+    category: 'correctness',
+    findings,
+    meta: { scanned: files.length, elapsedMs: Date.now() - start },
+  }
+}

package/src/doctor/gates/react-patterns.ts

@@ -0,0 +1,113 @@
+/**
+ * react-patterns gate — wraps `@pyreon/compiler:detectReactPatterns`.
+ *
+ * Catches "coming from React" mistakes: `useState` / `useEffect`,
+ * `className` / `htmlFor`, `onChange` on inputs, React-package
+ * imports, etc. The detector is already used standalone by the
+ * pre-PR-2 `pyreon doctor` legacy path; this adapter just emits its
+ * findings in the unified `Finding[]` shape so the v2 aggregator can
+ * fold them into the score.
+ *
+ * `--fix` mode delegates to `migrateReactCode` and reports BOTH the
+ * applied changes (as `info` findings) AND any residual diagnostics
+ * the migration didn't auto-resolve.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import {
+  detectReactPatterns,
+  hasReactPatterns,
+  migrateReactCode,
+} from '@pyreon/compiler'
+
+import type { Finding, GateResult } from '../types'
+import { collectSourceFiles } from '../utils/walk'
+
+export interface ReactPatternsGateOptions {
+  cwd: string
+  /** Apply `migrateReactCode` to each file with React patterns (writes to disk). */
+  fix?: boolean | undefined
+}
+
+export const runReactPatternsGate = async (
+  opts: ReactPatternsGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const files = collectSourceFiles(opts.cwd)
+
+  for (const file of files) {
+    let code: string
+    try {
+      code = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    if (!hasReactPatterns(code)) continue
+
+    const relPath = path.relative(opts.cwd, file)
+
+    if (opts.fix) {
+      const migrated = migrateReactCode(code, relPath)
+      if (migrated.changes.length > 0) {
+        fs.writeFileSync(file, migrated.code, 'utf-8')
+        for (const ch of migrated.changes) {
+          findings.push({
+            category: 'correctness',
+            severity: 'info',
+            code: `react-patterns/auto-fixed-${ch.type}`,
+            gate: 'react-patterns',
+            message: `Auto-fixed: ${ch.description}`,
+            location: { path: file, relPath, line: ch.line },
+          })
+        }
+      }
+      const remaining = detectReactPatterns(migrated.code, relPath)
+      for (const diag of remaining) {
+        findings.push({
+          category: 'correctness',
+          severity: diag.fixable ? 'warning' : 'error',
+          code: `react-patterns/${diag.code}`,
+          gate: 'react-patterns',
+          message: diag.message,
+          location: {
+            path: file,
+            relPath,
+            line: diag.line,
+            column: diag.column,
+          },
+          fix: diag.suggested,
+          fixable: diag.fixable,
+        })
+      }
+    } else {
+      const diagnostics = detectReactPatterns(code, relPath)
+      for (const diag of diagnostics) {
+        findings.push({
+          category: 'correctness',
+          severity: diag.fixable ? 'warning' : 'error',
+          code: `react-patterns/${diag.code}`,
+          gate: 'react-patterns',
+          message: diag.message,
+          location: {
+            path: file,
+            relPath,
+            line: diag.line,
+            column: diag.column,
+          },
+          fix: diag.suggested,
+          fixable: diag.fixable,
+        })
+      }
+    }
+  }
+
+  return {
+    gate: 'react-patterns',
+    category: 'correctness',
+    findings,
+    meta: { scanned: files.length, elapsedMs: Date.now() - start },
+  }
+}

package/src/doctor/gates/ssg-audit.ts

@@ -0,0 +1,57 @@
+/**
+ * ssg-audit gate — wraps `@pyreon/compiler:auditSsg`.
+ *
+ * SSG / ISR convention checker (M3.4): `_404.tsx` placement, dynamic
+ * routes missing `getStaticPaths`, non-literal revalidate exports.
+ * Severities mirror the gate's intent: missing-getStaticPaths is a
+ * warn (legit under `mode: 'ssr' | 'isr'`), the other two are errors
+ * (silently broken under `mode: 'ssg'`).
+ */
+
+import { auditSsg, type SsgFindingCode } from '@pyreon/compiler'
+
+import type { Finding, GateResult, Severity } from '../types'
+
+const SEVERITY_BY_CODE: Record<SsgFindingCode, Severity> = {
+  '404-outside-layout-dir': 'error',
+  'dynamic-route-missing-get-static-paths': 'warning',
+  'non-literal-revalidate-export': 'error',
+}
+
+export interface SsgAuditGateOptions {
+  cwd: string
+}
+
+export const runSsgAuditGate = async (
+  opts: SsgAuditGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const result = auditSsg(opts.cwd)
+
+  for (const f of result.findings) {
+    findings.push({
+      category: 'architecture',
+      severity: SEVERITY_BY_CODE[f.code] ?? 'error',
+      code: `ssg-audit/${f.code}`,
+      gate: 'ssg-audit',
+      message: f.message,
+      location: {
+        path: f.location.path,
+        relPath: f.location.relPath,
+        line: f.location.line,
+        column: f.location.column,
+      },
+    })
+  }
+
+  return {
+    gate: 'ssg-audit',
+    category: 'architecture',
+    findings,
+    meta: {
+      scanned: result.findings.length,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/orchestrator.ts

@@ -0,0 +1,176 @@
+/**
+ * Doctor orchestrator — picks the gate list per mode, runs them in
+ * parallel where safe, collects results, hands off to the aggregator.
+ *
+ * **Gate categorization by speed**:
+ *   - FAST gates (default): react-patterns, pyreon-patterns, lint,
+ *     distribution, doc-claims, islands-audit, ssg-audit, audit-tests.
+ *     Total runtime ~2-5s on the real Pyreon repo.
+ *   - SLOW gates (`--full` opt-in): audit-types (TS compiler-API walk
+ *     across 6 packages, ~1-30s), bundle-budgets (Bun.build of every
+ *     published package, ~15-30s).
+ *
+ * **Why parallel**: the gates are fully independent — no shared
+ * state, no file-write contention (only `--fix` writes, and lint /
+ * react-patterns target disjoint file patterns). Running them via
+ * `Promise.all` cuts wall-clock from ~5s sequential to ~1-2s for the
+ * fast set on a warm cache.
+ *
+ * **Skip filtering**: `--only` and `--skip` operate on gate names.
+ * Skipped gates appear in the report with `meta.skipped: true` so
+ * the renderer shows them in the footer ("Skipped: bundle-budgets").
+ */
+
+import {
+  runAuditTestsGate,
+  runAuditTypesGate,
+  runBundleBudgetsGate,
+  runDistributionGate,
+  runDocClaimsGate,
+  runIslandsAuditGate,
+  runLintGate,
+  runPyreonPatternsGate,
+  runReactPatternsGate,
+  runSsgAuditGate,
+} from './gates'
+import { buildReport } from './report'
+import type { DoctorReport, GateResult } from './types'
+
+export type GateName =
+  | 'react-patterns'
+  | 'pyreon-patterns'
+  | 'lint'
+  | 'distribution'
+  | 'doc-claims'
+  | 'audit-tests'
+  | 'islands-audit'
+  | 'ssg-audit'
+  | 'audit-types'
+  | 'bundle-budgets'
+
+/** Gates that run by default (fast). */
+const FAST_GATES: GateName[] = [
+  'react-patterns',
+  'pyreon-patterns',
+  'lint',
+  'distribution',
+  'doc-claims',
+  'islands-audit',
+  'ssg-audit',
+  'audit-tests',
+]
+
+/** Gates that require `--full` to enable. */
+const SLOW_GATES: GateName[] = ['audit-types', 'bundle-budgets']
+
+export interface OrchestratorOptions {
+  cwd: string
+  /** Enable slow gates (audit-types, bundle-budgets). */
+  full?: boolean | undefined
+  /** Run ONLY these gates (overrides `--full` / default selection). */
+  only?: GateName[] | undefined
+  /** Exclude these gates from whatever set would otherwise run. */
+  skip?: GateName[] | undefined
+  /** Apply auto-fixes where supported (lint + react-patterns). */
+  fix?: boolean | undefined
+  /** Min risk for the test-environment audit. Defaults to `'medium'`. */
+  auditMinRisk?: 'high' | 'medium' | 'low' | undefined
+}
+
+const skippedGate = (
+  gate: GateName,
+  category: GateResult['category'],
+  reason: string,
+): GateResult => ({
+  gate,
+  category,
+  findings: [],
+  meta: { elapsedMs: 0, skipped: true, skipReason: reason },
+})
+
+const ALL_GATE_CATEGORIES: Record<GateName, GateResult['category']> = {
+  'react-patterns': 'correctness',
+  'pyreon-patterns': 'correctness',
+  lint: 'correctness',
+  distribution: 'architecture',
+  'doc-claims': 'documentation',
+  'audit-tests': 'testing',
+  'islands-audit': 'architecture',
+  'ssg-audit': 'architecture',
+  'audit-types': 'architecture',
+  'bundle-budgets': 'performance',
+}
+
+/**
+ * Resolve which gates to run.
+ *
+ * Precedence: `--only` > `--skip` > (`--full` toggles slow gates) > default fast set.
+ */
+export const resolveGates = (opts: OrchestratorOptions): GateName[] => {
+  if (opts.only && opts.only.length > 0) {
+    const skip = new Set(opts.skip ?? [])
+    return opts.only.filter((g) => !skip.has(g))
+  }
+  const base: GateName[] = opts.full ? [...FAST_GATES, ...SLOW_GATES] : [...FAST_GATES]
+  const skip = new Set(opts.skip ?? [])
+  return base.filter((g) => !skip.has(g))
+}
+
+/**
+ * Run the gates and build the report. Wall-clock is measured here
+ * (vs the aggregator's sum-of-elapsedMs which is total CPU time).
+ */
+export const runDoctor = async (
+  opts: OrchestratorOptions,
+): Promise<DoctorReport> => {
+  const start = Date.now()
+  const selected = new Set(resolveGates(opts))
+  const all: GateName[] = [...FAST_GATES, ...SLOW_GATES]
+
+  const promises = all.map(async (gate): Promise<GateResult> => {
+    if (!selected.has(gate)) {
+      // Distinguish "user explicitly skipped" from "needs --full".
+      const reason = SLOW_GATES.includes(gate) && !opts.full
+        ? 'enable with --full'
+        : 'skipped'
+      return skippedGate(gate, ALL_GATE_CATEGORIES[gate], reason)
+    }
+    return runGate(gate, opts)
+  })
+
+  const gates = await Promise.all(promises)
+  const report = buildReport(gates)
+  // Overwrite the sum-of-elapsedMs proxy with the real wall-clock.
+  return { ...report, elapsedMs: Date.now() - start }
+}
+
+const runGate = async (
+  gate: GateName,
+  opts: OrchestratorOptions,
+): Promise<GateResult> => {
+  switch (gate) {
+    case 'react-patterns':
+      return runReactPatternsGate({ cwd: opts.cwd, fix: opts.fix })
+    case 'pyreon-patterns':
+      return runPyreonPatternsGate({ cwd: opts.cwd })
+    case 'lint':
+      return runLintGate({ cwd: opts.cwd, fix: opts.fix })
+    case 'distribution':
+      return runDistributionGate({ cwd: opts.cwd, skipPackProbe: true })
+    case 'doc-claims':
+      return runDocClaimsGate({ cwd: opts.cwd })
+    case 'audit-tests':
+      return runAuditTestsGate({
+        cwd: opts.cwd,
+        minRisk: opts.auditMinRisk ?? 'medium',
+      })
+    case 'islands-audit':
+      return runIslandsAuditGate({ cwd: opts.cwd })
+    case 'ssg-audit':
+      return runSsgAuditGate({ cwd: opts.cwd })
+    case 'audit-types':
+      return runAuditTypesGate({ cwd: opts.cwd })
+    case 'bundle-budgets':
+      return runBundleBudgetsGate({ cwd: opts.cwd })
+  }
+}

package/src/doctor/render/ansi.ts

@@ -0,0 +1,80 @@
+/**
+ * Minimal ANSI helpers for `pyreon doctor` human output.
+ *
+ * We deliberately don't pull in `chalk` / `kleur` / etc. — the doctor
+ * already lives in `@pyreon/cli` (the entrypoint package) and adding
+ * a runtime ANSI library bumps the install footprint. The escapes
+ * are tiny and stable.
+ *
+ * The `enabled` flag respects:
+ *   - `NO_COLOR=1`            → disable (de-facto standard)
+ *   - `FORCE_COLOR=1` / `0`   → force on / off
+ *   - `process.stdout.isTTY`  → default if no override
+ *   - CI tools like GitHub Actions set `CI=1` but their terminal DOES
+ *     render ANSI — so CI alone doesn't disable color.
+ */
+
+// ANSI control codes. ESC (char 27 / 0x1B) + open-bracket (CSI) for
+// SGR codes; ESC + close-bracket-8 for OSC-8 hyperlinks. We build the
+// strings via `String.fromCharCode(27)` rather than `` literals
+// so the source code stays free of non-printable bytes (some editors
+// + lint rules complain about raw ESC).
+const ESC = String.fromCharCode(27)
+const CSI = `${ESC}[`
+const OSC = `${ESC}]`
+// String terminator — ESC + backslash. BEL also works in most
+// terminals but ESC-\ is the spec-compliant form.
+const ST = `${ESC}\\`
+
+const isColorEnabled = (): boolean => {
+  if (process.env.NO_COLOR) return false
+  if (process.env.FORCE_COLOR === '0') return false
+  if (process.env.FORCE_COLOR) return true
+  return Boolean(process.stdout.isTTY)
+}
+
+export const colorEnabled = isColorEnabled()
+
+const wrap =
+  (open: string, close: string) =>
+  (s: string): string =>
+    colorEnabled ? `${CSI}${open}m${s}${CSI}${close}m` : s
+
+export const bold = wrap('1', '22')
+export const dim = wrap('2', '22')
+export const red = wrap('31', '39')
+export const green = wrap('32', '39')
+export const yellow = wrap('33', '39')
+export const blue = wrap('34', '39')
+export const magenta = wrap('35', '39')
+export const cyan = wrap('36', '39')
+export const gray = wrap('90', '39')
+
+/**
+ * OSC-8 hyperlink. iTerm2, WezTerm, kitty, modern VSCode terminals
+ * render this as a clickable link; other terminals show the visible
+ * text and ignore the escape. We use this for file paths so the user
+ * can cmd-click a finding's location and jump to it.
+ *
+ * `url` should be a `file://` URL with optional line/column:
+ *   `file:///path/to/file.ts#L42`
+ */
+export const hyperlink = (text: string, url: string): string => {
+  if (!colorEnabled) return text
+  return `${OSC}8;;${url}${ST}${text}${OSC}8;;${ST}`
+}
+
+/** Build a `file://` URL with optional line / column suffix. */
+export const fileUrl = (
+  absPath: string,
+  line?: number,
+  _column?: number,
+): string => {
+  // file:// URLs don't have a standard line/column shape across
+  // terminals; vscode uses `#L<line>`, iTerm2 + others use `:line:col`
+  // in the visible text but not the URL. We embed `#L<line>` since
+  // it's the form VSCode parses natively (the most common consumer).
+  let url = `file://${absPath}`
+  if (line !== undefined) url += `#L${line}`
+  return url
+}

package/src/doctor/render/gha.ts

@@ -0,0 +1,47 @@
+/**
+ * GitHub Actions annotation renderer.
+ *
+ * Emits per-finding `::error file=X,line=Y,col=Z::message` lines that
+ * GitHub Actions parses into inline PR annotations (clickable in the
+ * "Files changed" tab). One line per finding plus a summary header.
+ *
+ * Severity map: doctor `error` → GHA `error`, doctor `warning` →
+ * GHA `warning`, doctor `info` → GHA `notice`.
+ *
+ * Reference: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+
+import type { DoctorReport, Severity } from '../types'
+
+const GHA_LEVEL: Record<Severity, string> = {
+  error: 'error',
+  warning: 'warning',
+  info: 'notice',
+}
+
+const escape = (s: string): string =>
+  // GHA annotations require these chars URL-encoded
+  s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A')
+
+export const renderGha = (report: DoctorReport): string => {
+  const lines: string[] = []
+
+  // Summary header — visible at the top of the workflow log + on the
+  // job summary if `$GITHUB_STEP_SUMMARY` is also written.
+  lines.push(
+    `::notice::pyreon doctor score: ${report.score}/100 (${report.grade}) — ${report.totals.errors} errors, ${report.totals.warnings} warnings, ${report.totals.infos} info`,
+  )
+
+  for (const f of report.findings) {
+    const level = GHA_LEVEL[f.severity]
+    const props: string[] = []
+    props.push(`title=${escape(f.code)}`)
+    if (f.location?.relPath) props.push(`file=${escape(f.location.relPath)}`)
+    if (f.location?.line) props.push(`line=${f.location.line}`)
+    if (f.location?.column) props.push(`col=${f.location.column}`)
+    const msg = f.fix ? `${f.message} — ${f.fix}` : f.message
+    lines.push(`::${level} ${props.join(',')}::${escape(msg)}`)
+  }
+
+  return lines.join('\n')
+}

package/src/doctor/render/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel export for the three doctor renderers.
+ */
+
+export { renderText, type TextRenderOptions } from './text'
+export { renderJson } from './json'
+export { renderGha } from './gha'
+export * from './ansi'

package/src/doctor/render/json.ts

@@ -0,0 +1,16 @@
+/**
+ * Machine-readable JSON renderer. The full `DoctorReport` is
+ * structured for stable consumption — AI agents reading the output,
+ * CI dashboards, third-party tools all see the same shape.
+ *
+ * Backward-compatibility note: the legacy `doctor.ts` pre-PR-2
+ * emitted a different JSON shape (`{ passed, files, summary }`). The
+ * legacy `--json` is preserved via the compat path in the CLI
+ * orchestrator; this renderer is the new shape gated on `--format=json`
+ * (or default JSON when the v2 flag set is in use).
+ */
+
+import type { DoctorReport } from '../types'
+
+export const renderJson = (report: DoctorReport): string =>
+  JSON.stringify(report, null, 2)