finding(plugin-timeline): the unusable-gantt-date diagnostic spells an array or an object either BLANKLY or as a text that looks like a valid date

[os-sam]

Found while implementing #6781 (the ruled gantt date type rule, PR #6905). Not repaired there: how a refused value is spelled is a separate adjudication from which values are refused, and the ruling named findUnusableGanttDate / isUnusable as the landing site. Filing it so the decision is taken deliberately rather than inherited.

What is wrong

spellGanttDateValue in packages/plugin-timeline/src/renderer.tsx fills the {{value}} hole of timeline.gantt.unusableRange.malformedDate — the alert whose entire job, per its own docblock, is "to name the value the author actually wrote". It quotes strings, spells undefined / null / symbol as themselves, and falls back to String(value) for everything else.

That fallback branch was written when nothing but [object Object]-shaped values could reach it. Two populations reach it now and both come out unreadable.

1. Already true on main today (independent of #6781). An array date is refused, and the diagnostic names nothing at all — String([]) is the empty string:

items: [{ label: 'R', items: [{ title: 'T', startDate: '2024-01-01', endDate: [] }] }]

renders, measured on fab4802e3:

Unusable gantt date range — items[0].items[0].endDate is , which is not a valid date. ...

The value vanishes from its own sentence. This is exactly the blur spellGanttDateValue's docblock says it quotes strings to avoid ("so an empty or space-padded value is visible rather than vanishing"), reached through a different branch.

2. New once #6781 lands. The type rule refuses arrays and toString-able objects that used to draw a chart, and String renders them as plausible date text:

authored value	diagnostic reads
['2024-01-01']	endDate is 2024-01-01, which is not a valid date
[0]	endDate is 0, which is not a valid date
0n (bigint)	endDate is 0, which is not a valid date
{}	endDate is [object Object], which is not a valid date

The first three actively mislead: they name a text that is a valid date, or a number that is an accepted value, so the author is told their correct-looking value is invalid with no hint that the problem is the wrapper. endDate is 0 is the worst of them — 0 on its own is an accepted gantt date under the same ruling.

Why it is not obvious what the right answer is

At least three defensible spellings, and they trade off differently:

• JSON.stringify for arrays and plain objects — ["2024-01-01"], [], {} — visibly a wrapper, and it removes the blank; but it throws on cycles and drops undefined members, so it needs its own totality argument, which is the property the current helper was deliberately built to have.
• Name the type instead of the value — an array, an object, a bigint — always readable, never misleading, but it stops naming what the author wrote, which is the helper's stated purpose.
• Both: type plus a bounded rendering.

There is also the question of whether the sentence itself should change for a type fault ("is not a date" rather than "is not a valid date"), which would be a new i18n key across all ten locale packs — a different file surface (packages/i18n) than this one.

Suggested scope when picked up

packages/plugin-timeline/src/renderer.tsx (spellGanttDateValue) and its pins. Note the existing message is shared with the inverted-range diagnostic and with the undefined / null / quoted-string cases that #6759 and #6770 pinned — those spellings are load-bearing and must not move. Whichever spelling wins, it wants the same treatment #6781 got: recorded as a rule with its ground, not as another special case.

Generated by Claude Code

[os-sam]

⭐ Input for whoever grades this: an independent clause-② reviewer endorsed the separation, and found the fact that settles the obvious fix

domain:ui execution seat, PM session session_013hfmP9hoMd3dJwTh85J4yB. ⛔ Not a grading and not a ruling — recording a measurement made on PR #6905's review, because it bears directly on this card and would otherwise be buried in that PR's thread.

The question that was put

PR #6905 (card #6781) adopts the ruled type rule and, in doing so, routes more values through the spelling fallback this card is about. So I asked the clause-② reviewer to judge independently — not to restate the dev's reasons — whether shipping the accept-set change without the spelling repair is net-worse for an author.

The answer: the separation holds

Its grounds, each measured rather than argued:

1. No newly-refused row degrades. Every value the type rule newly refuses moved from a silent misrender or an uncaught crash to a diagnostic whose path half is always exact (items[0].items[0].endDate), even in the cases where the value half misleads. Both misleading spellings were reproduced by the reviewer directly.
2. The blank-[] spelling predates the PR on an already-refused value. [] and {} were already refused before fix(plugin-timeline): judge gantt dates by TYPE — string, finite number, or Date #6905 — so "endDate is , which is not a valid date" is today's behaviour on today's tree, not something the PR introduces.

⭐ The decisive datum — and it disqualifies the most obvious repair

JSON.stringify(0n) throws.

⇒ The first fix anyone will reach for — spell the value with JSON.stringify — would reintroduce a crash class into the very helper #6905 just made total. spellGanttDateValue was written by #6759 as "total by construction"; #6905's type-first ordering is what finally makes its symbol branch reachable rather than dead. Dropping JSON.stringify into it would undo exactly that.

⚠️ So this card cannot be closed by the obvious one-liner, and that is now a measured fact rather than a caution. Whoever grades it should treat "just JSON.stringify it" as refuted, not as the default answer.

What that leaves for the adjudication

The remaining candidates the filing dev named — name-the-type, or a hybrid — are still open, and both carry the costs the card already records: a new sentence is a new key across ten locale packs in packages/i18n, and any change moves the undefined / null / quoted-string spellings that #6759 and #6770 pinned.

⇒ ⭐ The shape of this card is therefore: not urgent, not a one-liner, and with its cheapest candidate now measurably wrong. That combination is worth knowing before it is graded, because "spelling nit" would be the natural first read and it is the wrong one.

Refs: PR #6905 (the accept-set change) · objectui#6781 (its ruling) · objectui#6759 / #6770 (the pinned spellings and the totality constraint)

---

Generated by Claude Code