Conversation
Made-with: Cursor
📝 WalkthroughWalkthroughThis pull request introduces comprehensive documentation for Refactron across API references, CLI commands, core concepts, configuration guides, quick-start materials, and language adapters. All changes are documentation-only, using Mintlify as the site generator with a structured navigation layout across "Getting Started," "Core Concepts," "CLI," "Languages," and "API Reference" sections. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
♻️ Duplicate comments (1)
docs/introduction.mdx (1)
90-92:⚠️ Potential issue | 🔴 CriticalVerification flow diagram contradicts the implementation.
The diagram shows:
Blast trivial → syntax only Blast medium → syntax+imports Blast critical→ full test suiteThis implies three-tier gating, but the actual implementation is binary:
- Trivial → syntax only
- All other levels (low, medium, high, critical) → syntax + imports + test gate
This is the same inconsistency flagged in
docs/cli/verify.mdx. The verification engine does not implement amediumthreshold for imports or ahigh/criticalthreshold for the test gate.📝 Proposed fix
Verification Engine ┌─────────────────────────────────┐ - │ Blast trivial → syntax only │ - │ Blast medium → syntax+imports │ - │ Blast critical→ full test suite│ + │ Trivial blast → syntax only │ + │ All other levels → syntax, │ + │ imports, and full test suite │ └─────────────────────────────────┘🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/introduction.mdx` around lines 90 - 92, Update the verification flow diagram so it matches the actual binary gating implemented by the verification engine: replace the three-line tiered mapping ("Blast trivial → syntax only", "Blast medium → syntax+imports", "Blast critical→ full test suite") with a two-tier mapping that shows "Blast trivial → syntax only" and "All other levels (low, medium, high, critical) → syntax + imports + test gate"; make the same correction in the corresponding docs/cli/verify.mdx diagram/text so both docs reflect the verification engine behavior (i.e., there is no medium/high/critical threshold for tests).
🧹 Nitpick comments (1)
docs/quickstart.mdx (1)
30-30: Avoid brittle hardcoded operational numbers in Quickstart.
0.1.0-beta.2and “Run 7 analyzers” can drift quickly and create doc/code mismatch. Prefer placeholders or wording that doesn’t encode volatile values.Suggested doc tweak
refactron --version -# 0.1.0-beta.2 +# x.y.z-2. Run 7 analyzers in parallel +2. Run multiple analyzers in parallelAlso applies to: 64-64
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/quickstart.mdx` at line 30, Replace the hardcoded release/version and analyzer count in the quickstart header and text (e.g., "0.1.0-beta.2" and "Run 7 analyzers") with non‑brittle wording or placeholders: update the header to a generic version token like "vX.Y.Z" or "current version" and change the sentence "Run 7 analyzers" to something like "Run the configured analyzers" or "Run N analyzers" (or use a template variable such as {ANALYZER_COUNT}) so documentation does not encode volatile numeric values.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cli/verify.mdx`:
- Around line 24-25: The docs incorrectly state thresholded gating; update the
documentation text in docs/cli/verify.mdx to match the implementation: state
that selectChecks runs only syntaxCheck for blast.level === 'trivial' and runs
syntaxCheck, importsCheck and testGate for any non-trivial levels (low, medium,
high, critical); reference the selectChecks function and the symbols
syntaxCheck, importsCheck, testGate and blast.level from
src/verification/engine.ts so readers understand the exact behavior.
In `@docs/concepts/blast-radius.mdx`:
- Around line 40-47: Update the documented score ranges in
docs/concepts/blast-radius.mdx so they match the implementation in
src/analysis/blast-radius.ts: change the Level ranges to trivial = 0, low =
1–19, medium = 20–49, high = 50–74, and critical = 75–100 (keep the Verification
descriptions as appropriate). Reference the named levels trivial, low, medium,
high, critical in the table to ensure consistency with the constants/logic in
blast-radius.ts.
In `@docs/concepts/verification.mdx`:
- Line 59: The docs incorrectly state tests run only for `high`/`critical`;
update docs/concepts/verification.mdx (the sentence at line ~59 and the table at
~65-72) to match runtime behavior in src/verification/engine.ts (the test gate
logic around lines 55-64) by documenting that the test gate executes for every
blast level except `trivial` (i.e., `low`, `medium`, `high`, and `critical` run
the test suite), and adjust the table entries to mark `low`/`medium` as running
tests rather than "no test suite".
- Around line 134-136: The documentation example showing backup filenames with a
“.bak” suffix is inconsistent with the actual backup implementation in
src/infrastructure/backup.ts (the backup routine that stores files under their
original basename); update docs/concepts/verification.mdx to show the real
filenames (remove the “.bak” suffix) in the example code block so the doc
matches the code, or alternatively explicitly note the naming difference and
show both formats if you intend to keep the current names in code.
In `@docs/languages/python.mdx`:
- Line 20: Update the Python docs to accurately list only the implemented fixers
by replacing the current sentence in docs/languages/python.mdx with a statement
that the Python adapter currently supports only the "unused-imports" and
"trailing-whitespace" fixers; reference the implementation in
src/adapters/python/fixer.ts where the handler checks issue.fixerName ===
'unused-imports' and issue.fixerName === 'trailing-whitespace' so readers see
the source of truth and remove mentions of unimplemented fixers like dead code,
type hints, f-string safety, and import sorting.
In `@docs/languages/typescript.mdx`:
- Line 30: The docs line claiming "vitest or jest auto-detection" is inaccurate
because the TypeScript adapter's test-run invocation currently only runs vitest
(see the test-run block that invokes vitest in the TypeScript adapter), so
update the sentence in docs/languages/typescript.mdx to say that only vitest
auto-detection is implemented (remove or rephrase any mention of jest
auto-detection) and make the wording explicit that jest is not currently
supported by the adapter's test-run code.
---
Duplicate comments:
In `@docs/introduction.mdx`:
- Around line 90-92: Update the verification flow diagram so it matches the
actual binary gating implemented by the verification engine: replace the
three-line tiered mapping ("Blast trivial → syntax only", "Blast medium →
syntax+imports", "Blast critical→ full test suite") with a two-tier mapping that
shows "Blast trivial → syntax only" and "All other levels (low, medium, high,
critical) → syntax + imports + test gate"; make the same correction in the
corresponding docs/cli/verify.mdx diagram/text so both docs reflect the
verification engine behavior (i.e., there is no medium/high/critical threshold
for tests).
---
Nitpick comments:
In `@docs/quickstart.mdx`:
- Line 30: Replace the hardcoded release/version and analyzer count in the
quickstart header and text (e.g., "0.1.0-beta.2" and "Run 7 analyzers") with
non‑brittle wording or placeholders: update the header to a generic version
token like "vX.Y.Z" or "current version" and change the sentence "Run 7
analyzers" to something like "Run the configured analyzers" or "Run N analyzers"
(or use a template variable such as {ANALYZER_COUNT}) so documentation does not
encode volatile numeric values.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: af973e3f-1bbe-4206-827c-3c9ec2cee6b8
📒 Files selected for processing (21)
docs/api/adapters.mdxdocs/api/models.mdxdocs/api/orchestrator.mdxdocs/api/overview.mdxdocs/cli/analyze.mdxdocs/cli/autofix.mdxdocs/cli/issue-browser.mdxdocs/cli/other-commands.mdxdocs/cli/overview.mdxdocs/cli/session.mdxdocs/cli/verify.mdxdocs/concepts/blast-radius.mdxdocs/concepts/sessions.mdxdocs/concepts/temporal-analysis.mdxdocs/concepts/verification.mdxdocs/configuration.mdxdocs/introduction.mdxdocs/languages/python.mdxdocs/languages/typescript.mdxdocs/mint.jsondocs/quickstart.mdx
| - Import resolution (at medium+ blast) | ||
| - Test gate (at high / critical blast) |
There was a problem hiding this comment.
Documentation contradicts the actual implementation.
The documentation claims checks are gated by specific blast level thresholds:
- "Import resolution (at medium+ blast)"
- "Test gate (at high / critical blast)"
However, the actual selectChecks implementation (see src/verification/engine.ts:55-64) uses binary logic:
if (blast.level === 'trivial') {
return [this.syntaxCheck];
}
return [this.syntaxCheck, this.importsCheck, testGate];The code runs all three checks (syntax, imports, test gate) for any blast level that is not trivial—including low and medium. There are no threshold comparisons for medium+ or high/critical as documented.
📝 Proposed fix to align documentation with implementation
-The verification engine runs checks based on **blast radius** (see [Verification engine](/concepts/verification)):
-
-- Syntax
-- Import resolution (at medium+ blast)
-- Test gate (at high / critical blast)
+The verification engine runs checks based on **blast radius** (see [Verification engine](/concepts/verification)):
+
+- **Trivial blast** — Syntax only
+- **All other levels** (low, medium, high, critical) — Syntax, import resolution, and test gate🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cli/verify.mdx` around lines 24 - 25, The docs incorrectly state
thresholded gating; update the documentation text in docs/cli/verify.mdx to
match the implementation: state that selectChecks runs only syntaxCheck for
blast.level === 'trivial' and runs syntaxCheck, importsCheck and testGate for
any non-trivial levels (low, medium, high, critical); reference the selectChecks
function and the symbols syntaxCheck, importsCheck, testGate and blast.level
from src/verification/engine.ts so readers understand the exact behavior.
| | 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) | | ||
|
|
There was a problem hiding this comment.
Blast-level score ranges do not match implementation.
The table currently documents trivial: 0–10, low: 11–25, etc., but src/analysis/blast-radius.ts uses trivial=0, low=1–19, medium=20–49, high=50–74, critical=75–100. Please align the ranges to avoid incorrect risk interpretation in docs.
Proposed fix
| 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) |
+| `trivial` | 0 | Syntax check only |
+| `low` | 1–19 | Syntax + imports + test gate |
+| `medium` | 20–49 | Syntax + imports + test gate |
+| `high` | 50–74 | Syntax + imports + test gate |
+| `critical` | 75–100 | Full: syntax + imports + test suite (120s timeout) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/concepts/blast-radius.mdx` around lines 40 - 47, Update the documented
score ranges in docs/concepts/blast-radius.mdx so they match the implementation
in src/analysis/blast-radius.ts: change the Level ranges to trivial = 0, low =
1–19, medium = 20–49, high = 50–74, and critical = 75–100 (keep the Verification
descriptions as appropriate). Reference the named levels trivial, low, medium,
high, critical in the table to ensure consistency with the constants/logic in
blast-radius.ts.
| - **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. |
There was a problem hiding this comment.
Verification gating by blast level is documented incorrectly.
Implementation (src/verification/engine.ts:55-64) runs test gate for every non-trivial blast level. Current docs say tests are only for high/critical, and the table marks low/medium as no test suite. Please update to match runtime behavior.
Proposed fix
-This is the most expensive check and only runs for `high` and `critical` blast radius issues.
+This is the most expensive check and runs for all non-`trivial` blast radius issues. | Blast Level | Syntax | Imports | Test Suite |
|-------------|--------|---------|------------|
| `trivial` | ✓ | — | — |
-| `low` | ✓ | — | — |
-| `medium` | ✓ | ✓ | — |
+| `low` | ✓ | ✓ | ✓ |
+| `medium` | ✓ | ✓ | ✓ |
| `high` | ✓ | ✓ | ✓ |
| `critical` | ✓ | ✓ | ✓ (120s) |Also applies to: 65-72
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/concepts/verification.mdx` at line 59, The docs incorrectly state tests
run only for `high`/`critical`; update docs/concepts/verification.mdx (the
sentence at line ~59 and the table at ~65-72) to match runtime behavior in
src/verification/engine.ts (the test gate logic around lines 55-64) by
documenting that the test gate executes for every blast level except `trivial`
(i.e., `low`, `medium`, `high`, and `critical` run the test suite), and adjust
the table entries to mark `low`/`medium` as running tests rather than "no test
suite".
| src/auth/token.ts.bak | ||
| src/api/routes.ts.bak | ||
| ``` |
There was a problem hiding this comment.
Backup filename example does not match current backup implementation.
The docs show *.bak backup names, but src/infrastructure/backup.ts:7-31 stores backups with the original basename (no .bak suffix). Aligning this prevents operator confusion during manual recovery.
Proposed fix
.refactron/
backups/
{session-id}/
- src/auth/token.ts.bak
- src/api/routes.ts.bak
+ token.ts
+ routes.ts📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| src/auth/token.ts.bak | |
| src/api/routes.ts.bak | |
| ``` | |
| src/auth/token.ts.bak | |
| src/api/routes.ts.bak |
| src/auth/token.ts.bak | |
| src/api/routes.ts.bak | |
| ``` | |
| token.ts | |
| routes.ts |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/concepts/verification.mdx` around lines 134 - 136, The documentation
example showing backup filenames with a “.bak” suffix is inconsistent with the
actual backup implementation in src/infrastructure/backup.ts (the backup routine
that stores files under their original basename); update
docs/concepts/verification.mdx to show the real filenames (remove the “.bak”
suffix) in the example code block so the doc matches the code, or alternatively
explicitly note the naming difference and show both formats if you intend to
keep the current names in code.
|
|
||
| ## 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. |
There was a problem hiding this comment.
Documentation overstates implemented fixers.
The documentation claims Python fixers include: "unused imports, dead code, type hints, f-string safety, trailing whitespace, import sorting, and others."
However, the actual Python adapter implementation (src/adapters/python/fixer.ts:5-27) only supports two fixers:
if (issue.fixerName === 'unused-imports') {
return removeUnusedImport(code, issue);
}
if (issue.fixerName === 'trailing-whitespace') {
return {
transformedCode: code.replace(/[ \t]+$/gm, ''),
description: 'Remove trailing whitespace',
riskLevel: 'low',
};
}The fixers for dead code, type hints, f-string safety, and import sorting are not implemented.
📝 Proposed fix to reflect actual capabilities
-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.
+Transforms are applied in-memory and then gated by the **verification engine** before write. Python-specific fixers currently include **unused imports** and **trailing whitespace** cleanup.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/languages/python.mdx` at line 20, Update the Python docs to accurately
list only the implemented fixers by replacing the current sentence in
docs/languages/python.mdx with a statement that the Python adapter currently
supports only the "unused-imports" and "trailing-whitespace" fixers; reference
the implementation in src/adapters/python/fixer.ts where the handler checks
issue.fixerName === 'unused-imports' and issue.fixerName ===
'trailing-whitespace' so readers see the source of truth and remove mentions of
unimplemented fixers like dead code, type hints, f-string safety, and import
sorting.
|
|
||
| - **Syntax** — TypeScript compiler API in check-only mode. | ||
| - **Imports** — Module resolution against the project layout. | ||
| - **Tests** — `vitest` or `jest` auto-detection where implemented. |
There was a problem hiding this comment.
Verification docs currently overstate test-runner support.
The implementation shown in src/adapters/typescript/index.ts:80-98 runs vitest only; jest auto-detection is not present there. Please reword this line to avoid implying current jest support.
✏️ Suggested doc fix
-- **Tests** — `vitest` or `jest` auto-detection where implemented.
+- **Tests** — `vitest` execution is supported in current builds; other runners may be added in future versions.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Tests** — `vitest` or `jest` auto-detection where implemented. | |
| - **Tests** — `vitest` execution is supported in current builds; other runners may be added in future versions. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/languages/typescript.mdx` at line 30, The docs line claiming "vitest or
jest auto-detection" is inaccurate because the TypeScript adapter's test-run
invocation currently only runs vitest (see the test-run block that invokes
vitest in the TypeScript adapter), so update the sentence in
docs/languages/typescript.mdx to say that only vitest auto-detection is
implemented (remove or rephrase any mention of jest auto-detection) and make the
wording explicit that jest is not currently supported by the adapter's test-run
code.
There was a problem hiding this comment.
Pull request overview
Adds a new Mintlify documentation site for Refactron, covering onboarding, core concepts, CLI usage, language adapters, and internal API reference to help users understand and operate the tool.
Changes:
- Introduces Mintlify site configuration (
docs/mint.json) and navigation structure. - Adds “Getting Started” docs (Introduction, Quickstart, Configuration) and concept guides (blast radius, verification, sessions, temporal analysis).
- Adds CLI and internal API reference pages, plus language-specific pages for Python and TypeScript.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/mint.json | Mintlify site configuration (branding, nav, links). |
| docs/introduction.mdx | High-level product overview and differentiators. |
| docs/quickstart.mdx | First-run walkthrough and core workflow summary. |
| docs/configuration.mdx | refactron.yaml configuration reference and examples. |
| docs/concepts/blast-radius.mdx | Explains blast radius scoring and levels. |
| docs/concepts/verification.mdx | Explains verification checks, timeouts, and write/backup model. |
| docs/concepts/sessions.mdx | Documents persisted work sessions and lifecycle. |
| docs/concepts/temporal-analysis.mdx | Documents Git-history enrichment and risk labeling. |
| docs/cli/overview.mdx | CLI entry points, authentication, detection, and command map. |
| docs/cli/analyze.mdx | analyze REPL command behavior and prerequisites. |
| docs/cli/issue-browser.mdx | TUI issue browser layout and keybindings. |
| docs/cli/autofix.mdx | autofix REPL command behavior and flags. |
| docs/cli/verify.mdx | verify REPL command behavior and outputs. |
| docs/cli/session.mdx | Session listing/loading behavior in the REPL. |
| docs/cli/other-commands.mdx | Auth/status/diff/rollback/help/exit command docs. |
| docs/languages/python.mdx | Python adapter behavior and verification expectations. |
| docs/languages/typescript.mdx | TypeScript adapter behavior and verification expectations. |
| docs/api/overview.mdx | Package layout and stability guidance for programmatic use. |
| docs/api/models.mdx | Core public types reference. |
| docs/api/adapters.mdx | ILanguageAdapter interface reference. |
| docs/api/orchestrator.mdx | Orchestrator API reference and pipeline description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Refactron will: | ||
| 1. Detect your language (Python or TypeScript) | ||
| 2. Run 7 analyzers in parallel |
There was a problem hiding this comment.
The quickstart says Refactron "runs 7 analyzers in parallel", but the current AnalysisEngine runs analyzers sequentially per file (only graph building / temporal profiling is parallelized). Please update this claim to match actual behavior, or adjust the implementation if parallel analyzer execution is intended.
| 2. Run 7 analyzers in parallel | |
| 2. Run 7 analyzers across your codebase |
| ▼ | ||
| Analysis Engine | ||
| ┌─────────────────────────────────┐ | ||
| │ 7 analyzers run in parallel │ |
There was a problem hiding this comment.
The "How It Works" diagram states "7 analyzers run in parallel", but the current AnalysisEngine runs analyzers sequentially per file (graphs/temporal profiling are parallelized, analyzer loop is not). Please adjust the diagram text to avoid overstating parallelism.
| │ 7 analyzers run in parallel │ | |
| │ 7 analyzers process each file │ |
| 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. |
There was a problem hiding this comment.
This section describes the Python "Import Resolution Check" as catching broken imports via py_compile, but py_compile.compile() only byte-compiles and does not resolve/import dependencies, so missing modules typically won't be detected. Please clarify what this check actually guarantees (or change the check implementation if true import resolution is intended).
| 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. | |
| Confirms that module references still look valid after the transform, within the guarantees of each language-specific check. | |
| - **Python:** runs `py_compile` to byte-compile the transformed file; this confirms the file can be compiled, but does **not** resolve or import its dependencies | |
| - **TypeScript:** checks that all `import` statements resolve to real modules | |
| For TypeScript, this catches fixes that accidentally removed a needed import or renamed an exported symbol. For Python, `py_compile` only guarantees compileability of the file itself; missing modules are typically caught later by tests or a real runtime import. |
| 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) | | ||
|
|
There was a problem hiding this comment.
The docs say the test gate "only runs for high and critical blast radius issues" and the table below skips imports/tests for low/medium. The current VerificationEngine runs syntax+imports+test-gate for every level except trivial. Please update the blast-level check mapping (or update the engine to match the documented behavior).
| ## 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%) | ||
| ``` |
There was a problem hiding this comment.
The confidence score is documented as checks_passed / checks_run, with non-zero confidence shown even when blocked. In the current implementation, confidence is a fixed heuristic (0.7/0.85/0.97) on pass and 0 on any block. Please align the docs/examples with the actual scoring behavior (or adjust the scoring implementation to match the documented formula).
| autofix . --verify → fix + verify in one command | ||
| status → review session summary | ||
| rollback → undo all fixes | ||
| diff → show unified diff of fixes | ||
| ``` |
There was a problem hiding this comment.
The workflow summary says rollback will "undo all fixes". In the current REPL implementation, rollback is informational-only (no restore is performed). Please adjust the summary to avoid promising functionality that isn’t currently available.
| All file writes use a temp-file-then-rename strategy. Partial writes and corrupted files are impossible. | ||
| </Card> | ||
| <Card title="Backup & Rollback" icon="rotate-left"> | ||
| Every session is backed up automatically. Run `rollback` to restore the previous state at any time. |
There was a problem hiding this comment.
This card says "Run rollback to restore the previous state at any time", but the current REPL rollback command does not perform any restore (it only prints guidance). Please soften/qualify this claim or wire rollback to actually restore from .refactron/backups/.
| Every session is backed up automatically. Run `rollback` to restore the previous state at any time. | |
| Every session is backed up automatically. Use `rollback` for restore guidance and recover from the saved backups when needed. |
| <Card title="Verification Gate" icon="shield-check"> | ||
| Changes are verified (syntax, imports, test suite) before being written to disk. Strictness scales automatically with blast radius. | ||
| </Card> |
There was a problem hiding this comment.
The "Verification Gate" card claims strictness scales with blast radius, but the current VerificationEngine runs syntax+imports+test-gate for every blast level except trivial (no medium/high differentiation). Please update this statement to reflect current behavior or implement blast-level-specific check selection.
| ``` | ||
|
|
||
| Run `rollback` at any time to restore all files from the session backup. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
This section suggests rollback restores all files from the session backup. In the current REPL implementation, rollback does not perform any restore (it only prints guidance). Please update this section to match reality or connect rollback to BackupManager.restore() for an actual restore flow.
|
|
||
| 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.** |
There was a problem hiding this comment.
The statement "Nothing is written to disk until verification passes" is unconditional, but verification can be disabled via autofix.require_verification: false (or overridden by CLI options), in which case writes can occur without any checks. Consider qualifying this as the default behavior / when verification is enabled.
| **Nothing is written to disk until verification passes.** | |
| **By default, nothing is written to disk until verification passes. If verification is disabled, writes can occur without these checks.** |
Summary by CodeRabbit