@pyreon/cli 0.16.0 → 0.18.0

package/src/doctor/render/text.ts

@@ -0,0 +1,206 @@
+/**
+ * Human-readable renderer for `DoctorReport`.
+ *
+ * Output shape (after react.doctor.com):
+ *   1. Big score banner with letter grade + label
+ *   2. Per-category bar chart (filled cells = score)
+ *   3. Top-N findings with severity icon, code, location, message, fix
+ *   4. Footer: skipped gates, totals, elapsed, run hints
+ *
+ * Colors degrade gracefully — see `ansi.ts:colorEnabled`.
+ */
+
+import type {
+  CategoryScore,
+  DoctorReport,
+  Finding,
+  Grade,
+  Severity,
+} from '../types'
+import {
+  bold,
+  cyan,
+  dim,
+  fileUrl,
+  gray,
+  green,
+  hyperlink,
+  red,
+  yellow,
+} from './ansi'
+
+const BAR_WIDTH = 12
+const FILLED = '█'
+const EMPTY = '░'
+
+const SEV_ICON: Record<Severity, string> = {
+  error: '✖',
+  warning: '⚠',
+  info: 'ℹ',
+}
+
+const colorForGrade = (g: Grade): ((s: string) => string) => {
+  if (g === 'A') return green
+  if (g === 'B' || g === 'C') return yellow
+  return red
+}
+
+const colorForSeverity = (s: Severity): ((str: string) => string) => {
+  if (s === 'error') return red
+  if (s === 'warning') return yellow
+  return cyan
+}
+
+const renderBar = (score: number, color: (s: string) => string): string => {
+  const filled = Math.round((score / 100) * BAR_WIDTH)
+  const empty = BAR_WIDTH - filled
+  return color(FILLED.repeat(filled)) + gray(EMPTY.repeat(empty))
+}
+
+const padRight = (s: string, n: number): string =>
+  s.length >= n ? s : s + ' '.repeat(n - s.length)
+
+const renderCategory = (c: CategoryScore): string => {
+  if (!c.included) {
+    return `  ${dim(padRight(c.category, 14))} ${gray('skipped')}`
+  }
+  const color = colorForGrade(c.grade)
+  const bar = renderBar(c.score, color)
+  const score = color(padRight(String(c.score), 3))
+  const breakdown =
+    c.errors + c.warnings + c.infos === 0
+      ? gray('clean')
+      : [
+          c.errors > 0 ? red(`${c.errors}E`) : '',
+          c.warnings > 0 ? yellow(`${c.warnings}W`) : '',
+          c.infos > 0 ? cyan(`${c.infos}i`) : '',
+        ]
+          .filter(Boolean)
+          .join(' ')
+  return `  ${padRight(c.category, 14)} ${bar} ${score} ${dim('·')} ${breakdown}`
+}
+
+const renderBanner = (report: DoctorReport): string => {
+  const gColor = colorForGrade(report.grade)
+  const score = gColor(bold(String(report.score)))
+  const grade = gColor(bold(report.grade))
+  const lines = [
+    '',
+    `  ${bold('pyreon doctor')} ${dim('· project health audit')}`,
+    '',
+    `  Score:  ${score}/100   Grade: ${grade}`,
+    '',
+  ]
+  return lines.join('\n')
+}
+
+const renderFinding = (f: Finding): string => {
+  const icon = colorForSeverity(f.severity)(SEV_ICON[f.severity])
+  const code = dim(f.code)
+  const header = `  ${icon} ${bold(f.message)}  ${code}`
+
+  const lines = [header]
+
+  if (f.location) {
+    const relPath = f.location.relPath || f.location.path
+    const lineCol = f.location.line
+      ? `:${f.location.line}${f.location.column !== undefined ? `:${f.location.column}` : ''}`
+      : ''
+    const visible = `${relPath}${lineCol}`
+    const linked = hyperlink(
+      cyan(visible),
+      fileUrl(f.location.path, f.location.line, f.location.column),
+    )
+    lines.push(`     ${linked}`)
+  }
+
+  if (f.relatedLocations && f.relatedLocations.length > 0) {
+    for (const rl of f.relatedLocations) {
+      const relPath = rl.relPath || rl.path
+      const lineCol = rl.line ? `:${rl.line}` : ''
+      const label = rl.label ? ` ${dim(`(${rl.label})`)}` : ''
+      lines.push(`     ${dim('↳')} ${cyan(relPath + lineCol)}${label}`)
+    }
+  }
+
+  if (f.fix) {
+    lines.push(`     ${dim('fix:')} ${f.fix}`)
+  }
+
+  return lines.join('\n')
+}
+
+const renderFindings = (report: DoctorReport, topN: number): string => {
+  if (report.findings.length === 0) {
+    return `  ${green('✓')} No findings. Your project is healthy.\n`
+  }
+
+  const shown = report.findings.slice(0, topN)
+  const remaining = report.findings.length - shown.length
+
+  const lines = [bold(`  Top findings (${shown.length} of ${report.findings.length}):`), '']
+  for (const f of shown) {
+    lines.push(renderFinding(f))
+    lines.push('')
+  }
+
+  if (remaining > 0) {
+    lines.push(
+      dim(
+        `  …and ${remaining} more. Run with ${bold('--json')} for the full list.`,
+      ),
+    )
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+const renderSkipped = (report: DoctorReport): string => {
+  const skipped = report.gates.filter((g) => g.meta.skipped)
+  if (skipped.length === 0) return ''
+  const names = skipped
+    .map((g) => `${g.gate}${g.meta.skipReason ? ` (${g.meta.skipReason})` : ''}`)
+    .join(', ')
+  return `  ${dim('Skipped:')} ${names}\n`
+}
+
+const renderFooter = (report: DoctorReport): string => {
+  const { errors, warnings, infos } = report.totals
+  const counts = [
+    errors > 0 ? red(`${errors} error${errors === 1 ? '' : 's'}`) : '',
+    warnings > 0 ? yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`) : '',
+    infos > 0 ? cyan(`${infos} info`) : '',
+  ]
+    .filter(Boolean)
+    .join(`${dim(' · ')}`)
+
+  const totalSummary = counts || green('no findings')
+  const elapsed = `${(report.elapsedMs / 1000).toFixed(1)}s`
+  return `  ${totalSummary} ${dim(`· ${report.gates.filter((g) => !g.meta.skipped).length} gates · ${elapsed}`)}\n`
+}
+
+export interface TextRenderOptions {
+  /** cwd kept for future relative-path display in findings (unused today). */
+  cwd?: string | undefined
+  /** Max findings to show in human output. Default 10. */
+  topN?: number | undefined
+}
+
+export const renderText = (
+  report: DoctorReport,
+  opts: TextRenderOptions = {},
+): string => {
+  const topN = opts.topN ?? 10
+  const sections = [
+    renderBanner(report),
+    bold('  Per category:'),
+    '',
+    ...report.categories.map(renderCategory),
+    '',
+    renderFindings(report, topN),
+    renderSkipped(report),
+    renderFooter(report),
+  ]
+  return sections.join('\n')
+}

package/src/doctor/report.ts

@@ -0,0 +1,61 @@
+/**
+ * `DoctorReport` aggregator — collects gate results, builds findings
+ * list, computes the 0-100 score, returns the report the renderers
+ * consume. Pure-function: takes gate results in, returns report out.
+ *
+ * The orchestration layer (which gates to run, in what order, with
+ * what timeout) lives in the doctor command itself; this module is
+ * just the "merge + score" step. Splitting them keeps the score
+ * formula testable in isolation and makes it trivial to add a new
+ * gate (drop into the orchestrator's list, no aggregator changes).
+ */
+
+import { computeScore } from './score'
+import type { DoctorReport, Finding, GateResult, Severity } from './types'
+
+const SEVERITY_RANK: Record<Severity, number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+}
+
+/**
+ * Sort findings: errors first, then warnings, then info. Within
+ * each severity, group by category for predictable output.
+ */
+const sortFindings = (findings: Finding[]): Finding[] =>
+  [...findings].sort((a, b) => {
+    const sevDelta = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    if (sevDelta !== 0) return sevDelta
+    if (a.category !== b.category) return a.category.localeCompare(b.category)
+    return a.code.localeCompare(b.code)
+  })
+
+export const buildReport = (gates: GateResult[]): DoctorReport => {
+  const findings = sortFindings(gates.flatMap((g) => g.findings))
+
+  const totals = {
+    errors: findings.filter((f) => f.severity === 'error').length,
+    warnings: findings.filter((f) => f.severity === 'warning').length,
+    infos: findings.filter((f) => f.severity === 'info').length,
+  }
+
+  const { score, grade, categories } = computeScore(findings, gates)
+
+  // Sum of per-gate elapsedMs — note this is NOT wall-clock if gates
+  // run in parallel. The orchestrator can override with a measured
+  // wall-clock when it has one; otherwise the sum is a useful proxy
+  // for "total work done".
+  const elapsedMs = gates.reduce((s, g) => s + g.meta.elapsedMs, 0)
+
+  return {
+    score,
+    grade,
+    categories,
+    gates,
+    findings,
+    totals,
+    elapsedMs,
+    timestamp: new Date().toISOString(),
+  }
+}

package/src/doctor/score.ts

@@ -0,0 +1,134 @@
+/**
+ * 0-100 health-score formula for `pyreon doctor`.
+ *
+ * Per-finding penalty by severity:
+ *   error   = 10 points
+ *   warning = 3 points
+ *   info    = 1 point
+ *
+ * Per-category subscore: `100 - clamp(sum(penalties), 0, 100)` — so
+ * 10 errors saturate to 0 in one category, 33 warnings = 1 point, etc.
+ * Linear-without-multiplier was chosen over multiplicative weighting
+ * because it gives the user predictable mental math: "fix one error,
+ * gain 10 points (capped at 100)".
+ *
+ * Overall score: simple mean of `included` category scores. Categories
+ * with no contributing gates are NOT included (a category that wasn't
+ * measured shouldn't pull the average up to 100). Five categories
+ * with equal weight gives any one bug class proportional impact —
+ * we don't try to weight "correctness > documentation" in code; the
+ * user reads the per-category bar chart and knows which to focus on.
+ *
+ * Letter grades:
+ *   A: 90+
+ *   B: 80-89
+ *   C: 70-79
+ *   D: 60-69
+ *   F: <60
+ *
+ * Reference: react.doctor uses a similar shape — score, letter, per-
+ * category bars. The constants are tuned for Pyreon's larger gate set
+ * (10+ vs react.doctor's 4).
+ */
+
+import type {
+  CategoryScore,
+  Finding,
+  FindingCategory,
+  GateResult,
+  Grade,
+  Severity,
+} from './types'
+
+const CATEGORIES: FindingCategory[] = [
+  'correctness',
+  'performance',
+  'architecture',
+  'testing',
+  'documentation',
+]
+
+const SEVERITY_WEIGHTS: Record<Severity, number> = {
+  error: 10,
+  warning: 3,
+  info: 1,
+}
+
+/** Pure scorer — no I/O, deterministic given findings. */
+export const scoreCategory = (
+  category: FindingCategory,
+  findings: Finding[],
+  included: boolean,
+): CategoryScore => {
+  const inCat = findings.filter((f) => f.category === category)
+  const errors = inCat.filter((f) => f.severity === 'error').length
+  const warnings = inCat.filter((f) => f.severity === 'warning').length
+  const infos = inCat.filter((f) => f.severity === 'info').length
+
+  const penalty =
+    errors * SEVERITY_WEIGHTS.error +
+    warnings * SEVERITY_WEIGHTS.warning +
+    infos * SEVERITY_WEIGHTS.info
+
+  const score = Math.max(0, Math.min(100, 100 - penalty))
+
+  return {
+    category,
+    score,
+    errors,
+    warnings,
+    infos,
+    grade: gradeFor(score),
+    included,
+  }
+}
+
+export const gradeFor = (score: number): Grade => {
+  if (score >= 90) return 'A'
+  if (score >= 80) return 'B'
+  if (score >= 70) return 'C'
+  if (score >= 60) return 'D'
+  return 'F'
+}
+
+/**
+ * Compute per-category subscores + overall score.
+ *
+ * `gates` is used to decide which categories are `included` — a
+ * category is included if at least one non-skipped gate emits in it.
+ * If no gate ran for `documentation`, the category is excluded from
+ * the overall mean rather than counted as 100/100.
+ */
+export const computeScore = (
+  findings: Finding[],
+  gates: GateResult[],
+): { score: number; grade: Grade; categories: CategoryScore[] } => {
+  // A category is included if any non-skipped gate's default category
+  // matches OR any finding lands in that category. The findings check
+  // covers the "lint emits a perf-flavored finding" cross-cutting case
+  // (lint's default category may be 'correctness' but its findings can
+  // still register a perf hit).
+  const includedCats = new Set<FindingCategory>()
+  for (const g of gates) {
+    if (!g.meta.skipped) includedCats.add(g.category)
+  }
+  for (const f of findings) {
+    includedCats.add(f.category)
+  }
+
+  const categories = CATEGORIES.map((c) =>
+    scoreCategory(c, findings, includedCats.has(c)),
+  )
+
+  const included = categories.filter((c) => c.included)
+  // No gates ran at all — degenerate case. Surface a perfect score
+  // with an A so the human path doesn't crash on division-by-zero,
+  // but the renderer should detect this and show "no gates ran".
+  if (included.length === 0) {
+    return { score: 100, grade: 'A', categories }
+  }
+
+  const sum = included.reduce((s, c) => s + c.score, 0)
+  const score = Math.round(sum / included.length)
+  return { score, grade: gradeFor(score), categories }
+}

package/src/doctor/types.ts

@@ -0,0 +1,196 @@
+/**
+ * Unified `Finding` + `GateResult` types shared by every doctor gate.
+ *
+ * Each programmatic gate (`runDistributionGate`, `runDocClaimsGate`, ...)
+ * returns `GateResult`. The aggregator in `pyreon doctor` merges every
+ * gate's findings into a `DoctorReport` with per-category subscores + an
+ * overall 0-100 health score — that aggregation layer lands in the
+ * follow-up PR (this PR is foundation-only).
+ *
+ * Why a unified shape now (PR 1) instead of together with the aggregator
+ * (PR 2): the gates are independently usable today via standalone scripts
+ * (`bun run check-distribution`, etc.). Locking the shape early means the
+ * scripts and the future aggregator consume the same `Finding[]` — no
+ * shim layer.
+ *
+ * Mirrors the existing per-detector shapes (`IslandFinding`, `SsgFinding`,
+ * `TestAuditEntry`) but elevated to a cross-gate vocabulary. Categories
+ * map onto the five react.doctor-style buckets so the score formula has
+ * a clear assignment per gate without case-by-case classification.
+ */
+
+export type FindingCategory =
+  | 'correctness'
+  | 'performance'
+  | 'architecture'
+  | 'testing'
+  | 'documentation'
+
+export type Severity = 'error' | 'warning' | 'info'
+
+/**
+ * A single actionable diagnostic. Every doctor gate emits Findings in
+ * this shape. Aggregation by category + severity drives the health score.
+ */
+export interface Finding {
+  /**
+   * Bucket the finding lands in for score aggregation. Each gate picks
+   * a default category for its emitted findings; an individual finding
+   * may override (e.g. a perf-flavored lint rule would still emit
+   * `category: 'performance'` even though the gate is `'lint'`).
+   */
+  category: FindingCategory
+
+  /** Severity drives per-finding weight in the score formula. */
+  severity: Severity
+
+  /**
+   * Stable code identifying the specific check. Format: `<gate>/<rule>`
+   * — e.g. `'audit-types/typed-but-unimplemented'`,
+   * `'distribution/missing-sideEffects'`, `'pyreon/for-missing-by'`.
+   * Used for filtering + cross-referencing in JSON output.
+   */
+  code: string
+
+  /**
+   * Identifier of the gate that produced this finding. Useful for
+   * grouping in human output and `--skip <gate>` filtering. Examples:
+   * `'lint'`, `'audit-types'`, `'check-distribution'`, `'islands-audit'`.
+   */
+  gate: string
+
+  /** One-paragraph human-readable explanation, including the fix path. */
+  message: string
+
+  /** Where the finding surfaces. Optional for project-wide findings. */
+  location?:
+    | {
+        /** Absolute path */
+        path: string
+        /** Path relative to the repo root for readable reporting */
+        relPath: string
+        /** 1-based line number */
+        line?: number | undefined
+        /** 1-based column number */
+        column?: number | undefined
+      }
+    | undefined
+
+  /**
+   * Companion locations for cross-file findings (e.g. duplicate-island-
+   * name lists the second occurrence). Surfaces in human output below
+   * the primary location with an `↳` marker.
+   */
+  relatedLocations?:
+    | Array<{
+        path: string
+        relPath: string
+        line?: number | undefined
+        column?: number | undefined
+        label?: string | undefined
+      }>
+    | undefined
+
+  /** Optional short fix hint shown under the message in human output. */
+  fix?: string | undefined
+
+  /**
+   * `true` if `pyreon doctor --fix` can auto-resolve this. Currently
+   * limited to lint findings whose rule has an auto-fixer.
+   */
+  fixable?: boolean | undefined
+}
+
+/**
+ * Result of running a single doctor gate. The aggregator collects N
+ * GateResults and computes the report.
+ */
+export interface GateResult {
+  /** Gate identifier (matches Finding.gate) */
+  gate: string
+
+  /**
+   * Default category for findings this gate produces. The aggregator
+   * uses this as the fallback when a Finding doesn't override
+   * `category` itself — but Finding.category is the source of truth
+   * for score attribution.
+   */
+  category: FindingCategory
+
+  /** All findings produced by this gate. May be empty. */
+  findings: Finding[]
+
+  /** Per-gate metadata for the human + JSON reports. */
+  meta: {
+    /** Number of files / packages / records the gate scanned. */
+    scanned?: number | undefined
+    /** Wall-clock duration in milliseconds. */
+    elapsedMs: number
+    /**
+     * `true` if the gate was skipped (e.g. `--skip <gate>`, missing
+     * prerequisite tool, mode-incompatible). The aggregator excludes
+     * skipped gates from the score and surfaces them in a "skipped"
+     * footer.
+     */
+    skipped?: boolean | undefined
+    /**
+     * Why the gate was skipped (only meaningful when `skipped: true`).
+     */
+    skipReason?: string | undefined
+  }
+}
+
+/** Convenience constructor for in-source readability. */
+export const finding = (f: Finding): Finding => f
+
+// ─── DoctorReport (PR 2 — aggregation + score) ──────────────────────────
+
+/**
+ * Per-category subscore + raw counts. The aggregator builds one
+ * `CategoryScore` per `FindingCategory`, then averages them into the
+ * overall score. Categories with no findings AND no contributing gates
+ * (skipped or filtered out) get `included: false` and are excluded
+ * from the mean — keeping a perfect 100 for an unmeasured category
+ * would be misleading.
+ */
+export interface CategoryScore {
+  category: FindingCategory
+  /** 0-100 subscore for this bucket */
+  score: number
+  errors: number
+  warnings: number
+  infos: number
+  /** Letter grade derived from `score` (A/B/C/D/F) */
+  grade: Grade
+  /** False if no gate covered this category — drop from mean */
+  included: boolean
+}
+
+export type Grade = 'A' | 'B' | 'C' | 'D' | 'F'
+
+/**
+ * Final aggregated report `pyreon doctor` produces. The renderer
+ * (text / json / gha) consumes this; gate orchestration is upstream.
+ */
+export interface DoctorReport {
+  /** 0-100 weighted mean of included `categories[].score` */
+  score: number
+  /** Letter grade for `score` */
+  grade: Grade
+  /** Per-category breakdown (always 5 entries — `included` flags coverage) */
+  categories: CategoryScore[]
+  /** Every gate that ran (or was skipped, with `meta.skipped: true`) */
+  gates: GateResult[]
+  /** Flat list of all findings across gates, ordered by severity then category */
+  findings: Finding[]
+  /** Aggregate counts across all findings */
+  totals: {
+    errors: number
+    warnings: number
+    infos: number
+  }
+  /** Top-level wall-clock — sum of gates' elapsedMs (parallel sum, not max) */
+  elapsedMs: number
+  /** ISO timestamp of when the report was produced (for diffing across runs) */
+  timestamp: string
+}

package/src/doctor/utils/walk.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared source-file walker for the per-file scanning gates
+ * (react-patterns, pyreon-patterns).
+ *
+ * The walker skips the standard non-source dirs (`node_modules`,
+ * `dist`, `lib`, `.git`, etc.) and matches `.ts` / `.tsx` / `.js` /
+ * `.jsx`. It's a thin wrapper around the original `collectSourceFiles`
+ * that lived in `doctor.ts` pre-PR-2; extracted here so any gate can
+ * use it without import-cycling through the doctor module.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+const SOURCE_EXTENSIONS = new Set(['.tsx', '.jsx', '.ts', '.js'])
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'lib',
+  '.pyreon',
+  '.git',
+  '.next',
+  'build',
+])
+
+const shouldSkipDirEntry = (entry: fs.Dirent): boolean => {
+  if (!entry.isDirectory()) return false
+  return entry.name.startsWith('.') || IGNORE_DIRS.has(entry.name)
+}
+
+const walk = (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()) {
+      walk(fullPath, results)
+    } else if (
+      entry.isFile() &&
+      SOURCE_EXTENSIONS.has(path.extname(entry.name))
+    ) {
+      results.push(fullPath)
+    }
+  }
+}
+
+export const collectSourceFiles = (cwd: string): string[] => {
+  const results: string[] = []
+  walk(cwd, results)
+  return results
+}