the pre-release sweep: C++ cites architecture by anchor and lint reads it, the arch tools locate instead of quote, the worker heap test measures collection, and the install lists catch up by borisbat · Pull Request #4047 · GaijinEntertainment/daScript

borisbat · 2026-09-16T17:38:56Z

Behavior changes: C and C++ cite architecture sections by anchor and LINT026 checks them; the MCP arch tools return locations instead of text; the strudel worker-heap test measures collection; four install and gate rosters catch up with the tree.

Why. The pre-release sweep before 0.6.4. C++ cited architecture documents by section number - // src/ast/ARCHITECTURE.md sec.2 - a spelling nothing could validate and a renumber silently orphaned. The MCP arch_of/arch_sites tools had eight calls in their whole life: they returned a section's text and lost the coordinates the next step needs. test_worker_heap.das flaked at 10242 KB against a 10 MB bar because it measured the wrong quantity. And a converter, a driver, a license and twelve install GLOBs were missing from the SDK's rules.

What changes.

A // <doc>#<anchor> pointer in a C/C++ // comment is the C++ spelling of the [arch] citation. One scanner (utils/common/arch_citations.das) reads both; the path is root-relative, the root found by walking up from the citing file, so a header under include/ reaches src/'s document, and the folder-tree rule does not bind C++. LINT026 walks C++ both ways; preflight's lint gate hands changed C++ to it; arch-extract reads the pointers so a C++-only-cited section reaches the SDK excerpt. 61 sec.N pointers migrated; 11 headings anchored. A web URL ending in .md#x is not a pointer.
arch_of is a locator: file:line symbol -> doc:first-last #anchor, one line per citation, both spellings. arch_sites gives every anchor its section's line range and searches the C++ homes beyond the document's subtree.
test_worker_heap.das asserts what only a collect produces - the published heap drops between ticks, and its floor holds across two stretches - on the worker's own clock.
modules/dasGLTF/tools/convert.das and utils/aot/main_llvm_aot.das install; the utils/* install GLOBs carry CONFIGURE_DEPENDS; MESHOPTIMIZER joins the bundle smoke's license roster.
The xxd step writes .das.inc with LF (CMake's file(WRITE) emits CRLF on Windows, so its skip-if-unchanged branch never fired there and every build rewrote every .inc); .gitattributes pins *.das.inc to LF.
CHANGELIST.md carries this PR and the previous one (the browser's K-quant dot rides the idot lattice, wasm gets its FMA, and neither the spin window nor the audio mixer pays the host clock #4045).

Observable behavior.

A C++ comment // src/misc/ARCHITECTURE.md#spin-window-clock-stride that names a missing document or anchor is a LINT026 finding at its line; an anchor cited only from C++ is no longer "uncited".
arch_of src/misc/job_que.cpp prints src/misc/job_que.cpp:41 -> src/misc/ARCHITECTURE.md:113-142 #spin-window-clock-stride. arch_sites src/ast/ARCHITECTURE.md#module-scan-manifest lists 22 sites in 10 files across src/ast, src/builtin, src/parser and include/.
On Windows a build no longer rewrites tracked .das.inc files; git status stays clean after a build.
An SDK bundle carries the glTF asset converter, the LLVM object AOT driver, and any utils/* file added since the last configure.

Where to look. The scanner is utils/common/arch_citations.das (collect_arch_pointers); the lint pass is run_arch_pass in utils/lint/main.das; the tools are utils/mcp/tools/arch_of.das and arch_sites.das; the test is tests/strudel_device/test_worker_heap.das; the rule text is skills/comment_style_hygiene.md, ARCHITECTURE_COMMON.md, REVIEW_COMMON.md.

Validation, claims, ledger

Validation

utils/lint/tests/lint026_arch_citations.das: 24 tests, 24 passed. The new test_arch_cpp_pointers plants a C++ source with a resolving pointer, a dangling one (named at its line), an #include, a block comment and two URLs (none fire), a header under include/deep reaching src/ARCHITECTURE.md through the root above both, and a negative control that swaps the anchor away (the pointer fires, the anchor is owed) and back (silent).
tests/strudel_device/test_worker_heap.das: 2 tests, 2 passed, 11.9 s. Behind the bars: three runs on this box, byte-identical - 28 drops per six worker-seconds, floor drift 0 KB, published span 9735 KB.
Pre-push gate --only format,lint,review-md: 3 passed. Lint covers 39 changed files on both rails, which is LINT026 over the real tree with C++ read: every one of the 61 migrated pointers resolves and every one of the 11 new anchors is cited. First run of the gate caught two things this PR then fixed: vendored imgui's GitHub URLs read as pointers (the URL rule), and utils/REVIEW.das refusing a comment that spelled utils/internal/ in a shipped tool.
arch-extract --base src src include: 3 documents, 11 sections, 58 citations from 310 files; src/misc's sec.8 (cited only from C++) and src/ast's sec.4 (cited from include/daScript/ast/ast.h) both land in the excerpt.
The four changed tools compile (-compile-only): utils/lint/main.das, utils/mcp/main.das, utils/internal/arch-extract/main.das, utils/internal/preflight/main.das.
The xxd step, run standalone on modules/dasUnitTest/unit_test.das: "has not been modified. C-array generation is skipped." - the branch that never fired on Windows - and the tracked .inc is byte-identical to git. cmake -P on a two-line file(WRITE "a\nb\n") writes a\r\nb\r\n on this box, which is the defect.
ci/check_shipped_skills.py over the checkout: no finding in skills/mcp_tools.md or skills/comment_style_hygiene.md.
MCP tool usage that motivated the reshape: both trees' mcp_server.log, 7233 tools/call since 2026-05-28 - arch_of 1, arch_sites 7, both inside one 8-day window in this worktree; lint 1598, compile_check 1525, format_file 1055.
CRLF churn check before commit: comm of git diff --name-only with and without --ignore-cr-at-eol is empty.

Claims - stated, not tested

The CONFIGURE_DEPENDS change is asserted from CMake's documented GLOB semantics, not from a before/after install on a stale configure.
MESHOPTIMIZER.LICENSE reaching the bundle root is asserted from the module's existing install rule plus the roster line; the bundle smoke itself runs in CI (bundle_smoke), not here.
test_worker_heap.das's bars (MIN_DROPS = 6, FLOOR_DRIFT_LIMIT = 4 MB) are set from this box's numbers with 5x and 2.5x margins; the darwin Debug runner that flaked the old test has not run the new one yet - CI will.

Not done

The //! reader change (an above-def //! attaching to the def, as typedef already does): 3828 functions' only docstring sits in the position the reader drops, and fio.das's match_glob reads "to be documented" in the generated reference with its //! right above it. A regen-sized sweep, kept out of this PR.
arch_sites still walks the .das census from the document's own subtree only; the C++ homes are added on top. A .das citer outside the subtree is a LINT026 finding by rule, so the census is complete for a lint-clean tree.
utils/benchctl/tests/ remains red on Windows (bin/daslang spelled where get_host_binary() is, and spawn_process throwing on a failed CreateProcess where POSIX reports through the exit code) - a builtin-contract ruling, noted in the browser's K-quant dot rides the idot lattice, wasm gets its FMA, and neither the spin window nor the audio mixer pays the host clock #4045.

Copilot

🟡 Changes recommended

The new C/C++ pointer scanner currently omits .c sources, so “C and C++” pointer citations are not fully supported as described.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR is a pre-release cleanup/sweep ahead of 0.6.4 that (1) migrates C/C++ “architecture pointers” from sec.N to validated #anchor citations (checked by LINT026), (2) reshapes MCP arch_* tools to return locations/ranges instead of quoting document text, (3) stabilizes the Strudel worker heap test by measuring actual collection signals, and (4) updates install/bundle rosters and Windows line-ending behavior for generated .das.inc files.

Changes:

Implement anchor-based architecture citation scanning across .das and C/C++ comment pointers; update lint + MCP tools + docs accordingly.
Update arch_of/arch_sites outputs to be coordinate-based (line ranges) and extend arch_sites census beyond the document subtree into C++ roots.
Fix test_worker_heap.das to assert collection behavior (drops + floor stability) using worker time; update install/gate rosters and enforce LF output for generated .das.inc.

File summaries

File	Description
utils/mcp/tools/arch_sites.das	Use `cited_symbol`, show section line ranges, and extend census to scan C++ roots (src/include/modules/*/src).
utils/mcp/tools/arch_of.das	Change output from quoted section text to a locator line per citation (doc path + line span).
utils/mcp/tools/arch_common.das	Extend scan helpers with C/C++ roots and add `cited_symbol` wrapper for non-.das sources.
utils/mcp/registry_das.das	Update MCP tool descriptions/schemas to reflect locator-based `arch_of` and expanded `arch_sites`.
utils/lint/tests/lint026_arch_citations.das	Add tests covering C++ `// <doc>.md#<anchor>` pointer scanning and failure modes.
utils/lint/main.das	Extend LINT026 scan to include C/C++ sources and short-circuit on `.md#` for pointer-only files.
utils/internal/preflight/main.das	Track changed headers explicitly and include changed C++/headers in the lint gate inputs.
utils/internal/arch-extract/main.das	Include `.md#` pointer scanning trigger and broaden file scan to C/C++ sources.
utils/common/arch_citations.das	Add C/C++ pointer citation parsing and shared resolution behavior for lint/tools/extract.
tests/strudel_device/test_worker_heap.das	Replace “peak-base” heuristic with drop-count + floor-drift assertions on worker clock.
src/parser/parser_impl.cpp	Migrate architecture pointers from `sec.N` to `#anchor`.
src/misc/job_que.cpp	Migrate architecture pointers from `sec.N` to `#anchor`.
src/misc/ARCHITECTURE.md	Add `{#anchor}` to the cited section heading (spin window).
src/builtin/REVIEW.md	Update review rule text to describe `#anchor` pointer style and LINT026 behavior.
src/builtin/module_builtin_rtti.cpp	Migrate pointer comment to `#anchor`.
src/builtin/module_builtin_fio.cpp	Migrate pointer comments to `#anchor`.
src/builtin/module_builtin_debugger.cpp	Migrate pointer comment to `#anchor`.
src/builtin/module_builtin_dasbind.cpp	Migrate pointer comments to `#anchor`.
src/builtin/module_builtin_ast.cpp	Migrate pointer comments to `#anchor`.
src/builtin/module_builtin_ast_serialize.cpp	Migrate pointer comments to `#anchor`.
src/builtin/ARCHITECTURE.md	Add `{#anchor}` suffixes to headings cited from C++ and tools.
src/ast/dyn_modules.cpp	Migrate pointer comments to `#anchor`.
src/ast/ast_simulate.cpp	Migrate pointer comments to `#anchor`.
src/ast/ast_parse.cpp	Migrate pointer comments to `#anchor`.
src/ast/ast_module.cpp	Migrate pointer comments to `#anchor`.
src/ast/ARCHITECTURE.md	Add `{#anchor}` suffixes to headings used by migrated citations.
skills/mcp_tools.md	Update documentation of `arch_of`/`arch_sites` to match new locator output and C/C++ pointers.
skills/comment_style_hygiene.md	Update rule text to prefer `// <doc>#<anchor>` pointers over `sec.N` for C++.
REVIEW_COMMON.md	Extend audit rule to include C++ under `// <doc>#<anchor>` pointers.
modules/dasLLVM/ARCHITECTURE_TARGET_FEATURES.md	Minor wording adjustment around numbered sections and stability.
modules/dasImgui/src/module_imgui_app.cpp	Migrate module architecture pointers from `sec.N` to `#anchor`.
modules/dasGLTF/CMakeLists.txt	Install the glTF asset converter script into the SDK bundle.
include/daScript/simulate/aot_builtin_ast.h	Migrate pointer comment to `#anchor`.
include/daScript/ast/dyn_modules.h	Migrate pointer comment to `#anchor`.
include/daScript/ast/ast.h	Migrate pointer comments to `#anchor`.
include/daScript/ast/ast_serializer.h	Migrate pointer comment to `#anchor`.
include/daScript/ast/ast_handle.h	Migrate pointer comment to `#anchor`.
CMakeXxdImpl.txt	Generate `.inc` with LF consistently via `configure_file(... NEWLINE_STYLE LF)` to avoid Windows rewrite churn.
CMakeLists.txt	Install additional tools; add `CONFIGURE_DEPENDS` to multiple `file(GLOB ...)` install lists.
CLAUDE.md	Update `[arch]` guidance to include C++ pointer spelling and locator-based MCP behavior.
ci/smoke_test_bundle.sh	Add MESHOPTIMIZER license to bundle smoke license roster.
CHANGELIST.md	Record this PR and the prior PR’s changes in the changelist.
ARCHITECTURE_COMMON.md	Update the repo-wide architecture-citation contract to include C/C++ pointer citations.
.gitattributes	Pin `*.das.inc` to LF to prevent autocrlf-based churn/accidental commits.

Review details

Files reviewed: 44/44 changed files
Comments generated: 1
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

🔵 Needs a closer look

It changes lint semantics/tooling + SDK install behavior across many subsystems, so it needs a final human review pass even though most changes look well-scoped.

Review details

Files reviewed: 44/44 changed files
Comments generated: 2
Review effort level: Lite

Copilot

🟡 Changes recommended

Preflight’s changed-file classification currently omits some real C/C++ source extensions (e.g. .c), which can prevent the intended LINT026 arch-pointer validation from running on those diffs.

Get a fresh assessment by requesting another Copilot review.

Review details

Files reviewed: 44/44 changed files
Comments generated: 1
Review effort level: Lite

Copilot

🟡 Changes recommended

arch_sites currently de-duplicates cross-root matches by file:line, which can drop distinct citations that share a line (e.g., multiple pointers in one // comment) when scan roots overlap.

Get a fresh assessment by requesting another Copilot review.

Review details

Files reviewed: 44/44 changed files
Comments generated: 1
Review effort level: Lite

Copilot

🟡 Changes recommended

The C/C++ citation scanner’s suffix allowlist omits .inc, so LINT026 and the MCP arch tools can silently miss // <doc>.md#<anchor> pointers placed in .inc include files.

Get a fresh assessment by requesting another Copilot review.

Review details

Files reviewed: 44/44 changed files
Comments generated: 1
Review effort level: Lite

Copilot

🔵 Needs a closer look

It changes multiple enforcement/tooling layers (lint, MCP tools, preflight, install rules, tests) across many subsystems, so it warrants a final human pass despite only a small concrete issue found.

Review details

Files reviewed: 44/44 changed files
Comments generated: 1
Review effort level: Lite

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

🔵 Needs a closer look

The changes are cross-cutting (lint semantics, MCP tools, tests, CMake install behavior, and widespread C/C++ doc pointers), so they warrant final human review despite only minor actionable nits.

Review details

Files reviewed: 45/45 changed files
Comments generated: 1
Review effort level: Lite

…s it, the arch tools locate instead of quote, the worker heap test measures collection, and the install lists catch up A C or C++ source cites an architecture section the way a .das declaration does now. The spelling is `// <doc>#<anchor>` inside a `//` comment - the kept-set pointer the comment rulebook already named, with the anchor in place of `sec.N`, a number nothing could check. One scanner (utils/common/arch_citations.das) reads both spellings: a .das file for its [arch(at=...)] annotations, a C++ file for its pointers, whose path is root-relative and whose root is the first folder up from the citing file the path exists under, so a header in include/ reaches the src/ document that owns its mechanism and a planted fixture tree resolves inside itself; the folder-tree rule does not bind C++ for the same reason. A URL to a document on the web is not a pointer - a scheme's walk-back leaves a leading slash, a bare host a dotted first segment - which imgui's vendored sources proved on the first run. LINT026 walks C++ in both directions, and preflight's lint gate hands changed .cpp and headers to it; arch-extract reads the pointers, so a section cited only from C++ lands in the SDK excerpt (src/misc sec.8 has no other citer); the sixty-one `sec.N` pointers are rewritten to anchors and the eleven sections they name carry `{#anchor}` headings. The fixture plants a C++ source with a resolving pointer, a dangling one, an #include, a block comment and two URLs, a header under include/deep reaching src/ through the root above both, and a negative control that swaps the anchor away and back. `arch_of` and `arch_sites` answered a question nobody asked: eight calls in their whole life, against thousands for lint and compile_check, because `arch_of` dumped the section's text and lost the coordinates the next step - a Read or an Edit of that section - needs, while `arch_sites` was a grep. `arch_of` is a locator now, one line per citation, `<file>:<line> <symbol> -> <doc>:<first>-<last> #<anchor>`, both spellings; `arch_sites` gives each anchor its section's line range and reads the C++ homes (src/, include/, every module's src/) beyond the document's own subtree, since a C++ citer may sit anywhere in them - the census of src/ast's manifest section grew from 11 sites to 22 in 10 files. CLAUDE.md sends a reader to the document first and to the tools for where. tests/strudel_device/test_worker_heap.das flaked at 10242 KB against a 10 MB bar, on darwin Debug. The number the strudel worker publishes is its heap BEFORE the tick's collect, so it reads live set plus that tick's garbage, and a tick's garbage runs from hundreds of kilobytes to ten megabytes: on an idle 64-core box the published number spans 9.7 MB while its floor moves 0 KB. `peak - base` measured the burstiness of a pattern query, not collection, and the bar was widened 2 -> 5 -> 10 MB in one day chasing it. The test now asserts the two things only a collect produces - a published number lower than the one before it (28 per six worker-seconds here; zero without collection, which test_worker_no_gc.das pins) and a floor that holds across two stretches (uncollected grows ~10 MB a stretch) - with warm-up and the stretches on the worker's own clock, so a slow box warms up before it is measured. The install lists: modules/dasGLTF/tools/convert.das, the asset converter the README documents, and utils/aot/main_llvm_aot.das, the LLVM object AOT driver, ship; the twelve utils/* install GLOBs carry CONFIGURE_DEPENDS, so a file added after a box's last configure lands in its bundle; MESHOPTIMIZER.LICENSE joins the bundle smoke's roster (the module is default-on and its notice installed, and the gate that exists to notice a silently skipped install rule did not list it). CMake's file(WRITE) emits the platform newline, so on Windows the xxd step rewrote every tracked .das.inc with CRLF on every build - its "not modified, skipped" branch could never fire there - and `git add -A` swept two of them into the last PR twice; the step pins LF through configure_file, and .gitattributes pins *.das.inc so a checkout cannot flip it back. CHANGELIST.md carries this and the previous PR. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

It touches cross-cutting correctness gates (lint + MCP tooling + build/install + tests) across many subsystems, so it warrants a final human review despite no specific defects found in this pass.

Review details

Files reviewed: 45/45 changed files
Comments generated: 0 new
Review effort level: Lite

Copilot AI lite review requested due to automatic review settings September 16, 2026 17:39

borisbat force-pushed the bbatkin/pre-release-sink branch from 091b993 to c647e2b Compare September 16, 2026 17:39

Copilot started reviewing on behalf of borisbat September 16, 2026 17:39 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread utils/common/arch_citations.das Outdated

Copilot AI review requested due to automatic review settings September 16, 2026 17:49

borisbat force-pushed the bbatkin/pre-release-sink branch from c647e2b to eb58932 Compare September 16, 2026 17:49

Copilot started reviewing on behalf of borisbat September 16, 2026 17:50 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread tests/strudel_device/test_worker_heap.das

Comment thread utils/mcp/tools/arch_sites.das

Copilot AI review requested due to automatic review settings September 16, 2026 17:58

borisbat force-pushed the bbatkin/pre-release-sink branch from eb58932 to e4f970a Compare September 16, 2026 17:58

Copilot started reviewing on behalf of borisbat September 16, 2026 17:59 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread utils/internal/preflight/main.das Outdated

Copilot AI review requested due to automatic review settings September 16, 2026 18:08

borisbat force-pushed the bbatkin/pre-release-sink branch from e4f970a to bafaf1a Compare September 16, 2026 18:08

Copilot started reviewing on behalf of borisbat September 16, 2026 18:08 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread utils/mcp/tools/arch_sites.das

Copilot AI review requested due to automatic review settings September 16, 2026 18:14

borisbat force-pushed the bbatkin/pre-release-sink branch from bafaf1a to 51d7f65 Compare September 16, 2026 18:14

Copilot started reviewing on behalf of borisbat September 16, 2026 18:15 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread utils/common/arch_citations.das Outdated

Copilot AI review requested due to automatic review settings September 16, 2026 18:21

borisbat force-pushed the bbatkin/pre-release-sink branch from 51d7f65 to 31855e4 Compare September 16, 2026 18:21

Copilot started reviewing on behalf of borisbat September 16, 2026 18:21 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread modules/dasLLVM/ARCHITECTURE_TARGET_FEATURES.md

Copilot AI review requested due to automatic review settings September 16, 2026 18:34

borisbat force-pushed the bbatkin/pre-release-sink branch from 31855e4 to 88a8001 Compare September 16, 2026 18:34

Copilot AI reviewed Sep 16, 2026

borisbat requested a lite review from Copilot September 16, 2026 18:34

Copilot started reviewing on behalf of borisbat September 16, 2026 18:34 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

Comment thread utils/mcp/registry_das.das Outdated

borisbat force-pushed the bbatkin/pre-release-sink branch from 88a8001 to ffdfe7b Compare September 16, 2026 18:39

Copilot AI review requested due to automatic review settings September 16, 2026 18:39

Copilot started reviewing on behalf of borisbat September 16, 2026 18:40 View session

Copilot AI reviewed Sep 16, 2026

View reviewed changes

borisbat merged commit 4ed51b7 into master Sep 16, 2026
38 checks passed

borisbat deleted the bbatkin/pre-release-sink branch September 16, 2026 19:40

Uh oh!

Conversation

borisbat commented Sep 16, 2026

Validation

Claims - stated, not tested

Not done

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants