effect-analyzer 0.1.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "effect-analyzer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Static analysis for Effect-TS code. Analyze Effect code to extract structure, calculate complexity, and generate visualizations.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "bin": {
+    "effect-analyze": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./effect-workflow": {
+      "types": "./dist/effect-workflow.d.ts",
+      "import": "./dist/effect-workflow.js",
+      "require": "./dist/effect-workflow.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lsp": "node dist/lsp/server.js",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "clean": "rm -rf dist",
+    "quality": "pnpm type-check && pnpm test && pnpm lint",
+    "effect:fetch": "tsx scripts/fetch-effect-repo.ts"
+  },
+  "keywords": [
+    "effect", "effect-ts", "static-analysis", "ts-morph",
+    "typescript", "visualization", "mermaid", "functional-programming"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "effect": ">=3.0.0",
+    "@effect/platform": ">=0.70.0"
+  },
+  "peerDependenciesMeta": {
+    "effect": { "optional": false },
+    "@effect/platform": { "optional": true }
+  },
+  "dependencies": {
+    "effect": "^3.21.0",
+    "ts-morph": "^27.0.2"
+  },
+  "optionalDependencies": {
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12"
+  },
+  "devDependencies": {
+    "@effect/eslint-plugin": "^0.3.2",
+    "@eslint/js": "^10.0.1",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.1.0",
+    "ts-morph": "^27.0.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.1",
+    "vitest": "^4.1.0"
+  }
+}

package/scripts/analyze-public-repos.ts

