updated .golangci.yml and CLAUDE.md

quietlight

May 18, 2026, 11:57 PM

TSPKDAFW3LRT5UXGNSJ2MOLSILLIGUHUVS7S2CLAWRZFMVBBMD4AC

Dependencies

• [2] NQPVZ3PP first phase of utils refactor, all realted to db interfaces
• [3] KZKLAINJ run out of space on nest, cleaned out
• [4] VYNOHQJW tidied up CLAUDE.md
• [5] VNFPBXF7 moved dep tests to golangci-lint
• [6] 2Y5U3QPU added gosymdb
• [7] JZRF7OBJ refactor to get db omports out of utils, but still have failing tests, may need updating
• [8] 3DVPQOKB big tidy up of tools/
• [9] JAT3DXOL cyclo over 15
• [10] I4CMOMXF dot files

Change contents

• edit in CLAUDE.md at line 12
  [3.1195618]→[3.3404:3405](∅→∅),[3.3405]→[2.53118:53204](∅→∅)
  −

  − If called by `cmd/`, it goes in `tools/`. If called by `tools/`, it goes in `utils/`.
• replacement in CLAUDE.md at line 13
  [3.1195619]→[3.6929:7009](∅→∅)
  − **Dependency rule:** packages may only import packages below them in this list:
  [3.1195619]

  [3.7299]
  + Enforced by `depguard` in `.golangci.yml`. A package may only import from packages **below** it:
