[claude]

Requested by Sebastian Konowrocki · Slack thread

Before: @leancodepl/logger's public API had no TSDoc, so editors showed no hover docs for createLogger, withContext, withMiddleware, the createCliLogger/createJsonLogger/createNestJsonLogger presets, or the log-level helpers. The core type SupportedOutput = boolean | number | object | string | unknown silently collapsed to unknown (any union containing unknown is just unknown), defeating the generic output inference the logger is built around.

After: The public symbols carry TSDoc matching the @leancodepl/utils documentation bar (summary, @template/@param/@returns, @example). SupportedOutput is now boolean | number | object | string, so output types are actually inferred instead of widening to unknown. No runtime behavior changes; the logger still builds and all tests pass.

How:

• Adds TSDoc across packages/logger/src/lib/*.ts: logger.ts (types + createLogger, isContextualMessage), cliLogger.ts, jsonLogger.ts, nestLogger.ts, logLevels.ts.
• Removes the unknown member from SupportedOutput.
• Narrows the one caller this affected: nestLogger.ts adapts NestJS's untyped (any) logger inputs to SupportedOutput at the boundary via a small, documented asSupportedOutput helper. The values are forwarded unchanged — downstream serialization (formatNestMessage) already handles every runtime type — so this only reconciles the static types without altering behavior, and avoids a blanket as any.

Verified locally: nx run logger:typecheck reports no new errors from this change (the only remaining logger:typecheck failures — TS6307 spec-project file-list and TS7031 in logger.spec.ts — pre-exist on main); nx run logger:build succeeds; nx run logger:test passes (10/10).

---

Generated by Claude Code

[konowrockis]

Do we need to update readme for that? There's skill for generating readmes afair

[claude]

Sprawdziłem to.

Czy istnieje generator README? Nie. W repo nie ma żadnego mechanizmu generowania README — brak skilla do generowania README, brak skryptu (tools/scripts/ zawiera tylko copy.mjs i publish.mjs, żaden z nich nie dotyka README), brak generatora nx oraz brak konfiguracji typedoc/api-extractor podpiętej do jakiegokolwiek targetu. (@microsoft/api-extractor pojawia się wyłącznie jako tranzytywna zależność w package-lock.json, nie jest nigdzie używany.)

Generowane czy pisane ręcznie? packages/logger/README.md jest pisane ręcznie — narracyjny opis i przykłady, brak jakichkolwiek markerów typu „auto-generated / do not edit”. To samo dotyczy pozostałych pakietów (np. @leancodepl/utils).

Czy potrzebna aktualizacja README? Nie. Zmiany z tego PR-a nie dotykają treści widocznej w README:

• TSDoc to wewnętrzne komentarze dokumentacyjne (hover w edytorze), które w ręcznie pisanym README i tak nie są odwzorowywane.
• Usunięcie unknown zmienia samą definicję typu SupportedOutput (boolean | number | object | string | unknown → bez unknown). README nigdzie nie pokazuje tej definicji — SupportedOutput występuje wyłącznie jako importowana nazwa typu w przykładach (sekcja „Typing Functions”), które pozostają poprawne i niezmienione.

Nie wprowadzałem żadnych zmian w README ani niczego nie pushowałem.

[konowrockis]

There's rule for that https://github.com/leancodepl/js_corelibrary/blob/main/.cursor/rules/readme.mdc

[claude]

Masz rację — jest reguła .cursor/rules/readme.mdc i mój wcześniejszy sprawdzian ją pominął. Skupiłem się na szukaniu generatora/skilla/skryptu/typedoc i nie uwzględniłem tej reguły Cursora, która opisuje konwencję README. Przepraszam za to.

Co wymaga reguła: struktura README z sekcjami ## Installation → ## API → ## Usage Examples, bez sekcji licencji. Kluczowy punkt to sekcja 7 („Complete Documentation Coverage"): każda eksportowana funkcja/klasa musi mieć nie tylko JSDoc, ale też wpis w sekcji ## API z pełnym opisem parametrów i wartości zwracanej (sekcje 3 i 8: „Verify each JSDoc export appears in README API section"). Reguła wprost wiąże JSDoc z sekcją API — a właśnie JSDoc do publicznego API dodaje ten PR.

Decyzja: README pakietu @leancodepl/logger nie miało ani sekcji ## Installation, ani ## API — narracyjny opis i przykłady, ale żaden eksport nie był udokumentowany w formacie wymaganym przez regułę. Skoro ten PR dodaje JSDoc do publicznego API, brak odpowiadającej mu sekcji API zostawiał pakiet niezgodny z regułą dokładnie na tym wymiarze, który PR zmienia. Dlatego zaktualizowałem README (commit 85d14483, wypchnięty na docs/logger-tsdoc):

• Dodałem ## Installation oraz ## API z wpisami dla wszystkich eksportowanych funkcji: createLogger, isContextualMessage, createCliLogger, createJsonLogger, createNestJsonLogger, isLogLevelEnabled — z parametrami (pełne typy), wartością zwracaną i krótkim, kompilowalnym przykładem. Opisy pochodzą wprost z TSDoc dodanego w tym PR.
• Dodałem listę eksportowanych wartości i typów (LogLevel, allLogLevels, defaultEnabledLogLevels, logLevelToLabel, SupportedOutput, DefaultContext, LoggerMessage, MethodHandler, Logger, LoggerWithContext, CliLogger/JsonLogger/NestJsonLogger, LoggerService). SupportedOutput jest opisany w nowej, zawężonej formie (boolean | number | object | string), co odzwierciedla usunięcie unknown z tego PR.
• Zgodnie z regułą @template zostały pominięte w README, nazwy bibliotek/funkcji są w backtickach, brak sekcji licencji. Istniejące przykłady zachowałem pod sekcją ## Usage Examples.

Trzymałem się zakresu tego PR (dokumentacja publicznego API loggera + zmiana typu) — nie przepisywałem README innych pakietów.

[claude]

CI "Build & Test" — analiza niepowodzenia

Co padło: krok Typecheck (nx affected -t typecheck), zadanie @leancodepl/logger:typecheck. Pozostałe afektowane projekty przechodzą. Błędy:

src/lib/cliLogger.spec.ts(2,33): error TS6307: File '.../cliLogger.ts' is not listed within the file list of project '.../tsconfig.spec.json'.
src/lib/cliLogger.ts(10,8):     error TS6307: File '.../logger.ts'   is not listed within the file list of project '.../tsconfig.spec.json'.
src/lib/cliLogger.ts(18,8):     error TS6307: File '.../logLevels.ts' is not listed within the file list of project '.../tsconfig.spec.json'.

Przyczyna: to błąd istniejący wcześniej, niezwiązany z tym PR. packages/logger/tsconfig.spec.json ma include na pliki spec, ale nie ma references do tsconfig.lib.json. Przy tsc --build pliki spec importują ./logger, ./cliLogger, ./logLevels, których nie widzą w swoim programie → TS6307. Błąd reprodukuje się 1:1 na czystym main (base 9f8c60f), a zmiany w tym PR (kod loggera, asSupportedOutput, README) go nie powodują — wręcz usunęły kilka dodatkowych błędów TS7031 obecnych na base.

Dlaczego ujawnił się dopiero teraz: na main doszedł commit cc8ca37f ("ci: add typecheck gate to CI workflow") dodający krok Typecheck (nx affected -t typecheck). Dla zdarzenia pull_request GitHub uruchamia definicję workflow z gałęzi bazowej (main), więc ten PR dostał nową bramkę typecheck, mimo że ci.yaml na samej gałęzi PR jej jeszcze nie ma. Ponieważ PR dotyka pakietu logger, affected wybiera logger:typecheck i bramka łapie istniejący błąd konfiguracji.

Nie wprowadzam zmiany w kodzie (zgodnie z klasyfikacją: failure pre-existing). Rekomendowana, jednoliniowa i bezpieczna naprawa odblokowująca PR (zweryfikowana lokalnie — logger:typecheck przechodzi):

// packages/logger/tsconfig.spec.json
"references": [{ "path": "./tsconfig.lib.json" }]

Najlepiej w osobnym PR/commicie naprawkowym (dotyczy konfiguracji, nie tematu tej dokumentacji). Po jego scaleniu wystarczy rebase tego PR na main.

[konowrockis]

@claude zrebasuj na najnowszego maina

[claude]

Zrebasowano gałąź na najnowszy main (38c6f326, po scaleniu #284). Zmiany w logger.ts połączyły się bez konfliktu — w różnych częściach pliku — więc współistnieją obie: usunięcie unknown z SupportedOutput (+ helper asSupportedOutput) z tego PR-a oraz zabezpieczenie noUncheckedIndexedAccess (handlers[key]?.(...)) z #284. Lokalnie nx affected -t lint test build typecheck --base=origin/main przechodzi dla całego zestawu (logger, intl, mail-translation, folder-structure-cruiser). Nowy HEAD: 53bf8ade.