@pyreon/cli 0.15.0 → 0.18.0

package/src/doctor.ts

@@ -1,281 +1,114 @@
 /**
- * pyreon doctor — project-wide health check for AI-friendly development
+ * `pyreon doctor` — project-wide health audit.
  *
- * Runs a pipeline of checks:
- *  1. React pattern detection (imports, hooks, JSX attributes)
- *  2. Import source validation (@pyreon/* vs react/vue)
- *  3. Common Pyreon mistakes (signal without call, key vs by, etc.)
+ * PR 2 rewrites this entrypoint around the unified gate API
+ * (`packages/tools/cli/src/doctor/`). The orchestrator runs every
+ * gate in parallel, the aggregator builds a `DoctorReport` with a
+ * 0-100 score, the renderer formats it for text / JSON / GHA.
+ *
+ * The legacy single-purpose flags (`--audit-tests`, `--check-islands`,
+ * `--check-ssg`) are interpreted as `--only <gate>` shortcuts so any
+ * existing CI script that relied on the old shape keeps working.
+ * Without those flags, doctor runs the full fast-gate set + computes
+ * a score — the new default behaviour.
  *
  * Output modes:
- *  - Human-readable (default): colored terminal output
- *  - JSON (--json): structured output for AI agent consumption
- *  - CI (--ci): exits with code 1 on any error
+ *   - text (default): big-score banner + per-category bars + top-N findings
+ *   - --json: full `DoctorReport` as JSON
+ *   - --gha:  GitHub Actions annotation lines (one per finding)
  *
- * Fix mode (--fix): auto-applies safe transforms via migrateReactCode
+ * Modes:
+ *   - --full: enable slow gates (audit-types, bundle-budgets)
+ *   - --only <gates>: run ONLY the listed comma-separated gates
+ *   - --skip <gates>: exclude these gates
+ *   - --fix: auto-fix where possible (lint + react-patterns)
+ *   - --ci: exit non-zero on any error finding
  */
 
