Skip to content

chore(miner): migrate packages/loopover-miner from plain .js + hand-maintained .d.ts to real TypeScript #7290

Description

@JSONbored

Problem

packages/loopover-miner/lib/** is 117 plain .js files, each with a hand-maintained .d.ts
sibling providing its types to consumers. Nothing actually verifies these stay in sync: the root
tsconfig.json's include is ["src", "test", ...] -- it never includes
packages/loopover-miner/lib itself, so the .js implementation is never compiled against its own
.d.ts. Type drift is only ever caught by luck, if some test/unit/miner-*.test.ts file's usage
happens to exercise the exact mismatched signature -- not by the compiler, which is the entire
point of having types. This is double the maintenance burden (every signature change means editing
two files by hand, in sync, with nothing enforcing it) for none of TypeScript's actual safety
guarantee.

Why plain .js was chosen (context, not a defense of the current gap)

packages/loopover-miner's own build script is literally node --check on every file -- no
tsc compilation step. This is a deliberate, real tradeoff: the package ships as directly-runnable
Node.js (npm install -g @loopover/miner then loopover-miner ... works with no build/transpile
step), which is genuinely valuable for a CLI tool. That property is worth preserving. What's NOT
worth preserving is losing compiler-verified types to get it -- tsc's own output can be plain,
directly-runnable JS (strip types, keep the code), so a proper TypeScript source with a real build
step does not have to sacrifice the zero-transpile-at-runtime property; it just needs the build
step to happen once, ahead of publish, instead of never.

Proposal

Convert packages/loopover-miner/lib/** (and bin/**) from .js + hand-maintained .d.ts to
real .ts source, compiled via tsc into the published package's actual JS output (mirroring how
packages/loopover-engine's src/ is already 100% real TypeScript with zero hand-maintained
.d.ts files anywhere in it -- the proven precedent in this same monorepo). The compiled output
stays a directly-runnable node bin/loopover-miner.js-shaped artifact; only the source changes,
not the distribution shape.

Deliberately NOT scoped as one PR. 117 files is too large and too risky for a single change --
this is a large, multi-phase migration, not a mechanical one-shot. Recommended phasing, smallest
and most-isolated first (matching the incremental discipline already proven tonight for the
storage-seam migration):

  1. Build tooling: add a real tsc build step to packages/loopover-miner's own package.json
    (build/typecheck scripts), a packages/loopover-miner/tsconfig.json, and CI wiring -- with
    zero source files converted yet, just proving the build pipeline itself works end-to-end
    (compiles, the CLI still runs, the package still publishes correctly) against a trivial single
    converted file as a smoke test.
  2. Convert the leaf-most, lowest-fan-in modules first (small, standalone stores/utilities with few
    internal dependents) -- lower risk, faster to review, builds momentum and catches build-tooling
    issues on small blast-radius changes before tackling anything foundational.
  3. Convert the CLI command files (*-cli.js) and bin/*.js entry points.
  4. Convert the foundational/most-depended-on modules last (local-store.js, store-db-adapter.js,
    event-ledger.js, and anything else many other files import) -- highest blast radius, do this
    once the pattern is fully proven on everything else.
  5. Remove every now-redundant hand-maintained .d.ts file as its .js sibling converts (a .ts
    file's types ARE the implementation -- no separate declaration file needed once converted).

Each phase should be filed as its own follow-up issue once the prior phase lands, sized to a
reviewable PR (a handful of files, not all-at-once) -- do not attempt to enumerate all 117 files
into sub-issues up front; let the phasing above guide real-time scoping as work progresses.

Deliverables

  • Phase 1: real tsc build pipeline wired for packages/loopover-miner, proven against one
    converted file
  • Phase 2+: remaining files converted in reviewable batches per the phasing above (tracked via
    follow-up issues, not enumerated here)
  • Every hand-maintained .d.ts removed once its .js sibling converts
  • Root tsconfig.json (or the package's own) actually type-checks the converted source against
    its own implementation, closing the drift gap this issue exists to fix

Test Coverage Requirements

No behavior should change from this migration alone -- it's a source-representation change, not a
logic change. Existing tests must continue to pass unmodified (only import paths/build output
shape might need adjustment). packages/loopover-miner/lib/** remains under Codecov's normal
99% patch-coverage gate for any genuinely new code introduced alongside a conversion PR.

Expected Outcome

packages/loopover-miner's source is real, compiler-verified TypeScript with the same
zero-transpile-at-runtime distribution shape it has today, and the current double-maintenance,
drift-prone .js + hand-authored .d.ts pattern is gone.

Links & Resources

  • packages/loopover-engine/src/** -- the proven, already-100%-TypeScript precedent in this same
    monorepo
  • packages/loopover-miner/package.json's build script -- the current node --check-only build
  • Root tsconfig.json -- confirms packages/loopover-miner/lib is not in include today

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.gittensor:priorityMaintainer-selected Gittensor priority — scores a 1.5x multiplier.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions