From 6b517db158cc08bdd51bf5994bc1f1a8e6ab8394 Mon Sep 17 00:00:00 2001 From: chasse20 Date: Fri, 13 Nov 2026 23:31:06 -0500 Subject: [PATCH 1/6] Add Rust code style guidelines --- AGENTS.md | 2 +- CODE_STYLE.md | 77 ++++++++++++++++++++++++++++ docs/helpful-pr-review-guidelines.md | 36 +------------ 3 files changed, 80 insertions(+), 35 deletions(-) create mode 100644 CODE_STYLE.md diff --git a/AGENTS.md b/AGENTS.md index 2d250fe..9887447 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,7 +72,7 @@ repository's infrastructure (xtask, automation, packaging, docking, theme) was c The goal is full parity with the professional node-based material workflow (the same panels, menus, node library, parameters, shortcuts and file conventions) with better performance, every feature drivable by agents, and builds for Windows, macOS, Linux, FreeBSD and the web. Read this -file first, then `docs/`. +file first, then [CODE_STYLE.md](CODE_STYLE.md) before editing or reviewing code, then `docs/`. ## 1. Orientation (5 minutes) diff --git a/CODE_STYLE.md b/CODE_STYLE.md new file mode 100644 index 0000000..86dcc05 --- /dev/null +++ b/CODE_STYLE.md @@ -0,0 +1,77 @@ +# Code style + +Style conventions for MaterialCraft's Rust code. +Read alongside [AGENTS.md](AGENTS.md) for repository requirements. + +## Naming and Rust conventions + +- Use descriptive names that explain purpose; include units where useful. Avoid misleading names + and abbreviations whose meaning is unclear in context. +- Follow Rust naming conventions: `snake_case` for functions, variables, fields, and modules; + `UpperCamelCase` for types and traits; `SCREAMING_SNAKE_CASE` for constants and statics. +- Conventional Rust names are not cryptic abbreviations. Keep names such as `fmt`, `iter`, `len`, + `args`, `err`, `id`, and `ui` when their meaning is clear. Do not expand them just to make them + longer. +- Keep standard file and directory names such as `lib.rs`, `main.rs`, `mod.rs`, `src`, `tests`, + `examples`, and `benches`. Rust keywords such as `mut`, `ref`, `impl`, and `mod` are language + syntax, not naming problems. +- Short names are appropriate in a clear local context: `i` for an index, `x` and `y` for + coordinates, `w` and `h` for image dimensions, and conventional generic parameters such as `T`. + Use more descriptive names when scope or ambiguity makes those hard to follow. + +## Magic numbers + +- Give non-obvious limits, thresholds, sizes, and tuning values descriptive named constants + instead of leaving unexplained numeric literals in the code. +- Name constants for their purpose, with units where useful, rather than for their literal value. + Keep them in the narrowest useful scope. +- Reuse an existing constant when it represents the same concept. Equal numeric values alone do + not mean two concepts should share a constant. +- Explain the origin or rationale of non-obvious coefficients and tolerances in a short comment. + Use standard library constants for standard mathematical values. +- Keep literals inline when their role is clear, such as zero initialization, incrementing by one, + or dividing by two to find a midpoint. Do not introduce names such as `ZERO` or `TWO` that add + no meaning. +- Apply this guidance to tests too; clear fixture values and expected results can remain literal. + +## Formatting and spacing + +- Let `cargo fmt` and the repository's [rustfmt.toml](rustfmt.toml) handle mechanical formatting. + Do not introduce a competing indentation or line-wrapping convention. +- Use one blank line between distinct logical steps: input preparation, validation, computation, + mutation, and result construction. +- Keep closely related statements together. Do not add a blank line after every declaration or + fragment a single operation with extra spacing. +- Put a blank line after a multiline early-exit guard, including `if` and `let ... else`, before + the next statement. +- Put a blank line before a comment introducing a new step, with no blank line between the + comment and the code it explains. +- Keep documentation and attributes attached to their declarations. +- Separate function definitions with one blank line. Avoid extra empty lines just inside braces + or between every field, argument, or statement. +- In tests, separate preparation, action, and verification with blank lines when those phases + are distinct; keep related assertions together. + +## Source organization + +- Give each struct or enum its own source file, with its implementation beside it. Use the full + type name in `snake_case`, such as `mesh_curvature_settings.rs` for `MeshCurvatureSettings`. +- Preserve conventional crate roots and module entry points such as `lib.rs`, `main.rs`, and + `mod.rs`. Follow the command and node module placement required by `AGENTS.md`. +- Prefer singular folder names for new domain modules, such as `map`, `setting`, or `tracing`. + Keep standard Rust directories and repository-mandated paths unchanged. +- Group related types into focused modules rather than collecting unrelated types in one large file. +- Apply these preferences to new types and source organization changes within scope. Do not + reorganize unrelated existing code to enforce them. + +## Comments + +- Explain intent or a non-obvious constraint rather than narrating the code. +- Use short `//` comments. Avoid block comments and wrapped prose in ordinary implementation + comments; adjacent comment lines should each express a concise point. +- Do not add trailing punctuation to ordinary code comments. +- Preserve explanations of guards and invariants. Remove stale or redundant comments without + losing necessary rationale. +- API documentation, required license headers, and examples may use conventional multiline + formatting and punctuation. +- Apply the same comment guidance to production code and tests. diff --git a/docs/helpful-pr-review-guidelines.md b/docs/helpful-pr-review-guidelines.md index 098b6ae..fbe4f69 100644 --- a/docs/helpful-pr-review-guidelines.md +++ b/docs/helpful-pr-review-guidelines.md @@ -8,7 +8,7 @@ Use these preferences when reviewing and improving a PR. Follow repository requi - Review-only requests call for findings; requests to fix or improve also authorize focused local edits - A review may conclude that no changes are needed. If the PR meets the applicable standards and no actionable issues are found, leave it unchanged. Do not invent findings, add unnecessary tests, or make edits merely to produce a diff. Report what was checked and any remaining validation limits - Apply all review standards across the entire affected method, including existing code and relevant tests -- Complete naming, spacing, and comment cleanup throughout it +- Read and apply [CODE_STYLE.md](../CODE_STYLE.md) throughout that scope - Make additional correctness or performance changes when supported by evidence and appropriate validation - Separate substantial changes that address an independent problem, explaining why - Apply the same scope to standalone functions and inspect relevant callers when verifying behavior @@ -27,6 +27,7 @@ Use these preferences when reviewing and improving a PR. Follow repository requi ## Optimization and simplicity - Prefer the smallest complete solution that is efficient and easy to understand +- Keep control flow direct and share repeated logic when it makes the code simpler - Look for repeated calculations, expensive iterations, unnecessary allocations, and redundant data access - For loops, batches, and streaming operations, trace allocations and buffer lifetimes across multiple iterations, including outputs retained from earlier iterations. Identify work that belongs once per operation rather than once per item, using the full selection when making retention decisions - Consider caching, batching, and parallelism when measurements justify their complexity and memory cost @@ -35,39 +36,6 @@ Use these preferences when reviewing and improving a PR. Follow repository requi - Check what the compiler already optimizes before replacing clear arithmetic with micro-optimizations - Avoid speculative optimization, unnecessary dependencies, and abstractions that add more code than clarity -## Clarity, naming, and spacing - -- Clean up the functions or methods being changed and their relevant tests within the scope above -- Use descriptive names that explain purpose; include units where useful -- Avoid cryptic abbreviations, misleading names, and unexplained production constants -- Keep control flow direct and share repeated logic when it makes the code simpler -- Use a single blank line to separate logical steps, such as input preparation, validation, computation, mutation, and result construction, when those steps are distinct -- Keep closely related statements together; avoid spacing that fragments a single operation or inserts a blank line after every declaration -- Put a blank line after a multiline early-exit guard, including `if` and `let ... else`, before the next statement -- Keep comments attached to the code they explain; put a blank line before a comment introducing a new step, with no blank line between the comment and that step -- Keep documentation and attributes attached to their declarations -- Separate function definitions with one blank line; avoid extra empty lines immediately inside braces or between every field, argument, or statement -- Group tests into preparation, action, and verification with blank lines where those phases are distinct; keep related assertions together -- Apply this spacing consistently throughout affected functions, methods, and tests, and follow the repository's formatter for mechanical formatting - -## Source organization - -- Keep each class, enum, or struct in its own source file, with its implementation beside it -- Spell out the full type name in the filename; use the language's filename convention, such as `mesh_curvature_settings.rs` for `MeshCurvatureSettings` in Rust -- Use singular folder names, such as `map`, `setting`, or `tracing` -- Group related types into focused modules and share helpers where useful without collecting unrelated types into one large file -- Apply these preferences to new types and source organization changes within scope; follow mandatory repository layout rules and leave unrelated existing structure alone - -## Comments - -- Use short, single-line comments; adjacent comment lines should each express a concise point -- Avoid block comments and wrapped prose in ordinary implementation comments -- Explain intent or a non-obvious constraint rather than narrating the code -- No trailing punctuation on ordinary code comments -- Preserve explanations of guards and invariants; remove stale or redundant comments without losing necessary rationale -- API documentation, required license headers, and examples may use their conventional multiline formatting and punctuation -- Apply these standards to both production code and tests - ## Validation and reporting - Run relevant tests and required repository checks with the project's expected toolchain From 9ac3a142f5ed260bc4870deeb0eeb2c802c5416f Mon Sep 17 00:00:00 2001 From: chasse20 Date: Fri, 13 Nov 2026 23:37:10 -0500 Subject: [PATCH 2/6] Restore original AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9887447..2d250fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,7 +72,7 @@ repository's infrastructure (xtask, automation, packaging, docking, theme) was c The goal is full parity with the professional node-based material workflow (the same panels, menus, node library, parameters, shortcuts and file conventions) with better performance, every feature drivable by agents, and builds for Windows, macOS, Linux, FreeBSD and the web. Read this -file first, then [CODE_STYLE.md](CODE_STYLE.md) before editing or reviewing code, then `docs/`. +file first, then `docs/`. ## 1. Orientation (5 minutes) From bb7434478ce9cf0c402eb7073181efb8cf76331e Mon Sep 17 00:00:00 2001 From: Chris Hassebrook Date: Sat, 14 Nov 2026 02:52:48 -0500 Subject: [PATCH 3/6] Matching CI to TextureCraft (#222) * ci: port TextureCraft verification improvements * fix: keep CI green on stable Rust --- .github/workflows/ci.yml | 1 - Cargo.toml | 7 +++++++ crates/automation/src/security.rs | 2 +- crates/formats/src/dds_image.rs | 2 +- crates/formats/src/image.rs | 2 +- crates/geom/src/mesh.rs | 8 ++++---- crates/nodes/src/atomic/text.rs | 2 +- crates/render/src/preview.rs | 2 +- crates/ui-egui/src/view2d.rs | 2 +- crates/ui-egui/tests/snapshot.rs | 6 +++--- docs/testing-ci.md | 34 +++++++++++++++++++++++++++---- xtask/src/main.rs | 6 ++++-- 12 files changed, 54 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3c0e54a..f4b3c10 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,7 +24,6 @@ jobs: # Same craft-fonts commit as release.yml. craft-fonts-ref: 3d9ab3a132ed0eff457e424226a435a901da30d3 os: '["ubuntu-24.04","windows-latest"]' - toolchain: "1.96.0" # xtask ci runs cargo test (including doctests), not cargo nextest. tools: "" packages: >- diff --git a/Cargo.toml b/Cargo.toml index 60799a5..a5be53c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -136,6 +136,13 @@ opt-level = 1 lto = "thin" codegen-units = 1 +# Fast optimized verification: each test executable otherwise repeats cross-crate LTO +# `false` keeps thin LTO within each crate; release packaging keeps the profile above +[profile.verify] +inherits = "release" +lto = false +codegen-units = 16 + [profile.wasm-release] inherits = "release" opt-level = "s" diff --git a/crates/automation/src/security.rs b/crates/automation/src/security.rs index 33040fe..fb716ee 100644 --- a/crates/automation/src/security.rs +++ b/crates/automation/src/security.rs @@ -179,7 +179,7 @@ pub struct Permit(Arc); impl ConnectionLimiter { pub fn try_acquire(&self, max: usize) -> Option { - self.0.fetch_update(Ordering::AcqRel, Ordering::Acquire, |n| (n < max).then_some(n + 1)).ok().map(|_| Permit(self.0.clone())) + self.0.try_update(Ordering::AcqRel, Ordering::Acquire, |n| (n < max).then_some(n + 1)).ok().map(|_| Permit(self.0.clone())) } } diff --git a/crates/formats/src/dds_image.rs b/crates/formats/src/dds_image.rs index e9befcb..cba769b 100644 --- a/crates/formats/src/dds_image.rs +++ b/crates/formats/src/dds_image.rs @@ -14,7 +14,7 @@ pub(crate) fn decode(bytes: &[u8], linear: bool) -> Result { dds::ImageViewMut::new(bytemuck::cast_slice_mut(&mut data), size, dds::ColorFormat::RGBA_F32).ok_or_else(|| error("Invalid DDS dimensions".into()))?; decoder.read_surface(view).map_err(|e| error(e.to_string()))?; if !linear && decoder.format().precision() != dds::Precision::F32 { - for pixel in data.chunks_exact_mut(4) { + for pixel in data.as_chunks_mut::<4>().0 { for value in pixel.iter_mut().take(3) { *value = srgb_to_linear(*value); } diff --git a/crates/formats/src/image.rs b/crates/formats/src/image.rs index 3f84054..f3fabdd 100644 --- a/crates/formats/src/image.rs +++ b/crates/formats/src/image.rs @@ -46,7 +46,7 @@ pub fn decode(bytes: &[u8], linear: bool) -> Result { let mut data = img.into_rgba32f().into_raw(); if !(float || linear) { - for px in data.chunks_exact_mut(4) { + for px in data.as_chunks_mut::<4>().0 { for c in px.iter_mut().take(3) { *c = srgb_to_linear(*c); } diff --git a/crates/geom/src/mesh.rs b/crates/geom/src/mesh.rs index 025de8b..9ef98bf 100644 --- a/crates/geom/src/mesh.rs +++ b/crates/geom/src/mesh.rs @@ -123,7 +123,7 @@ impl Mesh { /// Area-weighted smooth normals over the index buffer. pub fn compute_normals(&mut self) { let mut n = vec![Vec3::ZERO; self.positions.len()]; - for t in self.indices.chunks_exact(3) { + for t in self.indices.as_chunks::<3>().0 { let (a, b, c) = (t[0] as usize, t[1] as usize, t[2] as usize); let (Some(pa), Some(pb), Some(pc)) = (self.positions.get(a), self.positions.get(b), self.positions.get(c)) else { continue }; let face = (*pb - *pa).cross(*pc - *pa); @@ -161,7 +161,7 @@ impl Mesh { fn simple_tangents(&mut self) { let mut acc = vec![Vec3::ZERO; self.positions.len()]; - for t in self.indices.chunks_exact(3) { + for t in self.indices.as_chunks::<3>().0 { let (a, b, c) = (t[0] as usize, t[1] as usize, t[2] as usize); let (Some(pa), Some(pb), Some(pc)) = (self.positions.get(a), self.positions.get(b), self.positions.get(c)) else { continue }; let (Some(ua), Some(ub), Some(uc)) = (self.uvs.get(a), self.uvs.get(b), self.uvs.get(c)) else { continue }; @@ -211,7 +211,7 @@ impl Mesh { } } let mut shared = vec![false; self.positions.len()]; - for (_, tri) in self.indices.chunks_exact(3).enumerate().filter(|(t, _)| !is_mine.get(*t).copied().unwrap_or(false)) { + for (_, tri) in self.indices.as_chunks::<3>().0.iter().enumerate().filter(|(t, _)| !is_mine.get(*t).copied().unwrap_or(false)) { for v in tri { if let Some(s) = shared.get_mut(*v as usize) { *s = true; @@ -307,7 +307,7 @@ impl Mesh { (m.positions.len() - 1) as u32 }) }; - for t in self.indices.chunks_exact(3) { + for t in self.indices.as_chunks::<3>().0 { if t.iter().any(|&i| i as usize >= self.positions.len()) { continue; } diff --git a/crates/nodes/src/atomic/text.rs b/crates/nodes/src/atomic/text.rs index e914055..84088c4 100644 --- a/crates/nodes/src/atomic/text.rs +++ b/crates/nodes/src/atomic/text.rs @@ -104,7 +104,7 @@ fn glyph(c: char) -> &'static str { fn strokes(s: &str) -> impl Iterator> + '_ { s.split(' ') .filter(|t| !t.is_empty()) - .map(|t| t.as_bytes().chunks_exact(2).map(|p| [p[0].saturating_sub(b'0') as f32, p[1].saturating_sub(b'0') as f32]).collect()) + .map(|t| t.as_bytes().as_chunks::<2>().0.iter().map(|p| [p[0].saturating_sub(b'0') as f32, p[1].saturating_sub(b'0') as f32]).collect()) } /// Longest text drawn (an allocation cap) diff --git a/crates/render/src/preview.rs b/crates/render/src/preview.rs index a7fca3b..7ba30ba 100644 --- a/crates/render/src/preview.rs +++ b/crates/render/src/preview.rs @@ -115,7 +115,7 @@ impl Scene { // Normals of the displaced surface, shared per spot so seams don't show let moved = |i: u32| mesh.positions.get(i as usize).zip(offsets.get(i as usize)).map(|(p, o)| *p + *o); let mut face_sums: HashMap<[i32; 3], Vec3> = HashMap::new(); - for triangle in mesh.indices.chunks_exact(3) { + for triangle in mesh.indices.as_chunks::<3>().0 { let (Some(a), Some(b), Some(c)) = (moved(triangle[0]), moved(triangle[1]), moved(triangle[2])) else { continue }; let face = (b - a).cross(c - a); for spot in triangle.iter().filter_map(|&i| spots.get(i as usize)) { diff --git a/crates/ui-egui/src/view2d.rs b/crates/ui-egui/src/view2d.rs index 33d4c11..e65308b 100644 --- a/crates/ui-egui/src/view2d.rs +++ b/crates/ui-egui/src/view2d.rs @@ -24,7 +24,7 @@ const BINS: usize = 64; /// Histograms of the displayed 8-bit values: one for gray or isolated channels, else R, G and B. fn histogram(px: &[u8], channels: usize) -> Vec<[u32; BINS]> { let mut h = vec![[0u32; BINS]; channels]; - for p in px.chunks_exact(4) { + for p in px.as_chunks::<4>().0 { for (c, bins) in h.iter_mut().enumerate() { bins[p[c] as usize * BINS / 256] += 1; } diff --git a/crates/ui-egui/tests/snapshot.rs b/crates/ui-egui/tests/snapshot.rs index 5a07eef..9ef06c6 100644 --- a/crates/ui-egui/tests/snapshot.rs +++ b/crates/ui-egui/tests/snapshot.rs @@ -1468,14 +1468,14 @@ fn material_assignment_previews_outputs_and_survives_function_editing() { assert_eq!(harness.state().session.material_maps()[0].0, "baseColor"); let red_frame = harness.state().view3d.shown.clone().unwrap(); assert_ne!(before.2, red_frame.2, "assignment must invalidate the rendered frame"); - let red_pixels = red_frame.2.chunks_exact(4).filter(|pixel| u16::from(pixel[0]) > u16::from(pixel[1]) + 30).count(); + let red_pixels = red_frame.2.as_chunks::<4>().0.iter().filter(|pixel| u16::from(pixel[0]) > u16::from(pixel[1]) + 30).count(); assert!(red_pixels > 100, "the rendered mesh must show the assigned red image"); save(&mut harness, &directory, "material-assigned-red"); harness.state_mut().run("graph.node.param", json!({"id": source, "param": "color", "value": [0.02, 0.04, 0.8, 1.0]})).unwrap(); settle(&mut harness, 45); let blue_frame = harness.state().view3d.shown.clone().unwrap(); - let blue_pixels = blue_frame.2.chunks_exact(4).filter(|pixel| u16::from(pixel[2]) > u16::from(pixel[0]) + 30).count(); + let blue_pixels = blue_frame.2.as_chunks::<4>().0.iter().filter(|pixel| u16::from(pixel[2]) > u16::from(pixel[0]) + 30).count(); assert!(blue_pixels > 100, "edits must refresh the assigned material"); assert_ne!(red_frame.2, blue_frame.2); save(&mut harness, &directory, "material-assigned-blue"); @@ -1578,6 +1578,6 @@ fn explorer_inputs_and_graph_drop_share_labels_and_material_assignment() { let binding = &harness.state().session.material_preview.channels[&MaterialChannel::BaseColor]; assert_eq!((binding.graph, binding.node), (0, NodeId(output))); let frame = &harness.state().view3d.shown.as_ref().unwrap().2; - assert!(frame.chunks_exact(4).filter(|pixel| u16::from(pixel[0]) > u16::from(pixel[1]) + 30).count() > 100); + assert!(frame.as_chunks::<4>().0.iter().filter(|pixel| u16::from(pixel[0]) > u16::from(pixel[1]) + 30).count() > 100); save(&mut harness, &directory, "graph-dropped-on-material"); } diff --git a/docs/testing-ci.md b/docs/testing-ci.md index 34bff0a..ccedbde 100644 --- a/docs/testing-ci.md +++ b/docs/testing-ci.md @@ -12,6 +12,31 @@ Run a feature module with a test-name filter, for example: cargo test -p materialcraft-engine --test it graph_edit:: ``` +For faster optimized local verification, run the same workspace tests and doctests +with the `verify` profile: + +```sh +cargo test --workspace --profile verify +``` + +`verify` inherits the release profile's optimization level and runtime checks, but +uses 16 codegen units and `lto = false`. Cargo retains thin LTO within each crate +without repeating cross-crate LTO for every test executable. The existing test +selection and ignore attributes still apply. Keep the target directory between +runs so Cargo can reuse unchanged build artifacts. + +To compile the normal application binaries alongside the test binaries before +running them: + +```sh +cargo build --workspace --bins --tests --profile verify +cargo test --workspace --profile verify +``` + +This profile is for local verification. Use `--release` for release validation and +performance measurements; its compiler settings remain unchanged. The regular +debug test profile and CI test selection also remain unchanged. + The language-switching test stays in its own executable because it changes the process-global locale, which UI constructors also set. @@ -21,7 +46,8 @@ unchanged. Tests in the shared executable can run concurrently across modules; keep temporary paths unique and avoid changing process-wide state. CI continues to use the shared gate workflow and `cargo xtask ci` on Ubuntu and -Windows: formatting, Clippy, workspace tests (including doctests), layering and -isolated per-package WebAssembly checks. The caller disables the shared -workflow's optional tool installation because this gate uses `cargo test` and -does not use nextest. +Windows, using the shared workflow's stable Rust default: formatting, layering, +Clippy, workspace tests (including doctests) and isolated per-package WebAssembly +checks. Layering runs before Clippy and tests to reject structural failures early. +The caller disables the shared workflow's optional tool installation because this +gate uses `cargo test` and does not use nextest. diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 23b5d1b..240fd0e 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -15,7 +15,7 @@ usage: cargo xtask commands: layers enforce the crate dependency layering (xtask/src/layers.rs) wasm cargo check --target wasm32-unknown-unknown for the wasm crates and the web app - ci fmt --check, clippy -D warnings, test, layers, wasm (stops at the first failure) + ci fmt --check, layers, clippy -D warnings, test, wasm (stops at the first failure) version [set X.Y.Z[-pre]] print the workspace version, or set it (Cargo.toml + Cargo.lock) ico ... @@ -153,11 +153,13 @@ fn cmd_ci() -> Result<(), String> { } }; type Step = (&'static str, Box Result<(), String>>); + + // Reject invalid dependency layering before spending time compiling and running the workspace let steps: Vec = vec![ ("fmt", Box::new(cargo_step(&["fmt", "--all", "--", "--check"]))), + ("layers", Box::new(cmd_layers)), ("clippy", Box::new(cargo_step(&["clippy", "--workspace", "--all-targets", "--", "-D", "warnings"]))), ("test", Box::new(cargo_step(&["test", "--workspace"]))), - ("layers", Box::new(cmd_layers)), ("wasm", Box::new(cmd_wasm)), ]; for (i, (name, step)) in steps.iter().enumerate() { From 3a2b421e6da6b5891786d1b3a06d355696294a91 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 14:32:52 -0500 Subject: [PATCH 4/6] Refuse oversized .mcraft archives (#235) * Refuse oversized .mcraft archives The archive reader had no entry-count, per-entry or aggregate decompression limit: every member was read to its end and retained, so a small zip bomb could exhaust memory on Open. Members are now limited to 100 000 entries, 256 MiB each and 1 GiB together, and a member is read at most one byte past its allowance before the archive is refused. * formats: drop the unused mut on the capped zip entry --- crates/formats/src/project.rs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/crates/formats/src/project.rs b/crates/formats/src/project.rs index 0cc4b59..f73876c 100644 --- a/crates/formats/src/project.rs +++ b/crates/formats/src/project.rs @@ -13,6 +13,13 @@ use std::io::{Cursor, Read}; pub const EXT: &str = "mcraft"; pub const SBS_ENTRY: &str = "package.sbs"; +/// Most members one archive may hold; a header count is checked before any member is read. +const MAX_ENTRIES: usize = 100_000; +/// Largest member read. +const MAX_ENTRY_BYTES: u64 = 256 << 20; +/// Most bytes all members may expand to together. Without a total, many individually allowed +/// members could expand far past what one open should spend (audit: MaterialCraft #1). +const MAX_TOTAL_BYTES: u64 = 1 << 30; fn bad(message: impl Into) -> FormatError { FormatError::BadPackage(message.into()) @@ -76,10 +83,14 @@ fn resolve(owner: &str, reference: &str) -> Result { pub fn read(bytes: &[u8], identity: &str) -> Result { let mut zip = zip::ZipArchive::new(Cursor::new(bytes)).map_err(|error| bad(error.to_string()))?; + if zip.len() > MAX_ENTRIES { + return Err(bad(format!("archive has more than {MAX_ENTRIES} entries"))); + } let mut files = BTreeMap::new(); let mut seen = BTreeSet::new(); + let mut total = 0u64; for index in 0..zip.len() { - let mut entry = zip.by_index(index).map_err(|error| bad(error.to_string()))?; + let entry = zip.by_index(index).map_err(|error| bad(error.to_string()))?; let name = entry.name().to_string(); let path = name.trim_end_matches('/'); if path.is_empty() @@ -96,7 +107,14 @@ pub fn read(bytes: &[u8], identity: &str) -> Result { } let mut content = Vec::new(); - entry.read_to_end(&mut content).map_err(|error| bad(error.to_string()))?; + entry.take(MAX_ENTRY_BYTES + 1).read_to_end(&mut content).map_err(|error| bad(error.to_string()))?; + if content.len() as u64 > MAX_ENTRY_BYTES { + return Err(bad(format!("archive entry `{name}` is too large"))); + } + total = total.saturating_add(content.len() as u64); + if total > MAX_TOTAL_BYTES { + return Err(bad("archive expands past its total size limit")); + } files.insert(name, content); } let roots: Vec<_> = files.keys().filter(|name| !name.contains('/') && name.to_ascii_lowercase().ends_with(".sbs")).cloned().collect(); From 6f5812f8ef844c9f9f39cf4d237a13c73682334e Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 15:21:29 -0500 Subject: [PATCH 5/6] engine: cap linked SBS resources at 256 MiB (#236) --- crates/engine/src/linked_resource.rs | 37 ++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/crates/engine/src/linked_resource.rs b/crates/engine/src/linked_resource.rs index 7a0939c..9aabeb0 100644 --- a/crates/engine/src/linked_resource.rs +++ b/crates/engine/src/linked_resource.rs @@ -1,3 +1,8 @@ +use std::io::Read as _; + +/// Largest linked resource read from beside an SBS; matches the archive member cap. +const MAX_LINKED_RESOURCE: u64 = 256 << 20; + /// Read resource paths relative to an SBS package, including portable library aliases. pub fn reader(path: &str) -> impl Fn(&str) -> Option> + use<> { let owner = path.to_string(); @@ -28,13 +33,41 @@ pub fn reader(path: &str) -> impl Fn(&str) -> Option> + use<> { let folder = folder.as_ref()?; let file = std::fs::canonicalize(folder.join(&relative)).ok()?; let metadata = std::fs::metadata(&file).ok()?; - if !file.starts_with(folder) || !metadata.is_file() { + if !file.starts_with(folder) || !metadata.is_file() || metadata.len() > MAX_LINKED_RESOURCE { return None; } - std::fs::read(file).ok() + let mut bytes = Vec::new(); + std::fs::File::open(&file).ok()?.take(MAX_LINKED_RESOURCE + 1).read_to_end(&mut bytes).ok()?; + (bytes.len() as u64 <= MAX_LINKED_RESOURCE).then_some(bytes) } #[cfg(target_arch = "wasm32")] None } } + +#[cfg(test)] +mod tests { + use super::*; + use std::path::PathBuf; + + fn temp(name: &str) -> PathBuf { + std::env::temp_dir().join(format!("mc-linked-{}-{name}", std::process::id())) + } + + #[test] + fn linked_resources_over_the_cap_are_ignored() { + let dir = temp("cap"); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + let sbs = dir.join("p.sbs"); + std::fs::write(&sbs, b"x").unwrap(); + let big = dir.join("big.bin"); + std::fs::File::create(&big).unwrap().set_len(MAX_LINKED_RESOURCE + 1).unwrap(); + let read = reader(&sbs.to_string_lossy()); + assert!(read("big.bin").is_none(), "a resource over the cap is not read"); + std::fs::write(dir.join("small.bin"), b"ok").unwrap(); + assert_eq!(read("small.bin").as_deref(), Some(&b"ok"[..])); + let _ = std::fs::remove_dir_all(&dir); + } +} From 703d3b1cf4ae4633ee12a863df183e6ecdba2433 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 15:21:33 -0500 Subject: [PATCH 6/6] Bound SBS input bytes, wire counts and stored warnings (#237) * formats: bound SBS input, wires and stored warnings * formats: format the SBS size check --- crates/formats/src/sbs/constant.rs | 6 ++++++ crates/formats/src/sbs/read.rs | 16 +++++++++++++--- crates/formats/src/sbs/sbs_reader.rs | 8 +++++++- crates/formats/src/sbs/warnings.rs | 25 ++++++++++++++++++++++++- 4 files changed, 50 insertions(+), 5 deletions(-) diff --git a/crates/formats/src/sbs/constant.rs b/crates/formats/src/sbs/constant.rs index 9a99ebf..b4f3e3b 100644 --- a/crates/formats/src/sbs/constant.rs +++ b/crates/formats/src/sbs/constant.rs @@ -9,6 +9,12 @@ pub(super) const UPDATER_VERSION: &str = env!("CARGO_PKG_VERSION"); pub const SBS_EXT: &str = "sbs"; pub(super) const MAX_WARNINGS: usize = 600; + +/// Largest SBS document read (audit: MaterialCraft #2). +pub(super) const MAX_SBS_BYTES: u64 = 256 << 20; + +/// Most wires one SBS may carry, across all graphs (audit: MaterialCraft #2). +pub(super) const MAX_WIRES: usize = 1_000_000; pub(super) const SNIFF_BYTES: usize = 4096; pub(super) const SELF_DEPENDENCY: &str = "?himself"; pub(super) const FIRST_UID: u64 = 1_000_000_000; diff --git a/crates/formats/src/sbs/read.rs b/crates/formats/src/sbs/read.rs index ecfdd84..7ea9431 100644 --- a/crates/formats/src/sbs/read.rs +++ b/crates/formats/src/sbs/read.rs @@ -1,5 +1,5 @@ use super::{ - constant::{MAX_GRAPHS, MAX_XML_NODES, SNIFF_BYTES}, + constant::{MAX_GRAPHS, MAX_SBS_BYTES, MAX_XML_NODES, SNIFF_BYTES}, placeholder::report_placeholders, sbs_read::SbsRead, sbs_reader::SbsReader, @@ -12,6 +12,9 @@ use roxmltree::Node as XmlNode; use std::collections::HashMap; pub fn read_sbs(bytes: &[u8], name: &str, linked: &dyn Fn(&str) -> Option>) -> Result { + if bytes.len() as u64 > MAX_SBS_BYTES { + return Err(FormatError::BadPackage(format!("the SBS file is {} bytes, over the {MAX_SBS_BYTES} byte limit", bytes.len()))); + } let text = std::str::from_utf8(bytes).map_err(|e| FormatError::BadPackage(format!("the SBS file is not UTF-8 text: {e}")))?; let text = text.trim_start_matches('\u{feff}'); let options = roxmltree::ParsingOptions { allow_dtd: false, nodes_limit: MAX_XML_NODES }; @@ -30,8 +33,15 @@ pub fn read_sbs(bytes: &[u8], name: &str, linked: &dyn Fn(&str) -> Option "Untitled package".to_string(), }; - let mut reader = - SbsReader { text, warnings: &mut warnings, dependencies: HashMap::new(), graph_names: HashMap::new(), resource_names: HashMap::new(), node_count: 0 }; + let mut reader = SbsReader { + text, + warnings: &mut warnings, + dependencies: HashMap::new(), + graph_names: HashMap::new(), + resource_names: HashMap::new(), + node_count: 0, + wire_count: 0, + }; for dependency in child_element(root, "dependencies").into_iter().flat_map(|d| children_named(d, "dependency")) { if let (Some(uid), Some(file)) = (child_value(dependency, "uid"), child_value(dependency, "filename")) { reader.dependencies.insert(uid.to_string(), file.to_string()); diff --git a/crates/formats/src/sbs/sbs_reader.rs b/crates/formats/src/sbs/sbs_reader.rs index d95d183..83487b7 100644 --- a/crates/formats/src/sbs/sbs_reader.rs +++ b/crates/formats/src/sbs/sbs_reader.rs @@ -1,7 +1,7 @@ use super::base_parameters::read_base_params; use super::component_usage; use super::connection::connect_all; -use super::constant::MAX_NODES; +use super::constant::{MAX_NODES, MAX_WIRES}; use super::constant::{NODE_HALF_SIZE, SELF_DEPENDENCY}; use super::embedded::decode_embedded; use super::filter_map::{BASE_PARAMS, FilterMap, HANDLED_PARAMS, filter_by_sbs_name}; @@ -27,6 +27,7 @@ pub(super) struct SbsReader<'text, 'warnings> { pub(super) graph_names: HashMap, pub(super) resource_names: HashMap, pub(super) node_count: usize, + pub(super) wire_count: usize, } impl<'text> SbsReader<'text, '_> { @@ -341,6 +342,11 @@ impl<'text> SbsReader<'text, '_> { } }; + if self.wire_count >= MAX_WIRES { + self.warnings.add(format!("graph `{name}`: the {MAX_WIRES} wire limit was reached; later wires were dropped")); + return wires; + } + self.wire_count += 1; wires.push(Connection { from: from.id, from_port, to: to.id, to_port }); } } diff --git a/crates/formats/src/sbs/warnings.rs b/crates/formats/src/sbs/warnings.rs index 86406ac..3b81627 100644 --- a/crates/formats/src/sbs/warnings.rs +++ b/crates/formats/src/sbs/warnings.rs @@ -5,6 +5,8 @@ use std::collections::HashMap; pub(super) struct Warnings { pub(super) lines: Vec<(String, usize)>, pub(super) line_index: HashMap, + /// Messages over the limit: they are counted but never stored (audit: MaterialCraft #2). + dropped: usize, } impl Warnings { @@ -14,13 +16,17 @@ impl Warnings { line.1 += 1; return; } + if self.lines.len() >= MAX_WARNINGS { + self.dropped += 1; + return; + } self.line_index.insert(message.clone(), self.lines.len()); self.lines.push((message, 1)); } pub(super) fn finish(self) -> Vec { - let total = self.lines.len(); + let total = self.lines.len() + self.dropped; let mut out: Vec = self.lines.into_iter().take(MAX_WARNINGS).map(|(line, count)| if count > 1 { format!("{line} (×{count})") } else { line }).collect(); if total > MAX_WARNINGS { @@ -29,3 +35,20 @@ impl Warnings { out } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn warning_messages_are_capped_as_they_arrive() { + let mut w = Warnings::default(); + for i in 0..MAX_WARNINGS + 5 { + w.add(format!("warning {i}")); + } + assert_eq!(w.lines.len(), MAX_WARNINGS); + let out = w.finish(); + assert_eq!(out.len(), MAX_WARNINGS + 1); + assert_eq!(out.last().unwrap(), "…and 5 more warnings"); + } +}