Skip to content

Commit 98ebb51

Browse files
authored
Merge pull request #142 from PhysShell/claude/roslyn-tools-own-net-l36cwp
feat(cli): realize the extract/check/explain surface (explain in core, extract verb)
2 parents b9bbb71 + 9f125fb commit 98ebb51

8 files changed

Lines changed: 443 additions & 20 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -996,7 +996,28 @@ jobs:
996996
diff <(jq -S . "$RUNNER_TEMP/proj-facts.json") \
997997
<(jq -S . "$RUNNER_TEMP/proj-facts-flag.json") \
998998
|| { echo "FAIL: --project flag and positional .csproj emit different OwnIR facts"; exit 1; }
999-
echo "OK: .csproj input resolves to its source set and feeds the core identically (positional == --project, fact-level parity)"
999+
# the `extract` verb + `--out` long form must resolve to the same facts as the bare form.
1000+
dotnet run --project frontend/roslyn/OwnSharp.Extractor -- \
1001+
extract --project frontend/roslyn/project-input-sample/ProjectInputSample.csproj \
1002+
--out "$RUNNER_TEMP/proj-facts-verb.json"
1003+
diff <(jq -S . "$RUNNER_TEMP/proj-facts.json") \
1004+
<(jq -S . "$RUNNER_TEMP/proj-facts-verb.json") \
1005+
|| { echo "FAIL: 'extract --out' verb form disagrees with the bare form"; exit 1; }
1006+
echo "OK: .csproj input resolves to its source set and feeds the core identically (bare == --project == 'extract --out', fact-level parity)"
1007+
# explain: the diagnostic-catalogue CLI surface lives in the core (one checker). Smoke
1008+
# it end-to-end — explain a code, and harvest+explain every code in a real findings file.
1009+
- name: explain command (code + --json harvest)
1010+
run: |
1011+
python -m ownlang explain OWN001 | grep -q "Fix:" \
1012+
|| { echo "FAIL: explain OWN001 missing a Fix line"; exit 1; }
1013+
# ownir exits 1 when findings exist (expected — the sample leaks); only 2+ is a real
1014+
# error (bad facts / emit regression). Tolerate 1, surface 2+, so a genuine SARIF
1015+
# generation failure is not masked by a blanket `|| true` (CodeRabbit).
1016+
rc=0; python -m ownlang ownir "$RUNNER_TEMP/proj-facts.json" --format sarif > "$RUNNER_TEMP/proj.sarif" || rc=$?
1017+
[ "$rc" -le 1 ] || { echo "FAIL: SARIF generation errored (rc=$rc)"; exit 1; }
1018+
python -m ownlang explain --json "$RUNNER_TEMP/proj.sarif" | grep -q "OWN001" \
1019+
|| { echo "FAIL: explain --json did not harvest OWN001 from the SARIF log"; exit 1; }
1020+
echo "OK: explain answers a code and harvests codes from a real findings/SARIF file"
10001021
10011022
# The distribution surface (Уровень 1): the own-check.sh orchestrator walks a
10021023
# directory of real C# and prints findings in the host-parseable formats the

‎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

‎frontend/roslyn/OwnSharp.Extractor/Program.cs‎

Lines changed: 26 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,15 @@
1616
// `.Stop()` call. The IDisposable/pool/local detectors remain syntactic for now
1717
// (P-014 rollout: the event fact goes type-aware first).
1818
//
19-
// Usage: ownsharp-extract <file.cs | dir | *.csproj | *.sln> [more ...] [-o facts.json]
20-
// ownsharp-extract --project App.csproj (flag twin of the positional form)
19+
// Usage: ownsharp-extract [extract] <file.cs | dir | *.csproj | *.sln> [more ...] [-o|--out facts.json]
20+
// ownsharp-extract extract --project App.csproj --out facts.json
2121
// ownsharp-extract --solution App.sln
2222
//
23+
// `extract` is an optional leading verb (the tool's one job); the bare form is the
24+
// default. The sibling `check`/`explain` verbs are NOT here — `check` is the
25+
// own-check orchestrator that chains this + the core, and `explain` is `python -m
26+
// ownlang explain OWN001`. One checker: the C# tool only emits facts.
27+
//
2328
// Inputs may be .cs files, directories, a .csproj, or a .sln. A directory is walked
2429
// recursively for *.cs, skipping build output (bin/obj), VCS/vendor dirs (.git,
2530
// node_modules) and generated files (*.g.cs, *.Designer.cs) — so you can point it at a
@@ -70,25 +75,33 @@
7075
// run that did not request it (the other config — emitEvents/flowLocals/reportStats — are locals,
7176
// re-initialized each call, so they need no reset; only this static one does). CodeRabbit.
7277
BodyThrowEdges = false;
73-
for (int i = 0; i < args.Length; i++)
74-
{
75-
if (args[i] == "-o" && i + 1 < args.Length) outPath = args[++i];
78+
// `extract` verb: the tool's one job is extraction, so an optional leading `extract`
79+
// makes the advertised `ownsharp-extract extract --project App.csproj --out facts.json`
80+
// UX real while the bare form (no verb) stays the default and back-compatible. (The
81+
// sibling `check`/`explain` verbs live where the architecture puts them — `check` is the
82+
// own-check orchestrator, `explain` is `python -m ownlang explain`; the C# tool is not a
83+
// second checker.) A different first token (a path/flag) is left untouched as input.
84+
var args0 = args.Length > 0 && args[0] == "extract" ? args[1..] : args;
85+
for (int i = 0; i < args0.Length; i++)
86+
{
87+
// `--out FILE` is the long-form twin of `-o FILE` (the advertised `extract --out` UX).
88+
if ((args0[i] == "-o" || args0[i] == "--out") && i + 1 < args0.Length) outPath = args0[++i];
7689
// `--project <App.csproj>` / `--solution <App.sln>`: the explicit-flag twin of passing the
7790
// project/solution as a positional input (both resolve through Expand). The flag form matches
7891
// the advertised `ownsharp extract --project ...` UX borrowed from the roslyn-tools CLI shape;
7992
// the positional form keeps the command unambiguous next to dotnet's own `run --project`.
80-
else if ((args[i] == "--project" || args[i] == "--solution") && i + 1 < args.Length) rawInputs.Add(args[++i]);
81-
else if (args[i] == "--ref-dir" && i + 1 < args.Length) refDirs.Add(args[++i]);
82-
else if (args[i] == "--no-event-leaks") emitEvents = false;
83-
else if (args[i] == "--flow-locals") flowLocals = true;
84-
else if (args[i] == "--body-throw-edges") BodyThrowEdges = true;
85-
else if (args[i] == "--stats") reportStats = true;
86-
else rawInputs.Add(args[i]);
93+
else if ((args0[i] == "--project" || args0[i] == "--solution") && i + 1 < args0.Length) rawInputs.Add(args0[++i]);
94+
else if (args0[i] == "--ref-dir" && i + 1 < args0.Length) refDirs.Add(args0[++i]);
95+
else if (args0[i] == "--no-event-leaks") emitEvents = false;
96+
else if (args0[i] == "--flow-locals") flowLocals = true;
97+
else if (args0[i] == "--body-throw-edges") BodyThrowEdges = true;
98+
else if (args0[i] == "--stats") reportStats = true;
99+
else rawInputs.Add(args0[i]);
87100
}
88101

89102
if (rawInputs.Count == 0)
90103
{
91-
Console.Error.WriteLine("usage: ownsharp-extract <file.cs | dir | *.csproj | *.sln> [...] [-o facts.json] [--ref-dir <bin-dir>]");
104+
Console.Error.WriteLine("usage: ownsharp-extract [extract] <file.cs | dir | *.csproj | *.sln> [...] [-o|--out facts.json] [--ref-dir <bin-dir>]");
92105
return 2;
93106
}
94107

‎frontend/roslyn/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,18 @@ project or solution the way the borrowed roslyn-tools CLI shape advertises:
3838
dotnet run --project OwnSharp.Extractor -- App.csproj -o facts.json # positional
3939
dotnet run --project OwnSharp.Extractor -- --project App.csproj -o facts.json
4040
dotnet run --project OwnSharp.Extractor -- --solution App.sln -o facts.json
41+
dotnet run --project OwnSharp.Extractor -- extract --project App.csproj --out facts.json # explicit verb
4142
```
4243

44+
`extract` is an optional leading verb (the tool's one job; the bare form is the
45+
default), and `--out` is the long twin of `-o`. The sibling verbs live where the
46+
architecture puts them — `check` is `scripts/own-check.sh` (which chains this + the
47+
core and accepts a `.csproj`/`.sln`), and `explain` is in the core:
48+
`python -m ownlang explain OWN001` (or `--json findings.sarif` — the checker's
49+
findings/SARIF output — to explain every code a run produced; note `facts.json`
50+
holds extractor facts, not diagnostic codes). One checker: the C# tool only emits
51+
facts.
52+
4353
A `.csproj` resolves to its source set by scanning the project's directory for
4454
`*.cs` (the SDK default-compile-items behaviour) plus any concrete linked
4555
`<Compile Include="..\Shared\Foo.cs" />` outside the project tree — while honouring

‎ownlang/__main__.py‎

Lines changed: 106 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@
77
python -m ownlang report file.own # buffer storage report + .ownreport.json
88
python -m ownlang ownir facts.json # check OwnIR facts extracted from C# (P-001)
99
python -m ownlang ownir facts.json --format github|msbuild|human|sarif
10+
python -m ownlang explain OWN001 [DI002 ...] # explain diagnostic code(s): what/why/fix
11+
python -m ownlang explain --json findings.json # explain every code in a findings/SARIF file
12+
13+
`explain` is the diagnostic catalogue side of the CLI (the `ownsharp explain` the
14+
roslyn-tools-shaped surface advertises): it prints what a code means, why it fires,
15+
and how to fix it. It lives in the core, next to the catalogue, because there is one
16+
checker — the C# extractor emits facts, it does not own the diagnostics.
1017
1118
`--format` (ownir only) selects the finding surface: `human` (default CLI line),
1219
`github` (CI annotations on the PR diff), `msbuild` (VS Error List), or `sarif`
@@ -23,6 +30,7 @@
2330

2431
from __future__ import annotations
2532

33+
import re
2634
import sys
2735
from typing import TYPE_CHECKING
2836

@@ -192,6 +200,82 @@ def _read(path: str) -> str:
192200
return f.read()
193201

194202

203+
# A diagnostic code is OWN/WPF/DI followed by three digits. Used to validate an
204+
# `explain` argument and to harvest codes out of a findings/SARIF JSON file.
205+
_CODE_RE = re.compile(r"^(OWN|WPF|DI)\d{3}$")
206+
207+
208+
def _explain_one(code: str) -> str:
209+
"""The explanation block for one code: its title and the long-form what/why/fix
210+
(falling back to just the title when no long-form exists), or an 'unknown code'
211+
line. Pure text so it is trivially testable."""
212+
from .diagnostics import EXPLANATIONS, TITLES
213+
code = code.upper()
214+
title = TITLES.get(code)
215+
body = EXPLANATIONS.get(code)
216+
if title is None and body is None:
217+
return f"{code}: unknown diagnostic code"
218+
out = f"{code}: {title}" if title else code
219+
if body:
220+
out += "\n\n" + body
221+
return out
222+
223+
224+
def _codes_from_json(obj: object) -> list[str]:
225+
"""Every distinct diagnostic code reachable in a decoded JSON value, in first-seen
226+
order. Harvests the values of any `code`/`ruleId` key (so it reads a findings array,
227+
a single finding, or a SARIF log's results) that look like a diagnostic code."""
228+
seen: dict[str, None] = {}
229+
230+
def walk(node: object) -> None:
231+
if isinstance(node, dict):
232+
for key, val in node.items():
233+
if key in {"code", "ruleId"} and isinstance(val, str) and _CODE_RE.match(val):
234+
seen.setdefault(val, None)
235+
else:
236+
walk(val)
237+
elif isinstance(node, list):
238+
for item in node:
239+
walk(item)
240+
241+
walk(obj)
242+
return list(seen)
243+
244+
245+
def cmd_explain(codes: list[str], json_path: str | None) -> int:
246+
"""Explain diagnostic code(s): print what each means, why it fires, and how to fix
247+
it. Codes come from the command line (`explain OWN001 DI002`) and/or are harvested
248+
from a findings/SARIF JSON (`--json findings.json`), so you can explain exactly the
249+
codes a run produced. Exit 2 on a usage error (no codes) or an unreadable JSON."""
250+
import json
251+
all_codes = list(codes)
252+
if json_path is not None:
253+
try:
254+
with open(json_path, encoding="utf-8") as f:
255+
data = json.load(f)
256+
except (OSError, json.JSONDecodeError) as e:
257+
print(f"explain: cannot read {json_path}: {e}", file=sys.stderr)
258+
return 2
259+
found = _codes_from_json(data)
260+
if not found:
261+
print(f"explain: no diagnostic codes found in {json_path}", file=sys.stderr)
262+
return 2
263+
# de-dupe against any codes already given on the command line, preserving order
264+
for c in found:
265+
if c not in all_codes:
266+
all_codes.append(c)
267+
if not all_codes:
268+
print("explain: give a code (e.g. OWN001) or --json <findings.json>", file=sys.stderr)
269+
return 2
270+
from .diagnostics import EXPLANATIONS, TITLES
271+
print("\n\n".join(_explain_one(c) for c in all_codes))
272+
# If every requested code is unknown, that is almost certainly a typo — fail (2)
273+
# rather than silently succeed. A mix of known + unknown still exits 0.
274+
if all(c.upper() not in TITLES and c.upper() not in EXPLANATIONS for c in all_codes):
275+
return 2
276+
return 0
277+
278+
195279
def cmd_ownir(path: str, fmt: str = "human", severity: str = "error",
196280
verbosity: str = "normal") -> int:
197281
"""Check OwnIR facts (extracted from real C# by the Roslyn frontend) through
@@ -261,10 +345,31 @@ def cmd_ownir(path: str, fmt: str = "human", severity: str = "error",
261345

262346

263347
def main(argv: list[str]) -> int:
264-
if not argv or argv[0] not in {"check", "emit", "cfg", "report", "ownir"}:
348+
if not argv or argv[0] not in {"check", "emit", "cfg", "report", "ownir", "explain"}:
265349
print(__doc__)
266350
return 2
267351
cmd = argv[0]
352+
# `explain` has its own shape — zero-or-more code positionals plus an optional
353+
# `--json <file>` — so it is handled before the single-positional path below.
354+
if cmd == "explain":
355+
codes: list[str] = []
356+
json_path: str | None = None
357+
rest = argv[1:]
358+
i = 0
359+
while i < len(rest):
360+
a = rest[i]
361+
if a == "--json":
362+
if i + 1 >= len(rest):
363+
print("--json requires a value", file=sys.stderr)
364+
return 2
365+
json_path, i = rest[i + 1], i + 2
366+
continue
367+
if a.startswith("--json="):
368+
json_path, i = a.split("=", 1)[1], i + 1
369+
continue
370+
codes.append(a)
371+
i += 1
372+
return cmd_explain(codes, json_path)
268373
# Pull the optional value-flags (`--format`/`--severity`/`--verbosity`, ownir
269374
# only) out of the arguments in either `--flag V` or `--flag=V` form; everything
270375
# else is positional. Keeps the other commands' single positional-path contract.

0 commit comments

Comments
 (0)