suma 0.5.7 → 0.5.9

data/lib/suma/cli/core.rb

@@ -21,6 +21,27 @@ module Suma
 
       desc "build METANORMA_SITE_MANIFEST",
            "Build collection specified in site manifest (`metanorma*.yml`)"
+      # Mirrors so Core accepts the switches Cli::Build reparses; the inner
+      # class owns their declarations.
+      option :compile, type: :boolean, default: true,
+                       desc: "Compile or skip compile of collection"
+      option :schemas_all_path, type: :string, aliases: "-s",
+                                desc: "Generate file that contains all schemas " \
+                                      "in the collection."
+      option :staged, type: :boolean, default: false,
+                      desc: "Memory-bounded staged build"
+      option :incremental, type: :boolean, default: false,
+                           desc: "Re-render only changed schemas and dependents"
+      option :state_file, type: :string,
+                          desc: "Path to the incremental build state file"
+      option :jobs, type: :numeric, default: 1,
+                    desc: "Concurrent schema export workers"
+      option :provenance, type: :string,
+                          desc: "Write a build provenance manifest"
+      option :sign, type: :string, banner: "METHOD",
+                    desc: "Sign the provenance manifest: minisign or sigstore"
+      option :sign_key, type: :string,
+                        desc: "Signing key (sigstore signs keylessly when omitted)"
       def build(_site_manifest)
         Cli::Build.start
       end
@@ -45,12 +66,18 @@ module Suma
                          "(used for section references)"
       option :language_code, type: :string, default: "eng", aliases: "-l",
                              desc: "Language code for the Glossarist"
+      option :edition, type: :numeric,
+                       desc: "Owning edition recorded on each concept"
+      option :language_codes, type: :array,
+                              desc: "Additional linked localization languages"
       def extract_terms(schema_manifest_file, glossarist_output_path)
         TermExtractor.new(
           schema_manifest_file,
           glossarist_output_path,
           urn: options[:urn],
           language_code: options[:language_code],
+          edition: options[:edition],
+          language_codes: options[:language_codes],
         ).call
       end
 
@@ -66,6 +93,14 @@ module Suma
                              desc: "Language code for section names"
       option :owner, type: :string, default: Suma::RegisterManifestGenerator::DEFAULT_OWNER,
                      desc: "Owner of the dataset (e.g. 'ISO/TC 184/SC 4')"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303 or generic)"
+      option :year, type: :numeric,
+                    desc: "Edition year for the register"
+      option :supersedes, type: :string,
+                          desc: "URN/ref of the superseded edition"
+      option :edition, type: :numeric,
+                       desc: "Edition number (tagged as edition:N)"
       def generate_register(schema_manifest_file, output_path)
         RegisterManifestGenerator.new(
           schema_manifest_file,
@@ -75,6 +110,10 @@ module Suma
           ref: options[:ref],
           language_code: options[:language_code],
           owner: options[:owner],
+          profile: options[:profile],
+          year: options[:year],
+          supersedes: options[:supersedes],
+          edition: options[:edition],
         ).generate
       end
 
@@ -87,6 +126,31 @@ module Suma
       desc "export *FILES",
            "Export EXPRESS schemas from manifest files or " \
            "standalone EXPRESS files"
+      # The inner class reparses ARGV and owns the canonical declarations;
+      # these mirrors exist only so Core accepts the switches it passes
+      # through (Core checks unknown options before dispatch).
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Output directory path"
+      option :annotations, type: :boolean, default: false,
+                           desc: "Include annotations (remarks/comments)"
+      option :zip, type: :boolean, default: false,
+                   desc: "Create ZIP archive of exported schemas"
+      option :publication, type: :string, banner: "SCHEMA_ID",
+                           desc: "Export an AP publication bundle: the " \
+                                 "lead schema plus its transitive " \
+                                 "USE-FROM/REFERENCE closure (manifest " \
+                                 "input only)"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303 or generic)"
+      option :format, type: :string, default: "express", banner: "FORMAT",
+                      desc: "Output format: express (default) or owl"
+      option :corpus, type: :boolean, default: false,
+                      desc: "OWL only: emit one ontology for the whole " \
+                            "manifest instead of one per schema"
+      option :urn, type: :string, banner: "URN",
+                   desc: "OWL only: base URN for IRIs, before the " \
+                         ":tech component " \
+                         "(e.g. urn:iso:std:iso:10303:-2:ed-2:en)"
       def export(*_files)
         Cli::Export.start
       end
@@ -100,6 +164,25 @@ module Suma
       desc "validate SUBCOMMAND ...ARGS", "Validate express documents"
       subcommand "validate", Cli::Validate
 
+      desc "resolve [URN]", "Resolve URNs to canonical JSON + HTML artifacts"
+      # Mirrors so Core accepts the switches Cli::Resolve reparses; the
+      # inner class owns their declarations.
+      option :manifest, type: :string, required: true,
+                        desc: "Schema manifest used for schema/entity URNs"
+      option :urn, type: :string,
+                   desc: "Corpus URN base (defaults to the register URN)"
+      option :concepts, type: :string,
+                        desc: "Directory of Glossarist concept YAML files"
+      option :register, type: :string,
+                        desc: "Glossarist register.yaml (dataset URN)"
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Artifact output directory"
+      option :all, type: :boolean, default: false,
+                   desc: "Emit artifacts for every known URN"
+      def resolve(_urn = nil)
+        Cli::Resolve.start
+      end
+
       desc "check_svg_quality [PATH]",
            "Check SVG quality and sort by severity (critical files first)"
       option :pattern, type: :string, default: Cli::CheckSvgQuality::DEFAULT_PATTERN,

data/lib/suma/cli/export.rb

@@ -14,6 +14,11 @@ module Suma
     # +Suma::SchemaCategory+, the single source of truth. The exporter
     # itself never classifies — it consumes loaded ExpressSchema
     # objects whose output paths were set by this adapter.
+    #
+    # With +--publication SCHEMA_ID+, exports an application-protocol
+    # publication bundle instead: the lead schema plus the transitive
+    # USE-FROM/REFERENCE closure (+Suma::Publication+), written flat
+    # under +<output>/<lead_id>/+.
     class Export < Thor
       desc "export *FILES",
            "Export EXPRESS schemas from manifest files or " \
@@ -24,6 +29,22 @@ module Suma
                            desc: "Include annotations (remarks/comments)"
       option :zip, type: :boolean, default: false,
                    desc: "Create ZIP archive of exported schemas"
+      option :publication, type: :string, banner: "SCHEMA_ID",
+                           desc: "Export an AP publication bundle: the " \
+                                 "lead schema plus its transitive " \
+                                 "USE-FROM/REFERENCE closure (manifest " \
+                                 "input only)"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303 or generic)"
+      option :format, type: :string, default: "express", banner: "FORMAT",
+                      desc: "Output format: express (default) or owl"
+      option :corpus, type: :boolean, default: false,
+                      desc: "OWL only: emit one ontology for the whole " \
+                            "manifest instead of one per schema"
+      option :urn, type: :string, banner: "URN",
+                   desc: "OWL only: base URN for IRIs, before the " \
+                         ":tech component " \
+                         "(e.g. urn:iso:std:iso:10303:-2:ed-2:en)"
 
       def export(*files)
         require "expressir"
@@ -47,8 +68,87 @@ module Suma
       end
 
       def run(files, options)
-        schemas = files.flat_map { |file| build_schemas(file) }
+        format = options[:format].to_s.downcase
+        case format
+        when "express"
+          run_express(files, options)
+        when "owl"
+          run_owl(files, options)
+        else
+          raise ArgumentError, "Unsupported format: #{options[:format]}. " \
+                               "Use express or owl."
+        end
+      end
+
+      def run_express(files, options)
+        schemas = if options[:publication]
+                    publication_bundle(files, options)
+                  else
+                    files.flat_map { |file| build_schemas(file, options) }
+                  end
+        run_exporter(schemas, options)
+      end
+
+      # OWL projection: one Turtle file per schema (under its category
+      # directory, mirroring the EXPRESS export layout). With --corpus a
+      # top-level ontology importing every schema ontology is added
+      # alongside them.
+      def run_owl(files, options)
+        validate_owl_input!(files, options)
+        projection = OwlProjection.new(files.first, urn: options[:urn])
+        if options[:corpus]
+          write_schema_ontologies(projection, files.first)
+          write_ontology(projection, output_root.join("corpus.ttl"),
+                         projection.to_turtle)
+        else
+          write_schema_ontologies(projection, files.first)
+        end
+      end
+
+      def validate_owl_input!(files, options)
+        unless bundle_input?(files)
+          raise ArgumentError,
+                "--format owl requires exactly one schema manifest file " \
+                "(.yml/.yaml) as input"
+        end
+        if options[:publication]
+          raise ArgumentError,
+                "--publication bundles EXPRESS files and cannot be " \
+                "combined with --format owl"
+        end
+        return if options[:urn]
+
+        raise ArgumentError, "--format owl requires --urn BASE_URN"
+      end
+
+      def write_schema_ontologies(projection, manifest_file)
+        manifest = Expressir::SchemaManifest.from_file(manifest_file)
+        manifest.schemas.each do |entry|
+          target = output_root
+            .join(SchemaCategory.for_schema(
+              id: entry.id, path: entry.path,
+              profile: options[:profile]
+            ).directory)
+            .join("#{entry.id}.ttl")
+          write_ontology(projection, target,
+                         projection.to_turtle(schema_id: entry.id),
+                         schema_id: entry.id)
+        end
+      end
+
+      def write_ontology(projection, target, turtle, schema_id: nil)
+        problems = projection.validate(schema_id: schema_id)
+        unless problems.empty?
+          raise Error, "OWL projection of #{target} is invalid: " \
+                       "#{problems.join('; ')}"
+        end
 
+        FileUtils.mkdir_p(target.dirname)
+        File.write(target, turtle)
+        Utils.log "Wrote OWL ontology: #{target}"
+      end
+
+      def run_exporter(schemas, options)
         exporter = SchemaExporter.new(
           schemas: schemas,
           output_path: options[:output],
@@ -57,16 +157,41 @@ module Suma
             create_zip: options[:zip],
           },
         )
-
         exporter.export
       end
 
-      def build_schemas(file)
+      # Build the publication bundle schemas, rooted at
+      # <output>/<lead_id>/ so the AP volume lands in its own directory.
+      def publication_bundle(files, options)
+        validate_bundle_input!(files)
+        lead_id = options[:publication]
+        publication = Publication.new(
+          lead_id: lead_id,
+          schema_manifest_file: files.first,
+          profile: options[:profile],
+        )
+        publication.schemas(output_path: output_root.join(lead_id).to_s)
+      end
+
+      def validate_bundle_input!(files)
+        return if bundle_input?(files)
+
+        raise ArgumentError,
+              "--publication requires exactly one schema manifest file " \
+              "(.yml/.yaml) as input"
+      end
+
+      def bundle_input?(files)
+        files.length == 1 &&
+          %w[.yml .yaml].include?(File.extname(files.first).downcase)
+      end
+
+      def build_schemas(file, options)
         case File.extname(file).downcase
         when ".yml", ".yaml"
-          build_from_manifest(file)
+          build_from_manifest(file, options)
         when ".exp"
-          [build_standalone(file)]
+          [build_standalone(file, options)]
         else
           raise ArgumentError, "Unsupported file type: #{file}. " \
                                "Only .yml, .yaml, and .exp files are " \
@@ -74,27 +199,32 @@ module Suma
         end
       end
 
-      def build_from_manifest(file)
+      def build_from_manifest(file, options)
         manifest = Expressir::SchemaManifest.from_file(file)
-        manifest.schemas.map { |entry| build_from_manifest_entry(entry) }
+        manifest.schemas.map do |entry|
+          build_from_manifest_entry(entry, options)
+        end
       end
 
-      def build_from_manifest_entry(entry)
-        category = SchemaCategory.for_schema(id: entry.id, path: entry.path)
+      def build_from_manifest_entry(entry, options)
+        category = SchemaCategory.for_schema(id: entry.id, path: entry.path,
+                                             profile: options[:profile])
         ExpressSchema.new(
           id: entry.id,
           path: entry.path.to_s,
           output_path: output_root.join(category.directory).to_s,
           is_standalone_file: false,
+          profile: options[:profile],
         )
       end
 
-      def build_standalone(exp_file)
+      def build_standalone(exp_file, options)
         ExpressSchema.new(
           id: nil,
           path: File.expand_path(exp_file),
           output_path: output_root.to_s,
           is_standalone_file: true,
+          profile: options[:profile],
         )
       end
 

data/lib/suma/cli/extract_terms.rb

@@ -13,6 +13,14 @@ module Suma
       option :urn, type: :string, required: true, aliases: "-u",
                    desc: "URN for the dataset source " \
                          "(used for section references)"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303 or generic)"
+      option :edition, type: :numeric,
+                       desc: "Owning edition recorded on each concept"
+      option :language_codes, type: :array,
+                              desc: "Additional linked localization " \
+                                    "languages (the primary language is " \
+                                    "always included)"
 
       def extract_terms(schema_manifest_file, output_path)
         TermExtractor.new(
@@ -20,6 +28,9 @@ module Suma
           output_path,
           language_code: options[:language_code],
           urn: options[:urn],
+          profile: options[:profile],
+          edition: options[:edition],
+          language_codes: options[:language_codes],
         ).call
       end
     end

data/lib/suma/cli/generate_register.rb

@@ -17,6 +17,14 @@ module Suma
                    desc: "Human-readable reference label"
       option :owner, type: :string, default: Suma::RegisterManifestGenerator::DEFAULT_OWNER,
                      desc: "Owner of the dataset (e.g. 'ISO/TC 184/SC 4')"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303 or generic)"
+      option :year, type: :numeric,
+                    desc: "Edition year for the register"
+      option :supersedes, type: :string,
+                          desc: "URN/ref of the superseded edition"
+      option :edition, type: :numeric,
+                       desc: "Edition number (tagged as edition:N)"
 
       def generate_register(schema_manifest_file, output_path)
         RegisterManifestGenerator.new(
@@ -27,6 +35,10 @@ module Suma
           ref: options[:ref],
           language_code: options[:language_code],
           owner: options[:owner],
+          profile: options[:profile],
+          year: options[:year],
+          supersedes: options[:supersedes],
+          edition: options[:edition],
         ).generate
       end
     end

data/lib/suma/cli/resolve.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Suma
+  module Cli
+    # Resolve command: emit canonical JSON + HTML artifacts for URNs.
+    class Resolve < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "resolve URN", "Resolve a URN to canonical JSON + HTML artifacts"
+      option :manifest, type: :string, required: true,
+                        desc: "Schema manifest used for schema/entity URNs"
+      option :urn, type: :string,
+                   desc: "Corpus URN base (defaults to the register URN)"
+      option :concepts, type: :string,
+                        desc: "Directory of Glossarist concept YAML files"
+      option :register, type: :string,
+                        desc: "Glossarist register.yaml (dataset URN)"
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Artifact output directory"
+      option :all, type: :boolean, default: false,
+                   desc: "Emit artifacts for every known URN"
+      def resolve(urn = nil)
+        resolver = UrnResolver.new(
+          manifest_file: options[:manifest],
+          urn: options[:urn],
+          concepts_dir: options[:concepts],
+          register_file: options[:register],
+        )
+
+        if options[:all]
+          resolver.write(options[:output])
+        elsif urn
+          resolver.write_urn(urn, options[:output])
+          Utils.log "Resolved #{urn}"
+        else
+          raise ArgumentError, "provide a URN or use --all"
+        end
+      end
+    end
+  end
+end

data/lib/suma/cli/validate.rb

@@ -26,6 +26,22 @@ module Suma
         puts LinkValidation.generate_summary(result)
       end
 
+      desc "closure SCHEMAS_MANIFEST [DOCUMENTS_PATH]",
+           "Validate referential closure: every EXPRESS-internal reference " \
+           "resolves; optionally merge documentation-layer link failures"
+      option :format, type: :string, default: "terminal",
+                      desc: "Report format: terminal, json, yaml"
+      def closure(schemas_manifest_file, documents_path = nil)
+        graph = CorpusGraph.from_manifest(schemas_manifest_file)
+        violations = ClosureValidator.new(graph)
+          .validate_manifest(schemas_manifest_file)
+        if documents_path
+          violations += documentation_violations(schemas_manifest_file,
+                                                 documents_path)
+        end
+        emit_closure_report(violations)
+      end
+
       desc "mappings DOCUMENTS_PATH",
            "Validate module mapping.yaml links and reference paths " \
            "against the parsed module corpus; only NEW drift " \
@@ -48,6 +64,80 @@ module Suma
 
       private
 
+      # Print the closure report and raise on any unresolved reference.
+      def emit_closure_report(violations)
+        if violations.empty?
+          puts closure_success_message
+          return
+        end
+
+        puts format_closure_report(violations)
+        raise Thor::Error,
+              "Referential closure failed: #{violations.size} unresolved " \
+              "reference(s)"
+      end
+
+      def closure_success_message
+        case options[:format]
+        when "json"
+          require "json"
+          { "violations" => [] }.to_json
+        when "yaml"
+          require "yaml"
+          { "violations" => [] }.to_yaml
+        else
+          "Referential closure OK: all references resolve."
+        end
+      end
+
+      def format_closure_report(violations)
+        case options[:format]
+        when "json"
+          require "json"
+          { "violations" => violations.map(&:to_h) }.to_json
+        when "yaml"
+          require "yaml"
+          { "violations" => violations.map(&:to_h) }.to_yaml
+        else
+          violations.map { |v| format_closure_line(v) }
+            .sort
+            .join("\n")
+        end
+      end
+
+      def format_closure_line(violation)
+        location = [violation.file, violation.line].compact.join(":")
+        "[#{violation.kind}] #{violation.schema_id}/#{violation.owner_id} " \
+          "#{violation.reference} (#{location}) — #{violation.reason}"
+      end
+
+      # Merge documentation-layer link failures into the closure report:
+      # the same unresolved-reference predicate, applied by the doc-layer
+      # extractor.
+      def documentation_violations(schemas_file, documents_path)
+        result = LinkValidation.new(
+          schemas_file: schemas_file,
+          documents_path: documents_path,
+          output_file: nil,
+        ).call
+        result.unresolved.map { |issue| documentation_violation(issue) }
+      rescue StandardError => e
+        Utils.log "documentation-layer validation skipped: #{e.message}"
+        []
+      end
+
+      def documentation_violation(issue)
+        ClosureValidator::UnresolvedReference.new(
+          file: issue.file.to_s,
+          line: issue.line,
+          schema_id: issue.link.to_s.split(".").first,
+          owner_id: "(documentation)",
+          kind: "documentation",
+          reference: issue.link,
+          reason: issue.reason,
+        )
+      end
+
       def default_baseline_path(documents_path)
         File.join(documents_path, "mapping-drift-baseline.yml")
       end

data/lib/suma/cli.rb

@@ -12,6 +12,7 @@ module Suma
     autoload :GenerateRegister, "suma/cli/generate_register"
     autoload :GenerateSchemas,  "suma/cli/generate_schemas"
     autoload :Reformat,         "suma/cli/reformat"
+    autoload :Resolve,          "suma/cli/resolve"
     autoload :Validate,         "suma/cli/validate"
     autoload :ValidateLinks,    "suma/cli/validate_links"
   end