scripts/guards/doc-examples.baseline - main - nv-lang/nova

scripts/guards/doc-examples.baseline
93 строки8 KB
Evgeniy Golovin
docs(ffi-debt): опустить baseline retired_external_fn/retired_addr_of до 0 после погашения долга
05 авг 2026, 04:46
05 авг 2026, 04:464678ff2
# baseline 2026-08-05 (окно p-example-guard, sonnet) — первый ввод стража
# check-doc-examples.sh. Числа сняты САМИМ СТРАЖОМ на дереве github/main
# (коммит f34f4ce66), периметр: docs/guide/*.md (+ *.ru.md), spec/*.md
# (+ *.en.md) КРОМЕ spec/open-questions.md (см. ниже), README.md/README.ru.md
# — верхний уровень без рекурсии, только содержимое ```nova-блоков.
#
# --- ПЕРИМЕТР: почему spec/open-questions.md исключён из сканирования ---
# Файл открывается заголовком «Nova — открытые вопросы дизайна» и подписью
# «Что обсуждали, но не зафиксировали как решение» — это журнал НЕ решённых
# (или решённых давно, но зафиксированных СВОЕГО ВРЕМЕНИ синтаксисом) design-
# вопросов, а не «как писать Nova сегодня» гайд для читателя. В нём, например,
# `external fn` фигурирует как канон, потому что решение Q-string-builder
# зафиксировано 2026-05-08 — ДО ретракции D282/Plan 91.12 (`external fn` →
# `extern "nova" fn`/`extern "C" fn`) — и с тех пор текст не обновлялся, как
# и не обновляется большинство исторических записей журнала. Природа файла
# та же, что у `spec/decisions/` — внутренний рабочий норматив/журнал, не
# публикуемая читателю поверхность «как писать код» — check-doc-conventions.sh
# по той же причине выводит `spec/decisions/**` из периметра dev_links
# («внутренний рабочий норматив», см. его собственный baseline). Разница
# лишь в том, ЧТО служит признаком: там — путь-каталог, здесь — путь-файл
# (open-questions.md — единственный файл такой природы среди spec/*.md
# верхнего уровня; остальные 12 — conversions/effects/overview/paradigm/
# revolutionary/syntax/GLOSSARY — нормативный текст читателя, сканируются).
# Без исключения 32 из 112 находок retired_external_fn (28%) были бы шумом
# ОДНОГО нечитательского файла, топящим сигнал по реально опубликованным
# docs/guide/*.md, ради которых страж и вводится.
#
# --- НАЙДЕННЫЙ ДОЛГ (после исключения open-questions.md) ---
# retired_external_fn=60 и retired_addr_of=10 — РЕАЛЬНЫЕ снятые формы в
# ОПУБЛИКОВАННЫХ docs/guide/*.md (не false positive стража, проверено
# построчным чтением каждого совпадения): `external fn` (E_EXTERNAL_FN_RETRACTED,
# Plan 91.12/D282, канон `extern "nova" fn`/`extern "C" fn`) и
# `addr_of(x)`/`addr_of_mut(x)` (E_ADDR_OF_REMOVED, Plan 118.6/D216 §4, канон
# `&x`) — оба класса представлены как ТЕКУЩИЙ валидный синтаксис (без
# оговорки «устарело»/«снято» рядом), т.е. компилятор гарантированно отверг
# бы эти примеры при попытке собрать. Файлы-источники (en/ru-пары, долг
# симметричен по обеим сторонам):
#   external fn (60): cleanup-cookbook.md/.ru.md (5), contracts.md/.ru.md (1),
#     ffi-cookbook.md/.ru.md (22), typed-pointers.md/.ru.md (4)
#     [числа — на СТОРОНУ пары; en+ru вместе дают 60]
#   addr_of/addr_of_mut (10): ffi-cookbook.md/.ru.md (5 на сторону)
# Остальные девять классов — 0 на текущем дереве (`let`/`readonly`/`*ro T`/
# `*unsafe T`/постфикс-`!`/trait-impl-throws/`ref`-формы/`null <тип>`/
# `#impl(<старое имя>)`) — либо доку успели вычистить раньше (см. коммит
# f34f4ce66 «последние следы снятых форм»), либо конструкция никогда не
# документировалась в живом примере.
#
# ДЕЙСТВИЕ: долг НЕ ретрофичен этой волной (задача волны — сам страж, не
# чистка контента; тот же порядок, что doc-conventions.sh завёл для
# mixed_language_files/dev_links при их первом вводе) — заморожен
# храповиком. Погашение (переписать `external fn` → `extern "nova" fn`,
# `addr_of(x)` → `&x` в 4 файлах) — отдельная волна.
#
# --- ПОГАШЕНИЕ 2026-08-05 (окно p-extern-debt, sonnet) ---
# retired_external_fn 60→0, retired_addr_of 10→0. Оба класса переписаны на
# канон во ВСЕХ 4 файловых парах (cleanup-cookbook, contracts, ffi-cookbook,
# typed-pointers, .md+.ru.md — код-блоки байт-в-байт равны между сторонами
# пары после правки). ABI-выбор (`extern "nova" fn` vs `extern "C" fn`) —
# НЕ угадан построчно: sqlite3/libpng/libcurl/libuv/malloc/os_read/open —
# литеральные C-библиотеки/симв., рядом C-shim или прямое упоминание
# библиотеки → `extern "C" fn`; `RawMem.copy`/`RawMem.fill` — сверено с
# РЕАЛЬНЫМ std/src/runtime/raw_mem.nv (`export extern "nova" unsafe fn
# RawMem.copy/.fill/...`) → `extern "nova" unsafe fn`; `libc_strlen` в
# contracts.md/.ru.md — сверено с РЕАЛЬНЫМ тестом
# nova_tests/contracts/neg/external_no_trusted_fail.nv (`extern "nova" fn
# libc_strlen(s str) -> int`, тот же сигнатурный близнец) → `extern "nova"
# fn` (НЕ extern "C" fn, хотя имя намекает на literal libc — в этом дереве
# уже есть прецедент, решающий неоднозначность в пользу runtime-backed).
# `c_strlen`/`c_printf` (ffi-cookbook.md/.ru.md, «CStr handle» секция) —
# буквального C-имени/библиотеки рядом нет (иллюстративные имена из Plan
# 118.1, `docs/plans/118.1-ffi-intrinsics-and-cstring.md:1217` использует то
# же имя без привязки к реальному символу), но ВЕСЬ файл — «bind Nova to
# third-party C libraries» (шапка файла) и раздел прямо о C-ABI (`const
# char*`) — решено в пользу `extern "C" fn` по теме документа, а не оставлено
# как отдельный неразрешённый остаток (отмечено в отчёте окна p-extern-debt
# как наименее уверенный вызов). `addr_of`/`addr_of_mut` → `&x` (обе формы
# ретрагированы на ОДНУ; типизация `*mut T` для mut-биндинга — сверено с
# spec/decisions/02-types.md:9660 «`&x` with mut binding auto-infers `*mut
# T`»). Остаточные упоминания «external fn»/«addr_of» вне ```nova-блоков
# (историческая проза Plan 115 V1 setup, M-номер-таблица закрытых followup'ов)
# — НЕ тронуты: описывают ИСТОРИЮ («тогда было так»), не текущий синтаксис,
# тот же принцип, что exempts spec/open-questions.md выше.
retired_kw_let=0
retired_kw_readonly=0
retired_pointer_ro=0
retired_unsafe_type_modifier=0
retired_postfix_bang=0
retired_trait_impl_throws=0
retired_ref_form=0
retired_external_fn=0
retired_addr_of=0
retired_null_ptr=0
retired_protocol_renamed=0