Repository navigation
Commit f3a3afc
docs(i18n): restate the orphan-key table from the emitter, sibling packages included (#19839)
Fixes #19626
Clause-②: no
## What changed
The orphan-key table under **Orphan Keys and Option Keys** in
`content/docs/protocol/kernel/i18n-standard.mdx` is rewritten as one
unit, row by row from the emitter of `translation-target-unknown` on
`origin/main` (`1cacfe4a`). It no longer uses the old rule.
- **Row 1 was false and is corrected.** `objects.{object}` said "an
object this stack defines, or a platform object". On the per-package
pass, an object that a **sibling package of the same artifact** declares
also resolves, and its subtree is judged against that sibling's
declaration. The row now says so. It also names rung 2b, which was
missing: an object an `objectExtensions[]` entry extends but no package
of the artifact declares is skipped whole.
- **"Declared" is now defined once, above the table.** It means declared
by the stack being checked or by a sibling package of the same artifact.
The six vague rows (`_views`, `_sections`, `_actions`, `apps.*`,
`dashboards.*`, `globalActions`) now inherit that meaning instead of
each implying "this stack". A short rule also covers what happens when
the package and a sibling declare the same name: the package's own
record is used to judge options, params, widgets and header actions, and
flow screens.
- **Rows the emitter judges but the table never listed are added:**
`_tabs`, `_validations`, `flows.{flow}`, `.screens.{node}` and
`.fields.{field}`. The contributed-into app level
(`navigationContributions`) is also added.
- **Rows that were vague but not false are made exact:** `_views` (the
key the registry assigns, `default` for an unnamed default list),
`_sections` (all three anchors), `fields` (extension-merged fields and
system columns), and `globalActions` (a bound action gets a redirect,
not a match).
- `content/docs/deployment/validating-metadata.mdx`: the per-package
sentence ("so a sibling package's object still resolves") now also names
the collections a translation key resolves the same way, and links to
the table.
The emitter covers more than the card listed. The card named six
understated rungs. `artifactProvidedRecords` is also called for `flows`
and `pages`, and `pages` feeds `_tabs` and `record:details` `_sections`.
So a sibling's flow, filter-preset tab or page section resolves too.
Where the emitter and the card disagree, the table follows the emitter.
## Code sites each row is backed by
All in `packages/lint/src/validate-translation-references.ts` at
`1cacfe4a`:
| Row | Site |
|:---|:---|
| sibling reach (all rows) | `artifactProvidedRecords` :919 (reads
`packages[].manifest.COLLECTION`); calls for `objects` :1019, `views`
:1081, `pages` :1114, `actions` :1152, `apps` :1211, `dashboards` :1282,
`flows` :1331 |
| own-record precedence | `ownDeclaration` in `collectObjectRecord`
:950, `collectActionRecord` :1137, `collectDashboardRecord` :1261,
`collectFlowRecord` :1306 |
| `objects.{object}` | :1379-1421: universe hit,
`isPlatformProvidedObjectName` skip, `universe.extended` skip (rung 2b),
otherwise orphan; `objectExtensionsByTarget` :834 reads stack and
`packages[]` |
| `.fields.{field}` | `IMPLICIT_FIELDS` :284 (`SYSTEM_FIELDS` +
`_id`/`name`/`space`); extension fold :1042-1070; check :1423 |
| `.options.{key}` | `checkOptionKeys` :1778 (warning,
`translation-option-key-unknown`) |
| `._views.{view}` | `collectViewRecord` :421, `defaultListViewKey`
:574, `namedViewKeys` :612 (composer-derived keys) |
| `._sections.{section}` | `fieldGroups[].key` in `collectObjectRecord`;
`addSections` for `formViews`, the default `form` and the view record in
`collectViewRecord`; `record:details` `properties.sections` in
`collectPageRecord` :1093 |
| `._tabs.{tab}` | `collectPageTabs` :525 (`interfaceConfig.source`,
else `page.object`; `userFilters.tabs[].name`); check :1484 |
| `._validations.{rule}` | `collectValidationRuleNames` :238
(conditional branches), extension fold; check :1513 |
| `._actions.{action}` / `.params.{param}` | `collectActionRecord`
(owner = `objectName` / `object`); `checkActionParams` :1834 |
| `globalActions.{action}` | :1564-1597, bound-action redirect via
`actionOwners` |
| `apps.{app}` / `.navigation.{id}` | `collectAppRecord` (declared +
sibling), `contributedNavItemsByApp` :738 (stack `manifest` +
`packages[]`), `contributedOnlyApps` pass; check :1599-1652 |
| `dashboards.*` | `collectDashboardRecord`; check :1653-1695 |
| `flows.*` | `collectFlowRecord` (`walkFlowNodes`, `type: 'screen'`,
`config.fields[].name`, object-form diagnosis); check :1696-1760 |
The sibling behaviour for each rung is pinned in
`validate-translation-references.test.ts`, in the two describe blocks
for objects a sibling package of the artifact declares (from :1253) and
for collection rungs a sibling package declares (from :1463).
## Scope and changeset
Docs only: `content/docs/**`, which is not a governed surface and
publishes no package. No `.changeset` file is needed; by the `files[]`
criterion this is `skip-changeset` territory, and the label is left to
the PM seat. `skills/objectstack-i18n/SKILL.md` is deliberately **not**
touched, per the triage ruling.
## Verification
- Derived with `node scripts/pm/dispatch-gates.mjs --repo
objectstack-ai/objectstack --commands` at head `c61ae6d4`: 40 commands.
All 40 ran with exit 0. Four of them (`check:doc-formula-expressions`,
`check:doc-security-posture`, `check:skill-examples`,
`check:docs-transcript-drift`) first exited 3 (PREREQUISITE NOT MET,
nothing measured). I built their named prerequisites (the lint, formula
and client-react closures, plus spec) and re-ran them: all exit 0.
- `--ran` reconciliation: "40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN",
which it calls a derived zero because every line recorded an exit code.
- Relevant verdicts: `check-doc-anchors: 368 internal #fragment link(s)
across 410 source file(s) all resolve to a real heading` (this covers
the two new links); `check-nul-bytes: OK`; `check-doc-frontmatter` OK.
- NOT MEASURED locally, left to CI: the `Build Docs` job (the Next.js
docs build), the type-check lanes and the other families listed outside
the derived set.
## Acceptance notes
- The ladder comment in the emitter's own header
(`validate-translation-references.ts:122-123`) still says rungs 3 and 4
"warn on the object key only", but both go through `orphan()` at
`TRANSLATION_TARGET_UNKNOWN_SEVERITY = 'error'`. This is comment drift
inside the code, not a defect under class a, b or c, and it was not
changed here (docs-only scope). No carrier.
- `collectViewRecord` also registers a view record's root `name` as a
`_views` key. The table describes the composer's keys (map key, or
`default`) as the canonical spelling and does not list this edge.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent 08b213e commit f3a3afc
2 files changed
Lines changed: 36 additions & 13 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
623 | 623 | | |
624 | 624 | | |
625 | 625 | | |
626 | | - | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
627 | 630 | | |
628 | 631 | | |
629 | 632 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1019 | 1019 | | |
1020 | 1020 | | |
1021 | 1021 | | |
1022 | | - | |
1023 | | - | |
1024 | | - | |
| 1022 | + | |
| 1023 | + | |
| 1024 | + | |
| 1025 | + | |
| 1026 | + | |
| 1027 | + | |
| 1028 | + | |
| 1029 | + | |
| 1030 | + | |
| 1031 | + | |
| 1032 | + | |
| 1033 | + | |
| 1034 | + | |
| 1035 | + | |
| 1036 | + | |
| 1037 | + | |
| 1038 | + | |
1025 | 1039 | | |
1026 | | - | |
1027 | | - | |
| 1040 | + | |
| 1041 | + | |
1028 | 1042 | | |
1029 | | - | |
1030 | | - | |
1031 | | - | |
1032 | | - | |
1033 | | - | |
1034 | | - | |
1035 | | - | |
| 1043 | + | |
| 1044 | + | |
| 1045 | + | |
| 1046 | + | |
| 1047 | + | |
| 1048 | + | |
| 1049 | + | |
| 1050 | + | |
| 1051 | + | |
| 1052 | + | |
| 1053 | + | |
| 1054 | + | |
| 1055 | + | |
1036 | 1056 | | |
1037 | 1057 | | |
1038 | 1058 | | |
| |||
0 commit comments