Skip to content

Commit aeac74b

Browse files
fix(metadata-protocol): a form view naming a field its object lacks reads with the lint's form-field-unknown warning (#29307)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9MP94x2mHLb3VMeZqcfx4Es)_ Fixes #29196 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:表单视图的分区里写了对象上不存在的字段时,`/meta` 读取(已发布、草稿、草稿预览)的 `_diagnostics.warnings` 现在会带上 lint 规则 `form-field-unknown` 的原文警告,定位到具体字段引用。 - 为什么改:这种表单以前保存、发布、读取都显示 `valid: true`,作者完全不知道字段被静默跳过;规则早就有,只是只在 CLI 里跑。 - 风险与回滚:只加警告,不改 `valid`、不拒绝保存或发布;列表读取不受影响。回滚即还原本 PR,无数据迁移。 - 先看:`packages/metadata-protocol/src/metadata-diagnostics.ts`(`withFormLayoutWarnings`,ViewItem 的 `config` 适配与对象查找),`packages/metadata-protocol/src/protocol.ts`(读取出口的三处接线),`packages/metadata-protocol/src/protocol.form-layout-diagnostics.test.ts`。 - 两分钟验证:`pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.form-layout-diagnostics.test.ts`,预期 4 个用例全绿;在 main 上同一命令有 2 个红。 - 需要你做的:无,席位落地。 ## What changes `validateFormLayout` (`@objectstack/lint`) reports a form section field the bound object does not have as `form-field-unknown` ("is silently skipped and never renders on the form"). It ran only in the CLI, so the meta door served such a view with `_diagnostics: { valid: true }`. - **`withFormLayoutWarnings`** (new, `metadata-diagnostics.ts`): runs `validateFormLayout` on the served view body and appends each `form-field-unknown` finding to `_diagnostics.warnings` as the spec's `{ path, message }`, with the rule's own message and an item-relative path. `valid` and `errors` are left as they were. - A stored form `ViewItem` (`viewKind: 'form'`) keeps its form under `config`, a rung the lint's view walk does not descend. It is handed to the rule as the container shape the walk reads (`{ name, object, form: config }`), and the finding's `form.` path is mapped back to `config.` (QA's reproduction reads `config.sections.0.fields.1`). Containers and flattened form overlays are the walk's own input already. - The object universe is the door's own lookup: `registry.getObject(name)` (the served object, extensions folded on) for each object name the body spells. A name it cannot resolve is left out, so that form is not judged and gets no warning. - `@objectstack/lint` is imported lazily from its root on the first view read, the way `build-probes.ts` loads `validateObjectFieldRefs`. The kernel boot path still reaches the package only through `/runtime`. - **`readMetaItem`** (`protocol.ts`): the pass runs at every served exit of the single-item read: the active read (after the ADR-0047 reference merge, which rebuilds `_diagnostics` from its errors), the strict draft read, and the draft-preview arm (both through `serveDraft`, before the #26707 publish verdict is folded in). The execution face serves no `_diagnostics` and is untouched. `getMetaItems` (the list read) is untouched. Which attach site the served read uses: `@objectstack/metadata-protocol`'s `readMetaItem` (`decorateMetadataItem` plus the view reference merge). The card's `packages/metadata/src/metadata-manager.ts` is not on that path. ## Tests - New `packages/metadata-protocol/src/protocol.form-layout-diagnostics.test.ts`, through the protocol's own save, publish and read (the methods `PUT /meta/view/NAME?mode=draft`, `POST .../publish` and `GET` call), with the stub engine shape of `protocol.draft-publish-verdict.test.ts`: 1. QA's ViewItem body: the draft saves, its read carries the warning, the publish is not refused, and the active read carries the same warning. The message is compared against `validateFormLayout` run in the same test. 2. A view container's `formViews.edit` is judged and located under its own key. 3. Control: a form naming only fields the served object has (one of them only on the served object, not the authored one) reads exactly `{ valid: true }`, draft and active. 4. A form whose object does not resolve reads exactly `{ valid: true }`. - Forced edit: `scripts/engine-double-contract.pinned.json` gains the new file's three engine-double rows (`check:engine-double-contract`'s own `--write`). ## Acceptance notes - The warning carries no rule id on the read wire: `MetadataValidationResultSchema.warnings` entries are `{ path, message }` in the spec, the shape the read's other derived warnings already use. Carrying `code` is a spec widening, left as an open question in the card report. - The save and publish responses' `advisories` do not carry this finding: `validateFormLayout` is CLI-only on the runtime publish surface in the lint registry. Crossing it is a registry decision, left as an open question. - `form-section-group-unknown`, the rule's sibling finding, is not surfaced at the door (this card names `form-field-unknown` only). - The layered read (`?layers=true`) `_diagnostics` stays schema-only, as it already is for the ADR-0047 reference errors. - Studio: `ResourceEditPage` already renders `_diagnostics.warnings` with their paths. The form designer canvas has no reader of them; named as a `domain:ui` follow-up in the card report. - Cost: about 25 µs per single view read (2000 reads of a 6-section, 36-field form against a 40-field object, measured in-process). The list read pays nothing. ## Verification Head `1560285c` (main merged at `eed73a39`). Every run below goes through `scripts/pm/os-verify-lock.sh`; each line quotes the run's own verdict. <details><summary>Red first on main (104cd1a, test only)</summary> `vitest run src/protocol.form-layout-diagnostics.test.ts`: `Tests 2 failed | 2 passed (4)`. Failing: the ViewItem case at the draft read (`expected { valid: true } to deeply equal { valid: true, warnings: [ { …(2) } ] }`) and the container case (`expected undefined to deeply equal [ { …(2) } ]`). The two controls passed. </details> <details><summary>Green on the fix</summary> - The pin: `Tests 4 passed (4)`. - `pnpm --filter @objectstack/metadata-protocol typecheck && pnpm --filter @objectstack/metadata-protocol test` on `1560285c`: `VERDICT command-exit 0`, `Test Files 301 passed | 4 skipped (305)`, `Tests 22111 passed | 26 skipped (22137)`. - eslint (`eslint.js packages/metadata-protocol --no-inline-config`): exit 0. </details> <details><summary>Ablations (scripts/ablation-replace.mjs, each restored to the HEAD blob with an empty git diff HEAD)</summary> Run on `42185878`, the fix before the two main merges; neither merge touched `readMetaItem` or `metadata-diagnostics.ts`. - A, the active-exit call deleted from `readMetaItem`: `Tests 1 failed | 3 passed`, the ViewItem case red at the active read. - B, an unresolvable object name given an empty field set instead of being left out: `Tests 1 failed | 3 passed`, the unresolvable-object case red. - C, the lookup switched from `registry.getObject` to the authored `listItems('object')`: `Tests 1 failed | 3 passed`, the served-object control red (`region__c` reported). </details> <details><summary>Gates</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` on `1560285c`: 70 commands, all exit 0 (after a full `turbo run build --filter='./packages/**'`). `--ran` reconciliation: `70 derived famil(ies) accounted for — 70 run, 0 NOT-MEASURED (a DERIVED zero)`. </details> No `!` in the title and no `(narrowing)` arm, so the full dogfood battery is not owed. --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmQM9W8oVztX5XNAQaN)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent a2fcede commit aeac74b

5 files changed

Lines changed: 425 additions & 2 deletions

File tree

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@objectstack/metadata-protocol': patch
3+
---
4+
5+
fix(metadata-protocol): a form view naming a field its object lacks reads with the lint's `form-field-unknown` warning in `_diagnostics`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
A form section that names a field the bound object does not have (a typo, or a field deleted later) is valid against the view schema, so the `/meta` door saved it, published it and served it with `_diagnostics: { valid: true }`, while the record form skips the field. The `validateFormLayout` lint rule that reports it ran only in the CLI (`os validate`, `os build`, `os lint`).
11+
12+
The served view read (`GET /api/v1/meta/view/NAME`, the strict draft read and the draft preview) now runs that rule on the body it serves and adds each `form-field-unknown` finding to `_diagnostics.warnings`, located at the field reference (for a stored form view item, `config.sections.N.fields.M`) and worded exactly as the rule words it:
13+
14+
- **A warning, not a refusal.** `valid` stays the schema's answer. A draft still saves and a publish is not refused by it.
15+
- **The object the door serves.** Field names are judged against the object the registry serves for each object name the view spells, extensions included. A view whose object does not resolve is not judged, so it gets no warning.
16+
- **Single-item reads only.** The list read (`GET /api/v1/meta/view`) is unchanged and pays no object lookup.

‎packages/metadata-protocol/src/metadata-diagnostics.ts‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,122 @@ export function withPublishVerdict(
431431
};
432432
}
433433

