Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

source: scrub iter-code / Decision-N residue from inline comments

Browse Source 
Follow-up to bcd4181: the remaining ~530 inline `//` and `///`
comments still carrying opaque shorthand are now reformulated to
their content phrases. The only surviving `iter-<code>` reference
in source is the literal filename
`docs/journals/2026-05-13-iter-mq.3.md` (a real journal file).

Sweep covered:
  - `// Iter X.Y: <text>` prefixes (Iter 13a / 14a / 14e / 15g-aux /
    16b.x / 16d / 16e / 18b / 18c.x / 18d.x / 18e / 18g.x / 19a /
    19a.1 / 19b / 20a / 20f / 22-floats.x / 22b.x / 22c / 23.x /
    24.1 / cli-diag-human / hs.x / str-concat / etc.) — fully
    removed; the descriptive text that followed each prefix stays.
  - `// (Decision N)` and `per Decision N` and `Decision N axis 3` —
    replaced with the content phrase plus the relevant contract
    file (`design/contracts/tail-calls.md` for Decision 8,
    `design/contracts/memory-model.md` for Decision 10,
    `design/contracts/typeclasses.md` and `design/models/typeclasses.md`
    for Decision 11, `design/contracts/authoring-surface.md` for
    Decision 6, "the transitional dual-allocator" for Decision 9,
    "Effect prose" for Decision 3).
  - `// mq.X / mq.X (Task N) / mq.X journal / mq.X invariant` ->
    "the canonical-class-form rule / Class-class repurpose /
    method-dispatch-refactor journal / canonical-class-form
    invariant".
  - `// ct.X / ct.X (canonical-type-names) / ct.1.5a + ctt.2 /
    ct.2 Task N` -> "the canonical-form rule for type references /
    the canonical-form normalisation step / canonical-type-lookup
    refactor".
  - `// eob.X` -> "heap-Str-ABI" / "the Str carve-out".
  - `// rpe.X` -> "the per-type-print-op retirement".
  - `// post-mq.X / Pre-ct.X / pre-mq.X` -> "post-canonical-class-form" /
    "Pre-canonical-type-form" etc.
  - `/// Iter X regression: / /// Iter X.Y: / /// Iter A arm-close /
    /// Iter ct.4 (...): / /// Iter rpe.1 ...` -> descriptive
    phrases.

The journal filename in `crates/ailang-core/src/workspace.rs:573`
stays verbatim because it points at an actual file under
`docs/journals/`.

Tests: full `cargo test --workspace` green (80/80 test-result blocks
clean, no FAILED line). design_index_pin 5/5 + docs_honesty_pin 5/5
gating tests pass.
This commit is contained in:
Brummel
2026-05-20 09:58:04 +02:00
parent bcd41810f4
commit ac4d545570
43 changed files with 1004 additions and 1000 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/ailang-surface/src/parse.rs
+28 -28
View File
@@ -385,7 +385,7 @@ impl<'a> Parser<'a> {
ctors.push(self.parse_ctor()?);
}
Some("drop-iterative") => {
// Iter 18e: `(drop-iterative)` opt-in annotation.
// `(drop-iterative)` opt-in annotation.
// Takes no arguments — it is a flag. A second
// `(drop-iterative)` clause is a parse error
// (rejected here so that the JSON schema's
@@ -510,7 +510,7 @@ impl<'a> Parser<'a> {
let mut ty: Option<Type> = None;
let mut params: Option<Vec<String>> = None;
let mut body: Option<Term> = None;
// Iter 19b: every `(suppress ...)` clause appends one entry. Order
// every `(suppress ...)` clause appends one entry. Order
// is preserved (matches the on-disk JSON-AST order).
let mut suppress: Vec<Suppress> = Vec::new();
loop {
@@ -586,7 +586,7 @@ impl<'a> Parser<'a> {
})
}
/// Iter 19b: parse one `(suppress (code "<c>") (because "<r>"))`
/// parse one `(suppress (code "<c>") (because "<r>"))`
/// clause, returning a [`Suppress`] entry. Unknown sub-keywords
/// inside the clause are rejected with [`ParseError::Production`].
/// The `because` text is allowed to be empty here (the typechecker
@@ -639,7 +639,7 @@ impl<'a> Parser<'a> {
Ok(Suppress { code, because })
}
/// Iter 19b: helper — consume one string-literal token. Used by
/// helper — consume one string-literal token. Used by
/// [`Self::parse_suppress_attr`].
fn expect_string(&mut self, ctx: &'static str) -> Result<String, ParseError> {
match self.peek().cloned() {
@@ -1013,7 +1013,7 @@ impl<'a> Parser<'a> {
"con" => self.parse_type_con(),
"fn-type" => self.parse_fn_type(),
"forall" => self.parse_forall_type(),
// Iter 18a: `borrow` / `own` are valid only as
// `borrow` / `own` are valid only as
// wrappers around `fn-type` params or `ret`. At
// top-level type position they are a parse error
// with a clear message.
@@ -1109,7 +1109,7 @@ impl<'a> Parser<'a> {
})
}
/// Iter 18a: parse one fn-type slot — a type, optionally wrapped
/// parse one fn-type slot — a type, optionally wrapped
/// in `(borrow T)` or `(own T)`. The mode is `Implicit` for a
/// bare type, `Borrow` for `(borrow T)`, `Own` for `(own T)`.
fn parse_param_with_mode(&mut self) -> Result<(Type, ParamMode), ParseError> {
@@ -1304,7 +1304,7 @@ impl<'a> Parser<'a> {
self.parse_app_body(false, "app-term")
}
/// Iter 14e: `(tail-app callee arg+)` — same shape as `app` but
/// `(tail-app callee arg+)` — same shape as `app` but
/// constructs `Term::App { tail: true, .. }`. The typechecker's
/// tail-position pass verifies that the call really is in tail
/// position; an unmarked call in tail position is also legal.
@@ -1398,7 +1398,7 @@ impl<'a> Parser<'a> {
self.parse_do_body(false, "do-term")
}
/// Iter 14e: `(tail-do op arg*)` — same shape as `do` but
/// `(tail-do op arg*)` — same shape as `do` but
/// constructs `Term::Do { tail: true, .. }`.
fn parse_tail_do(&mut self) -> Result<Term, ParseError> {
self.expect_lparen("tail-do-term")?;
@@ -1501,7 +1501,7 @@ impl<'a> Parser<'a> {
})
}
/// Iter 16b.1: `(let-rec NAME (params PARAM*) (type T) (body TERM)
/// `(let-rec NAME (params PARAM*) (type T) (body TERM)
/// (in TERM))` — local recursive fn-shaped binding. Eliminated by
/// the desugar pass (lifted to a synthetic top-level fn) before
/// typecheck. The body's recursive references to `NAME` are
@@ -1529,7 +1529,7 @@ impl<'a> Parser<'a> {
})
}
/// Iter 18c.1: `(clone TERM)` — explicit RC clone wrapper. In 18c.1
/// `(clone TERM)` — explicit RC clone wrapper. In 18c.1
/// the wrapper is identity for typechecker and codegen; in 18c.3
/// the codegen will emit `call void @ailang_rc_inc` before yielding
/// the inner value's SSA reg under `--alloc=rc`.
@@ -1560,7 +1560,7 @@ impl<'a> Parser<'a> {
})
}
/// Iter 18d.1: `(reuse-as SOURCE BODY)` — explicit reuse-as wrapper.
/// `(reuse-as SOURCE BODY)` — explicit reuse-as wrapper.
/// In 18d.1 the wrapper is identity for codegen (lowers `body` and
/// drops `source`); 18d.2 will lower this as in-place rewrite under
/// `--alloc=rc`. The parser accepts any term in either slot — the
@@ -1834,7 +1834,7 @@ mod tests {
assert!(matches!(m.defs.len(), 1));
}
/// Iter 18a: `(borrow T)` and `(own T)` wrappers in fn-type
/// `(borrow T)` and `(own T)` wrappers in fn-type
/// param/ret slots round-trip into [`ParamMode::Borrow`] /
/// [`ParamMode::Own`] on `Type::Fn`. A bare type stays
/// [`ParamMode::Implicit`] (and its mode is elided from the
@@ -1870,7 +1870,7 @@ mod tests {
}
}
/// Iter 18a: `(borrow T)` outside an `fn-type` param/ret slot is
/// `(borrow T)` outside an `fn-type` param/ret slot is
/// a parse error. Specifically, a `const` whose declared type is
/// `(borrow ...)` must be rejected with a clear message — modes
/// are *not* a top-level type production.
@@ -1892,7 +1892,7 @@ mod tests {
);
}
/// Iter 18c.1: `(clone X)` parses to `Term::Clone { value: Var "x" }`.
/// `(clone X)` parses to `Term::Clone { value: Var "x" }`.
#[test]
fn parses_clone_wraps_inner_term() {
let m = parse(
@@ -1918,7 +1918,7 @@ mod tests {
}
}
/// Iter 18c.1: `(clone)` with no inner term is rejected with a
/// `(clone)` with no inner term is rejected with a
/// clear message.
#[test]
fn rejects_clone_without_argument() {
@@ -1939,7 +1939,7 @@ mod tests {
);
}
/// Iter 18d.1: `(reuse-as xs (term-ctor List Cons (...)))` parses to
/// `(reuse-as xs (term-ctor List Cons (...)))` parses to
/// `Term::ReuseAs { source: Var "xs", body: Ctor "Cons" ... }`.
#[test]
fn parses_reuse_as_wraps_source_and_body() {
@@ -1976,7 +1976,7 @@ mod tests {
}
}
/// Iter 18d.1: `(reuse-as)` with no args is rejected.
/// `(reuse-as)` with no args is rejected.
#[test]
fn rejects_reuse_as_with_no_arguments() {
let err = parse(
@@ -1996,7 +1996,7 @@ mod tests {
);
}
/// Iter 18d.1: `(reuse-as x)` with a single arg is rejected.
/// `(reuse-as x)` with a single arg is rejected.
#[test]
fn rejects_reuse_as_with_one_argument() {
let err = parse(
@@ -2016,7 +2016,7 @@ mod tests {
);
}
/// Iter 18d.1: round-trip via `parse_term` / `term_to_form_a` —
/// round-trip via `parse_term` / `term_to_form_a` —
/// `(reuse-as xs (term-ctor List Cons 1 xs))` survives a print/parse
/// cycle as the same `Term::ReuseAs`.
#[test]
@@ -2040,7 +2040,7 @@ mod tests {
assert_eq!(term_to_form_a(&parsed), printed);
}
/// Iter 18e: `(data T (drop-iterative))` parses with
/// `(data T (drop-iterative))` parses with
/// `drop_iterative = true` AND round-trips through the printer
/// back to the same canonical surface form.
#[test]
@@ -2073,7 +2073,7 @@ mod tests {
}
}
/// Iter 18e: `(data T)` with no `(drop-iterative)` clause parses
/// `(data T)` with no `(drop-iterative)` clause parses
/// with `drop_iterative = false`. Default state must be the
/// pre-18e shape so legacy fixtures' canonical bytes are stable.
#[test]
@@ -2096,7 +2096,7 @@ mod tests {
}
}
/// Iter 18e: `(drop-iterative ...arg...)` is rejected — the
/// `(drop-iterative ...arg...)` is rejected — the
/// annotation is a flag with no payload.
#[test]
fn rejects_drop_iterative_with_arguments() {
@@ -2116,7 +2116,7 @@ mod tests {
);
}
/// Iter 16b.1: minimal `(let-rec ...)` round-trips through the
/// minimal `(let-rec ...)` round-trips through the
/// parser into a `Term::LetRec` whose `name`, `params`, `body` and
/// `in_term` line up with the source.
#[test]
@@ -2157,7 +2157,7 @@ mod tests {
}
}
/// Iter 19b: a `(fn ...)` carrying a single
/// a `(fn ...)` carrying a single
/// `(suppress (code "...") (because "..."))` clause parses into
/// [`FnDef::suppress`] with the corresponding [`Suppress`] entry.
#[test]
@@ -2183,7 +2183,7 @@ mod tests {
}
}
/// Iter 19b: multiple `(suppress ...)` clauses accumulate into
/// multiple `(suppress ...)` clauses accumulate into
/// `FnDef::suppress` in declaration order. A second clause does
/// NOT overwrite the first.
#[test]
@@ -2212,7 +2212,7 @@ mod tests {
}
}
/// Iter 19b: a `(fn ...)` without a `(suppress ...)` clause has
/// a `(fn ...)` without a `(suppress ...)` clause has
/// `FnDef::suppress` empty (the default — round-trip identity
/// with pre-19b fixtures).
#[test]
@@ -2235,7 +2235,7 @@ mod tests {
}
}
/// Iter 19b: a `(suppress ...)` with `(because "")` (empty
/// a `(suppress ...)` with `(because "")` (empty
/// reason) still parses cleanly — the parser is intentionally
/// permissive; the typechecker is what emits
/// `empty-suppress-reason`. This keeps the surface symmetric
@@ -2263,7 +2263,7 @@ mod tests {
}
}
/// Iter 19b: an unknown sub-attribute inside `(suppress ...)`
/// an unknown sub-attribute inside `(suppress ...)`
/// produces a `ParseError::Production` naming the bad keyword and
/// listing the legal ones (`code` / `because`).
#[test]
crates/ailang-surface/src/print.rs
+11 -11
View File
@@ -44,7 +44,7 @@ pub fn term_to_form_a(t: &Term) -> String {
out
}
/// Iter 19a: render a [`Type`] as form-A. Used by diagnostics that want
/// render a [`Type`] as form-A. Used by diagnostics that want
/// to suggest a relaxed signature (e.g. `over-strict-mode` shows the
/// `(fn-type ...)` with `(borrow T)` in place of `(own T)`). Output is
/// the same shape that appears as the `type` slot of a `(fn ...)` def.
@@ -123,7 +123,7 @@ fn write_type_def(out: &mut String, td: &TypeDef, level: usize) {
out.push('\n');
write_ctor(out, c, level + 1);
}
// Iter 18e: `(drop-iterative)` annotation. Printed last (after
// `(drop-iterative)` annotation. Printed last (after
// every ctor) so the canonical form lands consistent with the
// design/contracts/data-model.md example. Omitted when `drop_iterative == false`.
if td.drop_iterative {
@@ -163,7 +163,7 @@ fn write_fn_def(out: &mut String, fd: &FnDef, level: usize) {
write_string_lit(out, export);
out.push(')');
}
// Iter 19b: emit one `(suppress ...)` clause per entry, after the
// emit one `(suppress ...)` clause per entry, after the
// doc string and before the type. Round-trip stable: parser
// re-reads each clause back into [`FnDef::suppress`].
for s in &fd.suppress {
@@ -191,7 +191,7 @@ fn write_fn_def(out: &mut String, fd: &FnDef, level: usize) {
out.push(')');
}
/// Iter 19b: print one `(suppress (code "<c>") (because "<r>"))`
/// print one `(suppress (code "<c>") (because "<r>"))`
/// clause. Indentation matches the rest of the fn-def (one level
/// deeper than the `(fn ...)` head).
fn write_suppress(out: &mut String, s: &Suppress, level: usize) {
@@ -323,7 +323,7 @@ fn write_instance_method(out: &mut String, m: &InstanceMethod, level: usize) {
// ---- types ----------------------------------------------------------------
/// Iter 18a: print one fn-type param/ret slot, wrapping with
/// print one fn-type param/ret slot, wrapping with
/// `(borrow ...)` or `(own ...)` when the slot has an explicit
/// mode. `Implicit` is printed bare so pre-18a fixtures round-trip
/// unchanged.
@@ -343,7 +343,7 @@ fn write_fn_type_slot(out: &mut String, t: &Type, mode: ParamMode) {
}
}
/// Iter 22b.4a.4.5: print one `(constraint <Class> <type>)` pair, used
/// print one `(constraint <Class> <type>)` pair, used
/// inside the optional `(constraints …)` clause of a `(forall …)`. The
/// clause itself is omitted entirely when `Type::Forall.constraints` is
/// empty so pre-22b.2 forall fixtures stay bit-identical.
@@ -422,7 +422,7 @@ fn write_term(out: &mut String, t: &Term, level: usize) {
Term::Lit { lit } => write_lit(out, lit),
Term::Var { name } => out.push_str(name),
Term::App { callee, args, tail } => {
// Iter 14e: `tail-app` is the form for `App { tail: true }`;
// `tail-app` is the form for `App { tail: true }`;
// otherwise the regular `app` head is used. Both productions
// are positional analogues of each other — only the head
// keyword differs.
@@ -469,7 +469,7 @@ fn write_term(out: &mut String, t: &Term, level: usize) {
out.push(')');
}
Term::Do { op, args, tail } => {
// Iter 14e: `tail-do` mirrors `tail-app` for effect ops.
// `tail-do` mirrors `tail-app` for effect ops.
out.push_str(if *tail { "(tail-do " } else { "(do " });
out.push_str(op);
for a in args {
@@ -537,7 +537,7 @@ fn write_term(out: &mut String, t: &Term, level: usize) {
out.push(')');
}
Term::Clone { value } => {
// Iter 18c.1: print as `(clone <inner>)`. The wrapper is
// print as `(clone <inner>)`. The wrapper is
// identity at typecheck/codegen in 18c.1; only authored
// intent is recorded for the future inc/dec emission pass.
out.push_str("(clone ");
@@ -545,7 +545,7 @@ fn write_term(out: &mut String, t: &Term, level: usize) {
out.push(')');
}
Term::ReuseAs { source, body } => {
// Iter 18d.1: print as `(reuse-as <source> <body>)`. The
// print as `(reuse-as <source> <body>)`. The
// wrapper is identity at codegen in 18d.1 (the `body` is
// lowered, the `source` is dropped); 18d.2 will lower this
// as in-place rewrite under `--alloc=rc`.
@@ -812,7 +812,7 @@ mod tests {
round_trip(m, "minimal_instance");
}
/// Iter 22-floats.2 RED: `lex(print(L)) == L` round-trip property
/// `lex(print(L)) == L` round-trip property
/// for Float literals. Six representative bit patterns:
/// `1.5`, `0.0`, `-0.0`, `10.0`, `-0.375`, `1e10`. The round-trip
/// uses the existing `round_trip(Module, &str)` helper, which