From 16ca82d7cf8421e199284ea10a7fd342e620c327 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 5 May 2026 21:12:05 +0200 Subject: [PATCH] docs(refactor-log): scaffold Lazar conformance refactor changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Empty section template plus the full doc-update checklist that the follow-up pass will work through after the refactor is merged. Captures the substitution map (paths, naming, patterns) so the doc updater can apply changes mechanically. Spec: docs/superpowers/specs/2026-05-05-lazar-pattern-conformance-design.md §10 Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-05-05-lazar-pattern-conformance.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md diff --git a/docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md b/docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md new file mode 100644 index 0000000..020619d --- /dev/null +++ b/docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md @@ -0,0 +1,105 @@ +# Refactor Changelog — Lazar Pattern Conformance + +**Started:** 2026-05-05 +**Spec:** [2026-05-05-lazar-pattern-conformance-design.md](../specs/2026-05-05-lazar-pattern-conformance-design.md) +**Plan:** [2026-05-05-plan-8-lazar-conformance.md](../plans/2026-05-05-plan-8-lazar-conformance.md) +**Branch:** feature/lazar-conformance + +This document captures every architectural change made during Plan 8 +execution, organized by category. After the plan is merged, use the +"Doc update checklist" at the bottom to update external docs in a +single follow-up pass. + +--- + +## Summary + +(Filled in at Task 10 — total files added/modified/deleted/renamed; net test count change; commits.) + +--- + +## 1. File renames (before → after) + +(populated as work progresses) + +## 2. Files added (with purpose) + +(populated as work progresses) + +## 3. Files deleted (with reason) + +(populated as work progresses) + +## 4. Pattern changes (code-level) + +### 4.1 Use cases — factory function pattern +(populated when a use case is migrated) + +### 4.2 Controllers — one per use case +(populated when controllers are split) + +### 4.3 Entities split — models/ + errors/ subdirs +(populated when entities are reshaped) + +## 5. DI changes + +### 5.1 Inversify `.toDynamicValue` bindings +(populated when DI modules are updated) + +### 5.2 Mock siblings registered as default bindings +(populated when modules are updated) + +## 6. Test refactor patterns + +### 6.1 Direct injection (no container rebinding) +(populated when tests are migrated) + +## 7. Open issues / deferred decisions + +(populated as encountered) + +--- + +## Doc update checklist (deferred — run after merge) + +After Plan 8 is merged to `main`, work through this list in a single +batched doc-update pass. Each item points at an external doc that +references the pre-Plan-8 layout or pattern and needs to be brought +in line. + +- [ ] `CLAUDE.md` — Key Conventions section: update file path examples to use `entities/models/.ts`; mention factory-function use cases; show `I*UseCase` type aliases +- [ ] `AGENTS.md` (root) — Per-Package Conventions: update naming examples (`.repository.{ts,mock.ts,interface.ts}`); add note about `I*UseCase` / `I*Controller` type aliases; document factory-style DI +- [ ] `docs/guides/adding-a-feature.md` — restructure to use factory-function pattern in every step; update file paths to new layout; show `.toDynamicValue()` bindings +- [ ] `docs/guides/tdd-workflow.md` — update "When to mock" decision tree to show direct factory injection (`signInUseCase(mocks)(input)`) instead of container rebinding; update factory usage examples to reference `entities/models/*` paths +- [ ] `docs/guides/testing-strategy.md` — Mocking section: remove DI-rebinding pattern as the default; show direct factory injection +- [ ] `docs/architecture/vertical-feature-spec.md` — update §10 (file shape examples) to new template; update §13 (testing) to reflect factory pattern + direct injection +- [ ] `docs/architecture/overview.md` — layer descriptions: mention factory-function use cases; add note that controllers are one-per-use-case +- [ ] `docs/architecture/dependency-flow.md` — verify dep flow still accurate with new DI bindings; update examples if any reference old paths +- [ ] `docs/decisions/adr-012-lazar-conformance.md` — NEW ADR documenting the conformance decision and the four intentional divergences (per-feature DI, inversify retained, colocated tests, no Sentry/instrumentation services) +- [ ] Per-feature `AGENTS.md` (auth/blog/media/marketing-pages/navigation) — update file path references; document factory pattern; update Tests section +- [ ] `packages/core-testing/AGENTS.md` — update factory examples to reference `entities/models/.ts` paths +- [ ] `packages/auth/AGENTS.md` — document the new real `UsersRepository` and `AuthenticationService` (Payload-backed) +- [ ] `packages/media/AGENTS.md` — full rewrite — media now has all Clean Architecture layers (entities, application, infrastructure, interface-adapters, DI, integrations/api) +- [ ] Plan 7 plan/spec docs — add a one-line note at the top noting that paths reference the pre-Plan-8 layout; link to refactor changelog + +--- + +## Notes for the doc-update pass author + +When updating external docs, apply these substitutions globally: + +| Old reference | New reference | +|---|---| +| `entities/.ts` | `entities/models/.ts` | +| `entities/errors.ts` | `entities/errors/.ts` (or `entities/errors/common.ts`) | +| `mock-.repository.ts` | `.repository.mock.ts` | +| `payload-.repository.ts` | `.repository.ts` (real impl is now the canonical name) | +| `-repository.interface.ts` | `.repository.interface.ts` | +| `class PayloadXRepository` | `class XRepository` | +| Use case calls `container.get(...)` inside its body | Use case is a factory function: `(deps) => async (input) => result` | +| Controller bundles multiple methods (`articles.controller.ts`) | One controller per use case (`get-articles.controller.ts`, `create-article.controller.ts`) | +| Test does `container.unbind(...).bind(...)` in `beforeEach` | Test constructs mocks and injects: `const useCase = signInUseCase(mockUsers, mockAuth);` | +| DI binds use case with `.to(...)` | DI binds use case with `.toDynamicValue((ctx) => factoryFn(ctx.container.get(...)))` | +| Use case + controller imports inject via container | Imports take dependencies as constructor/factory args | + +Add `I*UseCase` and `I*Controller` type alias examples wherever use cases / controllers are explained.