mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-10-02 05:24:34 +08:00

Files

T

Clay GoodandClaude Opus 4.8 ffe27de18d chore(scripts): add a parity-hash regeneration helper (#1416 )

skill-templates-parity.test.ts pins a SHA-256 per workflow template so an
unintended template edit fails loudly. The cost lands on every intended
edit: the pinned hashes go stale, and because all 37 live in two maps in
one file, two branches editing different templates collide there on rebase.
Resolving that means hand-editing 64-character hashes, which is where
transcription mistakes come from - and the test proves a hash matches its
source, never that the source is right, so a bad value regenerated over a
bad merge passes CI in silence.

Recompute every pinned hash from the built dist/ and rewrite the map in
place, reporting which entries moved. The skill-directory mapping comes
from getSkillTemplates(), the same helper the skills.sh generator uses, so
adding a workflow needs no second list here; function labels resolve
dynamically against the module exports, so there is no hard-coded list at
all.

"Nothing to update" has to mean it, so four things abort the run without
writing:
  - dist/ missing or older than src/, which would pin hashes from a stale
    build that the parity test - which reads src/ - then rejects
  - a pinned label with no matching export, from a renamed or deleted
    template
  - a pinned hash whose line the patterns do not recognise, counted by
    comparing 64-hex literals found against literals rewritten; the count
    uses a deliberately broader pattern so it is a real cross-check rather
    than a restatement of the same patterns
  - a skill the registry deploys that nothing pins, compared in the other
    direction: pins-to-registry only sees pins that already exist

That last direction closes a hole that predates this script. A workflow
added to getSkillTemplates() but never pinned was invisible to the parity
test too, which compares only the entries it already lists - so it shipped
with no golden hash while everything reported success. skill-templates-
parity.test.ts now pins the registry itself, so CI catches it whether or
not anyone runs this script.

The rewriting lives in parity-hash-shared.mjs, following the split between
generate-skillssh.mjs and skillssh-shared.mjs, so those guards can be
exercised against fabricated input. Running the script for real from a test
would rewrite the repository's own parity test file mid-suite. Each case in
parity-hash-shared.test.ts was mutation-checked: removing the guard it
covers makes it fail.

The script cannot silently emit a wrong hash: the parity test recomputes
the same values independently and compares, so a drift between the two
copies of stableStringify fails the test. The test stays the authority.

Dev tooling only. scripts/ is not published (package.json files ships just
scripts/postinstall.js), no src/ is touched, and no runtime behaviour
changes - hence no changeset.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-22 18:54:13 +00:00

2.6 KiB

Raw Blame History

OpenSpec Scripts

Utility scripts for OpenSpec maintenance and development.

update-flake.sh

Updates flake.nix pnpm dependency hash automatically.

When to use: After updating dependencies (pnpm install, pnpm update).

Usage:

./scripts/update-flake.sh

What it does:

Reads version from package.json (dynamically used by flake.nix)
Automatically determines the correct pnpm dependency hash
Updates the hash in flake.nix
Verifies the build succeeds

Example workflow:

# After dependency updates
pnpm install
./scripts/update-flake.sh
git add flake.nix
git commit -m "chore: update flake.nix dependency hash"

regen-parity-hashes.mjs

Recomputes the golden hashes pinned in test/core/templates/skill-templates-parity.test.ts.

When to use: After any intended workflow-template change, and after rebasing a branch that edits templates — two branches touching different templates collide on the same hash map, and hand-editing 64-character hashes during a conflict is where transcription mistakes happen.

Usage:

pnpm build && pnpm regen:parity-hashes
pnpm vitest run test/core/templates/skill-templates-parity.test.ts

What it does:

Refuses to run if dist/ is missing or older than src/ — hashes come from the build, while the parity test reads src/, so regenerating against a stale build writes hashes the test then rejects
Recomputes every pinned hash from the built dist/
Rewrites the map in place and prints which entries moved
Exits non-zero, writing nothing, if it cannot account for every pinned hash: a label with no matching export (a renamed or deleted template), or a hash line these patterns do not recognise. Both would otherwise be left stale while the run reported success, so nothing to update always means it.

Line endings round-trip unchanged, so a CRLF checkout is safe — test/** has no text eol=lf attribute, so the file arrives with CRLF on Windows.

The parity test recomputes the same hashes independently, so this script cannot silently produce a wrong value. Always run the test afterwards; it, not this script, is the authority.

The rewriting lives in parity-hash-shared.mjs so its guards can be exercised against fabricated input — see test/core/templates/parity-hash-shared.test.ts. A test that ran this script for real would rewrite the repository's own parity test file mid-suite.

postinstall.js

Post-installation script that runs after package installation.

pack-version-check.mjs

Validates package version consistency before publishing.

2.6 KiB Raw Blame History