@pyreon/cli 0.16.0 → 0.18.0

package/src/doctor/gates/distribution.ts

@@ -0,0 +1,206 @@
+/**
+ * Distribution-hygiene gate — programmatic API.
+ *
+ * Two static invariants every published `@pyreon/*` package must hold:
+ *   1. `sideEffects` field declared (bundler tree-shaking)
+ *   2. `!lib/** /*.map` excluded from `files` array (no source-map ship)
+ *
+ * Plus a live `npm pack --dry-run` probe of `@pyreon/reactivity` to
+ * verify the exclusion actually works at publish time (the `files`
+ * field is technically right but npm's interpretation can diverge).
+ *
+ * Pure function — the standalone script `scripts/check-distribution.ts`
+ * is a thin wrapper that calls this and formats the output.
+ *
+ * Mirrors the script logic 1:1 — no behavior change, just makes the
+ * findings programmatically consumable by `pyreon doctor` aggregation
+ * (PR 2).
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { Finding, GateResult } from '../types'
+
+interface PackageInfo {
+  name: string
+  dir: string
+  pj: {
+    name?: string
+    private?: boolean
+    sideEffects?: unknown
+    files?: string[]
+    main?: string
+    exports?: unknown
+  }
+}
+
+const findPackages = (repoRoot: string): PackageInfo[] => {
+  const result: PackageInfo[] = []
+  const packagesRoot = join(repoRoot, 'packages')
+  if (!existsSync(packagesRoot)) return result
+  for (const cat of readdirSync(packagesRoot)) {
+    const catDir = join(packagesRoot, cat)
+    let pkgs: string[]
+    try {
+      pkgs = readdirSync(catDir)
+    } catch {
+      continue
+    }
+    for (const pkg of pkgs) {
+      const pkgDir = join(catDir, pkg)
+      const pjPath = join(pkgDir, 'package.json')
+      if (!existsSync(pjPath)) continue
+      let pj: PackageInfo['pj']
+      try {
+        pj = JSON.parse(readFileSync(pjPath, 'utf8'))
+      } catch {
+        continue
+      }
+      if (pj.private) continue
+      if (typeof pj.name !== 'string') continue
+      result.push({ name: pj.name, dir: pkgDir, pj })
+    }
+  }
+  return result
+}
+
+/**
+ * Pure parse-and-emit function for the `npm pack --dry-run` JSON
+ * output. Exported as `_internal` so tests can exercise the .map-
+ * detection + finding emission path without spawning the live npm
+ * subprocess — under CI parallel load the real probe runs 100s+,
+ * tripping the per-test timeout. Returns the finding (if any) for
+ * the caller to push onto the gate's findings array.
+ */
+export const _detectMapsInPackOutput = (
+  raw: string,
+  cwd: string,
+  probe: { dir: string },
+  probePackage: string,
+): Finding | null => {
+  const result = JSON.parse(raw) as Array<{ files: Array<{ path: string }> }>
+  const tarballFiles = result[0]?.files.map((f) => f.path) ?? []
+  const maps = tarballFiles.filter((f) => f.endsWith('.map'))
+  if (maps.length === 0) return null
+  return {
+    category: 'architecture',
+    severity: 'error',
+    code: 'distribution/tarball-contains-map',
+    gate: 'distribution',
+    message: `${probePackage}: npm pack --dry-run reported ${maps.length} .map file(s) in the would-be-published tarball: ${maps.slice(0, 3).join(', ')}${maps.length > 3 ? ', …' : ''}`,
+    location: {
+      path: join(probe.dir, 'package.json'),
+      relPath: relative(cwd, join(probe.dir, 'package.json')),
+    },
+  }
+}
+
+export interface DistributionGateOptions {
+  /**
+   * Repository root directory. The gate walks `<cwd>/packages/*` and
+   * shells out to `npm pack` from `<cwd>/packages/core/reactivity`.
+   */
+  cwd: string
+
+  /**
+   * Skip the `npm pack --dry-run` probe. Useful for unit tests +
+   * environments where npm isn't on PATH. Defaults to `false`.
+   */
+  skipPackProbe?: boolean
+
+  /**
+   * Package to probe via `npm pack --dry-run`. Defaults to
+   * `@pyreon/reactivity` — small, stable, canonical 4-element `files`
+   * shape used by ~37 other published packages.
+   */
+  probePackage?: string
+}
+
+/**
+ * Run the distribution-hygiene gate. Returns findings + metadata.
+ *
+ * @example
+ * const result = await runDistributionGate({ cwd: process.cwd() })
+ * if (result.findings.length > 0) process.exit(1)
+ */
+export const runDistributionGate = async (
+  opts: DistributionGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const probePackage = opts.probePackage ?? '@pyreon/reactivity'
+  const findings: Finding[] = []
+  const packages = findPackages(opts.cwd)
+
+  for (const p of packages) {
+    // Rule 1: sideEffects must be defined.
+    if (p.pj.sideEffects === undefined) {
+      findings.push({
+        category: 'architecture',
+        severity: 'error',
+        code: 'distribution/missing-sideEffects',
+        gate: 'distribution',
+        message: `${p.name} package.json must declare \`sideEffects\` (use \`false\` for pure libraries, an array of paths for entry-point side effects) — required for bundler tree-shaking.`,
+        location: {
+          path: join(p.dir, 'package.json'),
+          relPath: relative(opts.cwd, join(p.dir, 'package.json')),
+        },
+        fix: 'Add `"sideEffects": false` to package.json',
+      })
+    }
+
+    // Rule 2: if the package ships `lib`, the `files` array must
+    // exclude source maps.
+    if (Array.isArray(p.pj.files) && p.pj.files.includes('lib')) {
+      if (!p.pj.files.includes('!lib/**/*.map')) {
+        findings.push({
+          category: 'architecture',
+          severity: 'error',
+          code: 'distribution/missing-map-exclusion',
+          gate: 'distribution',
+          message: `${p.name} package.json \`files\` must include \`"!lib/**/*.map"\` to exclude source maps from the published tarball.`,
+          location: {
+            path: join(p.dir, 'package.json'),
+            relPath: relative(opts.cwd, join(p.dir, 'package.json')),
+          },
+          fix: 'Add `"!lib/**/*.map"` to the `files` array',
+        })
+      }
+    }
+  }
+
+  // Rule 3: live `npm pack --dry-run` probe.
+  if (!opts.skipPackProbe) {
+    const probe = packages.find((p) => p.name === probePackage)
+    if (probe) {
+      try {
+        const out = execFileSync('npm', ['pack', '--dry-run', '--json'], {
+          cwd: probe.dir,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        const finding = _detectMapsInPackOutput(
+          out,
+          opts.cwd,
+          probe,
+          probePackage,
+        )
+        if (finding) findings.push(finding)
+      } catch {
+        // npm not available or pack failed — silently skip. Locally
+        // this might run in an environment where npm isn't on PATH
+        // (Bun-only setup); CI has npm so the gate fires there.
+      }
+    }
+  }
+
+  return {
+    gate: 'distribution',
+    category: 'architecture',
+    findings,
+    meta: {
+      scanned: packages.length,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/gates/doc-claims.ts

@@ -0,0 +1,240 @@
+/**
+ * Doc-claims gate — programmatic API.
+ *
+ * Catches numeric-drift between human-written docs and the underlying
+ * source of truth. Recurring failure mode: a hand-quoted count
+ * ("34 signal-based hooks…") appears in 3-5 places; one bumps when a
+ * new hook lands, the others don't. Audit caught the README claiming
+ * 16 vs actual 34 — drift that shipped to users for weeks.
+ *
+ * Pure function — `scripts/check-doc-claims.ts` wraps this for the
+ * standalone CLI invocation.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Finding, GateResult } from '../types'
+
+interface ClaimSpec {
+  /** Doc file relative to repo root */
+  file: string
+  /** Capture group 1 must contain the number */
+  pattern: RegExp
+  /** Optional pattern variant for "X+" hedged claims (also wrong) */
+  rejectHedged?: RegExp
+}
+
+interface ClaimCheck {
+  /** Human-readable name shown in findings */
+  name: string
+  /** Stable code suffix used in `Finding.code` */
+  codeId: string
+  /** Source-of-truth function — produces the actual count */
+  actual: (repoRoot: string) => number
+  /** Doc files that carry the claim */
+  claims: ClaimSpec[]
+}
+
+const countHookExports = (repoRoot: string): number => {
+  const indexPath = join(repoRoot, 'packages/fundamentals/hooks/src/index.ts')
+  if (!existsSync(indexPath)) return 0
+  const source = readFileSync(indexPath, 'utf8')
+  const matched = source.matchAll(
+    /^export \{ (?:default as )?(use[A-Z][a-zA-Z]+) \}/gm,
+  )
+  const names = new Set<string>()
+  for (const [, name] of matched) {
+    if (name) names.add(name)
+  }
+  return names.size
+}
+
+const countDocPages = (repoRoot: string): number => {
+  const docsDir = join(repoRoot, 'docs')
+  if (!existsSync(docsDir)) return 0
+  let count = 0
+  const walk = (dir: string): void => {
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of entries) {
+      if (
+        name === 'node_modules' ||
+        name === 'cache' ||
+        name === 'dist' ||
+        name.startsWith('.')
+      ) {
+        continue
+      }
+      const full = join(dir, name)
+      let isDir = false
+      try {
+        isDir = statSync(full).isDirectory()
+      } catch {
+        continue
+      }
+      if (isDir) walk(full)
+      else if (name.endsWith('.md')) count++
+    }
+  }
+  walk(docsDir)
+  return count
+}
+
+const checks: ClaimCheck[] = [
+  {
+    name: 'hook export count',
+    codeId: 'hook-count',
+    actual: countHookExports,
+    claims: [
+      {
+        file: 'packages/fundamentals/hooks/README.md',
+        pattern: /^(\d+) signal-based reactive utilities/m,
+      },
+      {
+        file: 'packages/fundamentals/hooks/src/manifest.ts',
+        pattern: /'(\d+) signal-based hooks:/,
+      },
+      {
+        file: 'packages/fundamentals/hooks/src/manifest.ts',
+        pattern: /Signal-based hooks for Pyreon — (\d+) reactive primitives/,
+      },
+      {
+        file: 'CLAUDE.md',
+        pattern: /\| `@pyreon\/hooks` *\| (\d+) signal-based hooks/,
+        rejectHedged: /\| `@pyreon\/hooks` *\| (\d+)\+ signal-based hooks/,
+      },
+      {
+        file: 'CLAUDE.md',
+        pattern: /^- (\d+) signal-based hooks across 6 categories/m,
+      },
+      {
+        file: 'docs/docs/index.md',
+        pattern: /\| (\d+) signal-based hooks for common UI patterns/,
+      },
+    ],
+  },
+  {
+    name: 'doc page count',
+    codeId: 'doc-count',
+    actual: countDocPages,
+    claims: [
+      {
+        file: 'CLAUDE.md',
+        pattern: /(\d+) doc pages covering all packages/,
+      },
+    ],
+  },
+]
+
+export interface DocClaimsGateOptions {
+  /** Repository root directory */
+  cwd: string
+}
+
+export const runDocClaimsGate = async (
+  opts: DocClaimsGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+
+  // The claim sites are Pyreon-monorepo-specific paths (hooks README,
+  // CLAUDE.md, docs/docs/index.md, etc.). In a downstream consumer
+  // project NONE of them exist — firing the gate would emit a flood of
+  // spurious file-missing errors that don't reflect any real problem.
+  // Skip when zero claim files are present: signal that the gate
+  // doesn't apply rather than blame the user for not being Pyreon.
+  const anyClaimExists = checks.some((c) =>
+    c.claims.some((cl) => existsSync(join(opts.cwd, cl.file))),
+  )
+  if (!anyClaimExists) {
+    return {
+      gate: 'doc-claims',
+      category: 'documentation',
+      findings: [],
+      meta: {
+        scanned: 0,
+        elapsedMs: Date.now() - start,
+        skipped: true,
+        skipReason:
+          'no claim sites found in this project (gate targets Pyreon monorepo paths)',
+      },
+    }
+  }
+
+  for (const check of checks) {
+    const actual = check.actual(opts.cwd)
+    for (const claim of check.claims) {
+      const filePath = join(opts.cwd, claim.file)
+      const relPath = claim.file
+
+      if (!existsSync(filePath)) {
+        findings.push({
+          category: 'documentation',
+          severity: 'error',
+          code: `doc-claims/${check.codeId}-file-missing`,
+          gate: 'doc-claims',
+          message: `${check.name}: claim file ${claim.file} not found (claim may have been deleted or moved). Actual: ${actual}.`,
+          location: { path: filePath, relPath },
+        })
+        continue
+      }
+      const content = readFileSync(filePath, 'utf8')
+
+      if (claim.rejectHedged) {
+        const hedged = content.match(claim.rejectHedged)
+        if (hedged?.[1]) {
+          findings.push({
+            category: 'documentation',
+            severity: 'error',
+            code: `doc-claims/${check.codeId}-hedged`,
+            gate: 'doc-claims',
+            message: `${check.name}: rejected hedged claim "${hedged[1]}+" in ${claim.file} — write the exact count instead. Actual: ${actual}.`,
+            location: { path: filePath, relPath },
+            fix: `Replace "${hedged[1]}+" with "${actual}"`,
+          })
+          continue
+        }
+      }
+
+      const match = content.match(claim.pattern)
+      const claimedRaw = match?.[1]
+      if (!claimedRaw) {
+        findings.push({
+          category: 'documentation',
+          severity: 'warning',
+          code: `doc-claims/${check.codeId}-pattern-miss`,
+          gate: 'doc-claims',
+          message: `${check.name}: pattern not found in ${claim.file} (claim was likely deleted or rephrased). Actual: ${actual}.`,
+          location: { path: filePath, relPath },
+        })
+        continue
+      }
+      const claimed = parseInt(claimedRaw, 10)
+      if (claimed !== actual) {
+        findings.push({
+          category: 'documentation',
+          severity: 'error',
+          code: `doc-claims/${check.codeId}-drift`,
+          gate: 'doc-claims',
+          message: `${check.name}: ${claim.file} claims ${claimed}, actual ${actual}.`,
+          location: { path: filePath, relPath },
+          fix: `Update the claim in ${claim.file} from ${claimed} to ${actual}`,
+        })
+      }
+    }
+  }
+
+  return {
+    gate: 'doc-claims',
+    category: 'documentation',
+    findings,
+    meta: {
+      scanned: checks.reduce((n, c) => n + c.claims.length, 0),
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/gates/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Barrel export for all programmatic doctor gates.
+ *
+ * Each gate exports a `run<Name>Gate(opts): Promise<GateResult>` function.
+ * The aggregator iterates a curated list of these to produce the
+ * unified `DoctorReport`; consumers can also import individual gates
+ * for standalone use (the existing `scripts/check-*.ts` wrappers do this).
+ */
+
+export {
+  runAuditTypesGate,
+  type AuditTypesGateOptions,
+} from './audit-types'
+export {
+  runBundleBudgetsGate,
+  type BundleBudgetsGateOptions,
+} from './bundle-budgets'
+export {
+  runDistributionGate,
+  type DistributionGateOptions,
+} from './distribution'
+export {
+  runDocClaimsGate,
+  type DocClaimsGateOptions,
+} from './doc-claims'
+export {
+  runReactPatternsGate,
+  type ReactPatternsGateOptions,
+} from './react-patterns'
+export {
+  runPyreonPatternsGate,
+  type PyreonPatternsGateOptions,
+} from './pyreon-patterns'
+export {
+  runAuditTestsGate,
+  type AuditTestsGateOptions,
+} from './audit-tests'
+export {
+  runIslandsAuditGate,
+  type IslandsAuditGateOptions,
+} from './islands-audit'
+export {
+  runSsgAuditGate,
+  type SsgAuditGateOptions,
+} from './ssg-audit'
+export { runLintGate, type LintGateOptions } from './lint'

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

@@ -0,0 +1,66 @@
+/**
+ * islands-audit gate — wraps `@pyreon/compiler:auditIslands`.
+ *
+ * Project-wide cross-file detectors for the island architecture
+ * (duplicate names, dead islands, registry drift, nested islands,
+ * never-with-registry-entry). Per-finding severity is derived from
+ * the finding code: `dead-island` is a warning (might be intentional
+ * during refactor), everything else is an error (silent runtime
+ * failure mode).
+ */
+
+import { auditIslands, type IslandFindingCode } from '@pyreon/compiler'
+
+import type { Finding, GateResult, Severity } from '../types'
+
+const SEVERITY_BY_CODE: Record<IslandFindingCode, Severity> = {
+  'duplicate-name': 'error',
+  'never-with-registry-entry': 'error',
+  'registry-mismatch': 'error',
+  'nested-island': 'error',
+  'dead-island': 'warning',
+}
+
+export interface IslandsAuditGateOptions {
+  cwd: string
+}
+
+export const runIslandsAuditGate = async (
+  opts: IslandsAuditGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const result = auditIslands(opts.cwd)
+
+  for (const f of result.findings) {
+    findings.push({
+      category: 'architecture',
+      severity: SEVERITY_BY_CODE[f.code] ?? 'error',
+      code: `islands-audit/${f.code}`,
+      gate: 'islands-audit',
+      message: f.message,
+      location: {
+        path: f.location.path,
+        relPath: f.location.relPath,
+        line: f.location.line,
+        column: f.location.column,
+      },
+      relatedLocations: f.related?.map((r) => ({
+        path: r.path,
+        relPath: r.relPath,
+        line: r.line,
+        column: r.column,
+      })),
+    })
+  }
+
+  return {
+    gate: 'islands-audit',
+    category: 'architecture',
+    findings,
+    meta: {
+      scanned: result.findings.length,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/gates/lint.ts

@@ -0,0 +1,129 @@
+/**
+ * lint gate — wraps `@pyreon/lint:lint`.
+ *
+ * Runs the project's configured Pyreon lint rules across the source
+ * tree. Per-finding category is derived from the rule ID's prefix
+ * (the lint rule categories: reactivity, jsx, lifecycle, performance,
+ * ssr, architecture, store, form, styling, hooks, accessibility,
+ * router, ssg) — `performance` rules emit `category: 'performance'`,
+ * `architecture` rules emit `category: 'architecture'`, the rest fold
+ * to `'correctness'` since they're all "your code is broken in some
+ * way" findings from the doctor's perspective.
+ *
+ * Severity passes through as-is from lint's `Diagnostic.severity`
+ * ('error' | 'warning' | 'info' all map 1:1 to the doctor severity
+ * shape).
+ */
+
+import * as path from 'node:path'
+
+import { lint, allRules } from '@pyreon/lint'
+
+import type {
+  Finding,
+  FindingCategory,
+  GateResult,
+  Severity,
+} from '../types'
+
+const mapLintSeverity = (s: string): Severity | null => {
+  if (s === 'error') return 'error'
+  if (s === 'warn') return 'warning'
+  if (s === 'info') return 'info'
+  return null // 'off'
+}
+
+// Build a rule-id → category lookup once at module load. The lint
+// rule registry is the source of truth for which category a rule
+// belongs to; this map mirrors the doctor's 5-bucket vocabulary.
+const RULE_CATEGORY = (() => {
+  const map = new Map<string, FindingCategory>()
+  for (const rule of allRules) {
+    const cat = mapLintCategory(rule.meta.category)
+    map.set(rule.meta.id, cat)
+  }
+  return map
+})()
+
+function mapLintCategory(c: string): FindingCategory {
+  switch (c) {
+    case 'performance':
+      return 'performance'
+    case 'architecture':
+    case 'ssr':
+    case 'ssg':
+    case 'router':
+      return 'architecture'
+    case 'styling':
+    case 'accessibility':
+      return 'architecture'
+    default:
+      // reactivity, jsx, lifecycle, store, form, hooks → all
+      // user-code correctness from the doctor's vocabulary.
+      return 'correctness'
+  }
+}
+
+export interface LintGateOptions {
+  cwd: string
+  /** Apply lint auto-fixes during the run. */
+  fix?: boolean | undefined
+}
+
+export const runLintGate = async (
+  opts: LintGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+
+  const result = await lint({
+    paths: [opts.cwd],
+    fix: opts.fix ?? false,
+  })
+
+  for (const fileResult of result.files) {
+    for (const diag of fileResult.diagnostics) {
+      const severity = mapLintSeverity(diag.severity)
+      if (severity === null) continue
+      const category = RULE_CATEGORY.get(diag.ruleId) ?? 'correctness'
+      findings.push({
+        category,
+        severity,
+        code: `lint/${diag.ruleId}`,
+        gate: 'lint',
+        message: diag.message,
+        location: {
+          path: fileResult.filePath,
+          relPath: path.relative(opts.cwd, fileResult.filePath),
+          line: diag.loc.line,
+          column: diag.loc.column,
+        },
+        fixable: diag.fix !== undefined,
+      })
+    }
+  }
+
+  // Surface config-level diagnostics as architecture errors — they
+  // mean the user's `.pyreonlintrc.json` has malformed rule options.
+  for (const cd of result.configDiagnostics) {
+    const severity = mapLintSeverity(cd.severity)
+    if (severity === null) continue
+    findings.push({
+      category: 'architecture',
+      severity,
+      code: `lint/config-${cd.ruleId}`,
+      gate: 'lint',
+      message: cd.message,
+    })
+  }
+
+  return {
+    gate: 'lint',
+    category: 'correctness',
+    findings,
+    meta: {
+      scanned: result.files.length,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}