ci(deps): guard pnpm-workspace floor-pin upper bounds (LAB-1513)

[27Bslash6]

Summary

This PR adds a CI-enforced guard to prevent bounded floor-pins in pnpm-workspace.yaml from being silently widened across major versions, closing a gap where vulnerability-alert-driven dependency updates could bypass existing review controls.

Background

The repository floor-pins vulnerable transitive dependencies in pnpm-workspace.yaml overrides, bounded to a specific major (e.g. '>=2.1.3 <3'). Renovate takes ownership of these entries and can propose widening the upper bound across majors. PR #94 demonstrated this by widening brace-expansion@2 from <3 to <6. Critically, GitHub vulnerability-alert updates carry a force flag that overrides repo-level dependency-dashboard approval, so cross-major widening could get through without human sign-off.

Changes

CI workflow (.github/workflows/ci.yml)

• Adds a new "Verify bounded floor-pins stay in-major" step in the security job, running before pnpm install so no install script can rewrite the file before the check reads it.
• Declares the expected set of bounded pins and their upper-bound majors (brace-expansion@2, js-yaml, protobufjs, uuid).
• Parses the overrides block and matches only plain >=floor <bound values. Any unrecognized shape (a || union, a missing bound, reindented YAML) fails the set comparison — the check fails closed rather than silently skipping what it cannot parse.
• On mismatch, emits a descriptive error explaining that a bound is a deliberate constraint, and how to legitimately cross one.

Documentation (CONTRIBUTING.md)

• Documents the now two-layer enforcement model: renovate.json dependency-dashboard approval (covers routine majors only) plus the CI floor-pin check (holds against vulnerability-alert PRs and hand-written diffs).
• Clarifies why the approval layer alone was insufficient (the force override on vulnerability alerts) and how a genuinely necessary cross-major security fix stays possible — CI goes red as a discovery channel, not a wall.

pnpm-workspace.yaml

• Updates the comment block above overrides to note that the bounds are now enforced by CI, not merely documented, and describes the process for intentionally crossing a bound.

Impact

Crossing a floor-pin upper bound now requires a hand-written commit that removes the bound and updates the expected list in the CI step, ensuring every cross-major dependency change reflects a deliberate human decision.

---

Summary

This PR adds a CI enforcement layer to prevent floor-pinned dependency overrides in pnpm-workspace.yaml from being widened across major versions without explicit human review.

What Changed

New CI guard (.github/workflows/ci.yml)

• Adds a "Verify bounded floor-pins stay in-major" step to the security job, positioned before pnpm install so no install script can rewrite the file before verification runs.
• The step declares an expected set of bounded pins (brace-expansion@2, js-yaml, protobufjs, uuid) with their upper-bound majors, then parses the overrides block of pnpm-workspace.yaml and fails the job unless the declared set matches exactly.
• The parser only matches a plain >=floor <bound shape. Any unrecognized shape (a || union, a missing bound, a moved floor, or reindented YAML) fails closed rather than being silently skipped.

Documentation updates (CONTRIBUTING.md, pnpm-workspace.yaml)

• Documents the two-layer defense against cross-major bound widening: renovate.json's dashboard-approval gate (covers routine majors) and the new CI check (covers vulnerability-alert PRs and hand-written diffs).
• Explains why the CI layer is necessary: a GitHub vulnerability-alert update carries force config that overrides repo settings and bypasses the approval gate — the path that PR chore(deps): update dependency brace-expansion@2 to v5 [security] - autoclosed #94 used to widen brace-expansion@2 from <3 to <6.
• Clarifies the intended workflow for a genuinely necessary cross-major security fix: CI goes red, the maintainer reads why, then removes the bound and updates the expected list in a hand-written commit explaining the decision.

Why

The existing Renovate approval gate does not cover vulnerability-alert-driven updates, which can silently widen an upper bound across a major version (as PR #94 demonstrated). This adds an enforcement layer that treats each upper bound as a deliberate constraint, ensuring any change to a bounded floor-pin requires an explicit human decision.

---

Description

This PR fixes a potential silent failure in the CI guard that validates bounded floor-pin overrides in pnpm-workspace.yaml.

Problem

The found variable is populated by a shell pipeline that includes a grep -v command. When the overrides block shape changes and no matching lines are found, grep -v exits with status code 1. Under pipefail, this non-zero exit would abort the step immediately with no explanatory message — precisely in the "shape-moved" scenario this guard is meant to detect.

Change

Added || true to the end of the pipeline (consistent with the sibling step referenced in the comments). This ensures that an empty result flows through to the explicit comparison branch, so the guard can produce its intended, self-explaining failure message rather than silently aborting.

Impact

• The guard now fails closed with a clear message when the overrides shape changes, instead of dying silently.
• No risk of masking real drift: a broken pipeline yields empty or partial output, which will never equal the expected value, so the comparison still fails as intended.
• Added explanatory comments documenting why || true is safe and necessary here.

Summary by CodeRabbit

• Security

  • Strengthened validation of security-related dependency version bounds during continuous integration.
  • Builds now fail safely when dependency safeguards are missing, unsupported or unexpectedly changed.
  • Verified security pins are clearly reported when checks pass.

• Documentation

  • Updated dependency maintenance guidance to explain approval requirements for major version changes and widened security bounds.
  • Clarified that urgent vulnerability updates can follow an expedited approval path.

• Chores

  • Improved automated dependency update controls to require review for major security-related changes.

[coderabbitai]

Walkthrough

The change adds pre-install CI validation for bounded dependency floor-pins. It also adds Renovate approval rules and documents the required override format, review process, and security exceptions.

Changes

Dependency floor-pin governance

Layer / File(s)	Summary
Floor-pin governance contract pnpm-workspace.yaml, renovate.json, CONTRIBUTING.md	The workspace documents bounded floor-pins. Renovate requires approval for major override updates. Contributor guidance documents CI checks and security exceptions.
Pre-install floor-pin validation .github/workflows/ci.yml	The security job parses and compares all overrides with the expected floor-pins. It fails on missing, added, malformed, widened, or unsupported entries.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Renovate
  participant WorkspaceOverrides
  participant CISecurityJob
  participant DependencyInstallation
  Renovate->>WorkspaceOverrides: Propose override update
  CISecurityJob->>WorkspaceOverrides: Read and parse overrides
  CISecurityJob->>CISecurityJob: Compare overrides with expected floor-pins
  CISecurityJob->>DependencyInstallation: Allow installation after validation

Loading

Possibly related PRs

• cachekit-io/cachekit-ts#95: Added bounded workspace floor-pins covered by this CI validation.
• cachekit-io/cachekit-ts#58: Added workspace dependency overrides governed by this change.
• cachekit-io/cachekit-ts#89: Added related security floor-pins and dependency-update guidance.

Suggested labels: dependencies, security

Suggested reviewers: kodus-27b

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the CI change that guards pnpm-workspace floor-pin upper bounds.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lab-1513-floor-pin-bound-guard

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[kodus-27b]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[27Bslash6]

@kody start-review

[27Bslash6]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.