feat: Standard Schema wrapper, JSR, pkg.pr.new, docs previews and a playground

.github/workflows/check.yml

@@ -56,9 +56,13 @@ jobs:
       - name: Check llms.txt/llms-full.txt are up to date
         run: npm run build:llms && git diff --exit-code -- docs/llms.txt docs/llms-full.txt
 
-      - name: Check the docs site shells and sitemap are up to date
-        # --intent-to-add makes a shell written for a new page show up in the diff as well.
-        run: npm run build:site && git add --intent-to-add docs && git diff --exit-code -- docs/sitemap.xml 'docs/*.html' 'docs/pt-br/*.html'
+      - name: Check the JSR exports are up to date
+        run: npm run build:jsr && git diff --exit-code -- jsr.json
+
+      - name: Build the documentation site
+        # The site is generated at deploy time (the Docs workflow), so nothing here can be stale;
+        # this only has to fail when a generator does.
+        run: npm run build:docs
 
       - name: Check the VEX statements against the suppressed advisories
         run: npm run check:vex

.github/workflows/datasets.yml

@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   update-datasets:
-    name: Update IBGE/CONCLA datasets
+    name: Update the embedded datasets
     runs-on: ubuntu-latest
     # Only this job pushes the dataset branch and opens the pull request.
     permissions:
@@ -43,14 +43,17 @@ jobs:
             echo "changed=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # Written outside the workspace, so the pull request does not pick the file up as a change.
+      - name: Summarize what changed
+        if: steps.diff.outputs.changed == 'true'
+        run: node scripts/data-summary.ts "$RUNNER_TEMP/dataset-summary.md"
+
       - name: Open pull request
         if: steps.diff.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7.0.11
         with:
-          commit-message: "chore(data): update IBGE/CONCLA datasets"
+          commit-message: "chore(data): update the embedded datasets"
           branch: chore/update-datasets
           base: ${{ github.event.repository.default_branch }}
-          title: "chore(data): update IBGE/CONCLA datasets"
-          body: |
-            Automated weekly refresh of the cities, states and legal-natures
-            datasets sourced from IBGE/CONCLA.
+          title: "chore(data): update the embedded datasets"
+          body-path: ${{ runner.temp }}/dataset-summary.md

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+# Builds the documentation site and publishes it to GitHub Pages. Everything the site needs that a
+# script can write - the per-page shells, the sitemap, llms.txt, llms-full.txt and the examples of
+# the document field page - is written here rather than kept in the repository, so a page and what
+# it is generated from can never disagree.
+#
+# This needs Pages set to "GitHub Actions" (Settings -> Pages -> Build and deployment -> Source);
+# serving the branch directly would publish `docs/` without these files.
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - scripts/**
+      - package.json
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Build and deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Build the site
+        run: npm run build:docs
+
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload the site
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs
+
+      - name: Deploy to Pages
+        id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.github/workflows/preview.yml

@@ -0,0 +1,38 @@
+# Publishes every pull request's build to pkg.pr.new, so a change can be installed and tried before
+# it is merged: `npm i https://pkg.pr.new/@brazilian-utils/brazilian-utils@<pr-number>`. The
+# pkg.pr.new GitHub App (https://github.com/apps/pkg-pr-new), installed on this repository, posts
+# the install command as a comment; the job itself needs no token and no write permission, which is
+# why it can run for pull requests from forks.
+name: Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  preview:
+    name: Publish a preview to pkg.pr.new
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Run build
+        run: vp run build
+
+      - name: Publish the preview
+        run: npx --yes pkg-pr-new@0.0.88 publish --compact --comment=update

.github/workflows/release.yml

@@ -7,7 +7,7 @@
 #      published yet. A maintainer reviews and merges that PR: that merge is confirmation #1.
 #   2. Merging the release PR makes release-please tag the release commit and create a GitHub
 #      Release, which triggers this same workflow again. This time `release_created` is `true`,
-#      so the `publish` job builds, validates and STAGES the package on npm
+#      so the `publish-npm` job builds, validates and STAGES the package on npm
 #      (`npm stage publish --provenance`). A staged version is not installable until a
 #      maintainer approves it with 2FA, on npmjs.com (package -> Staged versions) or with
 #      `npm stage approve <stage-id>`. That approval is confirmation #2 (npm's
@@ -26,6 +26,12 @@
 #   4. Save. No NPM_TOKEN secret is needed: npm exchanges the workflow's OIDC token for a
 #      short-lived token automatically.
 #
+# One-time JSR setup (done by a package maintainer, not by CI):
+#   1. Sign in at jsr.io with GitHub and create the scope `brazilian-utils` and the package
+#      `brazilian-utils` in it.
+#   2. Package Settings -> GitHub Actions -> link `brazilian-utils/javascript`. JSR then trusts
+#      this repository's OIDC token; no JSR token is stored anywhere.
+#
 # One-time GitHub Environment setup (done by a package maintainer, not by CI):
 #   Repository Settings -> Environments -> New environment -> name it `npm`. No protection rules
 #   are needed: the environment only exists so the npm trusted publisher can be bound to it.
@@ -64,7 +70,7 @@ jobs:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
-  publish:
+  publish-npm:
     name: Publish to npm
     needs: release-please
     if: ${{ needs.release-please.outputs.release_created == 'true' }}
@@ -120,6 +126,37 @@ jobs:
       - name: Stage on npm
         run: npm stage publish --provenance --access public
 
+  publish-jsr:
+    name: Publish to JSR
+    needs: release-please
+    # JSR publishes through OIDC as well: no token is stored. It needs the one-time JSR setup
+    # described at the top of this file; until that is done this job fails, and the npm job, which
+    # does not depend on it, still publishes.
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout the release tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          persist-credentials: false
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
+        with:
+          deno-version: v2.x
+
+      - name: Publish to JSR
+        run: deno publish
+
   sbom:
     name: Record the SBOM of the release
     needs: release-please

.github/workflows/tests.yml

@@ -97,6 +97,11 @@ jobs:
       - name: Run tests
         run: deno test --unstable-sloppy-imports --allow-net --allow-env src
 
+      # What JSR would reject at release time fails here instead: slow types in the public API,
+      # an export of jsr.json that does not resolve, a file outside the publish list.
+      - name: Dry-run the JSR publication
+        run: deno publish --dry-run
+
   test-browsers:
     name: Test on Browsers (${{ matrix.browser }})
     runs-on: ubuntu-latest

.github/zizmor.yml

@@ -7,8 +7,10 @@ rules:
     ignore:
       - build.yml
       - check.yml
+      - docs.yml
       - datasets.yml
       - live-tests.yml
       - mutation.yml
+      - preview.yml
       - release.yml
       - tests.yml

.gitignore

@@ -19,3 +19,23 @@ reports/*
 !reports/api/
 reports/api/*
 !reports/api/brazilian-utils.api.md
+# Deno writes a lockfile next to jsr.json on every `deno test`/`deno publish`; the npm lockfile is
+# the one that pins this project's dependencies.
+deno.lock
+
+# The documentation site is generated by `npm run build:docs` and published by the Docs workflow:
+# only what a person writes is kept here.
+docs/*.html
+!docs/index.html
+docs/pt-br/*.html
+docs/guides/*.html
+docs/pt-br/guides/*.html
+docs/sitemap.xml
+docs/llms.txt
+docs/llms-full.txt
+docs/snippets/document-field/generated/
+docs/snippets/address-form/*/cep-field.*
+docs/snippets/address-form/*/field.*
+docs/snippets/address-form/react/use-mask.ts
+docs/snippets/address-form/vue/mask.ts
+docs/snippets/address-form/angular/mask.directive.ts