@kevinrabun/judges 3.1.0 → 3.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Judges Panel
 
-An MCP (Model Context Protocol) server that provides a panel of **35 specialized judges** to evaluate AI-generated code — acting as an independent quality gate regardless of which project is being reviewed. Includes **built-in AST analysis** powered by the TypeScript Compiler API — no separate parser server needed.
+An MCP (Model Context Protocol) server that provides a panel of **35 specialized judges** to evaluate AI-generated code — acting as an independent quality gate regardless of which project is being reviewed. Combines **deterministic pattern matching & AST analysis** (instant, offline, zero LLM calls) with **LLM-powered deep-review prompts** that let your AI assistant perform expert-persona analysis across all 35 domains.
 
 **Highlights:**
 - Includes an **App Builder Workflow (3-step)** demo for release decisions, plain-language risk summaries, and prioritized fixes — see [Try the Demo](#2-try-the-demo).
@@ -9,12 +9,100 @@ An MCP (Model Context Protocol) server that provides a panel of **35 specialized
 
 [![CI](https://github.com/KevinRabun/judges/actions/workflows/ci.yml/badge.svg)](https://github.com/KevinRabun/judges/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@kevinrabun/judges)](https://www.npmjs.com/package/@kevinrabun/judges)
+[![npm downloads](https://img.shields.io/npm/dw/@kevinrabun/judges)](https://www.npmjs.com/package/@kevinrabun/judges)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-702-brightgreen)](https://github.com/KevinRabun/judges/actions)
+
+---
+
+## Why Judges?
+
+AI code generators (Copilot, Cursor, Claude, ChatGPT, etc.) write code fast — but they routinely produce **insecure defaults, missing auth, hardcoded secrets, and poor error handling**. Human reviewers catch some of this, but nobody reviews 35 dimensions consistently.
+
+| | ESLint / Biome | SonarQube | Semgrep / CodeQL | **Judges** |
+|---|---|---|---|---|
+| **Scope** | Style + some bugs | Bugs + code smells | Security patterns | **35 domains**: security, cost, compliance, a11y, API design, cloud, UX, … |
+| **AI-generated code focus** | No | No | Partial | **Purpose-built** for AI output failure modes |
+| **Setup** | Config per project | Server + scanner | Cloud or local | **One command**: `npx @kevinrabun/judges eval file.ts` |
+| **Auto-fix patches** | Some | No | No | **47 deterministic patches** — instant, offline |
+| **Non-technical output** | No | Dashboard | No | **Plain-language findings** with What/Why/Next |
+| **MCP native** | No | No | No | **Yes** — works inside Copilot, Claude, Cursor |
+| **SARIF output** | No | Yes | Yes | **Yes** — upload to GitHub Code Scanning |
+| **Cost** | Free | $$$$ | Free/paid | **Free / MIT** |
+
+**Judges doesn't replace linters** — it covers the dimensions linters don't: authentication strategy, data sovereignty, cost patterns, accessibility, framework-specific anti-patterns, and architectural issues across multiple files.
 
 ---
 
 ## Quick Start
 
+### Try it now (no clone needed)
+
+```bash
+# Install globally
+npm install -g @kevinrabun/judges
+
+# Evaluate any file
+judges eval src/app.ts
+
+# Pipe from stdin
+cat api.py | judges eval --language python
+
+# Single judge
+judges eval --judge cybersecurity server.ts
+
+# SARIF output for CI
+judges eval --file app.ts --format sarif > results.sarif
+
+# List all 35 judges
+judges list
+```
+
+### Use in GitHub Actions
+
+Add Judges to your CI pipeline with zero configuration:
+
+```yaml
+# .github/workflows/judges.yml
+name: Judges Code Review
+on: [pull_request]
+
+jobs:
+  judges:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # only if using upload-sarif
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KevinRabun/judges@main
+        with:
+          path: src/api.ts        # file or directory
+          format: text             # text | json | sarif | markdown
+          upload-sarif: true       # upload to GitHub Code Scanning
+          fail-on-findings: true   # fail CI on critical/high findings
+```
+
+**Outputs** available for downstream steps: `verdict`, `score`, `findings`, `critical`, `high`, `sarif-file`.
+
+### Use with Docker (no Node.js required)
+
+```bash
+# Build the image
+docker build -t judges .
+
+# Evaluate a local file
+docker run --rm -v $(pwd):/code judges eval --file /code/app.ts
+
+# Pipe from stdin
+cat api.py | docker run --rm -i judges eval --language python
+
+# List judges
+docker run --rm judges list
+```
+
+### Or use as an MCP server
+
 ### 1. Install and Build
 
 ```bash
@@ -279,24 +367,24 @@ This helps keep Copilot feedback aligned with Judges findings.
 
 The tribunal operates in three layers:
 
-1. **Pattern-Based Analysis** — All tools (`evaluate_code`, `evaluate_code_single_judge`, `evaluate_project`, `evaluate_diff`) perform heuristic analysis using regex pattern matching to catch common anti-patterns. This works entirely offline with zero external API calls.
+1. **Pattern-Based Analysis** — All tools (`evaluate_code`, `evaluate_code_single_judge`, `evaluate_project`, `evaluate_diff`) perform heuristic analysis using regex pattern matching to catch common anti-patterns. This layer is instant, deterministic, and runs entirely offline with zero external API calls.
 
-2. **AST-Based Structural Analysis** — The Code Structure judge (`STRUCT-*` rules) uses real Abstract Syntax Tree parsing to measure cyclomatic complexity, nesting depth, function length, parameter count, dead code, and type safety with precision that regex cannot achieve. JavaScript/TypeScript files are parsed via the TypeScript Compiler API; Python, Rust, Go, Java, and C# use a scope-tracking structural parser. No external AST server required.
+2. **AST-Based Structural Analysis** — The Code Structure judge (`STRUCT-*` rules) uses real Abstract Syntax Tree parsing to measure cyclomatic complexity, nesting depth, function length, parameter count, dead code, and type safety with precision that regex cannot achieve. JavaScript/TypeScript files are parsed via the TypeScript Compiler API. Python, Rust, Go, Java, and C# are parsed via **tree-sitter WASM grammars** — real syntax trees compiled to WebAssembly that run in-process with zero native dependencies. A scope-tracking structural parser is kept as a fallback when WASM grammars are unavailable. No external AST server required.
 
-3. **LLM-Powered Deep Analysis (Prompts)** — The server exposes MCP prompts (e.g., `judge-data-security`, `full-tribunal`) that provide each judge's expert persona as a system prompt. When used by an LLM-based client, this enables deeper, context-aware analysis beyond what static analysis can detect.
+3. **LLM-Powered Deep Analysis (Prompts)** — The server exposes MCP prompts (e.g., `judge-data-security`, `full-tribunal`) that provide each judge's expert persona as a system prompt. When used by an LLM-based client (Copilot, Claude, Cursor, etc.), the host LLM performs deeper, context-aware probabilistic analysis beyond what static patterns can detect. This is where the `systemPrompt` on each judge comes alive — Judges itself makes no LLM calls, but it provides the expert criteria so your AI assistant can act as 35 specialized reviewers.
 
 ---
 
 ## Composable by Design
 
-Judges Panel covers **heuristic pattern detection** and **AST structural analysis** in a single server — fast, offline, and self-contained. It does not try to be a CVE scanner or a linter. Those capabilities belong in dedicated MCP servers that an AI agent can orchestrate alongside Judges.
+Judges Panel is a **dual-layer** review system: instant **deterministic tools** (offline, no API keys) for pattern and AST analysis, plus **35 expert-persona MCP prompts** that unlock LLM-powered deep analysis when connected to an AI client. It does not try to be a CVE scanner or a linter. Those capabilities belong in dedicated MCP servers that an AI agent can orchestrate alongside Judges.
 
 ### Built-in AST Analysis (v2.0.0)
 
 Unlike earlier versions that recommended a separate AST MCP server, Judges Panel now includes **real AST-based structural analysis** out of the box:
 
 - **JavaScript / TypeScript** — Parsed with the TypeScript Compiler API (`ts.createSourceFile`) for full-fidelity AST
-- **Python, Rust, Go, Java, C#** — Analyzed with a scope-tracking structural parser that counts decision points and nesting levels
+- **Python, Rust, Go, Java, C#** — Parsed with **tree-sitter WASM grammars** for full syntax-tree analysis (functions, complexity, nesting, dead code, type safety). Falls back to a scope-tracking structural parser when WASM grammars are unavailable
 
 The Code Structure judge (`STRUCT-*`) uses these parsers to accurately measure:
 
@@ -723,7 +811,8 @@ judges/
 │   │   ├── index.ts          # analyzeStructure() — routes to correct parser
 │   │   ├── types.ts          # FunctionInfo, CodeStructure interfaces
 │   │   ├── typescript-ast.ts # TypeScript Compiler API parser (JS/TS)
-│   │   └── structural-parser.ts  # Scope-tracking parser (Python/Rust/Go/Java/C#)
+│   │   ├── tree-sitter-ast.ts    # Tree-sitter WASM parser (Python/Rust/Go/Java/C#)
+│   │   └── structural-parser.ts  # Fallback scope-tracking parser
 │   ├── evaluators/           # Analysis engine for each judge
 │   │   ├── index.ts          # evaluateWithJudge(), evaluateWithTribunal(), evaluateProject(), etc.
 │   │   ├── shared.ts         # Scoring, verdict logic, markdown formatters
@@ -741,6 +830,12 @@ judges/
 │   └── demo.ts                   # Run: npm run demo
 ├── tests/
 │   └── judges.test.ts            # Run: npm test
+├── grammars/                 # Tree-sitter WASM grammar files
+│   ├── tree-sitter-python.wasm
+│   ├── tree-sitter-go.wasm
+│   ├── tree-sitter-rust.wasm
+│   ├── tree-sitter-java.wasm
+│   └── tree-sitter-c_sharp.wasm
 ├── server.json               # MCP Registry manifest
 ├── package.json
 ├── tsconfig.json

package/dist/api.d.ts

@@ -19,6 +19,7 @@ export { LRUCache, contentHash } from "./cache.js";
 export { clearProjectCache } from "./evaluators/project.js";
 export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog } from "./formatters/sarif.js";
 export type { SarifValidationError } from "./formatters/sarif.js";
+export { runCli } from "./cli.js";
 import type { EvaluationOptions } from "./evaluators/index.js";
 import type { JudgeEvaluation, TribunalVerdict } from "./types.js";
 /**

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,KAAK,EACL,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGpF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAIxE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAGnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC7G,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAKlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAInE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,eAAe,CAEzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,eAAe,CAMjB"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,KAAK,EACL,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGpF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAIxE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAGnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC7G,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAKlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAInE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,eAAe,CAEzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,eAAe,CAMjB"}

package/dist/api.js

@@ -25,6 +25,8 @@ export { LRUCache, contentHash } from "./cache.js";
 export { clearProjectCache } from "./evaluators/project.js";
 // ─── Formatters ──────────────────────────────────────────────────────────────
 export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog } from "./formatters/sarif.js";
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+export { runCli } from "./cli.js";
 // ─── Convenience Aliases ─────────────────────────────────────────────────────
 import { evaluateWithTribunal, evaluateWithJudge } from "./evaluators/index.js";
 import { getJudge } from "./judges/index.js";

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+BH,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEpF,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzD,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAExE,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEnG,gFAAgF;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,gFAAgF;AAChF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG7G,gFAAgF;AAEhF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB,EAAE,OAA2B;IACtF,OAAO,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,OAA2B;IAE3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,eAAe,CAAC,mBAAmB,OAAO,GAAG,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+BH,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEpF,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzD,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAExE,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEnG,gFAAgF;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,gFAAgF;AAChF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG7G,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,gFAAgF;AAEhF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB,EAAE,OAA2B;IACtF,OAAO,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,OAA2B;IAE3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,eAAe,CAAC,mBAAmB,OAAO,GAAG,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}

package/dist/ast/index.d.ts

@@ -1,5 +1,6 @@
 import type { CodeStructure, FunctionInfo } from "./types.js";
 export type { CodeStructure, FunctionInfo };
+export { isTreeSitterAvailable, isTreeSitterReadySync } from "./tree-sitter-ast.js";
 export { analyzeTaintFlows } from "./taint-tracker.js";
 export type { TaintFlow, TaintSourceKind, TaintSinkKind } from "./taint-tracker.js";
 export { analyzeCrossFileTaint } from "./cross-file-taint.js";
@@ -7,10 +8,20 @@ export type { CrossFileTaintFlow } from "./cross-file-taint.js";
 /**
  * Analyse source code structurally. For JavaScript/TypeScript this uses the
  * TypeScript compiler API (full AST). For Python, Rust, Go, Java, and C# it
- * uses a lightweight scope-tracking parser.
+ * uses tree-sitter (real AST via WASM) when available, falling back to the
+ * lightweight scope-tracking parser.
  *
  * Returns function metrics (complexity, nesting, length, params), dead code
  * locations, deep-nesting locations, and type-safety issues.
  */
 export declare function analyzeStructure(code: string, language: string): CodeStructure;
+/**
+ * Async version of analyzeStructure that uses tree-sitter (real AST) for
+ * Python, Rust, Go, Java, and C# when WASM grammars are available.
+ * Falls back to the structural parser if tree-sitter is not available.
+ *
+ * Prefer this over analyzeStructure() for Tier 2 languages — it provides
+ * the same depth of analysis that the TS Compiler API gives JS/TS.
+ */
+export declare function analyzeStructureAsync(code: string, language: string): Promise<CodeStructure>;
 //# sourceMappingURL=index.d.ts.map

package/dist/ast/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CA6B9E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAG5C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAahE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAuC9E;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsClG"}

package/dist/ast/index.js

@@ -1,20 +1,33 @@
 // ─────────────────────────────────────────────────────────────────────────────
 // AST Analysis — Unified Entry Point
 // ─────────────────────────────────────────────────────────────────────────────
-// Routes to the TypeScript compiler-based parser for JS/TS or the lightweight
-// structural parser for Python, Rust, Go, Java, and C#.
+// Routes to the TypeScript compiler-based parser for JS/TS, the tree-sitter
+// real-AST parser for Python, Rust, Go, Java, and C# (when WASM grammars are
+// available), or the lightweight structural parser as a fallback.
 // ─────────────────────────────────────────────────────────────────────────────
 import { normalizeLanguage } from "../language-patterns.js";
 import { analyzeTypeScript } from "./typescript-ast.js";
 import { analyzeStructurally } from "./structural-parser.js";
+import { isTreeSitterAvailable, isTreeSitterReadySync, analyzeWithTreeSitter, analyzeWithTreeSitterSync, } from "./tree-sitter-ast.js";
+// Re-export tree-sitter availability checks
+export { isTreeSitterAvailable, isTreeSitterReadySync } from "./tree-sitter-ast.js";
 // Re-export taint analysis
 export { analyzeTaintFlows } from "./taint-tracker.js";
 // Re-export cross-file taint analysis
 export { analyzeCrossFileTaint } from "./cross-file-taint.js";
+// ─── Tree-sitter Warm-up ────────────────────────────────────────────────────
+// Pre-initialize tree-sitter on module load so it's ready when needed.
+// This is fire-and-forget; if it fails, analyzeStructure falls back silently.
+const TREE_SITTER_LANGS = ["python", "rust", "go", "java", "csharp"];
+const treeSitterReady = new Map();
+for (const lang of TREE_SITTER_LANGS) {
+    treeSitterReady.set(lang, isTreeSitterAvailable(lang));
+}
 /**
  * Analyse source code structurally. For JavaScript/TypeScript this uses the
  * TypeScript compiler API (full AST). For Python, Rust, Go, Java, and C# it
- * uses a lightweight scope-tracking parser.
+ * uses tree-sitter (real AST via WASM) when available, falling back to the
+ * lightweight scope-tracking parser.
  *
  * Returns function metrics (complexity, nesting, length, params), dead code
  * locations, deep-nesting locations, and type-safety issues.
@@ -30,6 +43,17 @@ export function analyzeStructure(code, language) {
         case "go":
         case "java":
         case "csharp":
+            // Use tree-sitter (real AST) if WASM runtime + grammar already loaded,
+            // otherwise fall back to the lightweight structural parser.
+            // parser.parse() is synchronous in web-tree-sitter once initialized.
+            if (isTreeSitterReadySync(lang)) {
+                try {
+                    return analyzeWithTreeSitterSync(code, lang);
+                }
+                catch {
+                    // Tree-sitter failed at runtime — fall back silently
+                }
+            }
             return analyzeStructurally(code, lang);
         default:
             // Unknown language — return a minimal structure
@@ -46,4 +70,49 @@ export function analyzeStructure(code, language) {
             };
     }
 }
+/**
+ * Async version of analyzeStructure that uses tree-sitter (real AST) for
+ * Python, Rust, Go, Java, and C# when WASM grammars are available.
+ * Falls back to the structural parser if tree-sitter is not available.
+ *
+ * Prefer this over analyzeStructure() for Tier 2 languages — it provides
+ * the same depth of analysis that the TS Compiler API gives JS/TS.
+ */
+export async function analyzeStructureAsync(code, language) {
+    const lang = normalizeLanguage(language);
+    switch (lang) {
+        case "javascript":
+        case "typescript":
+            return analyzeTypeScript(code, lang);
+        case "python":
+        case "rust":
+        case "go":
+        case "java":
+        case "csharp": {
+            // Try tree-sitter first (real AST), fall back to structural parser
+            const available = await (treeSitterReady.get(lang) ?? Promise.resolve(false));
+            if (available) {
+                try {
+                    return await analyzeWithTreeSitter(code, lang);
+                }
+                catch {
+                    // Tree-sitter failed at runtime — fall back silently
+                }
+            }
+            return analyzeStructurally(code, lang);
+        }
+        default:
+            return {
+                language: lang,
+                totalLines: code.split("\n").length,
+                functions: [],
+                fileCyclomaticComplexity: 1,
+                maxNestingDepth: 0,
+                deadCodeLines: [],
+                deepNestLines: [],
+                typeAnyLines: [],
+                imports: [],
+            };
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/ast/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;AAChF,8EAA8E;AAC9E,wDAAwD;AACxD,gFAAgF;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAK7D,2BAA2B;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,sCAAsC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB;IAC7D,MAAM,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAEzC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEvC,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,IAAI,CAAC;QACV,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ;YACX,OAAO,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEzC;YACE,gDAAgD;YAChD,OAAO;gBACL,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM;gBACnC,SAAS,EAAE,EAAE;gBACb,wBAAwB,EAAE,CAAC;gBAC3B,eAAe,EAAE,CAAC;gBAClB,aAAa,EAAE,EAAE;gBACjB,aAAa,EAAE,EAAE;gBACjB,YAAY,EAAE,EAAE;gBAChB,OAAO,EAAE,EAAE;aACZ,CAAC;IACN,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"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"}

package/dist/ast/tree-sitter-ast.d.ts

@@ -0,0 +1,34 @@
+import type { CodeStructure } from "./types.js";
+/**
+ * Check whether tree-sitter analysis is available for a given language.
+ * Must be called (and awaited) before analyzeWithTreeSitter.
+ */
+export declare function isTreeSitterAvailable(lang: string): Promise<boolean>;
+/**
+ * Synchronous readiness check — returns true only if tree-sitter's WASM
+ * runtime AND the grammar for `lang` have already been loaded into memory.
+ * This is safe to call from synchronous code paths; if the async init
+ * hasn't finished yet, it simply returns false and the caller falls back
+ * to the structural parser.
+ */
+export declare function isTreeSitterReadySync(lang: string): boolean;
+/**
+ * Synchronous tree-sitter analysis. Can ONLY be called when
+ * isTreeSitterReadySync(lang) returns true (i.e. parser module and grammar
+ * are already loaded). parser.parse() is synchronous in web-tree-sitter
+ * once the WASM runtime and grammar are in memory.
+ *
+ * Returns the same CodeStructure interface as analyzeWithTreeSitter.
+ * Throws if preconditions are not met.
+ */
+export declare function analyzeWithTreeSitterSync(code: string, language: string): CodeStructure;
+/**
+ * Analyse source code using tree-sitter's real syntax tree.
+ * Returns the same CodeStructure interface as the TypeScript and
+ * structural parsers — but with much higher precision for non-JS/TS languages.
+ *
+ * IMPORTANT: Call isTreeSitterAvailable(lang) first. If it returns false,
+ * fall back to analyzeStructurally().
+ */
+export declare function analyzeWithTreeSitter(code: string, language: string): Promise<CodeStructure>;
+//# sourceMappingURL=tree-sitter-ast.d.ts.map

package/dist/ast/tree-sitter-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-sitter-ast.d.ts","sourceRoot":"","sources":["../../src/ast/tree-sitter-ast.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAkG9D;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAKvF;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAKlG"}