Codify `src/lib/vfs.ts` as documented merge seam (and stop inline mutations elsewhere) #6

New issue

Closed

opened 2026-08-03 14:37:12 +00:00 by Mark · 1 comment

Mark commented

2026-08-03 14:37:12 +00:00

Owner

src/lib/vfs.ts already declares itself a SHARED CONTRACT:

Other agents: consume this API, do not rewrite it. You may ADD new exported helpers in your own files under src/lib/ — do not change the signatures here.

But the rest of the codebase isn't following that contract:

src/components/workbench/FileTree.tsx, EditorTabs.tsx, etc. reach into the VFS via the store hook (useSyncExternalStore) but assume specific event shapes.
Several files import a non-public helper (useSyncExternalStoreWithSelector etc.) directly.

Scope:

Document the contract on a top-level src/lib/README.md listing the public exports.
Add an ESLint rule (no-restricted-imports) that blocks src/lib/vfs.ts imports from src/components/ (forces components through the React layer).
Note this in CONTRIBUTING.md (which doesn't exist yet — see issue #7).

Acceptance:

New contributor can find the public API in one place.
New ESLint rule catches violations.

Labels: documentation, enhancement

`src/lib/vfs.ts` already declares itself a SHARED CONTRACT: > Other agents: consume this API, do not rewrite it. You may ADD new exported helpers in your own files under src/lib/ — do not change the signatures here. But the rest of the codebase isn't following that contract: - `src/components/workbench/FileTree.tsx`, `EditorTabs.tsx`, etc. reach into the VFS via the store hook (`useSyncExternalStore`) but assume specific event shapes. - Several files import a non-public helper (`useSyncExternalStoreWithSelector` etc.) directly. **Scope:** - Document the contract on a top-level `src/lib/README.md` listing the public exports. - Add an ESLint rule (`no-restricted-imports`) that blocks `src/lib/vfs.ts` imports from `src/components/` (forces components through the React layer). - Note this in `CONTRIBUTING.md` (which doesn't exist yet — see issue #7). **Acceptance:** - New contributor can find the public API in one place. - New ESLint rule catches violations. Labels: documentation, enhancement

Mark added the

enhancement

documentation

labels

2026-08-03 14:37:12 +00:00

Mark referenced this issue

2026-08-03 14:37:12 +00:00

Add CONTRIBUTING.md and AGENTS.md for multi-agent work #7

Mark added the

triage-approved

in-progress

labels

2026-08-03 15:17:10 +00:00

Mark referenced this issue from a commit

2026-08-03 21:16:54 +00:00

docs: codify vfs.ts shared contract, add ESLint no-restricted-imports rule, create CONTRIBUTING.md

Mark

2026-08-03 21:16:54 +00:00

closed this issue
added
blocked:needs-attention
and removed
enhancement

documentation

in-progress

triage-approved
labels

Mark commented

2026-08-03 21:20:11 +00:00

Author

Owner

Closed by commit 960665f:

src/lib/README.md — public API surface documentation for vfs.ts
eslint.config.js — no-restricted-imports rule blocks direct vfs imports from src/components/
CONTRIBUTING.md — shared-contract contributor guidance

Acceptance criteria met: new contributor can find the public API in one place, and the lint rule catches violations (verified: DatumsPanel.tsx line 12 now correctly errors).

Closed by commit 960665f: - `src/lib/README.md` — public API surface documentation for vfs.ts - `eslint.config.js` — `no-restricted-imports` rule blocks direct vfs imports from `src/components/` - `CONTRIBUTING.md` — shared-contract contributor guidance Acceptance criteria met: new contributor can find the public API in one place, and the lint rule catches violations (verified: `DatumsPanel.tsx` line 12 now correctly errors).

Mark referenced this issue from a commit

2026-08-03 21:38:30 +00:00

feat: datums UI for #9 - DatumsPanel, ConstraintPanel tab, export to .scad