[finding] ListView.tsx: `formatActionLabel`'s docblock sits two declarations above it, so `parseSortConfig` carries two leading comments and the helper carries none

[yinlianghui]

Found while implementing #3950 (PR #4965) — the removed UNSORTABLE_FIELD_TYPES const sat inside this run of comments, so the diff put the misattribution in plain view. Recorded, not claimed; not swept into that PR, whose scope is the sort affordance.

The layout

packages/plugin-list/src/ListView.tsx (anchor by the declarations, not the line numbers — this region moved in #4965):

/**
 * Format an action identifier string into a human-readable label.
 * e.g., 'send_email' → 'Send Email'
 */
/**
 * Normalize a view's `sort` declaration to SortItem[]. …
 */
export function parseSortConfig(sort: unknown): SortItem[] { … }

function formatActionLabel(action: string): string { … }

Two docblocks stacked with nothing between them, then parseSortConfig, then formatActionLabel — bare. The first block describes formatActionLabel, which is two declarations away.

By every consumer's adjacency rule the first block belongs to parseSortConfig: editor hover, TypeDoc, and — the reason this is slightly more than cosmetics — scripts/check-spec-symbol-derivation.mjs, whose rule 2 reads "the comment block ATTACHED to the declaration". That script already carries a precision rule earned by exactly this shape ("Reading all leading comments let a banner's prose supply the claim phrase for whichever declaration happened to sit first"). A misattributed docblock is how a claim gets scored against the wrong symbol; this one happens to carry no spec-alignment phrase, so nothing fires today.

Pre-existing, not introduced by #4965: before it, the two blocks were separated by the formula-set const and its own docblock, so the misattribution was already there and merely less adjacent.

Why it is observation-class

Nothing renders a comment, and neither function's behaviour is in question — formatActionLabel is a four-token string transform, parseSortConfig is pinned by ListView.parseSortConfig-facing tests. No user reaches this. The cost is to the next reader, who meets a sort-parser introduced by a sentence about action labels, and to any future gate that scores prose by adjacency.

Verified at source

objectui origin/main @ 1b21b1aaa (and unchanged in kind on claude/issue-3950-formula-sort-header): formatActionLabel is declared immediately after parseSortConfig's closing brace, with no comment of its own; the stack of two docblocks precedes parseSortConfig.

Suggested fix

Move the first docblock down to sit directly above formatActionLabel. No code, no strings, no tests.

Sibling in the same file, same class, different fact: #4559 (a stale claim in the sortFields comment block). Both are single comment edits in ListView.tsx and could reasonably be batched into one docs-only PR — worth the triage seat's call rather than mine.

---

Generated by Claude Code