effect-v4-audit 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# effect-v4-audit
+
+Deterministic CLI audit for v3-era Effect APIs in Effect v4 migrations.
+
+## Install (local package)
+
+```bash
+cd /Users/af/effect-cli-ce/effect-smol/packages/tools/effect-v4-audit
+bun install
+```
+
+After install, run:
+
+```bash
+bun x effect-v4-audit --help
+```
+
+## Usage
+
+```bash
+effect-v4-audit \
+  --cwd . \
+  --pattern "**/*.{ts,tsx,mts,cts}" \
+  --ignore "**/*.gen.ts" \
+  --format table \
+  --fail-on-findings
+```
+
+## Output
+
+- `table`: human-readable findings with path, line/column, and migration suggestion.
+- `json`: stable machine-readable report for CI.
+
+## Guarantees
+
+- deterministic file ordering and finding ordering
+- deterministic summary counters and per-rule map ordering
+- exits with code `1` only when `--fail-on-findings` is passed and findings exist
+
+## Limitations
+
+- rule-based text scan; does not parse full TypeScript AST
+- may flag strings/comments containing legacy API text
+- rules are intentionally conservative and not a full migration codemod

package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "./src/bin.ts"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "effect-v4-audit",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT",
+  "description": "Deterministic Effect v4 migration audit CLI",
+  "homepage": "https://effect.website",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Effect-TS/effect-smol.git",
+    "directory": "packages/tools/effect-v4-audit"
+  },
+  "sideEffects": [],
+  "bin": {
+    "effect-v4-audit": "./bin.js"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "bin.js",
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "audit": "bun run ./src/bin.ts",
+    "test": "bun test",
+    "check": "bun test --bail",
+    "coverage": "bun test --coverage"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "glob": "^13.0.0"
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,107 @@
+import { computeLineStarts, indexToLineColumn } from "./line-starts.ts"
+import { defaultV4AuditRules } from "./rules.ts"
+import type { V4AuditFinding, V4AuditReport, V4AuditRule, V4AuditSourceFile, V4AuditSummary } from "./types.ts"
+
+const normalizePath = (path: string): string => path.split("\\").join("/")
+
+const asGlobalRegExp = (pattern: RegExp): RegExp => {
+  const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  return new RegExp(pattern.source, flags)
+}
+
+const compareFindings = (left: V4AuditFinding, right: V4AuditFinding): number =>
+  left.path.localeCompare(right.path) ||
+  left.line - right.line ||
+  left.column - right.column ||
+  left.ruleId.localeCompare(right.ruleId) ||
+  left.match.localeCompare(right.match)
+
+const compareRules = (left: V4AuditRule, right: V4AuditRule): number => left.id.localeCompare(right.id)
+
+const scanSourceForRule = (
+  source: V4AuditSourceFile,
+  rule: V4AuditRule
+): ReadonlyArray<V4AuditFinding> => {
+  const path = normalizePath(source.path)
+  const lineStarts = computeLineStarts(source.content)
+  const pattern = asGlobalRegExp(rule.pattern)
+  const findings: Array<V4AuditFinding> = []
+
+  let match: RegExpExecArray | null = null
+  while ((match = pattern.exec(source.content)) !== null) {
+    const position = indexToLineColumn(lineStarts, match.index)
+    findings.push({
+      ruleId: rule.id,
+      severity: rule.severity,
+      message: rule.message,
+      suggestion: rule.suggestion,
+      path,
+      line: position.line,
+      column: position.column,
+      match: match[0]
+    })
+
+    if (match[0].length === 0) {
+      pattern.lastIndex = pattern.lastIndex + 1
+    }
+  }
+
+  return findings
+}
+
+const buildByRuleSummary = (findings: ReadonlyArray<V4AuditFinding>): Readonly<Record<string, number>> => {
+  const summary = new Map<string, number>()
+  for (const finding of findings) {
+    summary.set(finding.ruleId, (summary.get(finding.ruleId) ?? 0) + 1)
+  }
+
+  const byRule: Record<string, number> = {}
+  for (const [ruleId, count] of [...summary.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    byRule[ruleId] = count
+  }
+  return byRule
+}
+
+const buildSummary = (
+  filesScanned: number,
+  findings: ReadonlyArray<V4AuditFinding>
+): V4AuditSummary => {
+  let errorCount = 0
+  let warningCount = 0
+
+  const filesWithFindings = new Set<string>()
+  for (const finding of findings) {
+    filesWithFindings.add(finding.path)
+    if (finding.severity === "error") {
+      errorCount++
+    } else {
+      warningCount++
+    }
+  }
+
+  return {
+    filesScanned,
+    filesWithFindings: filesWithFindings.size,
+    findingCount: findings.length,
+    errorCount,
+    warningCount,
+    byRule: buildByRuleSummary(findings)
+  }
+}
+
+export const analyzeV4Sources = (options: {
+  readonly sources: ReadonlyArray<V4AuditSourceFile>
+  readonly rules?: ReadonlyArray<V4AuditRule> | undefined
+}): V4AuditReport => {
+  const rules = [...(options.rules ?? defaultV4AuditRules)].sort(compareRules)
+  const sources = [...options.sources].sort((a, b) => normalizePath(a.path).localeCompare(normalizePath(b.path)))
+
+  const findings = sources.flatMap((source) => rules.flatMap((rule) => scanSourceForRule(source, rule)))
+  findings.sort(compareFindings)
+
+  return {
+    version: 1,
+    summary: buildSummary(sources.length, findings),
+    findings
+  }
+}

package/src/bin.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env bun
+
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { glob } from "glob"
+import { analyzeV4Sources } from "./analyze.ts"
+import { renderV4AuditJson, renderV4AuditTable } from "./render.ts"
+
+interface CliOptions {
+  readonly cwd: string
+  readonly pattern: string
+  readonly ignore: ReadonlyArray<string>
+  readonly format: "table" | "json"
+  readonly failOnFindings: boolean
+}
+
+const defaultIgnorePatterns = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/.git/**",
+  "**/.turbo/**"
+] as const
+
+const usage = (): string => [
+  "effect-v4-audit",
+  "",
+  "Usage:",
+  "  effect-v4-audit [--cwd <dir>] [--pattern <glob>] [--ignore <glob>] [--format table|json] [--fail-on-findings]",
+  "",
+  "Options:",
+  "  -c, --cwd <dir>              Directory to scan (default: .)",
+  "  -p, --pattern <glob>         Glob for files to scan (default: **/*.{ts,tsx,mts,cts})",
+  "  -i, --ignore <glob>          Glob to ignore (repeat for multiple values)",
+  "  -f, --format <table|json>    Output format (default: table)",
+  "      --fail-on-findings       Exit with code 1 when findings exist",
+  "  -h, --help                   Show this help"
+].join("\n")
+
+const parseNextValue = (args: ReadonlyArray<string>, index: number, flag: string): string => {
+  const value = args[index + 1]
+  if (!value || value.startsWith("-")) {
+    throw new Error(`Missing value for ${flag}`)
+  }
+  return value
+}
+
+export const parseCliArgs = (args: ReadonlyArray<string>): CliOptions | { readonly help: true } => {
+  let cwd = "."
+  let pattern = "**/*.{ts,tsx,mts,cts}"
+  const ignore: Array<string> = []
+  let format: "table" | "json" = "table"
+  let failOnFindings = false
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+
+    switch (arg) {
+      case "-h":
+      case "--help":
+        return { help: true }
+      case "-c":
+      case "--cwd":
+        cwd = parseNextValue(args, index, arg)
+        index++
+        break
+      case "-p":
+      case "--pattern":
+        pattern = parseNextValue(args, index, arg)
+        index++
+        break
+      case "-i":
+      case "--ignore":
+        ignore.push(parseNextValue(args, index, arg))
+        index++
+        break
+      case "-f":
+      case "--format": {
+        const value = parseNextValue(args, index, arg)
+        if (value !== "table" && value !== "json") {
+          throw new Error(`Invalid format: ${value}`)
+        }
+        format = value
+        index++
+        break
+      }
+      case "--fail-on-findings":
+        failOnFindings = true
+        break
+      default:
+        throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  return {
+    cwd,
+    pattern,
+    ignore,
+    format,
+    failOnFindings
+  }
+}
+
+const toPosix = (file: string): string => file.split(path.sep).join("/")
+
+const readSources = async (options: CliOptions): Promise<ReadonlyArray<{ readonly path: string; readonly content: string }>> => {
+  const root = path.resolve(options.cwd)
+  const files = await glob(options.pattern, {
+    cwd: root,
+    dot: false,
+    follow: false,
+    nodir: true,
+    ignore: [...defaultIgnorePatterns, ...options.ignore]
+  })
+
+  const sorted = files.sort((a, b) => toPosix(a).localeCompare(toPosix(b)))
+
+  return Promise.all(
+    sorted.map(async (file) => {
+      const absolute = path.join(root, file)
+      const content = await readFile(absolute, "utf8")
+      return {
+        path: toPosix(file),
+        content
+      }
+    })
+  )
+}
+
+export const runCli = async (args: ReadonlyArray<string>): Promise<number> => {
+  const parsed = parseCliArgs(args)
+  if ("help" in parsed) {
+    console.log(usage())
+    return 0
+  }
+
+  const sources = await readSources(parsed)
+  const report = analyzeV4Sources({ sources })
+  const output = parsed.format === "json" ? renderV4AuditJson(report) : renderV4AuditTable(report)
+  console.log(output)
+
+  if (parsed.failOnFindings && report.summary.findingCount > 0) {
+    return 1
+  }
+
+  return 0
+}
+
+if (import.meta.main) {
+  const exitCode = await runCli(process.argv.slice(2)).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(message)
+    return 1
+  })
+
+  process.exitCode = exitCode
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import { analyzeV4Sources } from "./analyze.ts"
+import { defaultV4AuditRules } from "./rules.ts"
+import { renderV4AuditJson, renderV4AuditTable } from "./render.ts"
+
+export * from "./types.ts"
+export { analyzeV4Sources, defaultV4AuditRules, renderV4AuditJson, renderV4AuditTable }

