Skip to content

PRINCIPLES.md

Latest commit

 

History

History
51 lines (40 loc) · 2.5 KB

PRINCIPLES.md

File metadata and controls

51 lines (40 loc) · 2.5 KB

stepdown — Principles (language-agnostic)

stepdown is a family of structural source analyzers. Each language has its own implementation and its own ADR-0001, but every member inherits this constitution. A member that violates it is a different tool wearing the name.

The one opinion

Source reads top-down: high-level declarations appear before the supporting declarations they depend on, and within a scope a public entry point is immediately followed by its private callees in depth-first call order. stepdown enforces structure — never semantics, style, security, performance, or API design.

The constitution (binding on every language member)

  1. One opinion, structural only.
  2. Positive grammar only — walk valid structure, emit a named diagnostic on mismatch; no forbidden-pattern lists, deny-lists, or violation-type switches.
  3. No configuration — no config file, rule toggles, or per-project flavors.
  4. No waivers — no inline opt-outs or exemptions. If valid code consistently fails, the grammar is wrong and changes; source never gets a waiver. (Out-of-scope file categories — generated, test — are not waivers.)
  5. Positive witnesses only — fixtures are conforming source asserting zero diagnostics; no rejected-form corpus; sparse, mechanical tests.
  6. Self-policing — the tool passes its own check in its own CI; a release that fails its own grammar does not ship.
  7. Reviewable walker — small enough that a reviewer verifies mismatch paths by reading the source. Outgrowing that changes the test strategy only by ADR.
  8. ADR-driven evolution — every rule traces to the one opinion; new rules need a new ADR with explicit justification.

Shared vs per-language

Shared: this document. Per-language: the concrete grammar, classification, rule names, fixtures, and ADR-0001 — in that language's own concepts, with no foreign-language or steward identity in the rule vocabulary.

Output contract (shared)

  • Diagnostics: path:line:column: rule-name: description, one per line, deterministic, sorted, text only. JSON only if added to every member in lockstep by coordinated ADR.
  • Exit codes: 0 clean, 1 findings, 2 tool/load error; gates fail closed on any non-zero.
  • Pinning: each language uses its ecosystem's pinned-version invocation.

Stewardship

Repository, module path, license, and steward identity are locator metadata, not tool semantics, and change by ADR amendment without affecting the rule. Owner: Stinnett Holdings LLC.