Add Mintlify documentation with Maple theme#99
Conversation
- Set up Mintlify docs with Maple theme and emerald color scheme - Added comprehensive documentation pages for all features - Configured Space Grotesk font for modern typography - Added 8-step workflow guide (login -> init -> repo -> analyze -> suggest -> refactor -> report -> rollback) - Created API reference, CLI reference, guides, and advanced topics - Added social media links (GitHub, X, LinkedIn, Discord) - Migrated content from existing documentation to MDX format
github-actions
bot
added
bug
📝 WalkthroughWalkthroughComprehensive documentation expansion for Refactron across user guides, API references, and internal documentation. Adds getting started materials, configuration guides, feature documentation, CLI and API references, and architectural documentation. Removes legacy configuration files and static homepage. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 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
This pull request adds comprehensive Mintlify documentation with a Maple theme for Refactron. The PR migrates existing documentation from the documentation/docs/ directory into a new Mintlify-based documentation system with improved navigation, modern UI components (accordions, card groups, tabs), and an emerald color scheme with Space Grotesk typography.
Changes:
- Set up Mintlify documentation framework with Maple theme configuration
- Created complete documentation structure with Getting Started, Essentials, Guides, CLI Reference, API Reference, Advanced, and Resources sections
- Migrated and reformatted content from existing Markdown files to MDX format
- Added interactive documentation components (accordions, cards, code groups)
- Configured social media links and contextual AI integration options
Reviewed changes
Copilot reviewed 40 out of 55 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
docs/docs.json |
Mintlify configuration with theme, colors, navigation structure, and social links |
docs/introduction.mdx |
Main landing page with feature overview and navigation cards |
docs/quickstart.mdx |
Quick start guide with 8-step workflow and code examples |
docs/essentials/*.mdx |
Installation, configuration, and authentication guides |
docs/guides/*.mdx |
Comprehensive guides for code analysis, refactoring, AI features, and pattern learning |
docs/cli/commands.mdx |
Complete CLI command reference with examples |
docs/api-reference/*.mdx |
Python API documentation and class references |
docs/advanced/*.mdx |
Advanced topics: performance, monitoring, CI/CD integration |
docs/resources/*.mdx |
FAQ and changelog |
documentation/docs/*.md |
Migrated release notes, changelogs, and technical documentation |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Dependency, Dead Code, Type Hints | ||
| - Extract Method, Performance | ||
|
|
||
| **Refactorers** (6 total ): |
There was a problem hiding this comment.
Extra spaces in changelog: "refactorers (6 total ):" has double spaces before the closing parenthesis. Should be "refactorers (6 total):"
| **Refactorers** (6 total ): | |
| **Refactorers** (6 total): |
|
|
||
| --- | ||
|
|
||
| ### detect_project_root () |
There was a problem hiding this comment.
Typo in method name: "detect_project_root ()" has an extra space before the parentheses. Should be "detect_project_root()"
| ### detect_project_root () | |
| ### detect_project_root() |
|
|
||
| # Refactoring workflow | ||
| refactron refactor myfile.py --preview | ||
| ref actron refactor myfile.py --type extract_constant |
There was a problem hiding this comment.
Typo in command: "ref actron" should be "refactron"
| ref actron refactor myfile.py --type extract_constant | |
| refactron refactor myfile.py --type extract_constant |
| refactron report myproject/ --format json -o report.json | ||
|
|
||
| # HTML report | ||
| refactron report my project/ --format html -o report.html |
There was a problem hiding this comment.
Spacing issue: missing space between "my" and "project/" - should be "refactron report myproject/" not "refactron report my project/"
| refactron report my project/ --format html -o report.html | |
| refactron report myproject/ --format html -o report.html |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
documentation/docs/PATTERN_LEARNING.md (2)
480-489:⚠️ Potential issue | 🟡 Minor
batch_learnexample passes wrong argument type.Per the API reference in
patterns.md,batch_learnexpectsList[Tuple[RefactoringOperation, RefactoringFeedback]], but this example passes the raw output ofstorage.load_feedback(), which returnsList[RefactoringFeedback]. This will confuse users.Suggested fix
-# Load pending feedback -feedback_list = storage.load_feedback() - -# Batch learn -learner.batch_learn(feedback_list) +# Build (operation, feedback) tuples for batch learning +feedback_list = [ + (operation, feedback) + for operation, feedback in zip(operations, feedbacks) +] +learner.batch_learn(feedback_list)
540-558:⚠️ Potential issue | 🟡 MinorGitHub Actions example uses outdated action versions (
v2).
actions/checkoutandactions/setup-pythonare at v4. Using v2 in documentation examples can lead users to adopt deprecated versions.Suggested fix
- - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: actions/setup-python@v2 + uses: actions/setup-python@v4
🤖 Fix all issues with AI agents
In `@docs/api-reference/overview.mdx`:
- Around line 233-245: The example implements the wrong analyzer method and
signature: replace MyCustomAnalyzer.analyze_file with the required BaseAnalyzer
method analyze and match its types (analyze(self, file_path: Path, source_code:
str) -> List[CodeIssue]) so the framework recognizes your analyzer; update the
example to import or reference Path and CodeIssue types and ensure the return is
a List[CodeIssue], then keep the usage
(refactron.analyzers.append(MyCustomAnalyzer())) the same.
In `@docs/essentials/authentication.mdx`:
- Around line 143-149: Update the inaccurate security claim in the
Authentication docs: change the sentence that says "Tokens are stored securely
in your system keychain" to accurately describe how credentials are currently
persisted (plain file under ~/.refactron/ with 0600 permissions as implemented
in refactron.core.credentials) and add a note that OS keychain integration is a
planned future enhancement; ensure the revised text references the current
storage location and permission model and removes the incorrect keychain
assertion.
In `@docs/guides/ai-features.mdx`:
- Around line 220-227: Replace the literal api_key entry in the YAML example in
docs/guides/ai-features.mdx with an environment-variable reference (follow the
same Groq pattern used elsewhere) so users are guided to set the key via env
vars instead of committing secrets; update the llm block (the `provider:
custom`, `endpoint`, and `api_key` example) to show something like referencing
an env var name (e.g., REFRACTRON_LLM_API_KEY) and add a short note telling
readers to set that env var in their environment or CI.
In `@documentation/docs/api/analyzers.md`:
- Around line 40-41: The docs show CPython-internal types (pathlib._local.Path)
in analyzer method signatures; update the documentation generator to normalize
private module class names to their public equivalents so signatures use
pathlib.Path. Specifically, modify the generator logic that formats type
annotations (affecting BaseAnalyzer.analyze, BaseAnalyzer.parse_astroid, and the
same methods on CodeSmellAnalyzer, ComplexityAnalyzer, DeadCodeAnalyzer,
DependencyAnalyzer, PerformanceAnalyzer, SecurityAnalyzer, and TypeHintAnalyzer)
to replace occurrences of "pathlib._local.Path" with "pathlib.Path" (and apply
the same normalization for other private-to-public mappings across
refactorers.md, patterns.md, core.md, cicd.md, and autofix.md). Ensure the
normalization runs before rendering so all 16 occurrences in analyzers.md (and
similar occurrences in other docs) are corrected.
In `@documentation/docs/CODE_OF_CONDUCT.md`:
- Around line 61-63: Replace the placeholder "[INSERT CONTACT EMAIL]" in
CODE_OF_CONDUCT.md with the project's actual reporting address (for example
"conduct@refactron.dev" or the designated maintainer contact) so the enforcement
stanza is actionable; search for the literal string "[INSERT CONTACT EMAIL]" in
the document and update it to the final contact email used for incident reports.
🟡 Minor comments (21)
documentation/docs/CLI_REFERENCE.md-401-421 (1)
401-421:⚠️ Potential issue | 🟡 MinorContradictory default host for
serve-metrics.Line 411 example comment says
# Start on 0.0.0.0:9090but Line 416-417 describes the default as127.0.0.1 for localhost-only. One of these is wrong — please verify and correct.This matters for security:
0.0.0.0binds to all interfaces (network-exposed), while127.0.0.1is localhost-only.docs/resources/changelog.mdx-132-132 (1)
132-132:⚠️ Potential issue | 🟡 MinorTypo: extra whitespace in
(6 total ).There are two extra spaces before the closing parenthesis.
✏️ Fix
-**Refactorers** (6 total ): +**Refactorers** (6 total):documentation/docs/CHANGELOG.md-356-361 (1)
356-361:⚠️ Potential issue | 🟡 MinorPlaceholder GitHub URLs need to be updated.
Lines 358 and 361 reference
https://github.com/yourusername/refactronwhich is a template placeholder. These should point to the actual repository.✏️ Fix
-- [GitHub Repository](https://github.com/yourusername/refactron) +- [GitHub Repository](https://github.com/Refactron-ai/Refactron_lib) - [Documentation](README.md) - [Contributing Guide](CONTRIBUTING.md) -- [Issue Tracker](https://github.com/yourusername/refactron/issues) +- [Issue Tracker](https://github.com/Refactron-ai/Refactron_lib/issues)documentation/docs/CHANGELOG.md-313-320 (1)
313-320:⚠️ Potential issue | 🟡 MinorVersion History table is missing recent versions.
The table only lists versions up to 1.0.1, omitting 1.0.13, 1.0.14, and 1.0.15 which are all documented above. This is inconsistent with the
docs/resources/changelog.mdxwhich includes all versions in its summary table.✏️ Add missing entries
| Version | Date | Status | Highlights | |---------|------|--------|------------| +| 1.0.15 | 2026-02-08 | **Stable** | AI/LLM integration, RAG system | +| 1.0.14 | 2026-01-30 | **Stable** | CLI improvements | +| 1.0.13 | 2026-01-30 | **Stable** | Pattern learning, performance | | 1.0.1 | 2025-12-28 | **Stable** | Expanded analyzers, false positive reduction, performance analyzer, improved test coverage |docs/api-reference/refactron-class.mdx-222-222 (1)
222-222:⚠️ Potential issue | 🟡 MinorExtraneous space in method heading.
### detect_project_root ()has a space before the parentheses. Should be### detect_project_root().Proposed fix
-### detect_project_root () +### detect_project_root()docs/api-reference/refactron-class.mdx-106-108 (1)
106-108:⚠️ Potential issue | 🟡 MinorExample references non-existent
RefactorResultattributes.Based on the API reference in
documentation/docs/api/core.md,RefactorResulthasapplied(bool) andoperationsbut nosuccessorbackup_pathattributes. This example will mislead users.Proposed fix
-if result.success: - print(f"Applied {len(result.operations)} refactorings") - print(f"Backup: {result.backup_path}") +if result.applied: + print(f"Applied {len(result.operations)} refactorings")documentation/docs/TUTORIAL.md-18-18 (1)
18-18:⚠️ Potential issue | 🟡 MinorBroken link fragment — anchor mismatch with heading.
The link
[AI-Powered Features (v1.0.15)](#ai-powered-features)won't resolve because the heading on Line 226 (## AI-Powered Features (v1.0.15)) generates an anchor like#ai-powered-features-v1015. Update the fragment to match, or simplify the heading to## AI-Powered Featuresso the anchor matches.Proposed fix (option A: fix the link)
-6. [AI-Powered Features (v1.0.15)](`#ai-powered-features`) +6. [AI-Powered Features (v1.0.15)](`#ai-powered-features-v1015`)Proposed fix (option B: simplify the heading)
-## AI-Powered Features (v1.0.15) +## AI-Powered Featuresdocumentation/docs/LLM_RAG_INTEGRATION.md-80-84 (1)
80-84:⚠️ Potential issue | 🟡 MinorDocumentation generation command is inconsistent with other docs.
This page uses
refactron docs generate myfile.py(line 81), butQUICK_REFERENCE.mddocuments it asrefactron document <path>, and the detailed changelog lists it under therefactor.pymodule asdocument. Please align on the canonical command name.documentation/docs/api/patterns.md-403-403 (1)
403-403:⚠️ Potential issue | 🟡 Minor
pathlib._local.Pathis an internal CPython type; usepathlib.Pathin public docs.Throughout this file (e.g., lines 403, 411, 475, 483, 638, 646, 695, 709, etc.), type signatures reference
pathlib._local.Path. This is a CPython implementation detail (introduced when pathlib internals were reorganized) and not the public API users should reference. The documented type should bepathlib.Path.Example fix (apply to all occurrences)
-ProjectPatternProfile(project_id: str, project_path: pathlib._local.Path, ... +ProjectPatternProfile(project_id: str, project_path: pathlib.Path, ...documentation/docs/QUICK_REFERENCE.md-43-44 (1)
43-44:⚠️ Potential issue | 🟡 MinorQUICK_REFERENCE.md uses incorrect CI/CD command name.
Line 44 documents the command as
refactron ci <github|gitlab|pre-commit>, but the authoritative CLI_REFERENCE.md (lines 176-187) specifies the actual command asrefactron generate-cicd {github|gitlab|pre-commit|all}. Update QUICK_REFERENCE.md line 44 to use the correct command namerefactron generate-cicd.docs/advanced/monitoring.mdx-93-99 (1)
93-99:⚠️ Potential issue | 🟡 MinorDefault port inconsistency with CLI reference.
This page states the default port for
serve-metricsis 9090 (Line 94), butdocs/cli/commands.mdx(Line 400) documents the default as 8000. These need to be aligned to avoid user confusion.docs/cli/commands.mdx-512-512 (1)
512-512:⚠️ Potential issue | 🟡 MinorTypo:
ref actronshould berefactron.Proposed fix
-ref actron refactor myfile.py --type extract_constant +refactron refactor myfile.py --type extract_constantdocs/quickstart.mdx-172-183 (1)
172-183:⚠️ Potential issue | 🟡 MinorCode block language mismatch: JSON content labeled as Python.
This tab contains a JSON object but uses the
pythonlanguage identifier. This will produce incorrect syntax highlighting and may confuse readers who expect Python code.Proposed fix
-```python Python API +```json Python API { "files_analyzed": 25,docs/cli/commands.mdx-107-107 (1)
107-107:⚠️ Potential issue | 🟡 MinorTypo: stray space in path
my project/.All other examples in this file use
myproject/without a space. This is likely a typo that would cause a shell argument-splitting issue if copy-pasted without quoting.Proposed fix
-refactron report my project/ --format html -o report.html +refactron report myproject/ --format html -o report.htmldocs/api-reference/overview.mdx-180-188 (1)
180-188:⚠️ Potential issue | 🟡 MinorUpdate class name in documentation to match codebase.
Line 181 documents the class as
Issue, but the actual class inrefactron/core/models.pyis namedCodeIssue. Update the example to use the correct name to prevent users from implementing against outdated documentation.documentation/docs/ARCHITECTURE.md-361-364 (1)
361-364:⚠️ Potential issue | 🟡 MinorUpdate broken documentation links in ARCHITECTURE.md.
The referenced documentation links are incorrect:
docs/api.mddoes not exist; the new API documentation is atdocs/api-reference/overview.mdxCONTRIBUTING.mdandexamples/exist at the repository root, but fromdocumentation/docs/ARCHITECTURE.mdthey require the relative path prefix../../Update lines 362-364 to use correct relative paths or absolute references:
- [API Documentation](../../docs/api-reference/overview.mdx) - [Contributing Guide](../../CONTRIBUTING.md) - [Examples](../../examples/)docs/advanced/monitoring.mdx-143-152 (1)
143-152:⚠️ Potential issue | 🟡 MinorFix
cli/commands.mdxto use flag-based syntax instead of subcommands.The actual CLI implementation (refactron/cli.py lines 1971-2003) uses flag-based syntax (
--enable,--disable,--status), whichmonitoring.mdxcorrectly documents. Updatecli/commands.mdxlines 413-433 to show:
refactron telemetry --status(notrefactron telemetry status)refactron telemetry --enable(notrefactron telemetry enable)refactron telemetry --disable(notrefactron telemetry disable)docs/docs.json-70-83 (1)
70-83:⚠️ Potential issue | 🟡 MinorFix favicon path format and consider separate dark-mode logo.
Two issues:
- Favicon path is missing the leading slash. Per Mintlify documentation, static asset paths should be root-relative (e.g.,
/logo/logo.svg). This is inconsistent with the logo paths that correctly use/logo/logo.png.- Light and dark logos reference the same file. If the logo design doesn't have sufficient contrast on dark backgrounds, provide a separate dark-mode variant.
Proposed fix for path consistency
- "favicon": "logo/logo.svg", + "favicon": "/logo/logo.svg",docs/advanced/ci-cd.mdx-113-123 (1)
113-123:⚠️ Potential issue | 🟡 MinorInvalid code block language identifier for pre-commit config.
Line 113 uses
.pre-commit-config.yamlas the code fence language, which isn't a valid identifier. This should beyamlwith the filename shown separately or as a Mintlify annotation.Proposed fix
-```.pre-commit-config.yaml +```yaml .pre-commit-config.yamldocs/advanced/ci-cd.mdx-57-65 (1)
57-65:⚠️ Potential issue | 🟡 MinorExit code capture pattern is fragile.
The
||pattern on Line 60 meansexit_codeis only set when the command fails; on success,exit_codeis unset and theifon Line 61 would error or behave unexpectedly. A more robust pattern:Proposed fix
- name: Analyze Code run: | - refactron analyze . --log-format json || exit_code=$? - if [ $exit_code -eq 1 ]; then + refactron analyze . --log-format json; exit_code=$? + if [ "$exit_code" -eq 1 ]; then echo "Critical issues found!" exit 1 fidocs/advanced/ci-cd.mdx-41-46 (1)
41-46:⚠️ Potential issue | 🟡 MinorOutdated GitHub Actions versions in example workflows.
The examples reference
actions/checkout@v2,actions/setup-python@v2(Lines 41, 44), andactions/cache@v2(Line 150). These are significantly outdated — current versions are v4, v5, and v4 respectively. Users copying these templates will get deprecation warnings from GitHub.Proposed fix
- - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: '3.9' + python-version: '3.12'And at Line 150:
- - uses: actions/cache@v2 + - uses: actions/cache@v4
🧹 Nitpick comments (15)
documentation/docs/PERFORMANCE_OPTIMIZATION.md (2)
206-206: HTML entity<is unnecessary in a plain Markdown file.In
.mdfiles,<10renders correctly without escaping. The<entity is typically needed in MDX/JSX contexts. Since this is a.mdfile, you can use<10directly.Same applies to Line 291 (
<1000).✏️ Suggested fix
-- ❌ Small codebases (<10 files) +- ❌ Small codebases (<10 files)And at Line 291:
-### For Small Projects (<1000 files) +### For Small Projects (<1000 files)
462-465: Documenting a private method (_cleanup_if_needed) in public-facing docs.Line 464 references
refactron.ast_cache._cleanup_if_needed(), which is a private/internal method. Exposing this in user-facing documentation couples users to an implementation detail that may change without notice.Consider either omitting it or noting it as an internal/advanced API.
documentation/docs/CHANGELOG.md (1)
8-33: Inconsistent heading style for v1.0.15 entry.The v1.0.15 entry uses
### v1.0.15 (2026-02-08)(h3, no brackets) while all other version entries use## [x.y.z] - date(h2, with brackets). This breaks both the visual hierarchy and the Keep a Changelog link-reference convention.Additionally,
### Changedon Line 29 is at the same heading level as### v1.0.15, making it look like a sibling section rather than a subsection.✏️ Suggested fix
-### v1.0.15 (2026-02-08) +## [1.0.15] - 2026-02-08 -#### Added +### Added ... -#### Fixed +### Fixed ... -### Changed +### Changeddocumentation/docs/api/analyzers.md (2)
258-270: Inconsistent type annotation style forDependencyAnalyzer.
DependencyAnalyzeruses string-literal type hint'RefactronConfig'and an explicit-> Nonereturn type on__init__, while every other analyzer uses the fully-qualifiedrefactron.core.config.RefactronConfigwithout-> None. This inconsistency suggests the doc generation pulled from a differently-annotated source.✏️ Normalize to match other analyzers
-DependencyAnalyzer(config: 'RefactronConfig') -> None +DependencyAnalyzer(config: refactron.core.config.RefactronConfig)-DependencyAnalyzer.__init__(self, config: 'RefactronConfig') -> None +DependencyAnalyzer.__init__(self, config: refactron.core.config.RefactronConfig)
7-7: Empty## Functionssections add noise.Every analyzer module section has an empty
## Functionsheading with no content beneath it (Lines 7, 67, 127, 187, 247, 307, 367, 427, 487). Consider removing these empty sections to reduce clutter, or populating them if there are module-level functions to document.documentation/docs/SECURITY.md (1)
113-114: Security audit history may be stale.The audit history table only contains entries from 2024-10-31. Consider updating this to reflect any more recent audits, or adding a note about the audit cadence, to maintain credibility of the security policy.
documentation/docs/api/core.md (2)
37-38: Internal type paths leak into public API docs.Throughout this file, type annotations show
pathlib._local.Pathinstead ofpathlib.Path, andlibcst._nodes.module.Moduleinstead oflibcst.Module. These are CPython implementation details exposed by the doc generator. Consider post-processing the generated output to normalize these to their public type names for readability.This affects many signatures across the file (e.g., Lines 37, 69, 101, 120, 135, 445, 471, etc.).
757-787: Private helper functions exposed in public API documentation.
_normalize_base_urland_post_jsonare prefixed with_, indicating they are private implementation details. Public API documentation should typically exclude these to avoid confusing consumers and creating an implicit contract around internals.documentation/docs/api/autofix.md (1)
265-281: Fixer__init__docs show inherited params that don't match actual constructors.For example,
AddDocstringsFixer()signature shows no parameters, but the__init__docstring describesnameandrisk_scoreparams (inherited fromBaseFixer). This pattern repeats for all 14 fixer classes. Consider having the doc generator suppress inherited parameter docs when the concrete class constructor doesn't accept them, to avoid confusing users.documentation/docs/ARCHITECTURE.md (1)
9-25: Add a language specifier to the fenced code block.The directory tree code block has no language tag, which triggers the MD040 lint rule. Use
```textor```plaintextfor non-code blocks.Proposed fix
-``` +```text refactron/ ├── core/ # Core functionalitydocs/essentials/installation.mdx (1)
39-41: Hardcoded version string will become stale.The example output
refactron, version 1.0.15will need updating with each release. Consider using a placeholder likex.y.zor phrasing it as "You should see output similar to:" (which you already do on Line 37, so just update the version string to be generic).documentation/docs/api/refactorers.md (2)
40-41:pathlib._local.Pathexposes an internal module path in public docs.All refactorer method signatures show
pathlib._local.Path(e.g., Lines 40, 85, 130, 175, 220, 265) instead of the publicpathlib.Path. This is an implementation detail (CPython internals) that will confuse users reading the API reference.If this is auto-generated, consider configuring the doc generator to normalize internal paths to their public aliases. If manually authored, replace all occurrences with
pathlib.Path.
7-8: Empty "Functions" sections add noise.Every module section has an empty
## Functionsblock (Lines 7, 52, 97, 142, 187, 232, 277). If there are no module-level functions, consider removing these empty headings or suppressing them in the doc generator template.docs/guides/pattern-learning.mdx (1)
57-63: Confusingly similar config keys:enable_pattern_learningvspattern_learning_enabled.These two option names (Lines 59-60) are nearly identical and the distinction between "master switch" and "learn from feedback" is subtle. If these mirror the actual config schema, consider adding a brief clarifying note or a table explaining the relationship (e.g., that
pattern_learning_enabledis a sub-switch underenable_pattern_learning).docs/guides/ai-features.mdx (1)
83-89: Hardcoded date in example output looks stale.Line 87 shows
Last updated: 2024-02-15 10:30:42. Consider using a more generic placeholder like2025-01-15or<timestamp>to avoid the example looking outdated.
| ```python | ||
| from refactron.analyzers.base_analyzer import BaseAnalyzer | ||
|
|
||
| class MyCustomAnalyzer(BaseAnalyzer): | ||
| def analyze_file(self, file_path, ast_tree): | ||
| # Custom analysis logic | ||
| issues = [] | ||
| # ... analyze and create issues | ||
| return issues | ||
|
|
||
| # Use with Refactron | ||
| refactron = Refactron() | ||
| refactron.analyzers.append(MyCustomAnalyzer()) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find BaseAnalyzer class definition
echo "=== Finding BaseAnalyzer class definition ==="
find . -type f -name "*.py" | xargs grep -l "class BaseAnalyzer"Repository: Refactron-ai/Refactron_lib
Length of output: 154
🏁 Script executed:
#!/bin/bash
# Check ARCHITECTURE.md around line 85
echo "=== Checking ARCHITECTURE.md ==="
fd "ARCHITECTURE.md" -t f | head -5Repository: Refactron-ai/Refactron_lib
Length of output: 153
🏁 Script executed:
#!/bin/bash
# Search for analyze method in BaseAnalyzer
echo "=== Searching for analyze methods in BaseAnalyzer ==="
rg "def analyze" --type py -A 3 | head -30Repository: Refactron-ai/Refactron_lib
Length of output: 1686
🏁 Script executed:
#!/bin/bash
# Read the BaseAnalyzer class
echo "=== BaseAnalyzer class definition ==="
cat -n ./refactron/analyzers/base_analyzer.pyRepository: Refactron-ai/Refactron_lib
Length of output: 1352
🏁 Script executed:
#!/bin/bash
# Read ARCHITECTURE.md around line 85
echo "=== ARCHITECTURE.md context around line 85 ==="
sed -n '75,95p' ./documentation/docs/ARCHITECTURE.mdRepository: Refactron-ai/Refactron_lib
Length of output: 475
Example code shows incorrect analyze_file method signature.
The example at lines 233-245 shows analyze_file(self, file_path, ast_tree), but the actual BaseAnalyzer interface requires analyze(self, file_path: Path, source_code: str) -> List[CodeIssue]. Users following this example will implement the wrong method name and parameter types, causing their custom analyzers to be ignored at runtime.
🤖 Prompt for AI Agents
In `@docs/api-reference/overview.mdx` around lines 233 - 245, The example
implements the wrong analyzer method and signature: replace
MyCustomAnalyzer.analyze_file with the required BaseAnalyzer method analyze and
match its types (analyze(self, file_path: Path, source_code: str) ->
List[CodeIssue]) so the framework recognizes your analyzer; update the example
to import or reference Path and CodeIssue types and ensure the return is a
List[CodeIssue], then keep the usage
(refactron.analyzers.append(MyCustomAnalyzer())) the same.
| <Info> | ||
| Refactron follows security best practices: | ||
| - Tokens are stored securely in your system keychain | ||
| - API keys are never logged or displayed | ||
| - All communication uses HTTPS | ||
| - Authentication tokens expire after 30 days | ||
| </Info> |
There was a problem hiding this comment.
Inaccurate claim: tokens are NOT stored in system keychain.
The Security section claims "Tokens are stored securely in your system keychain," but per the refactron.core.credentials module documentation, credentials are stored in a plain file under ~/.refactron/ with 0600 permissions, with a note that "OS keychain integration can be added later." This discrepancy could mislead users about their security posture.
Proposed fix
<Info>
Refactron follows security best practices:
- - Tokens are stored securely in your system keychain
+ - Tokens are stored in a user-only readable file (~/.refactron/) with restricted permissions
- API keys are never logged or displayed
- All communication uses HTTPS
- Authentication tokens expire after 30 days
</Info>📝 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.
| <Info> | |
| Refactron follows security best practices: | |
| - Tokens are stored securely in your system keychain | |
| - API keys are never logged or displayed | |
| - All communication uses HTTPS | |
| - Authentication tokens expire after 30 days | |
| </Info> | |
| <Info> | |
| Refactron follows security best practices: | |
| - Tokens are stored in a user-only readable file (~/.refactron/) with restricted permissions | |
| - API keys are never logged or displayed | |
| - All communication uses HTTPS | |
| - Authentication tokens expire after 30 days | |
| </Info> |
🤖 Prompt for AI Agents
In `@docs/essentials/authentication.mdx` around lines 143 - 149, Update the
inaccurate security claim in the Authentication docs: change the sentence that
says "Tokens are stored securely in your system keychain" to accurately describe
how credentials are currently persisted (plain file under ~/.refactron/ with
0600 permissions as implemented in refactron.core.credentials) and add a note
that OS keychain integration is a planned future enhancement; ensure the revised
text references the current storage location and permission model and removes
the incorrect keychain assertion.
| Configure in `.refactron.yaml`: | ||
| ```yaml | ||
| llm: | ||
| provider: custom | ||
| endpoint: https://your-llm-api.com/v1 | ||
| api_key: your-key | ||
| ``` | ||
| </Accordion> |
There was a problem hiding this comment.
API key in YAML config encourages insecure practices.
Line 225 shows api_key: your-key directly in .refactron.yaml. This encourages users to commit secrets to version control. Recommend using an environment variable reference instead, consistent with the Groq setup pattern on Line 42.
Proposed fix
llm:
provider: custom
endpoint: https://your-llm-api.com/v1
- api_key: your-key
+ # Set via environment variable:
+ # export CUSTOM_LLM_API_KEY='your-key'🤖 Prompt for AI Agents
In `@docs/guides/ai-features.mdx` around lines 220 - 227, Replace the literal
api_key entry in the YAML example in docs/guides/ai-features.mdx with an
environment-variable reference (follow the same Groq pattern used elsewhere) so
users are guided to set the key via env vars instead of committing secrets;
update the llm block (the `provider: custom`, `endpoint`, and `api_key` example)
to show something like referencing an env var name (e.g.,
REFRACTRON_LLM_API_KEY) and add a short note telling readers to set that env var
in their environment or CI.
| BaseAnalyzer.analyze(self, file_path: pathlib._local.Path, source_code: str) -> List[refactron.core.models.CodeIssue] | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check how many occurrences of pathlib._local exist in the docs
rg -c 'pathlib\._local' documentation/docs/api/Repository: Refactron-ai/Refactron_lib
Length of output: 289
🏁 Script executed:
# Also check the specific file and lines mentioned
wc -l documentation/docs/api/analyzers.mdRepository: Refactron-ai/Refactron_lib
Length of output: 109
🏁 Script executed:
# View the problematic section around lines 40-41
sed -n '35,50p' documentation/docs/api/analyzers.mdRepository: Refactron-ai/Refactron_lib
Length of output: 450
🏁 Script executed:
# Check if the file has auto-generation markers
head -20 documentation/docs/api/analyzers.mdRepository: Refactron-ai/Refactron_lib
Length of output: 276
🏁 Script executed:
# Sample a few more occurrences to see the pattern across different lines
rg -n 'pathlib\._local' documentation/docs/api/analyzers.md | head -20Repository: Refactron-ai/Refactron_lib
Length of output: 2003
🏁 Script executed:
# Check if there's a docs generation script
find documentation -name "*.py" -o -name "*.sh" | grep -i genRepository: Refactron-ai/Refactron_lib
Length of output: 52
Type signatures expose CPython internal pathlib._local.Path — should be pathlib.Path.
All 16 occurrences in this file reference pathlib._local.Path, which is a CPython implementation detail (introduced in 3.12). User-facing docs should display the public type pathlib.Path. This affects all eight analyzer classes across both their analyze() and parse_astroid() method signatures:
- BaseAnalyzer (lines 40, 55)
- CodeSmellAnalyzer (lines 100, 115)
- ComplexityAnalyzer (lines 160, 175)
- DeadCodeAnalyzer (lines 220, 235)
- DependencyAnalyzer (lines 280, 295)
- PerformanceAnalyzer (lines 340, 355)
- SecurityAnalyzer (lines 400, 415)
- TypeHintAnalyzer (lines 460, 475)
This pattern also occurs across other API documentation files (refactorers.md, patterns.md, core.md, cicd.md, autofix.md). Identify and update the documentation generation source to normalize private module paths to their public equivalents.
✏️ Example fixes
-BaseAnalyzer.analyze(self, file_path: pathlib._local.Path, source_code: str) -> List[refactron.core.models.CodeIssue]
+BaseAnalyzer.analyze(self, file_path: pathlib.Path, source_code: str) -> List[refactron.core.models.CodeIssue]-BaseAnalyzer.parse_astroid(self, source_code: str, file_path: Optional[pathlib._local.Path] = None) -> Any
+BaseAnalyzer.parse_astroid(self, source_code: str, file_path: Optional[pathlib.Path] = None) -> Any📝 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.
| BaseAnalyzer.analyze(self, file_path: pathlib._local.Path, source_code: str) -> List[refactron.core.models.CodeIssue] | |
| ``` | |
| BaseAnalyzer.analyze(self, file_path: pathlib.Path, source_code: str) -> List[refactron.core.models.CodeIssue] |
🤖 Prompt for AI Agents
In `@documentation/docs/api/analyzers.md` around lines 40 - 41, The docs show
CPython-internal types (pathlib._local.Path) in analyzer method signatures;
update the documentation generator to normalize private module class names to
their public equivalents so signatures use pathlib.Path. Specifically, modify
the generator logic that formats type annotations (affecting
BaseAnalyzer.analyze, BaseAnalyzer.parse_astroid, and the same methods on
CodeSmellAnalyzer, ComplexityAnalyzer, DeadCodeAnalyzer, DependencyAnalyzer,
PerformanceAnalyzer, SecurityAnalyzer, and TypeHintAnalyzer) to replace
occurrences of "pathlib._local.Path" with "pathlib.Path" (and apply the same
normalization for other private-to-public mappings across refactorers.md,
patterns.md, core.md, cicd.md, and autofix.md). Ensure the normalization runs
before rendering so all 16 occurrences in analyzers.md (and similar occurrences
in other docs) are corrected.
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported to the community leaders responsible for enforcement at | ||
| [INSERT CONTACT EMAIL]. |
There was a problem hiding this comment.
Placeholder [INSERT CONTACT EMAIL] must be replaced with an actual contact address.
The enforcement section is not actionable without a real email for reporting incidents. Replace [INSERT CONTACT EMAIL] with the project's designated contact (e.g., conduct@refactron.dev or a maintainer's email).
✏️ Example fix
reported to the community leaders responsible for enforcement at
-[INSERT CONTACT EMAIL].
+conduct@refactron.dev.📝 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.
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | |
| reported to the community leaders responsible for enforcement at | |
| [INSERT CONTACT EMAIL]. | |
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | |
| reported to the community leaders responsible for enforcement at | |
| conduct@refactron.dev. |
🤖 Prompt for AI Agents
In `@documentation/docs/CODE_OF_CONDUCT.md` around lines 61 - 63, Replace the
placeholder "[INSERT CONTACT EMAIL]" in CODE_OF_CONDUCT.md with the project's
actual reporting address (for example "conduct@refactron.dev" or the designated
maintainer contact) so the enforcement stanza is actionable; search for the
literal string "[INSERT CONTACT EMAIL]" in the document and update it to the
final contact email used for incident reports.
Pull Request
📋 Description
A clear and concise description of what this PR does.
🔗 Related Issue
Closes #(issue number)
🧪 Type of Change
🧪 Testing
📝 Changes Made
🎯 Code Quality
📚 Documentation
🔒 Security
🚀 Performance
📋 Checklist
🎨 Screenshots (if applicable)
Add screenshots to help explain your changes.
📋 Additional Notes
Add any other context about the PR here.
🔍 Reviewers
@omsherikar - Please review this PR
🏷️ Labels
Please add appropriate labels to this PR:
bug- Bug fixenhancement- New featuredocumentation- Documentation updatedependencies- Dependency updatesecurity- Security updateperformance- Performance improvementrefactoring- Code refactoringtesting- Test updatesbreaking-change- Breaking changegood-first-issue- Good for new contributorshelp-wanted- Help neededpriority-high- High prioritypriority-medium- Medium prioritypriority-low- Low prioritySummary by CodeRabbit