tidy: rustdoc-sweep + drift-test-narrowing — autonomous batch
Two unrelated hygiene iters bundled because they shipped together in one autonomous-while-Boss-away batch: - iter rustdoc-sweep: cleared all 23 `cargo doc --workspace --no-deps` warnings (17 in ailang-check + 4 in ailang-core + 2 in ailang-surface). Two warning classes: pub-doc-comment links to pub(crate)/private items (15 hits — replaced with plain backtick-code-spans), and unresolved/ambiguous links (8 hits — fully-qualified, disambiguated to fn-form, or escaped). No behaviour change; tests 562 → 562. - iter drift-test-narrowing: design_schema_drift.rs now scans §"Data model" only via new helper data_model_section(), instead of full DESIGN.md. Closes the audit-form-a-precursor [high] "anchor-elsewhere-passes-silently" failure mode. All 38 anchors verified pre-edit to live in §"Data model" so the tightening doesn't regress to red. New pin data_model_section_is_bounded guards the extractor against silent regression. Tests 562 → 563.
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# iter drift-test-narrowing — design_schema_drift.rs scans §"Data model" only
|
||||
|
||||
**Date:** 2026-05-13
|
||||
**Started from:** rustdoc-sweep working-tree state
|
||||
**Status:** DONE
|
||||
|
||||
## Summary
|
||||
|
||||
`crates/ailang-core/tests/design_schema_drift.rs` is the
|
||||
drift-detection layer between AST enum definitions in
|
||||
`crates/ailang-core/src/ast.rs` and the canonical schema
|
||||
documentation in `docs/DESIGN.md` §"Data model". Each AST variant
|
||||
must have its JSON-schema anchor (e.g. `"t": "lit"`, `"k": "fn"`)
|
||||
documented; the tests assert presence of each anchor.
|
||||
|
||||
Pre-iter, the assertion was `DESIGN_MD.contains(anchor)` —
|
||||
substring search over the whole document. That was loose: an
|
||||
anchor present only in §"Decision 11" (or any other discussion
|
||||
section) was treated as documented even though §"Data model" —
|
||||
the canonical schema reference section — was missing it. The
|
||||
audit-form-a-precursor `[high]` drift report flagged this as the
|
||||
silent-pass failure mode.
|
||||
|
||||
This iter narrows the scan. New helper `data_model_section()`
|
||||
extracts the slice of `DESIGN_MD` from the `## Data model` header
|
||||
to the next top-level `## ` header. The 7 existing anchor tests
|
||||
now call `data_model_section().contains(anchor)` instead of
|
||||
`DESIGN_MD.contains(anchor)`. All 38 anchors verified present in
|
||||
§"Data model" pre-edit (no regressions). A new test
|
||||
`data_model_section_is_bounded` pins the extractor itself
|
||||
(starts-with `## Data model`, does not bleed past `\n## Pipeline`,
|
||||
length > 1 KB) so a future refactor cannot silently regress the
|
||||
extractor to whole-document scanning.
|
||||
|
||||
## Files touched
|
||||
|
||||
- `crates/ailang-core/tests/design_schema_drift.rs` (M)
|
||||
|
||||
## Verification
|
||||
|
||||
- `cargo test -p ailang-core --test design_schema_drift` →
|
||||
8 passed (was 7; +1 for the bounded-section pin), 0 failed.
|
||||
- `cargo test --workspace` → 563 passed (was 562; +1 from the
|
||||
new pin), 0 failed.
|
||||
|
||||
## Concerns
|
||||
|
||||
- (none)
|
||||
|
||||
## Known debt
|
||||
|
||||
- (none)
|
||||
@@ -0,0 +1,61 @@
|
||||
# iter rustdoc-sweep — clear all 23 cargo-doc warnings
|
||||
|
||||
**Date:** 2026-05-13
|
||||
**Started from:** 48b1f77 (post-WhatsNew str-concat done-state)
|
||||
**Status:** DONE
|
||||
|
||||
## Summary
|
||||
|
||||
Hygiene sweep against `cargo doc --workspace --no-deps`. Before: 23
|
||||
warnings (17 in `ailang-check` + 4 in `ailang-core` + 2 in
|
||||
`ailang-surface`). After: zero. All edits are documentation-only —
|
||||
no production code, no test code changed. Tests stay 562 green.
|
||||
|
||||
Two warning classes, fixed with two different shapes:
|
||||
|
||||
- **Public doc links to private items** (15 warnings). Pattern:
|
||||
a `pub` item's `///` doc references `[`fn_name`]` where `fn_name`
|
||||
is `pub(crate)` or private. Fix: replace ``[`fn_name`]`` with
|
||||
the plain backtick-code-span ``` `fn_name` ```. The identifier
|
||||
stays readable in rendered docs but rustdoc no longer tries to
|
||||
resolve the link.
|
||||
- **Unresolved links** (8 warnings). Sub-classes:
|
||||
- ``[`Registry`]`` in `mono.rs` (×3) — `Registry` lives in
|
||||
`ailang_core::workspace` and the path was bare. Fixed by
|
||||
fully-qualifying as `[`ailang_core::workspace::Registry`]` /
|
||||
`[`ailang_core::workspace::Registry::entries`]`.
|
||||
- ``[`Env::class_methods`]`` — `Env` is in this crate but
|
||||
bare; the doc string was demoted to plain backticks
|
||||
(`` `crate::Env::class_methods` ``) because `Env` itself has
|
||||
no `pub` re-export at the crate root that rustdoc could
|
||||
follow.
|
||||
- ``[`crate::parse`]`` ambiguous in `loader.rs` (×2) — rustdoc
|
||||
saw both a function and a module with that path. Disambiguated
|
||||
to the function form via ``[`crate::parse()`]`` per
|
||||
rustdoc's own suggestion.
|
||||
- `metas[i]` in `lib.rs` — rustdoc parsed `[i]` as a link.
|
||||
Escaped as `metas\[i\]` (same fix for the sibling `vars\[i\]`).
|
||||
|
||||
## Files touched
|
||||
|
||||
- `crates/ailang-core/src/desugar.rs` (1 line)
|
||||
- `crates/ailang-core/src/workspace.rs` (3 lines)
|
||||
- `crates/ailang-surface/src/loader.rs` (2 lines)
|
||||
- `crates/ailang-check/src/uniqueness.rs` (2 lines)
|
||||
- `crates/ailang-check/src/diagnostic.rs` (1 line)
|
||||
- `crates/ailang-check/src/mono.rs` (5 lines)
|
||||
- `crates/ailang-check/src/lib.rs` (8 lines)
|
||||
|
||||
## Verification
|
||||
|
||||
- `cargo doc --workspace --no-deps 2>&1 | grep "^warning:" | wc -l`
|
||||
→ `0`.
|
||||
- `cargo test --workspace` → 562 passed, 0 failed (baseline holds).
|
||||
|
||||
## Concerns
|
||||
|
||||
- (none)
|
||||
|
||||
## Known debt
|
||||
|
||||
- (none)
|
||||
@@ -58,3 +58,5 @@
|
||||
- 2026-05-13 — iter bugfix-instance-body-unbound-var: instance method bodies now walk through `check_fn` — `check_def`'s `Def::Class(_) | Def::Instance(_)` arm at `crates/ailang-check/src/lib.rs:1574-1595` was early-returning `Ok(())` for both variants (the comment claimed iter 22b.2 landed instance-body typechecking; the wiring was never implemented), so an unbound identifier inside an instance-method lambda body slipped past `ail check` (false-OK exit 0 with `ok (N symbols across M modules)`) and surfaced only at `ail build` as the degraded internal-error diagnostic `monomorphise_workspace: unknown identifier: <name>` without source location, symbol kind, or "did you mean" candidates. Fix: split the combined arm so `Def::Class(_)` stays schema-only at this layer while `Def::Instance(inst)` routes through a new helper `check_instance` that, for each `InstanceMethod`, lifts the body `Term::Lam` into a synthetic `FnDef` and applies class-method substitution (class param → instance type via the existing `substitute_rigids` / `substitute_rigids_in_term` helpers — looked up in `env.class_methods[(qualify_class_ref_in_check(&inst.class, &env.current_module), im.name)]` for the class's `param` name) before handing to `check_fn`. The reuse of `check_fn` is what gets the body walked through the same identifier-resolution path as fn bodies, so an unbound name fires `[unbound-var]` at `ail check` with exit 1 and the standard structured diagnostic. RED: 2 tests in `crates/ail/tests/unbound_in_instance_method_pin.rs` (text-mode + `--json` shape, both committed in 72f3f65 ahead of the GREEN side per the audit-trail flow). GREEN: 557+2 = 559 green; both pins PASS; fn-body-level unbound-var path stays green; all 8 carve-out fixtures classify unchanged. Known debt (out of scope per "minimal fix" constraint, recorded in journal): `check_instance` does not yet cross-check the substituted method signature against the class's `ClassMethodEntry.method_ty` — a malformed instance declaring wrong types in its Lam would still typecheck cleanly. Closes the bug finding from fieldtest-form-a → 2026-05-13-iter-bugfix-instance-body-unbound-var.md
|
||||
- 2026-05-13 — iter form-a.tidy: post-fieldtest documentary tidy — 6 tasks; closes 2/3 fieldtest-form-a spec_gaps + 3/4 audit-form-a drift items. T1-T3 add three new sections to `crates/ailang-core/specs/form_a.md`: `### Class — (class ...)` (EBNF with optional `(superclass …)?` schema-matched cardinality + abstract-required vs default-bearing method clauses, anchored to `examples/test_22c_user_class_e2e.ail` ok 24/2), `### Instance — (instance ...)` (EBNF with canonical-form CLASS-REF rule explicitly stated + same-module bare example abbreviated from `mq3_class_eq_vs_fn_eq_classmod.ail` + cross-module qualified example from `show_user_adt.ail` + `bare-cross-module-class-ref` diagnostic anchor), and `(forall ...)` extension with optional `(constraints (constraint CLASS-REF TYPE)+)?` clause + `no-instance` diagnostic anchor + fifth Examples-block entry anchored to `cmp_max_smoke.ail` ok 22/2. §Definitions intro flipped `Three kinds` → `Five kinds`. T4 fixes 6 contradictory "seven carve-outs" sites in `docs/specs/2026-05-13-form-a-default-authoring.md` (preamble + §C1 + §C2 + §C3 + §"Data flow" two sites) to match the §C4(b) amendment commit 9fcda8b; post-edit grep returns 4 correctly-scoped surviving "seven" mentions (lines 233, 238, 463, 469 — all §C4(a)-scope or arithmetic/future-state). T5 deletes empty `#[cfg(test)] mod tests {}` placeholder + 6-line relocation-comment block from `crates/ailang-core/src/hash.rs:50-57` (the unit tests live in `crates/ailang-core/tests/hash_pin.rs` since form-a.1 T5 relocation; placeholder served no purpose). T6 rewrites `crates/ailang-surface/tests/round_trip.rs` module-level `//!` (lines 1-26) and inner `///` (lines 63-72) docstrings to the post-T10 four-property framing (parse-determinism + idempotency-under-print + CLI-pipeline-idempotency + carve-out-anchor) instead of retired Direction-1/Direction-2 framing, with sibling-crate breadcrumbs pointing at the other two enforcement points (`crates/ail/tests/roundtrip_cli.rs::cli_parse_then_render_then_parse_is_idempotent` for CLI-pipeline-idempotency, `crates/ailang-core/tests/carve_out_inventory.rs::examples_ail_json_inventory_matches_carve_outs` for carve-out-anchor). Drift item B2 ("plan-file seven-orphans, two sites" per audit-form-a) dropped from the iter: recon verified `docs/plans/2026-05-13-iter-form-a.1.md` contains zero defective `seven` mentions; all four hits are internally scoped to §C4(a), arithmetic, or future-state — the audit-form-a journal's "two sites" claim against the plan file did not match its contents at HEAD; decision recorded in journal §"Decision recorded — Drift item B2". Tests 559 green at every per-task gate (no test-file changes; T5 deletes a no-op `mod tests {}`). Pure-documentary iter, Phase 3 deliberately skipped per carrier; verification was per-task `cargo test --workspace` + `ail check` on the four corpus fixtures cited in T1-T3. Remaining open from form-a fieldtest queue: friction (no `str_concat` primitive — symmetric tidy iter queued) → 2026-05-13-iter-form-a.tidy.md
|
||||
- 2026-05-13 — iter str-concat: `str_concat : (borrow Str, borrow Str) -> Str` heap-Str concatenation primitive shipped in four-site lockstep, closing fieldtest-form-a friction finding #4. T1 RED-pin `crates/ail/tests/str_concat_e2e.rs` + new corpus fixture `examples/show_user_adt_with_label.ail` (Show user-ADT body using `(app str_concat "Item " (app int_to_str n))` through prelude `print`; ok 23/2). T2 `runtime/str.c` C helper `ailang_str_concat(a, b)` appended after `ailang_str_clone`: reads `len` headers from both source payloads, `str_alloc(la+lb)`, memcpys both bytes, NUL-terminates. T3 `crates/ailang-check/src/builtins.rs` install entry (Type::Fn arity-2 Borrow-Borrow params, Own return, effects empty) + list() row + `install_str_concat_signature` unit test reaching into `env.globals` directly (deeper than synth_in_builtins_env-based siblings because first builtin with arity-2 Borrow params). T4 `crates/ailang-codegen/src/lib.rs` four-site lockstep: extern `declare ptr @ailang_str_concat(ptr, ptr)` after str_clone declare + lower_app arm after str_clone arm (arity-2 check + two `lower_term` + `fresh_ssa` + body push) + `is_builtin_callable` match-list extended with `"str_concat"` + IR-pin unit test `str_concat_emits_call_to_ailang_str_concat` asserting both extern declaration AND call instruction in emitted IR. Five IR snapshots regenerated (`hello.ll`, `list.ll`, `max3.ll`, `sum.ll`, `ws_main.ll`) to absorb the new unconditional declare line in IR header — same upkeep pattern as hs.4 (sole diff verified at IR line 17 across all snapshots). T5 lockstep-collision repair: `examples/bug_unbound_in_instance_method.ail` had used `str_concat` as the literal UNBOUND name (because that was the fieldtester's LLM-natural repro); renamed to `format_label` (LLM-author-realistic helper name that will never become a builtin) and updated `crates/ail/tests/unbound_in_instance_method_pin.rs` (`replace_all` on `str_concat` → `format_label`, including one test name flipped to `check_fires_unbound_var_for_format_label_in_instance_method_body`), preserving the regression guard's intent (instance-method-body walked through unbound-var check) while substituting a name with stable unbound semantics. T6 `docs/DESIGN.md` new §"Heap-Str primitives" subsection (line 1994) between the milestone-24 Show-backer enumeration and the existing `Primitive output goes through ...` paragraph, cataloguing all five heap-Str primitives (`int_to_str`, `bool_to_str`, `float_to_str`, `str_clone`, `str_concat`) with type signatures, iter origins, and the user-visible-vs-prelude-internal distinction; Show-backer block unchanged. T7 `docs/roadmap.md` struck `[x] [feature] str_concat` line at end of P2 cluster. Two minor plan-vs-actual discrepancies recorded in journal Concerns: (a) T3 Step 5 test-count prediction `passed: 560 failed: 1` was actual `passed: 558 failed: 3` because the unbound_in_instance_method_pin tests turn RED at checker registration not at codegen (assertion is on the `[unbound-var]` diagnostic which depends only on the checker registry) — implementation correct, T5 fully repairs; (b) IR snapshot regen for T4 was not explicitly scripted in the plan but follows hs.4 precedent. Final iter state: 562/562 green (559 baseline + 3 new pins), zero re-loops across all 7 tasks. Bench impact none (no new code paths touched by bench corpus; bench fixtures use `int_to_str` / `bool_to_str` only). Closes fieldtest-form-a queue: bug (closed bugfix-instance-body-unbound-var), spec_gaps 2+3 (closed form-a.tidy), friction (closed here). Remaining open: spec_gap 1 dropped per recon (audit-form-a "plan two sites" claim did not match HEAD) → 2026-05-13-iter-str-concat.md
|
||||
- 2026-05-13 — iter rustdoc-sweep: cleared all 23 `cargo doc --workspace --no-deps` warnings (17 in `ailang-check` + 4 in `ailang-core` + 2 in `ailang-surface`). Two warning classes: (a) `pub` doc-comments that linked-via-brackets to `pub(crate)`/private items (15 hits) — replaced ``[`fn`]`` with plain backtick-code-span ``` `fn` ``` so the identifier stays readable but rustdoc no longer tries to resolve the link; (b) unresolved/ambiguous links (8 hits) — `mono.rs` `[`Registry`]`/`[`Registry::entries`]` ×3 fully-qualified to `[`ailang_core::workspace::Registry…`]`; `loader.rs` `[`crate::parse`]` ×2 (ambiguous between fn + mod) disambiguated to `[`crate::parse()`]`; `lib.rs` `metas[i]` (parsed as a link) escaped to `metas\[i\]`. Tests 562 → 562, no behaviour change → 2026-05-13-iter-rustdoc-sweep.md
|
||||
- 2026-05-13 — iter drift-test-narrowing: `crates/ailang-core/tests/design_schema_drift.rs` now scans §"Data model" only, not the whole DESIGN.md. New helper `data_model_section()` slices `DESIGN_MD` from `## Data model` to the next top-level `## ` header; all 7 anchor-presence tests switched from `DESIGN_MD.contains(anchor)` to `data_model_section().contains(anchor)`. Closes the audit-form-a-precursor `[high]` "anchors-elsewhere-pass-silently" failure mode (an anchor present only in §"Decision 11" or another discussion section was previously treated as documented). All 38 anchors verified pre-edit to live in §"Data model" so the tightening doesn't regress to red. New pin `data_model_section_is_bounded` (starts-with `## Data model`, no bleed past `\n## Pipeline`, > 1 KB) guards the extractor itself against silent regression to whole-document scanning. Tests 562 → 563 (+1) → 2026-05-13-iter-drift-test-narrowing.md
|
||||
|
||||
Reference in New Issue
Block a user