gitronics 0.6.3__tar.gz → 0.6.4__tar.gz

gitronics-0.6.4/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: Rust tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Set up Python (Required for PyO3 test linking)
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Configure PyO3 Python path
+        shell: bash
+        run: |
+          echo "PYO3_PYTHON=${{ steps.setup-python.outputs.python-path }}" >> $GITHUB_ENV
+          if [[ "$RUNNER_OS" == "macOS" ]]; then
+            PYLIB=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
+            PYVER=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LDVERSION'))")
+            echo "RUSTFLAGS=-L${PYLIB} -lpython${PYVER}" >> $GITHUB_ENV
+          fi
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: rustfmt
+        run: cargo fmt --all --check
+
+      - name: Test
+        run: cargo test --workspace --features pyo3/auto-initialize
+
+      - name: Clippy
+        run: cargo clippy --workspace -- -D warnings
+
+  ruff:
+    name: Python lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      # Pinned so a new ruff release can't fail CI unexpectedly; bump deliberately.
+      - name: ruff lint
+        run: uvx ruff@0.15.21 check python
+
+      - name: ruff format
+        run: uvx ruff@0.15.21 format --check python
+
+  python:
+    name: Python tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Install maturin and pytest
+        run: pip install maturin pytest
+
+      - name: Build and install Python package (dev mode)
+        run: pip install -e .
+
+      - name: Run Python tests
+        run: pytest
+
+  report-viewer:
+    name: Report viewer (JS)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: report/package-lock.json
+
+      - name: Install test dependencies
+        working-directory: report
+        run: npm ci
+
+      # The viewer and vendored library are inlined by `include_str!` —
+      # there is no bundle step, so this job never runs cargo and cargo
+      # never runs node.
+      - name: Syntax check
+        working-directory: report
+        run: node --check report.js
+
+      - name: Render tests (jsdom)
+        working-directory: report
+        run: node --test 'test/*.test.mjs'

{gitronics-0.6.3 → gitronics-0.6.4}/.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 *.pyd
 *.pdb
 /site
+node_modules/
+.pytest_cache/
+.ruff_cache/

{gitronics-0.6.3 → gitronics-0.6.4}/Cargo.lock

@@ -124,12 +124,30 @@ version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
+[[package]]
+name = "castaway"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "cc"
 version = "1.2.62"
@@ -207,12 +225,35 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "compact_str"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dfdd1c2274d9aa354115b09dc9a901d6c5576818cdf70d14cae2bdb47df00ab"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.6"
@@ -238,6 +279,26 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
 [[package]]
 name = "dunce"
 version = "1.0.5"
