Skip to content

docs(api): document public API + JSR publish workflow (score -> 100) - #862

Merged
vladjerca merged 3 commits into
masterfrom
docs/jsr-score
Jul 16, 2026
Merged

docs(api): document public API + JSR publish workflow (score -> 100)#862
vladjerca merged 3 commits into
masterfrom
docs/jsr-score

Conversation

@vladjerca

@vladjerca vladjerca commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Follow-up to #861 (static types, merged). Closes out the remaining JSR score checks to reach 100.

Changes

  • Module doc + @example on the mod.ts entrypoint, plus a package README - covers readme/module-doc, examples, and module-docs-in-all-entrypoints.
  • JSDoc on every exported symbol (schemas, inferred model types, contracts, factories, client helpers): 100% coverage (414/414), up from 0%. Baseline docs are name-derived one-liners; the entrypoint symbols (traktApi, traktApiFactory, TraktApi, AbortError, Environment, ...) are hand-written. Comments are carried into the generated declarations, so JSR counts them.
  • JSR publish workflow (.github/workflows/publish.yml) that publishes via GitHub OIDC, which records provenance (public transparency log entry) on the next release. Runs deno task build:types before publishing.

JSR checklist

check before after
No slow types
Description / runtimes
Readme / module doc
Examples
Module docs in all entrypoints
Docs for most symbols ❌ 0% ✅ 100%
Provenance ✅ on next CI publish

Verified

  • deno doc symbol coverage: 100% (414/414)
  • Module doc + @example detected on the entrypoint
  • deno lint, deno check src, deno task openapi:validate, deno task publish:check all clean

Notes

  • Symbol docs are a generated baseline; can be enriched over time.
  • Ships as 0.5.1 (0.5.0 was already published from feat(api): static types + full docs -> JSR score to 100 #861 with static types only; published versions are immutable). Provenance turns green once 0.5.1 is published through the new workflow (GitHub release or manual dispatch).

Raises the JSR score toward 100 by covering the remaining checks:

- Module doc + `@example` on the `mod.ts` entrypoint, plus a package README
  (readme/module-doc, examples, module-docs-in-all-entrypoints).
- JSDoc on every exported symbol (schemas, inferred model types, contracts,
  factories, client helpers) - 100% symbol coverage, up from 0%. The comments
  are carried into the generated declarations, so JSR sees them.
- GitHub Actions workflow that publishes to JSR via OIDC, which records
  provenance (public transparency log entry) on the next release.
0.5.0 was already published (static types only); 0.5.1 is the first
version to ship the docs and JSR publish workflow. Published versions
are immutable, so a new version is required to update the JSR score.
Adds trakt-web-style agent rules: root CLAUDE.md routes to .agents/rules/,
AGENTS.md loads the core project rule, and domain rules cover keeping the
@trakt/api JSR score at 100 (jsr.md) and authoring contract schemas
(schemas.md, migrated from the previous AGENTS.md).
@vladjerca

Copy link
Copy Markdown
Contributor Author

Added agent rules (trakt-web style) to keep the score from regressing:

  • CLAUDE.md (root) routes to .agents/rules/; AGENTS.md loads the core project.md.
  • .agents/rules/jsr.md - the 100-score playbook (static types, per-symbol JSDoc, provenance publishing, pre-publish checklist).
  • .agents/rules/schemas.md - contract schema conventions (migrated from the old AGENTS.md, plus a JSR note).
  • projects/api/CLAUDE.md - loads jsr.md + schemas.md when working in the package.

Not published (outside publish.include).

@vladjerca
vladjerca merged commit 2154620 into master Jul 16, 2026
3 checks passed
@vladjerca
vladjerca deleted the docs/jsr-score branch July 16, 2026 20:48
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