refactor: consolidate type guards, validate JSON boundaries with zod, remove duplicated micro-helpers

[joesobo]

Summary

Follow-up to #302. That PR removed the hand-rolled isRecord guards; this one finishes the job (the extension-side commit missed the merge — cherry-picked here as the first commit) and cleans up the ten related code smells found in a monorepo-wide sweep.

Progress update

✅ Items 1–2: consolidated object-record probes and JSON-state parsing; switched repo-settings clone to structuredClone.
✅ Item 3: kept host/webview equality comparators separate after documenting their undefined key semantics; shared the record guard plumbing.
✅ Item 4: consolidated finite-number, positive-number, and pair guards in graph physics numeric helpers.
✅ Item 5: moved string-array/string readers onto shared schema-backed value helpers while preserving boundary-specific string semantics.
✅ Item 6: replaced plugin-runtime message probing with zod schemas that keep lenient filtering behavior.
✅ Item 7: schema-validated the remaining unvalidated persisted JSON boundaries; left already-normalized parse sites unchanged.
✅ Item 8: covered by the repo-settings clone update in items 1–2.
✅ Item 9: centralized unavoidable Tree-sitter language casts in one helper path.
✅ Item 10: intentionally kept core and extension unknownRecordSchema package-local to avoid expanding core's public API for a generic zod helper.

Plan of action

0. Leftover isRecord from #302 ✅ (first commit, cherry-picked)
e2e/workspacePlugins.ts, pluginData.ts, cssSnippets.ts, webview guards.ts/linkTargets.ts, acceptance helpers — zod at JSON boundaries, direct property checks for live d3-force objects.

1–2. isPlainObject / isGraphRecord clones (4 copies)
repoSettings/store/model/plainObject.ts, webview/store/messageHandlers/equality/structures.ts, webview/components/legends/panel/storage.ts, graphView/analysis/execution/publish/equality/collections.ts.
Approach: where the value comes from JSON/persisted state, parse with the shared unknownRecordSchema; where it's a structural probe in equality code, keep ONE shared typed helper and delete the clones.

3. Duplicate deep-equality implementations
Extension-host publish/equality/* vs webview messageHandlers/equality/structures.ts. Approach: compare semantics; if identical, extract one comparator into src/shared/; if intentionally different (host compares graph payloads, webview compares message state), document why and still deduplicate the record/array plumbing. Conservative: no behavior change, existing tests must stay green.

4. isFiniteNumber × 4+ webview copies (+ isFinitePositiveNumber, isFinitePair)
Consolidate into one exported helper next to the existing runtime/physics/numeric.ts, update all import sites, delete clones.

5. readStringArray / readOptionalString / readRequiredString re-implementations
repoSettings/store/model/persistedShape/stringArray.ts, e2e + acceptance helpers, core graphCache/database/records/values.ts. Approach: move to the shared zod value schemas (looseStringArraySchema etc.) introduced in #302; core keeps its own copy in core/src/values.ts, extension uses src/shared/values.ts.

6. Webview plugin-runtime message validation
webview/pluginRuntime/messageValidation.ts hand-probes payload as {...} field by field. Replace with zod schemas producing PluginInjectPayload / PluginWebviewAsset / PluginScopedMessage, preserving current lenient semantics (filter bad entries, don't throw).

7. Unvalidated JSON.parse + cast boundaries (audit + schema-fy)
repoSettings/store/persistence/diskState.ts, gitHistory/cache/storage.ts, graphView/groups/defaults/materialTheme/manifest.ts, repoSettings/meta.ts, core plugins/installedPluginCache/storage.ts, workspace/meta.ts. Approach: audit each; where the parsed value is cast or property-probed, add a zod schema; where it's already routed through a normalizer, leave it.

8. deepClone via JSON.parse(JSON.stringify(...))
repoSettings/store/model/plainObject.ts — switch to structuredClone (Node 20+ / modern webview), verify no reliance on JSON's undefined-dropping behavior in call sites first.

9. 19× as unknown as Parser.Language in core/treeSitter/runtime/languages/load.ts
Extract a single typed loadLanguageModule() helper so the unavoidable cast appears once, documented.

10. Duplicate unknownRecordSchema (core + extension)
Decide single source: keep both (packages are published independently) OR export from @codegraphy-dev/core. Default plan: export from core's public API and delete the extension copy, unless bundle/API-surface concerns say otherwise.

Method

• One commit per numbered item (or small cluster), pushed as completed
• No behavior changes intended; full unit suites + typecheck per package before each commit
• CRAP ≤ 8 / mutation thresholds respected for changed functions

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6d1d64d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR