docs: integrate npm package documentation#148
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
github-actions
bot
added
documentation
📝 WalkthroughWalkthroughThis PR introduces comprehensive documentation for the npm package, covering API reference (adapters, models, orchestrator), CLI commands, core concepts, language guides, configuration, and getting-started materials, while restructuring the documentation navigation to accommodate both Python and Node package documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
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 |
There was a problem hiding this comment.
Pull request overview
Integrates a new Mintlify documentation set for the npm (Node) package alongside the existing Python package docs by restructuring site navigation into tabs and adding a full set of Node-focused concept/CLI/API pages.
Changes:
- Updated
docs/docs.jsonnavigation to use tabbed docs (“Python Package” / “Node Package”). - Added a complete
docs/docs-npm/documentation tree (intro, quickstart, configuration, concepts, CLI pages, languages, API reference). - Added a Mintlify config file for the npm docs subtree (
docs/docs-npm/mint.json).
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/docs.json | Adds tabbed navigation and wires in the new docs-npm/* pages under a “Node Package” tab. |
| docs/docs-npm/mint.json | Mintlify config for the npm docs subtree (branding/nav/external links). |
| docs/docs-npm/introduction.mdx | Node package introduction/positioning and core differentiators. |
| docs/docs-npm/quickstart.mdx | Node package install + first-run + REPL workflow walkthrough. |
| docs/docs-npm/configuration.mdx | Node package configuration reference and examples. |
| docs/docs-npm/concepts/blast-radius.mdx | Explains blast radius model and how it affects verification strictness. |
| docs/docs-npm/concepts/verification.mdx | Documents the verification engine checks, selection, and timeouts. |
| docs/docs-npm/concepts/sessions.mdx | Describes persisted work sessions and their lifecycle. |
| docs/docs-npm/concepts/temporal-analysis.mdx | Documents git-history-based enrichment and risk labeling. |
| docs/docs-npm/cli/overview.mdx | CLI entry points, auth, detection, and command map. |
| docs/docs-npm/cli/analyze.mdx | analyze command behavior and session creation. |
| docs/docs-npm/cli/issue-browser.mdx | Interactive TUI issue browser usage and keybindings. |
| docs/docs-npm/cli/autofix.mdx | autofix command behavior and flags. |
| docs/docs-npm/cli/verify.mdx | verify command behavior and what checks run. |
| docs/docs-npm/cli/session.mdx | session listing/loading behavior. |
| docs/docs-npm/cli/other-commands.mdx | Auth/status/diff/rollback/issues/help/exit documentation. |
| docs/docs-npm/languages/python.mdx | Python adapter behavior (detection, analysis, verification). |
| docs/docs-npm/languages/typescript.mdx | TypeScript adapter behavior and current limitations. |
| docs/docs-npm/api/overview.mdx | High-level API layering and stability notes. |
| docs/docs-npm/api/models.mdx | Documents core types used by the Node package. |
| docs/docs-npm/api/adapters.mdx | Documents ILanguageAdapter interface and responsibilities. |
| docs/docs-npm/api/orchestrator.mdx | Documents orchestrator responsibilities and methods. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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 |
There was a problem hiding this comment.
The CLI in this repository uses .refactron.yaml (not refactron.yaml) and expects version to be "1.0" (ConfigValidator.CURRENT_VERSION). Consider updating the filename/version in this page (or explicitly calling out that the Node Package uses a different config filename/schema) to avoid users creating a config that the shipped CLI won’t load/validate.
| 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 | |
| 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.0" |
| code_smell: | ||
| enabled: true | ||
| max_method_lines: 50 # lines per function/method limit | ||
|
|
||
| dead_code: | ||
| enabled: true | ||
|
|
||
| type_hints: | ||
| enabled: true | ||
|
|
||
| dependencies: | ||
| enabled: true | ||
|
|
There was a problem hiding this comment.
This config example uses analyzer keys like code_smell and dependencies, but the analyzer names accepted by this repo’s config validator are code_smells and dependency (see ConfigValidator.VALID_ANALYZERS). If this page is meant to document the Python package in this repo, these keys should be updated so copied configs validate correctly; if it’s meant for a separate npm CLI, please call that out explicitly to prevent users mixing schemas.
|
|
||
| ## 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. |
There was a problem hiding this comment.
This page points to src/core/models.ts and src/adapters/interface.ts as in-repo sources, but this repository doesn’t contain a src/ tree. If the intent is to reference the separate TypeScript/npm repo, consider linking to the exact GitHub path/commit there (or rewording to avoid implying these files exist in this repo).
| 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. | |
| The Models and Adapters API surfaces documented here are treated as **LOCKED**: if you depend on them from outside the project, treat them as semver-sensitive. |
|
|
||
| ## Interface | ||
|
|
||
| Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`): |
There was a problem hiding this comment.
The interface reference src/adapters/interface.ts does not exist in this repository. If these docs are meant to describe the npm/TypeScript codebase hosted elsewhere, link to that repo/path (or rephrase to avoid a broken “Source” reference for readers browsing this repo).
| Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`): | |
| Language adapters implement the following `ILanguageAdapter` contract: |
|
|
||
| ## Source | ||
|
|
||
| `src/core/orchestrator.ts` |
There was a problem hiding this comment.
The “Source” reference src/core/orchestrator.ts doesn’t exist in this repository. Please link to the correct source location (e.g., in the external TypeScript/npm repo) or adjust wording so it’s not a dead reference for readers.
| `src/core/orchestrator.ts` | |
| This API is implemented in the project's TypeScript/npm source package. Refer to that package's repository for the current `Orchestrator` implementation. |
| 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. |
There was a problem hiding this comment.
This page says definitions live in src/core/models.ts, but that path doesn’t exist in this repository. If this is meant to refer to the external TypeScript/npm implementation, consider linking to the actual file in that repo (or remove the “Source” pointer).
| 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. | |
| The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. These additional types are part of the TypeScript/npm implementation, but the `src/core/models.ts` path referenced previously is not present in this repository. | |
| --- | |
| ## Source | |
| This page documents the public model shapes shown above. The previously referenced `src/core/models.ts` path is not present in this repository. |
![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
🧹 Nitpick comments (3)
docs/docs-npm/api/overview.mdx (1)
8-11: Prefer documenting exported entrypoints overdist/*paths.Suggest emphasizing
package.jsonexportsas the primary import surface and de-emphasizing deepdist/...imports, which are more likely to break across releases.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs-npm/api/overview.mdx` around lines 8 - 11, Update the docs text to recommend importing from the package's published entry points (the package.json "exports") instead of deep `dist/...` paths: replace or reword the sentence that references `dist/cli/index.js` and examples like `dist/core/models.js` / `dist/core/orchestrator.js` to stress using the exported entrypoints (e.g., top-level package imports or named exports defined in package.json) as the supported public API for the `refactron` CLI and library; keep a short note that deep `dist/*` imports may break across releases and point readers to check package.json "exports" for valid import paths.docs/docs-npm/cli/verify.mdx (1)
8-14: Make the usage synopsis explicit for session-wide mode.Line 9 currently shows
verify [file], but Line 13 also documents.and no-arg behavior. Consider reflecting that directly in the usage line to reduce ambiguity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs-npm/cli/verify.mdx` around lines 8 - 14, Update the CLI usage synopsis so it explicitly shows session-wide mode in the code block that currently reads "verify [file]"; change it to include "." and the no-arg form (for example "verify [file|.]" or a two-line snippet like "verify [file]" and "verify" / "verify .") so the usage aligns with the explanatory text about "." and no-arg behavior in the same section.docs/docs-npm/quickstart.mdx (1)
30-30: Avoid hardcoding a specific CLI version in Quickstart output.Line 30 uses a pinned example (
0.1.0-beta.2), which will go stale quickly. Prefer a placeholder-style output example.Suggested doc tweak
refactron --version -# 0.1.0-beta.2 +# x.y.z🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs-npm/quickstart.mdx` at line 30, Replace the hardcoded header "# 0.1.0-beta.2" in the quickstart output example with a placeholder-style value so the docs don't go stale; e.g., change the string "0.1.0-beta.2" (found in the header line "# 0.1.0-beta.2") to a generic placeholder such as "<cli-version>" or "{{cli_version}}" and update any adjacent explanatory text to refer to the placeholder.
🤖 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/docs-npm/api/models.mdx`:
- Around line 104-110: The docs reference the non-existent TypeScript file
src/core/models.ts; update the link and text to point to the actual Python
source refactron/core/models.py (or explicitly state this doc targets a separate
JS/TS package if that was intended) and ensure the types mentioned
(PipelineSession, FixQueueItem, FixStatus) are referenced to their Python
definitions or a note is added clarifying language mismatch.
In `@docs/docs-npm/cli/analyze.mdx`:
- Around line 40-42: The "Supported language detected" link currently points
only to /docs-npm/languages/python which is too narrow; update the link target
in the docs text "Supported language detected for the project. See
[Languages](/docs-npm/languages/python)." to point to a neutral languages index
(e.g., /docs-npm/languages) or include links to both relevant pages (e.g.,
Python and TypeScript) so Node users aren't misrouted; edit the link target text
in docs/docs-npm/cli/analyze.mdx accordingly.
In `@docs/docs-npm/cli/issue-browser.mdx`:
- Around line 28-39: The docs table for the issue browser is missing the
severity drill-in and navigation keybindings used by the interactive viewer;
update the CLI docs page (issue-browser.mdx) to include the keys `1`-`4` for
drilling into severity groups and `n`/`p`/`b`/`q` for next/previous/back/quit
navigation, and add a short note that `refactron analyze` launches the TTY
interactive issue viewer with severity-grouped navigation and falls back to
non-interactive output for CI/CD; reference the interactive issue
viewer/keybinding descriptions in the same table and adjacent paragraph so
readers see the mapping next to existing entries like `↑`/`↓`, `d`, `a`, `A`,
`v`, `/`, `g`/`G`, and `q`.
In `@docs/docs-npm/concepts/verification.mdx`:
- Around line 8-9: The doc incorrectly states checks are selected by blast
radius; update the "Verification Engine" documentation to state that
VerificationEngine always initializes and runs all three checks (syntax, medium,
test gate) sequentially, short-circuiting on the first failure, rather than
skipping checks by blast level; specifically replace any wording that says
checks are chosen by blast radius or that the test gate runs only for
high/critical with a clear description of the current implementation
(VerificationEngine initializes all checks and executes them in order), and
optionally add a note that blast-level-based skipping is a planned/possible
enhancement if desired.
In `@docs/docs-npm/configuration.mdx`:
- Around line 8-49: The docs show nested config sections (analyzers.*,
verification.*, autofix.*, output.*) but the loader expects flat fields passed
into RefactronConfig via RefactronConfig.from_file (refactron/core/config.py),
causing TypeError/ConfigError; fix by updating this example YAML to the flat
top-level shape that RefactronConfig expects (use the exact field names from the
RefactronConfig dataclass) or alternatively modify RefactronConfig.from_file to
deep-merge and normalize nested sections into the flat dict before calling
cls(**config_dict); reference RefactronConfig and from_file to locate the code
to change.
In `@docs/docs-npm/quickstart.mdx`:
- Line 9: Update the prerequisite sentence in quickstart.mdx to stop claiming
Git enables "blast radius": edit the line that currently reads "**Git**
(optional but recommended — enables temporal analysis and blast radius)" to
remove "and blast radius" so it only states that Git enables temporal analysis;
keep the rest of the phrasing intact to avoid conflicting guidance about
structural (blast radius) analysis being separate.
---
Nitpick comments:
In `@docs/docs-npm/api/overview.mdx`:
- Around line 8-11: Update the docs text to recommend importing from the
package's published entry points (the package.json "exports") instead of deep
`dist/...` paths: replace or reword the sentence that references
`dist/cli/index.js` and examples like `dist/core/models.js` /
`dist/core/orchestrator.js` to stress using the exported entrypoints (e.g.,
top-level package imports or named exports defined in package.json) as the
supported public API for the `refactron` CLI and library; keep a short note that
deep `dist/*` imports may break across releases and point readers to check
package.json "exports" for valid import paths.
In `@docs/docs-npm/cli/verify.mdx`:
- Around line 8-14: Update the CLI usage synopsis so it explicitly shows
session-wide mode in the code block that currently reads "verify [file]"; change
it to include "." and the no-arg form (for example "verify [file|.]" or a
two-line snippet like "verify [file]" and "verify" / "verify .") so the usage
aligns with the explanatory text about "." and no-arg behavior in the same
section.
In `@docs/docs-npm/quickstart.mdx`:
- Line 30: Replace the hardcoded header "# 0.1.0-beta.2" in the quickstart
output example with a placeholder-style value so the docs don't go stale; e.g.,
change the string "0.1.0-beta.2" (found in the header line "# 0.1.0-beta.2") to
a generic placeholder such as "<cli-version>" or "{{cli_version}}" and update
any adjacent explanatory text to refer to the placeholder.
🪄 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: a0f252e4-9283-42b7-a8fa-2b44844d5d4a
📒 Files selected for processing (22)
docs/docs-npm/api/adapters.mdxdocs/docs-npm/api/models.mdxdocs/docs-npm/api/orchestrator.mdxdocs/docs-npm/api/overview.mdxdocs/docs-npm/cli/analyze.mdxdocs/docs-npm/cli/autofix.mdxdocs/docs-npm/cli/issue-browser.mdxdocs/docs-npm/cli/other-commands.mdxdocs/docs-npm/cli/overview.mdxdocs/docs-npm/cli/session.mdxdocs/docs-npm/cli/verify.mdxdocs/docs-npm/concepts/blast-radius.mdxdocs/docs-npm/concepts/sessions.mdxdocs/docs-npm/concepts/temporal-analysis.mdxdocs/docs-npm/concepts/verification.mdxdocs/docs-npm/configuration.mdxdocs/docs-npm/introduction.mdxdocs/docs-npm/languages/python.mdxdocs/docs-npm/languages/typescript.mdxdocs/docs-npm/mint.jsondocs/docs-npm/quickstart.mdxdocs/docs.json
| 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. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Checking for referenced TypeScript models path..."
fd -a "models.ts" || true
rg -n "src/core/models.ts|refactron/core/models.py" docs/docs-npm/api/models.mdx refactron/core/models.py || true
echo
echo "If src/core/models.ts is absent and refactron/core/models.py exists, docs path is incorrect for this repository."Repository: Refactron-ai/Refactron_lib
Length of output: 528
🏁 Script executed:
# Check repository root structure
git ls-files | head -30
# Look for src/ directory
fd -type d "src" --max-depth 2
# Check for any TypeScript files in the repo
fd -type f "\.ts$" | head -20
# Verify Python structure
fd -type d "refactron" --max-depth 1Repository: Refactron-ai/Refactron_lib
Length of output: 1351
🏁 Script executed:
# Check the actual models.py file to understand the structure
cat -n refactron/core/models.py | head -50Repository: Refactron-ai/Refactron_lib
Length of output: 1646
Documentation path references non-existent TypeScript file.
Lines 104 and 110 direct readers to src/core/models.ts, but this repository contains Python source code with model definitions in refactron/core/models.py. The src/ directory does not exist. Either update the reference to point to refactron/core/models.py or clarify if this documentation targets a separate JavaScript/TypeScript package.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/api/models.mdx` around lines 104 - 110, The docs reference the
non-existent TypeScript file src/core/models.ts; update the link and text to
point to the actual Python source refactron/core/models.py (or explicitly state
this doc targets a separate JS/TS package if that was intended) and ensure the
types mentioned (PipelineSession, FixQueueItem, FixStatus) are referenced to
their Python definitions or a note is added clarifying language mismatch.
| - Authenticated session (unless your deployment waives auth). | ||
| - Supported language detected for the project. See [Languages](/docs-npm/languages/python). | ||
|
|
There was a problem hiding this comment.
Language prerequisite link is too narrow.
The text says “supported language” but links only to Python. Consider linking to a neutral languages index or both Python and TypeScript pages to avoid misrouting Node users.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/cli/analyze.mdx` around lines 40 - 42, The "Supported language
detected" link currently points only to /docs-npm/languages/python which is too
narrow; update the link target in the docs text "Supported language detected for
the project. See [Languages](/docs-npm/languages/python)." to point to a neutral
languages index (e.g., /docs-npm/languages) or include links to both relevant
pages (e.g., Python and TypeScript) so Node users aren't misrouted; edit the
link target text in docs/docs-npm/cli/analyze.mdx accordingly.
| | 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 | | ||
|
|
There was a problem hiding this comment.
Keybinding docs may be incomplete vs implemented navigation model.
This table omits the severity drill-in/navigation pattern (1-4, n/p/b/q) described for the interactive issue viewer. If implementation still follows that model, users will get stuck with the current docs.
Based on learnings: refactron analyze command must show interactive issue viewer (TTY) with severity-grouped navigation using [1-4] to drill in and [n/p/b/q] to navigate, with non-interactive fallback for CI/CD.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/cli/issue-browser.mdx` around lines 28 - 39, The docs table for
the issue browser is missing the severity drill-in and navigation keybindings
used by the interactive viewer; update the CLI docs page (issue-browser.mdx) to
include the keys `1`-`4` for drilling into severity groups and `n`/`p`/`b`/`q`
for next/previous/back/quit navigation, and add a short note that `refactron
analyze` launches the TTY interactive issue viewer with severity-grouped
navigation and falls back to non-interactive output for CI/CD; reference the
interactive issue viewer/keybinding descriptions in the same table and adjacent
paragraph so readers see the mapping next to existing entries like `↑`/`↓`, `d`,
`a`, `A`, `v`, `/`, `g`/`G`, and `q`.
| 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. | ||
|
|
There was a problem hiding this comment.
Blast-level check selection is documented incorrectly.
Line 8 and Lines 63–72 state checks are selected by blast radius, and Line 59 says test gate runs only for high/critical. In current implementation, VerificationEngine always initializes all three checks and executes them sequentially (short-circuiting only on failure), with no blast-level-based skip logic (refactron/verification/engine.py, Lines 30–47 and 48–96).
Suggested doc correction
-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.
+The Verification Engine is the safety gate between an auto-fix transform and a disk write. It runs checks in a fixed sequence and short-circuits on first failure.
-This is the most expensive check and only runs for `high` and `critical` blast radius issues.
+This is the most expensive check and runs after syntax/import checks if earlier checks pass.
-## Check Selection by Blast Level
+## Check Execution Order
-| Blast Level | Syntax | Imports | Test Suite |
-|-------------|--------|---------|------------|
-| `trivial` | ✓ | — | — |
-| `low` | ✓ | — | — |
-| `medium` | ✓ | ✓ | — |
-| `high` | ✓ | ✓ | ✓ |
-| `critical` | ✓ | ✓ | ✓ (120s) |
+| Order | Check |
+|------:|-------|
+| 1 | Syntax |
+| 2 | Imports |
+| 3 | Test gate (if prior checks pass) |Also applies to: 59-72
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/concepts/verification.mdx` around lines 8 - 9, The doc
incorrectly states checks are selected by blast radius; update the "Verification
Engine" documentation to state that VerificationEngine always initializes and
runs all three checks (syntax, medium, test gate) sequentially, short-circuiting
on the first failure, rather than skipping checks by blast level; specifically
replace any wording that says checks are chosen by blast radius or that the test
gate runs only for high/critical with a clear description of the current
implementation (VerificationEngine initializes all checks and executes them in
order), and optionally add a note that blast-level-based skipping is a
planned/possible enhancement if desired.
| 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 | ||
| ``` |
There was a problem hiding this comment.
Documented YAML schema does not match the currently implemented config loader.
The examples/documentation describe nested keys (analyzers.*, verification.*, autofix.*, output.*), but refactron/core/config.py currently accepts flat RefactronConfig fields and constructs via cls(**config_dict). Unknown keys will trigger ConfigError (via TypeError) in from_file (refactron/core/config.py:153-177). As written, users copying this page will provide invalid config and fail at load time.
💡 Proposed direction for a corrected top-level example (aligned to current loader shape)
- version: 1
- analyzers:
- complexity:
- enabled: true
- threshold: 10
- verification:
- timeout_seconds: 45
- autofix:
- dry_run: false
- output:
- format: terminal
+ version: "1"
+ enabled_analyzers:
+ - complexity
+ - code_smells
+ - security
+ - dependency
+ - dead_code
+ - type_hints
+ - performance
+ max_function_complexity: 10
+ max_function_length: 50
+ report_format: text
+ require_preview: true
+ backup_enabled: trueAlso applies to: 55-257
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/configuration.mdx` around lines 8 - 49, The docs show nested
config sections (analyzers.*, verification.*, autofix.*, output.*) but the
loader expects flat fields passed into RefactronConfig via
RefactronConfig.from_file (refactron/core/config.py), causing
TypeError/ConfigError; fix by updating this example YAML to the flat top-level
shape that RefactronConfig expects (use the exact field names from the
RefactronConfig dataclass) or alternatively modify RefactronConfig.from_file to
deep-merge and normalize nested sections into the flat dict before calling
cls(**config_dict); reference RefactronConfig and from_file to locate the code
to change.
| ## Prerequisites | ||
|
|
||
| - **Node.js 18+** | ||
| - **Git** (optional but recommended — enables temporal analysis and blast radius) |
There was a problem hiding this comment.
Prerequisite note overstates Git’s role for blast radius.
Line 9 says Git enables temporal analysis and blast radius. Blast radius is described elsewhere as structural analysis (imports/calls/tests), while Git history is for temporal signals. Please remove “blast radius” from this prerequisite note to avoid conflicting guidance.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs-npm/quickstart.mdx` at line 9, Update the prerequisite sentence in
quickstart.mdx to stop claiming Git enables "blast radius": edit the line that
currently reads "**Git** (optional but recommended — enables temporal analysis
and blast radius)" to remove "and blast radius" so it only states that Git
enables temporal analysis; keep the rest of the phrasing intact to avoid
conflicting guidance about structural (blast radius) analysis being separate.
Summary by CodeRabbit
refactron.yamlwith analyzer settings, verification timeouts, and output controls