434+
// ---------------------------------------------------------------------------
435+
// [#29196] The lint's `form-field-unknown` on a served view's `_diagnostics`
436+
// ---------------------------------------------------------------------------
437+
//
438+
// A form section naming a field its object does not have is Zod-valid, so the
439+
// schema verdict above reads `valid: true`, and the renderer skips the field.
440+
// `validateFormLayout` (`@objectstack/lint`) is the rule that says so, and it
441+
// ran only in the CLI. The view read now runs that rule on the body it serves
442+
// and puts each `form-field-unknown` finding in `_diagnostics.warnings`, with
443+
// the rule's own message: one spelling, no second rule.
444+
//
445+
// A WARNING, never an error: the spec's `MetadataValidationResult` calls
446+
// warnings non-blocking, `valid` stays the schema's answer, and neither a save
447+
// nor a publish reads it. The entry is the spec's `{ path, message }`, the
448+
// shape the read's other derived warnings already take (the admin read's
449+
// anonymous-intake reasons, a view container's rename note).
450+
//
451+
// The field set is the one the door already resolves for the view: the
452+
// caller's object lookup (`registry.getObject` at the read, the served object
453+
// with its extensions folded on), asked for the object names the body itself
454+
// spells. A name it cannot resolve is left out of the universe, and the rule
455+
// then judges nothing for that form: no false warning.
456+
//
457+
// Loaded lazily from the package root, as `build-probes.ts` loads its lint
458+
// rule: the kernel boot path reaches `@objectstack/lint` only through its
459+
// `/runtime` entry, and a view read is where this one is first needed.
460+
461+
/** The two names this pass reads from `@objectstack/lint`. */
462+
interface FormLayoutLint {
463+
validateFormLayout: (stack: Record<string, unknown>) => ReadonlyArray<{ rule: string; path: string; message: string }>;
464+
FORM_FIELD_UNKNOWN: string;
465+
}
466+
467+
let formLayoutLint: Promise<FormLayoutLint | undefined> | undefined;
468+
469+
function loadFormLayoutLint(): Promise<FormLayoutLint | undefined> {
470+
formLayoutLint ??= import('@objectstack/lint').then(
471+
(lint) => ({ validateFormLayout: lint.validateFormLayout, FORM_FIELD_UNKNOWN: lint.FORM_FIELD_UNKNOWN }),
472+
() => undefined,
473+
);
474+
return formLayoutLint;
475+
}
476+
477+
type Rec = Record<string, unknown>;
478+
479+
function isRec(value: unknown): value is Rec {
480+
return !!value && typeof value === 'object' && !Array.isArray(value);
481+
}
482+
483+
/**
484+
* The record the lint's view walk reads for one served view body. A stored
485+
* form `ViewItem` (`viewKind: 'form'`) keeps its form under `config`, a rung
486+
* the walk does not descend (it reads `views[]` entries as authored), so it is
487+
* handed over as the container shape the walk does read: the item's `config`
488+
* as the default `form`, bound to the item's `object`. Every other shape (a
489+
* view container, a flattened form overlay) is the walk's own input already.
490+
*/
491+
function formLayoutSubject(view: Rec): { subject: Rec; formKey: 'config' | 'form' } {
492+
if (view.viewKind === 'form' && isRec(view.config)) {
493+
return { subject: { name: view.name, object: view.object, form: view.config }, formKey: 'config' };
494+
}
495+
return { subject: view, formKey: 'form' };
496+
}
497+
498+
/** Every object name the body spells (`object` / `objectName`), at any depth. */
499+
function spelledObjectNames(value: unknown, into: Set<string>, depth = 0): Set<string> {
500+
if (depth > 16) return into;
501+
if (Array.isArray(value)) {
502+
for (const entry of value) spelledObjectNames(entry, into, depth + 1);
503+
} else if (isRec(value)) {
504+
for (const [key, inner] of Object.entries(value)) {
505+
if ((key === 'object' || key === 'objectName') && typeof inner === 'string' && inner) into.add(inner);
506+
else spelledObjectNames(inner, into, depth + 1);
507+
}
508+
}
509+
return into;
510+
}
511+
512+
/**
513+
* Add the lint's `form-field-unknown` warnings to a served view's
514+
* `_diagnostics`. Returns `served` itself when there is nothing to add.
515+
*
516+
* `getObject` is the door's own object lookup; an object it does not answer
517+
* is not judged.
518+
*/
519+
export async function withFormLayoutWarnings<T>(
520+
type: string,
521+
served: T,
522+
getObject: ((name: string) => unknown) | undefined,
523+
): Promise<T> {
524+
if ((PLURAL_TO_SINGULAR[type] ?? type) !== 'view' || !isRec(served) || !getObject) return served;
525+
const lint = await loadFormLayoutLint();
526+
if (!lint) return served;
527+
const { subject, formKey } = formLayoutSubject(served);
528+
const objects: Rec[] = [];
529+
for (const name of spelledObjectNames(subject, new Set())) {
530+
const object = getObject(name);
531+
if (isRec(object)) objects.push({ ...object, name });
532+
}
533+
if (objects.length === 0) return served;
534+
const name = typeof served.name === 'string' ? served.name : '';
535+
const warnings = lint.validateFormLayout({ objects, views: [subject] })
536+
.filter((finding) => finding.rule === lint.FORM_FIELD_UNKNOWN)
537+
.map((finding) => ({
538+
path: itemRelativeIssuePath('view', name, finding.path).replace(/^form(?=\.|$)/, formKey),
539+
message: finding.message,
540+
}));
541+
if (warnings.length === 0) return served;
542+
const prior = served._diagnostics as MetadataDiagnostics | undefined;
543+
const diagnostics: MetadataDiagnostics = {
544+
...(prior ?? { valid: true }),
545+
warnings: [...(prior?.warnings ?? []), ...warnings],
546+
};
547+
return { ...served, _diagnostics: diagnostics } as T;
548+
}
549+
434550
// ---------------------------------------------------------------------------
435551
// ADR-0047 — reference-integrity diagnostics for list views
436552
// ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)