• replacement in CLAUDE.md at line 16
  [3.1196121]→[3.241:308](∅→∅),[3.308]→[3.1196264:1196332](∅→∅),[3.1196264]→[3.1196264:1196332](∅→∅),[3.1196332]→[3.316203:316379](∅→∅),[3.316379]→[2.53205:53315](∅→∅),[3.9940]→[3.7389:7434](∅→∅),[2.53315]→[3.7389:7434](∅→∅),[3.316462]→[3.7389:7434](∅→∅),[3.360]→[3.7389:7434](∅→∅),[3.7434]→[2.53316:53628](∅→∅)
  − main.go → CLI dispatcher (import | sql | dataset | ...)

  − cmd/*.go → CLI commands (flags → tools → JSON output)

  − tools/*.go → CLI tools: sql, export, cluster, dataset, location, pattern, time, prepend

  − tools/calls/ → Call processing (filesystem .data/WAV, NO database access)

  − tools/import/ → Import operations (bulk, file, files, segments, unstructured; defines own DB interfaces)

  − tui/ → Interactive classify UI

  − db/ → Database connection + types + transactions (defines local mutator interface)

  − mapping/ → Mapping file types + loader (leaf package, shared by tools/calls/ and tools/import/)

  − utils/*.go → Reusable helpers (leaf package, no database/sql import, no `*Input`/`*Output` structs)
  [3.1196121]

  [3.1196493]
  + main.go

  + cmd/ → tools, tools/calls, tools/import, tui

  + tools/ → db, audio, wav, spectrogram, astro, mapping, utils

  + tools/calls/ → db, audio, wav, spectrogram, mapping, utils (NO DB access in practice)

  + tools/import/ → db, wav, astro, mapping, utils (defines own Mutator/Reader)

  + tui/ → audio, wav, spectrogram, utils (NO db, NO cmd)

  + db/ → wav (GainLevel only), utils (Placeholders only)

  + spectrogram/ → audio, wav

  + wav/ → audio, astro, utils

  + audio/ → (stdlib + go-dsp)

  + astro/ → (stdlib + suncalc)

  + mapping/ → (stdlib)

  + utils/ → (stdlib only — true leaf)
• replacement in CLAUDE.md at line 33
  [3.1196963]→[2.53629:53883](∅→∅)
  − **DB interface convention:** Each consumer defines its own minimal interface (Mutator, Reader, MappingQuerier, etc.) using `*Context` method variants. No god-interfaces in `db/`. Two near-identical interfaces in two packages beats the wrong abstraction.
  [3.1196963]

  [3.1196967]
  + **DB interface convention:** Each consumer defines its own minimal interface (`Mutator`, `Reader`, `Querier`, etc.) using `*Context` method variants only. No god-interfaces in `db/`. Two near-identical interfaces in two packages beats the wrong abstraction.

  +

  + **`utils/` invariants:** no `database/sql` import, no `skraak/*` import, no `*Input`/`*Output` structs.
• replacement in .golangci.yml at line 11
  [3.22119]→[2.56059:56076](∅→∅)
  − # - depguard
  [3.22119]

  [3.488]
  + - depguard
• replacement in .golangci.yml at line 35
  [3.1341]→[2.56077:58903](∅→∅)
  − # depguard:

  − # rules:

  − # # Package dependency rules — see CLAUDE.md "Package Organization"

  − # # Packages may only import packages below them in the list:

  − # # cmd → tools, tools/calls, tools/import, tui, utils, db

  − # # tools/calls → utils, db

  − # # tools/import → utils, db

  − # # tools → utils, db

  − # # tui → tools/calls, utils

  − # # db → utils

  − # # utils → (nothing — leaf package)

  − # utils:

  − # files:

  − # - "**/utils/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "utils is the leaf package"

  − # - pkg: "skraak/tools"

  − # desc: "utils is the leaf package"

  − # - pkg: "skraak/tui"

  − # desc: "utils is the leaf package"

  − # - pkg: "skraak/db"

  − # desc: "utils is the leaf package"

  − # db:

  − # files:

  − # - "**/db/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "db may only import utils"

  − # - pkg: "skraak/tools"

  − # desc: "db may only import utils"

  − # - pkg: "skraak/tui"

  − # desc: "db may only import utils"

  − # tui:

  − # files:

  − # - "**/tui/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "tui must not import cmd"

  − # - pkg: "skraak/db"

  − # desc: "tui must not import db"

  − # - pkg: "skraak/tools$"

  − # desc: "tui must import from tools/calls, not tools"

  − # calls:

  − # files:

  − # - "**/tools/calls/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "tools/calls must not import cmd"

  − # - pkg: "skraak/tools"

  − # desc: "tools/calls must not import parent package"

  − # - pkg: "skraak/tui"

  − # desc: "tools/calls must not import tui"

  − # import:

  − # files:

  − # - "**/tools/import/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "tools/import must not import cmd"

  − # - pkg: "skraak/tools"

  − # desc: "tools/import must not import parent package"

  − # - pkg: "skraak/tui"

  − # desc: "tools/import must not import tui"

  − # tools:

  − # files:

  − # - "**/tools/*.go"

  − # deny:

  − # - pkg: "skraak/cmd"

  − # desc: "tools must not import cmd"

  − # - pkg: "skraak/tui"

  − # desc: "tools must not import tui"

  − # - pkg: "skraak/tools/calls"

  − # desc: "tools must not import tools/calls (sub-package)"

  − # - pkg: "skraak/tools/import"

  − # desc: "tools must not import tools/import (sub-package)"
  [3.1341]

  [3.5137]
  + depguard:

  + rules:

  + # Package dependency rules — see CLAUDE.md "Package Organization".

  + # A package may only import packages BELOW it in the layered graph:

  + # cmd → tools, tools/calls, tools/import, tui, db, audio, wav, spectrogram, astro, mapping, utils

  + # tools/calls → db, audio, wav, spectrogram, mapping, utils

  + # tools/import → db, wav, astro, mapping, utils

  + # tools → db, audio, wav, spectrogram, astro, mapping, utils

  + # tui → audio, wav, spectrogram, utils

  + # db → wav, utils

  + # spectrogram → audio, wav

  + # wav → audio, astro, utils

  + # audio, astro, mapping, utils → (no skraak/* imports)

  + utils:

  + files: ["**/utils/*.go"]

  + deny:

  + - { pkg: "skraak/", desc: "utils is the leaf package — no skraak/* imports" }

  + mapping:

  + files: ["**/mapping/*.go"]

  + deny:

  + - { pkg: "skraak/", desc: "mapping is a leaf package — no skraak/* imports" }

  + audio:

  + files: ["**/audio/*.go"]

  + deny:

  + - { pkg: "skraak/", desc: "audio is a leaf package — no skraak/* imports" }

  + astro:

  + files: ["**/astro/*.go"]

  + deny:

  + - { pkg: "skraak/", desc: "astro is a leaf package — no skraak/* imports" }

  + wav:

  + files: ["**/wav/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "wav must not import cmd" }

  + - { pkg: "skraak/tools", desc: "wav must not import tools" }

  + - { pkg: "skraak/tui", desc: "wav must not import tui" }

  + - { pkg: "skraak/db", desc: "wav must not import db" }

  + - { pkg: "skraak/spectrogram", desc: "wav must not import spectrogram" }

  + spectrogram:

  + files: ["**/spectrogram/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "spectrogram must not import cmd" }

  + - { pkg: "skraak/tools", desc: "spectrogram must not import tools" }

  + - { pkg: "skraak/tui", desc: "spectrogram must not import tui" }

  + - { pkg: "skraak/db", desc: "spectrogram must not import db" }

  + - { pkg: "skraak/utils", desc: "spectrogram should only depend on audio + wav" }

  + - { pkg: "skraak/astro", desc: "spectrogram should only depend on audio + wav" }

  + - { pkg: "skraak/mapping", desc: "spectrogram should only depend on audio + wav" }

  + db:

  + files: ["**/db/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "db may only import wav + utils" }

  + - { pkg: "skraak/tools", desc: "db may only import wav + utils" }

  + - { pkg: "skraak/tui", desc: "db may only import wav + utils" }

  + - { pkg: "skraak/spectrogram", desc: "db may only import wav + utils" }

  + tui:

  + files: ["**/tui/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "tui must not import cmd" }

  + - { pkg: "skraak/db", desc: "tui must not import db" }

  + - { pkg: "skraak/tools$", desc: "tui must import from tools/calls, not tools" }

  + - { pkg: "skraak/tools/import", desc: "tui must not import tools/import" }

  + calls:

  + files: ["**/tools/calls/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "tools/calls must not import cmd" }

  + - { pkg: "skraak/tools$", desc: "tools/calls must not import parent tools package" }

  + - { pkg: "skraak/tools/import", desc: "tools/calls must not import tools/import (sibling)" }

  + - { pkg: "skraak/tui", desc: "tools/calls must not import tui" }

  + import:

  + files: ["**/tools/import/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "tools/import must not import cmd" }

  + - { pkg: "skraak/tools$", desc: "tools/import must not import parent tools package" }

  + - { pkg: "skraak/tools/calls", desc: "tools/import must not import tools/calls (sibling)" }

  + - { pkg: "skraak/tui", desc: "tools/import must not import tui" }

  + tools:

  + files: ["**/tools/*.go"]

  + deny:

  + - { pkg: "skraak/cmd", desc: "tools must not import cmd" }

  + - { pkg: "skraak/tui", desc: "tools must not import tui" }

  + - { pkg: "skraak/tools/calls", desc: "tools must not import tools/calls (sub-package)" }

  + - { pkg: "skraak/tools/import", desc: "tools must not import tools/import (sub-package)" }