feat(lint): warn when a form section has a label but no name — the heading no key can address (#5417) (#5455)

`_sections` is keyed by the section's `name`, and every renderer resolves a
section heading that way (`sectionLabel(objectName, section.name, authored)`),
falling back to the authored label when there is no name. So a section
authored with a `label` and no `name` is untranslatable by construction — and
both existing gates are structurally blind to it: there is no orphan key for
`validateTranslationReferences` to report, and the coverage walker (#5405)
emits one expected key per `sections[].name`, so a nameless section demands
nothing and the report reads 100%.

Measured: 70/70 HotCRM form-view sections are in that state at full declared
coverage; `os validate` over examples/app-showcase reports 14 (6 form views,
8 record:details pages) and still exits 0.

`validateTranslatableSections` (`translation-section-name-missing`) joins the
reference-integrity suite, so it runs on validate/lint/compile at once, and
reads exactly the anchors #5416's walker and #5422's fact set already agree
on — a container's `sections`, its DEFAULT `form.sections`, every
`listViews.*`/`formViews.*` sub-container, the same three on object-embedded
views, and `record:details` sections anywhere in a page's component tree via
the shared `walkPageComponents`. fieldGroups-derived sections are out of range
by construction (their key IS the name), as is a name-keyed `sections` map.

Warning, and opt-in: a section warns only when the object it renders under
carries some translation of its own, so a monolingual stack stays silent
exactly as `computeI18nCoverage` does. The fix is a diagnostic at the
producer — slugifying the label into a lookup key would fossilize a second
de-facto contract next to the declared one (Prime Directive #12, and the
renderer guard objectui#3373 pinned as correct).

Per the PM ruling on the issue, requiring `name` on `FormSection` outright
(the schema route) is a breaking authoring change left to the maintainer;
packages/spec is untouched.


Claude-Session: https://claude.ai/code/session_016FNvXhtSdnEGEfLEsMmvxh

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

.changeset/lint-translatable-sections.md

@@ -0,0 +1,47 @@
+---
+'@objectstack/lint': patch
+---
+
+lint: warn when a form section declares a `label` but no `name` — the heading no translation key can ever address
+
+`_sections` is keyed by the section's `name`, and every renderer that draws a
+section heading resolves it that way (`sectionLabel(objectName, section.name,
+authored)` — `plugin-form`'s `ObjectForm`/`ModalForm`, `plugin-detail`'s
+`record:details`), falling back to the authored label when there is no name.
+So a section authored with a `label` and no `name` is untranslatable **by
+construction**, and every gate we own was structurally blind to it:
+
+- the reference validator reports keys a bundle carries that nothing declares —
+  a nameless section produces no key, so there is no orphan to report;
+- the i18n coverage walk (#5405) emits one expected key per `sections[].name` —
+  a section with no name contributes nothing to demand, so the report reads
+  100% while the heading renders in the source locale in every locale.
+
+Measured on HotCRM: **70 of 70** form-view sections across all 14 view files are
+in exactly that state, with four locales at full declared coverage and zero
+warnings anywhere. It is also the real cause of the reported `Case / SLA /
+Resolution` English strip — that object's *detail page* sections carry names and
+translate, while its *form view* sections carry none.
+
+`validateTranslatableSections` (rule id `translation-section-name-missing`) joins
+the reference-integrity suite, so it runs on `os validate`, `os lint` and
+`os compile` at once. It reads exactly the anchors the two landed halves already
+agree on: a view container's `sections`, its **default** `form.sections`, every
+`listViews.*` / `formViews.*` sub-container, the same three on views embedded in
+an object, and `record:details` sections nested anywhere in a page's component
+tree. `fieldGroups`-derived sections are out of range by construction — their
+heading is keyed by `fieldGroups[].key`, so they always have a name.
+
+**Warning, and opt-in.** Nothing crashes and nothing is dead — one heading stays
+in the source locale — so the severity matches its sibling rules (ADR-0072 D1)
+and nothing that passed before starts failing. `os validate` over
+`examples/app-showcase` now reports 14 of these (6 from form views, 8 from
+`record:details` pages) and still exits 0. A section warns only when the
+object it renders under carries some translation of its own, which keeps the
+monolingual case silent exactly as the coverage gate already does.
+
+The fix is a diagnostic at the **producer**, deliberately not tolerance at the
+consumer: deriving a lookup key by slugifying the label would fossilize a second
+de-facto contract next to the declared one, and would move the day anyone edits
+the heading text. The `name` the hint suggests is a suggestion for the author to
+write down, never a key anything resolves.

packages/lint/src/index.ts

@@ -311,6 +311,18 @@ export type {
   TranslationRefSeverity,
 } from './validate-translation-references.js';
 
+// The other end of the same question (#5417): a form section authored with a
+// `label` and no `name` renders a heading `_sections` can never address — no
+// orphan key to report, and nothing for the coverage walk to demand.
+export {
+  validateTranslatableSections,
+  TRANSLATION_SECTION_NAME_MISSING,
+} from './validate-translatable-sections.js';
+export type {
+  TranslatableSectionFinding,
+  TranslatableSectionSeverity,
+} from './validate-translatable-sections.js';
+
 export {
   validateAiSurfaceAffinity,
   AI_SKILL_SURFACE_MISMATCH,

packages/lint/src/reference-integrity-suite.test.ts

@@ -23,6 +23,7 @@ describe('reference-integrity suite — membership', () => {
       'validateNavAccess',
       'validateNavTargetRefs',
       'validateTranslationReferences',
+      'validateTranslatableSections',
       'validateFlowTemplatePaths',
       'validateAiSurfaceAffinity',
       'validateAiToolReferences',
@@ -94,6 +95,15 @@ describe('reference-integrity suite — every member actually runs', () => {
           // validateActionNameRefs: no such action.
           bulkActions: ['mass_update'],
         },
+        // validateTranslatableSections (#5417): a form section authored with a
+        // `label` and no `name`. `_sections` is keyed by name, so this heading
+        // has no key any bundle can carry — and crm_lead IS translated below,
+        // which is what opens the rule's opt-in gate.
+        form: {
+          type: 'simple',
+          data: { provider: 'object', object: 'crm_lead' },
+          sections: [{ label: 'Qualification', columns: 2, fields: ['name'] }],
+        },
       },
     ],
     pages: [
@@ -228,6 +238,7 @@ describe('reference-integrity suite — every member actually runs', () => {
     expect(rules).toContain('chart-measure-unknown');
     expect(rules).toContain('nav-object-ungranted');
     expect(rules).toContain('translation-target-unknown');
+    expect(rules).toContain('translation-section-name-missing');
     expect(rules).toContain('flow-template-unknown-field');
     expect(rules).toContain('ai-skill-surface-mismatch');
     expect(rules).toContain('ai-skill-tool-unresolved');

packages/lint/src/reference-integrity-suite.ts

@@ -62,6 +62,7 @@ import { validateChartBindings } from './validate-chart-bindings.js';
 import { validateNavAccess } from './validate-nav-access.js';
 import { validateNavTargetRefs } from './validate-nav-target-refs.js';
 import { validateTranslationReferences } from './validate-translation-references.js';
+import { validateTranslatableSections } from './validate-translatable-sections.js';
 import { validateFlowTemplatePaths } from './validate-flow-template-paths.js';
 import { validateAiSurfaceAffinity } from './validate-ai-surface-affinity.js';
 import { validateAiToolReferences } from './validate-ai-tool-references.js';
@@ -120,6 +121,14 @@ export const REFERENCE_INTEGRITY_RULES: readonly ReferenceIntegrityRule[] = [
   // `component` (an unregistered ref renders a named diagnostic, not silence).
   { name: 'validateNavTargetRefs', run: validateNavTargetRefs },
   { name: 'validateTranslationReferences', run: validateTranslationReferences },
+  // The same family from the other end (#5417). Its sibling above asks "does
+  // this bundle key resolve?"; this one asks "is there a key at all?" — a form
+  // section authored with a `label` and no `name` renders a heading that
+  // `_sections` (keyed by name) can never address, so neither the orphan check
+  // nor the coverage walk can see it. A reference that cannot be written is
+  // still a reference question, and warning-only for the same reason its
+  // sibling is: one heading stays in the source locale, nothing breaks.
+  { name: 'validateTranslatableSections', run: validateTranslatableSections },
   { name: 'validateFlowTemplatePaths', run: validateFlowTemplatePaths },
   { name: 'validateAiSurfaceAffinity', run: validateAiSurfaceAffinity },
   { name: 'validateAiToolReferences', run: validateAiToolReferences },