refactrail 0.3.1a0__tar.gz

refactrail-0.3.1a0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: Local-contract checks
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+jobs:
+  python:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade pip
+      # Test against FuncLoom's current main branch from its public
+      # repository (a FUNCLOOM_READ_TOKEN secret is used only if one exists).
+      - uses: actions/checkout@v4
+        with:
+          repository: SAMtheROCKET/funcloom
+          path: funcloom-src
+          token: ${{ secrets.FUNCLOOM_READ_TOKEN || github.token }}
+      - run: python -m pip install ./funcloom-src
+      # refactrail-core is a dependency; before publication the local
+      # pure-Python fallback wheel satisfies it (Python engine).
+      - run: python -m pip install ./rust/fallback
+      - run: python -m pip install -e ".[release]"
+      - run: python -m unittest discover -s tests
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+  editor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: node --test editor/refactrail/test/runner.test.js editor/refactrail/test/setup.test.js
+  rust:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: cargo test --locked -p refactrail-lexer -p refactrail-parser -p refactrail-engine -p refactrail-cli
+        working-directory: rust

refactrail-0.3.1a0/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## Unreleased
+
+- Easy installation: `pip install refactrail` now also installs the Rust
+  engine (refactrail-core). Native wheels cover Windows x86_64, macOS arm64
+  and x86_64, and Linux x86_64 and ARM64 (glibc and musl); every other
+  system gets a pure-Python fallback wheel, so installation never needs
+  Rust. refactrail-core no longer depends back on refactrail.
+- `refactrail` without arguments shows a short quick start.
+- VS Code: the extension uses the interpreter selected in the Python
+  extension when `refactrail.pythonPath` is empty (the new default), and
+  offers one-click Install/Update when RefacTrail is missing or outdated.
+- pre-commit hooks: refactrail-lint, refactrail-format,
+  refactrail-format-check and refactrail-check.
+- Identifier parity with CPython in the Rust engine: NFKC normalization
+  of non-ASCII names (`file` is `file`), and CPython's rejection of
+  characters that cannot appear in names (`a = €`, `x² = 1`,
+  U+00A0 inside a name) with its exact messages and columns. Previously
+  such files were accepted or reported differently.
+- `refactrail lint` and `refactrail format` take `--engine
+  auto|python|rust`; the Rust engine lints and formats through
+  refactrail-core with byte-identical output (31/31 recorded runs).
+- Native `refactrail-native lint` refuses notebooks like the Python CLI.
+- Rust third-party license bundle regenerated from the locked dependency
+  graph (`scripts/gen_third_party_licenses.py`); it no longer lists the
+  removed Ruff crates.
+- Package metadata: RefacTrail is described as the Python refactorizer,
+  with keywords and family links to FuncLoom.
+
+## 0.3.1a0 - statement layout and rule fixes, local candidate, 2026-10-02
+
+- Formatter: new whole-statement layout engine. Over-long statements are
+  joined and split again inside existing brackets (right-hand split,
+  left-hand for definition headers, fewest lines), with delimiter
+  priorities for comprehensions, commas, conditionals, boolean,
+  string-concatenation, comparison and arithmetic splits. Long
+  `from ... import` lines gain parentheses; continuation lines are
+  re-packed. `--bracket-style own-line|hug` (editor: `refactrail.bracketStyle`).
+  Spacing re-runs after layout so one run is idempotent (found on
+  `http/server.py`). AST and literal-token validation still guard writes.
+- Rules (contract 3, both engines): module-level type aliases (`type X =`,
+  `X: TypeAlias =`, PascalCase `X = tuple[...]`) are no longer reported as
+  misnamed variables, as code before constants, or as import-time code.
+  14 verbs added to the shared verb list.
+- RC2 scope evidence: a name such as `locals` that is only assigned (for
+  example a dataclass field) no longer disables RC201/RC202 for the file.
+- Caches key on a fingerprint of RefacTrail's own code and word lists, not
+  only its version, so engine changes never reuse stale results.
+- refactrail-core is versioned with RefacTrail (0.3.1a0, contract 3); the
+  previous pins required refactrail 0.1.1a0 and could not be installed.
+- Editor: automated extension-host workflow test covering every command.
+
+## 0.3.0a0 - resumed independent engines, 2026-10-01
+
+- Add compiler-backed partial scope evidence, RC201 unresolved-name checks and
+  RC202 imports without lexical use; retain explicit unknowns and type comments.
+- Add independent bracket-group wrapping and byte-local Python notebook source
+  edits; preserve outputs, metadata, directives, literals and original endings.
+- Discover Python stubs and optionally notebook containers.
+- Add project symbol/import inventories and possible transitive impact queries,
+  including cycles, stubs, re-exports and explicitly changed deleted modules.
+- Add bounded local-variable rename review proposals with original source hashes,
+  collision/reflection/scope refusals and structural validation; no rename apply.
+- Add source/configuration/version-aware RC caching and parallel snapshot checks.
+- Add editor scope, project index and rename commands and notebook formatting.
+- Preserve the native RT contract and one-way FuncLoom dependency. Publication
+  remains held; this does not establish universal feature or speed superiority.
+
+## 0.2.0a0 - independent engine increment, 2026-10-01
+
+- Add `lint`: seven independent correctness checks, separate from the RT
+  style profiles. Diagnose mutable defaults, duplicate literal keys,
+  identity/literal comparisons, bare except, directly unreachable code,
+  tuple assertions and control-flow exits from finally.
+- Add `format`: independent bounded whitespace proposals, check/diff modes
+  and explicit hash-checked atomic writes. Preserve literal/comment tokens,
+  directives, BOM and original line endings; validate compilation and ASTs.
+- Add SARIF 2.1.0 reporting for `lint` and `check`; keep statistics on stderr
+  so JSON/SARIF stdout remains parseable.
+- Add public correctness/formatting APIs, examples and editor commands.
+- Keep the existing RT native contract unchanged. New engines use CPython
+  AST/tokenize and do not invoke Ruff, Black or an LLM. Native RT parsing
+  still uses the previously documented Ruff parser crates.
+- Document the larger independent-engine roadmap and current limitations.
+  This is an experimental increment, not complete formatter parity or a
+  demonstrated replacement for every existing refactoring tool.
+
+## 0.1.1a0 - local candidate, 2026-10-01
+
+- Validate compilation in both engines without executing source.
+- Honor suppression comments only outside strings; retain parse errors.
+- Add strict return and parameter suffix checks (RT206, RT207).
+- Avoid assuming rich comparisons return bool.
+- Validate configurations and ignore damaged caches.
+- Reject linked sources; check source hashes before atomic fix writes.
+- Skip return-annotation edits on decorated functions.
+- Add a native rule-contract compatibility check and interpreter cache key.
+- Add a local VS Code extension, CI configuration and release checks.
+- Keep FuncLoom as the one-way rewrite dependency; publish nothing.

refactrail-0.3.1a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sambit Supriya Dash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

refactrail-0.3.1a0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE pyproject.toml CHANGELOG.md
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include scripts *.py
+recursive-include editor *.js *.json *.md LICENSE
+include .github/workflows/ci.yml
+prune reports
+prune dist
+prune .venv
+prune rust
+global-exclude *.py[cod]
+exclude AGENTS.md

refactrail-0.3.1a0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: refactrail
+Version: 0.3.1a0
+Summary: The Python refactorizer: linter, formatter and verified refactoring with independent pure-Python and Rust engines
+Author: Sambit Supriya Dash
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SAMtheROCKET/refactrail
+Project-URL: Repository, https://github.com/SAMtheROCKET/refactrail
+Project-URL: Issues, https://github.com/SAMtheROCKET/refactrail/issues
+Keywords: python,refactorizer,linter,formatter,refactoring,static-analysis,code-quality,python-linter,code-formatter,sarif,rust,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: funcloom<0.11,>=0.10.2a0
+Requires-Dist: refactrail-core==0.3.1a0
+Provides-Extra: fast
+Provides-Extra: release
+Requires-Dist: build<2,>=1.2; extra == "release"
+Requires-Dist: setuptools>=77; extra == "release"
+Requires-Dist: twine<7,>=6; extra == "release"
+Dynamic: license-file
+
+# RefacTrail
+
+**The Python refactorizer.** A linter, formatter and verified refactoring
+tool with two independent engines, pure Python and Rust, built on its own
+parser. Run correctness checks and bounded formatting, or check structure,
+naming, types and documentation against a chosen profile.
+
+Part of a family of standalone Python tools: [FuncLoom](https://github.com/SAMtheROCKET/funcloom) (functionizer), [RefacTrail](https://github.com/SAMtheROCKET/refactrail) (refactorizer) and RepoContour (architect, planned). Each installs and works on its own.
+
+**0.3.1a0 is an unpublished experimental alpha.** Python 3.12 or newer is
+required. RefacTrail has its own package, CLI and VS Code extension. It
+installs FuncLoom automatically for its rewrite API; FuncLoom has no
+dependency on RefacTrail. No LLM, account or network is needed at runtime.
+
+## Quick start
+
+```bash
+pip install refactrail
+```
+
+That one command also installs FuncLoom and the fast Rust engine (a native
+wheel for Windows, macOS and Linux; on other systems a small fallback is
+installed and the Python engine gives the same results, so nothing ever
+needs compiling). Python 3.12 or newer is required. Until the first PyPI
+release, install from GitHub instead:
+`pip install git+https://github.com/SAMtheROCKET/refactrail.git`.
+
+Then, in any project folder:
+
+```bash
+refactrail                     # the most useful commands
+refactrail lint                # find likely bugs
+refactrail format --diff       # preview formatting; --write applies it
+refactrail check               # structure, naming, type hints, docstrings
+refactrail fix --diff          # preview safe fixes; drop --diff to apply
+```
+
+Paths default to the current folder; pass files or folders to narrow it.
+Exit codes are 0 (clean), 1 (findings) and 2 (error), ready for CI. If your
+system blocks the `refactrail` command, use `python -m refactrail`.
+
+**In VS Code**, install the RefacTrail extension and run *RefacTrail: ...*
+from the Command Palette. It uses the Python interpreter selected in VS Code
+and offers to install RefacTrail there with one click.
+
+**On every commit**, add the hooks to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/SAMtheROCKET/refactrail
+    rev: v0.3.1a0
+    hooks:
+      - id: refactrail-lint
+      - id: refactrail-format
+```
+
+`refactrail-format-check` (fails instead of rewriting) and
+`refactrail-check` are also available.
+
+### From source (development)
+
+Install FuncLoom from its source folder and the local engine fallback
+first, then RefacTrail:
+
+```bash
+python -m pip install -e ../funcloom ./rust/fallback
+python -m pip install -e .
+```
+
+Nothing is uploaded by these local tools.
+
+## General correctness and independent formatting
+
+```powershell
+python -m refactrail lint src
+python -m refactrail lint src --output-format sarif
+python -m refactrail format examples/general_demo.py --diff
+python -m refactrail format examples/general_demo.py --check
+python -m refactrail format examples/general_demo.py --write
+```
+
+`lint` provides nine RC correctness checks without imposing personal naming
+rules. `format` uses an independent CPython AST/tokenize implementation; its
+default is a read-only preview. It makes bounded whitespace edits and retains
+literal/comment spelling, directives, BOM and original line endings.
+Use `--line-length 79` for bracketed comma-group wrapping. Explicit Python
+notebooks and discovered stubs are supported; `--notebooks` includes notebooks
+in folder formatting. This is a documented style subset, not full Black parity.
+
+```powershell
+python -m refactrail format examples/analysis.ipynb --line-length 79 --diff
+python -m refactrail scope examples/project_demo/invoice.py
+python -m refactrail index examples/project_demo --changed invoice.py
+python -m refactrail rename examples/project_demo/invoice.py --function calculate_total --old amount --new base_amount_int
+```
+
+`scope` exposes partial compiler binding evidence. `index` inventories symbols
+and possible import impact under an explicit import root. `rename` produces a
+read-only, hash-linked proposal for a bounded local-variable subset; parameters,
+public APIs, nested scopes and dynamic namespaces are refused. See
+[the workflow and examples](docs/EXPANSION_USAGE.md).
+
+`lint --jobs 4` enables worker processes on larger batches. Lint caching hashes
+source bytes, rule selection, tool/interpreter version and path-sensitive policy;
+use `--no-cache` to disable it. No cache is used to authorize source changes.
+
+See [the independent engines](docs/INDEPENDENT_ENGINES.md) for contracts,
+APIs and limitations, and [the expansion roadmap](docs/EXPANSION_ROADMAP.md)
+for broader formatter, data-flow and repository-refactoring work. These
+engines do not invoke or contain Ruff or Black. The FuncLoom
+structural-rewrite dependency remains as documented below.
+
+## Checking and fixing
+
+`check` reports line, function and main-block sizes; docstrings and their
+sections; missing annotations; naming conventions and verb prefixes;
+constants and their location; and top-level script execution. The strict
+profile adds generic-name and dtype-suffix checks. Defaults are 79 columns,
+40 preferred / 50 maximum function lines, and 100 main-block lines.
+
+```powershell
+python -m refactrail check src --profile strict --statistics
+python -m refactrail check src --output-format json
+python -m refactrail rules
+python -m refactrail fix src --diff
+python -m refactrail fix src
+```
+
+`fix --diff` previews edits without writing. `fix` edits files in place:
+selected fixes add eligible `-> None` annotations, create function docstring
+skeletons, wrap supported lines and split supported long functions. It
+checks compilation, rejects linked files and changed source, and replaces
+each file atomically. Review diffs and run your project's tests. A failed
+file does not roll back other files in a multi-file run.
+
+These are structural checks, not proof of unchanged behavior. Annotations
+and docstrings can affect reflection. There is no automatic domain naming,
+public-API renaming, inferred annotation insertion beyond the bounded None
+case, or arbitrary repository restructuring. Missing meanings need user
+context. Unsupported functions can remain long. Use FuncLoom's explicit
+`modularize` command to create a separate package draft.
+
+Exit codes: check returns 0 with no findings, 1 for findings, 2 for usage
+errors. `--exit-zero` explicitly overrides finding failures. Diff returns 1
+when edits are proposed or files are skipped; fix returns 1 for skipped
+files. Syntax, encoding and internal errors cannot be hidden by selection
+or ignore lists. Suppression markers apply only inside real comment tokens.
+
+## Configuration
+
+```toml
+[tool.refactrail]
+profile = "strict"
+line-length = 79
+function-preferred-lines = 40
+function-max-lines = 50
+main-max-lines = 100
+select = ["RT"]
+ignore = []
+```
+
+Widths must be 40-200; the preferred function size cannot exceed the maximum.
+See [the rule contract](docs/RULES.md) and [design](docs/DESIGN.md).
+
+## The Rust engine
+
+`--engine auto` selects a compatible `refactrail-core` when installed and
+otherwise uses Python. `--engine python` selects the reference implementation.
+The native core is a separate PyO3/Rayon distribution built on
+RefacTrail's own Rust lexer, parser, compile checks and symbol table; it
+contains no Ruff code. `check`, `lint` and `format` accept `--engine`, and
+the standalone `refactrail-native` binary runs `check`, `lint`, `scope`,
+`format` and `index` without Python. Outputs are byte-identical to the
+Python engine on the recorded corpora and fuzzed inputs, with CPython as the
+oracle; see [the dual-engine record](docs/DUAL_ENGINES.md). Parity evidence
+is not a guarantee for every Python program.
+
+Native wheels (CPython 3.12+ ABI3) are built and tested in CI for Linux
+x86_64 (manylinux2014), Windows x86_64 and macOS arm64; other platforms use
+the Python engine. Install a local wheel with
+`pip install --no-index --no-deps WHEEL`. See
+[benchmark evidence](docs/BENCHMARKS.md) for measured timings and their
+limits.
+
+## Editor and release preparation
+
+[The VS Code extension](editor/refactrail/README.md) provides explicit check,
+diff-preview and fix commands. Install its local VSIX, select the Python
+environment containing these packages, and use a trusted workspace.
+
+```powershell
+python scripts/verify.py
+python scripts/release_check.py --output dist/0.3.1a0 --dependency-wheel path/to/funcloom-0.10.3a0-py3-none-any.whl
+```
+
+The release script builds and checks a wheel and source archive, installs
+both in fresh environments, tests installed code and checks uninstallation.
+CI runs the tests on Windows, Linux and macOS with Python 3.12-3.14, and
+the Release check workflow verifies the identical built files on all three
+systems. [Release preparation](docs/RELEASE_PREPARATION.md) lists the
+remaining launch work. No public release has been made.
+
+[MIT](LICENSE), copyright 2026 Sambit Supriya Dash.

refactrail-0.3.1a0/README.md

@@ -0,0 +1,203 @@
+# RefacTrail
+
+**The Python refactorizer.** A linter, formatter and verified refactoring
+tool with two independent engines, pure Python and Rust, built on its own
+parser. Run correctness checks and bounded formatting, or check structure,
+naming, types and documentation against a chosen profile.
+
+Part of a family of standalone Python tools: [FuncLoom](https://github.com/SAMtheROCKET/funcloom) (functionizer), [RefacTrail](https://github.com/SAMtheROCKET/refactrail) (refactorizer) and RepoContour (architect, planned). Each installs and works on its own.
+
+**0.3.1a0 is an unpublished experimental alpha.** Python 3.12 or newer is
+required. RefacTrail has its own package, CLI and VS Code extension. It
+installs FuncLoom automatically for its rewrite API; FuncLoom has no
+dependency on RefacTrail. No LLM, account or network is needed at runtime.
+
+## Quick start
+
+```bash
+pip install refactrail
+```
+
+That one command also installs FuncLoom and the fast Rust engine (a native
+wheel for Windows, macOS and Linux; on other systems a small fallback is
+installed and the Python engine gives the same results, so nothing ever
+needs compiling). Python 3.12 or newer is required. Until the first PyPI
+release, install from GitHub instead:
+`pip install git+https://github.com/SAMtheROCKET/refactrail.git`.
+
+Then, in any project folder:
+
+```bash
+refactrail                     # the most useful commands
+refactrail lint                # find likely bugs
+refactrail format --diff       # preview formatting; --write applies it
+refactrail check               # structure, naming, type hints, docstrings
+refactrail fix --diff          # preview safe fixes; drop --diff to apply
+```
+
+Paths default to the current folder; pass files or folders to narrow it.
+Exit codes are 0 (clean), 1 (findings) and 2 (error), ready for CI. If your
+system blocks the `refactrail` command, use `python -m refactrail`.
+
+**In VS Code**, install the RefacTrail extension and run *RefacTrail: ...*
+from the Command Palette. It uses the Python interpreter selected in VS Code
+and offers to install RefacTrail there with one click.
+
+**On every commit**, add the hooks to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/SAMtheROCKET/refactrail
+    rev: v0.3.1a0
+    hooks:
+      - id: refactrail-lint
+      - id: refactrail-format
+```
+
+`refactrail-format-check` (fails instead of rewriting) and
+`refactrail-check` are also available.
+
+### From source (development)
+
+Install FuncLoom from its source folder and the local engine fallback
+first, then RefacTrail:
+
+```bash
+python -m pip install -e ../funcloom ./rust/fallback
+python -m pip install -e .
+```
+
+Nothing is uploaded by these local tools.
+
+## General correctness and independent formatting
+
+```powershell
+python -m refactrail lint src
+python -m refactrail lint src --output-format sarif
+python -m refactrail format examples/general_demo.py --diff
+python -m refactrail format examples/general_demo.py --check
+python -m refactrail format examples/general_demo.py --write
+```
+
+`lint` provides nine RC correctness checks without imposing personal naming
+rules. `format` uses an independent CPython AST/tokenize implementation; its
+default is a read-only preview. It makes bounded whitespace edits and retains
+literal/comment spelling, directives, BOM and original line endings.
+Use `--line-length 79` for bracketed comma-group wrapping. Explicit Python
+notebooks and discovered stubs are supported; `--notebooks` includes notebooks
+in folder formatting. This is a documented style subset, not full Black parity.
+
+```powershell
+python -m refactrail format examples/analysis.ipynb --line-length 79 --diff
+python -m refactrail scope examples/project_demo/invoice.py
+python -m refactrail index examples/project_demo --changed invoice.py
+python -m refactrail rename examples/project_demo/invoice.py --function calculate_total --old amount --new base_amount_int
+```
+
+`scope` exposes partial compiler binding evidence. `index` inventories symbols
+and possible import impact under an explicit import root. `rename` produces a
+read-only, hash-linked proposal for a bounded local-variable subset; parameters,
+public APIs, nested scopes and dynamic namespaces are refused. See
+[the workflow and examples](docs/EXPANSION_USAGE.md).
+
+`lint --jobs 4` enables worker processes on larger batches. Lint caching hashes
+source bytes, rule selection, tool/interpreter version and path-sensitive policy;
+use `--no-cache` to disable it. No cache is used to authorize source changes.
+
+See [the independent engines](docs/INDEPENDENT_ENGINES.md) for contracts,
+APIs and limitations, and [the expansion roadmap](docs/EXPANSION_ROADMAP.md)
+for broader formatter, data-flow and repository-refactoring work. These
+engines do not invoke or contain Ruff or Black. The FuncLoom
+structural-rewrite dependency remains as documented below.
+
+## Checking and fixing
+
+`check` reports line, function and main-block sizes; docstrings and their
+sections; missing annotations; naming conventions and verb prefixes;
+constants and their location; and top-level script execution. The strict
+profile adds generic-name and dtype-suffix checks. Defaults are 79 columns,
+40 preferred / 50 maximum function lines, and 100 main-block lines.
+
+```powershell
+python -m refactrail check src --profile strict --statistics
+python -m refactrail check src --output-format json
+python -m refactrail rules
+python -m refactrail fix src --diff
+python -m refactrail fix src
+```
+
+`fix --diff` previews edits without writing. `fix` edits files in place:
+selected fixes add eligible `-> None` annotations, create function docstring
+skeletons, wrap supported lines and split supported long functions. It
+checks compilation, rejects linked files and changed source, and replaces
+each file atomically. Review diffs and run your project's tests. A failed
+file does not roll back other files in a multi-file run.
+
+These are structural checks, not proof of unchanged behavior. Annotations
+and docstrings can affect reflection. There is no automatic domain naming,
+public-API renaming, inferred annotation insertion beyond the bounded None
+case, or arbitrary repository restructuring. Missing meanings need user
+context. Unsupported functions can remain long. Use FuncLoom's explicit
+`modularize` command to create a separate package draft.
+
+Exit codes: check returns 0 with no findings, 1 for findings, 2 for usage
+errors. `--exit-zero` explicitly overrides finding failures. Diff returns 1
+when edits are proposed or files are skipped; fix returns 1 for skipped
+files. Syntax, encoding and internal errors cannot be hidden by selection
+or ignore lists. Suppression markers apply only inside real comment tokens.
+
+## Configuration
+
+```toml
+[tool.refactrail]
+profile = "strict"
+line-length = 79
+function-preferred-lines = 40
+function-max-lines = 50
+main-max-lines = 100
+select = ["RT"]
+ignore = []
+```
+
+Widths must be 40-200; the preferred function size cannot exceed the maximum.
+See [the rule contract](docs/RULES.md) and [design](docs/DESIGN.md).
+
+## The Rust engine
+
+`--engine auto` selects a compatible `refactrail-core` when installed and
+otherwise uses Python. `--engine python` selects the reference implementation.
+The native core is a separate PyO3/Rayon distribution built on
+RefacTrail's own Rust lexer, parser, compile checks and symbol table; it
+contains no Ruff code. `check`, `lint` and `format` accept `--engine`, and
+the standalone `refactrail-native` binary runs `check`, `lint`, `scope`,
+`format` and `index` without Python. Outputs are byte-identical to the
+Python engine on the recorded corpora and fuzzed inputs, with CPython as the
+oracle; see [the dual-engine record](docs/DUAL_ENGINES.md). Parity evidence
+is not a guarantee for every Python program.
+
+Native wheels (CPython 3.12+ ABI3) are built and tested in CI for Linux
+x86_64 (manylinux2014), Windows x86_64 and macOS arm64; other platforms use
+the Python engine. Install a local wheel with
+`pip install --no-index --no-deps WHEEL`. See
+[benchmark evidence](docs/BENCHMARKS.md) for measured timings and their
+limits.
+
+## Editor and release preparation
+
+[The VS Code extension](editor/refactrail/README.md) provides explicit check,
+diff-preview and fix commands. Install its local VSIX, select the Python
+environment containing these packages, and use a trusted workspace.
+
+```powershell
+python scripts/verify.py
+python scripts/release_check.py --output dist/0.3.1a0 --dependency-wheel path/to/funcloom-0.10.3a0-py3-none-any.whl
+```
+
+The release script builds and checks a wheel and source archive, installs
+both in fresh environments, tests installed code and checks uninstallation.
+CI runs the tests on Windows, Linux and macOS with Python 3.12-3.14, and
+the Release check workflow verifies the identical built files on all three
+systems. [Release preparation](docs/RELEASE_PREPARATION.md) lists the
+remaining launch work. No public release has been made.
+
+[MIT](LICENSE), copyright 2026 Sambit Supriya Dash.