Metadata-Version: 2.4
Name: llm-sca-tooling
Version: 0.16.0
Summary: Evidence-first, LLM-augmented static code analysis: graph indexing, MCP server, audit workflows
Project-URL: Homepage, https://github.com/grammy-jiang/llm-sca-tooling
Project-URL: Repository, https://github.com/grammy-jiang/llm-sca-tooling
Project-URL: Changelog, https://github.com/grammy-jiang/llm-sca-tooling/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/grammy-jiang/llm-sca-tooling/issues
Author-email: Grammy Jiang <grammy.jiang@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: code-analysis,code-graph,fault-localisation,llm,mcp,sarif,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.13
Requires-Dist: defusedxml>=0.7
Requires-Dist: fastapi>=0.115
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.23
Requires-Dist: lxml>=5.2
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: networkx>=3.3
Requires-Dist: orjson>=3.10
Requires-Dist: pyan3>=2.6.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: selectolax>=0.3
Requires-Dist: sqlmodel>=0.0.21
Requires-Dist: tree-sitter-c>=0.23
Requires-Dist: tree-sitter-cpp>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: watchdog>=4.0
Provides-Extra: cpp
Requires-Dist: libclang>=18.1.1; extra == 'cpp'
Provides-Extra: embeddings
Requires-Dist: fastembed>=0.3; extra == 'embeddings'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Description-Content-Type: text/markdown

# llm-sca-tooling

**Evidence-first, LLM-augmented static code analysis.**

`llm-sca-tooling` gathers *typed evidence* from your repository — AST symbols,
call graphs, SARIF alerts, tests, runtime traces — grades it
(`parser > analyser > heuristic > unknown`), and only then lets an LLM reason
over the graded context. Findings carry their evidence grade; the tool never
upgrades confidence on its own, and it never edits your source. Humans decide
on remediation.

## Five product surfaces

1. **MCP server** — the primary integration surface: 45+ tools, 14 resources,
   12 prompts over stdio or Streamable HTTP. Point Claude Code (or any MCP
   client) at it and ask questions about your repository with
   evidence-graded answers.
2. **Workflow orchestrator** — bug resolve, patch review, SAST alert repair,
   implementation check (spec-vs-code compliance), and fault localisation.
   Every run produces a structured report, a run record, and a harness
   condition sheet.
3. **Evaluation harness** — a T1–T4 benchmark ladder with calibration
   reports; T1 runs in null mode (no LLM) and gates every CI check.
4. **Operational harness plane** — run records, incident tracking, trajectory
   memory with experience replay, operational reviews, release gates.
5. **Operational guardrails** — permission profiles, doom-loop and budget
   monitoring, governance-drift checks, privacy redaction, session replay.

## Install

```bash
pipx install llm-sca-tooling          # CLI + MCP server
# optional capabilities:
pipx inject llm-sca-tooling fastembed # semantic retrieval (embeddings)
pipx inject llm-sca-tooling anthropic # live LLM boundaries (llm_mode)
```

or in a project:

```bash
pip install "llm-sca-tooling[embeddings,llm]"
```

Graph indexing uses `universal-ctags` (`apt install universal-ctags` /
`brew install universal-ctags`).

### Indexing backend tiers

Per language, facts are graded by the strongest backend that produced them and
reconciled by confidence (a fact confirmed by several backends ranks higher):

| Tier | Backends | Confidence |
|---|---|---|
| Semantic (cross-file resolution) | Python AST + pyan3, **ts-morph** (TS/JS), **libclang** (C/C++) | parser, 1.0 |
| Real grammar (structural) | **tree-sitter** (Python, TS/JS, C/C++ — ships by default) | parser, 0.8 |
| Heuristic | regex fallbacks, ctags | heuristic, 0.6–0.7 |

tree-sitter is always on (grammars are bundled dependencies); the semantic
backends need their optional toolchain (Node/ts-morph, the `cpp` extra) and
fall back through these tiers when absent.

### Optional: full-fidelity TypeScript/JavaScript

The TypeScript/JavaScript backend uses **ts-morph** for parser-grade facts
(resolved cross-file imports and call edges). It needs Node.js and a one-time
dependency install:

```bash
cd <site-packages>/llm_sca_tooling/indexing/backends/typescript/runner
npm install
```

Without Node/ts-morph the backend transparently falls back to a heuristic
regex parser — lower fidelity, but indexing still works.

### Optional: full-fidelity C/C++

The C/C++ backend uses **libclang** (`clang.cindex`) for parser-grade facts
(resolved symbols, `#include` edges, cross-file call edges). The `cpp` extra
bundles a loadable libclang — no system toolchain needed:

```bash
pip install "llm-sca-tooling[cpp]"
```

It honours `compile_commands.json` at the repo root when present. Without
libclang the backend falls back to the heuristic regex parser.

## Quickstart

```bash
llm-sca-tooling config validate
llm-sca-tooling mcp serve --transport stdio   # start the MCP server
```

Register with Claude Code:

```bash
claude mcp add llm-sca-tooling -- llm-sca-tooling mcp serve
```

Then, from your MCP client:

```text
register_repo(repo_path="/path/to/repo")
graph_build(repo_path="/path/to/repo")        # async — poll task_status
get_relevant_files(issue_text="NullPointerException in UserService.authenticate")
run_implementation_check(spec="<your architecture doc>", task=true)
run_issue_resolution(issue_text="<bug report>")
```

### LLM mode

Workflows run in **null mode** by default — deterministic heuristics only,
suitable for CI. With the `llm` extra installed and `ANTHROPIC_API_KEY`
exported, pass `llm_mode: true` to `run_implementation_check` to enable the
LLM boundaries (clause grounding, contract generation). Runs degrade to null
mode when no provider is available and report `llm_mode_active` so a degraded
run is never mistaken for an LLM-graded one. Model selection via
`LLM_SCA_MODEL` (default `claude-opus-4-8`).

## Evidence hierarchy

| Grade | Source | Confidence |
|---|---|---|
| `parser` | ctags AST, language servers, exact SARIF locations | High |
| `analyser` | dataflow, cross-file call graph | Medium-high |
| `heuristic` | pattern matching, keyword search, LLM-classified groundings | Medium |
| `unknown` | no hard evidence — reported honestly, never auto-passed | Low |

Every LLM-derived artefact is fail-closed: unparseable output degrades to the
deterministic null path, citations are filtered to evidence actually
provided, generated predicates must compile before they count, and LLM
groundings carry a `derivation="llm"` audit field.

## Governance

Development of this repository is governed by [AGENTS.md](AGENTS.md): hard
constraints (no secrets, write allowlists, deny-by-default egress), a
verify-before-commit gate (`make verify`), live session telemetry, and
harness condition sheets for every evaluation and release run.

## Documentation

- [Installation](docs/installation.md) ·
  [Quickstart](docs/quickstart.md) ·
  [Architecture](docs/architecture.md)
- [Evaluation guide](docs/evaluation-guide.md) ·
  [Harness setup](docs/harness-setup-guide.md) ·
  [Plugin authoring](docs/plugin-authoring-guide.md) ·
  [Incident response](docs/incident-response-guide.md)
- [CHANGELOG](CHANGELOG.md)

## License

[MIT](LICENSE)
