Repository navigation
fix(api): keep the config and artifact types stable for consumers - #48
Merged
Merged
Conversation
Keep authoring config types schema-input-derived and resolved config schema-output-derived. Materialize their declarations with the TypeScript checker so consumers do not inherit Zod internals or ambient Node types. Warn about stripped config keys, mark exposed source state unstable, and give artifact files and managed paths one code-unit ordering. Pin runtime exports and compile all public types in isolated consumers, including hoisted Zod 3 definitions. The Uint8Array file-value change needs the matching explicit UTF-8 conversions in the companion partials change. That owned file is deliberately left for its implementer.
FileValue is now string | Uint8Array, and Uint8Array.toString() joins byte values with commas instead of decoding them. Decode through Buffer.from so a Uint8Array value is read as UTF-8 text.
Match schema-derived alias expressions before replacing declarations, so a public type with the same name cannot be silently overwritten. Reuse existing structural aliases and emit multiline literals for readable output. Typecheck the publishable declaration with no ambient types and full library checking. This catches unqualified Zod helpers and missing dependencies during the build.
Track diagnostics by file and field instead of loader identity, so prune and diff do not warn again when they reload a project. Keep new keys visible without relying on the config module cache. Use manifest wording for legacy and canonical source manifests and MCP shipping manifests. Keep intentional record passthroughs silent.
Document string or Uint8Array artifact values and explicit UTF-8 decoding, including Node buffers. State which authored manifests receive stripped-key warnings and that repeated loads do not duplicate them.
# ------------------------ >8 ------------------------ # Do not modify or remove the line above. # Everything below it will be ignored. # # Conflicts: # src/config.ts
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
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.
Problem
The public config and type contract was not safe to keep stable:
defineConfigand the config types used the schema's output type. The first field with a.default()would have made that field required, and existingdefineConfig({...})calls would have stopped compiling.dist/index.d.tsreferenced zod internals (z.core), so the published types depended on zod's type layout.FileValueusedBufferwithout importing it. A consumer withtypes: []andskipLibCheck: falsefailed with TS2591.component:or a target namedcodxewere dropped without a word.filesandmanagedPathsin anArtifactused different sort orders.ResolvedProjectexposed internal source state with no stability note.Change
PluginpackConfig). The parsed config is a newResolvedPluginpackConfig. Both still derive from the zod schemas, and REVIEW.md says so.scripts/materialize-config-types.mjs) asks the TypeScript checker for the evaluated schema types and writes them intodist/index.d.tsas plain multi-line types. It replaces only aliases whose right-hand side is a schema-derived type, fails on any name collision, and typechecks the result withtypes: []andskipLibCheck: false.FileValueisstring | Uint8Array. Runtime values are still Buffers, and the README explains how to decode them.manifestandentrypassthroughs are not reported.ResolvedProject's internal fields andSourceProviderare marked@unstable.srcanddist, and compile a consumer that imports every exported type, both without zod and with zod 3 hoisted.Breaking changes
A TypeScript consumer that calls
.toString("utf8")on an artifact file value now needsBuffer.from(value).toString("utf8").Testing
npm run checkpasses. Tests cover a virtual schema that gains a default, an alias name collision, and an unresolved$brandtype.