cli: preflight reports

crates/nanobrush-cli/src/lib.rs

@@ -1,4 +1,5 @@
 //! Headless CLI; source-preserving conversion with atomic destination publication.
+pub mod preflight;
 use mb3_dat::{Document, Limits, Version, World};
 use std::ffi::OsString;
 use std::fmt;
@@ -7,7 +8,7 @@ use std::io::{self, BufRead, BufReader, Write};
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
 
-const HELP: &str = "nanobrush inspect INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush validate INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush convert INPUT OUTPUT --to txt|dat-201501280|dat-201512200 [--from auto|txt|dat] [--force] [LIMITS]\nLIMITS: --max-bytes N --max-items N --max-string-bytes N --max-owned-bytes N\nUse -- before positional paths beginning with a dash. TXT input is UTF-8; output has a BOM.\nExit: 0 success/help, 1 invalid data or I/O failure, 2 usage error.\n";
+const HELP: &str = "nanobrush preflight INPUT --to txt|dat-201501280|dat-201512200 [LIMITS]\nnanobrush inspect INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush validate INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush convert INPUT OUTPUT --to txt|dat-201501280|dat-201512200 [--from auto|txt|dat] [--force] [LIMITS]\nLIMITS: --max-bytes N --max-items N --max-string-bytes N --max-owned-bytes N\nUse -- before positional paths beginning with a dash. TXT input is UTF-8; output has a BOM.\nExit: 0 success/help, 1 invalid data or I/O failure, 2 usage error.\n";
 #[derive(Debug)]
 pub struct Error {
     pub usage: bool,
@@ -65,8 +66,13 @@ fn parse(args: impl IntoIterator<Item = OsString>) -> Result<Option<Options>> {
     let command = command
         .into_string()
         .map_err(|_| usage("command must be UTF-8"))?;
-    if !matches!(command.as_str(), "inspect" | "validate" | "convert") {
-        return Err(usage("expected inspect, validate or convert; use --help"));
+    if !matches!(
+        command.as_str(),
+        "inspect" | "validate" | "convert" | "preflight"
+    ) {
+        return Err(usage(
+            "expected inspect, validate, convert or preflight; use --help",
+        ));
     }
     let mut options = Options {
         command,
@@ -150,7 +156,11 @@ fn parse(args: impl IntoIterator<Item = OsString>) -> Result<Option<Options>> {
             options.paths.push(arg.into());
         }
     }
-    if options.command == "convert" {
+    if options.command == "preflight" {
+        if options.paths.len() != 1 || options.to.is_none() || options.force {
+            return Err(usage("preflight requires INPUT --to FORMAT"));
+        }
+    } else if options.command == "convert" {
         if options.paths.len() != 2 || options.to.is_none() {
             return Err(usage("convert requires INPUT OUTPUT --to FORMAT"));
         }
@@ -287,6 +297,17 @@ pub fn run(args: impl IntoIterator<Item = OsString>, stdout: &mut dyn Write) ->
     };
     let input = load(&o.paths[0], o.from, &o.limits)?;
     match o.command.as_str() {
+        "preflight" => {
+            let target = match o.to.ok_or_else(|| usage("missing --to"))? {
+                To::Txt => preflight::Target::Txt,
+                To::Dat(v) => preflight::Target::Dat(v),
+            };
+            writeln!(
+                stdout,
+                "{}",
+                preflight::analyze(&input.world, target).json()
+            )?;
+        }
         "inspect" => {
             let w = &input.world;
             let planes: usize = w.brushes.iter().map(|b| b.planes.len()).sum();

crates/nanobrush-cli/src/preflight.rs

@@ -0,0 +1,127 @@
+//! Compatibility reporting only: parsing/encoding remain authoritative validators.
+use mb3_dat::{Version, World};
+use std::collections::HashSet;
+#[derive(Clone, Copy, Debug)]
+pub enum Target {
+    Txt,
+    Dat(Version),
+}
+impl Target {
+    pub fn name(self) -> &'static str {
+        match self {
+            Self::Txt => "txt",
+            Self::Dat(Version::V201501280) => "dat-201501280",
+            Self::Dat(Version::V201512200) => "dat-201512200",
+        }
+    }
+}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Issue {
+    pub code: &'static str,
+    pub count: usize,
+}
+#[derive(Clone, Debug)]
+pub struct Report {
+    pub target: Target,
+    pub issues: Vec<Issue>,
+}
+impl Report {
+    pub fn compatible(&self) -> bool {
+        self.issues.is_empty()
+    }
+    pub fn json(&self) -> String {
+        let issues = self
+            .issues
+            .iter()
+            .map(|i| format!("{{\"code\":\"{}\",\"count\":{}}}", i.code, i.count))
+            .collect::<Vec<_>>()
+            .join(",");
+        format!(
+            "{{\"schema\":1,\"target\":\"{}\",\"compatible\":{},\"issues\":[{}]}}",
+            self.target.name(),
+            self.compatible(),
+            issues
+        )
+    }
+}
+pub fn analyze(world: &World, target: Target) -> Report {
+    let mut issues = Vec::new();
+    let planes = || world.brushes.iter().flat_map(|b| &b.planes);
+    match target {
+        Target::Dat(version) => {
+            let n = world
+                .string_properties
+                .iter()
+                .chain(&world.uv_properties)
+                .filter(|s| !s.is_ascii())
+                .count()
+                .saturating_add(
+                    planes()
+                        .flat_map(|p| &p.strings)
+                        .filter(|p| !p.value.is_ascii())
+                        .count(),
+                );
+            if n != 0 {
+                issues.push(Issue {
+                    code: "non_ascii",
+                    count: n,
+                });
+            }
+            if version == Version::V201501280 {
+                let n = world
+                    .string_properties
+                    .len()
+                    .saturating_add(world.uv_properties.len())
+                    .saturating_add(
+                        planes()
+                            .map(|p| p.strings.len().saturating_add(p.uv.len()))
+                            .fold(0usize, usize::saturating_add),
+                    );
+                if n != 0 {
+                    issues.push(Issue {
+                        code: "legacy_properties",
+                        count: n,
+                    });
+                }
+            }
+        }
+        Target::Txt => {
+            let mut n = 0usize;
+            for names in [&world.string_properties, &world.uv_properties] {
+                let mut seen = HashSet::new();
+                for name in names {
+                    if !seen.insert(name) {
+                        n = n.saturating_add(1);
+                    }
+                }
+            }
+            if n != 0 {
+                issues.push(Issue {
+                    code: "duplicate_names",
+                    count: n,
+                });
+            }
+        }
+    }
+    Report { target, issues }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn grouped_reports_and_no_mutation() {
+        let mut w = World {
+            string_properties: vec!["é".into(), "é".into()],
+            ..World::default()
+        };
+        let original = w.clone();
+        assert_eq!(analyze(&w, Target::Txt).issues[0].count, 1);
+        let r = analyze(&w, Target::Dat(Version::V201501280));
+        assert_eq!(r.issues.len(), 2);
+        assert!(!r.compatible());
+        assert!(r.json().contains("\"schema\":1"));
+        assert_eq!(w, original);
+        w.string_properties.clear();
+        assert!(analyze(&w, Target::Txt).compatible());
+    }
+}

docs/CLI.md

@@ -54,3 +54,5 @@ Incompatible exports fail before publication: for example, Unicode TXT→ASCII D
 ## Tests
 
 Eight asset-free unit tests cover options, limits, inspection, both DAT directions, Unicode paths, overwrite/same-file/hard-link/symlink guards, validation before any output, preservation of existing destinations after incompatible conversion, exclusive publication races and temporary cleanup. Two process integration tests check documented exit streams/codes and invoke the real binary for inspect, DAT→TXT, validate and TXT→DAT against **all 58 DAT outputs** (232 successful commands), verifying exact final DAT bytes. Fixture tests fail when assets are missing. See [E04](experiments/txt-cli-2026-10-21.md).
+
+`preflight INPUT --to FORMAT` emits schema-1 compatibility JSON without writing a document. A successful report command exits 0 even when `compatible` is false. Grouped issues cover non-ASCII DAT values, property-bearing old-DAT exports and duplicate TXT table names. Counts refer to affected names/entries, not lost bytes. Full structural/size validation remains the encoder’s responsibility.

docs/PROGRESS_2026-10-26.md

@@ -0,0 +1,16 @@
+# Ten medium tasks — 2026-10-26
+
+Scope: extend native headless formats and geometry. Each stage is independently checked and committed. Native geometry policies do not claim measured editor parity. All fixtures remain in Xet; authored code/tests/docs remain ordinary Git.
+
+| Stage | TODO | Scope | Status/evidence |
+| --- | --- | --- | --- |
+| 1 | P6.23 | Structured preflight reports | Complete: `preflight INPUT --to FORMAT` emits schema-1 JSON with grouped ASCII/downgrade/duplicate-name incompatibilities; reports never mutate documents. Parser/encoder validation remains authoritative. Unit tests and existing CLI unit regressions pass. |
+| 2 | P6.24 | Explicit Latin-1 TXT input | Pending |
+| 3 | P6.25 | Bounded computed OBJ writer | Pending |
+| 4 | P6.26 | CLI OBJ with loss acknowledgement | Pending |
+| 5 | P5.15 | Geometry primitives/bounds | Pending |
+| 6 | P5.16 | Convex brush contours | Pending |
+| 7 | P5.17 | Patch9 tessellation | Pending |
+| 8 | P5.18 | Computed world pipeline/CLI | Pending |
+| 9 | P5.19 | Nearest-hit ray queries | Pending |
+| 10 | P5.20 | Property table edits/reindexing | Pending |

docs/TODO.md

@@ -157,6 +157,8 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 
 - [x] P6.22 Implement bounded Rust TXT readers/writers and native `nanobrush inspect/validate/convert` for TXT and both DAT versions, with explicit Unicode/loss policies, structural validation, guarded atomic publication and Nix packaging. All 58 DAT outputs survive CLI DAT→TXT→DAT exactly; seven TXT outputs and 16 direct TXT→DAT pairs are covered; nine invalid/lossy inputs are rejected ([RUST_TXT.md](RUST_TXT.md), [CLI.md](CLI.md), E04/F30/F31).
 
+- [x] P6.23 Implement grouped, versioned conversion preflight reports for TXT/DAT incompatibilities without mutation ([ten-task ledger](PROGRESS_2026-10-26.md)).
+
 ## P7 — Input, cameras, grids, views, and editing workflows
 
 **Depends on:** P4 dispatch and P5 geometry. **Exit:** complete interaction/state-machine specifications and reproducible replays.