diff --git a/docs/docs-npm/api/adapters.mdx b/docs/docs-npm/api/adapters.mdx new file mode 100644 index 0000000..387c3b7 --- /dev/null +++ b/docs/docs-npm/api/adapters.mdx @@ -0,0 +1,64 @@ +--- +title: Adapters +description: ILanguageAdapter — pluggable analysis, transforms, and verification. +--- + +## Interface + +Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`): + +```typescript +interface ILanguageAdapter { + readonly name: string; + readonly extensions: string[]; + readonly displayName: string; + + detect(projectRoot: string): Promise; + + analyze(files: string[]): Promise; + + transform(file: string, code: string, issue: CodeIssue): Promise; + + verifySyntax(path: string, code: string): Promise; + verifyImports(path: string, code: string): Promise; + verifyTests(path: string, code: string): Promise; + + generateDiff(original: string, transformed: string): string; + + buildImportGraph(projectRoot: string): Promise; + buildCallGraph(files: string[]): Promise; +} +``` + +**Contract:** `analyze` must return issues with **blast radius** populated for every item. + +--- + +## Graphs + +- **ImportGraph** — `dependentsOf`, `dependenciesOf`, `allFiles` for blast radius fan-in. +- **CallGraph** — `transitiveCallersOf`, `allPublicFunctionsIn` for function-level impact. + +--- + +## Built-in adapters + +| Adapter | Module | Notes | +|---------|--------|------| +| Python | `PythonAdapter` | Full analyzer suite | +| TypeScript | `TypeScriptAdapter` | Graphs + verification; static analysis coverage varies by version | + +`AdapterRegistry` discovers adapters and scores them against the project. + +--- + +## Transforms + +`transform` returns `TransformResult` with `transformedCode`, human-readable `description`, and a coarse `riskLevel`. The **autofix engine** chooses fixers by issue; verification runs **after** transform. + +--- + +## See also + +- [Languages](/docs-npm/languages/python) +- [Orchestrator](/docs-npm/api/orchestrator) diff --git a/docs/docs-npm/api/models.mdx b/docs/docs-npm/api/models.mdx new file mode 100644 index 0000000..f896937 --- /dev/null +++ b/docs/docs-npm/api/models.mdx @@ -0,0 +1,110 @@ +--- +title: Models +description: Core types for issues, blast radius, verification, and analysis results. +--- + +## Severity and blast levels + +```typescript +type Severity = 'critical' | 'high' | 'medium' | 'low'; +type BlastLevel = 'trivial' | 'low' | 'medium' | 'high' | 'critical'; +``` + +--- + +## BlastRadius + +Every `CodeIssue` carries a non-optional `BlastRadius`: + +```typescript +interface BlastRadius { + affectedFiles: string[]; + affectedFunctions: string[]; + affectedTestFiles: string[]; + score: number; // 0–100 + level: BlastLevel; +} +``` + +--- + +## TemporalProfile + +Optional enrichment when Git history is available: + +```typescript +interface TemporalProfile { + lastModified: Date; + changeVelocity: number; + coChangePairs: string[]; + daysSinceLastTouch: number; +} +``` + +--- + +## CodeIssue + +```typescript +interface CodeIssue { + id: string; + file: string; + line: number; + column?: number; + severity: Severity; + type: string; + message: string; + suggestion?: string; + fixable: boolean; + fixerName?: string; + blastRadius: BlastRadius; + temporal?: TemporalProfile; + ruleId: string; +} +``` + +--- + +## VerificationResult + +```typescript +interface VerificationResult { + safeToApply: boolean; + passed: boolean; + checksRun: string[]; + checksPassed: string[]; + checksFailed: string[]; + blockingReason?: string; + confidenceScore: number; + verificationMs: number; + skippedChecks: string[]; +} +``` + +--- + +## AnalysisResult + +```typescript +interface AnalysisResult { + target: string; + filesAnalyzed: number; + filesSkipped: number; + issues: CodeIssue[]; + languageBreakdown: Record; + durationMs: number; + timestamp: Date; +} +``` + +--- + +## Pipeline / fix queue + +The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. See `src/core/models.ts` for full definitions. + +--- + +## Source + +Definitions live in `src/core/models.ts` in the repository. diff --git a/docs/docs-npm/api/orchestrator.mdx b/docs/docs-npm/api/orchestrator.mdx new file mode 100644 index 0000000..0d16e76 --- /dev/null +++ b/docs/docs-npm/api/orchestrator.mdx @@ -0,0 +1,64 @@ +--- +title: Orchestrator +description: High-level analyze and autofix pipeline. +--- + +## Class + +```typescript +class Orchestrator { + constructor( + adapter: ILanguageAdapter, + config: RefactronConfig, + projectRoot: string, + ); + + analyze(target: string): Promise; + + autofix( + target: string, + options?: { dryRun?: boolean; verify?: boolean }, + ): Promise<{ session: PipelineSession; analysis: AnalysisResult }>; + + autofixFromAnalysis( + analysis: AnalysisResult, + options?: { dryRun?: boolean; verify?: boolean }, + ): Promise; +} +``` + +`OrchestratorResult` bundles a `PipelineSession` with the `AnalysisResult` from **`analyze`**. + +--- + +## analyze + +Runs the **AnalysisEngine** on the target path, records issue counts on an internal pipeline session, persists via **SessionStore**, and returns both session summary and full **AnalysisResult**. + +--- + +## autofix + +1. Calls **`analyze`** on the same target. +2. Enqueues fixable issues, runs **AutoFixEngine** transforms. +3. If verification is required (CLI flag or `config.autofix.require_verification`), runs **VerificationEngine** before each write. +4. On success, **BackupManager** + **atomicWrite** persist changes. + +--- + +## autofixFromAnalysis + +Skips a new scan — used by the REPL **`autofix`** command when reconstructing analysis from a **WorkSession** so fixes apply to the stored issue list without re-running analyzers. + +--- + +## Source + +`src/core/orchestrator.ts` + +--- + +## See also + +- [Models](/docs-npm/api/models) +- [Verification](/docs-npm/concepts/verification) diff --git a/docs/docs-npm/api/overview.mdx b/docs/docs-npm/api/overview.mdx new file mode 100644 index 0000000..0e68f4f --- /dev/null +++ b/docs/docs-npm/api/overview.mdx @@ -0,0 +1,33 @@ +--- +title: API overview +description: Programmatic building blocks in the Refactron TypeScript codebase. +--- + +## Package layout + +The published **npm** package is primarily the **`refactron`** CLI (`dist/cli/index.js`). The same build outputs library modules under `dist/` (for example `dist/core/models.js`, `dist/core/orchestrator.js`). + +If you embed Refactron programmatically, import from the compiled paths your bundler resolves (check `package.json` **exports** for supported entry points in your version). + +--- + +## Core layers + +| Layer | Role | +|-------|------| +| **Models** | `CodeIssue`, `BlastRadius`, `VerificationResult`, `AnalysisResult`, pipeline types — see [Models](/docs-npm/api/models) | +| **Orchestrator** | Wires analysis → autofix → verification → backup → atomic write — see [Orchestrator](/docs-npm/api/orchestrator) | +| **Adapters** | `ILanguageAdapter` for language-specific analyze/transform/verify — see [Adapters](/docs-npm/api/adapters) | +| **Session (CLI)** | `WorkSessionManager` persists REPL sessions under `.refactron/work-sessions/` | + +--- + +## Stability + +Types under `src/core/models.ts` and `src/adapters/interface.ts` are marked **LOCKED** in-repo: treat them as semver-sensitive when depending on them from outside the project. + +--- + +## See also + +- [Core concepts](/docs-npm/concepts/blast-radius) — Blast radius and verification behavior diff --git a/docs/docs-npm/cli/analyze.mdx b/docs/docs-npm/cli/analyze.mdx new file mode 100644 index 0000000..ac59ac2 --- /dev/null +++ b/docs/docs-npm/cli/analyze.mdx @@ -0,0 +1,48 @@ +--- +title: analyze +description: Scan a path, create a work session, and open the issue browser. +--- + +## Usage + +At the REPL prompt: + +``` +analyze [target] +``` + +- **`target`** — Directory or path to scan. Defaults to `.` if omitted (parsed as the second token; see below). + +Examples: + +``` +❯ analyze . +❯ analyze src/ +``` + +--- + +## Behavior + +1. Resolves `target` to an absolute path. +2. Runs the analysis engine (analyzers, import/call graphs, blast radius, optional temporal data). +3. Creates a new **work session** with a unique id and stores it under `.refactron/work-sessions/`. +4. Sets this session as **active**. +5. Prints a severity-grouped summary to the REPL. +6. Opens the **interactive issue browser** automatically. + +If you need the browser again later, run **`issues`** (requires an active session). + +--- + +## Prerequisites + +- Authenticated session (unless your deployment waives auth). +- Supported language detected for the project. See [Languages](/docs-npm/languages/python). + +--- + +## See also + +- [Work sessions](/docs-npm/concepts/sessions) +- [Issue browser](/docs-npm/cli/issue-browser) diff --git a/docs/docs-npm/cli/autofix.mdx b/docs/docs-npm/cli/autofix.mdx new file mode 100644 index 0000000..f408ccf --- /dev/null +++ b/docs/docs-npm/cli/autofix.mdx @@ -0,0 +1,49 @@ +--- +title: autofix +description: Apply fixes for all fixable issues in the active session. +--- + +## Usage + +``` +autofix [--dry-run] [--verify] +``` + +There is **no path argument** in the REPL: autofix always uses the **active** session’s stored issues (from the last `analyze`). + +| Flag | Meaning | +|------|---------| +| `--dry-run` | Compute transforms and queue results **without** writing files | +| `--verify` | Run the verification engine before each write (in addition to config `autofix.require_verification`) | + +--- + +## Behavior + +1. Loads fixable issues from the active session. +2. Reconstructs the analysis result and runs the **orchestrator** autofix pipeline (fixers → verification gate → atomic writes → backups when not dry-run). +3. Updates the session with applied vs blocked fixes and timestamps. + +--- + +## Output + +You will see counts for **Applied** and **Blocked**, plus any block reasons (for example verification failure). Session **phase** moves to `fixed` when updates succeed. + +--- + +## Configuration + +Global behavior is controlled in `refactron.yaml`: + +- `autofix.dry_run` — Default dry-run for automation (REPL flag overrides per run when passed). +- `autofix.require_verification` — If true, fixes that fail verification are not written. + +See [Configuration](/docs-npm/configuration). + +--- + +## See also + +- [Verification](/docs-npm/cli/verify) +- [Verification engine](/docs-npm/concepts/verification) diff --git a/docs/docs-npm/cli/issue-browser.mdx b/docs/docs-npm/cli/issue-browser.mdx new file mode 100644 index 0000000..e4de58c --- /dev/null +++ b/docs/docs-npm/cli/issue-browser.mdx @@ -0,0 +1,55 @@ +--- +title: Issue browser +description: Keyboard-driven TUI to navigate issues, preview diffs, fix, and verify. +--- + +## Opening the browser + +The browser opens automatically after a successful **`analyze`**. You can reopen it anytime with: + +``` +issues +``` + +Requires an **active** session (from the latest `analyze` or from **`session`** …). If there is no session, the CLI tells you to run `analyze` first. + +--- + +## Layout + +- **Header** — Session id, issue counts, fixable count. +- **List** — One row per issue: index, severity, message, file:line, fix status markers. +- **Detail** — Selected issue message, suggestion, file path, blast level, fixable flag. + +--- + +## Keys + +| Key | Action | +|-----|--------| +| `↑` / `↓` or `j` / `k` | Move selection | +| `d` | Preview diff (dry-run; no write) | +| `Esc` | Dismiss diff overlay | +| `a` | Fix selected issue | +| `A` | Fix all fixable issues | +| `v` | Verify fixed files | +| `/` | Filter issues | +| `g` / `G` | Jump to first / last issue | +| `q` | Quit browser, return to REPL | + +Markers in the list can include fixable (`·`), fixed (`✔`), verified (`✓`), or blocked (`✘`) depending on implementation version. + +--- + +## Tips + +- Use **`d`** before **`a`** to confirm the transform on critical paths. +- After bulk **`A`**, run **`v`** to run verification for fixed files. +- Quitting with **`q`** does not delete the session; use **`session list`** to resume later. + +--- + +## See also + +- [Quickstart](/docs-npm/quickstart) — First-run walkthrough +- [Blast radius](/docs-npm/concepts/blast-radius) diff --git a/docs/docs-npm/cli/other-commands.mdx b/docs/docs-npm/cli/other-commands.mdx new file mode 100644 index 0000000..6d36b20 --- /dev/null +++ b/docs/docs-npm/cli/other-commands.mdx @@ -0,0 +1,83 @@ +--- +title: Other commands +description: Auth, status, diff, rollback, and REPL housekeeping. +--- + +## Authentication + +### `login` + +Starts the OAuth device flow (optional `--no-browser` style flags may apply). On success, stores credentials under `~/.refactron/credentials.json`. + +### `logout` + +Deletes stored credentials and exits the CLI. + +### `auth` + +Prints whether you are logged in, plan, and token expiry when available. + +--- + +## status + +``` +status +``` + +Shows a **session card** for the **active** session. If none is active, shows the **latest saved** session when one exists; otherwise prompts you to run `analyze`. + +--- + +## diff + +``` +diff +``` + +Prints unified diffs for fixes recorded in the active session’s **`autofix`** results. If no fix data is present, run **`autofix`** first. + +--- + +## rollback + +``` +rollback +``` + +The REPL prints guidance about backups and autofix. **Per-file backups** are created under `.refactron/backups/` when fixes are written; use your version’s behavior for full restore. If restore is not yet wired to this command in your build, recover files manually from the backup directory or re-run from Git. + +--- + +## issues + +Opens the [issue browser](/docs-npm/cli/issue-browser). Requires an active session. + +--- + +## help + +``` +help +``` + +or `?` — Lists REPL commands (analyze, issues, autofix, verify, status, session, rollback, diff, login, logout, auth, clear, exit). + +--- + +## clear + +Clears the REPL output buffer (terminal escape). + +--- + +## exit / quit / q + +Exits the CLI. + +--- + +## See also + +- [CLI overview](/docs-npm/cli/overview) +- [Quickstart](/docs-npm/quickstart) — Auth flow summary diff --git a/docs/docs-npm/cli/overview.mdx b/docs/docs-npm/cli/overview.mdx new file mode 100644 index 0000000..6b139ca --- /dev/null +++ b/docs/docs-npm/cli/overview.mdx @@ -0,0 +1,50 @@ +--- +title: CLI overview +description: How the Refactron command-line interface is structured and how to get help. +--- + +## Entry points + +Running **`refactron`** with no arguments (after authentication, when required) starts the **interactive REPL**: a terminal UI where you type commands at the `❯` prompt. + +Fast paths that exit immediately: + +```bash +refactron --version # or -v +refactron --help # or -h — prints a short command summary +``` + +The REPL is the primary way to run **analyze**, **autofix**, **verify**, **session**, and related workflows. Command names match the help text; you can also prefix commands with `/` (for example `/analyze`). + +--- + +## Authentication + +Most commands require a valid login. Exceptions include `login`, `logout`, `auth`, `help`, `clear`, `exit`, `quit`, `session`, and `issues` (though `issues` still needs an active session from a prior `analyze`). + +See [Other commands](/docs-npm/cli/other-commands) for `login`, `logout`, and `auth`. + +--- + +## Project detection + +On startup, Refactron picks a **language adapter** by scanning the project root for matching source files (Python `*.py` vs TypeScript `*.ts` / `*.tsx`), ignoring `node_modules`, `.git`, and `dist`. Ensure the intended language has the most matching files, or run from the correct subdirectory. + +--- + +## Configuration + +Project settings are loaded from `refactron.yaml` in the **current working directory** when the CLI starts. See [Configuration](/docs-npm/configuration). + +--- + +## Command map + +| Topic | Page | +|-------|------| +| Scan and sessions | [analyze](/docs-npm/cli/analyze) | +| Interactive TUI | [Issue browser](/docs-npm/cli/issue-browser) | +| Apply fixes | [autofix](/docs-npm/cli/autofix) | +| Post-fix checks | [verify](/docs-npm/cli/verify) | +| Saved sessions | [session](/docs-npm/cli/session) | +| Auth, status, diff, rollback | [Other commands](/docs-npm/cli/other-commands) | diff --git a/docs/docs-npm/cli/session.mdx b/docs/docs-npm/cli/session.mdx new file mode 100644 index 0000000..4f065d9 --- /dev/null +++ b/docs/docs-npm/cli/session.mdx @@ -0,0 +1,41 @@ +--- +title: session +description: List, load, and resume persisted work sessions. +--- + +## Usage + +``` +session list +session a1b2c3 +``` + +- **`session list`** — Prints all saved sessions (newest first), with id, phase, issue count, target path, and timestamp. Marks the active session when applicable. +- **`session`** with a session id — Loads the matching JSON file under `.refactron/work-sessions/`, sets it as the **active** session, and prints a summary card. + +Using `session` with target `.` behaves like **`session list`** in the current implementation. + +--- + +## Storage + +Sessions live at: + +``` +.refactron/work-sessions/{session-id}.json +``` + +See [Work sessions](/docs-npm/concepts/sessions) for fields and lifecycle. + +--- + +## When to use + +- After restarting the CLI — reload a session instead of re-running a long `analyze`. +- To compare two analysis runs — keep multiple session files and switch with `session`. + +--- + +## See also + +- [status](/docs-npm/cli/other-commands#status) — Quick view of active or latest session diff --git a/docs/docs-npm/cli/verify.mdx b/docs/docs-npm/cli/verify.mdx new file mode 100644 index 0000000..784aa8d --- /dev/null +++ b/docs/docs-npm/cli/verify.mdx @@ -0,0 +1,39 @@ +--- +title: verify +description: Run verification checks on files from the active session. +--- + +## Usage + +``` +verify [file] +``` + +- With **`file`** — Restricts to fixable issues in that file (resolved path). +- With **`.`** or no file-specific target — Considers fixable issues across the active session (per unique file). + +Requires an **active** session. + +--- + +## What gets checked + +The verification engine runs checks based on **blast radius** (see [Verification engine](/docs-npm/concepts/verification)): + +- Syntax +- Import resolution (at medium+ blast) +- Test gate (at high / critical blast) + +Each file is verified using the **maximum** blast radius among its fixable issues. + +--- + +## Output + +For each file you will see **pass** with a confidence percentage, or **fail** with a blocking reason. The session is updated with aggregate passed/blocked counts and per-file entries. + +--- + +## See also + +- [Configuration](/docs-npm/configuration) — `verification.timeout_seconds` and `critical_timeout_seconds` diff --git a/docs/docs-npm/concepts/blast-radius.mdx b/docs/docs-npm/concepts/blast-radius.mdx new file mode 100644 index 0000000..9af5150 --- /dev/null +++ b/docs/docs-npm/concepts/blast-radius.mdx @@ -0,0 +1,121 @@ +--- +title: Blast Radius +description: How Refactron measures the impact of every code change before it happens. +--- + +## What is Blast Radius? + +Blast Radius is Refactron's core safety mechanism. Every `CodeIssue` carries a mandatory `BlastRadius` object — it is never optional, never null. Before any fix is applied, Refactron knows exactly how many files, functions, and test files could be affected by that change. + +```typescript +interface BlastRadius { + affectedFiles: string[]; // files that transitively import the changed file + affectedFunctions: string[]; // functions in the call graph that reference the changed code + affectedTestFiles: string[]; // test files that cover the changed code + score: number; // 0–100 weighted impact score + level: BlastLevel; // trivial | low | medium | high | critical +} +``` + +--- + +## The Score (0–100) + +The score is a weighted sum of three factors: + +| Factor | Weight | What it measures | +|--------|--------|-----------------| +| Affected files | 40% | How many files transitively import the changed file | +| Affected functions | 40% | How many functions in the call graph reference the changed code | +| Test coverage gap | 20% | Penalty when affected code has no test coverage | + +``` +score = (normalised_files × 0.4) + (normalised_functions × 0.4) + (coverage_gap × 0.2) +``` + +--- + +## Blast Levels + +| Level | Score | Verification | +|-------|-------|-------------| +| `trivial` | 0–10 | Syntax check only | +| `low` | 11–25 | Syntax check only | +| `medium` | 26–50 | Syntax + import resolution | +| `high` | 51–75 | Syntax + imports + test gate | +| `critical` | 76–100 | Full: syntax + imports + test suite (120s timeout) | + + +A `critical` blast radius fix will run your **entire test suite** before writing anything to disk. If any test fails, the fix is blocked. + + +--- + +## How It Is Computed + +### 1. Import Graph Traversal + +Refactron builds a full transitive import graph of your project. For each file, it walks all direct and indirect importers: + +``` +changed: src/auth/token.ts + imported by: src/auth/index.ts + imported by: src/api/middleware.ts + imported by: src/api/routes.ts + imported by: src/server.ts + +affectedFiles = [index.ts, middleware.ts, routes.ts, server.ts] → high score +``` + +A utility function with no importers scores near zero. A core module imported by half the codebase scores near 100. + +### 2. Call Graph Analysis + +Beyond file-level imports, Refactron traces function-level call relationships. If you change `parseToken()`, every function that directly or indirectly calls it is counted as affected. + +### 3. Test Coverage Gap + +If the changed code has no test files covering it, a 20% penalty is applied. If tests exist, the penalty is zero. + +--- + +## Reading Blast Radius in the Browser + +In the interactive issue browser, blast radius is shown in the detail panel: + +``` +File: src/auth/token.ts:47 blast:high [fixable] +``` + +And in the issue list, each row shows the blast mark: + +| Mark | Meaning | +|------|---------| +| `·` | Fixable, not yet fixed | +| `✔` | Fixed | +| `✓` | Fixed and verified safe | +| `✘` | Verified but blocked | + +--- + +## Why This Matters + +### Traditional approach (no blast radius) + +```bash +eslint --fix src/ # fixes everything, no idea what broke +``` + +### Refactron approach + +``` +Issue: Remove unused import 'os' +Blast: trivial (score: 2) — 0 files affected +→ Syntax check only, instant fix ✔ + +Issue: Refactor authenticate() +Blast: critical (score: 89) — 34 files affected, 0 test coverage +→ Full test suite runs before any write. Tests fail → fix blocked ✘ +``` + +Blast radius turns "I hope this doesn't break anything" into a quantified, verifiable guarantee. diff --git a/docs/docs-npm/concepts/sessions.mdx b/docs/docs-npm/concepts/sessions.mdx new file mode 100644 index 0000000..15e2a0e --- /dev/null +++ b/docs/docs-npm/concepts/sessions.mdx @@ -0,0 +1,65 @@ +--- +title: Work Sessions +description: How Refactron persists analyze → autofix → verify context across REPL commands. +--- + +## What is a session? + +Every successful `analyze` run creates a **work session**: a snapshot of the analysis (full issue list, blast radius, metadata) stored on disk so you can **autofix**, **verify**, and **diff** without rescanning the tree. + +Sessions are identified by a short hex id (for example `a1b2c3`) and progress through phases: + +| Phase | Meaning | +|-------|---------| +| `analyzed` | Scan finished; issues are available for the issue browser and `autofix` | +| `fixing` | Reserved for in-progress fix passes | +| `fixed` | `autofix` completed (applied and blocked counts recorded) | +| `verified` | `verify` completed (per-file confidence and checks recorded) | + +--- + +## Where sessions live + +Sessions are stored as JSON under your project: + +``` +.refactron/work-sessions/{session-id}.json +``` + +The active session in memory is whichever run of **`analyze`** or **`session`** (with a session id) last activated a session. Commands such as `autofix`, `verify`, `diff`, and `issues` use the **active** session. + +--- + +## Typical workflow + +1. **`analyze src/`** — Creates a new session, sets it active, opens the interactive issue browser. +2. **Fix in the browser** or run **`autofix`** — Updates the same session with fix results (applied vs blocked). +3. **`verify`** — Runs verification for fixable files and updates the session with pass/block counts. +4. **`session list`** — Lists saved sessions on disk (newest first). +5. **`session` + session id** — Loads a previous session and makes it active so you can continue without a new scan (example: `session a1b2c3`). + +--- + +## What is stored + +Each session file includes: + +- **Analysis** — Target path, file counts, full `CodeIssue[]` list (including blast radius), timestamps. +- **Fix** (after `autofix`) — Dry-run flag, applied vs blocked fix queue items, optional diffs. +- **Verify** (after `verify`) — Per-file entries with `safe`, confidence, checks run, and blocking reasons. + +This design keeps the REPL responsive: heavy analysis runs once; later steps reuse the stored issues. + +--- + +## Related commands + +| Command | Role | +|---------|------| +| `status` | Shows the active session (or the latest saved session if none is active) | +| `issues` | Reopens the issue browser for the active session | +| `diff` | Prints unified diffs from the last `autofix` results in the active session | + + +If you restart the CLI, run `session list` and then `session` with the desired id to resume work without re-running `analyze`. + diff --git a/docs/docs-npm/concepts/temporal-analysis.mdx b/docs/docs-npm/concepts/temporal-analysis.mdx new file mode 100644 index 0000000..3b28d9a --- /dev/null +++ b/docs/docs-npm/concepts/temporal-analysis.mdx @@ -0,0 +1,47 @@ +--- +title: Temporal Analysis +description: Git history signals that complement blast radius for change risk. +--- + +## Overview + +**Temporal analysis** enriches each issue with an optional `TemporalProfile` when Refactron runs inside a **Git** repository. It does not replace blast radius; it adds **time-based** context: how often a file changes, when it was last touched, and which other files tend to change together. + +If the project is not a Git repo or a file has no recent history, the profile is omitted and analysis continues normally. + +--- + +## TemporalProfile + +```typescript +interface TemporalProfile { + lastModified: Date; + changeVelocity: number; // approximate commits per month (6-month window) + coChangePairs: string[]; // paths that often change in the same commits + daysSinceLastTouch: number; +} +``` + +Data is derived from `git log` over a **six-month** window for the file’s path. + +--- + +## Combined risk score + +The `TemporalAnalyzer` can combine blast radius score with temporal fields to produce a coarse label: `DANGER` | `HIGH` | `MEDIUM` | `LOW`. For example, **very high blast**, **stale code** (not touched in a long time), and **low change velocity** can surface as **DANGER** — a signal that a change may have hidden coupling even when tests pass. + +Use this as a **prioritization hint** alongside blast radius and verification results, not as a second gate for writes. + +--- + +## Requirements + +- **Git** available and the working tree under a repository root (`process.cwd()`). +- Enough history for meaningful stats; new or rarely committed files may get sparse profiles. + +--- + +## See also + +- [Blast radius](/docs-npm/concepts/blast-radius) — structural impact (imports, calls, tests). +- [Verification](/docs-npm/concepts/verification) — what must pass before a fix is written. diff --git a/docs/docs-npm/concepts/verification.mdx b/docs/docs-npm/concepts/verification.mdx new file mode 100644 index 0000000..a593d12 --- /dev/null +++ b/docs/docs-npm/concepts/verification.mdx @@ -0,0 +1,163 @@ +--- +title: Verification Engine +description: How Refactron proves a fix is safe before writing it to disk. +--- + +## Overview + +The Verification Engine is the safety gate between an auto-fix transform and a disk write. It runs a set of checks proportional to the blast radius of the change. A trivial fix in an isolated file only needs a syntax check. A change to a widely-imported core module runs the full test suite. + +**Nothing is written to disk until verification passes.** + +--- + +## Verification Result + +```typescript +interface VerificationResult { + safeToApply: boolean; // true only if all required checks passed + passed: boolean; + checksRun: string[]; // which checks were executed + checksPassed: string[]; + checksFailed: string[]; + blockingReason?: string; // human-readable reason if blocked + confidenceScore: number; // 0.0–1.0 + verificationMs: number; // how long verification took + skippedChecks: string[]; // checks skipped due to blast level +} +``` + +--- + +## The Three Checks + +### 1. Syntax Check + +Parses the transformed code to confirm it is syntactically valid. + +- **Python:** calls `ast.parse()` on the transformed source +- **TypeScript:** runs the TypeScript compiler API in check-only mode + +A syntax error means the transform produced broken code. The fix is immediately blocked. + +### 2. Import Resolution Check + +Verifies that all imports in the transformed file can still be resolved. + +- **Python:** runs `py_compile` to catch broken import paths +- **TypeScript:** checks that all `import` statements resolve to real modules + +This catches fixes that accidentally removed a needed import or renamed an exported symbol. + +### 3. Test Gate Check + +Runs the test suite for the project and checks that all tests pass. + +- **Python:** runs `pytest` with a 45s timeout (120s for critical blast) +- **TypeScript:** runs `vitest` or `jest` (auto-detected) + +This is the most expensive check and only runs for `high` and `critical` blast radius issues. + +--- + +## Check Selection by Blast Level + +| Blast Level | Syntax | Imports | Test Suite | +|-------------|--------|---------|------------| +| `trivial` | ✓ | — | — | +| `low` | ✓ | — | — | +| `medium` | ✓ | ✓ | — | +| `high` | ✓ | ✓ | ✓ | +| `critical` | ✓ | ✓ | ✓ (120s) | + +--- + +## Confidence Score + +The confidence score (`0.0–1.0`) reflects how many required checks passed: + +``` +score = checks_passed / checks_run +``` + +A score of `1.0` means every required check passed. A score below `1.0` with `safeToApply: false` means at least one check failed. + +In the issue browser, confidence is shown after verifying: + +``` +✔ Safe to apply (confidence: 100%) +✘ Blocked — 3 tests failed (83%) +``` + +--- + +## Timeouts + +| Check | Standard timeout | Critical blast timeout | +|-------|-----------------|----------------------| +| Syntax | instant | instant | +| Imports | 45s | 45s | +| Test gate | 45s | **120s** | + +Adjust in `refactron.yaml`: + +```yaml +verification: + timeout_seconds: 45 + critical_timeout_seconds: 120 +``` + +--- + +## Atomic Writes + +When verification passes, Refactron writes the transformed file using a **temp-file-then-rename** strategy: + +``` +1. Write transformed code to src/auth/token.ts.refactron-tmp +2. Verify the tmp file is safe +3. Rename tmp → src/auth/token.ts (atomic on POSIX, best-effort on Windows) +``` + +If the process crashes between steps 2 and 3, the original file is untouched. The `.refactron-tmp` file is cleaned up on next run. + +--- + +## Backup Before Every Write + +Before any atomic write, a backup is made: + +``` +.refactron/ + backups/ + {session-id}/ + src/auth/token.ts.bak + src/api/routes.ts.bak +``` + +Run `rollback` at any time to restore all files from the session backup. + +``` +❯ rollback +``` + +--- + +## Disabling Verification + + +Disabling verification removes the safety guarantee. Only use this in trusted local workflows. + + +```yaml +# refactron.yaml +autofix: + require_verification: false +``` + +Or use dry-run mode to see what would change without writing anything: + +```yaml +autofix: + dry_run: true +``` diff --git a/docs/docs-npm/configuration.mdx b/docs/docs-npm/configuration.mdx new file mode 100644 index 0000000..1043a45 --- /dev/null +++ b/docs/docs-npm/configuration.mdx @@ -0,0 +1,257 @@ +--- +title: Configuration +description: Customize Refactron with a refactron.yaml file in your project root. +--- + +## Config File + +Create `refactron.yaml` in your project root. All fields are optional — Refactron ships with sensible defaults and deep-merges your overrides. + +```yaml +# refactron.yaml +version: 1 + +analyzers: + complexity: + enabled: true + threshold: 10 # cyclomatic complexity limit + + security: + enabled: true + + code_smell: + enabled: true + max_method_lines: 50 # lines per function/method limit + + dead_code: + enabled: true + + type_hints: + enabled: true + + dependencies: + enabled: true + + performance: + enabled: true + +verification: + timeout_seconds: 45 # standard check timeout + critical_timeout_seconds: 120 # timeout for critical blast radius checks + +autofix: + dry_run: false # set true to never write files + require_verification: true # block fixes that fail verification + +output: + format: terminal # terminal | json | sarif + fail_on: null # critical | high | medium | low | null +``` + +--- + +## Full Reference + +### `analyzers` + +Each analyzer can be individually enabled or disabled. + + + + Detects functions with cyclomatic complexity above the threshold. + + ```yaml + analyzers: + complexity: + enabled: true + threshold: 10 # default: 10, lower = stricter + ``` + + **What it catches:** deeply nested conditionals, long switch statements, functions with many branches. + + + + Detects common security vulnerabilities. + + ```yaml + analyzers: + security: + enabled: true + ``` + + **What it catches:** + - SQL injection via string formatting (`f"SELECT * FROM {table}"`) + - `eval()` calls + - Hardcoded secrets (passwords, API keys, tokens in source) + - `exec()` with dynamic input + + + + Detects overly long functions/methods. + + ```yaml + analyzers: + code_smell: + enabled: true + max_method_lines: 50 # default: 50 + ``` + + **What it catches:** functions exceeding `max_method_lines` lines (excluding comments and blank lines). + + + + Detects unreachable code after control flow statements. + + ```yaml + analyzers: + dead_code: + enabled: true + ``` + + **What it catches:** code after `return`, `raise`, `break`, `continue` that can never execute. + + + + Detects missing type annotations. + + ```yaml + analyzers: + type_hints: + enabled: true + ``` + + **What it catches (Python):** functions missing return type annotations. + **What it catches (TypeScript):** explicit `any` usage. + + + + Detects unused imports. + + ```yaml + analyzers: + dependencies: + enabled: true + ``` + + **What it catches:** imported names that are never referenced in the file body. + + + + Detects common performance anti-patterns. + + ```yaml + analyzers: + performance: + enabled: true + ``` + + **What it catches:** + - List concatenation inside loops (`result = result + [item]`) + - `await` calls inside loops (should be `Promise.all` or batched) + + + +--- + +### `verification` + +Controls timeouts for the verification engine. + +```yaml +verification: + timeout_seconds: 45 # syntax + imports checks + critical_timeout_seconds: 120 # full test suite for critical blast radius +``` + + +Critical blast radius issues run the full test suite. Increase `critical_timeout_seconds` for large test suites. + + +--- + +### `autofix` + +```yaml +autofix: + dry_run: false # true: never write files, only show diffs + require_verification: true # true: block any fix that fails verification +``` + +Setting `dry_run: true` is useful in CI pipelines where you want to report fixable issues without applying them. + +--- + +### `output` + +```yaml +output: + format: terminal # terminal | json | sarif + fail_on: null # null | critical | high | medium | low +``` + +**`fail_on`** — exit with code 1 if any issue at or above this severity is found. Useful for CI gates: + +```yaml +output: + fail_on: high # CI fails if any HIGH or CRITICAL issues exist +``` + +--- + +## Example Configurations + +### Strict Security CI Gate + +```yaml +version: 1 +analyzers: + security: + enabled: true + complexity: + enabled: true + threshold: 8 + type_hints: + enabled: true +output: + fail_on: high +autofix: + dry_run: true +``` + +### Relaxed Local Development + +```yaml +version: 1 +analyzers: + complexity: + threshold: 15 + code_smell: + max_method_lines: 100 + type_hints: + enabled: false +autofix: + require_verification: false +``` + +### Minimal (security only) + +```yaml +version: 1 +analyzers: + complexity: + enabled: false + code_smell: + enabled: false + dead_code: + enabled: false + type_hints: + enabled: false + dependencies: + enabled: false + performance: + enabled: false + security: + enabled: true +output: + fail_on: critical +``` diff --git a/docs/docs-npm/introduction.mdx b/docs/docs-npm/introduction.mdx new file mode 100644 index 0000000..132eae1 --- /dev/null +++ b/docs/docs-npm/introduction.mdx @@ -0,0 +1,125 @@ +--- +title: Introduction +description: Safety-first refactoring — finds, fixes, and verifies changes are safe before touching the filesystem. +--- + +Refactron Hero + +## What is Refactron? + +Refactron is a TypeScript CLI that analyzes your codebase for issues, automatically fixes what it can, and **verifies every change is safe before writing a single byte to disk**. + +It is built around one core idea: **every code change has a blast radius**. A one-liner fix in an isolated utility is low-risk. A change to a function imported by 40 files that has no tests is extremely high-risk. Refactron measures this mathematically and scales its verification strictness accordingly. + +```bash +npm install -g refactron +cd your-project +refactron +``` + +--- + +## The Problem Refactron Solves + +Most refactoring tools answer "what should I fix?" but leave you to figure out "is it safe to fix?". Refactron answers both. + +| Tool Category | Finds Issues | Auto-fixes | Verifies Safety | Blast Radius | +|---|---|---|---|---| +| Linters (ESLint, Pylint) | ✓ | Partial | ✗ | ✗ | +| Formatters (Prettier, Black) | ✓ | ✓ | ✗ | ✗ | +| **Refactron** | ✓ | ✓ | **✓** | **✓** | + +--- + +## Core Differentiators + + + + Every issue carries a mandatory 0–100 impact score computed from transitive import and call graphs. You always know how dangerous a change is before making it. + + + Changes are verified (syntax, imports, test suite) before being written to disk. Strictness scales automatically with blast radius. + + + All file writes use a temp-file-then-rename strategy. Partial writes and corrupted files are impossible. + + + Every session is backed up automatically. Run `rollback` to restore the previous state at any time. + + + After analysis, an interactive TUI opens automatically. Navigate issues, preview diffs, fix and verify — all without leaving the terminal. + + + Every `analyze` run creates a persistent session. Fix and verify against it later — no re-scanning needed. + + + +--- + +## How It Works + +``` +analyze src/ (at REPL prompt) + │ + ▼ + Analysis Engine + ┌─────────────────────────────────┐ + │ 7 analyzers run in parallel │ + │ Import graph + call graph built│ + │ Blast radius scored per issue │ + │ Temporal profile from git log │ + └─────────────────────────────────┘ + │ + ▼ + Issue Browser (interactive TUI) + ┌─────────────────────────────────┐ + │ Navigate issues ↑↓ / j k │ + │ Preview diff d │ + │ Fix in place a │ + │ Fix all A │ + │ Verify fix v │ + └─────────────────────────────────┘ + │ + ▼ + Verification Engine + ┌─────────────────────────────────┐ + │ Blast trivial → syntax only │ + │ Blast medium → syntax+imports │ + │ Blast critical→ full test suite│ + └─────────────────────────────────┘ + │ + ▼ + Atomic write to disk (or blocked) +``` + +--- + +## Quick Example + +```bash +# Install +npm install -g refactron + +# Start Refactron, then at the ❯ prompt (same commands as below): +refactron + +# Analyze your project — issue browser opens automatically +analyze src/ + +# In the browser: +# j/k navigate issues +# d preview diff +# a fix selected issue +# A fix all fixable issues +# v verify a fixed issue +# q quit + +# From the REPL: +autofix --verify # fix + verify in one pass (uses active session) +status # see active session +rollback # backup / restore guidance (see docs) +``` diff --git a/docs/docs-npm/languages/python.mdx b/docs/docs-npm/languages/python.mdx new file mode 100644 index 0000000..22989e6 --- /dev/null +++ b/docs/docs-npm/languages/python.mdx @@ -0,0 +1,41 @@ +--- +title: Python +description: Python adapter — analyzers, transforms, and verification. +--- + +## Detection + +The Python adapter is selected when Python 3 is available (`python3 --version` succeeds) and your project contains `.py` files (among supported adapters, the one with the most matching files wins). + +--- + +## Analysis + +Python analysis walks source files and runs the shared analyzer suite: security, complexity, code smell, dead code, type hints, dependencies, and performance. Each issue includes a populated **blast radius** from import and call graphs. + +--- + +## Auto-fixes + +Transforms are applied in-memory and then gated by the **verification engine** before write. Python-specific fixers include unused imports, dead code, type hints, f-string safety, trailing whitespace, import sorting, and others registered in the autofix engine. + +--- + +## Verification + +- **Syntax** — `ast.parse` via a Python subprocess. +- **Imports** — Exercises that catch broken imports after a transform. +- **Tests** — `pytest` for the file or project (see adapter and test-runner implementation for timeouts). + +--- + +## Requirements + +- **Python 3.8+** on `PATH` as `python3`. +- For tests: `pytest` in the environment when the test gate runs. + +--- + +## See also + +- [Configuration](/docs-npm/configuration) — Analyzer toggles and thresholds diff --git a/docs/docs-npm/languages/typescript.mdx b/docs/docs-npm/languages/typescript.mdx new file mode 100644 index 0000000..aef2e99 --- /dev/null +++ b/docs/docs-npm/languages/typescript.mdx @@ -0,0 +1,43 @@ +--- +title: TypeScript +description: TypeScript adapter — graphs, transforms, and verification hooks. +--- + +## Detection + +The TypeScript adapter is favored when a `tsconfig.json` exists at the project root and `.ts` / `.tsx` files are present (file-count heuristic vs other adapters). + +--- + +## Analysis + +The TypeScript adapter’s **static analysis** integration is still evolving. In current builds, deep issue finding may be limited compared to Python; the pipeline still supports **blast radius** construction, **transforms** for supported fixers (for example whitespace), and **verification** (syntax, imports, tests). + +Use Python projects for the full seven-analyzer experience until TS analysis catches up. + +--- + +## Auto-fixes + +Fixers that only need text transforms (for example **trailing whitespace**) work on `.ts` / `.tsx` files. More complex semantic fixes follow the same verification gate as Python. + +--- + +## Verification + +- **Syntax** — TypeScript compiler API in check-only mode. +- **Imports** — Module resolution against the project layout. +- **Tests** — `vitest` or `jest` auto-detection where implemented. + +--- + +## Requirements + +- **Node.js 18+** +- **`tsconfig.json`** for typical project detection + +--- + +## See also + +- [CLI overview](/docs-npm/cli/overview) — Language selection at startup diff --git a/docs/docs-npm/mint.json b/docs/docs-npm/mint.json new file mode 100644 index 0000000..5e5ec39 --- /dev/null +++ b/docs/docs-npm/mint.json @@ -0,0 +1,85 @@ +{ + "$schema": "https://mintlify.com/schema.json", + "name": "Refactron", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "favicon": "/favicon.svg", + "colors": { + "primary": "#4a9eff", + "light": "#cce4ff", + "dark": "#1a3a5c" + }, + "topbarLinks": [ + { + "name": "npm", + "url": "https://www.npmjs.com/package/refactron" + } + ], + "topbarCtaButton": { + "name": "GitHub", + "url": "https://github.com/Refactron-ai/Refactron_Lib_TS" + }, + "tabs": [ + { + "name": "API Reference", + "url": "api" + } + ], + "anchors": [ + { + "name": "GitHub", + "icon": "github", + "url": "https://github.com/Refactron-ai/Refactron_Lib_TS" + }, + { + "name": "npm", + "icon": "npm", + "url": "https://www.npmjs.com/package/refactron" + }, + { + "name": "Issues", + "icon": "bug", + "url": "https://github.com/Refactron-ai/Refactron_Lib_TS/issues" + } + ], + "navigation": [ + { + "group": "Getting Started", + "pages": ["introduction", "quickstart", "configuration"] + }, + { + "group": "Core Concepts", + "pages": [ + "concepts/blast-radius", + "concepts/verification", + "concepts/sessions", + "concepts/temporal-analysis" + ] + }, + { + "group": "CLI", + "pages": [ + "cli/overview", + "cli/analyze", + "cli/issue-browser", + "cli/autofix", + "cli/verify", + "cli/session", + "cli/other-commands" + ] + }, + { + "group": "Languages", + "pages": ["languages/python", "languages/typescript"] + }, + { + "group": "API Reference", + "pages": ["api/overview", "api/models", "api/adapters", "api/orchestrator"] + } + ], + "footerSocials": { + "github": "https://github.com/Refactron-ai/Refactron_Lib_TS" + } +} diff --git a/docs/docs-npm/quickstart.mdx b/docs/docs-npm/quickstart.mdx new file mode 100644 index 0000000..72899f7 --- /dev/null +++ b/docs/docs-npm/quickstart.mdx @@ -0,0 +1,148 @@ +--- +title: Quickstart +description: Install Refactron and run your first analysis in under 2 minutes. +--- + +## Prerequisites + +- **Node.js 18+** +- **Git** (optional but recommended — enables temporal analysis and blast radius) +- **Python 3.8+** (required for Python projects) + +--- + +## Installation + + +```bash npm +npm install -g refactron +``` + +```bash npx (no install) +npx refactron +``` + + +Verify the installation: + +```bash +refactron --version +# 0.1.0-beta.2 +``` + +--- + +## First Run + +Navigate to any project directory and run: + +```bash +cd your-project +refactron +``` + +If you are not logged in, Refactron will open the authentication flow in your browser. After login, the REPL starts. + +--- + +## Analyze Your Project + +From the Refactron REPL prompt (`❯`), type: + +``` +❯ analyze . +``` + +Or analyze a specific directory: + +``` +❯ analyze src/ +``` + +Refactron will: +1. Detect your language (Python or TypeScript) +2. Run 7 analyzers in parallel +3. Build import and call graphs +4. Score every issue with a blast radius +5. **Automatically open the interactive issue browser** + +--- + +## The Issue Browser + +After analysis, you land in the interactive browser: + +``` + Issues session abc123 · 42 issues · 18 fixable +──────────────────────────────────────────────────── + # SEV MESSAGE FILE:LINE +▶ 1 CRIT SQL injection via string format db/query.py:47 · + 2 HIGH Cyclomatic complexity 14 > 10 api/views.py:123 · + 3 HIGH Unused import: os utils/file.py:1 · + 4 MED Missing return type annotation core/auth.py:88 · +──────────────────────────────────────────────────── +Msg: SQL injection via string format +Fix: Use parameterised queries instead of f-string formatting +File: db/query.py:47 blast:high [fixable] +──────────────────────────────────────────────────── +↑↓ · a fix · A all · d diff · v verify · / filter · q quit +``` + +### Key Actions + +| Key | Action | +|-----|--------| +| `↑` / `↓` or `j` / `k` | Navigate issues | +| `d` | Preview diff (dry-run, nothing written) | +| `a` | Fix selected issue (atomic write) | +| `A` | Fix **all** fixable issues in one pass | +| `v` | Verify a fixed issue's file | +| `/` | Filter by message, file, severity, or type | +| `g` / `G` | Jump to first / last issue | +| `q` | Quit browser, return to REPL | + +--- + +## Your First Fix + +1. Navigate to a fixable issue (marked `·` on the right) +2. Press `d` to preview the diff — nothing is written yet +3. Press `Esc` to dismiss the diff +4. Press `a` to apply the fix — the issue is now marked `✔` +5. Press `v` to verify the fix is safe + + +Press `A` to fix all fixable issues in one pass. Refactron applies each fix atomically with a backup, so you can always `rollback`. + + +--- + +## Workflow Summary + +``` +analyze . → scan + open browser + a / A → fix one or all issues + v → verify fixed files + q → return to REPL + +autofix . --verify → fix + verify in one command +status → review session summary +rollback → undo all fixes +diff → show unified diff of fixes +``` + +--- + +## Authentication + +Refactron uses OAuth 2.0 Device Authorization. The first time you run it: + +1. Your browser opens automatically to the approval page +2. You approve access — no password is ever stored +3. Credentials are saved to `~/.refactron/credentials.json` + +``` +❯ auth # check login status +❯ logout # remove credentials +❯ login # re-authenticate +``` diff --git a/docs/docs.json b/docs/docs.json index 897b0d6..4e3fa64 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -2,7 +2,7 @@ "$schema": "https://mintlify.com/docs.json", "theme": "palm", "name": "Refactron", - "description": "Safety-first refactoring for Python — behavior-preserving transforms with deterministic verification.", + "description": "Safety-first refactoring for Python \u2014 behavior-preserving transforms with deterministic verification.", "appearance": { "default": "dark", "strict": true @@ -29,60 +29,117 @@ } }, "custom": { - "stylesheets": ["/custom.css"] + "stylesheets": [ + "/custom.css" + ] }, "navigation": { - "groups": [ - { - "group": "Getting Started", - "pages": [ - "introduction", - "quickstart" - ] - }, - { - "group": "Essentials", - "pages": [ - "essentials/installation", - "essentials/configuration", - "essentials/authentication" - ] - }, - { - "group": "Guides", - "pages": [ - "guides/code-analysis", - "guides/refactoring", - "guides/ai-features", - "guides/pattern-learning" - ] - }, - { - "group": "CLI Reference", - "pages": [ - "cli/commands" - ] - }, - { - "group": "API Reference", - "pages": [ - "api-reference/overview", - "api-reference/refactron-class" - ] - }, + "tabs": [ { - "group": "Advanced", - "pages": [ - "advanced/performance", - "advanced/monitoring", - "advanced/ci-cd" + "tab": "Python Package", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "introduction", + "quickstart" + ] + }, + { + "group": "Essentials", + "pages": [ + "essentials/installation", + "essentials/configuration", + "essentials/authentication" + ] + }, + { + "group": "Guides", + "pages": [ + "guides/code-analysis", + "guides/refactoring", + "guides/ai-features", + "guides/pattern-learning" + ] + }, + { + "group": "CLI Reference", + "pages": [ + "cli/commands" + ] + }, + { + "group": "API Reference", + "pages": [ + "api-reference/overview", + "api-reference/refactron-class" + ] + }, + { + "group": "Advanced", + "pages": [ + "advanced/performance", + "advanced/monitoring", + "advanced/ci-cd" + ] + }, + { + "group": "Resources", + "pages": [ + "resources/changelog", + "resources/faq" + ] + } ] }, { - "group": "Resources", - "pages": [ - "resources/changelog", - "resources/faq" + "tab": "Node Package", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "docs-npm/introduction", + "docs-npm/quickstart", + "docs-npm/configuration" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "docs-npm/concepts/blast-radius", + "docs-npm/concepts/verification", + "docs-npm/concepts/sessions", + "docs-npm/concepts/temporal-analysis" + ] + }, + { + "group": "CLI", + "pages": [ + "docs-npm/cli/overview", + "docs-npm/cli/analyze", + "docs-npm/cli/issue-browser", + "docs-npm/cli/autofix", + "docs-npm/cli/verify", + "docs-npm/cli/session", + "docs-npm/cli/other-commands" + ] + }, + { + "group": "Languages", + "pages": [ + "docs-npm/languages/python", + "docs-npm/languages/typescript" + ] + }, + { + "group": "API Reference", + "pages": [ + "docs-npm/api/overview", + "docs-npm/api/models", + "docs-npm/api/adapters", + "docs-npm/api/orchestrator" + ] + } ] } ]