[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #252 (comment)

What

Two edges of the reader's flow-mapping entry, found by the adversarial review of #213 (its F3 and F4) and
filed as #252. Both made a flow mapping read differently from its block twin.

1. An explicit key. The block reader refuses ? by name (_refuse_unsupported: explicit keys are not supported), and the reader's header lists explicit keys as REFUSED, because the meaning would have to be
   invented. That check runs on block lines only, so k: {? a: b} read as the literal key ? a. A flow
   mapping entry opening ? is now refused with the same phrase. A flow collection has no line to name, so it
   names the entry: explicit keys are not supported: '? a: b'.
2. An empty value. _flow_value asked text[:1] in "[{", which is True for the empty string, so {a: },
   {a:} and {a: , b: 1} ran _flow('') and were refused as not a flow collection: '', a text nobody
   wrote. The question is whether the text OPENS a flow collection (startswith(("[", "{"))), which an empty
   one does not. It reaches _scalar(''), the null the block a: reads. A quoted empty ({a: ""}) stays the
   empty string.

Functions touched, and nothing else: _split_key_flow (the refusal, before return _split_key(text)),
_flow_value (the test), and one appended paragraph in the SUPPORTED/REFUSED header comment. _split_key,
_flow, _split_flow, _scalar, _strip_comment and _refuse_unsupported are untouched.

Why

"An invented meaning in a validator is a wrong answer with a confident tone." Row 1 was a wrong answer with no
refusal; rows 3 to 5 were refusals of valid YAML naming an empty string a person never wrote. Latent today: no
writer in the repository emits a flow mapping with a key or a value. It shows on a file a person edits, such as
naming: {form: } left half filled in project.yaml.

Evidence

• New tests/test_yaml_flow_mappings.py, 46 tests: 34 fail and 12 pass on 150c41d (the 12 are controls),
  46 pass on head. Pins the issue's rows, the places each can stand (after another entry, nested in a
  flow mapping and in a flow sequence, as a block-sequence item, in a file read through load_yaml), the block
  twin equal wherever the block reader reads one, the spelled nulls (~, null, Null, NULL) equal to the
  empty value, quoted empties staying '', and what must NOT be refused ("? a", '? a', ?a, a?,
  b?).
• Mutation probes, each reverts or bends one hunk: nine behavioural mutants each fail at least one new test
  (20, 14, 1, 3, 5, 20, 13, 1, 2); the comment hunk and docstrings are behaviour-free and survive.
• Differential fuzz, 100,000 documents with PyYAML 6.0.3 as the oracle (the oracle only, never imported by
  shipped code): flow == expected == block twin == PyYAML on every one on head; on 150c41d 64,387 of them read
  wrong. 100,000 variants with one entry made an explicit key: all refused on head, none on 150c41d. Re-run of
  scripts/repo_shape.py _split_flow ignores a backslash inside a double-quoted flow item, so pins: ["x\",y"] reads back as two items x\ and y" where the same text as a block sequence item reads as the one item x",y #213's flow/block fuzz (100,000 plus 60,000 with the code-point escapes): 0 mismatches.
• Reach: all 14 tracked YAML files read identically on 150c41d and on head. The writers that emit a flow
  collection (pins, allow_empty_legs, also_matches, referent_chain, members: [], paths: []) emit
  sequences or [], never a mapping.
• Targeted, on head: test_yaml_flow_mappings, test_yaml_flow_quotes, test_load_yaml_refusals,
  test_adopt_plan_escapes, test_manifest_validator, test_pin_validator, test_neutral_pin_validator,
  test_repo_hygiene, test_cli_reference, test_adopt_plan: 321 passed, 1 skipped (SHAPE_MEDXEHR_CLONE
  unset). test_shape_doctor.py: 181 passed.
• Not run here: the full suite, and the macOS and Windows jobs; the new tests pass bytes to git nowhere and
  write files as bytes, so LF on every platform.

Composition

