code-comments: make YAML scan block-scalar-aware (stop over-reading bash comments in run: | blocks) #181

New issue

Closed

opened 2026-06-06 05:16:08 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-06 05:16:08 +00:00

Owner

Problem

check_code_comments.py is line-based: it flags any line whose first non-whitespace token is a comment prefix. For YAML that prefix is #. But a # line inside a block scalar (run: |, script: |, any | / > literal/folded block) is string content, not a YAML comment. The checker over-reads those lines as YAML comments.

This was tolerable under the old "two contiguous lines anywhere" rule but surfaces now that YAML is restricted to one top-of-file comment (#160): every # ... bash line inside a composite action's run: | step trips the rule.

Current workaround

pyproject.toml [tool.agentic-os.code-comments].excludes grandfathers actions/** and .coily/coily.yaml. That is a blunt exclude. It also silences genuine net-new YAML comments in those files, which is the opposite of what the rule wants.

Fix

Make the YAML scan block-scalar-aware: when a key's value is a block scalar (|, |-, |+, >, >-, >+, with optional indentation indicator), skip every line indented deeper than the key until the block ends. # lines inside that span are content, not comments, and must not be flagged. Only then can actions/** come back off the exclude list.

A real YAML parse (ruamel/pyyaml round-trip with comment tokens) would be more correct but heavier; a line-based block-scalar tracker is enough for this checker's scope and keeps it dependency-free.

Acceptance

# ... lines inside a run: | / any block scalar are not flagged.
A genuine YAML comment below line 1 (outside any block scalar) is still flagged.
actions/** removed from the code-comments exclude list, hook still green on --all-files.

## Problem `check_code_comments.py` is line-based: it flags any line whose first non-whitespace token is a comment prefix. For YAML that prefix is `#`. But a `#` line inside a block scalar (`run: |`, `script: |`, any `|` / `>` literal/folded block) is **string content**, not a YAML comment. The checker over-reads those lines as YAML comments. This was tolerable under the old "two contiguous lines anywhere" rule but surfaces now that YAML is restricted to one top-of-file comment (#160): every `# ...` bash line inside a composite action's `run: |` step trips the rule. ## Current workaround `pyproject.toml` `[tool.agentic-os.code-comments].excludes` grandfathers `actions/**` and `.coily/coily.yaml`. That is a blunt exclude. It also silences genuine net-new YAML comments in those files, which is the opposite of what the rule wants. ## Fix Make the YAML scan block-scalar-aware: when a key's value is a block scalar (`|`, `|-`, `|+`, `>`, `>-`, `>+`, with optional indentation indicator), skip every line indented deeper than the key until the block ends. `#` lines inside that span are content, not comments, and must not be flagged. Only then can `actions/**` come back off the exclude list. A real YAML parse (ruamel/pyyaml round-trip with comment tokens) would be more correct but heavier; a line-based block-scalar tracker is enough for this checker's scope and keeps it dependency-free. ## Acceptance - `# ...` lines inside a `run: |` / any block scalar are not flagged. - A genuine YAML comment below line 1 (outside any block scalar) is still flagged. - `actions/**` removed from the code-comments exclude list, hook still green on `--all-files`.

coilysiren referenced this issue from a commit

2026-06-06 05:24:26 +00:00

feat(code-comments): one top-of-file YAML comment, block-scalar aware

coilysiren closed this issue

2026-06-06 05:24:26 +00:00