@grimoire-rs/indexer 0.3.2 → 0.4.0

package/dist/validate/adapters/http.d.ts

@@ -15,7 +15,12 @@ export interface HttpResponse {
     body: string;
     header(name: string): string;
 }
-export declare function request(url: string, headers?: Record<string, string>): Promise<HttpResponse>;
+/** Everything past a plain GET. Omitted leaves `fetch`'s own defaults. */
+export interface RequestOptions {
+    method?: string;
+    body?: string;
+}
+export declare function request(url: string, headers?: Record<string, string>, options?: RequestOptions): Promise<HttpResponse>;
 /** `request` plus a `JSON.parse` that yields `null` instead of throwing. */
 export declare function requestJson(url: string, headers?: Record<string, string>): Promise<{
     status: number;

package/dist/validate/adapters/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/validate/adapters/http.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAC7C,eAAO,MAAM,UAAU,QAAS,CAAC;AACjC,eAAO,MAAM,kBAAkB,QAAc,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AA4BD,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,OAAO,CAAC,YAAY,CAAC,CAoBvB;AAED,4EAA4E;AAC5E,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAQ5C"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/validate/adapters/http.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAC7C,eAAO,MAAM,UAAU,QAAS,CAAC;AACjC,eAAO,MAAM,kBAAkB,QAAc,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AA4BD,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACpC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAwBvB;AAED,4EAA4E;AAC5E,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAQ5C"}

package/dist/validate/adapters/http.js

