Import stricter Python lint tiers - #13
Merged
Merged
Conversation
Import the Ruff selector set, banned deprecated `typing` APIs, and focused Pylint message policy from `leynos/episodic`. Run Pylint after Ruff through the pinned `pylint-pypy-shim` wrapper under PyPy, then continue through the existing Rust lint tiers. Update the Makefile contract tests and developer guide so the new lint path is covered and documented. Resolve the new lint findings in the existing Python code and tests, and refresh the locked Ruff version so the imported preview rules are known.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
WalkthroughStandardise Makefile to use an uv wrapper and add PyPy-backed Pylint wiring; add Ruff and focused Pylint configuration to pyproject.toml; modernise Callable types to collections.abc; update protocol stubs and tests; apply broad documentation reflow and add ADR 004 describing the two‑tier lint architecture. ChangesLinting toolchain and type modernisation
Documentation updates for linting and examples
Sequence Diagram(s)flowchart LR
MakeLint["make lint"]
PYLINT["PYLINT (uv tool run --python pypy + pylint-pypy-shim)"]
RUFF["ruff check"]
MakeLint --> PYLINT
PYLINT --> RUFF
Possibly related PRs
Poem
Caution Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional.
❌ Failed checks (1 error, 1 inconclusive)
✅ Passed checks (16 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
leynos
marked this pull request as ready for review
May 15, 2026 11:40
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/stilyagi-design.md`:
- Around line 805-806: The inline code span for `segments` is split across two
lines causing malformed backticks; update the Markdown so the entire inline code
list appears on a single line (e.g., change "It does not yet expose
`line_index`, `segments`," to keep the backticks around `segments` on the same
line) or move the backtick boundaries to a proper word boundary so `segments` is
fully enclosed; ensure the other items (`line_index`, `owner metadata`,
`canonical IR JSON`) remain formatted consistently and run mdformat-all /
markdownlint-cli2 to validate the fix.
In `@tests/test_build_spine_units.py`:
- Line 60: The test uses yaml.load(..., Loader=yaml.BaseLoader) which triggers
Ruff S506; either add "S506" to the per-file-ignores array for the test glob in
pyproject.toml (the "**/test_*.py" entry) so tests can use BaseLoader, or
restore a narrow inline suppression on the call to yaml.load using noqa for
S506; reference the yaml.load call and yaml.BaseLoader in
tests/test_build_spine_units.py and the "**/test_*.py" per-file-ignores entry in
pyproject.toml when making the change.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: e57c5fa7-309e-4532-8466-529010ea50d9
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (16)
.rules/python-generators.mdMakefiledocs/complexity-antipatterns-and-refactoring-strategies.mddocs/developers-guide.mddocs/execplans/1-2-3-makefile-and-ci-smoke-tests.mddocs/execplans/1-3-1-assemble-representative-fixtures.mddocs/local-validation-of-github-actions-with-act-and-pytest.mddocs/rfcs/0005-grammar-capability-and-syntactic-api-extensions.mddocs/roadmap.mddocs/scripting-standards.mddocs/stilyagi-design.mdpyproject.tomlpython/stilyagi/nlp/base.pypython/stilyagi/smoke.pytests/test_build_spine_units.pytests/test_package_skeleton_units.py
Add ADR 004 for the Ruff-first, focused-Pylint-second linting architecture and record the Makefile execution model behind `make lint`. Expand the developer guide with the lint tiers, Makefile variables, Episodic policy baseline, and `pyproject.toml` configuration sections so maintainers can change or diagnose the lint gate deliberately.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Allow checked-in YAML fixture parsing in tests through Ruff per-file ignores, matching the test-only scope of the existing workflow parser. Rewrite the design note payload wording so Markdown formatting no longer splits inline code spans across lines.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/developers-guide.md`:
- Line 612: In the documentation line containing the phrase "bans broad `from`
imports for modules whose aliases are standardised", replace the British
spelling "standardised" with the en-GB-oxendict form "standardized" so the
sentence reads "...whose aliases are standardized"; update any other occurrences
of "standardised" in docs/developers-guide.md to "standardized" to comply with
the en-GB-oxendict -ize guideline.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5139020a-cc5f-47f4-9f73-77559a199b34
📒 Files selected for processing (5)
docs/adr-004-python-linting-architecture.mddocs/contents.mddocs/developers-guide.mddocs/stilyagi-design.mdpyproject.toml
Replace the lint guide wording with the Oxford spelling `standardized`.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/developers-guide.md`:
- Around line 179-184: Add a short caption line immediately above each of the
two Markdown tables so they comply with the "Caption every table" rule; locate
the first table that documents SHARED_MARKDOWN_FIXTURE_PATH, repository_root,
corpus_fixture_path, and read_corpus_fixture and insert a one-sentence caption
directly before the table, and do the same for the other table referenced around
the 572-582 range—ensure captions are brief (e.g., "Table: Repository fixture
utilities and signatures") and placed on their own line immediately preceding
each table block.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 66bb2703-6402-413b-bdfe-d2a459784cf9
📒 Files selected for processing (1)
docs/developers-guide.md
Reorder the focused Pylint allowlist by diagnostic purpose so logging, pattern matching, control flow, collections, runtime hazards, text hygiene, mutation, and complexity checks are easier to review.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add short captions before the fixture utility and lint variable tables so the developer guide follows the documentation table-caption rule.
This was referenced May 16, 2026
This was referenced May 27, 2026
This was referenced Jun 9, 2026
This was referenced Jun 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch imports the stricter Python lint policy from
leynos/episodicso Stilyagi checks Python with Ruff first, then a focused Pylint pass through the pinned PyPy shim, before continuing through the existing Rust lint tiers. It also records that linting architecture in an ADR and expands the developer guide so maintainers can run, diagnose, and deliberately change the gate.The branch is not linked to a roadmap task, issue, or execplan.
Review walkthrough
UVresolver, pinnedpylint-pypy-shiminvocation, andmake lintordering.typing.*APIs, and focused Pylint message set.make lintworkflow, Makefile variables, Episodic policy baseline, andpyproject.tomllint configuration map.make fmt.Validation
make fmt: passedmake lint: passedmake check-fmt: passedmake typecheck: passedmake test: passed; 59 Rust tests and 51 Python tests passedmake markdownlint: passed after the ADR and developer-guide updatemake nixie: passed after the ADR and developer-guide updatembake validate Makefile: passedNotes
The imported
RUF066selector required refreshing the locked Ruff version because the previously locked Ruff release did not recognise that preview rule. The new Pylint tier also exposed a few existing Python and test clean-ups, which this branch resolves so the stricter gate starts green.ADR 004 treats the Episodic lint policy as a deliberate baseline, not an automatic upstream subscription. Future lint-policy imports should be reviewed and gated rather than copied mechanically.
References