@@ -349,6 +410,16 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.3.4"
@@ -390,7 +461,7 @@ dependencies = [
 
 [[package]]
 name = "gitronics"
-version = "0.6.3"
+version = "0.6.4"
 dependencies = [
  "chrono",
  "clap",
@@ -402,11 +473,14 @@ dependencies = [
  "logtest",
  "migjorn",
  "path-clean",
+ "pathdiff",
  "pyo3",
  "rayon",
  "regex",
  "serde",
  "serde-saphyr",
+ "serde_json",
+ "sha2",
  "tempfile",
  "thiserror",
  "walkdir",
@@ -636,21 +710,25 @@ dependencies = [
 
 [[package]]
 name = "migjorn"
-version = "0.2.2"
+version = "0.3.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce11924d4ef1f0496f0be14e68860ab11bbc0b63222057d03bc92b22b4084f3d"
+checksum = "ecf4b3b5db557a6100d1767eb22295cbd70521d1678a34584644356ff140865c"
 dependencies = [
+ "compact_str",
  "migjorn-syntax",
+ "rayon",
  "rustc-hash",
 ]
 
 [[package]]
 name = "migjorn-syntax"
-version = "0.2.2"
+version = "0.3.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42d3806f43fee8380cfaa0e26e9fee3a2dbece142e5314b6c7f9a0babf03fe05"
+checksum = "f7bce9c260eb5e8f964a98d313dd84ceb805e979b31ecdcdef5b90a059e5eb58"
 dependencies = [
- "rustc-hash",
+ "compact_str",
+ "memchr",
+ "rayon",
 ]
 
 [[package]]
@@ -686,6 +764,12 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "17359afc20d7ab31fdb42bb844c8b3bb1dabd7dcf7e68428492da7f16966fcef"
 
+[[package]]
+name = "pathdiff"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df94ce210e5bc13cb6651479fa48d14f601d9858cfe0467f43ae157023b938d3"
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -757,6 +841,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
 dependencies = [
  "once_cell",
+ "python3-dll-a",
  "target-lexicon",
 ]
 
@@ -795,6 +880,15 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "python3-dll-a"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d80ba7540edb18890d444c5aa8e1f1f99b1bdf26fb26ae383135325f4a36042b"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -890,6 +984,12 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -960,6 +1060,7 @@ version = "1.0.149"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
 dependencies = [
+ "indexmap",
  "itoa",
  "memchr",
  "serde",
@@ -967,6 +1068,17 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "shlex"
 version = "1.3.0"
@@ -985,6 +1097,12 @@ version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -1041,6 +1159,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"

{gitronics-0.6.3 → gitronics-0.6.4}/Cargo.toml

@@ -1,9 +1,17 @@
 [package]
 name = "gitronics"
-version = "0.6.3"
+version = "0.6.4"
 edition = "2024"
 description = "Build MCNP neutronics models from modular components"
 license = "EUPL-1.2"
+# The published crate includes the viewer and vendored library it inlines; the
+# viewer's test harness and its dependencies are development-only.
+exclude = [
+    "report/test",
+    "report/node_modules",
+    "report/package.json",
+    "report/package-lock.json",
+]
 readme = "README.md"
 
 [[bin]]
@@ -15,11 +23,16 @@ name = "gitronics"
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }
-migjorn = { version = "0.2.2" }
+pyo3 = { version = "0.23", features = [
+    "extension-module",
+    "abi3-py39",
+    "generate-import-lib",
+] }
+migjorn = "0.3.11"
 walkdir = "2.5.0"
 serde = { version = "1.0.228", features = ["derive"] }
 serde-saphyr = "0.0.26"
+serde_json = { version = "1.0", features = ["preserve_order"] }
 thiserror = "2.0.18"
 rayon = "1.12.0"
 log = "0.4.29"
@@ -31,6 +44,8 @@ indexmap = { version = "2.14.0", features = ["serde"] }
 git2 = "0.21.0"
 dunce = "1.0.5"
 path-clean = "1.0.1"
+sha2 = "0.10"
+pathdiff = "0.2"
 
 [dev-dependencies]
 tempfile = "3.0"

{gitronics-0.6.3 → gitronics-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitronics
-Version: 0.6.3
+Version: 0.6.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{gitronics-0.6.3 → gitronics-0.6.4}/README.md

@@ -114,7 +114,9 @@ Requires the stable [Rust toolchain](https://rustup.rs/) and [maturin](https://g
 git clone https://github.com/Fusion4Energy/gitronics
 cd gitronics
 pip install maturin
-maturin develop --release
+maturin develop --release 
+# Or to generate a wheel for distribution:
+maturin build --release --target x86_64-pc-windows-gnu --zig -i python3.12
 ```
 </details>
 

{gitronics-0.6.3 → gitronics-0.6.4}/docs/getting_started/building_a_model.md

@@ -11,7 +11,7 @@ gitronics build configurations/baseline.yaml -o output/
 This will assemble the model defined in `baseline.yaml` and write an `assembled.mcnp` file to the `output/` directory.
 
 !!! tip "HTML report"
-    The `gitronics build` command can also generate an HTML report of the assembled model. This report includes a summary of the configuration, a list of all files used, and the filler models assignation of the envelope structure.
+    Every successful build writes a self-contained, offline `build_report.html` and its machine-readable `build_report.json` manifest.
 
 If there is any problem during the assembly (configuration wrongly defined, missing files, duplicated card IDs, etc.), Gitronics will raise an error and the build will fail. The error message will indicate the cause of the failure and the file where it occurred.
 
@@ -32,9 +32,25 @@ When running the `gitronics build` command, the following steps are performed:
 3. All fillers and data card files are reordered by their card type and ID numbers. Every `assembled.mcnp` file will have the same deterministic order of cards. Only the first ID number of the first card in each file is used to determine the order of the files.
 4. The envelope structure is adapted to include the `FILL` cards for the envelope cells that have a filler model assigned. The `FILL` cards will reference the correct universe ID of the filler model by parsing the filler model in search of the first `U` card. The transformation associated to each `FILL` card is also applied as defined in the metadata of the filler model.
 5. The envelope structure, filler models, and data card files are concatenated into a single MCNP input file.
-6. Validations checks are performed on the assembled model to ensure that it is a valid MCNP input file. This includes checking for duplicate card IDs, missing cards, and other potential issues. Failure to pass the checks will crash the build with an error message.
+6. Assembly checks detect card ID collisions and invalid references supported by the parser. These checks do not validate geometry overlaps, transport behaviour, or physical correctness. Failure returns an error.
 7. The assembled model is written to the output file: `assembled.mcnp`.
-8. An HTML report is written to the output directory with name: `build_report.html`.
+8. HTML and JSON reports are written, recording the output identity and the checks performed.
+
+## Reviewing a build
+
+- **Overview and Checks:** assembly outcome, warnings, and each recorded check's result. Configuration completeness counts all marked envelopes, including those missing from the configuration. Explicit `null` assignments are complete, intentionally empty placements, not errors.
+- **Explorer and Coverage Map:** filled, explicitly empty, and unconfigured envelopes, with search and status filters. Grouping fields come from project metadata; no field such as `sector` or `zone` is required or privileged. Defaults favour populated fields with a small number of repeated values.
+- **Envelope and filler details:** envelope cell IDs, assignment configuration, input paths, transforms, arbitrary metadata, and searchable placement lists. IDs identify cards in the source files; source line numbers are not recorded.
+- **ID Map:** separate lanes for cells, surfaces, materials, tallies, transformations, and universes, with exact numeric lookup, zoom, and pan. Geometry IDs identify their filler or envelope structure; data-card IDs identify their defining file and open the card definition. Materials count `M` definitions (not `MT`/`MX` modifiers), tallies count `F` and `FMESH` definitions (not tally modifiers), and transformations count `TR` definitions, including starred forms. Universes include explicit cell `U` assignments and implicit root universe 0 on ordinary cells; negative `U` values use their absolute ID, and inherited-only `LIKE ... BUT` membership is not separately resolved. Shared IDs show all defining owners and count once in occupancy totals. Older reports without the required inventory show an unavailable state rather than claiming the namespace is empty.
+- **Data Cards:** one expandable entry per selected data file, showing its logical name, relative path, configuration role, and counts of actual card types. Expand a file to see card IDs grouped by type; open an ID (or a name such as `MODE` or `NPS`) for its definition and references. Search matches files, IDs, and definitions, reveals matching files, and highlights matching IDs. File roles and contents are separate: a file selected under `materials` can also contain transforms. The tab badge and overview count selected data files, not individual cards. Material definitions include direct cell references; transform definitions link matching envelope placements. This is not an exhaustive dependency analysis of all MCNP card types or inherited `LIKE ... BUT` properties.
+- **Inputs:** file paths relative to the selected configuration, byte counts, SHA-256 identities, raw configuration inheritance layers, resolved configuration, and the configuration responsible for each envelope assignment.
+- **Diff:** baseline and current identity, assignment and transform values, component statistics, input content hashes, data-card definitions, and placement impact. Schema-1 reports remain viewable, but cannot provide content comparisons without hashes.
+
+The content fingerprint identifies the selected input bytes, logical paths, resolved configuration, and Gitronics version. It excludes timestamps and Git working-tree status; it is not a physics-equivalence hash. The separate output checksum includes the timestamped MCNP banner and identifies the exact assembled file. Input hashes describe the bytes read by the loaders, including configuration inheritance layers, rather than a separate pre-build read. Those identities are checked again before writing; changing loaded inputs during a build requires rebuilding.
+
+Once assembly data is available, merge, data-card parsing, reference-validation, input-stability, and output-writing failures attempt to produce a report marked **failed**, without an output identity. If writing that report also fails, the original build error is preserved and the reporting error is logged as a warning. A report-writing failure after otherwise successful assembly still causes the command to fail. Earlier failures such as invalid configuration or missing files still return CLI errors before a new report can be produced. An old or partially written output deck can remain in a reused output directory after failure; do not treat it as the output of the failed attempt.
+
+Reports embed file paths, metadata, configuration, and data-card text. Review that information before sharing reports outside the project.
 
 ## Logging
 

{gitronics-0.6.3 → gitronics-0.6.4}/docs/getting_started/configuration_file.md

@@ -79,6 +79,8 @@ Only one source file can be specified, but any number of materials, transformati
 
 This field is a dictionary that maps envelope cell names to filler model file stems.
 If an envelope cell name appears in the dictionary but is not found in the envelope structure file, Gitronics will raise an error.
+This also applies to names assigned `null`. The build stops before writing the assembled model or build reports and lists the unmatched names.
+An envelope present in the structure but omitted from the configuration is left unfilled with a warning; use an explicit `null` assignment to mark it as intentionally empty.
 
 <figure class="wide" markdown="span">
   ![How the envelopes map fills envelope cells](../assets/mapping.svg#only-dark){ width="100%" }
@@ -100,7 +102,15 @@ The overriding rules are as follows:
 
 - The field `project_roots` is not inherited, it must be specified in the current configuration file.
 - The fields `envelope_structure`, `source`, `materials`, `transformations`, and `tallies` are inherited, but they can be overridden in the current configuration file. If the current file defines the field, the parent value is ignored.
+- For `source`, omitting the key inherits the parent's value, `source: null` explicitly removes it, and a file stem replaces it. A cleared source remains cleared in descendants unless they assign a new source.
 - The field `envelopes` is inherited and merged entry-by-entry. The current file can add new envelopes or change specific ones without repeating the full list. If an envelope name is present in both the parent and the current configuration, the current value takes precedence.
 
+For example, to inherit a model without its source cards:
+
+```yaml
+overrides: baseline.yaml
+source: null
+```
+
 !!! tip "Nested inheritance"
     Inheritance chains are allowed but are not considered a good practice. It is simpler and less error-prone to inherit from a single parent configuration file.

gitronics-0.6.4/docs/usage/build.md

@@ -0,0 +1,140 @@
+# `build` — Assemble a Model
+
+The `build` command reads a YAML configuration file and assembles a ready-to-run MCNP input file.
+
+## Synopsis
+
+```
+gitronics build <CONFIG> [--output-path <DIR>]
+```
+
+| Argument | Description |
+|---|---|
+| `CONFIG` | Path to the configuration YAML file (absolute or relative to cwd). |
+| `-o`, `--output-path` | Directory to write `assembled.mcnp` into. Defaults to `.` (current directory). |
+
+## Example
+
+```bash
+gitronics build configurations/in_vessel_only.yaml --output-path output/
+```
+
+## Output
+
+On success, the following files are written to `--output-path`:
+
+| File | Description |
+|---|---|
+| `assembled.mcnp` | The complete, self-contained MCNP input deck. |
+| `build_report.html` | A report of the build process, including a list of all files used and the envelope assignation. |
+| `build_report.json` | The machine-readable build manifest, also used as the baseline for report comparisons. |
+| `.gitignore` | A file to ignore the contents of the directory in Git. |
+
+The `.gitignore` file is written to the output directory to prevent accidentally committing the assembled model and report to version control. 
+
+The top of `assembled.mcnp` contains a metadata comment block:
+
+```
+C ============================================================
+C  Built by gitronics v0.1.0
+C  Configuration : configurations/in_vessel_only.yaml
+C  Git commit    : v0.6.2-4-g04d555a
+C  Date / time   : 2025-01-15 14:32:00
+C ============================================================
+```
+
+## Comparing builds
+
+Open the current build's `build_report.html`, select **Diff**, and choose or drop
+the baseline `build_report.json`. Both reports stay local to your browser; the
+HTML includes its assets and works offline. Rebuild or regenerate older HTML
+reports to use the updated viewer. The JSON schema is unchanged.
+
+The summary shows envelope changes, input and data-card changes, warning-message
+changes, and signed cell/surface deltas (`current - baseline`). Click a count or
+use the section controls to inspect the corresponding changes. **Build summary
+changes** displays list-valued selections as bullet lists; an empty selection is
+shown as **None**.
+
+- **Assignments** groups repeated baseline/current filler substitutions, sorted
+    by affected placement count. Expand a group to inspect its placements, or use
+    **By envelope**. Search names or metadata, filter added/removed/reassigned
+    envelopes or transform/universe/status changes, and select metadata values
+    from either build. Results are paginated in groups of 25.
+- **Inputs** separates content changes and added/removed inputs from collapsed
+    path-only changes with identical hashes. Search includes full paths; select
+    an input to compare paths, hashes and sizes. Missing hashes are marked as not
+    comparable, not treated as unchanged content.
+- **Components** compares same-name components and explicit assignment
+    replacements. Replacements are inferred from shared envelope assignments,
+    not guessed from similar filenames, and do not imply a rename. Added and
+    removed component inventories remain available separately.
+- **Data cards** lists modifications before removals and additions. Filter by
+    category or change type and select a card for a line-numbered diff. Related
+    tally cards such as `FMESH1014:N`, `FC1014`, and `FM1014` appear together under
+    **Tally 1014**. A member addition, removal, or edit marks an existing tally as
+    modified. Open a tally to select individual member comparisons, including
+    unchanged members; modified members are selected first. Counts distinguish
+    grouped items from individual card changes, and searches include all members.
+    Unchanged line context is folded by default; full definitions remain available.
+    Very costly line comparisons fall back to full definitions with a notice.
+- **Checks & warnings** compares check results and warning-message occurrence
+    counts, including new, resolved and repeated warnings. A warning count is not
+    a geometry or physics validation result.
+
+Placement details show baseline and current values together, including metadata,
+assignment origins, and assigned components. Changed fields are highlighted;
+unchanged fields are de-emphasized. Removed placements can still be inspected.
+Schema 1 reports remain supported, with notices where input hashes or diagnostics
+were not recorded. Input and card comparisons use recorded evidence; they do not
+constitute a geometric or physical equivalence test.
+
+The standalone **Data Cards** tab also groups tally members by ID within each
+source file. Expand a tally and then a member to inspect its definition and
+references. Searching for one member keeps its tally family visible. Global
+defaults such as `E0` remain separate, as do non-tally cards with the same numeric
+ID. Diff combines related tally members across files while preserving each
+member's baseline and current file provenance.
+
+### Viewer development
+
+Run `npm ci`, `npm test`, `npm run check`, and `npm run lint` from `report/`.
+The pinned `diff` development dependency supplies the offline jsdiff asset. After
+updating that dependency, run `npm run vendor:diff` and commit the generated
+`report/vendor/diff.js` with the package manifests. The generated asset includes
+its BSD license and is embedded by both Rust and the JavaScript test harness.
+Normal Rust builds do not require Node.js or an asset build step.
+
+## How files are located
+
+Gitronics recursively searches all directories listed in `project_roots` (defined in the configuration) for files referenced by stem name. 
+This means you can organise your project files into subdirectories however you like, as long as each stem name is unique across all `project_roots`.
+
+## Python API
+
+`build_model` is also available as a Python function for use in scripts and notebooks:
+
+```python
+import gitronics
+
+gitronics.build_model(
+    "configurations/in_vessel_only.yaml",
+    "output/",
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `config_path` | `str` or `Path` | Path to the configuration YAML file. |
+| `output_path` | `str` or `Path` | Directory to write `assembled.mcnp` into. |
+
+Raises `RuntimeError` on failure with a descriptive message.
+
+## Logging
+
+Set the `RUST_LOG` environment variable to control verbosity:
+
+```bash
+RUST_LOG=info gitronics build configurations/baseline.yaml
+RUST_LOG=debug gitronics build configurations/baseline.yaml
+```