Encode the feature-folder layering contract as a CI gate: lib is the floor,
store/ui must not import features/app, cross-feature only via the barrel, no
cycles. dependency-cruiser resolves the @/ alias via tsconfig; tests excluded.
Land as a ratchet: the 738 current violations are seeded into
.dependency-cruiser-known-violations.json and ignored via --ignore-known, so
HEAD is green and any NEW violation fails CI. Regenerate the baseline as the
drain removes an exception; the count is the tracked residual debt.
Wired via `npm run dep:check` into a new dependency-cruiser job in eslint.yml
and the ci-ok required-check aggregate.
The 945-LOC lib/api/library.ts (cucadmuh's deliberate 'one thin file' library_*
command surface) exceeded the ~500 LOC ceiling. Split by its own PR-5 section
comments into library/{dto,reads,sync,stats,events}.ts + a private library/internal.ts
(the shared serverId↔indexKey helpers). lib/api/library.ts is now a barrel that
re-exports all of them, so @/lib/api/library stays the single import point — every
consumer (incl. the Settings LibraryTab) and all 11 vi.mock('@/lib/api/library')
test factories are unchanged. Pure reorganization, no logic change; tests pass
unmodified. Largest module is now dto.ts (466, pure types).
a11y-branch hold lifted. Pure share machinery (no @/features runtime imports) →
lib/share: shareLink, shareSearch, shareServerOriginLabel, copyEntityShareLink
(+tests). The two orchestrators that runtime-import offline/playback/orbit →
new features/share: applySharePaste, enqueueShareSearchPayload (+test); doc-only
barrel, consumers use deep paths. No low-layer consumes the orchestrators, so no
seam is needed — pure move, tests pass unmodified. Drains utils/share.
Only import lines changed in the PasteClipboardHandler consumer (logic untouched).
a11y-branch hold lifted (Frank: modals get re-refactored separately, no rebase to
protect). Both were only blocked by their modal consumers:
- licensesData (pure licenses.json lazy-loader) → features/settings/utils; main
consumer is the settings LicensesPanel. JSON dynamic import absolutized to
@/data/licenses.json.
- userMgmtHelpers (pure formatLastSeen, lib/format only) → lib/format; multi-feature
consumer set, same class as playlistDetailHelpers.
Drains utils/componentHelpers (dir removed). Only import lines changed in the
LicenseTextModal/SongInfoModal consumers (logic untouched); tests pass unmodified.
uploadArtistImage lived in lib/api/subsonicPlaylists but is artist-domain and
consumed only by features/artist/runArtistDetailActions. Relocated to
lib/api/subsonicArtists (its rightful API module); consumer repointed. Also fixes
a stale doc comment in features/randomMix/index.ts (mixRatingFilter now lives in
features/playback). No behavior change; tests pass unmodified.
cardGridLayout's only store dep was three grid-column constants it imported from
authStoreDefaults. Flipped ownership: the constants now live in lib/util/cardGridLayout
(pure layout config) and authStoreDefaults re-exports them (store→lib), so the auth
settings clamp/default and every existing consumer are unchanged. cardGridLayout is now
store-free and homes in lib/util alongside the other pure helpers — consumed cleanly by
ui/VirtualCardGrid + cover/layoutSizes. Resolves the documented store-free-lib block for
the card-grid layout helper. Pure move + constant relocation; tests pass unmodified.
The connection-reachability + Subsonic network-guard helpers were pinned low by
four lib/api consumers (subsonicLibrary/Playlists/Ratings/Scrobble) yet ran two
lower-layer→feature inversions. Both removed without a registry:
- devOfflineBrowseStore is a self-contained DEV-only toggle with zero offline-
feature coupling — it was only colocated there. Relocated features/offline/store
→ store/ (global). The @/features/offline barrel re-exports it so feature/UI
consumers are unchanged; the three lower-layer readers (subsonicNetworkGuard,
activeServerReachability, useConnectionStatus) now import it from @/store directly.
- subsonicNetworkGuard's only other feature dep was playback's resolvePlaybackUrl,
used solely for the psysonic-local:// skip check. Added hasLocalPlaybackUrl to the
existing M4 substrate store/localPlaybackResolve — it mirrors resolvePlaybackUrl's
local-source branch exactly (same profile resolution; the empty-serverId playback
fallback never applies in the guard), so the skip stays bit-identical.
network/ (subsonicNetworkGuard + activeServerReachability + tests) → lib/network,
now @/features-free. useConnectionStatus is now iron-rule-clean and stays in hooks/
(cross-cutting). Test mocks retargeted to the new seam modules.
Behavior-adjacent (covered by suite; default paths identical): the local-bytes skip
helper — flag for offline-playback runtime QA alongside the M4 media-resolver seam.
Two lower-layer→feature inversions removed:
- Detail-route predicates (isAlbumDetailPath/isArtistDetailPath/isComposerDetailPath)
were defined in features/album's browse store but are pure URL checks. Extracted
to lib/navigation/detailRoutePaths; the browse store re-exports them so the
@/features/album barrel surface is unchanged. This frees albumDetailNavigation of
its only @/features import, so it moves utils/navigation → lib/navigation (drains
utils/navigation). Also fixes the M5 isArtistDetailPath misplacement.
- mixRatingFilter's sole feature dep is playback's userRatingOverrides and its only
binding consumer is playback's buildInfiniteQueueCandidates, so it belongs in the
playback feature: utils/mix → features/playback/utils (drains utils/mix). The
earlier handoff note that lib/api/subsonicStarRating consumes it was stale — that
is only a code comment, verified no runtime import.
Pure moves; tests pass unmodified. The share cluster + switchActiveServer stay in
utils/ — they are imported by the a11y-HELD PasteClipboardHandler, so relocating
them would rewrite a do-not-touch file.
Per-file routing of the 9-file utils/componentHelpers grab-bag, each driven by
its verified consumer set:
- contextMenu{Actions,Helpers} → features/contextMenu/utils (sole consumer)
- queuePanelHelpers → features/queue/utils (sole consumer)
- nowPlayingHelpers → features/nowPlaying/utils; isRealArtistImage split out to
cover/ (consumed by cover/artistHero, a lower layer)
- appUpdaterHelpers(+test) + listReorder(+test) → lib/util (config/ + lib/hooks
consume them; pure)
- playlistDetailHelpers → lib/format (consumed by 3 features; pure)
- appShellHelpers → app/ (app-shell consumers only)
- userMgmtHelpers left in place: consumed by the a11y-HELD SongInfoModal, so a
move would rewrite a do-not-touch file (same block as licensesData).
Pure moves; tests pass unmodified.
Both one-time boot migrations are consumed only by app/MainApp; advancedModeMigration runtime-imports @/features/artist + @/features/playlist, so it is app-level orchestration (an inversion if kept in utils/ infra). Pure move.
Psychotoxical