git merge-tree --write-tree HEAD <ref>: clean against origin/main 39ac59c, and clean against
fix/yaml-block-key-nul (9be6287), where the combined tree also passes both writers' new tests together (125).
fix/yaml-quote-boundaries and fix/scaffold-referent-chain-links had no commit when this was written, so
nothing was merged against them.

Left out

• A flow SEQUENCE item opening ? ([? a], [? a: b]) still reads as a string, where the block - ? a is
  refused. Same class, different branch of _flow; scripts/repo_shape.py reads ? a: b in a flow mapping as the literal key ? a, where the block reader refuses explicit keys, and refuses {a: } and {a:} as not a flow collection: '' instead of reading {'a': None} #252 names the mapping.
• ? followed by a tab, and a bare ? block item, are not refused by either form (both look for "? ").
• A flow entry with a key and no colon ({a}) is still refused as without a key.
• The empty flow ITEMS and [k: v] notes in the issue are unchanged.

Closes #252

🤖 Generated with Claude Code

Summary by Sourcery

Align flow-mapping edge cases with block-mapping behavior by refusing unsupported explicit keys and reading empty values as null.

Bug Fixes:

• Make flow-mapping entries beginning with ? refuse unsupported explicit keys instead of interpreting them as literal keys.
• Treat empty flow-mapping values as null, matching block mappings and spelled null values.

Enhancements:

• Document flow-mapping behavior parity with block mappings and preserve handling of quoted empty strings and non-explicit question-mark keys.

Tests:

• Add comprehensive coverage for explicit-key refusals, empty values, nested flow mappings, block-sequence contexts, file loading, and regression cases.

[brettheap]

(lane openRepoShape-5, 2026-10-11T22:24Z) @codex review

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR fixes two flow-mapping edge cases in repo_shape.py: explicit-key entries beginning with ? are now refused consistently with block mappings, and genuinely empty values are parsed as null rather than being misclassified as flow collections. A new focused test module validates parity across nesting, sequence and file-loading contexts while protecting related YAML behaviors.

File-Level Changes

Change	Details	Files
Align flow-mapping entry handling with block-mapping behavior for unsupported explicit keys and empty values.	Reject entries beginning with ? using the existing explicit-key refusal wording, including the raw flow entry in the error. Treat only text that actually starts with [ or { as a nested flow collection; pass empty values to scalar parsing so they become null. Document the flow-mapping/block-mapping parity contract and the two edge cases.	scripts/repo_shape.py
Add comprehensive regression coverage for flow-mapping parity, refusals, null values, and preserved distinctions.	Cover explicit-key refusals across nesting and placement contexts, while confirming quoted and non-indicator question marks remain valid. Verify empty flow values match block nulls and spelled null forms, while quoted empty values remain empty strings. Exercise nested collections, file loading, refusal propagation, and unchanged malformed-collection behavior.	tests/test_yaml_flow_mappings.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#252	Refuse explicit flow-mapping keys beginning with ? with the same unsupported-explicit-key behavior as the block reader, rather than interpreting ? a as a literal key.	✅
#252	Interpret empty flow-mapping values such as {a: }, {a:}, and {a: , b: 1} as YAML null values, matching block mappings, while preserving quoted empty strings and nested flow-collection handling.	✅
#252	Add regression coverage documenting and testing the explicit-key refusal and empty-value behavior in relevant nesting, file-loading, and compatibility cases.	✅

Possibly linked issues

• scripts/repo_shape.py reads ? a: b in a flow mapping as the literal key ? a, where the block reader refuses explicit keys, and refuses {a: } and {a:} as not a flow collection: '' instead of reading {'a': None} #252: PR directly fixes both reported behaviors and adds comprehensive regression tests for issue scripts/repo_shape.py reads ? a: b in a flow mapping as the literal key ? a, where the block reader refuses explicit keys, and refuses {a: } and {a:} as not a flow collection: '' instead of reading {'a': None} #252.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T22:33:32.791793Z	2438190	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 2438190b40

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".