hypatia: detect required-check dependency listed only in optionalDependencies (from #333 cohort, pattern 2)

[hyperpolymath]

Detector spec (from hypatia#333 Pattern 2)

Pattern 2 — Required-check depends on a package only listed in optionalDependencies

Severity: high (contradiction: required check that can't be installed)

Detection (Hypatia.Rules.CicdRules):

• For each workflow job listed in branches/main/protection.required_status_checks.contexts:
  • Scan its run: steps. If any step does require("X") (or imports X) and X appears in a sibling package.json's optionalDependencies block but not in dependencies or devDependencies, flag it.
• The combination of "required" + "optional install" is a structural contradiction.

Worked example (this session):

• affinescript/editors/vscode/out/extension.cjs runtime-requires @hyperpolymath/affine-vscode.
• affinescript/editors/vscode/package.json lists it in optionalDependencies (so npm install doesn't 404 when the package is missing).
• vscode-smoke was NOT required (correct), but the same pattern in a required check would be silently broken. Was masked here by continue-on-error: true (see Pattern 5).
• Fix: affinescript#380 embedded the adapter source at codegen time so the runtime no longer needs the optional dep at all.

Remediation guidance to emit:

Either move the dep out of optionalDependencies so installs are reliable, or remove the runtime require (embed the source / inline the adapter / use a different lookup path).

Implementation pointers

• Detection algorithm: For each job in branches/main/protection.required_status_checks.contexts, scan run: steps for require("X")/imports; flag if X is in sibling package.json's optionalDependencies only (not in dependencies/devDependencies).
• Real-world example: affinescript/editors/vscode/out/extension.cjs runtime-requires @hyperpolymath/affine-vscode while package.json lists it in optionalDependencies only. Masked by continue-on-error: true; would have silently broken any required check.
• Landed fix (reference): affinescript#380 (embedded adapter source at codegen time, removing the runtime require).
• Rule statement: Either move the dep out of optionalDependencies so installs are reliable, or remove the runtime require (embed the source / inline the adapter / use a different lookup path).

Acceptance

• Rule encoded in hypatia (file path follows existing rule naming convention — lib/rules/<name>.ex if Elixir, or matching the repo's rule DSL)
• Test fixture exercising the positive case + at least one negative case
• Smoke test passes against the cited landed-fix repo

Source cohort: hypatia#333.

[hyperpolymath]

cicd triage 2026-05-30 — scoped plan + park

PR #403 ships the first batch of 4 rules from this cohort (#336, #337, #338, #390). This issue is in the next batch; landing it requires more substantial work than the first four:

Detection needs cross-file: workflow required-status-checks → run: step require("X") calls → sibling package.json optionalDependencies-only check. Add to lib/rules/cicd_rules.ex (workflow + package.json is its remit).

The issue body is the implementation spec (detection algorithm + worked example + remediation guidance — well-formed). Next-batch PR will pick this up. Leaving open with cicd label.

[hyperpolymath]

Deferred from the #333-cohort Group-B batch (PR #411) to avoid a near-duplicate (cf. the #390 → already-shipped-as-WF018 case).

The "required-check requires a package that's optionalDependencies-only" smell overlaps the existing Hypatia.Rules.BuildSystemRules check, which already flags org packages placed in optionalDependencies/devDependencies instead of dependencies. The distinct value here is the required_status_checks.contexts correlation (a required job that require()s an optional-only dep = structural contradiction), which is API-dependent.

Suggest deciding between: (a) extend BuildSystemRules with the required-check correlation, or (b) a distinct CicdRules rule. Left open for that call rather than shipping a third overlapping rule.

---

Generated by Claude Code

[hyperpolymath]

Forward-pointer (2026-05-31): hypatia#409 (proposed WF021-WF025) was closed as partially superseded — main's recent WF021-WF023 work consumed the WF021/WF024 slots. The 3 detector ideas in this cohort (#361/#363/#366) remain owed and should be implemented by a successor PR using WF024+ numbering (main's highest is WF023).