[tooling] Evaluate a 500-line maximum per file #109

Summary

Several source and test files in the Python SDK are very large (for example nitrostack/cli/main.py and nitrostack/core/app.py each run well past a thousand lines). Large files are harder to review, test and change safely. This issue is for investigation and a decision, not for splitting files.

The question: should the repo enforce a 500-line maximum per file, and if so, on which files and how?

Reference

Python (current largest files, to be measured):

• nitrostack/cli/main.py
• nitrostack/core/app.py
• nitrostack/transports/http.py
• nitrostack/widgets/route_templates.py
• tests/ (largest test modules)

Tooling to evaluate:

• Ruff (PLR0915 is statements per function, not file length), pylint too-many-lines (max-module-lines), flake8 plugins, or a small custom script run in CI.

Task

1. Measure the current state.
2. Decide the scope and the limit's definition.
3. Evaluate enforcement options and their cost.
4. Either close with the reasoning, or open implementation issues with a scoped plan.

Suggested measurement (PowerShell, from the repo root):

Get-ChildItem nitrostack,tests,examples -Recurse -Filter *.py |
  ForEach-Object { [pscustomobject]@{ Lines = (Get-Content $_.FullName).Count; File = $_.FullName } } |
  Sort-Object Lines -Descending | Select-Object -First 30

Questions to answer

• How many files exceed 500 lines today, split by nitrostack/, tests/, examples/, and templates?
• Is the limit counted as physical lines, or excluding blanks, comments and docstrings?
• Should generated or data-heavy files be exempt (for example widgets/route_templates.py, which embeds HTML, and CLI template strings)?
• Should tests have a different limit from source?
• Should Markdown docs also be limited, or only Python?
• Is a ratchet better than a hard limit: a baseline of current offenders that may not grow, with new files held to 500?
• What are the split points for the three largest files, and would splitting create import cycles or break public import paths (nitrostack.core.app, nitrostack.cli.main)?
• Does any open PR touch these files heavily, so that splitting would cause merge conflicts?

Acceptance criteria

• A table of files over 500 lines, with line counts and the commit measured, is added to the investigation document.
• Each candidate enforcement tool is evaluated for what it checks, configuration needed, and CI impact.
• A recommended policy is written down: limit, scope, exemptions, and whether it is a hard limit or a ratchet.
• A rough split plan exists for the files over the limit, with risks.
• The issue ends with a clear conclusion.

Deliverable

docs/investigations/file-length-limit.md, with pinned commit hash, measurement table, tool comparison, policy recommendation and conclusion. No source files are split in this issue.

Conclusion (to be completed)

Pick one and delete the other.

A. Close. The limit is not worth enforcing because <reason>.

B. Open implementation issues. Scope:

• add the enforcement check (tool and config) with a baseline of current offenders
• split <file> into <modules> while preserving public imports
• update CONTRIBUTING with the policy

Out of scope: unrelated refactors of file contents.