diff --git a/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.md b/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.md new file mode 100644 index 00000000..d0713c66 --- /dev/null +++ b/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.md @@ -0,0 +1,36 @@ +--- +model: openai/gpt-5.6-sol +service: opencode +session: ses_fd403c9c9ffe625w99Tr0ALQBN +timestamp: 2026-08-25T18:11:02Z +git_ref: 3690e43a +scope: config +substantive: true +raw_file: 20260825T181102Z_3690e43a_prompt_io.raw.md +--- + +## Prompt + +Enforce the 69-column Python source limit through Ruff and record a +follow-up for richer project-specific style checks. + +## Response summary + +Enabled E501 at 69 columns and documented a later changed-line +token/AST checker for style rules Ruff cannot represent. Isolated the +configuration on a dedicated follow-up branch after measuring the +existing repository lint debt. + +## Files changed + +- `ruff.toml` - enables 69-column E501 enforcement and records + follow-up lint work. + +## Human edits + +The human initially selected immediate global enforcement and +explicitly requested the richer-checker TODO. After review exposed +1,548 existing diagnostics, the human directed the work onto an +independent linting branch and deferred landing until incremental +enforcement is implemented. The agent applied the config and transfer; +no direct manual source edits were identified. diff --git a/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.raw.md b/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.raw.md new file mode 100644 index 00000000..cca719a4 --- /dev/null +++ b/ai/prompt-io/opencode/20260825T181102Z_3690e43a_prompt_io.raw.md @@ -0,0 +1,24 @@ +--- +model: openai/gpt-5.6-sol +service: opencode +timestamp: 2026-08-25T18:11:02Z +git_ref: main +diff_cmd: git diff HEAD~1..HEAD -- ruff.toml +--- + +## Prompt + +Enable Ruff enforcement of the shared 69-column Python source limit in +Modden, Piker, and Tractor. Add a TODO for a later changed-line token/AST +checker covering project rules Ruff cannot express. + +## Response + +Configured Ruff's formatter/lint line length to 69 and enabled E501. Added a +follow-up TODO for boolean layout, local annotation placement, docstring +quoting and rationale, and symbol-qualified technical prose. + +> `git diff HEAD~1..HEAD -- ruff.toml` + +The configuration parses successfully. Existing Tractor package/test debt is +1,469 E501 diagnostics; it was reported rather than reformatted implicitly. diff --git a/plans/opencode/py_codestyle_linting.md b/plans/opencode/py_codestyle_linting.md new file mode 100644 index 00000000..7bcee098 --- /dev/null +++ b/plans/opencode/py_codestyle_linting.md @@ -0,0 +1,97 @@ +# Incremental Python Style Enforcement + +## Objective + +Enforce the mechanically checkable parts of `/py-codestyle` on new and +changed Python lines without requiring an immediate repository-wide +cleanup. Keep subjective prose guidance in review policy and expose +legacy debt separately from blocking CI. + +## Current State + +- `ruff.toml` sets the intended 69-column limit and enables `E501`. +- A package-and-test scan reports 1,548 existing violations. +- Ruff can enforce line length, ordinary syntax rules, unused f-string + prefixes, and configured quote style. +- Ruff cannot directly encode several project-specific layout, + docstring, annotation, and technical-prose policies. + +The initial configuration is branch scaffolding, not a landable final +state. The implementation must make changed-code enforcement usable +before this branch targets `main`. + +## Policy Matrix + +Document each `/py-codestyle` rule under one enforcement class: + +1. Ruff lint rule, enabled directly when the repository is clean. +2. Ruff formatter setting, used for intentionally formatted files. +3. Deterministic token or AST check, enforced on changed lines. +4. Review-only guidance where automation would produce false positives. + +Start with native checks for `E501`, `F541`, quote style, import and +syntax errors. Use custom checks for exact docstring delimiters and +shape, multiline string construction, double-newline source layout, +f-string continuation consistency, local annotation placement, and +boolean-expression layout. Keep symbol-qualified technical prose and +regression-test rationale as review guidance unless a low-noise warning +can be demonstrated. + +## Changed-Line Harness + +Add `scripts/check_py_codestyle.py` with these responsibilities: + +- Read a base revision and collect added line ranges from `git diff + --unified=0`. +- Treat every line in an added Python file as changed. +- Run Ruff with JSON output and the incremental native-rule set. +- Report only diagnostics intersecting added line ranges. +- Run token/AST checks and apply the same changed-line filter. +- Return a nonzero status only for changed-code violations. +- Offer a separate nonblocking full-tree debt-report mode. + +Keep `E501` out of the default global Ruff selection until the legacy +count reaches zero. The harness should request it explicitly so normal +repository lint remains useful during migration. + +## Verification + +Add focused checker tests covering: + +- diff range parsing, deleted lines, renames, and new files; +- 69-column boundaries with indentation and string syntax; +- compliant and noncompliant docstring delimiters and closing shape; +- f-string continuation and double-newline source layout; +- boolean layout and local annotation placement; +- diagnostics on untouched legacy lines being ignored; +- diagnostics on newly touched legacy lines becoming blocking. + +Run the checker against a fixture base and against the branch diff. Run +the existing Ruff checks without incremental rules to prove the normal +lint path remains usable. + +## CI Integration + +Add a dedicated CI step that derives the pull-request base commit from +the event payload and invokes the changed-line harness. Preserve a local +`--base main` mode for developers. Emit normal file, line, column, and +rule identifiers so forge annotations remain navigable. + +Publish the full-tree debt count as nonblocking output. Do not hide or +silently rewrite existing source violations. + +## Commit Boundaries + +1. Record the 69-column policy scaffold and provenance. +2. Add the changed-line Ruff harness and its tests. +3. Add deterministic token/AST policy checks and fixtures. +4. Wire the harness into CI and document local usage. +5. Enable native rules globally only after their legacy counts reach + zero, using separate cleanup commits where needed. + +## Deferred + +Type-checking migration belongs in a separate branch. It should use the +same incremental principle: establish the tool configuration and debt +inventory, gate new or changed code, publish nonblocking full-tree debt, +and tighten global enforcement as annotations and defects are repaired. diff --git a/ruff.toml b/ruff.toml index a461ac0b..74b1e74c 100644 --- a/ruff.toml +++ b/ruff.toml @@ -31,8 +31,8 @@ exclude = [ "venv", ] -# Same as Black. -line-length = 88 +# Project source style limit. +line-length = 69 indent-width = 4 # assume latest minor cpython @@ -42,11 +42,15 @@ target-version = "py313" # Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default. # Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or # McCabe complexity (`C901`) by default. -select = ["E4", "E7", "E9", "F"] +select = ["E4", "E7", "E9", "E501", "F"] ignore = [ 'E402', # https://docs.astral.sh/ruff/rules/module-import-not-at-top-of-file/ ] +# TODO: add a changed-line token/AST checker for py-codestyle rules +# Ruff cannot express: boolean layout, local annotation placement, +# docstring quoting/rationale, and symbol-qualified technical prose. + # Allow fix for all enabled rules (when `--fix`) is provided. fixable = ["ALL"] unfixable = []