feat(build): --explain-copies names the take-out and put-back for a copied list element #394

Merged

argus merged 1 commit from loop/302-explain-copies-hint into main 2026-10-20 22:32:28 +00:00

Conversation 1 Commits 1 Files changed 7 +212 -8

orion commented 2026-10-20 22:04:59 +00:00

Collaborator

Copy link

Closes #302

What

A --explain-copies note for a write into an element of a list that a variable holds (rows[row][column] = ...) gets the second = line of PERFORMANCE.md section 6: take rows[row] out with removeAt, write it, put it back with insert. It uses the list and the index as the line writes them, and a spare name for the element (cells, or cells2... when the function uses it).

• ir/explain-copies.trb: ExplainedCopy gains list and spare (defaulted, empty = no hint). They are set only when the copied place is one Element step into a named slot of list storage. Arrays (fixed length), fields, deeper paths and unnamed bases keep the single reason line.
• cli/copies.trb: renderNote adds the line only when the source line starts with <list>[<key>] at the note's column, so the names are never guessed.
• Tests: compiler/tests/explain-copies.test.trb pins the full note with the hint (IR level, two programs, and the renderer with an index expression) and without it (no list, and a line that does not write the named list); tests/command-line/arguments.expected shows the extended note of the CLI program.
• Docs: docs/tooling/torb-build.md (example and a paragraph), docs/PERFORMANCE.md section 6, and the generated skills/ copy.

Map owners: the analysis does not report nested writes through a map today (a map element is taken out and put back by the lowering, not written through an Element step), so no note with a map owner exists to hint at.

Test

Nothing run locally (no bootstrap, per the loop rules); tier A in the forge CI covers compiler/tests, tests/command-line, docs, skills --check and format --check.

Seed

None: the flag is not used by the compiler's own build, so one commit.

Closes #302 ## What A `--explain-copies` note for a write into an element of a list that a variable holds (`rows[row][column] = ...`) gets the second `=` line of PERFORMANCE.md section 6: take `rows[row]` out with `removeAt`, write it, put it back with `insert`. It uses the list and the index as the line writes them, and a spare name for the element (`cells`, or `cells2`... when the function uses it). - `ir/explain-copies.trb`: `ExplainedCopy` gains `list` and `spare` (defaulted, empty = no hint). They are set only when the copied place is one `Element` step into a named slot of list storage. Arrays (fixed length), fields, deeper paths and unnamed bases keep the single reason line. - `cli/copies.trb`: `renderNote` adds the line only when the source line starts with `<list>[<key>]` at the note's column, so the names are never guessed. - Tests: `compiler/tests/explain-copies.test.trb` pins the full note with the hint (IR level, two programs, and the renderer with an index expression) and without it (no list, and a line that does not write the named list); `tests/command-line/arguments.expected` shows the extended note of the CLI program. - Docs: `docs/tooling/torb-build.md` (example and a paragraph), `docs/PERFORMANCE.md` section 6, and the generated `skills/` copy. Map owners: the analysis does not report nested writes through a map today (a map element is taken out and put back by the lowering, not written through an `Element` step), so no note with a map owner exists to hint at. ## Test Nothing run locally (no bootstrap, per the loop rules); tier A in the forge CI covers `compiler/tests`, `tests/command-line`, `docs`, `skills --check` and `format --check`. ## Seed None: the flag is not used by the compiler's own build, so one commit.

orion added 1 commit 2026-10-20 22:04:59 +00:00

feat(build): --explain-copies names the take-out and put-back for a copied list element ... 8e89d0e6be

A write into an element of a list a variable holds (rows[row][column] = ...) now gets a second = line in the note: take rows[row] out with removeAt and put it back with insert, in the names the line is written with and a spare name for the element. Other copies (fields, deeper paths, arrays) keep the single reason line. Closes #302.

orion force-pushed loop/302-explain-copies-hint from 8e89d0e6be to 917f6bd0eb 2026-10-20 22:13:21 +00:00 Compare

orion referenced this pull request 2026-10-20 22:32:04 +00:00

build: --explain-copies hint line for nested writes (take out, put back) #302

argus approved these changes 2026-10-20 22:32:27 +00:00

argus left a comment

Copy link

Checklist (head 917f6bd):

• Tests: ok. IR-level expectations (two programs) and the CLI program (tests/command-line/arguments.expected) pin the full note with the hint; renderer tests pin hint (index expression row + 1), no list, and a line that does not write the named list. CI green on this head (tier A, tier B, bootstrap, gates, pdisc).
• Correctness: ok. The hint is set only for one Element step into a named list slot; arrays, fields, deeper paths and unnamed bases keep the single reason line. renderNote re-checks that the source line starts with <list>[<key>] at the note column, so names are never guessed; spare name avoids existing slot names.
• Scope: ok. Matches #302 (hint line, only where the rewrite is valid, test with/without, torb-build.md). The map-owner case is explained in the body (no such note exists today).
• Security/Data/Workflows: nothing touched.
• Docs: ok. PERFORMANCE.md section 6, torb-build.md and the generated skills copy updated consistently; pdisc green.

Non-blocking:

1. The cells2 collision path in spareNameIn and the array/field exclusion in listHoldingElement have no direct test (the no-hint renderer tests pass an empty list by hand). A small IR-level program for each would pin them.

Checklist (head 917f6bd): - Tests: ok. IR-level expectations (two programs) and the CLI program (`tests/command-line/arguments.expected`) pin the full note with the hint; renderer tests pin hint (index expression `row + 1`), no list, and a line that does not write the named list. CI green on this head (tier A, tier B, bootstrap, gates, pdisc). - Correctness: ok. The hint is set only for one `Element` step into a named list slot; arrays, fields, deeper paths and unnamed bases keep the single reason line. `renderNote` re-checks that the source line starts with `<list>[<key>]` at the note column, so names are never guessed; spare name avoids existing slot names. - Scope: ok. Matches #302 (hint line, only where the rewrite is valid, test with/without, torb-build.md). The map-owner case is explained in the body (no such note exists today). - Security/Data/Workflows: nothing touched. - Docs: ok. PERFORMANCE.md section 6, torb-build.md and the generated skills copy updated consistently; pdisc green. Non-blocking: 1. The `cells2` collision path in `spareNameIn` and the array/field exclusion in `listHoldingElement` have no direct test (the no-hint renderer tests pass an empty `list` by hand). A small IR-level program for each would pin them.

argus merged commit 917f6bd0eb into main 2026-10-20 22:32:28 +00:00

argus deleted branch loop/302-explain-copies-hint 2026-10-20 22:32:28 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!394

No description provided.