Skip to content

Commit f799ca0

Browse files
committed
Merge remote-tracking branch 'origin/main' into claude/own-net-tasks-3k6d07
# Conflicts: # docs/notes/field-notes-patterns.md
2 parents 19471e3 + 3703b05 commit f799ca0

21 files changed

Lines changed: 2021 additions & 33 deletions

‎.github/workflows/ci.yml‎

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1002,7 +1002,106 @@ jobs:
10021002
diff <(jq -S . "$RUNNER_TEMP/proj-facts.json") \
10031003
<(jq -S . "$RUNNER_TEMP/proj-facts-flag.json") \
10041004
|| { echo "FAIL: --project flag and positional .csproj emit different OwnIR facts"; exit 1; }
1005-
echo "OK: .csproj input resolves to its source set and feeds the core identically (positional == --project, fact-level parity)"
1005+
# the `extract` verb + `--out` long form must resolve to the same facts as the bare form.
1006+
dotnet run --project frontend/roslyn/OwnSharp.Extractor -- \
1007+
extract --project frontend/roslyn/project-input-sample/ProjectInputSample.csproj \
1008+
--out "$RUNNER_TEMP/proj-facts-verb.json"
1009+
diff <(jq -S . "$RUNNER_TEMP/proj-facts.json") \
1010+
<(jq -S . "$RUNNER_TEMP/proj-facts-verb.json") \
1011+
|| { echo "FAIL: 'extract --out' verb form disagrees with the bare form"; exit 1; }
1012+
echo "OK: .csproj input resolves to its source set and feeds the core identically (bare == --project == 'extract --out', fact-level parity)"
1013+
# explain: the diagnostic-catalogue CLI surface lives in the core (one checker). Smoke
1014+
# it end-to-end — explain a code, and harvest+explain every code in a real findings file.
1015+
- name: explain command (code + --json harvest)
1016+
run: |
1017+
python -m ownlang explain OWN001 | grep -q "Fix:" \
1018+
|| { echo "FAIL: explain OWN001 missing a Fix line"; exit 1; }
1019+
# ownir exits 1 when findings exist (expected — the sample leaks); only 2+ is a real
1020+
# error (bad facts / emit regression). Tolerate 1, surface 2+, so a genuine SARIF
1021+
# generation failure is not masked by a blanket `|| true` (CodeRabbit).
1022+
rc=0; python -m ownlang ownir "$RUNNER_TEMP/proj-facts.json" --format sarif > "$RUNNER_TEMP/proj.sarif" || rc=$?
1023+
[ "$rc" -le 1 ] || { echo "FAIL: SARIF generation errored (rc=$rc)"; exit 1; }
1024+
python -m ownlang explain --json "$RUNNER_TEMP/proj.sarif" | grep -q "OWN001" \
1025+
|| { echo "FAIL: explain --json did not harvest OWN001 from the SARIF log"; exit 1; }
1026+
echo "OK: explain answers a code and harvests codes from a real findings/SARIF file"
1027+
1028+
# The OwnTS frontend spike (P-020 Own.React): the SAME OwnIR seam, fed from a
1029+
# React .tsx instead of C#. Two analyses over the one core: (1) a useEffect
1030+
# acquire (timer / subscribe / listener) with no cleanup return is the core's
1031+
# OWN001 — the cross-language leak model; (2) EFF001, a NEW core analysis
1032+
# (ownlang/effects.py) — an IO effect whose dependency identity is unstable
1033+
# (a render-scope object literal) re-fires every render: the effect storm. The
1034+
# frontend emits only facts; the stability verdict is the core's. No dotnet.
1035+
ownts-react-effects:
1036+
name: OwnTS (React useEffect) -> OwnIR -> core
1037+
runs-on: ubuntu-latest
1038+
steps:
1039+
- uses: actions/checkout@v4
1040+
- uses: actions/setup-python@v5
1041+
with:
1042+
python-version: "3.13"
1043+
- name: Pin the spike (leaky=3xOWN001+EFF001, clean=0, showcase=2xEFF001)
1044+
run: python frontend/ownts/test_ownts.py
1045+
- name: Extract OwnIR facts from a React .tsx and check through the core
1046+
run: |
1047+
python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx \
1048+
-o "$RUNNER_TEMP/dash.facts.json"
1049+
cat "$RUNNER_TEMP/dash.facts.json"
1050+
out=$(python -m ownlang ownir "$RUNNER_TEMP/dash.facts.json" || true)
1051+
echo "$out"
1052+
echo "$out" | grep -q "Dashboard.tsx" \
1053+
|| { echo "FAIL: expected findings located at the .tsx"; exit 1; }
1054+
echo "$out" | grep -q "resource: timer" \
1055+
|| { echo "FAIL: expected the setInterval [resource: timer] leak"; exit 1; }
1056+
[ "$(echo "$out" | grep -c 'OWN001')" -eq 3 ] \
1057+
|| { echo "FAIL: expected three OWN001 leaks"; exit 1; }
1058+
echo "$out" | grep -q "\[EFF001\].*request storm" \
1059+
|| { echo "FAIL: expected the EFF001 effect-storm verdict"; exit 1; }
1060+
# exact finding count (a code-tagged line each), not a substring of "4 finding"
1061+
[ "$(echo "$out" | grep -cE '\[(OWN|EFF|DI)[0-9]{3}\]')" -eq 4 ] \
1062+
|| { echo "FAIL: expected 3 OWN001 + 1 EFF001 = 4 findings"; exit 1; }
1063+
- name: EFF001 stability showcase — only provable storms fire (low FP)
1064+
run: |
1065+
python frontend/ownts/ownts.py frontend/ownts/examples/EffectStorm.tsx \
1066+
-o "$RUNNER_TEMP/storm.facts.json"
1067+
storm=$(python -m ownlang ownir "$RUNNER_TEMP/storm.facts.json" || true)
1068+
echo "$storm"
1069+
# the direct object dep and its derived alias fire; memo/ref/call/primitive/no-IO stay silent
1070+
[ "$(echo "$storm" | grep -c '\[EFF001\]')" -eq 2 ] \
1071+
|| { echo "FAIL: expected exactly two EFF001 (object dep + derived alias)"; exit 1; }
1072+
echo "$storm" | grep -q "derives from" \
1073+
|| { echo "FAIL: expected the derivation (propagation) verdict"; exit 1; }
1074+
- name: Edge cases — partial timer cleanup + nested-scope shadow
1075+
run: |
1076+
python frontend/ownts/ownts.py frontend/ownts/examples/EffectEdges.tsx \
1077+
-o "$RUNNER_TEMP/edges.facts.json"
1078+
edges=$(python -m ownlang ownir "$RUNNER_TEMP/edges.facts.json" || true)
1079+
echo "$edges"
1080+
# only the SECOND, uncleared interval leaks; the memoized dep is not shadowed
1081+
[ "$(echo "$edges" | grep -cE '\[(OWN|EFF|DI)[0-9]{3}\]')" -eq 1 ] \
1082+
|| { echo "FAIL: expected exactly one OWN001 (the uncleared timer)"; exit 1; }
1083+
echo "$edges" | grep -q "pollB" \
1084+
|| { echo "FAIL: the leak must be the second (uncleared) interval"; exit 1; }
1085+
- name: Parser hardening — string literals, nested dep brackets, listener options
1086+
run: |
1087+
python frontend/ownts/ownts.py frontend/ownts/examples/EffectHardening.tsx \
1088+
-o "$RUNNER_TEMP/hard.facts.json"
1089+
hard=$(python -m ownlang ownir "$RUNNER_TEMP/hard.facts.json" || true)
1090+
echo "$hard"
1091+
# a string with commas/braces does not truncate the body (the timer is cleared);
1092+
# the leak is the options-dropped listener; the object dep fires EFF001 once
1093+
[ "$(echo "$hard" | grep -cE '\[(OWN|EFF|DI)[0-9]{3}\]')" -eq 2 ] \
1094+
|| { echo "FAIL: expected one OWN001 (listener) + one EFF001 (object dep)"; exit 1; }
1095+
echo "$hard" | grep -q "scroll" \
1096+
|| { echo "FAIL: the leak must be the options-dropped scroll listener"; exit 1; }
1097+
- name: The clean fixture (cleanups + useMemo'd dep) is silent
1098+
run: |
1099+
python frontend/ownts/ownts.py frontend/ownts/examples/DashboardClean.tsx \
1100+
-o "$RUNNER_TEMP/clean.facts.json"
1101+
clean=$(python -m ownlang ownir "$RUNNER_TEMP/clean.facts.json" || true)
1102+
echo "$clean"
1103+
[ "$(echo "$clean" | grep -cE '\[(OWN|EFF|DI)[0-9]{3}\]')" -eq 0 ] \
1104+
|| { echo "FAIL: cleaned-up + memoised effects must not fire"; exit 1; }
10061105
10071106
# The distribution surface (Уровень 1): the own-check.sh orchestrator walks a
10081107
# directory of real C# and prints findings in the host-parseable formats the

‎docs/notes/field-notes-patterns.md‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,8 @@ critical section — important on hot paths.
131131
**Analyzer angle:** the disposable is a **value type**, disposed by the `using`.
132132
Infer#'s Pulse engine reports each of these as `PULSE_RESOURCE_LEAK` "allocated
133133
indirectly via `TimedLock.Lock` … not closed" — a systematic **over-report on the
134-
struct-`using` pattern** (12 of them on Polly). Own.NET's silence is correct.
134+
struct-`using` pattern** (11 of them on Polly; the 12th Infer# resource-leak report is a
135+
strategy-ctor allocation, see entry 7). Own.NET's silence is correct.
135136
**A value-type `IDisposable` used in a `using` is disposed deterministically;
136137
don't treat the `.Lock()` factory call as an escaping allocation.**
137138

@@ -178,7 +179,42 @@ viewed through an adapter. **When a type wraps a disposable it doesn't own, the
178179
correct behaviour is to forward disposal, not perform it — and an analyzer must
179180
not count the wrapped allocation against the wrapper.**
180181

181-
## 7. Event subscription on a freshly-created, *returned* publisher
182+
## 7. Run ledger — Polly re-run after D5.4 step 2 (ctor-adopt `alias_join`)
183+
184+
**Seen in:** the oracle re-run of `App-vNext/Polly` (`src/`, product code only) at
185+
commit `976983f` *after* P-005 D5.4 step 2 shipped — the Roslyn extractor now emits
186+
`alias_join` for a verified constructor adopt (`var w = new W(x)`). This entry is the
187+
**audit record** the maintenance rule below requires: it pins no new idiom (entries 1–4
188+
already cover Polly's), but documents that the new emission stayed precise and accounts
189+
for every `oracle-only` finding.
190+
191+
**Buckets (unchanged from the pre-step-2 run):** Own.NET leak findings **0**; Agree 0;
192+
**Own.NET-only 0**; oracle-only **16**. The new `alias_join` path produced **zero**
193+
own-only findings on real code — the precision floor held end-to-end.
194+
195+
**The 16 oracle-only, each accounted for (all oracle FP or by-design):**
196+
197+
| # | site | tool | disposition → entry |
198+
|---|---|---|---|
199+
| 11 | `TimedLock.Lock(...)` across `CircuitBreaker/*` (AdvancedCircuitController ×3, CircuitStateController ×4, ConsecutiveCountCircuitController ×3) + `TimedLock.cs:32` | Infer# `PULSE_RESOURCE_LEAK` | struct-`using` over-report → **entry 4** |
200+
| 1 | `CircuitBreakerResiliencePipelineBuilderExtensions.cs:75` | Infer# `PULSE_RESOURCE_LEAK` | strategy ctor allocation, disposed by the pipeline → **entry 1/2** |
201+
| 2 | `BulkheadSemaphoreFactory.cs:8,11` | CodeQL `cs/local-not-disposed` | factory returns, adopted into owning fields → **entry 1** |
202+
| 1 | `ConfigureBuilderContextExtensions.cs:40` | CodeQL `cs/local-not-disposed` | CTS disposed in an `OnPipelineDisposed` callback (`#pragma CA2000`) → **entry 2** |
203+
| 1 | `TimeoutResilienceStrategy.cs:67` | CodeQL `cs/dispose-not-called-on-throw` | pooled CTS `Get`/`Return` (catch-all around the throwing await) → **entry 3** |
204+
205+
**Analyzer angle / the recall boundary this run pins.** `BulkheadSemaphoreFactory`
206+
(entry 1) is the shape people expect step 2 to "fix", but it is **not** the construction-
207+
site ctor-adopt step 2 models — it is *factory-returns-fresh* + *caller-stores-in-an-
208+
owning-field* (the deferred T4b field-store-to-`this` shape). So step 2 correctly leaves
209+
it untouched, and CodeQL's two FPs there stay `oracle-only` (we must **not** flag them —
210+
the semaphores are owned by `BulkheadPolicy`). Both CodeQL CTS findings are also
211+
non-leaks (callback-deferred dispose; pooled return), so **there is nothing on Polly we
212+
could newly catch without manufacturing a false positive.** own-only-0 here is principled,
213+
not luck — and the next recall lever for this family is the deferred field-store adopt, not
214+
anything in step 2's scope. *(Confidence: high — dispositions verified against the pinned
215+
Polly source, not just the SARIF excerpts.)*
216+
217+
## 8. Event subscription on a freshly-created, *returned* publisher
182218

183219
**Seen in:** Newtonsoft.Json `Src/Newtonsoft.Json/JsonSerializer.cs:717`
184220
(`ApplySerializerSettings`, commit `4f73e74`).
@@ -221,7 +257,7 @@ interprocedural (the construct-and-return is in the caller), which is the hard p
221257
The honest interim posture — advisory warning, never a hard error — is already in
222258
place.**
223259

224-
## 8. Owning field whose IDisposable holds no unmanaged resource
260+
## 9. Owning field whose IDisposable holds no unmanaged resource
225261

226262
**Seen in:** Newtonsoft.Json `Src/Newtonsoft.Json/Serialization/TraceJsonReader.cs:37,38`
227263
and `TraceJsonWriter.cs:39` (commit `4f73e74`).
@@ -270,13 +306,14 @@ responsibility travels with the reference** — out of a factory (1, 6), forward
270306
time via a callback (2), into a pool (3), or down a `using` on a value type (4).
271307
Naive "every disposable needs a lexical `using`/`Dispose` on every path" checks
272308
misread all of them, which is why Infer#/CodeQL over-report here and a
273-
transfer/escape-aware checker (Own.NET) correctly stays quiet.
309+
transfer/escape-aware checker (Own.NET) correctly stays quiet. (Entry 7 is a run
310+
ledger — an audit record of a Polly re-run, not an idiom.)
274311

