From d963ab0c96a8ff5686fb55e27bd5a12f4e6ba1fd Mon Sep 17 00:00:00 2001 From: Amit Kumar Date: Wed, 1 Apr 2026 05:17:32 +0000 Subject: [PATCH] docs: update CLAUDE.md and README.md with verified codebase facts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consolidates findings from 4 engineer review subtasks (RAN-44, RAN-45, RAN-46, RAN-47) to fix documentation discrepancies: - MCP tools: 30 → 31 (add find_node) - REST endpoints: unspecified/32+ → 34 with full controller breakdown - Test count: ~1385/1,227 → 1,440 - Spring AI version in README: 1.1.4 → 2.0.0-M3 - Remove POST /api/analyze and analyze_codebase (never existed) - Tech stack: Thymeleaf+HTMX → React 18+Vite 6+Tailwind CSS - CLI commands: add topology and cypher to tables - Add Neo4j conditional config property - Fix MCP tool names in README (match actual @McpTool method names) - Console description: Monaco Editor → MCP Inspector Co-Authored-By: Paperclip --- CLAUDE.md | 49 ++++++++++++++++++++++++++++++++++++------------- README.md | 30 ++++++++++++++++-------------- 2 files changed, 52 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ed8abe5e..9fb43226 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 | @@ -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`) diff --git a/README.md b/README.md index 3cfb9add..ebd7e9d5 100644 --- a/README.md +++ b/README.md @@ -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 @@ -50,10 +50,10 @@ 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 @@ -61,7 +61,7 @@ java -jar target/code-iq-*-cli.jar serve /path/to/repo - **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 @@ -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 | @@ -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 @@ -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=` @@ -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 @@ -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 @@ -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 |