Skip to content

Commit ee9ba63

Browse files
thrishank007thrishank007
committed
docs: add doxy v0.1 design and plan
1 parent b20eb8b commit ee9ba63

2 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎docs/superpowers/plans/2026-04-25-doxy-v0.1.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Doxy v0.1 Implementation Plan
2+
3+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4+
5+
**Goal:** Ship `doxy verify` end-to-end for React and ReactDOM with human, JSON, and JSONL output.
6+
7+
**Architecture:** Build a thin CLI over the existing repo-context, parser, adapter, and authority modules. Add a focused analyzer, config loader, file selection, reporters, and end-to-end fixture tests without implementing cache or multi-command orchestration.
8+
9+
**Tech Stack:** TypeScript, Vitest, SWC, citty, zod
10+
11+
---
12+
13+
### Task 1: Add end-to-end verify tests
14+
15+
**Files:**
16+
- Modify: `src/test/golden.ts`
17+
- Create: `src/cli/verify.test.ts`
18+
19+
- [ ] **Step 1: Write the failing verify fixture test**
20+
- [ ] **Step 2: Run the targeted test and confirm it fails for missing CLI/analyzer code**
21+
- [ ] **Step 3: Add minimal helpers for invoking verify against fixtures**
22+
- [ ] **Step 4: Re-run targeted tests and confirm failures are now behavioral**
23+
24+
### Task 2: Build the analyzer and file discovery path
25+
26+
**Files:**
27+
- Create: `src/core/analyzer/index.ts`
28+
- Create: `src/core/files/index.ts`
29+
- Modify: `src/parser/swc-bridge.ts`
30+
- Modify: `src/core/types/normalized-ast.ts`
31+
32+
- [ ] **Step 1: Write failing analyzer tests for deprecated, removed, future, and wrong-arity findings**
33+
- [ ] **Step 2: Run targeted tests and confirm they fail**
34+
- [ ] **Step 3: Implement symbol analysis and message generation**
35+
- [ ] **Step 4: Extend the parser to capture member references needed for non-call APIs**
36+
- [ ] **Step 5: Implement file selection for CLI args and config include/exclude patterns**
37+
- [ ] **Step 6: Re-run analyzer and fixture tests until green**
38+
39+
### Task 3: Add config loading, suppression application, and reporters
40+
41+
**Files:**
42+
- Create: `src/cli/config.ts`
43+
- Create: `src/cli/reporters.ts`
44+
- Create: `src/core/analyzer/messages.ts`
45+
- Modify: `src/core/suppression/index.ts`
46+
47+
- [ ] **Step 1: Write failing tests for config loading, inline suppression, config suppression, and output modes**
48+
- [ ] **Step 2: Run targeted tests and confirm they fail**
49+
- [ ] **Step 3: Implement config loading with defaults and schema validation**
50+
- [ ] **Step 4: Implement suppression application in the analyzer flow**
51+
- [ ] **Step 5: Implement human, JSON, and JSONL reporters**
52+
- [ ] **Step 6: Re-run targeted tests until green**
53+
54+
### Task 4: Wire the CLI command and public entry points
55+
56+
**Files:**
57+
- Create: `src/cli/index.ts`
58+
- Create: `src/index.ts`
59+
- Modify: `package.json`
60+
- Modify: `README.md`
61+
62+
- [ ] **Step 1: Write failing CLI tests for exit codes and output mode selection**
63+
- [ ] **Step 2: Run targeted tests and confirm they fail**
64+
- [ ] **Step 3: Implement `doxy verify [files...]` with citty**
65+
- [ ] **Step 4: Export a small programmatic API from `src/index.ts`**
66+
- [ ] **Step 5: Update README to match the actual v0.1 surface**
67+
- [ ] **Step 6: Run full test, typecheck, lint, and build**
68+
69+
### Task 5: Verify and package the release candidate
70+
71+
**Files:**
72+
- Modify: `README.md` as needed
73+
74+
- [ ] **Step 1: Run `npm test`**
75+
- [ ] **Step 2: Run `npm run typecheck`**
76+
- [ ] **Step 3: Run `npm run lint`**
77+
- [ ] **Step 4: Run `npm run build`**
78+
- [ ] **Step 5: Fix any regressions and repeat until clean**
79+
- [ ] **Step 6: Commit the v0.1 implementation**