-import * as fs from 'node:fs'
-import * as path from 'node:path'
 import {
-  auditTestEnvironment,
-  type AuditRisk,
-  detectReactPatterns,
-  formatTestAudit,
-  hasReactPatterns,
-  migrateReactCode,
-  type ReactDiagnostic,
-} from '@pyreon/compiler'
+  runDoctor,
+  type GateName,
+  type OrchestratorOptions,
+} from './doctor/orchestrator'
+import { renderGha, renderJson, renderText } from './doctor/render'
+import type { DoctorReport } from './doctor/types'
+
+export type DoctorFormat = 'text' | 'json' | 'gha'
 
 export interface DoctorOptions {
   fix: boolean
+  /** Legacy boolean — interpreted as `format = 'json'` if true. */
   json: boolean
   ci: boolean
   cwd: string
+  /** Explicit format override (wins over `json` boolean). */
+  format?: DoctorFormat | undefined
+  /** Enable slow gates (audit-types, bundle-budgets). */
+  full?: boolean | undefined
+  /** Run ONLY these gates. */
+  only?: GateName[] | undefined
+  /** Skip these gates. */
+  skip?: GateName[] | undefined
+
+  // ── Legacy flags (mapped to --only shortcuts for back-compat) ────
   /**
-   * When true, run the test-environment audit (mock-vnode pattern
-   * detection) and append the result to the doctor output. Default
-   * false — the audit is scoped to test files only and isn't part of
-   * the React-migration check pipeline, so we gate it to avoid noise
-   * in the typical "is my migration done?" call.
+   * @deprecated Prefer `--only audit-tests`. Both forms behave
+   * identically: include the test-environment audit gate in the
+   * report. Kept so existing CI scripts continue to work.
    */
   auditTests?: boolean | undefined
-  /** Minimum risk level to include in the test-audit report. Default 'medium'. */
-  auditMinRisk?: AuditRisk | undefined
-}
-
-interface FileResult {
-  file: string
-  diagnostics: ReactDiagnostic[]
-  fixed: boolean
-}
-
-interface DoctorResult {
-  passed: boolean
-  files: FileResult[]
-  summary: {
-    filesScanned: number
-    filesWithIssues: number
-    totalErrors: number
-    totalFixable: number
-    totalFixed: number
-  }
-}
-
-export async function doctor(options: DoctorOptions): Promise<number> {
-  const startTime = performance.now()
-  const files = collectSourceFiles(options.cwd)
-  const result = runChecks(files, options)
-  const elapsed = Math.round(performance.now() - startTime)
-
-  if (options.json) {
-    printJson(result)
-  } else {
-    printHuman(result, elapsed)
-  }
-
-  // Test-environment audit — optional follow-on pass. We run AFTER the
-  // main React-migration output so a migration-focused run isn't
-  // contaminated; pass `--audit-tests` to see it. The exit code is
-  // unaffected since mock-vnode test risk is a "should review" signal,
-  // not a "broken build" signal.
-  if (options.auditTests) {
-    const auditResult = auditTestEnvironment(options.cwd)
-    if (options.json) {
-      console.log('')
-      console.log(JSON.stringify({ testAudit: auditResult }, null, 2))
-    } else {
-      console.log('')
-      console.log(formatTestAudit(auditResult, { minRisk: options.auditMinRisk ?? 'medium' }))
-      console.log('')
-    }
-  }
-
-  return result.summary.totalErrors
+  /** Minimum risk for the test-environment audit. Default 'medium'. */
+  auditMinRisk?: 'high' | 'medium' | 'low' | undefined
+  /** @deprecated Prefer `--only islands-audit`. */
+  checkIslands?: boolean | undefined
+  /** @deprecated Prefer `--only ssg-audit`. */
+  checkSsg?: boolean | undefined
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// File collection
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const sourceExtensions = new Set(['.tsx', '.jsx', '.ts', '.js'])
-const sourceIgnoreDirs = new Set([
-  'node_modules',
-  'dist',
-  'lib',
-  '.pyreon',
-  '.git',
-  '.next',
-  'build',
-])
-
-function shouldSkipDirEntry(entry: fs.Dirent): boolean {
-  if (!entry.isDirectory()) return false
-  return entry.name.startsWith('.') || sourceIgnoreDirs.has(entry.name)
-}
-
-function walkSourceFiles(dir: string, results: string[]): void {
-  let entries: fs.Dirent[]
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true })
-  } catch {
-    return
-  }
-
-  for (const entry of entries) {
-    if (shouldSkipDirEntry(entry)) continue
-
-    const fullPath = path.join(dir, entry.name)
-    if (entry.isDirectory()) {
-      walkSourceFiles(fullPath, results)
-    } else if (entry.isFile() && sourceExtensions.has(path.extname(entry.name))) {
-      results.push(fullPath)
-    }
-  }
+const resolveFormat = (options: DoctorOptions): DoctorFormat => {
+  if (options.format) return options.format
+  if (options.json) return 'json'
+  return 'text'
 }
 
