truecourse 0.1.17 → 0.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +178 -0
- package/assets/demo.gif +0 -0
- package/assets/icon.svg +20 -0
- package/assets/logo.svg +29 -0
- package/assets/screenshot.png +0 -0
- package/assets/screenshot_analytics.png +0 -0
- package/assets/screenshot_code-review.png +0 -0
- package/assets/screenshot_diff.png +0 -0
- package/assets/screenshot_er.png +0 -0
- package/assets/screenshot_flows.png +0 -0
- package/package.json +1 -1
- package/public/assets/{index-DFA4Vhig.js → index-BM6GwBRV.js} +101 -101
- package/public/index.html +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/logo.svg" alt="TrueCourse" width="300" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<strong>AI Architecture & Code Intelligence Platform</strong>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<em>Built for humans and AI agents — web UI for developers, CLI for automation.</em>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://github.com/truecourse-ai/truecourse/actions/workflows/test.yml"><img src="https://github.com/truecourse-ai/truecourse/actions/workflows/test.yml/badge.svg" alt="Tests" /></a>
|
|
15
|
+
<a href="https://www.npmjs.com/package/truecourse"><img src="https://img.shields.io/npm/v/truecourse" alt="npm version" /></a>
|
|
16
|
+
<a href="https://github.com/truecourse-ai/truecourse/blob/main/LICENSE"><img src="https://img.shields.io/github/license/truecourse-ai/truecourse" alt="License" /></a>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
TrueCourse analyzes your codebase architecture and code to detect violations that traditional linters miss — circular dependencies, layer violations, dead modules, race conditions, security anti-patterns, and more. It combines static analysis with AI review to surface findings with fix suggestions.
|
|
20
|
+
|
|
21
|
+
Everything runs locally on your machine. Works with Claude Code (no API key needed) or your own API keys. Your code never leaves your environment.
|
|
22
|
+
|
|
23
|
+
<p align="center">
|
|
24
|
+
<img src="assets/demo.gif" alt="TrueCourse Screenshot" width="100%" />
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
## Built for Humans and AI Agents
|
|
28
|
+
|
|
29
|
+
TrueCourse is designed with two interfaces:
|
|
30
|
+
|
|
31
|
+
- **Web UI** — Interactive dependency graph, inline code viewer with violation markers, cross-service flow tracing, database ER diagrams, analytics dashboard, and diff mode. Built for developers who want to explore and understand their codebase visually.
|
|
32
|
+
- **CLI** — Analyze repos, list violations, and run diff checks from the terminal. Built for AI coding agents, CI pipelines, and automation workflows that need structured output.
|
|
33
|
+
|
|
34
|
+
Both interfaces share the same analysis engine and database — run `analyze` from an agent, review results in the UI.
|
|
35
|
+
|
|
36
|
+
## What it catches
|
|
37
|
+
|
|
38
|
+
### Architecture & Module Analysis
|
|
39
|
+
|
|
40
|
+
- **Circular dependencies** between services and modules
|
|
41
|
+
- **Layer violations** like data layer calling API layer, skipping service layer, etc.
|
|
42
|
+
- **God modules** with too many exports or responsibilities
|
|
43
|
+
- **Dead modules** that are unused and should be removed
|
|
44
|
+
- **Tight coupling** between services or modules with excessive cross-dependencies
|
|
45
|
+
- **Database issues** like missing indexes, raw SQL bypassing ORM, schema problems
|
|
46
|
+
|
|
47
|
+
### Code Intelligence
|
|
48
|
+
|
|
49
|
+
<!-- TODO: Add screenshot of code viewer with inline violations -->
|
|
50
|
+
|
|
51
|
+
TrueCourse goes beyond architecture — it reviews your actual source code for semantic issues that AST-based linters can't detect:
|
|
52
|
+
|
|
53
|
+
- **Error handling** — Catch blocks that swallow errors, rethrow without context, or return misleading success values
|
|
54
|
+
- **Race conditions** — Shared mutable state across async boundaries, check-then-act patterns
|
|
55
|
+
- **Misleading names** — Functions whose names don't match behavior (`validate` that mutates, `getUser` that deletes)
|
|
56
|
+
- **Dead code** — Unreachable code, always-true/false conditions, assigned-but-never-read variables
|
|
57
|
+
- **Security anti-patterns** — `Math.random()` for tokens, disabled TLS, `eval()` with dynamic input, unsanitized `innerHTML`
|
|
58
|
+
- **Resource leaks** — File handles, connections, or event listeners opened without cleanup
|
|
59
|
+
- **Inconsistent returns** — Functions returning different types across branches
|
|
60
|
+
|
|
61
|
+
Code violations appear inline in the code viewer with severity markers, highlighted ranges, and fix suggestions. Deterministic rules (empty catch, console.log, hardcoded secrets, magic numbers, explicit `any`, SQL injection) run via AST visitors; semantic rules run via LLM.
|
|
62
|
+
|
|
63
|
+
### Cross-Service Flow Tracing
|
|
64
|
+
|
|
65
|
+
TrueCourse automatically detects request flows across service boundaries — HTTP calls, route handlers, and internal method chains — and visualizes them as end-to-end traces. Each flow shows the chain of services, modules, and methods involved, with severity indicators when violations exist along the path.
|
|
66
|
+
|
|
67
|
+
### Database Analysis
|
|
68
|
+
|
|
69
|
+
Databases are detected automatically from ORM usage (Prisma, TypeORM, Drizzle, Knex, etc.) and displayed as nodes in the dependency graph. Click a database node to see a full ER diagram with tables, columns, types, and relationships. LLM rules check for missing foreign keys, missing indexes, naming inconsistencies, and schema issues.
|
|
70
|
+
|
|
71
|
+
### Analytics Dashboard
|
|
72
|
+
|
|
73
|
+
Track violation trends over time with charts showing how your codebase health evolves across analyses. Breakdowns by severity, category, and rule help identify recurring patterns. Code hotspots highlight files with the most violations.
|
|
74
|
+
|
|
75
|
+
### Git Diff Mode
|
|
76
|
+
|
|
77
|
+
- **New vs resolved** — See which violations your uncommitted changes introduce or fix
|
|
78
|
+
- **Affected nodes** — Graph dims unaffected nodes, highlights touched services/modules/methods
|
|
79
|
+
|
|
80
|
+
## Quick Start
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
cd /path/to/your/repo
|
|
84
|
+
npx truecourse analyze
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
On first run, the server starts automatically and the setup wizard configures your LLM provider:
|
|
88
|
+
|
|
89
|
+
- **Claude Code CLI** (Recommended) — uses your Claude Code subscription, no API key needed
|
|
90
|
+
- **Anthropic API** — requires an Anthropic API key
|
|
91
|
+
- **OpenAI API** — requires an OpenAI API key
|
|
92
|
+
|
|
93
|
+
An embedded PostgreSQL database is created automatically, no Docker or external database required.
|
|
94
|
+
|
|
95
|
+
Violations print in your terminal and the web UI opens automatically with an interactive dependency graph and violations highlighted.
|
|
96
|
+
|
|
97
|
+
## CLI Commands
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx truecourse # Runs setup + starts the server
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
or you can run them one by one:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npx truecourse setup # Configure LLM provider
|
|
107
|
+
npx truecourse start # Start the server
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Once the server is running, `cd` into any repo and:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
npx truecourse add # Register repo without analyzing
|
|
114
|
+
npx truecourse analyze # Analyze current repo, show violations
|
|
115
|
+
npx truecourse analyze --code-review # Analyze with LLM code review (off by default)
|
|
116
|
+
npx truecourse analyze --diff # Show new/resolved violations from uncommitted changes
|
|
117
|
+
npx truecourse list # Show violations from latest analysis
|
|
118
|
+
npx truecourse list --diff # Show saved diff check results
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Prerequisites
|
|
122
|
+
|
|
123
|
+
- Node.js >= 20
|
|
124
|
+
- One of:
|
|
125
|
+
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed (recommended, no API key needed)
|
|
126
|
+
- An Anthropic or OpenAI API key
|
|
127
|
+
|
|
128
|
+
No database setup, no Docker. Everything runs locally out of the box.
|
|
129
|
+
|
|
130
|
+
## Development Setup
|
|
131
|
+
|
|
132
|
+
If you want to contribute or run from source:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
git clone https://github.com/yourusername/truecourse.git
|
|
136
|
+
cd truecourse
|
|
137
|
+
pnpm install
|
|
138
|
+
|
|
139
|
+
cp .env.example .env
|
|
140
|
+
# Edit .env with your ANTHROPIC_API_KEY or OPENAI_API_KEY
|
|
141
|
+
|
|
142
|
+
pnpm dev
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Claude Code Skills
|
|
146
|
+
|
|
147
|
+
TrueCourse includes [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) that let you run analysis conversationally from within Claude Code.
|
|
148
|
+
|
|
149
|
+
When you register a repo with `npx truecourse add`, you'll be prompted to install Claude Code skills. Accepting copies the skill files to `.claude/skills/truecourse/` in your project.
|
|
150
|
+
|
|
151
|
+
### Available skills
|
|
152
|
+
|
|
153
|
+
| Skill | Triggers | What it does |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| `/truecourse-analyze` | "analyze this repo", "run a diff check" | Runs `truecourse analyze` or `analyze --diff` and summarizes results |
|
|
156
|
+
| `/truecourse-list` | "show violations", "list issues" | Runs `truecourse list` or `list --diff` to show full violation details |
|
|
157
|
+
| `/truecourse-fix` | "fix violations", "apply fixes" | Lists fixable violations, lets you pick which to fix, applies changes |
|
|
158
|
+
|
|
159
|
+
## Analysis Rules
|
|
160
|
+
|
|
161
|
+
TrueCourse ships with three types of rules:
|
|
162
|
+
|
|
163
|
+
- **Deterministic rules** — Checked programmatically via AST visitors (layer violations, circular deps, dead modules, empty catch, etc.)
|
|
164
|
+
- **LLM architecture rules** — Passed to the LLM for deeper architectural, database, and module inspection with fix suggestions
|
|
165
|
+
- **LLM code rules** — Source files sent to the LLM in batches for semantic code review (error handling, race conditions, magic numbers, security, etc.). Runs when code review is enabled (`--code-review` flag or "Analyze with code review" in the UI)
|
|
166
|
+
|
|
167
|
+
All rules are visible in the **Rules** tab in the web UI. Custom rule generation is an upcoming feature.
|
|
168
|
+
|
|
169
|
+
## Language Support
|
|
170
|
+
|
|
171
|
+
| Language | Status |
|
|
172
|
+
|---|---|
|
|
173
|
+
| JavaScript / TypeScript | Supported |
|
|
174
|
+
| Python | Upcoming |
|
|
175
|
+
|
|
176
|
+
## License
|
|
177
|
+
|
|
178
|
+
MIT
|
package/assets/demo.gif
ADDED
|
Binary file
|
package/assets/icon.svg
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
|
|
2
|
+
<!-- Background -->
|
|
3
|
+
<rect width="512" height="512" rx="80" fill="#0f172a"/>
|
|
4
|
+
|
|
5
|
+
<!-- Sail -->
|
|
6
|
+
<polygon points="256,110 256,310 170,310" fill="#3b82f6"/>
|
|
7
|
+
|
|
8
|
+
<!-- Mast -->
|
|
9
|
+
<line x1="256" y1="95" x2="256" y2="330" stroke="#e2e8f0" stroke-width="6" stroke-linecap="round"/>
|
|
10
|
+
|
|
11
|
+
<!-- Crow's nest -->
|
|
12
|
+
<rect x="238" y="95" width="36" height="20" rx="4" fill="#e2e8f0"/>
|
|
13
|
+
<line x1="256" y1="95" x2="256" y2="85" stroke="#e2e8f0" stroke-width="5" stroke-linecap="round"/>
|
|
14
|
+
|
|
15
|
+
<!-- Hull -->
|
|
16
|
+
<path d="M 140,330 L 370,330 L 345,380 L 165,380 Z" fill="#e2e8f0"/>
|
|
17
|
+
|
|
18
|
+
<!-- Hull accent -->
|
|
19
|
+
<path d="M 150,348 L 360,348 L 350,372 L 160,372 Z" fill="#3b82f6" opacity="0.35"/>
|
|
20
|
+
</svg>
|
package/assets/logo.svg
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 320" width="400" height="320">
|
|
2
|
+
<!-- Sail -->
|
|
3
|
+
<polygon points="200,30 200,190 130,190" fill="#3b82f6" opacity="0.9"/>
|
|
4
|
+
|
|
5
|
+
<!-- Mast -->
|
|
6
|
+
<line x1="200" y1="20" x2="200" y2="210" stroke="#1e3a5f" stroke-width="4" stroke-linecap="round"/>
|
|
7
|
+
|
|
8
|
+
<!-- Crow's nest -->
|
|
9
|
+
<rect x="185" y="20" width="30" height="16" rx="3" fill="#1e3a5f"/>
|
|
10
|
+
<line x1="200" y1="20" x2="200" y2="12" stroke="#1e3a5f" stroke-width="3" stroke-linecap="round"/>
|
|
11
|
+
|
|
12
|
+
<!-- Hull -->
|
|
13
|
+
<path d="M 100,210 L 300,210 L 280,250 L 120,250 Z" fill="#1e3a5f"/>
|
|
14
|
+
|
|
15
|
+
<!-- Hull accent stripe -->
|
|
16
|
+
<path d="M 108,225 L 292,225 L 284,245 L 116,245 Z" fill="#2563eb" opacity="0.4"/>
|
|
17
|
+
|
|
18
|
+
<!-- Bow detail -->
|
|
19
|
+
<path d="M 280,210 L 310,210 L 280,250 Z" fill="#163050"/>
|
|
20
|
+
|
|
21
|
+
<!-- Waves -->
|
|
22
|
+
<path d="M 60,260 Q 90,248 120,260 Q 150,272 180,260 Q 210,248 240,260 Q 270,272 300,260 Q 330,248 360,260"
|
|
23
|
+
fill="none" stroke="#3b82f6" stroke-width="3" opacity="0.6" stroke-linecap="round"/>
|
|
24
|
+
<path d="M 50,275 Q 80,263 110,275 Q 140,287 170,275 Q 200,263 230,275 Q 260,287 290,275 Q 320,263 350,275"
|
|
25
|
+
fill="none" stroke="#3b82f6" stroke-width="2.5" opacity="0.35" stroke-linecap="round"/>
|
|
26
|
+
|
|
27
|
+
<!-- TrueCourse text -->
|
|
28
|
+
<text x="200" y="310" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="28" font-weight="700" fill="#1e3a5f" letter-spacing="3">TRUECOURSE</text>
|
|
29
|
+
</svg>
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|