Skip to content

[Bug] declarationMap and sourceMap are on while files ships only dist, so all 1100 map files in the tarball point at a ../src that is not published and go-to-definition dead-ends for every consumer #1007

Description

@pathosDev

Problem

The tarball ships 1100 source-map files, all of them dangling. declarationMap and
sourceMap are on, but files publishes only dist/, so every map's sources entry
points at ../src/*.ts — a directory that is not in the package. None of them carry
sourcesContent, so there is no fallback either.

The consumer-visible effect: go-to-definition on any actor-ts symbol follows the
.d.ts.map, fails to find the .ts, and lands on the generated declaration instead;
a debugger stepping into framework code has nothing to show. Both features are worse
than if the maps were absent — a missing map degrades cleanly, a dangling one makes the
tool hunt for a file that will never appear.

The cost is 35% of the published bytes for a feature that cannot work.

Evidence

Both flags on:

tsconfig.json:11-12
    "declarationMap": true,
    "sourceMap": true,

src/ not published:

package.json:36-41
  "files": [
    "dist/",
    "README.md",
    "CHANGELOG.md",
    "LICENSE"
  ],

The emitted map, as installed from the tarball:

node_modules/actor-ts/dist/index.js.map (first 120 bytes)
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,
node_modules/actor-ts/dist/index.d.ts.map (first 120 bytes)
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,IAAI,EACJ,

../src/index.ts resolves, from the installed dist/, to
node_modules/actor-ts/src/index.ts. The installed package contains exactly four
entries: CHANGELOG.md, LICENSE, README.md, dist, package.json.

Census of the installed package:

js           550 files   2.34 MB  36.5%
d.ts         550 files   1.55 MB  24.1%
js.map       550 files   1.55 MB  24.0%
d.ts.map     550 files   0.70 MB  10.8%
other          4 files   0.29 MB   4.6%
TOTAL                    6.43 MB
maps:       1100 files   2.24 MB  = 35% of the package

Proposal

Three coherent options; the project should pick one rather than keep the current state,
which is the only one that costs bytes and delivers nothing.

  1. Drop the maps"declarationMap": false, "sourceMap": false in the build
    tsconfig. Removes 1100 files and 2.24 MB, and go-to-definition still lands on the
    .d.ts, which is the same place it lands today. Smallest change, no loss.

  2. Ship src/ — add "src/" to files. Costs roughly what the maps already cost,
    and in exchange go-to-definition reaches the real TypeScript, which is a genuinely
    better authoring experience for a framework people read the internals of. This is the
    option most type-heavy libraries take.

  3. Inline the sources"inlineSources": true alongside the existing flags. Maps
    become self-contained (sourcesContent populated), no src/ in the tarball, but the
    maps grow by roughly the size of src/.

Option 1 or 2. Option 3 is strictly worse than 2 for the same bytes, since it gives the
debugger the source but not the editor.

Note this interacts with #820 (per-subpath bundle-size budget): whichever option
lands changes the baseline that budget would be measured against, so it is worth doing
first.

Acceptance sketch

  • No .map file in the tarball references a path that is not in the tarball.
  • npm pack output either contains no maps, or contains src/, or contains maps with sourcesContent.
  • Go-to-definition from a consumer project lands somewhere real.
  • publint and attw stay green.

Verification status

Reproduced by execution. bunx tscnpm pack --pack-destination <scratch>npm install into a throwaway directory outside the repo. Every .map under the installed
dist/ was parsed and each sources entry resolved relative to the map's own directory:

map files: 1100 | with sourcesContent: 0 | dangling source refs: 1100

1100 of 1100 dangle; none carries inline content. The byte census above is measured on
the installed tree. git status --porcelain is clean afterwards; dist/ is gitignored.

(The original review note said 37% of 6.13 MB; the difference is packed-versus-installed
measurement. The count of dangling maps — all of them — is the same either way.)

Part of the production-readiness review batch — tracked in #913.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingpriority: lowNice-to-have / niche / demand-drivenproduction-goalBlocks or defines the path to production readiness

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions