finding: `app-shell/utils/metadataConverters.ts` has zero importers — a dead module still carrying a name-heuristic `isSystem` and a `referenceTo` tolerance

[yinlianghui]

Observation-class finding, surfaced while re-deriving the read/write sites for objectui#6041 and objectui#6044. No live defect — the code is unreachable, which is the finding. Filed unassigned; finding, deliberately not pm:queue.

Measured

On origin/main @ 7da7b8a1d:

grep -rn "metadataConverters" --include=*.ts --include=*.tsx . \
 --exclude-dir=node_modules --exclude-dir=dist | grep -v "utils/metadataConverters.ts:"
 => no output

grep -n "metadataConverters\|toFieldDefinition" packages/app-shell/dist/index.d.ts
 => no output

So toObjectDefinition and toFieldDefinition are exported from the module, imported by nothing in the repo, and not re-exported from @object-ui/app-shell's published entry (exports declares . and ./styles.css only). Control that the instrument works: the same grep for a module that is reachable, packages/app-shell/src/services/MetadataService.ts, returns importers.

Why it is worth recording rather than ignoring

The module is a second, independent copy of the designer's read-direction converter, and it disagrees with the one that is live:

• toFieldDefinition derives the system-field flag from a name heuristic — field.readonly === true && (field.name === 'id' || field.name === 'createdAt' || field.name === 'updatedAt') — rather than from the spec's system flag. That is the same dead detection objectui#6044 just repaired in MetadataFieldsPage.toDesignerField, in a shape a grep for the misspelling does not find, and with a spelling (createdAt) the spec does not use (created_at).
• Its MetadataField interface declares referenceTo and reads field.reference_to || field.reference || field.referenceTo — a three-way tolerance for a target the spec spells reference, which objectui#6041 has now made the single spelling on both wire-bound shapes.

