TS Dependency Analyzer

Analyze TypeScript/JavaScript dependencies, build a directed graph (imports/exports/require/dynamic import), compute metrics (fan-in/out, density, mutual pairs, complexity), find cycles (Tarjan SCC), and generate a heuristic (LLM-free) analysis. Optionally add LLM insights (Gemini) while never sending file contents — only graph metadata.

---

Features

• Supports: import, export from, require, import(), import = require(), with warnings for non-literal specifiers.
• TypeScript-aware resolution (honors tsconfig.json: paths, baseUrl, rootDirs, extensions).
• Metrics: fan-in / fan-out, density, mutual pairs, normalized coupling score, complexity score.
• Cycle detection via Tarjan SCCs and an LLM-free heuristic narrative.
• Optional Gemini insights (on metadata only; no source code).
• CLI and HTTP API (the server is in server/server.ts).
• Vitest test suite with ≥80% coverage.

---

Requirements

• Node.js 18+ (20+ recommended)
• pnpm / npm / yarn
• (optional) GEMINI_API_KEY if you plan to use --llm gemini

---

Project Structure

ai-api
├─ app/
│  ├─ ApplicationService.ts
│  └─ ports.ts
├─ analyzer/
│  ├─ depsExtractor.ts
│  ├─ fileScanner.ts
│  ├─ graph.ts
│  ├─ heuristics.ts
│  ├─ metrics.ts
│  ├─ narrative.ts
│  ├─ rules.ts
│  └─ tsResolver.ts
├─ composition/
│  ├─ makeAnalyzer.ts
│  ├─ makeRenderer.ts
│  └─ makeWriter.ts
├─ core/
│  └─ types.ts
├─ formats/
│  ├─ renderers.ts
│  ├─ reportGenerator.ts
│  └─ reportTypes.ts
├─ llm/
│  ├─ geminiProvider.ts
│  ├─ prompts.ts
│  └─ provider.ts
├─ server/
│  └─ server.ts   ← HTTP API server
├─ utils/
│  ├─ fsUtils.ts
│  └─ logger.ts
├─ test/          ← Vitest tests (≥80% coverage)
├─ index.ts       ← CLI entry
├─ package.json
├─ tsconfig.json
├─ vite.config.ts ← for Vitest
├─ .gitignore
└─ .env.example

---

Installation (choose one)

  cd ./ai-api

Option A: pnpm

pnpm install
pnpm build      # compile to dist/

Option B: npm

npm install
npm run build

Option C: yarn

yarn
yarn build

Option D (dev, no build): run directly from .ts

Requires tsx or ts-node. Example with tsx:

pnpm add -D tsx
npx tsx index.ts --root ./src --llm none
# or the server:
npx tsx server/server.ts

---

Usage (CLI)

Minimal analysis (no LLM)

node dist/index.js --root ./../src --llm none

Write a JSON report

node dist/index.js --root ./../src --llm none --json analysis.report.json

Include JS/JSX and import type edges

node dist/index.js --root ./../src --includeJS --includeTypeImports --llm none --json analysis.report.json

Analyze a different directory (e.g., ../src)

node dist/index.js --root ../src --llm none --json analysis.report.json

With Gemini insights (optional)

# macOS/Linux (bash/zsh)
export GEMINI_API_KEY=YOUR_KEY
# optional:
# export GEMINI_MODEL=gemini-2.5-flash

node dist/index.js --root ./../src --llm gemini --json analysis.report.json

Security: only metadata (edge endpoints, SCCs, aggregate metrics) is sent to the LLM. Never source code.

---

HTTP API (Server)

The server lives in server/server.ts.

Start from compiled build

# 1) build
npm build

# 2) run (PORT=5050 by default)
node dist/server/server.js

Start directly from TypeScript (dev)

npx tsx server/server.ts
# or: npx ts-node server/server.ts

Use

• Open in a browser: http://localhost:5050/ → quick help
• Example JSON analysis:

curl "http://localhost:5050/analyze?root=./../src&llm=none" | jq .
# available query params:
#   &includeJS=true
#   &includeTypeImports=true
#   &llm=none|gemini

You can set the port via env:
macOS/Linux: export PORT=5050
PowerShell: $env:PORT=5050

---

Full CLI Flags Reference

node dist/index.js --root <path> [--includeJS] [--includeTypeImports] [--json <file>] [--llm <none|gemini>]

Flag	Type	Default	Description
--root	string	./../src	Root directory to analyze.
--includeJS	boolean	false	Include .js/.jsx (in addition to .ts/.tsx).
--includeTypeImports	boolean	false	Include import type edges.
--json	string	""	Write the report to a JSON file.
--llm	enum	none	none or gemini. Adds LLM insights if configured.

---

Environment (.env)

See .env.example. Common settings:

LOG_LEVEL=info            # debug|info|warn|error
PORT=5050                 # HTTP server port
GEMINI_API_KEY=...        # only if you use --llm gemini
# GEMINI_MODEL=gemini-2.5-flash   # optional override

---

Scripts (package.json)

Add/verify:

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/index.js --root ./../src --llm none",
    "serve": "node dist/server/server.js",
    "test": "vitest --run",
    "coverage": "vitest run --coverage"
  }
}

---

Testing

npm test
npm coverage

• Coverage target: ≥80% lines/functions/branches.
• The suite covers: import extraction, resolver, graph algorithms, metrics, heuristics, composition, application flow, logger, and Gemini provider (mocked).

---

Troubleshooting

• fast-glob import/type errors → ensure your tsconfig.json includes:

  {
    "compilerOptions": {
      "esModuleInterop": true,
      "allowSyntheticDefaultImports": true
    }
  }

• Windows paths → the report normalizes to POSIX-style paths.
• Gemini 404/model → set a valid GEMINI_MODEL and correct GEMINI_API_KEY.
• No files found → confirm --root points to the folder containing your sources.

---