test(project-engine-client,user-manager-client): spec-verify checksum gate (LLMO-5976)

[aliciadriani]

Spec

LLMO-5976: any re-vendor of the Semrush OpenAPI spec must force a reviewed hash bump.
The vendored spec stays byte-for-byte; if its actual bytes drift from the committed
digest, CI fails until a human reviews the change and bumps the recorded hash in the
same PR. This closes the gap where a silent re-vendor could slip through unreviewed —
the existing overlay-freshness gate (test/overlay.test.js) only pins the CRn
correction overlay against generated types, not the raw vendored bytes.

Implementation plan

Existed: both Semrush client packages (project-engine-client, user-manager-client)
already had an overlay-freshness gate pinning corrections against generated types, and
test/foundation.test.js already asserted textual facts about the vendored spec
(basePath, swagger version) — but neither pinned the spec's raw bytes. That was the gap.

Added (smallest shippable version — extends existing files, no new framework, no
new src/mock logic, zero coverage burden):

• packages/spacecat-shared-project-engine-client/spec/projectengine_swagger_public.yaml.sha256
  — committed digest.
• packages/spacecat-shared-user-manager-client/spec/usermanager_swagger.yaml.sha256
  — committed digest.
• A gate describe block appended to each package's test/foundation.test.js that
  hashes the vendored spec bytes (Buffer, not utf-8) and asserts equality against the
  committed digest, plus a self-test proving hashing tampered bytes does NOT match.
• A doc note in each package's CLAUDE.md next to the "spec is never edited" line.

The vendored specs remain byte-for-byte unchanged.

CI integration point: runs as a normal Mocha test under each package's npm test
(c8 mocha), which the root .github/workflows/main.yaml Test job already invokes on
every PR via the shared lint-test-coverage composite action. No new workflow, no new
npm script — same path as every other unit test.

Verification:

• lint clean on both packages.
• npm test -w packages/spacecat-shared-project-engine-client — 230 passing, 100%
  stmts/branches/funcs/lines.
• npm test -w packages/spacecat-shared-user-manager-client — 167 passing, 100%
  stmts/branches/funcs/lines.
• Confirmed the gate bites: appended a byte to the vendored spec, gate failed with a
  "vendored spec drifted" message, reverted.

Cut as speculative:

• No standalone spec:verify npm script — redundant with the CI-run Mocha test and
  would carry its own coverage burden.
• No checksum of the generated types.ts or the overlay — the overlay gate already
  guards corrections, and types.ts derives from the spec this gate now pins.
• No shared cross-package helper — two ~15-line blocks beat a new coverage-tracked
  module for two call sites.

Note: /create-pr skill was not available in this session; this PR was opened directly
via gh pr create with the body manually structured to match the unified template shape.

🤖 Generated with Claude Code

[github-actions]

This PR will trigger no release when merged.

[MysticatBot]

Hey @aliciadriani,

Verdict: Approve - clean, well-scoped checksum gate with no blocking issues.
Complexity: LOW - small diff, single concern, no risk signals.
Changes: Adds SHA-256 checksum verification gates to both vendored Semrush OpenAPI specs, preventing silent re-vendor without human review (6 files).
Note: Recommend a human read before merge - this change modifies package-level CLAUDE.md files (architectural documentation). The bot review is a complement to, not a replacement for, a human read here.

Non-blocking (3): minor issues and suggestions

• nit: No .gitattributes rule guarantees byte-stable checkouts for the vendored YAML specs. If a contributor has core.autocrlf=true, the spec could check out with CRLF, producing a hash mismatch that looks like drift but is just a line-ending difference. Consider spec/*.yaml eol=lf in each package or at the repo root.
• suggestion: The two test implementations are identical except for file paths. If a third vendored spec adopts this pattern, extract a shared helper (e.g., makeChecksumGate(specPath, checksumPath)) to avoid copy-paste drift.
• nit: The "detects a byte-for-byte mismatch" test asserts a property of SHA-256 itself (different inputs produce different outputs), not a property of the gate logic. It has documentation value but cannot meaningfully fail unless createHash is broken.

Note: CI checks are currently pending.

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 1m 10s | Cost: $3.16 | Commit: 91266f112758d3805d45dbf60e9b1a3016edc7fc
If this code review was useful, please react with 👍. Otherwise, react with 👎.}