Skip to content

Commit 68f653f

Browse files
committed
docs(cli,spec): the flows gating and translateFlow comments describe the live flows row
Comments only. The authorWarnedTranslationGroups docblock and the extract surface header, the flow-screen coverage test header and translateFlow's docblock said the flow label was unread and the row planned. Claude-Session: https://claude.ai/code/session_01T9u38rswFp5Rw8DswRUReJ Co-authored-by: Claude <noreply@anthropic.com>
1 parent bffb933 commit 68f653f

3 files changed

Lines changed: 36 additions & 35 deletions

File tree

‎packages/cli/src/utils/i18n-extract.ts‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -107,9 +107,10 @@
107107
* flows.<flow>.screens.<node_id>.title (#7646 / #11287)
108108
* flows.<flow>.screens.<node_id>.fields.<field>.label
109109
* flows.<flow>.screens.<node_id>.fields.<field>.placeholder
110-
* ^ gated: `flows` is `planned` + `authorWarn` in the liveness ledger, so
111-
* these are walked only once the row goes `live` (#11624 — see
112-
* `authorWarnedTranslationGroups`)
110+
* flows.<flow>.screens.<node_id>.fields.<field>.inlineHelpText
111+
* ^ walked because the ledger's `flows` row is `live` and warns no
112+
* author; a group the ledger does warn on is left out of the walk
113+
* (see `authorWarnedTranslationGroups`)
113114
* metadataForms.<type>.label / .description
114115
* metadataForms.<type>.sections.<section>.label / .description
115116
* metadataForms.<type>.fields.<dotPath>.label / .helpText / .placeholder
@@ -1067,8 +1068,9 @@ function walkObjectTabs(config: any, out: ExpectedEntry[]): void {
10671068
}
10681069

10691070
/**
1070-
* Translation groups the shipped liveness ledger warns an author for authoring
1071-
* — today exactly `flows` (`status: planned`, `authorWarn: true`).
1071+
* Translation groups the shipped liveness ledger warns an author for authoring.
1072+
* Today the set is empty: `flows`, the one group ever warned, is `live` now
1073+
* that both its halves are read, so nothing is gated.
10721074
*
10731075
* ## Why the walk surface is gated on this at all (#11624)
10741076
*
@@ -1083,20 +1085,20 @@ function walkObjectTabs(config: any, out: ExpectedEntry[]): void {
10831085
* `i18n/missing-*` family. Under `--i18n-strict` the demand side is an error,
10841086
* so a project could be *forced* to author keys it is then warned for.
10851087
*
1086-
* ⛔ The warn side is not the bug and must not be softened. Only part of the
1087-
* group is read: the console's screen-flow runner reads `screens`, but the
1088-
* flow's own `label` is read by nothing yet (#20318), so a translated flow
1089-
* label really is stored and never shown. The warn is group-level, so it still
1090-
* covers the whole group. The demand is the half that is premature.
1088+
* ⛔ The warn side was not the bug, and it was not softened. While the
1089+
* console's screen-flow runner read only `screens`, a translated flow `label`
1090+
* really was stored and never shown, and the group-level warn said so. The
1091+
* demand was the premature half, and it is the half this gate holds back.
1092+
* The runner now names the flow by `flows.<flow>.label` too, so the row is
1093+
* `live` and the warn and the gate are gone together.
10911094
*
10921095
* ## Shape
10931096
*
10941097
* Group-general, not `flows`-specific, and read from the ledger rather than a
1095-
* switch of our own: the day the row flips to `live` (dropping its
1096-
* `authorWarn`; for `flows` that waits on #20318), the bucket turns itself back
1097-
* on with no edit here — and any FUTURE group that acquires a warn is covered on
1098-
* the day it is marked, rather than re-opening this collision one group at a
1099-
* time.
1098+
* switch of our own: when the `flows` row flipped to `live` and dropped its
1099+
* `authorWarn`, the bucket turned itself back on with no edit here — and any
1100+
* FUTURE group that acquires a warn is covered on the day it is marked, rather
1101+
* than re-opening this collision one group at a time.
11001102
*
11011103
* The join is on the group (`path[0]`) and stops there deliberately: for
11021104
* file-authored bundles the warn side only ever fires at that depth. Its

‎packages/cli/test/i18n-flow-screen-coverage.test.ts‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,26 +29,24 @@
2929
// the spec-exported key face` test below pins list↔walker on this side, so a
3030
// hand-copied list here fails rather than silently offering a key nothing reads.
3131

32-
// ## Why this file simulates a `live` ledger row (#11624)
32+
// ## Why this file simulates a `live` ledger row
3333
//
3434
// Everything below is the behaviour of the flow bucket ITSELF — which keys the
3535
// walker harvests, how the coverage report attributes them, what the skeleton
36-
// looks like. None of it changed in #11624. What changed is WHEN it runs: the
37-
// `flows` row in `@objectstack/spec/liveness/translation.json` is `planned` +
38-
// `authorWarn`, and `os lint` runs this bucket in the SAME pass as
39-
// `lintLivenessProperties`, so demanding the keys while the ledger warns
40-
// authors for writing them left the author with no move that satisfies both.
41-
// The bucket is now gated on that row, and it turns itself back on the day the
42-
// row flips to `live` (dropping its `authorWarn`; for `flows` that waits on
43-
// #20318).
36+
// looks like. WHEN it runs is the ledger's call: the bucket is gated on the
37+
// `flows` row in `@objectstack/spec/liveness/translation.json`. While that row
38+
// was `planned` + `authorWarn`, `os lint` would have demanded the keys in the
39+
// same pass that warned authors for writing them, leaving no move that
40+
// satisfies both, so the walk left the group out. The row is `live` now (the
41+
// runner reads the flow's own `label` as well as `screens`), and the bucket is
42+
// back on with no edit to the walker.
4443
//
45-
// So these pins are re-anchored, not retired: the mock below is the ledger
46-
// warning on nothing, i.e. exactly the post-flip world. Retiring them instead
47-
// would have left the flip with no proof the bucket still works, and a pin that
48-
// "passes" because the walker now emits nothing is the worst of both. The
49-
// GATED half — that none of this reaches an author while the row is `planned`
50-
// — is pinned next door in `i18n-flow-liveness-gate.test.ts`, against the real
51-
// shipped ledger.
44+
// The mock below pins the ledger to "warns on nothing", which today is also
45+
// the real ledger's state. It stays so that these pins keep measuring the
46+
// bucket whatever the shipped ledger says next: a pin that "passes" because
47+
// the walker emits nothing is the worst of both. The GATED half — what the
48+
// walk does for a group the ledger DOES warn on — is pinned next door in
49+
// `i18n-flow-liveness-gate.test.ts`, which also pins the real shipped ledger.
5250
//
5351
// The mock is fail-loud: if it stopped applying, every `expect(...).toContain`
5452
// below would go red rather than silently assert over an empty walk.

‎packages/spec/src/system/i18n-resolver.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3991,10 +3991,11 @@ export function resolveFlowScreenTitle(
39913991
* draws, read at the `.objectui-sha` pin `f8a9d0fb`, and the ledger's
39923992
* `flows.screens` row is `live` citing it. This function stays unregistered
39933993
* because the server-side route is not the one taken. `flows.<flow>.label`
3994-
* takes the same client side: the authored label it falls back to reaches the
3995-
* runner on every run result as `AutomationResult.flowLabel`, but nothing reads
3996-
* the translation key on either side yet (the objectui runner half is still to
3997-
* land), so its ledger row stays `planned`.
3994+
* takes the same client side: `FlowRunner` hands this function the authored
3995+
* label the engine serves on every run result as `AutomationResult.flowLabel`,
3996+
* and draws the answer (the API name when no label was served) in its header
3997+
* and its completion toast, read at the `.objectui-sha` pin `0abd4f9f8`. Both
3998+
* `flows` rows in the ledger are `live`.
39983999
*/
39994000
export function translateFlow<T extends FlowLike>(
40004001
flow: T,

0 commit comments

Comments
 (0)