docs: document the entire public surface; internalize Zod (#29)#31
Merged
Conversation
Clears the 238 `deno doc --lint` errors across the public surface of
`@dv-cli/dv` and `@dv-cli/clipc`, then flips the CI doc-lint step from
`continue-on-error` to a hard gate.
JSDoc sweep
- Documents every exported symbol on the `@dv-cli/dv` library entry —
runners, their option/result interfaces (and each field), and the
Plan contract — converting the existing `//` notes to `/** */`.
Public-surface type plumbing
- Re-exports the domain types reachable through the public option/result
shapes (ChangeType, Package, PluginReference, PluginAssignment,
ResolvedPlugin, SlugRandomSource, ConfigMigrationStepResult,
MigrationChange, PLUGIN_OP_NAMES) so they're nameable rather than
reached through indexed-access types.
- Rewrites the Plan contract as hand-written interfaces instead of
`z.infer` aliases. The Zod schemas are annotated `z.ZodType<…>`
against those interfaces, so the two cannot drift while Zod's
internal types stay off the public surface.
Internalize Zod in clipc (breaking)
- `rawCliError{Payload,Envelope}Schema` are no longer exported from the
package surface — Zod is now an implementation detail of clipc.
Consumers validate via the new Zod-free `parseCliErrorEnvelope` /
`safeParseCliErrorEnvelope`. The raw schema stays available to the
in-repo JSON Schema generator through a `./internal/error-schema`
subpath export.
CI
- `deno doc --lint` is now a hard gate (was non-blocking pending #29).
Records filed for both packages (dogfooded via `dv add`); `dv status`
previews clipc 0.3.1 → 0.4.0 and dv 0.8.1 → 0.9.0.
Closes #29.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The roadmap-ledger proposal added in #26 links to the internal specs (language, design, ROADMAP) that are deliberately off the public site, so VitePress flagged 8 dead links and failed the docs build on main. Proposals are implementer-facing design docs — exclude the directory like the rest of the internal spec library. Surfaced by this branch's CI run; the breakage predates it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Closes #29.
Clears all 238
deno doc --linterrors (227 missing-JSDoc + 11 private-type-ref) across the public surface of@dv-cli/dvand@dv-cli/clipc, then flips the CI doc-lint step to a hard gate.What changed
JSDoc sweep (the 227 missing-jsdoc)
Every exported symbol on the
@dv-cli/dvlibrary entry now carries JSDoc — the runners, their option/result interfaces (and each field),FinalizedFile/CascadedUpdate, the plugin commands, and the Plan contract. Existing//notes were converted to/** */(wording preserved), with accurate one-liners added where there were none.Public-surface type plumbing (the 11 private-type-ref)
ChangeType,Package,PluginReference,PluginAssignment,ResolvedPlugin,SlugRandomSource,ConfigMigrationStepResult,MigrationChange,PLUGIN_OP_NAMES) so consumers can import them by name instead of through indexed-access types. Each got JSDoc at its source.z.inferaliases. The Zod schemas are annotatedz.ZodType<…>against those interfaces, so the schema and the public type can't drift — while Zod's internaloutput/schema types stay off the public surface.schemas:checkconfirms the generatedplan.jsonis byte-identical.Internalize Zod in clipc⚠️ breaking
Per maintainer steer (leaking Zod from clipc's public surface was the wrong design):
rawCliErrorPayloadSchema/rawCliErrorEnvelopeSchemaare no longer exported from the package surface.parseCliErrorEnvelope/safeParseCliErrorEnvelope(returns a plain{ success, data | issues }). TheRawCliError*contract interfaces are unchanged../internal/error-schemasubpath export (invisible to the documented.surface / doc-lint).CI
deno doc --lintflips fromcontinue-on-error: trueto a hard gate.Acceptance
deno task doc:lintreports 0 errorsVerification
fmt:check,lint,check,test(376 passing),schemas:check(in sync), andpublish:check(slow-types clean, incl. the new clipc subpath) all green. Dogfooded withdv add— two Records filed;dv statuspreviews@dv-cli/clipc0.3.1 → 0.4.0 (minor, breaking capped at minor pre-1.0) and@dv-cli/dv0.8.1 → 0.9.0.🤖 Generated with Claude Code