Skip to content

Commit 6075641

Browse files
committed
test(ownir): enforce producer version single-sourcing + record schema rationale
Track A (N4, no-dependency slice). - test_ownir now asserts each frontend producer (Program.cs, ownts.py) stamps the same ownir_version as the core's OWNIR_VERSION — so 'bumped the core, forgot a frontend' (or the reverse) fails loudly instead of silently mis-reading facts. This is the no-dep half of version single-sourcing; the P-022 own-ir crate will be a fourth producer to fold in (or generate from the schema). (211/211 bridge checks.) - Register: recover and record the strong pro-schema argument now that its trigger has fired. OwnIR is THE language every frontend + the core speak; a language without a formal grammar lies about itself. The schema looked redundant only while load() was the sole validator (zero-dep, no second type set). #170's crates/own-ir hand-writes Rust serde structs that must match load() — two hand-maintained validators in two languages, the exact drift formalization exists to kill. So the schema flips from a shadow of load() to the source both are generated from (serde via typify; C#/TS source-gen), collapsing the hand-synced shapes AND the four ownir_version literals into one authority. Recommendation: co-design spec/ownir.schema.json WITH the own-ir crate, not a jsonschema validator bolted onto the zero-dep core. Refs docs/notes/tech-debt-register.md (N4), P-022 #170. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FJSfUpRbRXegrwJNV1rx1X
1 parent f6b5d77 commit 6075641

2 files changed

Lines changed: 69 additions & 19 deletions

File tree

‎docs/notes/tech-debt-register.md‎

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -122,21 +122,23 @@ The formalization stack, in order of actual protection delivered:
122122
normalized facts for the pinned samples, and feed the same goldens to
123123
`test_ownir.py` so the Python suite also consumes *extractor-produced*
124124
facts, not only hand-written ones.
125-
3. **`spec/OwnIR.md` + `spec/ownir.schema.json`** (JSON Schema draft 2020-12,
126-
`ownir_version` as a `const`) *(now/short)*. Validate all
127-
`tests/fixtures/ownir/*.json` and the extractor's CI output against it.
128-
Note: the schema must encode the *deliberate* open points — unknown
129-
resource kinds coerce to `subscription` by documented design
130-
(`ownir.py:66-70`), so the resource-kind enum is open, and the schema's job
131-
is shape/type/enum guarantees, not vocabulary closure.
132-
4. **A written evolution policy** *(now, one paragraph in the spec)*: additive
133-
optional fields do not bump `OWNIR_VERSION`; a **new op or changed op
134-
semantics does**. Today's policy only covers the first half, which is
135-
exactly the gap item 1 exploits.
136-
5. Version single-sourcing across the three producers (`ownir.py:159`,
137-
`Program.cs:4360`, `ownts.py:580`) *(with next touch)* — worth doing, but
138-
understand what it does not protect: the dangerous case is *nobody* bumping,
139-
which only items 1–4 catch.
125+
3. **`spec/OwnIR.md`** ✅ (shipped) **+ `spec/ownir.schema.json`** (JSON Schema
126+
draft 2020-12, `ownir_version` as a `const`) — **the schema's trigger has now
127+
fired** (see the box below). Validate all `tests/fixtures/ownir/*.json` and
128+
each frontend's output against it. The schema must encode the *deliberate*
129+
open points — unknown resource kinds coerce to `subscription` by documented
130+
design (`ownir.py:66-70`), so the resource-kind enum is open; its job is
131+
shape/type/enum guarantees, not vocabulary closure.
132+
4. **A written evolution policy** ✅ *(now shipped in `spec/OwnIR.md` §2, rules
133+
IR1–IR6)*: additive optional fields / new resource kinds do not bump
134+
`OWNIR_VERSION`; a **new op or changed op semantics does**.
135+
5. Version single-sourcing ✅ *(enforced)* — a `test_ownir.py` check now greps
136+
each frontend producer (`Program.cs`, `ownts.py`) and asserts its
137+
`ownir_version` literal equals the core's `OWNIR_VERSION`, so "bumped the
138+
core, forgot a frontend" (or the reverse) fails loudly. Understand what it
139+
does **not** protect: the dangerous case is *nobody* bumping, which only
140+
items 1/4 catch. When the P-022 `own-ir` crate lands (a **fourth** producer),
141+
add it to this check — or, better, generate all four from the schema (§below).
140142
6. Reconcile or explicitly document the BCL fresh-factory asymmetry *(now,
141143
small)*: the extractor's `IsOwningFactory` knows the ADO.NET family
142144
(`ExecuteReader`/`CreateCommand`/`BeginTransaction`,
@@ -146,9 +148,28 @@ The formalization stack, in order of actual protection delivered:
146148
only consulted for first-party `call` ops), but the lockstep is
147149
comment-enforced and has already quietly diverged.
148150

149-
Later, if a Rust/C# core materializes: generate types from the same schema
150-
(serde via typify / System.Text.Json source-gen). Protobuf/FlatBuffers only if
151-
fact volume ever makes JSON parse time measurable — no evidence today.
151+
> **Why the schema is now worth building (the argument that was strong all
152+
> along, recovered).** OwnIR is not a nice-to-have file — it is *the one language
153+
> every frontend and the core speak* ("frontends only produce/consume OwnIR",
154+
> ROADMAP design philosophy). **A language without a formal grammar is a language
155+
> that lies about itself.** Until now the schema looked redundant: `ownlang`'s
156+
> hand-written `load()` was the sole validator, so a JSON Schema only *duplicated*
157+
> its shape checks — a second source of truth to drift against, needing a
158+
> `jsonschema` dependency the zero-dep core avoids. **That calculus flips the
159+
> moment there is a second language-native type set** — which has now arrived:
160+
> P-022 #170 ships `crates/own-ir`, hand-writing Rust `serde` structs under the
161+
> rule "accept exactly what Python `load()` accepts," kept in sync only by a
162+
> fixture round-trip. That is two hand-maintained validators of one contract, in
163+
> two languages — the exact drift the OwnIR formalization exists to kill. The
164+
> schema stops being a *shadow* of `load()` and becomes the *source both are
165+
> generated from* (Rust `serde` via `typify`/`schemars`; C#/TS types via
166+
> source-gen), collapsing the hand-synced fact shapes **and** the now-four
167+
> `ownir_version` literals into one authority. So: `spec/OwnIR.md` (done) is the
168+
> prose grammar; `spec/ownir.schema.json` is the machine grammar, and it should be
169+
> **co-designed with the `own-ir` crate** (generate the Rust types from it, don't
170+
> hand-write them twice) rather than bolted on after. JSON stays the wire format;
171+
> Protobuf/FlatBuffers only if measured parse cost ever demands it — no evidence
172+
> today.
152173
153174
## 3. The extractor↔bridge "mirror" (LowerFlowStmt / _lower_flow)
154175

@@ -195,7 +216,7 @@ Python walkers (§2.1).
195216
| N1 ✅ | `else: raise` on unknown flow ops | `ownlang/ownir.py` `_lower_flow` | Silent fact-swallowing → fabricated/missed verdicts (§2.1). *Done: raises `OwnIRError`; pinned by test_ownir. The five read-only walkers legitimately ignore ops they don't consume, so the guard is scoped to `_lower_flow` (the only pass that must handle every op or lose facts).* |
196217
| N2 ✅ | Auto-discovery in the test runner | `tests/run_tests.py` | 25-term hand-rolled `or`; a forgotten `rc` silently stopped gating. *Done: the runner now globs `test_*.py`, calls each module's `run()`, and gates on `any(rc)` — a new test file is auto-included, a module without `run()` fails the suite, and a discovery of zero modules fails loud. `test_codegen_props` keeps its lighter in-suite iteration count via a small special-case map.* |
197218
| N3 | Golden facts snapshots in CI + feed to `test_ownir.py` | `ci.yml` wpf-extractor job | The seam is never diffed at the facts level (§2.2) |
198-
| N4 ◑ | `spec/OwnIR.md` ✅ + JSON Schema (pending) + evolution policy ✅ | `spec/OwnIR.md` | §2.3–2.4. *Done: normative spec incl. the version evolution policy (IR1–IR6), registered in `spec/README.md`. Still to do: `spec/ownir.schema.json` + CI fixture validation.* |
219+
| N4 ◑ | `spec/OwnIR.md` ✅ + evolution policy ✅ + version single-sourcing ✅ + JSON Schema (trigger now fired) | `spec/OwnIR.md`, `tests/test_ownir.py` | §2. *Done: normative spec with the version evolution policy (IR1–IR6), registered in `spec/README.md`; and a producer-version-consistency check (each frontend's `ownir_version` must equal the core's). Remaining: `spec/ownir.schema.json` — its trigger has now fired (P-022 #170's `own-ir` crate = a second hand-written type set), so **co-design it with that crate and generate the Rust types from it**, per the §2 box; do NOT bolt a `jsonschema` CI validator onto the zero-dep core first.* |
199220
| N5 | DI001–005 + EFF001 into `spec/` + `Diagnostics.md` + `test_spec.py` | `ownlang/di.py`, `effects.py` | Second-largest analyzer has zero normative governance |
200221
| N6 ✅ | Fail-loud on unknown diagnostic code | `ownlang/diagnostics.py` `Diagnostic.__post_init__` | New codes land weekly; a typo'd code silently rendered `""`. *Done: `Diagnostic` now rejects any code absent from `TITLES` at construction (full suite confirms every emitted code is registered), and `title` indexes instead of `.get(...,"")`. A full `StrEnum` is the heavier follow-up; this closes the silent-`""` hole cheaply.* |
201222
| N7 | Split `ownir.py` → `ownir/{render,load,lower,inference,check}` | `ownlang/ownir.py` (2430 lines) | Fastest-accreting file in the repo; `check_facts` grows a branch per resource kind; deferring = paying the god-file tax on every feature |

‎tests/test_ownir.py‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
import json
2121
import os
22+
import re
2223
import sys
2324

2425
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
@@ -244,6 +245,34 @@ def _sub(source: str | None) -> list[Finding]:
244245
except OwnIRError:
245246
pass
246247

248+
# Version single-sourcing (IR2): every producer must stamp the SAME
249+
# ownir_version as the core. The literal is hand-kept in each frontend today —
250+
# once P-022's `own-ir` crate lands there are FOUR producers, so a schema will
251+
# make this a generated constant (spec/OwnIR.md §2). Until then, assert the
252+
# frontends match the core here, so "bumped the core, forgot a frontend" (or the
253+
# reverse) fails loudly instead of silently mis-reading facts at runtime.
254+
_ver = re.compile(r'ownir_version["\s]*[=:]\s*(\d+)')
255+
_repo = os.path.join(os.path.dirname(__file__), "..")
256+
_producers = {
257+
"Roslyn extractor (Program.cs)":
258+
os.path.join(_repo, "frontend", "roslyn", "OwnSharp.Extractor", "Program.cs"),
259+
"OwnTS frontend (ownts.py)":
260+
os.path.join(_repo, "frontend", "ownts", "ownts.py"),
261+
}
262+
for _label, _path in _producers.items():
263+
checks += 1
264+
try:
265+
with open(_path, encoding="utf-8") as _f:
266+
_m = _ver.search(_f.read())
267+
except OSError as _e:
268+
fails.append(f"{_label}: cannot read producer ({_e})")
269+
continue
270+
if _m is None:
271+
fails.append(f"{_label}: no `ownir_version` literal found (moved? update this check)")
272+
elif int(_m.group(1)) != OWNIR_VERSION:
273+
fails.append(f"{_label}: ownir_version {_m.group(1)} != core OWNIR_VERSION "
274+
f"{OWNIR_VERSION} — bump every producer together")
275+
247276
# --- WPF002 timer profile: a started timer never stopped/detached leaks,
248277
# a stopped one stays silent, and the finding is tagged [resource: timer].
249278
with open(_TIMER_FIXTURE, encoding="utf-8") as f:

0 commit comments

Comments
 (0)