package/src/line-starts.ts

@@ -0,0 +1,47 @@
+export interface LineColumn {
+  readonly line: number
+  readonly column: number
+}
+
+export const computeLineStarts = (content: string): ReadonlyArray<number> => {
+  const starts: Array<number> = [0]
+
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") {
+      starts.push(i + 1)
+    }
+  }
+
+  return starts
+}
+
+export const indexToLineColumn = (lineStarts: ReadonlyArray<number>, index: number): LineColumn => {
+  let low = 0
+  let high = lineStarts.length - 1
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2)
+    const start = lineStarts[mid]
+    const nextStart = mid + 1 < lineStarts.length ? lineStarts[mid + 1] : Number.POSITIVE_INFINITY
+
+    if (index < start) {
+      high = mid - 1
+      continue
+    }
+
+    if (index >= nextStart) {
+      low = mid + 1
+      continue
+    }
+
+    return {
+      line: mid + 1,
+      column: index - start + 1
+    }
+  }
+
+  return {
+    line: lineStarts.length,
+    column: 1
+  }
+}

package/src/render.ts

@@ -0,0 +1,25 @@
+import type { V4AuditReport } from "./types.ts"
+
+export const renderV4AuditJson = (report: V4AuditReport): string => JSON.stringify(report, null, 2)
+
+export const renderV4AuditTable = (report: V4AuditReport): string => {
+  if (report.summary.findingCount === 0) {
+    return `No v4-audit findings. Files scanned: ${report.summary.filesScanned}.`
+  }
+
+  const lines: Array<string> = [
+    `Findings: ${report.summary.findingCount} (errors: ${report.summary.errorCount}, warnings: ${report.summary.warningCount})`,
+    `Files scanned: ${report.summary.filesScanned}, files with findings: ${report.summary.filesWithFindings}`,
+    ""
+  ]
+
+  for (const finding of report.findings) {
+    lines.push(`[${finding.severity.toUpperCase()}] ${finding.ruleId} ${finding.path}:${finding.line}:${finding.column}`)
+    lines.push(`  ${finding.message}`)
+    lines.push(`  Suggestion: ${finding.suggestion}`)
+    lines.push(`  Match: ${JSON.stringify(finding.match)}`)
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}

package/src/rules.ts

@@ -0,0 +1,132 @@
+import type { V4AuditRule } from "./types.ts"
+
+const errorRule = (
+  id: string,
+  pattern: RegExp,
+  message: string,
+  suggestion: string
+): V4AuditRule => ({
+  id,
+  severity: "error",
+  pattern,
+  message,
+  suggestion
+})
+
+const warningRule = (
+  id: string,
+  pattern: RegExp,
+  message: string,
+  suggestion: string
+): V4AuditRule => ({
+  id,
+  severity: "warning",
+  pattern,
+  message,
+  suggestion
+})
+
+export const defaultV4AuditRules: ReadonlyArray<V4AuditRule> = [
+  errorRule(
+    "legacy-context-generic-tag",
+    /\bContext\.GenericTag\b/g,
+    "Context.GenericTag is a v3 API.",
+    "Use ServiceMap.Service instead."
+  ),
+  errorRule(
+    "legacy-context-tag",
+    /\bContext\.Tag\b/g,
+    "Context.Tag is a v3 API.",
+    "Use ServiceMap.Service instead."
+  ),
+  errorRule(
+    "legacy-context-reference",
+    /\bContext\.Reference\b/g,
+    "Context.Reference is a v3 API.",
+    "Use ServiceMap.Reference instead."
+  ),
+  errorRule(
+    "legacy-effect-tag",
+    /\bEffect\.Tag\s*\(/g,
+    "Effect.Tag is a v3 API.",
+    "Use ServiceMap.Service class syntax or function syntax."
+  ),
+  errorRule(
+    "legacy-effect-service",
+    /\bEffect\.Service\s*\(/g,
+    "Effect.Service is a v3 API.",
+    "Use ServiceMap.Service plus explicit Layer.effect wiring."
+  ),
+  errorRule(
+    "legacy-fiberref",
+    /\bFiberRef\./g,
+    "FiberRef APIs were replaced in v4.",
+    "Use References.* values or ServiceMap.Reference."
+  ),
+  errorRule(
+    "legacy-scope-extend",
+    /\bScope\.extend\b/g,
+    "Scope.extend was renamed in v4.",
+    "Use Scope.provide."
+  ),
+  errorRule(
+    "legacy-catch-all",
+    /\bEffect\.catchAll\b/g,
+    "Effect.catchAll was renamed in v4.",
+    "Use Effect.catch."
+  ),
+  errorRule(
+    "legacy-catch-all-cause",
+    /\bEffect\.catchAllCause\b/g,
+    "Effect.catchAllCause was renamed in v4.",
+    "Use Effect.catchCause."
+  ),
+  errorRule(
+    "legacy-catch-all-defect",
+    /\bEffect\.catchAllDefect\b/g,
+    "Effect.catchAllDefect was renamed in v4.",
+    "Use Effect.catchDefect."
+  ),
+  errorRule(
+    "legacy-catch-some",
+    /\bEffect\.catchSome\b/g,
+    "Effect.catchSome was renamed in v4.",
+    "Use Effect.catchFilter."
+  ),
+  errorRule(
+    "legacy-catch-some-cause",
+    /\bEffect\.catchSomeCause\b/g,
+    "Effect.catchSomeCause was renamed in v4.",
+    "Use Effect.catchCauseFilter."
+  ),
+  errorRule(
+    "legacy-catch-some-defect",
+    /\bEffect\.catchSomeDefect\b/g,
+    "Effect.catchSomeDefect was removed in v4.",
+    "Use Effect.catchDefect or Effect.catchCause depending on intent."
+  ),
+  errorRule(
+    "legacy-fork",
+    /\bEffect\.fork\s*\(/g,
+    "Effect.fork was renamed in v4.",
+    "Use Effect.forkChild."
+  ),
+  errorRule(
+    "legacy-fork-daemon",
+    /\bEffect\.forkDaemon\b/g,
+    "Effect.forkDaemon was renamed in v4.",
+    "Use Effect.forkDetach."
+  ),
+  errorRule(
+    "legacy-equal-equivalence",
+    /\bEqual\.equivalence\b/g,
+    "Equal.equivalence was renamed in v4.",
+    "Use Equal.asEquivalence."
+  ),
+  warningRule(
+    "unstable-effect-import",
+    /from\s+["']effect\/unstable\/[^"']+["']/g,
+    "Unstable module import detected.",
+    "Treat unstable APIs as non-semver-stable and isolate usage."
+  )
+]

package/src/types.ts

@@ -0,0 +1,40 @@
+export type V4AuditSeverity = "error" | "warning"
+
+export interface V4AuditRule {
+  readonly id: string
+  readonly severity: V4AuditSeverity
+  readonly pattern: RegExp
+  readonly message: string
+  readonly suggestion: string
+}
+
+export interface V4AuditSourceFile {
+  readonly path: string
+  readonly content: string
+}
+
+export interface V4AuditFinding {
+  readonly ruleId: string
+  readonly severity: V4AuditSeverity
+  readonly message: string
+  readonly suggestion: string
+  readonly path: string
+  readonly line: number
+  readonly column: number
+  readonly match: string
+}
+
+export interface V4AuditSummary {
+  readonly filesScanned: number
+  readonly filesWithFindings: number
+  readonly findingCount: number
+  readonly errorCount: number
+  readonly warningCount: number
+  readonly byRule: Readonly<Record<string, number>>
+}
+
+export interface V4AuditReport {
+  readonly version: 1
+  readonly summary: V4AuditSummary
+  readonly findings: ReadonlyArray<V4AuditFinding>
+}