effect-v4-audit 0.1.0 → 0.2.1

package/README.md

@@ -1,18 +1,30 @@
 # effect-v4-audit
 
 Deterministic CLI audit for v3-era Effect APIs in Effect v4 migrations.
+Built on Effect v4 beta CLI APIs (`effect/unstable/cli`).
 
-## Install (local package)
+## Demo
+
+![effect-v4-audit demo](./demo/effect-v4-audit-demo.gif)
+
+## Install
+
+```bash
+bunx effect-v4-audit --help
+```
+
+## Local Development
 
 ```bash
-cd /Users/af/effect-cli-ce/effect-smol/packages/tools/effect-v4-audit
+git clone https://github.com/agustif/effect-v4-audit.git
+cd effect-v4-audit
 bun install
 ```
 
-After install, run:
+Then run:
 
 ```bash
-bun x effect-v4-audit --help
+bun run ./src/bin.ts --help
 ```
 
 ## Usage
@@ -22,13 +34,15 @@ effect-v4-audit \
   --cwd . \
   --pattern "**/*.{ts,tsx,mts,cts}" \
   --ignore "**/*.gen.ts" \
-  --format table \
+  --color auto \
+  --format diagnostic \
   --fail-on-findings
 ```
 
 ## Output
 
-- `table`: human-readable findings with path, line/column, and migration suggestion.
+- `diagnostic`: rust-style diagnostics with source snippet and `help` hint.
+- `table`: compact findings with path, line/column, and migration suggestion.
 - `json`: stable machine-readable report for CI.
 
 ## Guarantees

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "effect-v4-audit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3.0"
   },
   "license": "MIT",
   "description": "Deterministic Effect v4 migration audit CLI",
-  "homepage": "https://effect.website",
+  "homepage": "https://github.com/agustif/effect-v4-audit",
+  "bugs": {
+    "url": "https://github.com/agustif/effect-v4-audit/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Effect-TS/effect-smol.git",
-    "directory": "packages/tools/effect-v4-audit"
+    "url": "git+https://github.com/agustif/effect-v4-audit.git"
   },
   "sideEffects": [],
   "bin": {
-    "effect-v4-audit": "./bin.js"
+    "effect-v4-audit": "bin.js"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -24,6 +26,7 @@
   },
   "files": [
     "bin.js",
+    "demo/effect-v4-audit-demo.gif",
     "src/**/*.ts",
     "README.md"
   ],
@@ -34,9 +37,12 @@
     "coverage": "bun test --coverage"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.12",
+    "effect": "4.0.0-beta.12",
     "glob": "^13.0.0"
   }
 }

package/src/bin.ts

@@ -1,157 +1,119 @@
 #!/usr/bin/env bun
 
+import * as NodeServices from "@effect/platform-node/NodeServices"
 import { readFile } from "node:fs/promises"
 import path from "node:path"
 import { glob } from "glob"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as CliError from "effect/unstable/cli/CliError"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
 import { analyzeV4Sources } from "./analyze.ts"
+import { renderV4AuditDiagnostics, type V4AuditColorMode } from "./diagnostics.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 cwd = Flag.directory("cwd", { mustExist: true }).pipe(
+  Flag.withAlias("c"),
+  Flag.withDescription("Directory to scan"),
+  Flag.withDefault(".")
+)
+
+const pattern = Flag.string("pattern").pipe(
+  Flag.withAlias("p"),
+  Flag.withDescription("Glob for files to scan"),
+  Flag.withDefault("**/*.{ts,tsx,mts,cts}")
+)
+
+const ignore = Flag.string("ignore").pipe(
+  Flag.withAlias("i"),
+  Flag.withDescription("Glob pattern(s) to ignore (repeat --ignore for multiple values)"),
+  Flag.between(0, Infinity)
+)
+
+const format = Flag.choice("format", ["diagnostic", "table", "json"] as const).pipe(
+  Flag.withAlias("f"),
+  Flag.withDescription("Report output format"),
+  Flag.withDefault("diagnostic")
+)
+
+const color = Flag.choice("color", ["auto", "always", "never"] as const).pipe(
+  Flag.withDescription("ANSI color output mode"),
+  Flag.withDefault("auto")
+)
+
+const failOnFindings = Flag.boolean("fail-on-findings").pipe(
+  Flag.withDescription("Exit with error code when at least one finding exists")
+)
+
+const toUserError = (cause: unknown, fallback: string): CliError.UserError =>
+  new CliError.UserError({
+    cause: cause instanceof Error
+      ? cause.message
+      : typeof cause === "string"
+      ? cause
+      : fallback
   })
 
-  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 {
+const cli = Command.make("effect-v4-audit", {
+  cwd,
+  pattern,
+  ignore,
+  format,
+  color,
+  failOnFindings
+}, (options) =>
+  Effect.gen(function*() {
+    const root = path.resolve(options.cwd)
+    const toPosix = path.sep === "/" ? (file: string) => file : (file: string) => file.split(path.sep).join("/")
+
+    const files = yield* Effect.tryPromise({
+      try: () =>
+        glob(options.pattern, {
+          cwd: root,
+          dot: false,
+          follow: false,
+          nodir: true,
+          ignore: [...defaultIgnorePatterns, ...options.ignore]
+        }),
+      catch: (cause) => toUserError(cause, "Failed to collect files")
+    }).pipe(Effect.map((files) => files.sort((a, b) => toPosix(a).localeCompare(toPosix(b)))))
+
+    const sources = yield* Effect.forEach(files, (file) =>
+      Effect.tryPromise({
+        try: () => readFile(path.join(root, file), "utf8"),
+        catch: (cause) => toUserError(cause, `Failed to read ${file}`)
+      }).pipe(Effect.map((content) => ({
         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
-  })
+      }))))
+
+    const report = analyzeV4Sources({ sources })
+    const output = options.format === "json"
+      ? renderV4AuditJson(report)
+      : options.format === "table"
+      ? renderV4AuditTable(report)
+      : renderV4AuditDiagnostics(report, sources, { color: options.color as V4AuditColorMode })
+
+    yield* Console.log(output)
+
+    if (options.failOnFindings && report.summary.findingCount > 0) {
+      yield* Effect.sync(() => {
+        process.exitCode = 1
+      })
+    }
+  }))
+
+const main = Command.run(cli, { version: "0.2.1" }).pipe(
+  Effect.provide(NodeServices.layer)
+)
 
-  process.exitCode = exitCode
-}
+Effect.runPromise(main)

package/src/diagnostics.ts

@@ -0,0 +1,124 @@
+import type { V4AuditReport, V4AuditSourceFile } from "./types.ts"
+
+export type V4AuditColorMode = "auto" | "always" | "never"
+
+const resolveUseColor = (mode: V4AuditColorMode): boolean => {
+  if (mode === "always") {
+    return true
+  }
+
+  if (mode === "never") {
+    return false
+  }
+
+  const globalProcess = (globalThis as any).process
+  const hasProcess = typeof globalProcess === "object" && globalProcess !== null
+  if (!hasProcess) {
+    return false
+  }
+
+  if (globalProcess.env?.NO_COLOR === "1") {
+    return false
+  }
+
+  if (globalProcess.env?.FORCE_COLOR && globalProcess.env.FORCE_COLOR !== "0") {
+    return true
+  }
+
+  return globalProcess.stdout?.isTTY === true
+}
+
+const makeColor = (useColor: boolean) => {
+  if (!useColor) {
+    return {
+      bold: (text: string): string => text,
+      dim: (text: string): string => text,
+      red: (text: string): string => text,
+      yellow: (text: string): string => text,
+      blue: (text: string): string => text,
+      cyan: (text: string): string => text,
+      green: (text: string): string => text
+    }
+  }
+
+  return {
+    bold: (text: string): string => `\x1b[1m${text}\x1b[0m`,
+    dim: (text: string): string => `\x1b[2m${text}\x1b[0m`,
+    red: (text: string): string => `\x1b[31m${text}\x1b[0m`,
+    yellow: (text: string): string => `\x1b[33m${text}\x1b[0m`,
+    blue: (text: string): string => `\x1b[34m${text}\x1b[0m`,
+    cyan: (text: string): string => `\x1b[36m${text}\x1b[0m`,
+    green: (text: string): string => `\x1b[32m${text}\x1b[0m`
+  }
+}
+
+const lineAt = (content: string, line: number): string => {
+  const lines = content.split("\n")
+  if (line <= 0 || line > lines.length) {
+    return ""
+  }
+  return lines[line - 1] ?? ""
+}
+
+const markerWidth = (match: string): number => Math.max(1, match.trim().length)
+
+const digits = (value: number): number => `${Math.max(1, value)}`.length
+
+const padLeft = (value: string, width: number): string => `${" ".repeat(Math.max(0, width - value.length))}${value}`
+
+export const renderV4AuditDiagnostics = (
+  report: V4AuditReport,
+  sources: ReadonlyArray<V4AuditSourceFile>,
+  options?: {
+    readonly color?: V4AuditColorMode | undefined
+  }
+): string => {
+  const color = makeColor(resolveUseColor(options?.color ?? "never"))
+
+  if (report.summary.findingCount === 0) {
+    return `No v4-audit findings. Files scanned: ${report.summary.filesScanned}.`
+  }
+
+  const sourceMap = new Map<string, string>()
+  for (const source of sources) {
+    sourceMap.set(source.path.split("\\").join("/"), source.content)
+  }
+
+  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) {
+    const severity = finding.severity === "error"
+      ? color.bold(color.red("error"))
+      : color.bold(color.yellow("warning"))
+    const ruleId = color.bold(color.cyan(finding.ruleId))
+    const sourceContent = sourceMap.get(finding.path)
+    const codeLine = sourceContent ? lineAt(sourceContent, finding.line) : ""
+    const lineNo = `${finding.line}`
+    const gutterWidth = digits(finding.line)
+    const marker = finding.severity === "error"
+      ? color.red("^".repeat(markerWidth(finding.match)))
+      : color.yellow("^".repeat(markerWidth(finding.match)))
+    const columnOffset = Math.max(0, finding.column - 1)
+
+    lines.push(`${severity}[${ruleId}]: ${finding.message}`)
+    lines.push(`  ${color.blue("-->")} ${finding.path}:${finding.line}:${finding.column}`)
+    lines.push(`${color.dim(" ".repeat(gutterWidth))} ${color.blue("|")}`)
+
+    if (codeLine.length > 0) {
+      lines.push(`${color.dim(padLeft(lineNo, gutterWidth))} ${color.blue("|")} ${codeLine}`)
+      lines.push(`${color.dim(" ".repeat(gutterWidth))} ${color.blue("|")} ${" ".repeat(columnOffset)}${marker}`)
+    } else {
+      lines.push(`${color.dim(padLeft(lineNo, gutterWidth))} ${color.blue("|")} ${finding.match}`)
+      lines.push(`${color.dim(" ".repeat(gutterWidth))} ${color.blue("|")} ${marker}`)
+    }
+
+    lines.push(`${color.dim(" ".repeat(gutterWidth))} ${color.green("=")} ${color.green("help")}: ${finding.suggestion}`)
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}

package/src/index.ts

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