Danijel Martinek
60967a630d
Replaces the ADR-014 stub with the full Accepted-status decision record: context, the 7 numbered decisions (vendor-neutral interfaces, full-depth instrumentation, throw-site capture, PII rules, three Sentry projects, ESLint boundary, Recording* test pair), alternatives considered, positive/negative consequences, and an "execution notes" section covering the spec deviations and surprises encountered. Updates the refactor log: ticks all 33 tasks, populates "Decisions deviated from spec" (PII key list extended with ipaddress; spec section appended as §16 not §10; vite.config skipped; HTML section numbering kept conservative) and "Notable surprises" (apps needed direct core-shared deps; deep subpath exports for dynamic import; peerDependenciesMeta.optional for @sentry/node and @sentry/react; pre-existing lint debt; allowlist patterns needed **/-prefix for flat-config glob matching from sub-package cwd). Final verification (run before commit): - pnpm test → 26/26 tasks pass - pnpm lint → 15/15 tasks pass (warnings-only) - pnpm typecheck → 14/14 tasks pass - R31 grep gate (sendDefaultPii: true) → clean, no matches Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
73 lines
7.2 KiB
Markdown
73 lines
7.2 KiB
Markdown
# Refactor Log — Instrumentation + Sentry Logging (Plan 10)
|
||
|
||
**Date:** 2026-05-06
|
||
**Spec:** docs/superpowers/specs/2026-05-06-instrumentation-sentry-design.md
|
||
**Plan:** docs/superpowers/plans/2026-05-06-plan-10-instrumentation-sentry.md
|
||
**Branch:** feature/instrumentation-sentry
|
||
|
||
## Tasks
|
||
|
||
- [x] Task 1 — Scaffold refactor log + ADR-014 stub
|
||
- [x] Task 2 — Tracer interface + ISpan + AttributeValue + SpanOpts
|
||
- [x] Task 3 — NoopTracer
|
||
- [x] Task 4 — Logger interface + NoopLogger + Breadcrumb + CaptureContext
|
||
- [x] Task 5 — withSpan helper
|
||
- [x] Task 6 — Symbols + index barrel
|
||
- [x] Task 7 — SentryTracer adapter
|
||
- [x] Task 8 — SentryLogger adapter (with double-report guard)
|
||
- [x] Task 9 — pii-fields constants + scrub.beforeSend / scrub.beforeSendTransaction
|
||
- [x] Task 10 — init-server helper
|
||
- [x] Task 11 — init-client helper (browser-only)
|
||
- [x] Task 12 — bindNoopInstrumentation + bindSentryInstrumentation
|
||
- [x] Task 13 — apps/web-next bindAll() Rule 0 dispatcher
|
||
- [x] Task 14 — Tests for bindAll() orthogonality (R47)
|
||
- [x] Task 15 — RecordingTracer in core-testing
|
||
- [x] Task 16 — RecordingLogger in core-testing
|
||
- [x] Task 17 — vitest.setup.ts binds Noop by default
|
||
- [x] Task 18 — Blog feature wiring (pilot)
|
||
- [x] Task 19 — Auth feature wiring
|
||
- [x] Task 20 — Marketing-pages feature wiring
|
||
- [x] Task 21 — Navigation feature wiring
|
||
- [x] Task 22 — Media feature wiring
|
||
- [x] Task 23 — defineContractSuite expectSpan helper
|
||
- [x] Task 24 — Update repo contract suites to assert span shape
|
||
- [x] Task 25 — apps/web-next instrumentation files + scrubber test
|
||
- [x] Task 26 — apps/cms instrumentation files + scrubber test
|
||
- [x] Task 27 — apps/web-tanstack instrumentation files + scrubber test
|
||
- [x] Task 28 — ESLint boundary rule (R40) + CI grep gate (R31)
|
||
- [x] Task 29 — turbo.json globalEnv updates
|
||
- [x] Task 30 — Doc updates (CLAUDE.md, AGENTS.md, vertical-feature-spec.md)
|
||
- [x] Task 31 — Doc updates (tdd-workflow.md, testing-strategy.md, dependency-flow.md, core-shared/AGENTS.md)
|
||
- [x] Task 32 — HTML updates (data-flow-explainer §06, di-explainer §08)
|
||
- [x] Task 33 — ADR-014 final + refactor log final
|
||
|
||
## Decisions deviated from spec
|
||
|
||
- **PII key-substring list extended (Task 25).** Added `"ipaddress"` to `PII_KEY_SUBSTRINGS` so keys like `ipAddress` trigger full key-level redaction in addition to the existing IPv4/IPv6 string-pattern redaction. The plan's R38 PII-scrubber test expected `result.extra.ipAddress === "[redacted]"`, which the original substring list (without "ipaddress") could not satisfy. Tighter posture than the spec; existing scrub.test.ts continues to pass.
|
||
|
||
- **vertical-feature-spec.md numbering (Task 30).** The plan instructed to add the instrumentation section as "§10". The spec already had 15 sections, so the section was appended as **§16** (rather than renumbering §10–§15) to avoid invalidating every cross-reference in the spec.
|
||
|
||
- **Web-tanstack `vite.config.ts` modifications skipped (Task 27, Step 6).** The app is a placeholder — its `package.json` has `"build": "echo 'placeholder — TanStack Start build configured in later plan'"` and there's no `vite.config.ts`. The `@sentry/vite-plugin` dep is installed but dormant; it will be wired into the build when TanStack Start build is configured. A minimal `src/vite-env.d.ts` shims `ImportMetaEnv` for the client entry's `import.meta.env` reads.
|
||
|
||
- **data-flow-explainer.html section numbering (Task 32).** The plan asked to renumber the verdict from §06 to §07 and slot the new tracing section in as §06 — done. The `<style>` block uses dark-paper variables (`--paper`, `--ink-2`, `--rule`) tuned to the existing palette rather than the plan's snippet which used `--paper-tone, #f4ede3` (light-mode token). Same visual intent, correct theme.
|
||
|
||
- **di-explainer.html numbering (Task 32).** The plan suggested numbering the new instrumentation section as "§ 0X" (placeholder) and "renumber subsequent sections accordingly". The page's existing sections went up to §07; appending the new instrumentation section as **§08** required no renumbering and matches the plan's intent.
|
||
|
||
## Notable surprises
|
||
|
||
- **`@repo/core-shared` was not a direct dep of `apps/cms` or `apps/web-tanstack`** before Plan 10. Both apps had transitive access via feature packages. Adding the deep subpath imports `@repo/core-shared/instrumentation/sentry/init-server` (etc.) required adding `@repo/core-shared` as a direct `workspace:*` dependency of each app — pnpm's strict-peer mode wouldn't resolve the subpath through transitive paths.
|
||
|
||
- **Subpath exports needed for the dynamic-import pattern.** Apps' `instrumentation.ts` uses `await import("@repo/core-shared/instrumentation/sentry/init-server")` to keep the Sentry code out of the cold-start boot path. The barrel re-export was sufficient for static imports but not for the dynamic deep paths — added explicit `package.json#exports` entries for each `sentry/init-*` and `sentry/scrub` file.
|
||
|
||
- **`core-shared`'s `peerDependenciesMeta.optional`** was needed for `@sentry/node` and `@sentry/react` so feature packages installing `core-shared` don't pull in the React/Node SDK transitively. The same packages stay in `devDependencies` of `core-shared` so its own typecheck and test runs resolve them locally.
|
||
|
||
- **Pre-existing lint debt blocked the Task 28 R40 rule from going green.** Several issues unrelated to instrumentation surfaced once the rule was active: unused variables not covered by an `argsIgnorePattern: "^_"` config, `process` undefined in `*.mjs` config files (Node globals not declared), and stale `eslint-disable` directives in `marketing-pages`. These were each a one-line fix and were bundled into the Task 28 commit since they were the only thing blocking the lint gate.
|
||
|
||
- **`core-testing/setup/no-sentry.test.ts` was not in the original allowlist.** The file imports `@sentry/nextjs` to assert that the mock is in place. Added `**/setup/no-sentry.test.{ts,js}` to the allowlist alongside the source file. Same for `**/instrumentation/di/bind-sentry-instrumentation.test.{ts,js}` — Task 12's test file lives in `instrumentation/di/`, not `instrumentation/sentry/`, so the `**/instrumentation/sentry/**` allowlist alone wouldn't catch it.
|
||
|
||
- **ESLint flat-config glob patterns are relative to the eslint command's cwd.** When `pnpm --filter <pkg> lint` runs, ESLint sees file paths relative to the package root, not the repo root. The plan's allowlist patterns (`packages/core-shared/src/instrumentation/sentry/**`) wouldn't match. Switched to `**/`-prefixed patterns (`**/instrumentation/sentry/**`) which match regardless of where ESLint is invoked.
|
||
|
||
- **Vite/TanStack Start typing not yet present in web-tanstack.** The client entry uses `import.meta.env.VITE_*`, but no Vite types are installed since the build infra is a placeholder. A small `src/vite-env.d.ts` declares the env shape for now; replace with `/// <reference types="vite/client" />` when Vite is wired.
|
||
|
||
- **Spec deviations are usually a sign of a mis-aligned spec, not a wrong implementation.** Three of the deviations above (ipaddress, vertical-feature-spec section number, di-explainer section number) are minor; the vite.config skip and vite-env shim are real architecture decisions worth recording in ADR-014 alongside the major decisions.
|