@terreno/mcp 0.26.0 → 0.28.0

package/src/docs/versioned/0.26.0/reference/ui.md

@@ -0,0 +1,476 @@
+# @terreno/ui
+
+React Native UI component library (88+ components). Layout (Box, Page, Card), forms (TextField, SelectField), display (Text, DataTable), actions (Button), feedback (Modal, Toast), and theming via TerrenoProvider.
+
+## Key exports
+
+- Layout: `Box`, `Page`, `SplitPage`, `Card`
+- Forms: `TextField`, `SelectField`, `DateTimeField`, `CheckBox`
+- Display: `Text`, `Heading`, `Badge`, `DataTable`
+- Actions: `Button`, `IconButton`, `Link`
+- Feedback: `Spinner`, `Modal`, `Toast`
+- Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
+- Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
+- **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
+
+## Type Re-exports
+
+@terreno/ui re-exports commonly-used React Native types to help consumers avoid version conflicts:
+
+``````typescript
+import {StyleProp, ViewStyle} from "@terreno/ui";
+
+// Use these instead of importing from react-native directly
+const customStyle: StyleProp<ViewStyle> = {
+  flex: 1,
+  backgroundColor: "#fff",
+};
+``````
+
+**Benefits:**
+- Avoids version mismatches between your app's react-native and @terreno/ui's react-native
+- Ensures type compatibility when passing styles to @terreno/ui components
+- Simplifies imports (one package instead of two)
+
+## Component Behaviors
+
+### Button Layout Behavior
+
+Buttons automatically size to their content unless `fullWidth` is specified:
+
+``````typescript
+// Button takes only the space it needs
+<Box direction="column">
+  <Button text="Save" onClick={handleSave} />  {/* Auto-sized */}
+</Box>
+
+// Button stretches to full width
+<Box direction="column">
+  <Button text="Save" onClick={handleSave} fullWidth />  {/* Full width */}
+</Box>
+``````
+
+Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
+
+## Authentication Components
+
+### SocialLoginButton
+
+Branded social login buttons for OAuth authentication with Google, GitHub, and Apple.
+
+``````typescript
+import {SocialLoginButton} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<SocialLoginButton
+  provider="google"  // "google" | "github" | "apple"
+  variant="primary"  // "primary" | "outline"
+  onPress={async () => {
+    await authClient.signIn.social({
+      provider: "google",
+      callbackURL: "yourapp://auth/callback",
+    });
+  }}
+  loading={isLoading}
+  fullWidth
+/>
+``````
+
+**Features:**
+- Proper brand colors for each provider (follows brand guidelines)
+- Built-in icons (FontAwesome 6)
+- Primary and outline variants
+- Loading states with spinner
+- Automatic text: "Continue with {Provider}"
+
+### LoginScreen
+
+Complete login screen with email/password and optional social providers.
+
+``````typescript
+import {LoginScreen} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<LoginScreen
+  onEmailLogin={async ({email, password}) => {
+    await authClient.signIn.email({email, password});
+  }}
+  onSocialLogin={async (provider) => {
+    await authClient.signIn.social({provider, callbackURL: "yourapp://auth"});
+  }}
+  socialProviders={["google", "github", "apple"]}
+  onForgotPassword={() => navigation.navigate("ForgotPassword")}
+  onSignUp={() => navigation.navigate("SignUp")}
+/>
+``````
+
+### SignUpScreen
+
+Complete signup screen with email/password and optional social providers.
+
+``````typescript
+import {SignUpScreen} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<SignUpScreen
+  onEmailSignUp={async ({email, password, name}) => {
+    await authClient.signUp.email({email, password, name});
+  }}
+  onSocialLogin={async (provider) => {
+    await authClient.signIn.social({provider, callbackURL: "yourapp://auth"});
+  }}
+  socialProviders={["google", "github"]}
+  onSignIn={() => navigation.navigate("Login")}
+  requireName
+  requireTermsAcceptance
+/>
+``````
+
+**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+
+## Testing Utilities
+
+@terreno/ui provides test helpers for writing component tests with @testing-library/react-native.
+
+### renderWithTheme
+
+Wraps components in ThemeProvider for testing.
+
+``````typescript
+import {renderWithTheme} from "@terreno/ui";
+import {describe, it, expect} from "bun:test";
+
+describe("MyComponent", () => {
+  it("renders correctly", () => {
+    const {getByTestId} = renderWithTheme(<MyComponent testID="my-comp" />);
+    expect(getByTestID("my-comp")).toBeTruthy();
+  });
+});
+``````
+
+**Why:** Most @terreno/ui components require ThemeProvider context to access theme values.
+
+### createCommonMocks
+
+Creates mock functions for common component callbacks.
+
+``````typescript
+import {createCommonMocks} from "@terreno/ui";
+
+const mocks = createCommonMocks();
+// Returns: {onBlur, onChange, onEnter, onFocus, onIconClick, onSubmitEditing}
+
+<TextField
+  value="test"
+  onChange={mocks.onChange}
+  onBlur={mocks.onBlur}
+  onFocus={mocks.onFocus}
+/>
+
+// Assert mock was called
+expect(mocks.onChange).toHaveBeenCalledWith("new value");
+``````
+
+### setupComponentTest / teardownComponentTest
+
+Lifecycle helpers for test setup and cleanup.
+
+``````typescript
+import {setupComponentTest, teardownComponentTest} from "@terreno/ui";
+
+describe("MyForm", () => {
+  let mocks;
+
+  beforeEach(() => {
+    mocks = setupComponentTest(); // Returns createCommonMocks()
+  });
+
+  afterEach(() => {
+    teardownComponentTest(); // No-op in Bun (auto-cleanup)
+  });
+
+  it("submits form", () => {
+    // Test with mocks
+  });
+});
+``````
+
+## Date Utilities
+
+Luxon-based helpers for date comparison and formatting.
+
+``````typescript
+import {
+  isToday,
+  isTomorrow,
+  isYesterday,
+  isThisYear,
+  isWithinWeek,
+  getIsoDate,
+} from "@terreno/ui";
+
+const date = DateTime.now();
+
+if (isToday(date)) console.log("Today!");
+if (isTomorrow(date)) console.log("Tomorrow!");
+if (isYesterday(date)) console.log("Yesterday!");
+if (isThisYear(date)) console.log("This year!");
+if (isWithinWeek(date)) console.log("Within 7 days!");
+
+// Convert to ISO date string
+const isoString = getIsoDate(date); // "2026-02-15"
+``````
+
+### Timezone Utilities
+
+``````typescript
+import {getTimezoneOptions} from "@terreno/ui";
+
+// Get USA timezones only
+const usaTimezones = getTimezoneOptions("usa");
+// Returns: [{label: "Pacific Time", value: "America/Los_Angeles"}, ...]
+
+// Get worldwide timezones
+const allTimezones = getTimezoneOptions("worldwide");
+// Returns: [{label: "UTC", value: "UTC"}, {label: "New York", value: "America/New_York"}, ...]
+``````
+
+**Use case:** Populate SelectField with timezone choices.
+
+## Address Utilities
+
+Google Places API integration helpers for address handling.
+
+### formatAddress
+
+``````typescript
+import {formatAddress} from "@terreno/ui";
+
+const address = {
+  street: "123 Main St",
+  city: "San Francisco",
+  state: "CA",
+  zipCode: "94102",
+};
+
+const formatted = formatAddress(address);
+// "123 Main St, San Francisco, CA 94102"
+``````
+
+### processAddressComponents
+
+Parses Google Places API address_components into structured data.
+
+``````typescript
+import {processAddressComponents} from "@terreno/ui";
+
+// From Google Places API response
+const components = place.address_components;
+
+const parsed = processAddressComponents(components);
+// Returns: {street, city, state, zipCode, country, county}
+``````
+
+### findAddressComponent
+
+``````typescript
+import {findAddressComponent} from "@terreno/ui";
+
+const city = findAddressComponent(components, "locality");
+const state = findAddressComponent(components, "administrative_area_level_1", "short_name");
+``````
+
+### Validation
+
+``````typescript
+import {isValidGoogleApiKey, formattedCountyCode} from "@terreno/ui";
+
+if (!isValidGoogleApiKey(apiKey)) {
+  console.error("Invalid Google API key");
+}
+
+// Format US county codes
+const county = formattedCountyCode("6075"); // "6075" (Santa Cruz County, CA)
+``````
+
+## Media Query Helpers
+
+Responsive design utilities for breakpoints and device detection.
+
+``````typescript
+import {
+  mediaQuery,
+  mediaQueryLargerThan,
+  mediaQuerySmallerThan,
+  isMobileDevice,
+} from "@terreno/ui";
+
+// Check if matches breakpoint
+if (mediaQuery("md")) {
+  console.log("Medium or larger");
+}
+
+// Greater than breakpoint
+if (mediaQueryLargerThan("sm")) {
+  console.log("Larger than small");
+}
+
+// Smaller than breakpoint
+if (mediaQuerySmallerThan("lg")) {
+  console.log("Smaller than large");
+}
+
+// Detect mobile
+if (isMobileDevice()) {
+  console.log("Running on mobile device");
+}
+``````
+
+**Breakpoints:**
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+
+## Icons
+
+Terreno uses **FontAwesome 6** by default. Pass icon names via `iconName` on `Icon`, `Button`, `IconButton`, form fields, `Badge`, and other icon-aware components.
+
+### FontAwesome Icons
+
+All 2000+ FontAwesome 6 icons are available:
+
+``````typescript
+import {Icon, Button} from "@terreno/ui";
+
+<Icon iconName="check" size="md" color="primary" />
+<Icon iconName="user" size="lg" color="secondaryDark" />
+<Icon iconName="chevron-right" size="sm" color="primary" />
+
+<Button text="Save" iconName="check" onClick={handleSave} />
+``````
+
+**Sizes:** `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
+
+**Types:** `solid` (default), `regular`, `brand`, `light`, `thin`, `duotone`, `sharp`, and related variants.
+
+### Custom Icons
+
+Register your own icons (SVGs, etc.) on `TerrenoProvider` and use them by name anywhere `iconName` is accepted. Registered names take precedence over FontAwesome.
+
+**1. Create a custom icon component** that accepts `color`, `size` (pixels), and optional `testID`:
+
+``````typescript
+import type {CustomIconProps} from "@terreno/ui";
+import Svg, {Path} from "react-native-svg";
+
+export const SparkleIcon = ({color, size, testID}: CustomIconProps): React.ReactElement => (
+  <Svg fill="none" height={size} testID={testID} viewBox="0 0 24 24" width={size}>
+    <Path d="M12 2l2.4 6.6L21 11l-6.6 2.4L12 20l-2.4-6.6L3 11l6.6-2.4L12 2z" fill={color} />
+  </Svg>
+);
+``````
+
+Terreno resolves theme colors and size tokens before passing them to your component.
+
+**2. Register icons** via the `icons` prop on `TerrenoProvider`:
+
+``````typescript
+import {TerrenoProvider} from "@terreno/ui";
+import {SparkleIcon} from "./components/SparkleIcon";
+
+<TerrenoProvider icons={{sparkle: SparkleIcon}}>
+  {children}
+</TerrenoProvider>
+``````
+
+**3. Use by name** like any built-in icon:
+
+``````typescript
+<Icon iconName="sparkle" color="accent" size="lg" />
+<Button text="Sparkle" iconName="sparkle" onClick={handleClick} />
+<IconButton accessibilityLabel="Sparkle" iconName="sparkle" onClick={handleClick} />
+``````
+
+**TypeScript:** extend `CustomIconRegistry` via declaration merging for autocomplete and type-safe `iconName` values:
+
+``````typescript
+declare module "@terreno/ui" {
+  interface CustomIconRegistry {
+    sparkle: true;
+  }
+}
+``````
+
+See [`demo/components/customIcons.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
+
+### Built-in Status Icons
+
+@terreno/ui also ships status indicator SVGs as standalone components (not registered via `TerrenoProvider`):
+
+``````typescript
+import {MobileIcon, OnlineIcon, OfflineIcon, OutOfOfficeIcon} from "@terreno/ui";
+
+<MobileIcon width={20} height={20} fill="#007AFF" />
+<OnlineIcon width={16} height={16} />
+<OfflineIcon width={16} height={16} />
+<OutOfOfficeIcon width={16} height={16} />
+``````
+
+**Use case:** User status indicators, device type badges.
+
+## Style Utilities
+
+### Unifier Class
+
+Color manipulation helper:
+
+``````typescript
+import {Unifier} from "@terreno/ui";
+
+// Darken/lighten colors
+const darkColor = Unifier.changeColorLuminance("#007AFF", -0.2); // Darker
+const lightColor = Unifier.changeColorLuminance("#007AFF", 0.2); // Lighter
+``````
+
+### Style Helpers
+
+``````typescript
+import {identity, concat, fromClassName, toggle, binding, union} from "@terreno/ui";
+
+// Compose style objects
+const styles = concat(baseStyles, conditionalStyles);
+
+// Toggle styles
+const buttonStyles = toggle(isPressed, pressedStyles, defaultStyles);
+``````
+
+**Note:** Most use cases are better served by Box props (`padding`, `color`, etc.).
+
+## Environment Variables
+
+@terreno/ui components do not require environment variables. All configuration is done at runtime via:
+
+- **TerrenoProvider props** — Theme customization, custom icon registry (`icons`), OpenAPI spec URL
+- **Theme hooks** — `useTheme()`, `setTheme()`, `setPrimitives()`
+- **Component props** — Direct prop overrides for individual components
+
+**Example configuration:**
+
+``````typescript
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider
+  baseUrl="https://api.example.com"
+  theme={{
+    surface: {primary: "secondary500"},
+  }}
+  onError={(error) => console.error(error)}
+>
+  {children}
+</TerrenoProvider>
+``````
+
+## Related Documentation
+
+See the [ui package source](../../ui/src/) and [.cursor/rules/ui/](../../.cursor/rules/ui/) for props and conventions.

