Skip to content

Commit ffcd657

Browse files
cliffhallclaude
andcommitted
docs: address review round 3 — scope the "no types/ bucket" claim (#1776)
Doc-only follow-up to the round-3 @claude review on PR #1784 (no code changed): 1. "no separate types/ bucket" overreached: clients/web/src/types/ does exist (navigation.ts + react-syntax-highlighter .d.ts ambient stubs wired via tsconfig.app.json paths). Scoped the claim in both AGENTS.md and the web README to "no types/ sub-bucket INSIDE lib/utils", and noted src/types/ is for ambient .d.ts stubs, not domain types. 2. README example list drifted from AGENTS.md's round-2 load-bearing anchors — realigned it (inspectorTabs/mcpNetworkHeaders, dropped the zero-importer customHeaders from the headline list). 3. Clarified v2_ux_interfaces_plan.md:185 so the v2 path reads as the copy's destination, not as the v1.5 source location. Follow-up filed as #1785 (board Todo): src/types/navigation.ts InspectorTab is dead and duplicates utils/inspectorTabs.ts — kept out of this pure-move PR. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent c77df99 commit ffcd657

3 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ gh project item-edit --project-id PVT_kwDOCt2Azc4BJVxt --id "$ITEM_ID" --field-i
245245

246246
The web client keeps two grab-bag directories under `clients/web/src`, split by a real (now codified) rule — **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
247247

248-
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.) This includes modules that are pure **shared domain types plus their pure constructors/transforms** (`customHeaders` — `CustomHeader` + `headersToRecord`/`migrateFromLegacyAuth`, a shape staged for `ServerSettingsForm`, see `specification/v2_ux_interfaces_plan.md`, so it currently has no importer but its own test); there is no separate `types/` bucket. **Diagnostic logging (`console.warn`/`console.error`) does not count as a side effect** for this rule — a validator that warns on bad input is still "pure" here (`sandbox-csp`, `jsonUtils`, `schemaUtils` all warn). Two forms of importing from `@inspector/core` are also fine: a **type-only** import is not a subsystem dependency (`pendingReauth` is pure type declarations), and **re-exporting pure functions or constants** from core is not subsystem ownership either (`oauthUx`/`oauthFlow` re-export core copy/predicates) — what makes a module `lib` is wrapping core's *stateful runtime*, not merely importing from it.
248+
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.) This includes modules that are pure **shared domain types plus their pure constructors/transforms** (`customHeaders` — `CustomHeader` + `headersToRecord`/`migrateFromLegacyAuth`, a shape staged for `ServerSettingsForm`, see `specification/v2_ux_interfaces_plan.md`, so it currently has no importer but its own test); there is no `types/` sub-bucket **inside** `lib`/`utils` (the removal of `lib/types/` is what the `customHeaders` move settles). This is distinct from the top-level `src/types/`, which is not a home for domain types at all — it holds ambient `.d.ts` module stubs (e.g. the `react-syntax-highlighter` shims wired through `tsconfig.app.json` `paths`). **Diagnostic logging (`console.warn`/`console.error`) does not count as a side effect** for this rule — a validator that warns on bad input is still "pure" here (`sandbox-csp`, `jsonUtils`, `schemaUtils` all warn). Two forms of importing from `@inspector/core` are also fine: a **type-only** import is not a subsystem dependency (`pendingReauth` is pure type declarations), and **re-exporting pure functions or constants** from core is not subsystem ownership either (`oauthUx`/`oauthFlow` re-export core copy/predicates) — what makes a module `lib` is wrapping core's *stateful runtime*, not merely importing from it.
249249
- **`src/lib/`** — infrastructure / integration / stateful adapters. Modules that instantiate or compose subsystems, wrap the `@inspector/core` **runtime** (not just its types), touch the DOM / `window` / `sessionStorage`, or otherwise produce side effects. (Anchors: `environmentFactory` composes `InspectorClientEnvironment`; `remoteOAuthStorage` is an adapter class over `core/auth`; `oauthResume` reads/writes `sessionStorage`; `browserTabVisibility` registers `visibilitychange` listeners; `clearServerOAuthState` drives the live `InspectorClient` / `OAuthStorage`; `downloadFile` triggers browser downloads.)
250250

251251
Cross-directory imports point **one way, `lib → utils`** (infra depends on pure helpers, never the reverse). Keep it that way: if a `utils/` module needs a type currently exported from a `lib/` module, declare the type in `utils/` and re-export it from `lib/` (as `pendingReauth` owns `OAuthResumeAuthKind` and `oauthResume` re-exports it), rather than importing "up" from `utils` into `lib`.

‎clients/web/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Every screen and element has a `*.stories.tsx` (see [Storybook](#storybook)). St
5959

6060
Two grab-bag directories, split by one rule: **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
6161

62-
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. Diagnostic `console.warn`/`console.error` doesn't count as a side effect; neither a type-only import from `@inspector/core` nor re-exporting core's pure functions/constants counts as a subsystem dependency (what makes a module `lib` is wrapping core's stateful runtime). Also home to pure shared domain types + their constructors (`customHeaders`) — no separate `types/` bucket. Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `deepLink`, `sandbox-csp`, `customHeaders`.
62+
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. Diagnostic `console.warn`/`console.error` doesn't count as a side effect; neither a type-only import from `@inspector/core` nor re-exporting core's pure functions/constants counts as a subsystem dependency (what makes a module `lib` is wrapping core's stateful runtime). Also home to pure shared domain types + their constructors (`customHeaders`) — there is no `types/` sub-bucket inside `lib`/`utils` (the top-level `src/types/` is separate: ambient `.d.ts` module stubs, not domain types). Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.
6363
- **`src/lib/`** — infrastructure / stateful adapters: modules that compose subsystems, wrap the `@inspector/core` **runtime**, or produce side effects. Examples: `environmentFactory`, `remoteOAuthStorage`, `oauthResume` (sessionStorage), `browserTabVisibility` (DOM listeners), `clearServerOAuthState`, `downloadFile`.
6464

6565
Nothing keys off the boundary — it's a human-legible import-time signal. See [`AGENTS.md`](../../AGENTS.md) for the full rule.

‎specification/v2_ux_interfaces_plan.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -182,8 +182,8 @@ have no v1.5 equivalent):
182182
or transport concept. Place it under `clients/web/src/types/navigation.ts`
183183
rather than in `core/mcp/types.ts`. Everything else lives in `core/mcp/types.ts`.
184184

185-
**Custom headers**: copy `clients/web/src/utils/customHeaders.ts` from
186-
v1.5 verbatim. It owns `CustomHeader` / `CustomHeaders` shape used by
185+
**Custom headers**: `clients/web/src/utils/customHeaders.ts` is a verbatim
186+
copy of the v1.5 module. It owns `CustomHeader` / `CustomHeaders` shape used by
187187
`ServerSettingsForm` and the experimental panel.
188188

189189
**JSON Schema typing for `SchemaForm`**: copy v1.5's

0 commit comments

Comments
 (0)