@@ -37,11 +37,15 @@ async function readCapped(response, cap) {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-export async function request(url, headers = {}) {
+export async function request(url, headers = {}, options = {}) {
     const none = { status: 0, body: "", header: () => "" };
     try {
         const response = await fetch(url, {
             headers: { "User-Agent": USER_AGENT, ...headers },
+            // Both `undefined` for a two-argument call, which is what `fetch` sees
+            // when neither is passed — the existing GET call sites are untouched.
+            method: options.method,
+            body: options.body,
             // ponytail: redirects are refused, not followed. If a real registry ever
             // needs one, re-run the host policy on the Location and follow one hop.
             redirect: "manual",

package/dist/validate/adapters/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/validate/adapters/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/validate/adapters/http.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grimoire-rs/indexer",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI + Astro integration for running your own grim package index",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,6 +38,7 @@
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.0",
     "js-yaml": "^4.1.0",
+    "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"

package/templates/ci/github-pages.yml

@@ -7,7 +7,7 @@ name: pages
 
 on:
   push:
-    branches: [{{defaultBranch}}]
+    branches: [{{defaultBranch}}]{{githubRatingsSchedule}}
   workflow_dispatch:
 
 # Default-deny at the top; every job pays for exactly what it needs.
@@ -19,7 +19,7 @@ concurrency:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest{{githubRatingsBuildKeys}}
     permissions:
       contents: read
     steps:
@@ -40,12 +40,17 @@ jobs:
       # here, in the job that publishes the site.
       - name: Install
         run: npm ci --ignore-scripts
-{{githubEnrichSteps}}
+
+      # Ahead of the build, not after it: it only resolves this repository's
+      # Pages URL and sets outputs, and a step that runs before the build - the
+      # ratings seed - cross-checks `site` against that URL before it reads the
+      # published sidecar.
+      - id: pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+{{githubEnrichSteps}}{{githubRatingsSeedSteps}}
       - name: Build index
         run: npm run build
 
-      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: dist
@@ -62,3 +67,4 @@ jobs:
     steps:
       - id: deployment
         uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+{{githubRatingsJob}}

package/templates/ci/github-ratings-seed.yml

@@ -0,0 +1,88 @@
+
+      # Invariant R-2 lives in these two steps and in their order.
+      #
+      # A completed tally has already merged itself over this same published
+      # copy, per stat key, so it wins outright. Only when there is no fresh
+      # tally does the published copy get carried forward untouched - which is
+      # exactly what must happen when the `ratings` job failed, was skipped, or
+      # was never enabled on this run.
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        # A failed or skipped tally produced no artifact. That must not fail
+        # the deploy: carrying the published sidecar forward is the whole point.
+        continue-on-error: true
+        with:
+          name: grim-stats
+
+      # `|| true` is forbidden here. It cannot tell a genuine 404 from a DNS
+      # failure, a TLS error, a 5xx or a truncated body - and if the tally also
+      # failed, the deploy would then publish a site with no sidecar at all,
+      # the exact wipe R-2 exists to prevent. So the status code is captured
+      # and branched on: 404 is an empty seed, a 2xx that parses is the merge
+      # base, anything else fails the job.
+      - name: Seed from the published sidecar
+        env:
+          PAGES_URL: ${{ steps.pages.outputs.base_url }}
+        run: |
+          set -euo pipefail
+
+          # One source. The seed URL is `site` from index.config.json, read
+          # out of the checkout here - the same key, the same file and the
+          # same run as the tally that produced the artifact above. Not baked
+          # in at render time on purpose: a workflow rendered before `site`
+          # was last edited would seed from one URL while the tally read the
+          # other, which is the divergence this step exists to close.
+          SITE_URL=$(node -p 'JSON.parse(require("fs").readFileSync("index.config.json","utf8")).site ?? ""')
+          rstrip() { u=$1; while [ "${u%/}" != "$u" ]; do u=${u%/}; done; printf '%s' "$u"; }
+          SITE_URL=$(rstrip "$SITE_URL")
+          case "$SITE_URL" in
+            https://*) ;;
+            # Not defaulted: the built-in default names the first-party index,
+            # and seeding from someone else's published stats would merge
+            # their ratings into this one's sidecar. TLS because the fetched
+            # document decides every published rating - `--proto '=https'`
+            # below would refuse it anyway, in curl's words instead of these.
+            *) echo "::error::index.config.json needs an explicit https \`site\` - the seed is read from <site>/stats.json (got '$SITE_URL')"; exit 1 ;;
+          esac
+
+          # The Pages URL is a cross-check, never a second source: while it was
+          # the source, this step fetched one URL and the tally fetched the
+          # other, and a 404 there is a legal empty seed - so a disagreement
+          # published a sidecar built from nothing, at exit 0.
+          #
+          # Absent is not a disagreement: a fork, or a deploy that is not
+          # Pages, has no such URL, and `site` stands alone. Neither is a
+          # trailing slash, the scheme, or host case - hostnames are
+          # case-insensitive where the path is not. A real disagreement fails
+          # ahead of the freshness check below: the tally read `site` too, so
+          # a fresh artifact is no evidence that this URL is the right one.
+          lower() { u=${1#*://}; h=${u%%/*}; printf '%s%s' "${h,,}" "${u#"$h"}"; }
+          if [ -n "${PAGES_URL:-}" ] && [ "$(lower "$(rstrip "$PAGES_URL")")" != "$(lower "$SITE_URL")" ]; then
+            echo "::error::index.config.json publishes to $SITE_URL but this pipeline deploys $PAGES_URL - the seed would be read from one and the sidecar published to the other"
+            exit 1
+          fi
+
+          if [ -f .stats.json ]; then
+            echo "using the tally this run produced"
+            exit 0
+          fi
+          code=$(curl -sS --proto '=https' --tlsv1.2 --max-time 30 \
+            -o .stats.json.seed -w '%{http_code}' "$SITE_URL/stats.json") || {
+            echo "::error::could not read the published stats.json - refusing to deploy a site that would empty every published rating"
+            exit 1
+          }
+          case "$code" in
+            404)
+              echo "no stats.json published yet - starting from an empty seed"
+              ;;
+            2??)
+              node -e 'JSON.parse(require("fs").readFileSync(".stats.json.seed","utf8"))' || {
+                echo "::error::the published stats.json did not parse - refusing to treat an unreadable seed as an empty one"
+                exit 1
+              }
+              mv -f .stats.json.seed .stats.json
+              ;;
+            *)
+              echo "::error::the published stats.json returned HTTP $code"
+              exit 1
+              ;;
+          esac

package/templates/ci/github-ratings.yml

@@ -0,0 +1,51 @@
+
+  # Tallies the forge's own upvote counters into `.stats.json` - the sidecar
+  # `build` joins onto the catalog and the deploy publishes beside all.json.
+  #
+  # Its own job, ahead of `build`, because `build` has to run even when this
+  # one fails. A tally that cannot reach the forge must never empty a published
+  # rating set (R-2), and the only way to keep the previous one is to deploy
+  # without a fresh tally - see the seed step in `build`.
+  #
+  # Turn ratings off by deleting the `ratings` block from index.config.json and
+  # re-rendering. That stops the tally, but the last one stays published:
+  # deleting `stats.json` from the deploy is the other half of the rollback.
+  ratings:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # The only write anything in this pipeline is granted, and it is what a
+      # vote is: threads live on the forge, nothing is committed here.
+      discussions: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "{{nodeVersion}}"
+          cache: npm
+
+      - name: Install
+        run: npm ci --ignore-scripts
+
+      # `npx --no` refuses to fetch anything `npm ci` did not install, so the
+      # renderer that tallies is the one package-lock.json pins - the same
+      # reviewed-fact rule every other job here follows. Spelled as `npx`
+      # rather than an npm script so an index scaffolded before ratings existed
+      # turns them on by re-rendering CI, with no package.json edit.
+      - name: Tally ratings
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx --no grim-indexer ratings
+
+      # `error` rather than the default warning: a run that reported success
+      # and wrote nothing is a bug, and the failure mode it would otherwise
+      # produce - `build` silently falling back to the seed - looks exactly
+      # like a healthy carry-forward.
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: grim-stats
+          path: .stats.json
+          if-no-files-found: error

package/templates/ci/gitlab-ci.yml

@@ -129,13 +129,13 @@ grim-indexer:validate:
 pages:
   stage: deploy
   rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH{{gitlabRatingsPagesRule}}
   before_script:
     - npm ci --cache .npm --prefer-offline --ignore-scripts
   script:
     - |
       set -eu
-{{gitlabEnrichScript}}
+{{gitlabEnrichScript}}{{gitlabRatingsSeedScript}}
     # Built into `dist/`, then moved. Building straight into `public/` was a
     # data-loss bug: the compile step clears its output directory first, so it
     # deleted this index's own committed asset layer (logo, favicon) before
@@ -146,4 +146,4 @@ pages:
   artifacts:
     paths:
       - public
-{{gitlabPublishJob}}
+{{gitlabRatingsJob}}{{gitlabPublishJob}}

package/templates/ci/gitlab-ratings-seed.sh

@@ -0,0 +1,83 @@
+
+      # Invariant R-2. GitLab hands this job the ratings artifact before the
+      # script runs, so `.stats.json` being present means a tally completed -
+      # and a completed tally has already merged itself over this same
+      # published copy, per stat key. Only when there is none does the
+      # published copy get carried forward untouched, which is what must happen
+      # when the tally failed or was skipped.
+      #
+      # `|| true` is forbidden here. It cannot tell a genuine 404 from a DNS
+      # failure, a TLS error, a 5xx or a truncated body - and if the tally also
+      # failed, the deploy would then publish a site with no sidecar at all,
+      # the exact wipe R-2 exists to prevent. So the status code is captured
+      # and branched on: 404 is an empty seed, a 2xx that parses is the merge
+      # base, anything else fails the job.
+      #
+      # One source. The seed URL is `site` from index.config.json, read out of
+      # the checkout here - the same key, the same file and the same run as
+      # the tally that produced the artifact this job was handed. Not baked in
+      # at render time on purpose: a pipeline rendered before `site` was last
+      # edited would seed from one URL while the tally read the other, which
+      # is the divergence this step exists to close.
+      #
+      # Deliberately NOT cross-checked against `CI_PAGES_URL`. That variable
+      # is always a subdomain of `CI_PAGES_DOMAIN` and never reflects a custom
+      # domain, and unique domains (16.7+) and `path_prefix` (17.9+) move it
+      # again - so it disagrees with a correct `site` as the normal case, and
+      # comparing them would fail every such deploy. The GitHub arm keeps its
+      # cross-check because `steps.pages.outputs.base_url` really is a
+      # statement about where the site deploys.
+      SITE_URL=$(node -p 'JSON.parse(require("fs").readFileSync("index.config.json","utf8")).site ?? ""')
+      rstrip() { u=$1; while [ "${u%/}" != "$u" ]; do u=${u%/}; done; printf '%s' "$u"; }
+      SITE_URL=$(rstrip "$SITE_URL")
+      case "$SITE_URL" in
+        https://*) ;;
+        # Not defaulted: the built-in default names the first-party index, and
+        # seeding from someone else's published stats would merge their
+        # ratings into this one's sidecar. TLS because the fetched document
+        # decides every published rating - `--proto '=https'` below would
+        # refuse it anyway, in curl's words instead of these.
+        *)
+          echo "grim-indexer: index.config.json needs an explicit https \`site\` - the seed is read from <site>/stats.json (got '$SITE_URL')" >&2
+          exit 1
+          ;;
+      esac
+
+      # `node:*-alpine` ships no curl, and the runner's clone helper is a
+      # separate image, so nothing else puts one here. Install it for whichever
+      # package manager this image has, then insist it is really there - a
+      # missing tool must fail the job, never silently skip the seed.
+      if [ ! -f .stats.json ]; then
+        if ! command -v curl >/dev/null 2>&1; then
+          if command -v apk >/dev/null 2>&1; then
+            apk add --no-cache curl
+          elif command -v apt-get >/dev/null 2>&1; then
+            apt-get update -qq && apt-get install -y -qq --no-install-recommends curl
+          fi
+        fi
+        command -v curl >/dev/null 2>&1 || {
+          echo "grim-indexer: seeding stats.json needs curl, and this image has none" >&2
+          exit 1
+        }
+        code=$(curl -sS --proto '=https' --tlsv1.2 --max-time 30 \
+          -o .stats.json.seed -w '%{http_code}' "$SITE_URL/stats.json") || {
+          echo "grim-indexer: could not read the published stats.json - refusing to deploy a site that would empty every published rating" >&2
+          exit 1
+        }
+        case "$code" in
+          404)
+            echo "grim-indexer: no stats.json published yet - starting from an empty seed"
+            ;;
+          2??)
+            node -e 'JSON.parse(require("fs").readFileSync(".stats.json.seed","utf8"))' || {
+              echo "grim-indexer: the published stats.json did not parse - refusing to treat an unreadable seed as an empty one" >&2
+              exit 1
+            }
+            mv -f .stats.json.seed .stats.json
+            ;;
+          *)
+            echo "grim-indexer: the published stats.json returned HTTP $code" >&2
+            exit 1
+            ;;
+        esac
+      fi