A dead copy that disagrees with the live one is the thing that gets revived by a future author looking for "the converter", so the two candidate resolutions are: delete the module (the #4687 shape), or point it at the shared classifiers that already exist — isSystemManagedField in @object-ui/types branches on the spec system flag, and reference-keys.ts in @object-ui/core already owns the target-key read.

Adjacent, same family, not filed separately

packages/plugin-dashboard/src/recordFields.tsx line 56 reads if (def && (def.isSystem === true || def.system === true)) return true;. The isSystem half of that disjunction can never fire on a spec-parsed field def — FieldSchema refuses the key by name — so it is a consumer-side tolerance for a spelling the platform does not emit. Live code, harmless today, and it belongs to whoever takes the module above.

Refs: #6041 · #6044 · #5761 (the parity gate) · #4687

[claude]

Concentrated triage batch: finding → pm:queue + domain:ui, Task, S — metadataConverters.ts has zero importers and no published re-export (measured with a working positive control), and it still carries a name-heuristic isSystem and a referenceTo tolerance that would mislead the next reader who copies from it. Delete the module (enforce-or-remove; dead code carrying wrong patterns is worse than dead code). If the deletion compile reveals a hidden consumer the grep missed, stop and report.

---

Generated by Claude Code

[yinlianghui]

Claimed + dispatched — domain:ui @ objectui execution seat

PM session session_01CSoz9uGhaaSgiq3hshtN7L, branch claude/issue-6224-delete-dead-metadataconverters.
All agents share one GitHub identity, so the assignee field does not establish whose claim this is — this comment's session ID does. No earlier claim comment exists on this card.

裁决 (binding)

Delete packages/app-shell/src/utils/metadataConverters.ts. Enforce-or-remove: it has zero importers and no published re-export, and dead code carrying wrong patterns is worse than dead code.

The two wrong patterns are the reason this is a delete rather than a shrug, and they are why leaving it is not neutral:

• a name-heuristic isSystem — the server sends a real system flag, and PR fix(designer,app-shell): spell the designer's lookup target and system marker as the spec does (#6041, #6044) #6225 (Both designer field shapes spell the spec's system flag as isSystem — so system-field detection reads a key the server never sends, and the key round-trips back out as a 422 #6044) just landed the repair that reads it. A dead module deriving the same flag from a name heuristic is a working example of the defect that card closed.
• a referenceTo tolerance — the misspelling PR fix(designer,app-shell): spell the designer's lookup target and system marker as the spec does (#6041, #6044) #6225 (Field designer offers a referenceTo control for lookup fields — a key FieldSchema rejects by name, so saving a lookup field hard-blocks the object #6041) just retired, with referenceTo added to RETIRED_FIELD_KEYS so a stored one cannot ride back out.

⚠️ So this module is not merely unused: it is a copy-paste source for two defects the lane repaired hours ago. That is the whole argument, and it belongs in the PR body.

⛔ Fork clause

If the deletion compile reveals a hidden consumer the grep missed, stop and report. Do not "fix" the consumer, do not keep the module alive with a narrowed export. A live consumer means the card's premise ("zero importers") is false and the resolution is someone else's.

PM机制假设 (verify — the card measured this, but re-derive it)

1. Zero importers, measured with a working positive control — triage says the original measurement carried one, and yours must too. ⚠️ A grep that finds nothing is indistinguishable from a grep that is wrong: prove your search would have found a real importer by pointing it at a module you know is imported.
2. No published re-export — check the package barrel (packages/app-shell/src/index.ts) and the exports map in package.json. ⚠️ Deleting something that is publicly re-exported is a breaking change even with zero in-repo callers; toSortItems — a published export — still tolerantly reads the retired direction sort spelling (s.order || s.direction), dormant because nothing in-tree calls it #6011 tonight was exactly that shape and shipped as a minor with a loud changeset. If it is re-exported, that changes the changeset and must be stated.
3. Confirm the two patterns are still present in the file as described, so the PR body's argument is about today's code.
4. ⚠️ Search for dynamic reach too, not just static imports: require(, template-literal import paths, and any test that imports it. A test-only importer is still an importer — report it rather than deleting the test to make the card work.

Standing verification rules (non-negotiable)

Predict direction before running. Prove the deletion on disk. Print the landing site. Restore under trap … EXIT INT TERM with a cwd-independent command; confirm git diff HEAD --stat empty afterwards (a trap that fires is not a trap that restored — one fired and failed on a repo-relative pathspec tonight, leaving a dirty tree that read as clean). Derive the gate set by enumerating each CI job's own step list. A cached turbo green is not a measurement — use --force.

⚠️ Trap ① — the type-check is the real oracle here, and it is easy to misread. tsc and vitest resolve workspace deps differently, measured tonight: vitest.config.mts aliases @object-ui/* to src/, while tsc resolves through dist (no tsconfig path mapping). So a red after deletion can be an unbuilt sibling package, a real hidden consumer, or both — a dev tonight got 15 errors that were 14 noise + 1 real, and reading it as either "all noise" or "I broke it" would have been wrong. Build the closure first, then re-read, and classify every remaining error by name before concluding.

⚠️ Trap ② — a deletion card's "green" is weak evidence. Nothing goes red when unused code disappears, so a green suite does not confirm the module was unused; it only confirms nothing that runs today touched it. The positive-control grep and the downstream type-check with a built closure are the verification. Say so in the PR body rather than letting green stand in for proof.

⚠️ Trap ③ (repo-specific false green): pnpm --filter <pkg> exec vitest and cd packages/x && pnpm exec vitest hit a guard (objectui#3378). Behaviour differs by invocation form — one dev saw it refuse loudly (ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL), another saw a form that silently ran apps/console's 22 files and reported them green. Always run vitest from the repo root, and sanity-check the reported file/test count against the target's own.

Changeset

⛔ Let check-changeset-presence decide and quote its verdict line. @object-ui/app-shell is a released package, so one is likely owed. If the module turns out to be publicly re-exported, it is a minor naming the removed symbols; if it is genuinely internal, patch. ⛔ Never major.

Collision bounds

Four sibling agents are live: #6176 (packages/plugin-form), #6167 (examples/schema-catalog/** + apps/site/**), #5935 (⚠️ wide — packages/components, packages/plugin-list, packages/plugin-detail + the lucide gate script), #6165 (HomeRail + two sibling consumers).

packages/app-shell/src/utils/ is yours. ⚠️ If #6165's three consumers turn out to live in app-shell, check before editing — different files is fine, same file is not — and report any file-level overlap rather than resolving it yourself.

⛔ Leave the PR draft. Do not mark ready, do not enqueue, do not enable auto-merge — the PM lands it.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 6224,
 "status": "done",
 "branch": "claude/issue-6224-delete-dead-metadataconverters",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6265",
 "premise_still_valid": true,
 "summary": "Deleted packages/app-shell/src/utils/metadataConverters.ts (139 lines) plus a patch changeset for @object-ui/app-shell; no other production change. The card's premise held on every leg: zero importers (static and dynamic), no barrel re-export, and an exports map declaring only '.' and './styles.css'. Both wrong patterns were re-read in today's file before the PR body argued about them — the name-heuristic isSystem (readonly && name in id/createdAt/updatedAt, using a createdAt spelling the spec does not emit) and the three-way reference_to || reference || referenceTo tolerance. The fork clause was NOT triggered: the post-deletion downstream type-check with a built closure and stale dist cleared came back 39/39 with zero TS errors. One detail worth PM attention: the module did compile into dist/utils/metadataConverters.{js,d.ts} and therefore shipped in the tarball, but no exports subpath reaches it, so no external consumer could deep-import it — that is why the changeset is patch and not the minor shape #6011 had.",
 "tests": "All runs serialized through the container's shared verify lock; gate union re-run at final HEAD 4473c3149 (clean tree confirmed). (1) POSITIVE-CONTROL GREP, same shape for every row: services/MetadataService.ts -> 25 files; utils/appRoute.ts -> 60 lines; utils/resolveViewId.ts -> 18; utils/crudAffordances.ts -> 5; utils/metadataConverters.ts -> 0. Whole-repo grep across ALL file types for 'metadataConverters' returns only CHANGELOG/ROADMAP prose. No require(, no dynamic import(, no template-literal import path; packages/app-shell/src has no require( at all; no test imports it. The two toObjectDefinition hits in plugin-designer/src/MetadataObjectsPage.tsx are its OWN local 'function toObjectDefinition(raw: ServerObjectSchema)' at line 85, not an import. (2) PUBLISHED SURFACE: src/index.ts, src/utils/index.ts (all 112 lines) and the freshly built dist/index.d.ts all zero-hit for metadataConverters/toObjectDefinition/toFieldDefinition, while a control grep on the same dist file for resolveHostAppSegment + MetadataDirectoryPage hits. (3) TYPE-CHECK ORACLE, closure built first, both runs --force (cached turbo green is not a measurement): BASELINE before deletion 'Tasks: 39 successful, 39 total / Cached: 0 cached'; AFTER deletion, with the stale dist/utils/metadataConverters.{js,d.ts} deleted first so a dist-resolving consumer could not be masked, 'Tasks: 39 successful, 39 total / Cached: 0 cached', zero 'error TS' lines. Filter '...@object-ui/app-shell' is the DOWNSTREAM direction: app-shell plus @object-ui/console, example-byo-backend-console, example-console-starter. (4) ORACLE CONTROL (ablation, predicted RED, observed RED): a probe file importing './metadataConverters.js' was written into packages/app-shell/src/utils/; landing on disk proved by grep -c on BOTH the injected marker and the import specifier (an editor's exit code is not evidence of a write), not by a bare diff --stat; then 'pnpm --filter @object-ui/app-shell type-check' printed exactly one error — \"src/utils/__oracle_control_6224.ts(1,35): error TS2307: Cannot find module './metadataConverters.js' or its corresponding type declarations. / Exit status 2\" — and the script echoed its own name, so this was not a zero-match no-op. Restored under trap ... EXIT INT TERM with absolute paths, and the restore was VERIFIED: git diff HEAD --stat afterwards showed only ' packages/app-shell/src/utils/metadataConverters.ts | 139 ---------- / 1 file changed, 139 deletions(-)'. (5) VITEST, run from the REPO ROOT per objectui#3378: 'Test Files 26 passed (26) / Tests 453 passed (453)'; sanity-checked against the target's own count (find under packages/app-shell/src/utils = 26 test files, matching — not apps/console's 22). DECLARED NARROWING: app-shell's full suite is 524 files; CI's 4-shard test job covers the rest, and the blast radius is measurably zero since nothing imports the module by any route. (6) GATES, quoting each gate's own verdict line, exit codes captured before any pipe: check-changeset-presence measured RED->GREEN — before, '1 source file(s) of 1 released package(s) changed, and this change adds no changeset: @object-ui/app-shell'; after, '1 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)' (this is the only genuine red-to-green in the PR). check-changeset-no-major 'No changeset declares a major bump'; check-changeset-fixed 'All workspace packages are in the changeset fixed group'; check-control-bytes 'OK (scanned 5168 tracked text file(s))'; check-designer-field-key-parity 'designer-field-key-parity: OK'; check-phantom-dependencies 'Every in-scope import is declared by the package that publishes it'; check-package-self-import 'No package names itself inside its own src/'; check-spec-symbol-derivation 'spec alignment claims: 2 declared deliberate copies, 18 unbacked claims in 5 packages'; check-node-esm-load --specifiers-only 'Specifier leg: no un-ledgered package emits an extensionless relative specifier'; check-lint-coverage '46/46 packages linted, 0 with outstanding errors'; check-type-check-coverage '41/41 packages compile their tests, 0 declared debt'; eslint on app-shell '2678 problems (0 errors, 2678 warnings)' — zero errors, the warnings are the package's pre-existing no-explicit-any baseline; full repo build 'Tasks: 43 successful, 43 total'. check-readme-exports first came back RED with 5 unjudgeable self-imports in @object-ui/cli and @object-ui/plugin-ai ('its type entry ./dist/index.d.ts is not on disk') — the unbuilt-sibling artefact of Trap 1, not this change; rather than assume that, those two packages were built and the gate re-measured 'OK ... 378 self-imports judged (378 real, 0 wrong-path, 0 fabricated) ... 0 unbuilt'. WEAK-EVIDENCE CAVEAT, stated in the PR body too: every assertion in the repo would still pass on a revert of this commit — nothing tests the deleted module, which is the finding. The evidence is the positive-control greps, the published-surface check, the downstream type-check with a built closure, and the oracle control — not the green suite.",
 "open_questions": [],
 "out_of_scope_findings": [
 "not filed as a new issue — already recorded in #6224's own body under 'Adjacent, same family': packages/plugin-dashboard/src/recordFields.tsx:56 reads `def.isSystem === true || def.system === true`, and the isSystem half can never fire on a spec-parsed field def (FieldSchema refuses the key by name). Live code in another package, untouched by this PR, left for PM triage rather than double-filed.",
 "not filed — observation for PM: packages/plugin-designer/src/MetadataObjectsPage.tsx:85 declares its own local `function toObjectDefinition(raw: ServerObjectSchema)`, an independent same-named converter. It is live and spec-typed (ServerObjectSchema), so it is not the dead-copy shape this card removed; naming it only so the next reader does not mistake the surviving hit for a missed importer.",
 "no file-level collision: #6165's HomeRail consumers do live in packages/app-shell, but under src/console/home/ (HomeRail.tsx, HomePage.tsx + tests) — different files from src/utils/metadataConverters.ts. No overlap with #6176, #6167 or #5935."
 ]
}

---

Generated by Claude Code

[yinlianghui]

os-dev-report

(Marker repost. The previous comment carried the HTML-comment form of this marker as its first line; a read-back showed GitHub's sanitizer had eaten it, leaving that comment invisible to a marker scan. No comment-edit path is reachable from this seat — the MCP surface has no editor and direct api.github.com returns 403 — so the report is re-posted here with the literal-text marker. This comment is the authoritative one; the content is identical.)

{
 "issue": 6224,
 "status": "done",
 "branch": "claude/issue-6224-delete-dead-metadataconverters",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6265",
 "premise_still_valid": true,
 "summary": "Deleted packages/app-shell/src/utils/metadataConverters.ts (139 lines) plus a patch changeset for @object-ui/app-shell; no other production change. The card's premise held on every leg: zero importers (static and dynamic), no barrel re-export, and an exports map declaring only '.' and './styles.css'. Both wrong patterns were re-read in today's file before the PR body argued about them — the name-heuristic isSystem (readonly && name in id/createdAt/updatedAt, using a createdAt spelling the spec does not emit) and the three-way reference_to || reference || referenceTo tolerance. The fork clause was NOT triggered: the post-deletion downstream type-check with a built closure and stale dist cleared came back 39/39 with zero TS errors. One detail worth PM attention: the module did compile into dist/utils/metadataConverters.{js,d.ts} and therefore shipped in the tarball, but no exports subpath reaches it, so no external consumer could deep-import it — that is why the changeset is patch and not the minor shape #6011 had.",
 "tests": "All runs serialized through the container's shared verify lock; gate union re-run at final HEAD 4473c3149 (clean tree confirmed). (1) POSITIVE-CONTROL GREP, same shape for every row: services/MetadataService.ts -> 25 files; utils/appRoute.ts -> 60 lines; utils/resolveViewId.ts -> 18; utils/crudAffordances.ts -> 5; utils/metadataConverters.ts -> 0. Whole-repo grep across ALL file types for 'metadataConverters' returns only CHANGELOG/ROADMAP prose. No require(, no dynamic import(, no template-literal import path; packages/app-shell/src has no require( at all; no test imports it. The two toObjectDefinition hits in plugin-designer/src/MetadataObjectsPage.tsx are its OWN local 'function toObjectDefinition(raw: ServerObjectSchema)' at line 85, not an import. (2) PUBLISHED SURFACE: src/index.ts, src/utils/index.ts (all 112 lines) and the freshly built dist/index.d.ts all zero-hit for metadataConverters/toObjectDefinition/toFieldDefinition, while a control grep on the same dist file for resolveHostAppSegment + MetadataDirectoryPage hits. (3) TYPE-CHECK ORACLE, closure built first, both runs --force (cached turbo green is not a measurement): BASELINE before deletion 'Tasks: 39 successful, 39 total / Cached: 0 cached'; AFTER deletion, with the stale dist/utils/metadataConverters.{js,d.ts} deleted first so a dist-resolving consumer could not be masked, 'Tasks: 39 successful, 39 total / Cached: 0 cached', zero 'error TS' lines. Filter '...@object-ui/app-shell' is the DOWNSTREAM direction: app-shell plus @object-ui/console, example-byo-backend-console, example-console-starter. (4) ORACLE CONTROL (ablation, predicted RED, observed RED): a probe file importing './metadataConverters.js' was written into packages/app-shell/src/utils/; landing on disk proved by grep -c on BOTH the injected marker and the import specifier (an editor's exit code is not evidence of a write), not by a bare diff --stat; then 'pnpm --filter @object-ui/app-shell type-check' printed exactly one error — \"src/utils/__oracle_control_6224.ts(1,35): error TS2307: Cannot find module './metadataConverters.js' or its corresponding type declarations. / Exit status 2\" — and the script echoed its own name, so this was not a zero-match no-op. Restored under trap ... EXIT INT TERM with absolute paths, and the restore was VERIFIED: git diff HEAD --stat afterwards showed only ' packages/app-shell/src/utils/metadataConverters.ts | 139 ---------- / 1 file changed, 139 deletions(-)'. (5) VITEST, run from the REPO ROOT per objectui#3378: 'Test Files 26 passed (26) / Tests 453 passed (453)'; sanity-checked against the target's own count (find under packages/app-shell/src/utils = 26 test files, matching — not apps/console's 22). DECLARED NARROWING: app-shell's full suite is 524 files; CI's 4-shard test job covers the rest, and the blast radius is measurably zero since nothing imports the module by any route. (6) GATES, quoting each gate's own verdict line, exit codes captured before any pipe: check-changeset-presence measured RED->GREEN — before, '1 source file(s) of 1 released package(s) changed, and this change adds no changeset: @object-ui/app-shell'; after, '1 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)' (this is the only genuine red-to-green in the PR). check-changeset-no-major 'No changeset declares a major bump'; check-changeset-fixed 'All workspace packages are in the changeset fixed group'; check-control-bytes 'OK (scanned 5168 tracked text file(s))'; check-designer-field-key-parity 'designer-field-key-parity: OK'; check-phantom-dependencies 'Every in-scope import is declared by the package that publishes it'; check-package-self-import 'No package names itself inside its own src/'; check-spec-symbol-derivation 'spec alignment claims: 2 declared deliberate copies, 18 unbacked claims in 5 packages'; check-node-esm-load --specifiers-only 'Specifier leg: no un-ledgered package emits an extensionless relative specifier'; check-lint-coverage '46/46 packages linted, 0 with outstanding errors'; check-type-check-coverage '41/41 packages compile their tests, 0 declared debt'; eslint on app-shell '2678 problems (0 errors, 2678 warnings)' — zero errors, the warnings are the package's pre-existing no-explicit-any baseline; full repo build 'Tasks: 43 successful, 43 total'. check-readme-exports first came back RED with 5 unjudgeable self-imports in @object-ui/cli and @object-ui/plugin-ai ('its type entry ./dist/index.d.ts is not on disk') — the unbuilt-sibling artefact of Trap 1, not this change; rather than assume that, those two packages were built and the gate re-measured 'OK ... 378 self-imports judged (378 real, 0 wrong-path, 0 fabricated) ... 0 unbuilt'. WEAK-EVIDENCE CAVEAT, stated in the PR body too: every assertion in the repo would still pass on a revert of this commit — nothing tests the deleted module, which is the finding. The evidence is the positive-control greps, the published-surface check, the downstream type-check with a built closure, and the oracle control — not the green suite.",
 "open_questions": [],
 "out_of_scope_findings": [
 "not filed as a new issue — already recorded in #6224's own body under 'Adjacent, same family': packages/plugin-dashboard/src/recordFields.tsx:56 reads `def.isSystem === true || def.system === true`, and the isSystem half can never fire on a spec-parsed field def (FieldSchema refuses the key by name). Live code in another package, untouched by this PR, left for PM triage rather than double-filed.",
 "not filed — observation for PM: packages/plugin-designer/src/MetadataObjectsPage.tsx:85 declares its own local `function toObjectDefinition(raw: ServerObjectSchema)`, an independent same-named converter. It is live and spec-typed (ServerObjectSchema), so it is not the dead-copy shape this card removed; naming it only so the next reader does not mistake the surviving hit for a missed importer.",
 "no file-level collision: #6165's HomeRail consumers do live in packages/app-shell, but under src/console/home/ (HomeRail.tsx, HomePage.tsx + tests) — different files from src/utils/metadataConverters.ts. No overlap with #6176, #6167 or #5935."
 ]
}

---

Generated by Claude Code