@@ -0,0 +1,130 @@
+/**
+ * Clone public Effect repos into .analysis-output/, run effect-analyze (colocated
+ * .effect-analysis.md), and optionally run coverage audit and append a one-line
+ * summary to .analysis-output/NOTES.md.
+ *
+ * Usage: pnpm build && pnpm run analyze:public-repos [--refresh]
+ *
+ * --refresh  Re-clone repos that already exist (default: skip existing clones).
+ *
+ * After running, review generated .effect-analysis.md files under .analysis-output
+ * and update .analysis-output/NOTES.md with README-worthy examples (repo, file, program, why).
+ */
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, rmSync } from 'fs';
+import { join, resolve } from 'path';
+import { execFileSync, spawnSync } from 'child_process';
+
+const ROOT = resolve(process.cwd());
+const ANALYSIS_DIR = join(ROOT, '.analysis-output');
+const CLI_PATH = join(ROOT, 'dist/cli.js');
+
+const REPOS: { name: string; url: string }[] = [
+  { name: 'typed', url: 'https://github.com/TylorS/typed.git' },
+  { name: 'effect-http', url: 'https://github.com/sukovanej/effect-http.git' },
+  { name: 'distilled', url: 'https://github.com/alchemy-run/distilled.git' },
+  { name: 'sync-engine-web', url: 'https://github.com/typeonce-dev/sync-engine-web.git' },
+  { name: 'effect-aws', url: 'https://github.com/floydspace/effect-aws.git' },
+  { name: 'effect-nextjs', url: 'https://github.com/mcrovero/effect-nextjs.git' },
+  { name: 'sqlfx', url: 'https://github.com/tim-smart/sqlfx.git' },
+  // EffectReact templates: add exact repo URL when known (e.g. Effect-TS/effect-react or template repo)
+];
+
+const NOTES_TEMPLATE = `# Public repo analysis – README candidates
+
+One-line audit summaries are appended below by the script. Add README-worthy examples here after reviewing generated \`.effect-analysis.md\` files.
+
+## Audit summaries (auto-appended)
+
+`;
+
+function ensureAnalysisDir(): void {
+  mkdirSync(ANALYSIS_DIR, { recursive: true });
+}
+
+function ensureNotesFile(): void {
+  const notesPath = join(ANALYSIS_DIR, 'NOTES.md');
+  if (!existsSync(notesPath)) {
+    writeFileSync(notesPath, NOTES_TEMPLATE, 'utf-8');
+  }
+}
+
+function clone(repo: { name: string; url: string }, refresh: boolean): void {
+  const dest = join(ANALYSIS_DIR, repo.name);
+  if (existsSync(dest)) {
+    if (refresh) {
+      rmSync(dest, { recursive: true, force: true });
+    } else {
+      console.log(`  [skip clone] ${repo.name} (already exists; use --refresh to re-clone)`);
+      return;
+    }
+  }
+  console.log(`  cloning ${repo.name}...`);
+  execFileSync('git', ['clone', '--depth', '1', repo.url, dest], {
+    stdio: 'inherit',
+    cwd: ROOT,
+  });
+}
+
+function runAnalyzer(repoName: string): boolean {
+  const targetPath = join(ANALYSIS_DIR, repoName);
+  const result = spawnSync('node', [CLI_PATH, targetPath], {
+    stdio: 'inherit',
+    cwd: ROOT,
+    shell: false,
+  });
+  return result.status === 0;
+}
+
+function runCoverageAudit(repoName: string): { discovered: number; analyzed: number; failed: number } | null {
+  const targetPath = join(ANALYSIS_DIR, repoName);
+  const auditPath = join(ANALYSIS_DIR, `audit-${repoName}.json`);
+  const result = spawnSync(
+    'node',
+    [CLI_PATH, targetPath, '--coverage-audit', '--no-colocate', '-o', auditPath],
+    { cwd: ROOT, shell: false, encoding: 'utf-8' },
+  );
+  if (result.status !== 0) return null;
+  try {
+    const json = JSON.parse(readFileSync(auditPath, 'utf-8'));
+    return {
+      discovered: json.discovered ?? 0,
+      analyzed: json.analyzed ?? 0,
+      failed: json.failed ?? 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function appendAuditLine(repoName: string, audit: { discovered: number; analyzed: number; failed: number }): void {
+  const notesPath = join(ANALYSIS_DIR, 'NOTES.md');
+  const line = `- **${repoName}**: discovered ${audit.discovered}, analyzed ${audit.analyzed}, failed ${audit.failed}\n`;
+  appendFileSync(notesPath, line, 'utf-8');
+}
+
+function main(): void {
+  if (!existsSync(CLI_PATH)) {
+    console.error('Run pnpm build first (dist/cli.js not found).');
+    process.exit(1);
+  }
+
+  const refresh = process.argv.includes('--refresh');
+  ensureAnalysisDir();
+  ensureNotesFile();
+
+  console.log('Repos: ' + REPOS.map((r) => r.name).join(', '));
+  for (const repo of REPOS) {
+    console.log(`\n--- ${repo.name} ---`);
+    clone(repo, refresh);
+    const targetPath = join(ANALYSIS_DIR, repo.name);
+    if (!existsSync(targetPath)) continue;
+    runAnalyzer(repo.name);
+    const audit = runCoverageAudit(repo.name);
+    if (audit) appendAuditLine(repo.name, audit);
+  }
+
+  console.log('\nDone. Review .analysis-output/**/*.effect-analysis.md and update .analysis-output/NOTES.md with README candidates.');
+}
+
+main();

package/scripts/audit-ci.ts

@@ -0,0 +1,213 @@
+import { Effect } from 'effect';
+import { join, resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { runCoverageAudit } from '../src/project-analyzer';
+
+const DEFAULT_EFFECT_REPO_PATH = resolve('.cache/effect-repo');
+
+function getArgValue(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return undefined;
+  const next = process.argv[idx + 1];
+  if (!next || next.startsWith('--')) return undefined;
+  return next;
+}
+
+function parseNumber(
+  value: string | undefined,
+  fallback: number,
+): number {
+  if (value === undefined) return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function parseIntNumber(
+  value: string | undefined,
+  fallback: number,
+): number {
+  if (value === undefined) return fallback;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+type BudgetConfig = {
+  dirPath: string;
+  tsconfig: string | undefined;
+  knownEffectInternalsRoot: string | undefined;
+  maxFailed: number;
+  maxUnknownNodeRate: number;
+  maxSuspiciousZeros: number;
+  baselineFile: string | undefined;
+};
+
+type BudgetBaseline = {
+  maxFailed?: number;
+  maxUnknownNodeRate?: number;
+  maxSuspiciousZeros?: number;
+  metrics?: {
+    failed?: number;
+    unknownNodeRate?: number;
+    suspiciousZeros?: number;
+  };
+};
+
+function readBaseline(pathValue: string | undefined): BudgetBaseline | undefined {
+  if (!pathValue) return undefined;
+  if (!existsSync(pathValue)) return undefined;
+  try {
+    const raw = readFileSync(pathValue, 'utf-8');
+    return JSON.parse(raw) as BudgetBaseline;
+  } catch {
+    return undefined;
+  }
+}
+
+function getConfig(): BudgetConfig {
+  const effectRepoPath = resolve(
+    process.env.EFFECT_REPO_PATH ?? DEFAULT_EFFECT_REPO_PATH,
+  );
+  const defaultDir = join(effectRepoPath, 'packages');
+  const defaultInternalsRoot = join(effectRepoPath, 'packages', 'effect', 'src', 'internal');
+  const defaultBaselineFile = resolve('scripts/baselines/effect-audit-baseline.json');
+  const baselineFile =
+    getArgValue('--baseline-file') ??
+    process.env.AUDIT_BASELINE_FILE ??
+    (existsSync(defaultBaselineFile) ? defaultBaselineFile : undefined);
+  const baseline = readBaseline(baselineFile);
+
+  const dirPath = resolve(
+    getArgValue('--dir') ??
+      process.env.EFFECT_AUDIT_DIR ??
+      defaultDir,
+  );
+  const tsconfig = getArgValue('--tsconfig') ?? process.env.EFFECT_AUDIT_TSCONFIG;
+  const knownEffectInternalsRoot =
+    getArgValue('--known-effect-internals-root') ??
+    process.env.KNOWN_EFFECT_INTERNALS_ROOT ??
+    defaultInternalsRoot;
+
+  // Defaults are set to current observed baselines; tighten over time.
+  const maxFailed = parseIntNumber(
+    getArgValue('--max-failed') ?? process.env.AUDIT_MAX_FAILED,
+    baseline?.maxFailed ?? baseline?.metrics?.failed ?? 0,
+  );
+  const maxUnknownNodeRate = parseNumber(
+    getArgValue('--max-unknown-node-rate') ?? process.env.AUDIT_MAX_UNKNOWN_NODE_RATE,
+    baseline?.maxUnknownNodeRate ?? baseline?.metrics?.unknownNodeRate ?? 0.1173,
+  );
+  const maxSuspiciousZeros = parseIntNumber(
+    getArgValue('--max-suspicious-zeros') ?? process.env.AUDIT_MAX_SUSPICIOUS_ZEROS,
+    baseline?.maxSuspiciousZeros ?? baseline?.metrics?.suspiciousZeros ?? 999_999,
+  );
+
+  return {
+    dirPath,
+    tsconfig,
+    knownEffectInternalsRoot,
+    maxFailed,
+    maxUnknownNodeRate,
+    maxSuspiciousZeros,
+    baselineFile,
+  };
+}
+
+async function main(): Promise<void> {
+  const config = getConfig();
+  const startedAt = Date.now();
+  if (!existsSync(config.dirPath)) {
+    console.error(
+      JSON.stringify(
+        {
+          status: 'fail',
+          message:
+            `Audit dir not found: ${config.dirPath}. ` +
+            'Set EFFECT_AUDIT_DIR / EFFECT_REPO_PATH, or run `pnpm effect:fetch` to clone Effect locally.',
+        },
+        null,
+        2,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const audit = await Effect.runPromise(
+    runCoverageAudit(config.dirPath, {
+      tsconfig: config.tsconfig,
+      knownEffectInternalsRoot: config.knownEffectInternalsRoot,
+    }),
+  );
+
+  const suspiciousCount = audit.zeroProgramCategoryCounts.suspicious;
+  const violations: string[] = [];
+
+  if (audit.failed > config.maxFailed) {
+    violations.push(
+      `failed files ${audit.failed} exceeds max ${config.maxFailed}`,
+    );
+  }
+  if (audit.unknownNodeRate > config.maxUnknownNodeRate) {
+    violations.push(
+      `unknownNodeRate ${(audit.unknownNodeRate * 100).toFixed(2)}% exceeds max ${(config.maxUnknownNodeRate * 100).toFixed(2)}%`,
+    );
+  }
+  if (suspiciousCount > config.maxSuspiciousZeros) {
+    violations.push(
+      `suspicious zeros ${suspiciousCount} exceeds max ${config.maxSuspiciousZeros}`,
+    );
+  }
+
+  const summary = {
+    dirPath: config.dirPath,
+    budgets: {
+      maxFailed: config.maxFailed,
+      maxUnknownNodeRate: config.maxUnknownNodeRate,
+      maxSuspiciousZeros: config.maxSuspiciousZeros,
+      baselineFile: config.baselineFile,
+    },
+    metrics: {
+      discovered: audit.discovered,
+      analyzed: audit.analyzed,
+      zeroPrograms: audit.zeroPrograms,
+      failed: audit.failed,
+      coverage: audit.percentage,
+      analyzableCoverage: audit.analyzableCoverage,
+      unknownNodeRate: audit.unknownNodeRate,
+      suspiciousZeros: suspiciousCount,
+      zeroProgramCategoryCounts: audit.zeroProgramCategoryCounts,
+      durationMs: audit.durationMs,
+      wallClockMs: Date.now() - startedAt,
+    },
+  };
+
+  if (violations.length > 0) {
+    console.error(
+      JSON.stringify(
+        {
+          status: 'fail',
+          violations,
+          summary,
+          suspiciousZeroSample: audit.suspiciousZeros.slice(0, 50),
+        },
+        null,
+        2,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        status: 'pass',
+        summary,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+void main();

package/scripts/audit-public-effect-modules.ts

@@ -0,0 +1,111 @@
+import { Effect } from 'effect';
+import { join, resolve } from 'path';
+import { analyze } from '../src/analyze';
+
+const DEFAULT_EFFECT_REPO_PATH = '/Users/jagreehal/dev/js/awaitly/__temp/effect';
+
+function getEffectRepoPath(): string {
+  return resolve(process.env.EFFECT_REPO_PATH ?? DEFAULT_EFFECT_REPO_PATH);
+}
+
+function getArgValue(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return undefined;
+  const next = process.argv[idx + 1];
+  if (!next || next.startsWith('--')) return undefined;
+  return next;
+}
+
+function getModules(): string[] {
+  const raw = getArgValue('--modules');
+  if (!raw) return ['Effect.ts', 'Layer.ts', 'Schedule.ts', 'Stream.ts', 'Chunk.ts'];
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+async function auditModule(
+  filePath: string,
+  knownEffectInternalsRoot: string,
+): Promise<unknown> {
+  const base = await Effect.runPromise(
+    analyze(filePath, { knownEffectInternalsRoot }).all().pipe(Effect.either),
+  );
+  if (base._tag === 'Left') {
+    return { file: filePath, error: base.left.code };
+  }
+
+  const rows = base.right;
+  const low = rows.filter((r) => r.root.discoveryConfidence === 'low');
+  const medium = rows.filter((r) => r.root.discoveryConfidence === 'medium');
+  const high = rows.filter((r) => r.root.discoveryConfidence === 'high');
+
+  const publicHigh = await Effect.runPromise(
+    analyze(filePath, {
+      knownEffectInternalsRoot,
+      onlyExportedPrograms: true,
+      minDiscoveryConfidence: 'high',
+    }).all().pipe(Effect.either),
+  );
+
+  const exportedAll = await Effect.runPromise(
+    analyze(filePath, {
+      knownEffectInternalsRoot,
+      onlyExportedPrograms: true,
+      minDiscoveryConfidence: 'low',
+    }).all().pipe(Effect.either),
+  );
+
+  const exportedLowNames =
+    exportedAll._tag === 'Left'
+      ? []
+      : exportedAll.right
+          .filter((r) => r.root.discoveryConfidence === 'low')
+          .map((r) => r.root.programName);
+
+  return {
+    file: filePath,
+    total: rows.length,
+    confidence: {
+      high: high.length,
+      medium: medium.length,
+      low: low.length,
+    },
+    lowNames: low.map((r) => r.root.programName),
+    exportedLowNames,
+    launchReadyPublicSurface: exportedLowNames.length === 0,
+    publicHigh:
+      publicHigh._tag === 'Left'
+        ? { error: publicHigh.left.code }
+        : {
+            count: publicHigh.right.length,
+            sample: publicHigh.right.slice(0, 20).map((r) => r.root.programName),
+          },
+  };
+}
+
+async function main(): Promise<void> {
+  const effectRepoPath = getEffectRepoPath();
+  const srcRoot = join(effectRepoPath, 'packages', 'effect', 'src');
+  const internalsRoot = join(srcRoot, 'internal');
+  const modules = getModules();
+
+  const reports = [];
+  for (const mod of modules) {
+    reports.push(await auditModule(join(srcRoot, mod), internalsRoot));
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        effectRepoPath,
+        srcRoot,
+        internalsRoot,
+        modules,
+        reports,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+void main();

package/scripts/baselines/effect-audit-baseline.json

@@ -0,0 +1,14 @@
+{
+  "notes": "Observed on 2026-02-25 against /Users/jagreehal/dev/js/awaitly/__temp/effect/packages with KNOWN_EFFECT_INTERNALS_ROOT set. Tighten budgets over time.",
+  "maxFailed": 0,
+  "maxUnknownNodeRate": 0.1463,
+  "maxSuspiciousZeros": 63,
+  "metrics": {
+    "discovered": 1756,
+    "analyzed": 1043,
+    "zeroPrograms": 713,
+    "failed": 0,
+    "unknownNodeRate": 0.14623301179761178,
+    "suspiciousZeros": 63
+  }
+}

package/scripts/benchmark.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env npx tsx
+/**
+ * Benchmark script — runs coverage audit across repos and stores JSON snapshots.
+ * Usage: npx tsx scripts/benchmark.ts [repo1] [repo2] ...
+ */
+import { Effect } from 'effect';
+import { runCoverageAudit } from '../src/project-analyzer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, basename, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const BENCHMARK_DIR = resolve(__dirname, '..', 'benchmarks');
+
+interface BenchmarkResult {
+  repo: string;
+  timestamp: string;
+  discovered: number;
+  analyzed: number;
+  zeroPrograms: number;
+  failed: number;
+  percentage: number;
+  analyzableCoverage: number;
+  unknownNodeRate: number;
+  suspiciousZerosCount: number;
+  durationMs: number;
+}
+
+async function benchmarkRepo(repoPath: string): Promise<BenchmarkResult> {
+  const start = Date.now();
+  const tsconfig = existsSync(join(repoPath, 'tsconfig.json'))
+    ? join(repoPath, 'tsconfig.json')
+    : undefined;
+
+  const audit = await Effect.runPromise(
+    runCoverageAudit(repoPath, { tsconfig }),
+  );
+
+  return {
+    repo: basename(repoPath),
+    timestamp: new Date().toISOString(),
+    discovered: audit.discovered,
+    analyzed: audit.analyzed,
+    zeroPrograms: audit.zeroPrograms,
+    failed: audit.failed,
+    percentage: Math.round(audit.percentage * 100) / 100,
+    analyzableCoverage: Math.round(audit.analyzableCoverage * 100) / 100,
+    unknownNodeRate: Math.round(audit.unknownNodeRate * 10000) / 10000,
+    suspiciousZerosCount: audit.suspiciousZeros.length,
+    durationMs: Date.now() - start,
+  };
+}
+
+async function main() {
+  const repos = process.argv.slice(2);
+  if (repos.length === 0) {
+    console.log('Usage: npx tsx scripts/benchmark.ts <repo-path> [repo-path2] ...');
+    process.exit(1);
+  }
+
+  if (!existsSync(BENCHMARK_DIR)) mkdirSync(BENCHMARK_DIR, { recursive: true });
+
+  const results: BenchmarkResult[] = [];
+  for (const repo of repos) {
+    const repoResolved = resolve(repo);
+    if (!existsSync(repoResolved)) {
+      console.log(`Skipping ${repo} — not found`);
+      continue;
+    }
+    console.log(`Benchmarking ${repoResolved}...`);
+    const result = await benchmarkRepo(repoResolved);
+    results.push(result);
+    console.log(`  discovered=${result.discovered} analyzed=${result.analyzed} zero=${result.zeroPrograms} failed=${result.failed}`);
+    console.log(`  coverage=${result.percentage}% analyzable=${result.analyzableCoverage}% unknownRate=${result.unknownNodeRate}`);
+    console.log(`  duration=${result.durationMs}ms`);
+  }
+
+  // Save snapshot
+  const snapshotPath = join(BENCHMARK_DIR, `benchmark-${new Date().toISOString().slice(0, 10)}.json`);
+  writeFileSync(snapshotPath, JSON.stringify(results, null, 2));
+  console.log(`\nSnapshot saved to ${snapshotPath}`);
+
+  // Compare with previous baseline if exists
+  const baselinePath = join(BENCHMARK_DIR, 'baseline.json');
+  if (existsSync(baselinePath)) {
+    const baseline: BenchmarkResult[] = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+    console.log('\nDeltas vs baseline:');
+    for (const result of results) {
+      const base = baseline.find((b) => b.repo === result.repo);
+      if (!base) {
+        console.log(`  ${result.repo}: NEW (no baseline)`);
+        continue;
+      }
+      const delta = (field: keyof BenchmarkResult) => {
+        const curr = result[field] as number;
+        const prev = base[field] as number;
+        const diff = curr - prev;
+        return diff >= 0 ? `+${diff}` : `${diff}`;
+      };
+      console.log(`  ${result.repo}: analyzed ${delta('analyzed')} | unknown ${delta('unknownNodeRate')} | coverage ${delta('percentage')}%`);
+    }
+  }
+}
+
+main().catch(console.error);