Reduce public API surface and implement API Extractor#30
Merged
Conversation
Adds an API Extractor pass to the build that rolls the per-file `.d.ts` files into a single trimmed `dist/index.d.ts` containing only `@public` symbols, and commits an `api/logger.api.md` report that CI gates against to catch accidental public-API drift. Every exported symbol is now explicitly classified: - @public: Logger, logger, createLogger, LoggerOptions, LogLevel, LogLevelNumeric, LogLevelPriority, LogMessage, MessageHandler, Transport, ConsoleTransport, QueuedTransport, FileTransport - @internal (stripped from shipped typings, kept for unit tests): chalk, LogLevelColor `LogLevelPriority` is kept @public because roku-debug consumes it to convert a LogLevel to its numeric form. Verified consumers (brighterscript, roku-debug, ropm, roku-report-analyzer) only reference @public symbols against the new trimmed surface. Also enables declarationMap so consumers get go-to-definition into source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…aps) Switch the `files` allow-list to ship only the runtime `.js` plus the single trimmed `dist/index.d.ts` rollup. The per-file declarations (Logger.d.ts, transports/*.d.ts, util.d.ts, Stopwatch.d.ts) and all source maps are no longer published, so consumers can only resolve types through the package root `@rokucommunity/logger` — there's no deep-import escape hatch around the trimmed public surface. This only affects the published tarball (24 files/80kB -> 11 files/47kB). The local build is unchanged: tsc still emits every per-file .d.ts to dist/, so API Extractor and the drift test work exactly as before, and `npm link` consumers still see the full on-disk dist. declarationMap stays enabled for link-time go-to-source navigation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
TwitchBronBron
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Introduces API Extractor to generate a trimmed, public-only
dist/index.d.tsand a committed API report (api/logger.api.md) that CI gates against.Before this PR, typings were a raw
export * from './Logger', which leaked internal symbols (LogLevelPriority,LogLevelColor,chalk) into the published surface. Now every export is explicitly tagged and the shipped.d.tscontains only what we mean to expose.API surface
@public(shipped):Logger,logger,createLogger,LoggerOptions,LogLevel,LogLevelNumeric,LogLevelPriority,LogMessage,MessageHandler,Transport,ConsoleTransport,QueuedTransport,FileTransport@internal(stripped from shipped typings, kept for unit tests):chalk,LogLevelColorHow it's wired
npm run buildnow runstscthenapi:build-and-validate(fails on untagged exports or report drift).npm run api:build-and-updateaccepts an intentional API change by rewritingapi/logger.api.md.src/apiExtractor.spec.tsruns the same gate in-process so it's covered by the normal test run.declarationMap: trueso consumers get go-to-definition into source.Consumer verification
Checked the actual downstream consumers in the local monorepo checkouts against the new trimmed surface:
Logger,LogLevelNumeric,LogMessage,LogLevel, defaultlogger, and the publicgetLogLevelNumeric()/getLogLevelText()methods.LogLevelPriority(LogLevelPriority[logger.logLevel]to convert a level to its numeric form for roku-deploy). To avoid breaking it,LogLevelPriorityis kept@public. (Note:logger.getLogLevelNumeric()is the public method that does the same thing, so roku-debug could migrate later — but no forced break here.)logger,Logger,LogLevel).Notes for the reviewer
api/logger.api.mdwas regenerated from a clean full build; an earlier draft of it had been generated from a partial build and was missing the@internalchalk/LogLevelColorentries (would have failed CI on a fresh checkout). That's corrected.npm run buildgreen.🤖 Generated with Claude Code