Skip to content

Commit 6d51b4a

Browse files
committed
docs: address CodeRabbit review on #140 (fix 2, clarify 3)
Fixed: - alpha-readiness front-door note was stale within this PR — README is now bilingual (EN default + README.ru.md), no longer "the Russian PoC"; reworded. - alpha-readiness gate-B cell: backtick the action `format` values (`github`/`msbuild`/`human`/`sarif`) — they are literal option strings, so backticked, not capitalized as the platform name (LanguageTool misfire). Kept with clarification (CodeRabbit applied the global contract without the profile nuance): - "OWN001 warning" is correct, not a contract violation: the subscription profile deliberately down-tiers an injected/unknown-lifetime source to a warning (ROADMAP milestone 2, P-004:84). Added "deliberate down-tier (OWN001 is otherwise an error)" inline, EN + RU. - ArrayPool `buf.AsSpan()` stays unbounded: the block is emitter output *verbatim* (the borrow template carries no length), and the README already documents the `AsSpan(0,size)` caveat. Editing it would falsify the verbatim-emit claim; strengthened the caveat to mark the snippet illustrative/non-normative instead, EN + RU. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QnGqHwVb2H1jZ71f498MFa
1 parent 2e1b31b commit 6d51b4a

3 files changed

Lines changed: 14 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,8 @@ but a *region escape*: the extractor lowers it to a tokenless `capture` fact, an
158158
matching `-=` clears the finding) — the WPF escape as a profile of the general
159159
region model, not a separate detector (P-004 WPF005; sample
160160
`StaticEventEscapeViewModel`). An injected source (unknown lifetime) stays an
161-
OWN001 warning until ownership modelling can prove its lifetime.
161+
OWN001 warning — the subscription profile's deliberate down-tier (OWN001 is otherwise
162+
an error) — until ownership modelling can prove its lifetime.
162163

163164
There is one core (not a second checker written in C#): the extractor only
164165
produces facts. dotnet exists only in CI (the `wpf-extractor` job runs the
@@ -214,10 +215,11 @@ public static void process(int size)
214215
```
215216

216217
`Main` and the `Fill`/`Hash` stubs in `Program.cs` are host code, written by hand
217-
(`extern fn` is the host's promise; the host supplies the body). A caveat: `AsSpan()`
218-
takes the whole rented array (Rent may return more than requested); an honest version
219-
would write `AsSpan(0, size)`, but the length is not available to the borrow template
220-
— a deliberate simplification for the smoke test.
218+
(`extern fn` is the host's promise; the host supplies the body). A caveat: this snippet is
219+
**emitter output verbatim, so it is illustrative, not normative** — `AsSpan()` takes the
220+
whole rented array (Rent may return more than requested); an honest version would write
221+
`AsSpan(0, size)`, but the length is not available to the borrow template, a deliberate
222+
simplification for the smoke test.
221223

222224
---
223225

‎README.ru.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ CustomerViewModel.cs:9: error: [OWN001] event 'bus.CustomerChanged' is subscribe
157157
process-lifetime; парный `-=` снимает находку) — WPF-escape как профиль общей
158158
region-модели, а не отдельный детектор (P-004 WPF005; сэмпл
159159
`StaticEventEscapeViewModel`). Источник-инъекция (неизвестное время жизни)
160-
остаётся OWN001-warning'ом, пока ownership-моделирование не докажет его время жизни.
160+
остаётся OWN001-warning'ом — это осознанный down-tier профиля подписок (по умолчанию OWN001 — ошибка), — пока ownership-моделирование не докажет его время жизни.
161161

162162
Ядро одно (не второй чекер на C#): экстрактор только производит факты. dotnet
163163
есть лишь в CI (job `wpf-extractor` гоняет экстрактор на сэмплах сквозняком);
@@ -212,7 +212,8 @@ public static void process(int size)
212212
```
213213

214214
`Main` и заглушки `Fill`/`Hash` в `Program.cs` — это host-код, написанный руками
215-
(`extern fn` — обещание хоста, тело даёт хост). Нюанс: `AsSpan()` берёт весь
215+
(`extern fn` — обещание хоста, тело даёт хост). Нюанс: этот фрагмент — **дословный вывод
216+
эмиттера, поэтому он иллюстративный, а не нормативный** — `AsSpan()` берёт весь
216217
арендованный массив (Rent может вернуть длиннее запрошенного); честная версия
217218
писала бы `AsSpan(0, size)`, но шаблону borrow'а длина недоступна — это
218219
сознательное упрощение для smoke-теста.

‎docs/notes/alpha-readiness.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,16 @@ The bar for "showable": a person can reproduce the wow in ~3 minutes
3737
| | Item | Status (2026-06-27) | Gap to close |
3838
|---|------|--------------------|--------------|
3939
| **A** | `dotnet tool` one-command CLI | ◑ **partial** — the *extractor* is `PackAsTool` (`ownsharp-extract`, P-013); the core is Python. The delightful `ownsharp check MyApp.sln` single tool isn't packaged. | Wrap extractor+core into one `dotnet tool` (or a self-contained CLI) that takes a `.sln`/dir and prints findings. |
40-
| **B** | GitHub Action | ✅ **built** — `action.yml`: `path`/`severity`/`format` (github / msbuild / human / sarif), purple shield branding. Matches the "stupidly simple YAML" bar. | Publish to Marketplace; pin the 6-line usage in the README. |
40+
| **B** | GitHub Action | ✅ **built** — `action.yml`: `path`/`severity`/`format` (`github` / `msbuild` / `human` / `sarif`), purple shield branding. Matches the "stupidly simple YAML" bar. | Publish to Marketplace; pin the 6-line usage in the README. |
4141
| **C** | SARIF / PR annotations | ✅ **built** — SARIF 2.1.0 + GitHub annotations + reachability/evidence (P-015). | — |
4242
| **D** | 5 core diagnostics | ✅ **built, well past** — OWN001/002/003, OWN014, DI001–005, POOL001–005, WPF001–005 (catalog). The comment's `SUB001/SUB002/TMR001/DISP001/DI001` all exist *semantically*; the `SUB/TMR/DISP` catalog rename is the deferred consolidation item, not new work. | (naming only) land the catalog rename with the OwnIR-v1/profile-label work. |
4343
| **E** | 10 bad/ok examples | ✅ **built** — 12 test-pinned gallery cases (`examples/gallery/`, incl. `00_ok_clean`) + extractor samples. | Add `.cs`-native (not `.own`) bad/ok pairs for the C# audience. |
4444
| **F** | 3 real-world case studies | ◑ **partial** — one honest mining write-up (`real-world-mining.md`: Dapper, CsvHelper, **ScreenToGif** flagship `VideoSource` + two `SystemEvents` leaks, all TPs, clean on disciplined libs) + a 20-case `corpus/real-world/`. Raw material for 3 studies exists; the *packaged* studies don't. | Write 3 `bad → fixed → what others miss → how Own reports it` studies from existing finds. |
4545
| **G** | suppression + false-positive policy | ◑ **partial** — `[OwnIgnore("reason")]` designed (P-004), project-wide config is P-015 (draft); precision behaviour is strong & documented ("no FP from `using`"). | One consolidated user-facing page: suppression mechanism + explicit FP policy. |
4646

47-
**Plus the front door (not in A–G but the real blocker):** `README.md` is still
48-
`# OwnLang — PoC` — deep, Russian, research-framed. There is **no 20-second landing /
47+
**Plus the front door (not in A–G but the real blocker):** `README.md` is now
48+
bilingual (English default + a `README.ru.md` variant), but still `# OwnLang — PoC` —
49+
deep, research-framed, no wedge landing. There is **no 20-second landing /
4950
copy-paste install / Action quickstart** at the top. Per the comment's own
5051
open-source-path list (README-in-20s → copy-paste → bad/ok → Action → SARIF →
5152
suppression → "why not Sonar/CodeQL"), this is the highest-leverage missing piece.

0 commit comments

Comments
 (0)