package/templates/ci/gitlab-ratings.yml

@@ -0,0 +1,37 @@
+
+# Tallies the forge's own emoji reactions into `.stats.json` - the sidecar the
+# `pages` job joins onto the catalog and publishes beside all.json. (GitLab
+# renamed this feature Award Emoji to Emoji Reactions in 16.0; the GraphQL
+# surface is unchanged.)
+#
+# Its own job, ahead of `pages`, because `pages` has to run even when this one
+# fails. A tally that cannot reach GitLab must never empty a published rating
+# set (R-2), and the only way to keep the previous one is to deploy without a
+# fresh tally - hence `allow_failure`, which still reds the pipeline and still
+# lets the deploy through, and hence `optional: true` on the `pages` job's
+# `needs`.
+#
+# `resource_group` is a correctness requirement, not tuning: two overlapping
+# runs can interleave a stale tally over a fresh one. It serializes them. Set
+# the group's process mode to `oldest_first` once in Settings -> CI/CD, so a
+# queued run cannot overtake the one ahead of it - that part has no YAML.
+#
+# The tally needs a token that may write reactions: set GRIM_RATINGS_TOKEN as a
+# masked CI/CD variable (a project access token with `api` scope is enough,
+# since the threads live in this same project). CI_JOB_TOKEN cannot do it.
+grim-indexer:ratings:
+  stage: test
+  resource_group: grim-ratings
+  allow_failure: true
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  before_script:
+    - npm ci --cache .npm --prefer-offline --ignore-scripts
+  script:
+    # `npx --no` refuses to fetch anything `npm ci` did not install, so the
+    # renderer that tallies is the one package-lock.json pins.
+    - npx --no grim-indexer ratings
+  artifacts:
+    paths:
+      - .stats.json

package/templates/gitignore

@@ -8,6 +8,14 @@ dist/
 # Renderer scratch dir - removed on a clean build, left behind by a killed one.
 .index-*/
 
+# The ratings sidecar. CI seeds it from the live site, the tally merges over
+# it, and the deploy publishes it as `stats.json` - it is a build input, never
+# a source of truth. Deliberately not committed: it is regenerated from the
+# forge every run, so a committed copy is only ever a stale one, and it would
+# keep being published after the `ratings` block was removed, defeating the
+# rollback.
+.stats.json
+
 node_modules/
 .npm/