Skip to content

Validator: simplify severity model from 4 tiers to 2 (blocking + advisory) #728

@arjunmehta-git

Description

@arjunmehta-git

Context

The validator currently has 5 reporting functions (`warn`, `advisory`, `reportStyleIssue`, `reportDesignAdvisory`, `reportContractAdvisory`) controlled by 5 CLI flags (`--warn`, `--no-baseline`, `--style-debt`, `--contract-debt`, `--strict-consistency`). This creates a complex combinatorial matrix:

Default --warn --strict --style-debt --contract-debt
Style skip skip error warning skip
Design warn warn error warning warning
Contract skip skip error skip warning
Blocking error error error error error

Problem

  • 5 flags and 4 severity tiers are hard to reason about
  • The style/contract distinction existed primarily because of v1beta1 legacy debt and v1beta2-draft, both of which are now resolved or removed
  • Contributors and CI configurations struggle to pick the right combination

Proposal

Collapse to 2 tiers: blocking and advisory.

  • All advisory rules (style, design, contract) emit warnings by default
  • `--strict` promotes all to errors
  • `--baseline` suppresses known issues
  • Drop `--style-debt` and `--contract-debt` as separate flags
  • Reduce to 3 flags: `--strict`, `--baseline`, `--warn`
  • Eliminate `consistency-policy.js` entirely — replace with a single inline check
  • Simplify the 6 Makefile targets to 3: `validate-schemas`, `validate-schemas-strict`, `audit-schemas`

Impact

  • Validator code: delete `build/lib/consistency-policy.js`, simplify `validate-schemas.js` reporting
  • Makefile: reduce 6 targets to 3
  • CI: update `.github/workflows/schema-audit.yml`
  • Tests: simplify `tests/validate-schemas-consistency-policy.test.js`

References

Identified in schema validator audit — Section 3d (The 3-Tier Severity System).

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions