Skip to content

refactor(internal): audit package cohesion across internal/ #3

Description

@grantcarthew

Walk each package under internal/ and check whether the files inside still match the package's stated purpose, or whether responsibilities have drifted in as the codebase has grown.

Packages to audit:

  • cache
  • cli
  • config
  • cue
  • detection
  • doctor
  • modules
  • orchestration
  • registry
  • shell
  • temp
  • tui

For each package, ask:

  1. Does every file in the package contribute to the role the package name implies, or does some content belong elsewhere?
  2. Are any single files doing two jobs (e.g. a "primary type + a grab-bag of utility functions other packages reach into")? If so, would a clean split improve discoverability?
  3. Are there parallel type hierarchies across packages that describe the same underlying data — and if so, is the split still earning its keep?
  4. Is the dependency direction acyclic and one-way (UI/CLI → runtime → utilities), with no back-edges from lower layers to higher ones?
  5. Are public symbols on the package narrow and intentional, or accidental (an internal helper that became Exported because one cross-package caller needed it)?

Out of scope:

Deliverable:

  • A short note per package describing what's in scope vs out of scope, what would move, and what stays. Treat it as an inventory pass before any restructuring PR — the moves themselves can land incrementally and don't need to be one giant change.

Surfaced by a pre-commit review conversation (.start/reviews/2026-05-16-pre-commit-01.md).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions