Skip to content

docs: update CLAUDE.md and README.md with verified codebase facts #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aksOps merged 1 commit into from
Apr 1, 2026
Merged

docs: update CLAUDE.md and README.md with verified codebase facts #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 36 additions & 13 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
- JavaParser 3.28.0 (Java AST analysis)
- ANTLR 4.13.2 (TypeScript/JavaScript, Python, Go, C#, Rust, C++ grammars)
- Picocli 4.7.7 (CLI framework, integrated with Spring Boot)
- Thymeleaf + HTMX (web UI)
- React 18 + TypeScript + Vite 6 + Tailwind CSS (web UI)
- H2 (incremental analysis cache)

## Architecture
Expand Down Expand Up @@ -96,10 +96,10 @@ io.github.randomcodespace.iq
|-- grammar/ # ANTLR parser factory + generated parsers
|-- graph/ # GraphStore (Neo4j facade), GraphRepository (SDN, writes only)
|-- health/ # GraphHealthIndicator (Spring Actuator)
|-- mcp/ # McpTools (30 @McpTool methods, read-only)
|-- mcp/ # McpTools (31 @McpTool methods, read-only)
|-- model/ # CodeNode, CodeEdge, NodeKind (32), EdgeKind (27)
|-- query/ # QueryService, StatsService (categorized), TopologyService
|-- web/ # ExplorerController (Thymeleaf web UI)
|-- web/ # Static resource serving (React SPA)
```

## Critical Rules
Expand Down Expand Up @@ -144,6 +144,7 @@ io.github.randomcodespace.iq
| `bundle [path]` | Package graph + source into distributable ZIP |
| `cache [action]` | Manage analysis cache |
| `plugins [action]` | List and inspect detectors |
| `topology [path]` | Show service topology map |
| `version` | Show version info |

### Standard Pipeline
Expand All @@ -161,25 +162,46 @@ code-iq serve /path/to/repo # needs enrich if using index

## Server Endpoints (all read-only)

### REST API (`/api`)
### REST API (`/api`) -- 34 endpoints

**GraphController** (`/api`):
- `GET /api/stats` -- Rich categorized statistics (graph, languages, frameworks, infra, connections, auth, architecture)
- `GET /api/stats/detailed?category=` -- Single category stats
- `GET /api/kinds` -- Node kinds with counts
- `GET /api/kinds/{kind}` -- Paginated nodes by kind
- `GET /api/nodes`, `GET /api/edges` -- Paginated queries
- `GET /api/nodes` -- Paginated node queries
- `GET /api/nodes/{id}/detail` -- Full node detail with edges
- `GET /api/nodes/{id}/neighbors` -- Neighbor traversal
- `GET /api/edges` -- Paginated edge queries
- `GET /api/ego/{center}` -- Ego subgraph
- `GET /api/query/cycles`, `/shortest-path`, `/consumers/{id}`, `/producers/{id}`, `/callers/{id}`, `/dependencies/{id}`, `/dependents/{id}`
- `GET /api/query/cycles` -- Cycle detection
- `GET /api/query/shortest-path` -- Shortest path between nodes
- `GET /api/query/consumers/{id}`, `/producers/{id}`, `/callers/{id}`, `/dependencies/{id}`, `/dependents/{id}`
- `GET /api/query/dead-code` -- Dead code detection (semantic edge filtering, excludes entry points)
- `GET /api/triage/component?file=`, `/impact/{id}` -- Agentic triage
- `GET /api/triage/component?file=` -- Agentic triage by file
- `GET /api/triage/impact/{id}` -- Impact trace
- `GET /api/search?q=` -- Free-text search
- `GET /api/file?path=` -- Source files (path traversal protected)
- `GET /api/flow/{view}` -- Flow diagrams
- `GET /api/topology` -- Service topology map

### MCP Tools (30, via `@McpTool` annotation)
`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`, `get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`
**TopologyController** (`/api/topology`):
- `GET /api/topology` -- Service topology map
- `GET /api/topology/services/{name}` -- Service detail
- `GET /api/topology/services/{name}/deps` -- Service dependencies
- `GET /api/topology/services/{name}/dependents` -- Service dependents
- `GET /api/topology/blast-radius/{nodeId}` -- Blast radius analysis
- `GET /api/topology/path` -- Find path between services
- `GET /api/topology/bottlenecks` -- Find bottleneck services
- `GET /api/topology/circular` -- Circular dependency detection
- `GET /api/topology/dead` -- Dead service detection

**FlowController** (`/api/flow`):
- `GET /api/flow` -- List available flow views
- `GET /api/flow/{view}` -- Flow diagram for specific view
- `GET /api/flow/{view}/{nodeId}/children` -- Node children in flow
- `GET /api/flow/{view}/{nodeId}/parent` -- Node parent in flow

### MCP Tools (31, via `@McpTool` annotation)
`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`, `get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`, `find_node`

## Adding a New Detector

Expand Down Expand Up @@ -218,7 +240,7 @@ code-iq serve /path/to/repo # needs enrich if using index
## Testing

```bash
# Run all tests (~1385 tests)
# Run all tests (~1440 tests)
mvn test

# Run a specific test class
Expand Down Expand Up @@ -287,7 +309,7 @@ mvn dependency-check:check
| `config/JacksonConfig.java` | Jackson config (FAIL_ON_UNKNOWN_PROPERTIES disabled for MCP compat) |
| `cache/AnalysisCache.java` | H2 incremental cache |
| `api/GraphController.java` | REST API endpoints (read-only) |
| `mcp/McpTools.java` | 30 MCP tool definitions (`@McpTool`, read-only) |
| `mcp/McpTools.java` | 31 MCP tool definitions (`@McpTool`, read-only) |
| `query/QueryService.java` | Graph query operations with Spring caching |
| `query/StatsService.java` | Rich categorized statistics (7 categories) |
| `query/TopologyService.java` | Service topology queries |
Expand Down Expand Up @@ -321,6 +343,7 @@ mvn dependency-check:check
- `codeiq.max-radius` -- max ego graph radius (default: 10)
- `codeiq.max-depth` -- max impact trace depth (default: 10)
- `codeiq.batch-size` -- files per H2 flush batch (default: 500)
- `codeiq.neo4j.enabled` -- Neo4j conditional toggle (default: `true`, overridden to `false` in `indexing` profile)
- `spring.ai.mcp.server.protocol` -- MCP protocol (STREAMABLE)

### Project-level overrides (`.osscodeiq.yml`)
Expand Down
30 changes: 16 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@

---

**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (31 tools), REST API (32+ endpoints), React web UI, and zero AI dependency.
**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (31 tools), REST API (34 endpoints), React web UI, and zero AI dependency.

## Quick Start

Expand Down Expand Up @@ -50,18 +50,18 @@ java -jar target/code-iq-*-cli.jar serve /path/to/repo
- **Neo4j Embedded** graph database -- full Cypher query support, no external server needed
- **H2 analysis cache** -- batched streaming for memory-efficient indexing on CI runners
- **Spring AI MCP server** -- 31 tools via streamable HTTP for AI-powered triage
- **REST API** -- 32+ endpoints for programmatic access
- **React UI** -- Dashboard, Topology (Cytoscape.js), Explorer, Flow, MCP Console (Monaco Editor), API Docs
- **REST API** -- 34 endpoints for programmatic access
- **React UI** -- Dashboard, Topology (Cytoscape.js), Explorer, Flow, MCP Console, API Docs (Swagger)
- **Service Topology** -- AppDynamics-style service map with blast radius, circular deps, bottleneck detection
- **CLI with 14 commands** -- analyze, index, enrich, serve, stats, graph, query, find, flow, bundle, cache, plugins, topology, version
- **CLI with 15 commands** -- analyze, index, enrich, serve, stats, graph, query, find, cypher, flow, topology, bundle, cache, plugins, version
- **Virtual threads** (Java 25) -- adaptive parallelism across all available cores
- **Config-driven pipeline** -- `.osscodeiq.yml` to control languages, detectors, parsers, excludes
- **Multi-repo support** -- `--graph` + `--service-name` for shared graph across repositories
- **Flow diagrams** -- interactive Cytoscape.js architecture diagrams (Overview, CI, Deploy, Runtime, Auth views)
- **Bundle & distribute** -- package graph DB + source + interactive HTML into a ZIP
- **100% deterministic** -- same input, same output, every time
- **Incremental analysis** -- H2-backed file hash cache, only re-analyzes changed files
- **1,227 tests** passing
- **1,440 tests** passing

## Three-Command Architecture

Expand Down Expand Up @@ -129,6 +129,7 @@ Spring Security, Django Auth, FastAPI Auth, NestJS Guards, Passport/JWT, K8s RBA
| `graph [path]` | Export graph in various formats (JSON, YAML, Mermaid, DOT) |
| `query [path]` | Query graph relationships (consumers, producers, callers, etc.) |
| `find [what] [path]` | Preset queries (endpoints, guards, entities, topics, etc.) |
| `cypher [query]` | Execute raw Cypher queries against Neo4j |
| `topology [path]` | Service topology queries (blast radius, circular deps, bottlenecks) |
| `flow [path]` | Generate architecture flow diagrams |
| `bundle [path]` | Package graph + source into distributable ZIP |
Expand Down Expand Up @@ -195,7 +196,7 @@ code-iq serve /path/to/repo
| | |
v v v
REST API MCP React UI
(32+ ep) (31 tools) (6 pages)
(34 ep) (31 tools) (6 pages)
```

## Server
Expand All @@ -212,12 +213,12 @@ Modern React 18 + TypeScript + Tailwind CSS interface:
- **Topology** -- Cytoscape.js service dependency map with drill-down
- **Explorer** -- browse by node kind, click to drill into details with edges
- **Flow** -- interactive architecture diagrams (Overview, CI, Deploy, Runtime, Auth)
- **Console** -- Monaco Editor for MCP tool invocation
- **Console** -- MCP Inspector for tool invocation with category filters and JSON response viewer
- **API Docs** -- embedded Swagger/OpenAPI documentation
- Dark/light/system theme toggle

### REST API (`/api`)
32+ endpoints for programmatic access:
34 endpoints for programmatic access:
- `/api/stats`, `/api/stats/detailed?category=` -- graph and categorized statistics
- `/api/kinds`, `/api/kinds/{kind}` -- node kinds with counts, paginated nodes
- `/api/nodes`, `/api/edges` -- paginated queries with `?kind=&limit=&offset=`
Expand All @@ -228,17 +229,18 @@ Modern React 18 + TypeScript + Tailwind CSS interface:
- `/api/triage/component?file=`, `/api/triage/impact/{id}` -- agentic triage
- `/api/search?q=` -- free-text graph search
- `/api/file?path=` -- source files (path traversal protected)
- `/api/flow/{view}` -- flow diagrams
- `POST /api/analyze` -- trigger analysis
- `/api/flow`, `/api/flow/{view}`, `/api/flow/{view}/{nodeId}/children`, `/api/flow/{view}/{nodeId}/parent` -- flow diagrams
- `/api/topology/services/{name}/deps`, `/api/topology/services/{name}/dependents` -- service dependencies
- `/api/topology/path` -- find path between services

### MCP Server (`/mcp`)
31 tools via Spring AI streamable HTTP for AI-powered code triage:

**Core (21 tools):**
`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `generate_flow`, `analyze_codebase`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`
`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`

**Topology (10 tools):**
`get_topology`, `get_service_detail`, `get_service_dependencies`, `get_service_dependents`, `get_blast_radius`, `find_service_path`, `find_bottlenecks`, `find_circular_dependencies`, `find_dead_services`, `find_topology_node`
`get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`, `find_node`

## Service Topology

Expand Down Expand Up @@ -340,7 +342,7 @@ cd code-iq
# Build
mvn clean package

# Run tests (1,227 tests)
# Run tests (1,440 tests)
mvn test

# Analyze this repo
Expand Down Expand Up @@ -369,7 +371,7 @@ java -jar target/code-iq-*-cli.jar serve .
| Graph DB | Neo4j Embedded 2026.02.3 (Community Edition) |
| Analysis Cache | H2 (pure Java, virtual thread safe) |
| Cache | Spring Cache (simple in-memory, @Cacheable on query methods) |
| MCP | Spring AI 1.1.4 (streamable HTTP) |
| MCP | Spring AI 2.0.0-M3 (streamable HTTP) |
| Java AST | JavaParser 3.28.0 |
| Multi-lang AST | ANTLR 4.13.2 (10 grammars) |
| CLI | Picocli 4.7.7 |
Expand Down
Loading