Skip to content

An example that produces the code - #966

Merged
onatozmenn merged 1 commit into
mainfrom
an-example-that-produces-the-code
Aug 9, 2026
Merged

onatozmenn merged 1 commit into
mainfrom
an-example-that-produces-the-code

Conversation

@onatozmenn

Copy link
Copy Markdown
Collaborator

deed explain DEED2011 says "there is no range in this language", and printed
this:

module a

fn f() -> Int {
  Int n = 1
  n
}

That program produces DEED2010. There is no range in it.

Measured

Every page's example, checked, and run when the code only appears at run time:

pages 104
carrying an example 89
whose example does not produce the code 43

Why

The example was "the first deed-looking string in a test that mentions this
code"
, which is a different claim from "a program that produces it". Two
shapes:

  • The extractor read a test from its #[test] to the next #[test], so
    the window swallowed whatever introduced the following test. These files
    introduce a test with a banner naming its code:

    // -- DEED2011, a range ------------------------------------------------

    so every code named that way matched the previous test's window first.
    That is the whole DEED2002…DEED2012 run, each page holding its predecessor's
    program.

  • Where a test carried two modules, or a passing control arm, the first string
    was the wrong half. DEED4006 (non-exhaustive match) showed one module of a
    two-module program, which on its own produces DEED3007, "no module other".

This artefact is read by deed explain, by the deed_explain MCP tool, and by
the error index the site builds. An agent asking what a code means was handed a
program about a different one.

The rule now

An example is the first candidate that produces the code, asked of the
compiler. Every deed snippet in every test naming the code is a candidate.

before after
carrying an example 89 75
…that produces the code 46 75
carrying none 15 29

Fourteen pages traded a wrong program for no program. A page with nothing true
to show should show nothing, and Page::example was already Option.

DEED2011 now prints the range. DEED4025 prints a call that breaks a
precondition.

Why the generator moved

To crates/deed-driver/tests/explain_pages.rs. Deciding that a program
produces a code takes a checker, and deed-explain depends on nothing on
purpose — it is data. Letting it dev-depend on deed-driver puts two published
crates in a dependency cycle, and neither could then be published first.

Measured before choosing rather than assumed: cargo metadata resolves that
cycle without complaint, and cargo publish --dry-run would not have said
otherwise. Deciding it on the dry run's terms is exactly the mistake that costs
a release.

deed-explain keeps its packaging tests, which are about a different bug and
still hold.

Gates

Both break-verified:

CAUGHT   a page showing a program that does not produce its code
CAUGHT   the old window that swallowed the next test's banner
  • every_example_produces_the_code_its_page_is_about reads the committed
    pages, not the tree, so it holds what a reader of the shipped compiler gets
    even if the generator is never run again.
  • a_test_body_ends_before_what_introduces_the_next_one holds the window on a
    fixture with the banner in it.
  • The floor in explain.rs moves 76 → 75 and now records why the lower number
    is the better one, so nobody buys it back with programs that do not produce
    the code.

Checks

cargo fmt, clippy -D warnings, nextest --profile ci (2438 passed, 4
skipped), cargo test --doc --workspace. Regeneration takes about a second.

`deed explain DEED2011` says "there is no range in this language" and printed
this program:

    module a

    fn f() -> Int {
      Int n = 1
      n
    }

That is DEED2010. Forty-three of the eighty-nine pages carrying an example
showed a program that does not produce the code, measured by checking each one
and running its tests.

The example was "the first deed-looking string in a test that mentions this
code", which is a different claim from "a program that produces it". Two
shapes: the extractor read a test from its `#[test]` to the next `#[test]`, so
it swallowed the banner introducing the following test, and every code named in
a banner was offered the previous test's program; and where a test carried two
modules or a passing control arm, the first string was the wrong half.

This is read by `deed explain`, by the `deed_explain` MCP tool and by the error
index the site builds from the same artefact, so an agent asking what a code
means was handed a program about a different one.

The example is now the first candidate that produces the code, asked of the
compiler: checked, and run when the code only appears at run time. Seventy-five
pages carry one and every one is verified; the other twenty-nine carry none.

The generator moved to `crates/deed-driver/tests/explain_pages.rs`. Deciding
this needs a checker, and `deed-explain` depends on nothing on purpose --
making it depend on the compiler to test itself puts two published crates in a
dependency cycle `cargo publish` cannot order. Measured before choosing:
`cargo metadata` resolves such a cycle happily and `--dry-run` would not have
said otherwise, which is the reason to decide it on the real command's terms.

Two gates, both break-verified:

- `every_example_produces_the_code_its_page_is_about` reads the committed
  pages, not the tree, so it holds what a reader gets.
- `a_test_body_ends_before_what_introduces_the_next_one` holds the window.

The floor in `explain.rs` moves from 76 to 75 and now says why a lower number
is the better one.
@onatozmenn
onatozmenn merged commit fcfb84a into main Aug 9, 2026
10 checks passed
@onatozmenn
onatozmenn deleted the an-example-that-produces-the-code branch August 9, 2026 17:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant