[Triage] Help parsing is sensitive to ANSI colour (latent on Python 3.14): coloured {choices} silently disable choice-value drift checking (CR-A17a-053) #829

Activity

1. cemililik

   added

   bugSomething isn't workingSomething isn't working

   needs-triageNot triaged yet: every new issue starts with it; only a maintainer removes itNot triaged yet: every new issue starts with it; only a maintainer removes it

   source: review-2026-10Found by the October 2026 code and documentation reviewFound by the October 2026 code and documentation review

   on Oct 9, 2026
2. cemililik

   added this to ForgeLM Project Planon Oct 9, 2026
3. cemililik

   added a parent issue on Oct 9, 2026

   • [Epic] Triage: disputed findings #878
4. cemililik commented on Oct 20, 2026

   

   cemililik

   on Oct 20, 2026

   CollaboratorAuthor

   More actions

   Checked on development: on Python 3.13, FORCE_COLOR=1 and PYTHON_COLORS=1 change nothing (no escape bytes, identical help, same parsed surface), so nothing is broken on a supported interpreter today.

   With synthetic ANSI around the flags and {choices}, the parser keeps the flags but returns an empty choice map, and a coloured COMMAND line makes the subcommand list parse fail loudly. We have no 3.14 interpreter to confirm the real layout. It is less silent than described: test_deploy_target_choices_recovered asserts the choices are recovered and would fail in the same environment.

   Kept as low-priority hardening: run the child with colour disabled (and/or strip ANSI) and add a test with injected ANSI, ideally together with adding 3.14 to CI (#526).

   Triage result: enhancement, area: dev-tooling, severity: info, wave: 4.

   Triage round 1, checked against development on 2026-10-20.
5. cemililik

   added

   area: dev-toolingCode area: dev-toolingCode area: dev-tooling

   enhancementNew feature or requestNew feature or request

   severity: infoHardening or improvement suggestionHardening or improvement suggestion

   wave: 4Roadmap wave 4: low / info / watch, when touching the moduleRoadmap wave 4: low / info / watch, when touching the module

   on Oct 20, 2026
6. cemililik

   added this to the Backlog — Wave 4: low, info and watch items milestone on Oct 20, 2026
7. cemililik

   removed a parent issue on Oct 20, 2026

   • [Epic] Triage: disputed findings #878
8. cemililik

   removed

   needs-triageNot triaged yet: every new issue starts with it; only a maintainer removes itNot triaged yet: every new issue starts with it; only a maintainer removes it

   on Oct 20, 2026
9. cemililik

   added a parent issue on Oct 20, 2026

   • [Epic] Wave 4 · Module sweep #875
10. cemililik

    added

    good first issueGood for newcomersGood for newcomers

    and removed

    bugSomething isn't workingSomething isn't working

    on Oct 20, 2026
11. cemililik commented on Oct 22, 2026

    

    cemililik

    on Oct 22, 2026

    CollaboratorAuthor

    More actions

    Where to start

    Thanks for taking a look. Claim it by starting a comment with /assign so nobody duplicates the work.

    Start with these files on development:

    • tools/check_cli_help_consistency.py
    • tests/test_check_cli_help_consistency.py

    _run_help() (about line 123) runs python3 -m forgelm.cli ... --help with the parent's environment and parses the text. Python 3.14's argparse can colour its help; whether it does depends on FORCE_COLOR, PYTHON_COLORS and NO_COLOR. If it does, the escape bytes break two parsers:

    • _parse_subcommand_list stops finding the COMMAND line, which raises a loud RuntimeError;
    • _FLAG_CHOICES_RE stops matching --flag {a,b,c}, so the choice map comes back empty while the flag set looks fine, and drift in choice values goes unchecked.

    On Python 3.13 colour changes nothing, so nothing is broken today; this is hardening.

    What to change (decided, so you do not need to choose):

    1. In _run_help, pass env= to subprocess.run: a copy of os.environ without FORCE_COLOR, with NO_COLOR=1 and PYTHON_COLORS=0.
    2. Add a small _strip_ansi(text) helper and apply it to the text _run_help returns, as a second line of defence. Use a bounded pattern such as \x1b\[[0-9;]{0,32}m (regex standard).
    3. Leave out two parts of the finding. Do not add a check that fails when a subcommand's choice map is empty compared with the previous release: there is no previous-release data to compare. Adding Python 3.14 to CI is tracked in Python support window lags: 3.14 (GA Oct 2025) is installable but never tested; 3.10 reaches EOL this month (CR-A16-056) #526.

    Add the tests to tests/test_check_cli_help_consistency.py. Copy test_deploy_target_choices_recovered in TestParserSurfaceDiscovery and use the tool fixture:

    • Run _strip_ansi on a --target {a,b} line with escape codes around the flag and around the braces. Then _parse_usage_flags(...) returns the choice map. Do the same for a coloured COMMAND line and _parse_subcommand_list.
    • monkeypatch.setenv("FORCE_COLOR", "1"), replace tool.subprocess.run with a fake that records its keyword arguments, and call _run_help(["--help"]). Assert that the recorded env has no FORCE_COLOR, that NO_COLOR == "1" and that PYTHON_COLORS == "0".

    pytest tests/test_check_cli_help_consistency.py --no-cov
    FORCE_COLOR=1 PYTHON_COLORS=1 python3 tools/check_cli_help_consistency.py --strict --quiet
    ruff format --check tools/check_cli_help_consistency.py tests/test_check_cli_help_consistency.py
    ruff check tools/check_cli_help_consistency.py tests/test_check_cli_help_consistency.py

    No GPU, network access or model download is needed. Add an entry under ## [Unreleased] in CHANGELOG.md, where earlier guard changes are listed. The change is tooling only, so there is no Turkish mirror to update.

    Open the PR against development with Fixes #829 (finding CR-A17a-053).