Code Analysis Suite

See the Architecture Before You Change It

Code Analysis Suite provides evidence for understanding a codebase before deciding how to change it. It collects structural observations, binds them to source locations and hashes, and retains them in a validated JSON report. Tables, diagrams, comparisons, and review packets are views of that saved evidence, not reasons to keep rescanning the same source.

The project is in beta, with 0.2.0b1 as the documented candidate version. Command-line scanning, report generation, and exports are the established workflows. The local browser interface is actively being tested and refined; beta feedback is particularly useful for confusing navigation, source investigation, and finding the right evidence. This is not a stable API or report-format compatibility promise.

What It Examines

• Structure and dependencies: source roots, modules, symbols, spans, local imports, import cycles, and complexity metrics.
• Contracts and data flow: Python contracts, dictionary shapes, validation, lifecycle evidence, and bounded producer/consumer relationships.
• Refactoring review: clone/commonality evidence, state and side effects, responsibility groups, and bounded proposals with explicit evidence limits.
• Change and test evidence: static test impact, explicitly requested Git history, imported coverage, and opt-in Python profiling.
• Investigation and presentation: saved-report queries, comparisons, tables, graphs, review packets, and hash-verified source browsing.

Python has the broadest analytical coverage through its standard-library AST frontend. JavaScript/JSX collection uses optional Tree-sitter dependencies; Ruby uses an existing Ruby/Prism installation through a parser driver. Capabilities differ by language, and reports preserve partial, unsupported, and unavailable evidence. TypeScript/TSX and automatic source refactoring are not supported.

Evidence You Can Keep and Revisit

The authoritative code-analysis-report JSON retains source-relative paths, SHA-256 source hashes, configuration identity, provider status, diagnostics, completeness, limitations, and stable evidence IDs. Saved evidence can be queried, compared, and exported without another source scan. Browsing original source separately requires matching files and hashes.

The CLI can produce reports and projections in formats including Markdown, tables, DOT, Mermaid, and graphics where supported by the selected view. SVG/PNG graph rendering requires an available Graphviz executable. Missing providers and renderers remain explicit; an unavailable tool does not become an empty successful result. The report and diagram catalog documents individual views and their limitations.

A finding is a reason to investigate, not permission to edit. High complexity does not establish an extraction boundary, an import cycle is not automatically a defect, and static observations cannot prove runtime behavior or semantic equivalence.

Local Browser and Terminal Investigation

The loopback WebUI supports saved-report exploration, comparisons, verified source navigation, contextual offline help, and session-only editing drafts. Its shared browser components come from LocalOps UI Kit; the application retains ownership of analytical meaning and operational behavior. The optional Textual interface provides another route into saved evidence.

Opening the browser UI does not start a scan. Use --no-collection when browsing saved reports without collection-launch capability. Closing a browser tab does not stop its background session; use the application’s stop control or code-analysis ui-stop as documented in the UI guide.

Getting Started

Python 3.12 or newer is required. Install from the source repository in an isolated environment rather than assuming a PyPI release:

git clone https://github.com/unixwzrd/code-analytics.git
cd code-analytics
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install .
code-analysis doctor

From a project directory, the basic workflow is:

code-analysis scan .
code-analysis

For a named report and a dependency graphic:

code-analysis refactor . --json-compact -o refactor.json
code-analysis summary refactor.json
code-analysis export refactor.json --projection dependencies --format svg -o dependencies.svg
code-analysis ui refactor.json --source-root . --no-collection

The refactor command generates analytical evidence and proposals; it does not rewrite source. Install Graphviz separately if using the SVG command. Optional JavaScript parsing, terminal UI, and runtime capabilities have explicit extras described in the README. Run doctor and providers to see what is actually available.

Try an Investigation Before Scanning Your Own Project

The repository includes nine Fawlty Towers-inspired tutorials: beginner, intermediate, and advanced investigations for Python, JavaScript, and Ruby. Each includes a working sample application, saved source-bound evidence, an independent investigation, optional hints, and separate solutions. They are supplied in the source checkout, not as a tutorial browser bundled in the wheel.

Start with the Python reservation desk. Opening its saved report requires neither running the sample application nor rescanning its source.

Safety and Beta Feedback

Static analysis parses source without importing or executing the target application. By default it writes owned reports and caches under a self-ignored .code-analysis/ workspace; use --no-workspace or an explicitly selected alternative for read-only targets. Runtime profiling and coverage execution are separate, authorized workflows that run a supplied workload with the operator’s permissions; they are not a sandbox.

Analysis is local, but reports can still disclose source names, literals, relationships, and diagnostics. Review artifacts before sharing them. Report nonsensitive issues through GitHub, including the version, platform, interpreter/browser, command or UI task, expected result, actual diagnostics, and a minimal synthetic reproduction. Follow the repository’s security policy for sensitive reports.

The project is MIT-licensed. The beta notes, CLI reference, and changelog distinguish current capabilities from planned work.