Skip to content

build(core): stop shipping sourcemaps, expose schemas, tighten the barrel - #924

Open
ozymandiashh wants to merge 1 commit into
getagentseal:feat/core-extractionfrom
ozymandiashh:fix/core-package-hygiene
Open

build(core): stop shipping sourcemaps, expose schemas, tighten the barrel#924
ozymandiashh wants to merge 1 commit into
getagentseal:feat/core-extractionfrom
ozymandiashh:fix/core-package-hygiene

Conversation

@ozymandiashh

Copy link
Copy Markdown
Collaborator

Three defects in what @codeburn/core publishes. 0.9.20 is already on npm, so an external consumer meets all three today.

Sourcemaps ship, and they are most of the tarball

tsup emitted them and files ships dist, so 41 maps rode along — roughly 1.2 MB against 420 kB of JavaScript.

Worth being precise about the reasoning, because the obvious argument is wrong: the maps are not broken. esbuild embeds sourcesContent by default, so they are self-contained and debugging the published package works today. This is a weight decision. What is lost: stepping into @codeburn/core frames from an app, and symbolication of consumer stack traces. dist is unminified, so that loss is small.

Not emitting beats emitting-and-excluding: files is a whitelist, so excluding would need .npmignore or a post-build rm — a second mechanism to drift out of sync.

schemas/ ships but cannot be reached

files includes the directory and the repo publishes JSON Schemas there so non-TypeScript consumers can validate observations and findings. But the exports map had no entry, and an exports map blocks any path it does not list. The schemas were unreachable through the package specifier — shipped and inert.

The barrel omitted the detectors

./detectors is a documented public subpath, but src/index.ts re-exported only schema, observations, diagnostics, fingerprint and contracts, so the detector surface was invisible to anyone importing the package root.

Added as a named list rather than export *. The detectors module re-exports its own helpers, so star-exporting would have pulled clamp01, forEachCall, READ_TOOL_NAMES, EDIT_TOOL_NAMES and AVG_TOKENS_PER_READ into the root API — where renaming one or tuning a threshold constant becomes a visible break after 1.0. They stay reachable through ./detectors.

Support changes

verify-dist learned to resolve wildcard patterns. It also had a latent bug: for a pattern whose literal prefix contains no /, lastIndexOf returned -1 and it scanned a truncated directory, reporting "directory does not exist" instead of the real problem. It now walks recursively and includes dotfiles, because Node's * spans / and accepts them — verified with a probe package — so a shallower check would leave a future schemas/v2/ tree importable but unverified.

A new test resolves @codeburn/core/schemas/observation-0.2.0.json through the exports map in a spawned child and loads it as a JSON module, rather than reading the file off disk and calling that proof. It lives outside import-smoke deliberately: that suite blocks I/O to prove import-time purity, and loading a JSON module needs exactly the I/O it forbids.

Verification

Core suite 510 tests green. verify-dist reports 84 export targets across 42 subpaths. npm pack --dry-run: 112.6 kB packed, zero .map entries, schemas present. The wildcard fix was proved by temporarily adding a root-level "foo*" pattern and confirming the validator now diagnoses it truthfully.

Note for release: the package version is unchanged at 0.9.20, so this needs a version bump to reach consumers.

…rrel

Three defects in what `@codeburn/core` publishes. 0.9.20 is already on npm, so
an external consumer meets all three today.

**Sourcemaps.** tsup emitted them and `files` ships `dist`, so 41 maps rode
along — about 1.2 MB against 420 kB of JavaScript. They are self-contained
(esbuild embeds sourcesContent), so this is a weight argument, not a broken
one: what is lost is stepping into `@codeburn/core` frames in an app and
symbolicating consumer stack traces. `dist` is unminified, so that loss is
small.

**schemas/.** `files` shipped the directory but the exports map had no entry
for it, and an exports map blocks whatever it does not list — so the published
JSON Schemas, whose whole point is letting non-TypeScript consumers validate
observations and findings, could not be resolved at all.

**The barrel.** `src/index.ts` omitted detectors even though `./detectors` is a
documented public subpath, so the detector surface was invisible to anyone
importing the package root. Added as a named list rather than `export *`: the
detectors module re-exports its own helpers, and star-exporting would have made
`clamp01`, `READ_TOOL_NAMES` and `AVG_TOKENS_PER_READ` part of the root API,
where renaming one or tuning a constant becomes a visible break after 1.0.
They remain reachable through `./detectors`.

Two support changes fall out. `verify-dist` learned to resolve wildcard export
patterns — including the case where the literal prefix has no separator, which
previously scanned a truncated directory and reported a misleading error — and
walks recursively including dotfiles, because Node's `*` spans `/` and accepts
them, so a shallower check would leave a future `schemas/v2/` importable but
unverified.

A new test resolves a concrete schema through the exports map in a spawned
child and loads it as a JSON module. It lives outside import-smoke on purpose:
that suite blocks I/O to prove import-time purity, and reading a JSON module
needs exactly the I/O it forbids.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant