expressir 2.4.3 → 2.4.4

data/ext/expressir_core/src/lib.rs

@@ -0,0 +1,446 @@
+//! Ruby bridge for expressir-core: exposes the Rust parse + model
+//! extraction pipeline to the expressir gem.
+//!
+//! Two entry points:
+//! - `parse_to_model_hash` — the wire JSON string (tooling, parity runs)
+//! - `parse_to_model` — the hydrated model, built by walking the wire
+//!   JSON definition once and constructing each node through
+//!   `Serializable.instantiate` (lutaml-model's fast bulk constructor).
+//!   Skips the JSON string, `JSON.parse`, and the generic from_hash
+//!   mapping machinery.
+
+use std::collections::HashMap;
+use std::sync::mpsc::Receiver;
+use std::sync::Mutex;
+
+use expressir_rs::batch::{self, BatchOutcome};
+use expressir_rs::compiled_set::{CompiledFile, CompiledSet};
+use expressir_rs::ParsedTree;
+use magnus::{function, method};
+use magnus::prelude::*;
+use magnus::typed_data::DataTypeBuilder;
+use magnus::value::Lazy;
+use magnus::IntoValue;
+use magnus::{DataType, DataTypeFunctions, Error, RArray, RClass, RHash, RModule, Ruby, TypedData};
+use serde_json::Value as Wire;
+
+fn parse_error(ruby: &Ruby, e: expressir_rs::model_json::ModelJsonError) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        format!("expressir-core: parse error: {e:?}"),
+    )
+}
+
+fn model_json(ruby: &Ruby, source: String, path: String) -> Result<String, Error> {
+    let tree = ParsedTree::parse(&source).map_err(|e| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("expressir-core: parse error: {e:?}"),
+        )
+    })?;
+    let value = tree.to_model_json(&path).map_err(|e| parse_error(ruby, e))?;
+    serde_json::to_string(&value).map_err(|e| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("expressir-core: serialize error: {e}"),
+        )
+    })
+}
+
+/// Resolves `Expressir::Model::*` classes by their wire `_class` name,
+/// caching each lookup (the class set is closed).
+#[derive(Default)]
+struct ClassCache {
+    classes: HashMap<String, RClass>,
+}
+
+impl ClassCache {
+    fn resolve(&mut self, ruby: &Ruby, name: &str) -> Result<RClass, Error> {
+        if let Some(klass) = self.classes.get(name) {
+            return Ok(*klass);
+        }
+
+        let short = name.strip_prefix("Expressir::Model::").ok_or_else(|| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("expressir-core: unknown model class {name:?}"),
+            )
+        })?;
+        let mut current = ruby
+            .class_object()
+            .const_get::<_, RModule>("Expressir")?
+            .const_get::<_, RModule>("Model")?;
+        let segments: Vec<&str> = short.split("::").collect();
+        let last = segments.len() - 1;
+        for (i, segment) in segments.iter().enumerate() {
+            let value = current
+                .const_get::<_, magnus::Value>(segment.to_string())
+                .map_err(|e| {
+                    Error::new(
+                        ruby.exception_runtime_error(),
+                        format!("expressir-core: unknown model class {name:?}: {e}"),
+                    )
+                })?;
+            if i == last {
+                let klass = RClass::from_value(value).ok_or_else(|| {
+                    Error::new(
+                        ruby.exception_runtime_error(),
+                        format!("expressir-core: {name:?} is not a class"),
+                    )
+                })?;
+                self.classes.insert(name.to_string(), klass);
+                return Ok(klass);
+            }
+            current = RModule::from_value(value).ok_or_else(|| {
+                Error::new(
+                    ruby.exception_runtime_error(),
+                    format!("expressir-core: {name:?} is not a module"),
+                )
+            })?;
+        }
+        unreachable!()
+    }
+}
+
+/// Live handle to a running batch compile: the outcomes channel plus
+/// the per-stream class cache and the wire values retained for
+/// artifact assembly. `next` blocks until a worker delivers; workers
+/// are Rust threads, so they progress while Ruby waits.
+#[derive(DataTypeFunctions)]
+struct BatchStream {
+    rx: Receiver<BatchOutcome>,
+    cache: Mutex<ClassCache>,
+    wires: Mutex<Vec<(String, Wire)>>,
+    /// Wire paths in job order — the artifact layout must be
+    /// deterministic regardless of completion order.
+    order: Mutex<Vec<String>>,
+}
+
+// SAFETY: BatchStream never crosses threads itself; Send is required by
+// magnus to expose methods, and every access happens on the Ruby thread
+// that owns the stream.
+unsafe impl Send for BatchStream {}
+
+unsafe impl TypedData for BatchStream {
+    fn class(ruby: &Ruby) -> RClass {
+        static CLASS: Lazy<RClass> = Lazy::new(|ruby| {
+            let class = ruby
+                .class_object()
+                .const_get::<_, RModule>("Expressir")
+                .and_then(|m| m.const_get::<_, RModule>("Core"))
+                .and_then(|m| m.const_get::<_, RClass>("BatchStream"))
+                .expect("Expressir::Core::BatchStream defined in init");
+            class.undef_default_alloc_func();
+            class
+        });
+        ruby.get_inner(&CLASS)
+    }
+
+    fn data_type() -> &'static DataType {
+        static DATA_TYPE: DataType =
+            DataTypeBuilder::<BatchStream>::new(c"Expressir::Core::BatchStream").build();
+        &DATA_TYPE
+    }
+}
+
+fn batch_start(ruby: &Ruby, jobs: RArray, workers: usize) -> Result<BatchStream, Error> {
+    let mut parsed: Vec<(String, String)> = Vec::with_capacity(jobs.len());
+    for index in 0..jobs.len() {
+        let job = jobs.entry(index as isize)?;
+        let pair = RArray::from_value(job).ok_or_else(|| {
+            Error::new(
+                ruby.exception_arg_error(),
+                "jobs must be [read_path, wire_path] pairs",
+            )
+        })?;
+        let read_path: String = pair.entry(0)?;
+        let wire_path: String = pair.entry(1)?;
+        parsed.push((read_path, wire_path));
+    }
+    let order = parsed.iter().map(|(_, wire)| wire.clone()).collect();
+    let rx = batch::parse_batch(parsed, workers);
+    Ok(BatchStream {
+        rx,
+        cache: Mutex::new(ClassCache::default()),
+        wires: Mutex::new(Vec::new()),
+        order: Mutex::new(order),
+    })
+}
+
+/// Write the compiled-set artifact from this stream's retained wires:
+/// `read_paths` maps wire_path → physical source for digesting.
+fn batch_write_set(
+    ruby: &Ruby,
+    stream: &BatchStream,
+    out_path: String,
+    read_paths: RHash,
+    expressir_version: String,
+) -> Result<magnus::Value, Error> {
+    let wires = stream.wires.lock().expect("wires").clone();
+    let order = stream.order.lock().expect("order").clone();
+    let position: HashMap<String, usize> =
+        order.iter().enumerate().map(|(i, p)| (p.clone(), i)).collect();
+    let mut wires = wires;
+    wires.sort_by_key(|(wire_path, _)| position.get(wire_path).copied().unwrap_or(usize::MAX));
+
+    let mut files = Vec::with_capacity(wires.len());
+    for (wire_path, wire) in wires {
+        let read_path: Option<String> = read_paths
+            .fetch(ruby.str_new(&wire_path))
+            .map_err(|e| Error::new(ruby.exception_arg_error(), e.to_string()))?;
+        let source_sha = read_path
+            .as_deref()
+            .map(compiled_set_file_sha)
+            .unwrap_or_default();
+        let wire_json = serde_json::to_string(&wire).map_err(|e| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("wire encode {wire_path}: {e}"),
+            )
+        })?;
+        files.push(CompiledFile {
+            wire_path,
+            source_sha,
+            wire_json,
+        });
+    }
+    let set = CompiledSet::build(files, &expressir_version, &expressir_rs::grammar_digest());
+    set.write_to(&out_path).map_err(|e| {
+        Error::new(
+            ruby.exception_io_error(),
+            format!("compiled set {out_path}: {e}"),
+        )
+    })?;
+    Ok(ruby.str_new(&set.header.set_digest).as_value())
+}
+
+fn compiled_set_file_sha(path: &str) -> String {
+    expressir_rs::compiled_set::file_sha256(path)
+}
+
+/// `[wire_path, model, nil]` / `[wire_path, nil, message]`, or nil when
+/// the queue has drained.
+fn batch_next(ruby: &Ruby, stream: &BatchStream) -> Result<magnus::Value, Error> {
+    let outcome = stream.rx.recv();
+    let Ok(outcome) = outcome else {
+        return Ok(ruby.qnil().as_value());
+    };
+    let BatchOutcome { path, result } = outcome;
+    let triple = RArray::with_capacity(3);
+    triple.push(ruby.str_new(&path))?;
+    match result {
+        Ok(wire) => {
+            stream
+                .wires
+                .lock()
+                .expect("wires")
+                .push((path.clone(), wire.clone()));
+            let mut cache = stream.cache.lock().expect("class cache");
+            let model = value_to_ruby(ruby, &mut cache, &wire)?;
+            triple.push(model)?;
+            triple.push(ruby.qnil())?;
+        }
+        Err(message) => {
+            triple.push(ruby.qnil())?;
+            triple.push(ruby.str_new(&message))?;
+        }
+    }
+    Ok(triple.as_value())
+}
+
+/// Reader over a compiled-set artifact: ordered, lazy — each `next`
+/// hydrates one file's wire model through the shared class cache.
+#[derive(DataTypeFunctions)]
+struct SetReader {
+    set: CompiledSet,
+    index: Mutex<usize>,
+    cache: Mutex<ClassCache>,
+}
+
+// SAFETY: only ever touched from the owning Ruby thread.
+unsafe impl Send for SetReader {}
+
+unsafe impl TypedData for SetReader {
+    fn class(ruby: &Ruby) -> RClass {
+        static CLASS: Lazy<RClass> = Lazy::new(|ruby| {
+            let class = ruby
+                .class_object()
+                .const_get::<_, RModule>("Expressir")
+                .and_then(|m| m.const_get::<_, RModule>("Core"))
+                .and_then(|m| m.const_get::<_, RClass>("Set"))
+                .expect("Expressir::Core::Set defined in init");
+            class.undef_default_alloc_func();
+            class
+        });
+        ruby.get_inner(&CLASS)
+    }
+
+    fn data_type() -> &'static DataType {
+        static DATA_TYPE: DataType =
+            DataTypeBuilder::<SetReader>::new(c"Expressir::Core::Set").build();
+        &DATA_TYPE
+    }
+}
+
+fn set_open(_ruby: &Ruby, path: String) -> Result<SetReader, Error> {
+    let set = CompiledSet::read_from(&path).map_err(|e| {
+        Error::new(
+            _ruby.exception_runtime_error(),
+            format!("compiled set {path}: {e}"),
+        )
+    })?;
+    Ok(SetReader {
+        set,
+        index: Mutex::new(0),
+        cache: Mutex::new(ClassCache::default()),
+    })
+}
+
+fn set_digest(ruby: &Ruby, reader: &SetReader) -> Result<magnus::Value, Error> {
+    Ok(ruby.str_new(&reader.set.header.set_digest).as_value())
+}
+
+fn set_count(_ruby: &Ruby, reader: &SetReader) -> usize {
+    reader.set.files.len()
+}
+
+/// `[wire_path, model]` for the next file in artifact order, nil at
+/// the end.
+fn set_next(ruby: &Ruby, reader: &SetReader) -> Result<magnus::Value, Error> {
+    let mut index = reader.index.lock().expect("index");
+    if *index >= reader.set.files.len() {
+        return Ok(ruby.qnil().as_value());
+    }
+    let file = &reader.set.files[*index];
+    *index += 1;
+    let wire = file.wire().map_err(|e| {
+        Error::new(ruby.exception_runtime_error(), format!("{}: {e}", file.wire_path))
+    })?;
+    let mut cache = reader.cache.lock().expect("class cache");
+    let model = value_to_ruby(ruby, &mut cache, &wire)?;
+    let pair = RArray::with_capacity(2);
+    pair.push(ruby.str_new(&file.wire_path))?;
+    pair.push(model)?;
+    Ok(pair.as_value())
+}
+
+/// Whether the artifact still matches the given {wire_path => read_path}
+/// sources; nil when a source is unreadable.
+fn set_matches_sources(ruby: &Ruby, reader: &SetReader, read_paths: RHash) -> Result<magnus::Value, Error> {
+    let lookup = |wire_path: &str| -> Option<String> {
+        read_paths
+            .fetch(ruby.str_new(wire_path))
+            .ok()
+            .and_then(|v| String::try_convert(v).ok())
+    };
+    match reader.set.matches_sources(&lookup) {
+        Some(ok) => Ok(ok.into_value()),
+        None => Ok(ruby.qnil().as_value()),
+    }
+}
+
+/// Write a compiled set from Ruby-provided entries —
+/// `[wire_path, source_sha, wire_json]` triples (the post-remark wire
+/// of finalized models, so warm loads skip remark attachment).
+fn set_write(
+    ruby: &Ruby,
+    out_path: String,
+    entries: RArray,
+    expressir_version: String,
+) -> Result<magnus::Value, Error> {
+    let mut files = Vec::with_capacity(entries.len());
+    for index in 0..entries.len() {
+        let triple = RArray::from_value(entries.entry(index as isize)?).ok_or_else(|| {
+            Error::new(
+                ruby.exception_arg_error(),
+                "entries must be [wire_path, source_sha, wire_json] triples",
+            )
+        })?;
+        let wire_path: String = triple.entry(0)?;
+        let source_sha: String = triple.entry(1)?;
+        let wire_json: String = triple.entry(2)?;
+        files.push(CompiledFile {
+            wire_path,
+            source_sha,
+            wire_json,
+        });
+    }
+    let set = CompiledSet::build(files, &expressir_version, &expressir_rs::grammar_digest());
+    set.write_to(&out_path).map_err(|e| {
+        Error::new(
+            ruby.exception_io_error(),
+            format!("compiled set {out_path}: {e}"),
+        )
+    })?;
+    Ok(ruby.str_new(&set.header.set_digest).as_value())
+}
+
+fn value_to_ruby(ruby: &Ruby, cache: &mut ClassCache, wire: &Wire) -> Result<magnus::Value, Error> {
+    match wire {
+        Wire::Null => Ok(ruby.qnil().as_value()),
+        Wire::Bool(b) => Ok(b.into_value()),
+        Wire::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Ok(ruby.integer_from_i64(i).into_value())
+            } else {
+                Ok(ruby.float_from_f64(n.as_f64().unwrap_or(0.0)).into_value())
+            }
+        }
+        Wire::String(s) => Ok(ruby.str_new(s).as_value()),
+        Wire::Array(items) => {
+            let array = ruby.ary_new_capa(items.len());
+            for item in items {
+                array.push(value_to_ruby(ruby, cache, item)?)?;
+            }
+            Ok(array.as_value())
+        }
+        Wire::Object(map) => {
+            let class_name = map.get("_class").and_then(Wire::as_str).ok_or_else(|| {
+                Error::new(
+                    ruby.exception_runtime_error(),
+                    "expressir-core: model node without _class",
+                )
+            })?;
+            let klass = cache.resolve(ruby, class_name)?;
+            let attrs = RHash::new();
+            for (key, item) in map {
+                attrs.aset(ruby.sym_new(key.as_str()), value_to_ruby(ruby, cache, item)?)?;
+            }
+            klass.funcall::<_, _, magnus::Value>("instantiate", (attrs,))
+        }
+    }
+}
+
+fn model_object(ruby: &Ruby, source: String, path: String) -> Result<magnus::Value, Error> {
+    let tree = ParsedTree::parse(&source).map_err(|e| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("expressir-core: parse error: {e:?}"),
+        )
+    })?;
+    let wire = tree.to_model_json(&path).map_err(|e| parse_error(ruby, e))?;
+    let mut cache = ClassCache::default();
+    value_to_ruby(ruby, &mut cache, &wire)
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Expressir")?.define_module("Core")?;
+    module.define_singleton_method("parse_to_model_hash", function!(model_json, 2))?;
+    module.define_singleton_method("parse_to_model", function!(model_object, 2))?;
+    module.define_singleton_method("write_set", function!(set_write, 3))?;
+    let batch_class = module.define_class("BatchStream", ruby.class_object())?;
+    batch_class.define_singleton_method("start", function!(batch_start, 2))?;
+    batch_class.define_method("next", method!(batch_next, 0))?;
+    batch_class.define_method(
+        "write_set",
+        method!(batch_write_set, 3),
+    )?;
+    let set_class = module.define_class("Set", ruby.class_object())?;
+    set_class.define_singleton_method("open", function!(set_open, 1))?;
+    set_class.define_method("digest", method!(set_digest, 0))?;
+    set_class.define_method("count", method!(set_count, 0))?;
+    set_class.define_method("next", method!(set_next, 0))?;
+    set_class.define_method("matches_sources", method!(set_matches_sources, 1))?;
+    Ok(())
+}

data/lib/expressir/cli.rb

@@ -18,17 +18,62 @@ module Expressir
     method_option :provenance, type: :boolean,
                                desc: "Include provenance information (ELF profile only)",
                                default: true
-    def format(path)
+    def format(path, _thor_options = nil)
       Expressir::Commands::Format.new(options).run(path)
     end
 
     desc "clean PATH", "Strip remarks and prettify EXPRESS schema at PATH"
     method_option :output, type: :string,
                            desc: "Output file path (defaults to stdout)"
-    def clean(path)
+    def clean(path, _thor_options = nil)
       Expressir::Commands::Clean.new(options).run(path)
     end
 
+    desc "fix PATH",
+         "Rewrite self-schema-qualified references (#125) in the EXPRESS schema at PATH"
+    method_option :output, type: :string,
+                           aliases: "-o",
+                           desc: "Output file path (defaults to stdout)"
+    def fix(path, _thor_options = nil)
+      Expressir::Commands::Fix.new(options).run(path)
+    end
+
+    desc "expand PATH",
+         "Concatenate the interface closure of PATH into one .exp artifact"
+    method_option :output, type: :string,
+                           aliases: "-o",
+                           desc: "Output file path (defaults to stdout)"
+    method_option :manifest, type: :string,
+                             desc: "ELF schema manifest YAML defining where schemas live " \
+                                   "(primary resolution mode)"
+    method_option :stepmod, type: :string,
+                            desc: "STEPmod checkout root — explicit opt-in to directory-" \
+                                  "convention resolution as the fallback"
+    def expand(path, _thor_options = nil)
+      Expressir::Commands::Expand.new(options).run(path)
+    end
+
+    desc "flatten PATH",
+         "Flatten the interface closure of PATH into an ISO 10303-11:1994 longform schema"
+    method_option :output, type: :string,
+                           aliases: "-o",
+                           desc: "Output file path (defaults to stdout)"
+    method_option :longform_name, type: :string,
+                                  desc: "Longform SCHEMA id (default: <root>_lf)"
+    method_option :extenders, type: :string,
+                              desc: "Extensible type handling: 'all' (default, fold every " \
+                                    "extender in the closure per Annex G.2.3/G.2.4) or " \
+                                    "'none' (leave extensible types as declared)"
+    method_option :manifest, type: :string,
+                             desc: "ELF schema manifest YAML defining where schemas live " \
+                                   "(primary resolution mode)"
+    method_option :stepmod, type: :string,
+                            desc: "STEPmod checkout root — explicit opt-in to directory-" \
+                                  "convention resolution as the fallback"
+    def flatten(path, _thor_options = nil)
+      Expressir::Commands::Flatten.new(options).run(path)
+    end
+
     desc "benchmark FILE_OR_YAML",
          "Benchmark schema loading performance for a file or list of files from YAML"
     method_option :ips, type: :boolean,
@@ -37,7 +82,7 @@ module Expressir
     method_option :save, type: :boolean, desc: "Save benchmark results to file"
     method_option :format, type: :string,
                            desc: "Output format (json, csv, default)"
-    def benchmark(path)
+    def benchmark(path, _thor_options = nil)
       Expressir::Commands::Benchmark.new(options).run(path)
     end
 
@@ -50,7 +95,7 @@ module Expressir
                            desc: "Output format (json, csv, default)"
     method_option :cache_path, type: :string,
                                desc: "Path to store the cache file"
-    def benchmark_cache(path)
+    def benchmark_cache(path, _thor_options = nil)
       Expressir::Commands::BenchmarkCache.new(options).run(path)
     end
 

data/lib/expressir/commands/check.rb

@@ -0,0 +1,56 @@
+require "json"
+
+module Expressir
+  module Commands
+    # `validate check` — semantic checks modeled on eeng check-p11 note
+    # subset (expressir#282). Exits 1 when any :error notes are emitted.
+    # Loads the interface closure of each input file so USE FROM targets
+    # are visible — matches Concatenator/Shtolo expectations.
+    class Check < Base
+      def run(*paths)
+        files = Array(paths).flat_map do |p|
+          if File.directory?(p)
+            Dir["#{p}/**/*.exp"]
+          else
+            ParityInputs.closure_paths(
+              p, manifest: options[:manifest], stepmod: options[:stepmod]
+            ).select { |f| File.exist?(f) }
+          end
+        end.uniq
+        repository = Expressir::Express::Parser.from_files(files)
+        # A file that failed to parse is a nil entry: it must fail the run,
+        # not pass silently as a "clean" schema (#413).
+        failed = repository.files.count(&:nil?)
+        if failed.positive?
+          raise Thor::Error, "#{failed} file(s) failed to parse"
+        end
+
+        result = Expressir::Express::Checker.new(repository).check
+
+        if options[:json]
+          say JSON.generate(
+            valid: result.valid?,
+            errors: serialize(result.errors),
+            warnings: serialize(result.warnings),
+          )
+        else
+          result.notes.each { |n| say "[#{n.severity}] #{n.id}: #{n.message}" }
+          say "#{result.errors.size} error(s), #{result.warnings.size} warning(s)"
+        end
+
+        return if result.valid?
+
+        raise Thor::Error, "schema check produced #{result.errors.size} error(s)"
+      end
+
+      private
+
+      def serialize(notes)
+        notes.map do |n|
+          { id: n.id.to_s, severity: n.severity.to_s, schema: n.schema,
+            message: n.message }
+        end
+      end
+    end
+  end
+end

data/lib/expressir/commands/expand.rb

@@ -0,0 +1,26 @@
+module Expressir
+  module Commands
+    # `expand` — flattens an interface closure into a single concatenated
+    # .exp artifact (expressir#247). Equivalent to eeng's
+    # `--concat_schema` over the root schema's closure.
+    class Expand < Base
+      def run(path)
+        root, repository = ParityInputs.root_schema(
+          path, manifest: options[:manifest], stepmod: options[:stepmod]
+        )
+        exit_with_error "schema for #{path} not found in closure" unless root
+
+        closure = Expressir::Express::Concatenator.closure(root, repository)
+
+        if options[:output]
+          File.open(options[:output], "w") do |io|
+            Expressir::Express::Concatenator.write(io, closure)
+          end
+          say "Concatenated schema written to #{options[:output]}"
+        else
+          Expressir::Express::Concatenator.write($stdout, closure)
+        end
+      end
+    end
+  end
+end

data/lib/expressir/commands/fix.rb

@@ -0,0 +1,33 @@
+module Expressir
+  module Commands
+    # `fix` — rewrites self-schema-qualified references (#125): string
+    # literals like `'THIS_SCHEMA.ITEM'` lose the current-schema prefix
+    # when the item is local, or gain the item's true defining schema
+    # otherwise. Outputs the corrected EXPRESS file.
+    class Fix < Base
+      def run(path)
+        # Load the interface closure (same-dir by default, or --manifest /
+        # --stepmod) so SelfSchemaReference can resolve where each item
+        # truly comes from.
+        files = ParityInputs.closure_paths(
+          path, manifest: options[:manifest], stepmod: options[:stepmod]
+        ).select { |f| File.exist?(f) }
+        repository = Expressir::Express::Parser.from_files(
+          files, skip_references: true
+        )
+        total = repository.schemas.sum do |schema|
+          Expressir::Express::SelfSchemaReference.fix!(schema)
+        end
+
+        text = Expressir::Express::Formatter.format(repository)
+        if options[:output]
+          File.write(options[:output], text)
+          say "#{total} self-schema reference(s) fixed; written to " \
+              "#{options[:output]}"
+        else
+          $stdout.write(text)
+        end
+      end
+    end
+  end
+end

data/lib/expressir/commands/flatten.rb

@@ -0,0 +1,29 @@
+module Expressir
+  module Commands
+    # `flatten` — converts a STEPmod-style multi-schema root into a single
+    # ISO 10303-11:1994 longform schema (SHTOLO, expressir#32).
+    # Equivalent to eeng's `--flat -mode _longform`.
+    class Flatten < Base
+      def run(path)
+        root, repository = ParityInputs.root_schema(
+          path, manifest: options[:manifest], stepmod: options[:stepmod]
+        )
+        exit_with_error "schema for #{path} not found in closure" unless root
+
+        longform_name = options[:longform_name] || "#{root.id}_lf"
+        extenders = options[:extenders] == "none" ? :none : :all
+        flat = Expressir::Express::Shtolo.new(root, repository,
+                                              longform_name: longform_name,
+                                              extenders: extenders).flatten.schema
+        text = Expressir::Express::Formatter.format(flat)
+
+        if options[:output]
+          File.write(options[:output], text)
+          say "Longform schema written to #{options[:output]}"
+        else
+          $stdout.write(text)
+        end
+      end
+    end
+  end
+end