-function collectSourceFiles(cwd: string): string[] {
-  const results: string[] = []
-  walkSourceFiles(cwd, results)
-  return results
+const resolveOnly = (options: DoctorOptions): GateName[] | undefined => {
+  if (options.only && options.only.length > 0) return options.only
+  // Legacy single-purpose flags → `--only` shortcuts.
+  const legacyOnly: GateName[] = []
+  if (options.auditTests) legacyOnly.push('audit-tests')
+  if (options.checkIslands) legacyOnly.push('islands-audit')
+  if (options.checkSsg) legacyOnly.push('ssg-audit')
+  return legacyOnly.length > 0 ? legacyOnly : undefined
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// Check pipeline
-// ═══════════════════════════════════════════════════════════════════════════════
-
-function checkFileWithFix(
-  file: string,
-  relPath: string,
-): { result: FileResult | null; fixCount: number } {
-  let code: string
-  try {
-    code = fs.readFileSync(file, 'utf-8')
-  } catch {
-    return { result: null, fixCount: 0 }
+export const doctor = async (options: DoctorOptions): Promise<number> => {
+  const orchestratorOpts: OrchestratorOptions = {
+    cwd: options.cwd,
+    full: options.full,
+    only: resolveOnly(options),
+    skip: options.skip,
+    fix: options.fix,
+    auditMinRisk: options.auditMinRisk,
   }
 
-  if (!hasReactPatterns(code)) return { result: null, fixCount: 0 }
-
-  const migrated = migrateReactCode(code, relPath)
-  if (migrated.changes.length > 0) {
-    fs.writeFileSync(file, migrated.code, 'utf-8')
-  }
-  const remaining = detectReactPatterns(migrated.code, relPath)
-  if (remaining.length > 0 || migrated.changes.length > 0) {
-    return {
-      result: { file: relPath, diagnostics: remaining, fixed: migrated.changes.length > 0 },
-      fixCount: migrated.changes.length,
-    }
-  }
-  return { result: null, fixCount: 0 }
-}
-
-function checkFileDetectOnly(file: string, relPath: string): FileResult | null {
-  let code: string
-  try {
-    code = fs.readFileSync(file, 'utf-8')
-  } catch {
-    return null
-  }
+  const report = await runDoctor(orchestratorOpts)
+  const format = resolveFormat(options)
 
-  if (!hasReactPatterns(code)) return null
-
-  const diagnostics = detectReactPatterns(code, relPath)
-  if (diagnostics.length > 0) {
-    return { file: relPath, diagnostics, fixed: false }
-  }
-  return null
-}
-
-function runChecks(files: string[], options: DoctorOptions): DoctorResult {
-  const fileResults: FileResult[] = []
-  let totalFixed = 0
-
-  for (const file of files) {
-    const relPath = path.relative(options.cwd, file)
-
-    if (options.fix) {
-      const { result, fixCount } = checkFileWithFix(file, relPath)
-      totalFixed += fixCount
-      if (result) fileResults.push(result)
-    } else {
-      const result = checkFileDetectOnly(file, relPath)
-      if (result) fileResults.push(result)
-    }
-  }
-
-  const totalErrors = fileResults.reduce((sum, f) => sum + f.diagnostics.length, 0)
-  const totalFixable = fileResults.reduce(
-    (sum, f) => sum + f.diagnostics.filter((d) => d.fixable).length,
-    0,
-  )
-
-  return {
-    passed: totalErrors === 0,
-    files: fileResults,
-    summary: {
-      filesScanned: files.length,
-      filesWithIssues: fileResults.length,
-      totalErrors,
-      totalFixable,
-      totalFixed,
-    },
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Output formatters
-// ═══════════════════════════════════════════════════════════════════════════════
-
-function printJson(result: DoctorResult): void {
-  console.log(JSON.stringify(result, null, 2))
-}
-
-function printFileResult(fileResult: FileResult): void {
-  if (fileResult.diagnostics.length === 0) return
-
-  console.log(`  ${fileResult.file}${fileResult.fixed ? ' (partially fixed)' : ''}`)
-
-  for (const diag of fileResult.diagnostics) {
-    const fixTag = diag.fixable ? ' [fixable]' : ''
-    console.log(`    ${diag.line}:${diag.column} — ${diag.message}${fixTag}`)
-    console.log(`      Current:   ${diag.current}`)
-    console.log(`      Suggested: ${diag.suggested}`)
-    console.log('')
+  if (format === 'json') {
+    console.log(renderJson(report))
+  } else if (format === 'gha') {
+    console.log(renderGha(report))
+  } else {
+    console.log(renderText(report, { cwd: options.cwd }))
   }
-}
 
-function printSummary(summary: DoctorResult['summary']): void {
-  console.log(
-    `  ${summary.totalErrors} issue${summary.totalErrors === 1 ? '' : 's'} in ${summary.filesWithIssues} file${summary.filesWithIssues === 1 ? '' : 's'}`,
-  )
-  if (summary.totalFixable > 0) {
-    console.log(`  ${summary.totalFixable} auto-fixable — run 'pyreon doctor --fix' to apply`)
-  }
-  console.log('')
+  // Exit code: in --ci mode, any error finding fails. Otherwise, only
+  // a non-zero is returned when there are findings AT ALL — so
+  // `pyreon doctor && echo green` works as a quick gate.
+  if (options.ci) return report.totals.errors
+  return report.totals.errors + report.totals.warnings + report.totals.infos
 }
 
-function printHuman(result: DoctorResult, elapsed: number): void {
-  const { summary } = result
-
-  console.log('')
-  console.log(`  Pyreon Doctor — scanned ${summary.filesScanned} files in ${elapsed}ms`)
-  console.log('')
-
-  if (result.passed && summary.totalFixed === 0) {
-    console.log('  ✓ No issues found. Your code is Pyreon-native!')
-    console.log('')
-    return
-  }
-
-  if (summary.totalFixed > 0) {
-    console.log(`  ✓ Auto-fixed ${summary.totalFixed} issue${summary.totalFixed === 1 ? '' : 's'}`)
-    console.log('')
-  }
-
-  for (const fileResult of result.files) {
-    printFileResult(fileResult)
-  }
-
-  printSummary(summary)
-}
+// Re-export the report types for external consumers (CI integrations,
+// AI agents, dashboards).
+export type { DoctorReport, GateName }

package/src/index.ts

@@ -4,12 +4,26 @@
  * @pyreon/cli — Developer tools for Pyreon
  *
  * Commands:
- *   pyreon doctor [--fix] [--json]  — Scan project for React patterns, bad imports, etc.
- *   pyreon context                  — Generate .pyreon/context.json for AI tools
+ *   pyreon doctor   — project-wide health audit (score + per-category bars + findings)
+ *   pyreon context  — generate .pyreon/context.json for AI tools
  */
 
 import { generateContext } from './context'
 import { type DoctorOptions, doctor } from './doctor'
+import type { GateName } from './doctor/orchestrator'
+
+const VALID_GATES: GateName[] = [
+  'react-patterns',
+  'pyreon-patterns',
+  'lint',
+  'distribution',
+  'doc-claims',
+  'audit-tests',
+  'islands-audit',
+  'ssg-audit',
+  'audit-types',
+  'bundle-budgets',
+]
 
 const args = process.argv.slice(2)
 const command = args[0]
@@ -19,18 +33,69 @@ function printUsage(): void {
   pyreon <command> [options]
 
   Commands:
-    doctor [--fix] [--json] [--ci] [--audit-tests] [--audit-min-risk <level>]
-                                     Scan for React patterns, bad imports, common mistakes.
-                                     --audit-tests appends mock-vnode test-audit (PR #197 class).
-                                     --audit-min-risk is high|medium|low (default medium).
+    doctor [options]                 Project-wide health audit with 0-100 score.
+                                     Runs 8 fast gates by default; --full enables 2 slow gates.
     context [--out <path>]           Generate .pyreon/context.json for AI tools
 
+  doctor options:
+    --fix                            Auto-fix what we can (lint + react-patterns).
+    --full                           Include slow gates (audit-types, bundle-budgets).
+    --only <gates>                   Run ONLY these gates (comma-separated).
+    --skip <gates>                   Skip these gates (comma-separated).
+    --format text|json|gha           Output format (default: text).
+    --json                           Shortcut for --format=json.
+    --gha                            Shortcut for --format=gha (GitHub Actions annotations).
+    --ci                             Exit non-zero on error findings only.
+    --audit-min-risk high|medium|low Minimum risk for test-env audit (default: medium).
+
+  doctor gates:
+    Fast: ${VALID_GATES.slice(0, 8).join(', ')}
+    Slow: ${VALID_GATES.slice(8).join(', ')} (require --full)
+
+  Legacy doctor flags (still work — map to --only shortcuts):
+    --audit-tests                    Equivalent to --only audit-tests
+    --check-islands                  Equivalent to --only islands-audit
+    --check-ssg                      Equivalent to --only ssg-audit
+
   Options:
     --help                           Show this help message
     --version                        Show version
 `)
 }
 
+const parseGateList = (raw: string | undefined): GateName[] | undefined => {
+  if (!raw) return undefined
+  const names = raw.split(',').map((s) => s.trim()).filter(Boolean)
+  const invalid = names.filter((n) => !VALID_GATES.includes(n as GateName))
+  if (invalid.length > 0) {
+    console.error(
+      `Unknown gate(s): ${invalid.join(', ')}. Valid: ${VALID_GATES.join(', ')}`,
+    )
+    process.exit(1)
+  }
+  return names as GateName[]
+}
+
+const getFlagValue = (flag: string): string | undefined => {
+  const idx = args.indexOf(flag)
+  if (idx < 0) return undefined
+  return args[idx + 1]
+}
+
+const parseFormat = (raw: string | undefined): DoctorOptions['format'] => {
+  if (!raw) return undefined
+  if (raw === 'text' || raw === 'json' || raw === 'gha') return raw
+  console.error(`--format must be text|json|gha, got '${raw}'`)
+  process.exit(1)
+}
+
+const parseMinRisk = (raw: string | undefined): DoctorOptions['auditMinRisk'] => {
+  if (!raw) return undefined
+  if (raw === 'high' || raw === 'medium' || raw === 'low') return raw
+  console.error(`--audit-min-risk must be high|medium|low, got '${raw}'`)
+  process.exit(1)
+}
+
 async function main(): Promise<void> {
   if (!command || command === '--help' || command === '-h') {
     printUsage()
@@ -43,19 +108,23 @@ async function main(): Promise<void> {
   }
 
   if (command === 'doctor') {
-    const riskIdx = args.indexOf('--audit-min-risk')
-    const rawRisk = riskIdx >= 0 ? args[riskIdx + 1] : undefined
-    if (rawRisk !== undefined && rawRisk !== 'high' && rawRisk !== 'medium' && rawRisk !== 'low') {
-      console.error(`--audit-min-risk must be high | medium | low, got '${rawRisk}'`)
-      process.exit(1)
-    }
+    const format = args.includes('--gha')
+      ? ('gha' as const)
+      : parseFormat(getFlagValue('--format'))
+
     const options: DoctorOptions = {
       fix: args.includes('--fix'),
       json: args.includes('--json'),
       ci: args.includes('--ci'),
       cwd: process.cwd(),
+      format,
+      full: args.includes('--full'),
+      only: parseGateList(getFlagValue('--only')),
+      skip: parseGateList(getFlagValue('--skip')),
       auditTests: args.includes('--audit-tests'),
-      auditMinRisk: rawRisk as DoctorOptions['auditMinRisk'],
+      auditMinRisk: parseMinRisk(getFlagValue('--audit-min-risk')),
+      checkIslands: args.includes('--check-islands'),
+      checkSsg: args.includes('--check-ssg'),
     }
     const exitCode = await doctor(options)
     if (options.ci && exitCode > 0) {
@@ -82,5 +151,5 @@ main().catch((err) => {
 })
 
 export type { ContextOptions, ProjectContext } from './context'
-export type { DoctorOptions } from './doctor'
+export type { DoctorOptions, DoctorReport, GateName } from './doctor'
 export { doctor, generateContext }