275-
Entries 7–8 are the **mirror image — the first cases where _Own.NET_ is the one
312+
Entries 8–9 are the **mirror image — the first cases where _Own.NET_ is the one
276313
over-reporting and the oracle is correctly silent.** They map our own precision
277-
frontier: a subscription on a publisher that *escapes by return* (7, the dual of
314+
frontier: a subscription on a publisher that *escapes by return* (8, the dual of
278315
ownership transfer — bounded, but the construct-and-return is interprocedural), and
279-
an owning field whose `IDisposable` holds no real resource (8, a `StringWriter` is
316+
an owning field whose `IDisposable` holds no real resource (9, a `StringWriter` is
280317
not a handle — belongs in the `IsDisposeOptional` allowlist). Same moral as 1–6,
281318
pointed back at us: **a leak is about the *resource* and the *reference's
282319
lifetime*, not the mere presence of an `IDisposable` and a missing `Dispose`/`-=`.**

‎docs/notes/roslyn-tools-and-cli.md‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,37 @@ short of the full project/package/reference graph — that is the
117117
`wpf-extractor` CI step pins the `.csproj` path to a golden (positional ==
118118
`--project`).
119119

120-
## Next PR (concrete, no scope creep)
120+
## The `extract` / `check` / `explain` surface (landed)
121121

122-
Firm up the rest of the advertised CLI: `extract` / `check` / `explain`
123-
subcommands (`System.CommandLine`), and `--ref-dir`-from-project-`bin`
124-
auto-derivation once `ProjectDependencies`-style graph reading lands.
122+
The advertised three-verb CLI is realised — but split to where the architecture
123+
puts each, not bolted onto one binary (there is one checker; the C# tool only
124+
emits facts):
125+
126+
```bash
127+
ownsharp-extract extract --project App.csproj --out facts.ownir.json # C# extractor (facts)
128+
scripts/own-check.sh --format sarif -- App.sln > findings.sarif # `check`: the orchestrator
129+
python -m ownlang explain OWN001 # `explain`: the core's catalogue
130+
python -m ownlang explain --json findings.sarif # (explain every code a run produced)
131+
```
132+
133+
(`explain --json` harvests diagnostic *codes* from the checker's findings/SARIF
134+
output — not from `facts.ownir.json`, which carries extractor facts, no codes.)
135+
136+
- **`extract`** is an optional leading verb on the C# tool (the bare form stays the
137+
default), plus `--out` as the long twin of `-o`. The tool's one job.
138+
- **`check`** is *not* a C# verb: `own-check.sh` already chains the extractor and the
139+
core, and since the project/solution PR it takes a `.csproj`/`.sln` directly.
140+
Re-implementing a checker in C# is the rejected path.
141+
- **`explain`** lives in the core next to the diagnostic catalogue
142+
(`ownlang/diagnostics.py`: `TITLES` + `EXPLANATIONS`): it prints what a code means,
143+
why it fires, and how to fix it; `--json` harvests every code from a findings/SARIF
144+
file so you can explain exactly what a run produced.
145+
146+
A `System.CommandLine` migration of the C# tool (auto `--help`, validation) and
147+
`--ref-dir`-from-project-`bin` auto-derivation remain the next polish — deferred over
148+
a blind framework swap, since the extractor builds only in CI here.
149+
150+
## Earlier next-PR sketch (kept for the record)
125151

126152
```bash
127153
ownsharp extract --project App.csproj --out facts.ownir.json

‎docs/proposals/P-020-ownts-react-effects.md‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,17 @@
33
- **Status:** draft — **experiment / proposal, explicitly not mainline.** A
44
marketing-shaped spike under the OwnTS frontend, on the record so the framing is
55
honest before any code.
6+
- **Spike landed:** the honest `EFF003`/`EFF004` slice (timer / subscribe /
7+
listener acquire with no cleanup `return` → core `OWN001`) is implemented in
8+
`frontend/ownts/` and CI-pinned (the `ownts-react-effects` job).
9+
- **`EFF001` is now a real core analysis** (`ownlang/effects.py`), answering Open
10+
question 1 below: a self-contained **dependency-identity stability** lattice with
11+
reference propagation, computed by the **core** over an OwnIR `effects` fact block
12+
the frontend emits — *not* a frontend heuristic, and *not* an `OWN001`. It is its
13+
own core code (`EFF001`), exactly as the DI captive check is `DI001`. The frontend
14+
states only what each render-scope binding syntactically is; the core decides
15+
stability. `EFF002` (network IO with no stable guard) is governed by the same
16+
analysis and left as the next increment.
617
- **Depends on:** [P-017](P-017-multi-stack-frontends.md) (the OwnTS frontend &
718
confidence tiers that this profile feeds), `spec/OwnCore.md` (the acquire/release
819
vocabulary), [P-004](P-004-wpf-lifetime-profile.md) (WPF — the same lifecycle
@@ -145,12 +156,18 @@ has on the .NET side (P-013/P-015); 1/2/6/7 are this proposal's actual work.
145156

146157
## Open questions
147158

148-
1. **The new analysis for `EFF001/002`.** Detecting "dependency identity is unstable
149-
across renders" needs render-scope object-literal/identity reasoning the core
150-
has no model for. Is that a small, self-contained *stability* fact
151-
(`unstable(dep, effect)`) the OwnTS frontend can emit and the core treat like an
152-
acquire-site, or a genuinely new core analysis? This is the gating question — do
153-
not let `EFF001` masquerade as an `OWN001` leak.
159+
1. **The new analysis for `EFF001`.** ✅ **Answered (implemented).** It is a
160+
genuinely new core analysis, not an `OWN001` acquire-site — and *not* a frontend
161+
verdict either. The resolution: the frontend emits per-binding **facts** (each
162+
render-scope binding's syntactic `init` kind + the names it references, the dep
163+
list, whether the body does IO) in an OwnIR `effects` block; the **core**
164+
(`ownlang/effects.py`) runs an identity-stability lattice (`STABLE < UNKNOWN <
165+
UNSTABLE`) to a fixpoint over the references and decides `unstable(dep)`. An
166+
effect is `EFF001` iff it does IO **and** a dep is *provably* `UNSTABLE`
167+
(`UNKNOWN`/memoised/primitive clear it — low false positives). The gating
168+
discipline held: `EFF001` is its own core code (like `DI001`), never an `OWN001`.
169+
`EFF002` (network IO with no stable guard) is intended to reuse this same
170+
lattice but is **not yet implemented** — it remains the next increment.
154171
2. **Confidence tier.** `EFF001` clearly wants TS-mode type info (is the dep an
155172
object literal? does the body do IO?). What, if anything, survives into JS mode
156173
(P-017's heuristic tier) as a warning?

0 commit comments

Comments
 (0)