package/src/docs/versioned/0.26.0/tasks/syncdb-local-first.md

@@ -0,0 +1,117 @@
+# Task List: SyncDB Local-First Data Layer
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Foundation
+
+- [ ] **Task 1.1**: Scaffold `@terreno/syncdb` package
+  - Description: Create the package with core entrypoints, lifecycle interfaces, and typed configuration.
+  - Files: `syncdb/package.json` (new), `syncdb/src/index.ts` (new), `syncdb/src/types.ts` (new), `syncdb/README.md` (new)
+  - Depends on: none
+  - Acceptance: package compiles and exports `createSyncDbClient` and configuration types.
+
+- [ ] **Task 1.2**: Define storage and sync contracts
+  - Description: Add canonical interfaces for entities, outbox records, sync cursors, conflicts, and keyring entries.
+  - Files: `syncdb/src/storage/types.ts` (new), `syncdb/src/sync/types.ts` (new), `syncdb/src/crypto/types.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: type checks enforce required fields and operations.
+
+## Phase 2: Local DB and Encryption
+
+- [ ] **Task 2.1**: Implement IndexedDB adapter with migrations
+  - Description: Add object stores for entities/outbox/cursors/conflicts/keyring and schema version migration support.
+  - Files: `syncdb/src/storage/indexedDb.ts` (new), `syncdb/src/storage/migrations.ts` (new), `syncdb/src/storage/indexedDb.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: storage CRUD + migration tests pass.
+
+- [ ] **Task 2.2**: Implement key manager (Web Crypto)
+  - Description: Add DEK generation + wrap/unwrap logic and persistence integration.
+  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: key lifecycle tests pass for generate/wrap/unwrap/reload.
+
+- [ ] **Task 2.3**: Encrypt IndexedDB payloads at rest
+  - Description: Add AES-GCM envelope encryption/decryption and integrate in storage read/write paths.
+  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), `syncdb/src/crypto/envelope.test.ts` (new)
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: tests verify no plaintext persistence and successful decrypt roundtrip.
+
+## Phase 3: Local Mutation Engine
+
+- [ ] **Task 3.1**: Add optimistic local mutation application
+  - Description: Apply local patches immediately and retain inverse patches for rollback.
+  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
+  - Depends on: Task 2.3
+  - Acceptance: immediate local apply and rollback tests pass.
+
+- [ ] **Task 3.2**: Implement durable outbox state machine
+  - Description: Persist queued mutations and manage transitions `queued -> inFlight -> acked/conflicted/failed`.
+  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
+  - Depends on: Task 3.1
+  - Acceptance: replay transition and retry logic tests pass.
+
+- [ ] **Task 3.3**: Implement conflict capture and resolution
+  - Description: Persist conflict records and support `useServer` and `keepMine` resolution paths.
+  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
+  - Depends on: Task 3.2
+  - Acceptance: both resolution strategies correctly update local state and queue state.
+
+## Phase 4: Websocket Delta Sync
+
+- [ ] **Task 4.1**: Build sync transport client
+  - Description: Add websocket connect/auth/reconnect lifecycle and sync event channel handling.
+  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: transport lifecycle tests pass including reconnect behavior.
+
+- [ ] **Task 4.2**: Implement cursor-aware delta applier
+  - Description: Apply deltas idempotently with monotonic cursor checks and gap handling.
+  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: ordered delta tests pass; duplicate/out-of-order deltas are safely handled.
+
+- [ ] **Task 4.3**: Wire ack/nack replay coordinator
+  - Description: Connect outbox replay to server ack/nack responses and conflict creation.
+  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
+  - Depends on: Task 3.3, Task 4.2
+  - Acceptance: ack finalizes queued mutations; nack creates conflict records.
+
+## Phase 5: App Integration and Migration Bridge
+
+- [ ] **Task 5.1**: Implement React hooks and provider
+  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and context provider wiring.
+  - Files: `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/hooks.test.tsx` (new)
+  - Depends on: Task 3.3, Task 4.3
+  - Acceptance: hooks update on local mutations and remote deltas.
+
+- [ ] **Task 5.2**: Add Redux migration bridge
+  - Description: Provide optional adapter for Redux-based consumers transitioning from `@terreno/rtk`.
+  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
+  - Depends on: Task 5.1
+  - Acceptance: bridge supports selector and dispatch-driven mutation usage.
+
+- [ ] **Task 5.3**: Integrate `example-frontend` todos behind `USE_SYNCDB`
+  - Description: Switch todos flow to syncdb under a feature flag while keeping legacy path available.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/(tabs)/index.tsx`, `example-frontend/app/_layout.tsx`
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: flagged path supports offline local create/update/delete and sync reconciliation.
+
+## Phase 6: Codegen and Validation
+
+- [ ] **Task 6.1**: Prototype `@terreno/syncdb-codegen`
+  - Description: Create codegen package that emits typed syncdb operation descriptors from OpenAPI.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), `syncdb-codegen/src/*.test.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: generator produces valid descriptors for one sample domain.
+
+- [ ] **Task 6.2**: Author migration docs
+  - Description: Document migration path from `@terreno/rtk` to `@terreno/syncdb` and rollout strategy.
+  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
+  - Depends on: Task 5.3
+  - Acceptance: docs include setup, API usage, and feature-flag rollout playbook.
+
+- [ ] **Task 6.3**: Run validation suite
+  - Description: Execute compile, lint, and tests for touched packages and resolve regressions.
+  - Files: as needed in touched packages
+  - Depends on: Task 6.2
+  - Acceptance: relevant compile/lint/test commands pass with no blockers.

package/src/docs/versioned/0.27.0/explanation/README.md

@@ -0,0 +1,14 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Contents
+
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels

package/src/docs/versioned/0.27.0/explanation/explicit-any-policy.md

@@ -0,0 +1,88 @@
+# Explicit `any` policy
+
+Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
+
+## Why
+
+- **Type safety**: `any` disables checking and hides bugs at compile time.
+- **Refactor confidence**: precise types make API and UI changes safer.
+- **Consistency**: one convention for when `any` is acceptable and how it is documented.
+
+Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
+
+## Allowed uses
+
+Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
+
+- Mongoose `Schema<any, …>` accepting arbitrary consumer schemas (`api/src/plugins.ts`)
+- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
+- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
+
+Every allowed use must be **lint-clean** and **documented** (see below).
+
+## Remediation status
+
+The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
+
+| Status | Meaning |
+|--------|---------|
+| `violation` | No `biome-ignore` — fails Biome lint |
+| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
+| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
+| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
+| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
+
+## How to document an `any`
+
+When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
+
+```typescript
+// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
+// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
+const hook = (api as any)[`useGet${name}Query`];
+```
+
+For test files with many mocks, a file-level header is fine:
+
+```typescript
+// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+```
+
+## Commands
+
+```bash
+bun run check:explicit-any                         # summary report
+bun run check:explicit-any:json                    # JSON inventory
+bun run check:explicit-any:baseline                # fail if counts regress vs baseline
+bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
+bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
+bun run check:explicit-any -- --production-only --undocumented --list
+bun run check:explicit-any -- --package=api        # filter to one package
+bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
+bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
+bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
+```
+
+## Enforcement
+
+| Layer | What it does |
+|-------|----------------|
+| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, undocumented, and violation counts must not increase |
+| **`bun run lint`** | Per-package lint including `noExplicitAny` |
+
+Baseline file: `scripts/check-explicit-any/baseline.json`. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+
+## Remediation workflow
+
+1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
+2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
+3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
+4. Run `bun run check:explicit-any:baseline` before opening a PR.
+5. If counts decreased, run `--write-baseline` and commit the new baseline.
+
+## Exclusions
+
+The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.