‎docs/superpowers/specs/2026-04-25-doxy-v0.1-design.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Doxy v0.1 Design
2+
3+
## Goal
4+
5+
Ship a usable `doxy verify` command for JavaScript and TypeScript projects that use React and ReactDOM. The command must statically report deprecated APIs, removed APIs, future-version APIs, and wrong-arity calls using the repo's installed dependency versions and the bundled authority dataset.
6+
7+
## Scope
8+
9+
Included in v0.1:
10+
11+
- `doxy verify [files...]`
12+
- React and ReactDOM authority checks only
13+
- Human-readable default reporter
14+
- `--json` and `--jsonl` machine-readable reporters
15+
- Severity filtering and fail threshold handling
16+
- `doxy.config.json` loading
17+
- Include and exclude path filtering
18+
- Inline and config-based suppression support
19+
20+
Explicitly deferred:
21+
22+
- `--changed`
23+
- cache management
24+
- `doxy explain`
25+
- `doxy fix`
26+
- authority update commands
27+
- baseline files
28+
29+
## CLI UX
30+
31+
`stdout` carries findings only. In human mode it prints grouped file diagnostics and a concise summary. In `--json` mode it prints one JSON object containing findings and summary metadata. In `--jsonl` mode it prints one JSON record per finding plus a final summary record.
32+
33+
`stderr` is reserved for operational errors. Normal successful runs stay quiet on `stderr` unless a fatal project or config problem occurs.
34+
35+
Exit behavior:
36+
37+
- `0` when no findings meet `failOn`
38+
- `1` when findings meet `failOn`
39+
- `2` for config problems
40+
- `3` for project read errors
41+
- `4` for authority data errors
42+
- `5` for internal failures
43+
44+
## Architecture
45+
46+
The first release should use the existing primitives instead of introducing a full pipeline abstraction:
47+
48+
1. Load config from `doxy.config.json`, merged with defaults.
49+
2. Build `RepoContext` from manifest, lockfile, and tsconfig.
50+
3. Load bundled authority data.
51+
4. Detect active adapters.
52+
5. Resolve target source files from CLI args or configured include globs.
53+
6. Parse files with SWC.
54+
7. Resolve symbol usages through the active adapter.
55+
8. Query authority data and emit findings.
56+
9. Apply inline and config suppressions.
57+
10. Filter findings by configured minimum severity and render output.
58+
59+
## Analysis Rules
60+
61+
For each resolved symbol usage:
62+
63+
- `deprecated-api`: API exists at the installed version and has an active deprecation without removal at or before the installed version.
64+
- `removed-api`: API has a deprecation whose `removedIn` is less than or equal to the installed version.
65+
- `future-api`: API does not exist at the installed version and its minimum supported version is greater than the installed version.
66+
- `wrong-arity`: API exists and the observed call argument count falls outside the active signature range.
67+
- `unknown-export`: API is referenced from a covered package but not found in authority data. This is emitted as `info` only.
68+
69+
The parser must also record non-call member references such as `React.PropTypes` so constant or class removals are visible even when there is no function call.
70+
71+
## Output Shape
72+
73+
Human mode:
74+
75+
- group findings by file
76+
- show `line:column severity message kind id`
77+
- print one indented migration hint line when present
78+
- print final summary count with errors and warnings
79+
80+
`--json` object:
81+
82+
- `tool`
83+
- `version`
84+
- `findings`
85+
- `summary`
86+
87+
`--jsonl` records:
88+
89+
- one `finding` record per finding
90+
- one trailing `summary` record
91+
92+
## Testing
93+
94+
v0.1 is test-driven from fixture-backed integration tests:
95+
96+
- deprecated fixture
97+
- removed fixture
98+
- future API fixture
99+
- wrong-arity fixture
100+
- inline suppression fixture
101+
- config suppression fixture
102+
- clean fixture
103+
104+
Additional tests cover CLI output mode shape and exit codes.

0 commit comments

Comments
 (0)