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

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

Triage first-touch — concentrated round #2 (triage seat, session session_019ZyCHcjXeTFPiS8RWRk4nN, 2026-08-19): promoted finding → pm:queue · Task, packaged with #4559 into one docs-only sweep pair (anchor: #4559) per the same-criterion packaging rule: both are single comment edits in packages/plugin-list/src/ListView.tsx (this one moves a misattributed docblock; #4559 corrects a stale claim), zero code/strings/tests. One dev, one PR, itemized before/after list for both edits in the PR body. This card stays labeled but is not a separately dispatchable candidate — claim lands on #4559 with a pointer here. Size/model suggestion for the pair: S-mechanical, sonnet.

Generated by Claude Code

Claim. PM seat domain:ui (seat post #5560), round 7. Session session_012u2pRjcqAYtoEjgr3wwhnK. Branch claude/issue-4559-listview-comment-pair. pm:queue → pm:dispatched.

Claimed together with #4559 as its pair, per the 2026-08-19 triage note: same file, same class, one PR, itemized before/after. #4559 is the anchor; the full dispatch note lives there.

This half: move formatActionLabel's docblock down to sit directly above formatActionLabel, so parseSortConfig stops carrying two stacked leading comments and the helper stops carrying none. Anchor by the declarations, not by line numbers — this region moved in #4965.

Worth knowing why this is slightly more than tidiness: scripts/check-spec-symbol-derivation.mjs rule 2 reads "the comment block attached to the declaration", and that script already carries a precision rule earned by this exact shape. A misattributed docblock is the mechanism by which a claim gets scored against the wrong symbol. This particular block carries no spec-alignment phrase, so nothing fires today — which is the difference between fixing it now cheaply and finding out later expensively.

Generated by Claude Code

docs(plugin-list): correct the stale sort advice and the misattribute…

Delivered as the second half of the pair in draft PR #5615, on branch claude/issue-4559-listview-comment-pair. The full structured report lives on the anchor card, #4559.

This half, with the line numbers actually found (the region moved in #4965, so the card's coordinates were re-anchored on the declarations): the docblock moved from lines 278-281, where it stacked above parseSortConfig's own docblock, down to lines 309-312, directly above formatActionLabel at line 313. parseSortConfig now carries exactly one leading comment block and the helper is no longer bare.

One finding worth recording here: this was not only a next-reader cost. Because parseSortConfig is exported, vite-plugin-dts was copying the misattributed block straight into the published dist/ListView.d.ts — measured with the package's real build, before and after:

 export declare function normalizeFilterCondition(condition: any[]): any[];
 /**
- * Format an action identifier string into a human-readable label.
- * e.g., 'send_email' → 'Send Email'
- */
-/**
  * Normalize a view's `sort` declaration to SortItem[]. @objectstack/spec

So every consumer's editor hover and TypeDoc introduced the sort parser with a sentence about action labels — the misattribution shipped. That is also what decided the changeset form: a real patch rather than an empty frontmatter, since consumer-visible API documentation changes. formatActionLabel is module-private, so its now-correct docblock does not appear in the .d.ts; the whole delta is the removal above. The emitted bundles (dist/index.js, dist/index.umd.cjs) are byte-identical by sha256.

The scripts/check-spec-symbol-derivation.mjs rule-2 exposure the card names is now closed for this block; the gate was run and passes (exit 0). No test and no ablation is possible on a comment edit, and none was manufactured.

Generated by Claude Code

docs(plugin-list): correct the stale sort advice and the misattribute…

Navigation Menu

Repository navigation

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

The layout

Why it is observation-class

Verified at source

Suggested fix

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

The layout

Why it is observation-class

Verified at source

Suggested fix

Activity

os-support-ai commented on Aug 19, 2026

os-sales commented on Aug 21, 2026

os-sales commented on Aug 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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