suma 0.5.6 → 0.5.8

data/lib/suma/build_plan.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "fileutils"
+
+module Suma
+  # Decides which schemas an incremental build must re-render.
+  #
+  # The state is a map of schema id → sha256 of its source. A schema is
+  # changed when its digest differs from the previous build; rendering is
+  # required for every changed schema plus all transitive dependents, because
+  # a dependent's cross-references and rendered anchors may shift. The
+  # dependents come from the corpus graph (S1), the same USE/REFERENCE edges
+  # that drive change impact (S3).
+  class BuildPlan
+    # @param entries [Array<#id,#path>] schema manifest entries
+    # @param graph [CorpusGraph]
+    # @param previous_state [Hash{String=>String}] digest per schema id
+    def initialize(entries:, graph:, previous_state: {})
+      @entries = entries
+      @graph = graph
+      @previous_state = previous_state || {}
+      @ids_by_key = entries.to_h { |entry| [entry.id.downcase, entry.id] }
+    end
+
+    # @return [Array<String>] declared ids whose source differs since the
+    #   previous build (all ids on a first build)
+    def changed
+      current_state.reject do |id, digest|
+        @previous_state[id] == digest
+      end.keys
+    end
+
+    # @return [Array<String>] schemas to re-render: every changed schema plus
+    #   its transitive dependents; empty when nothing changed
+    def rebuild
+      changed_ids = changed
+      return [] if changed_ids.empty?
+
+      expanded = changed_ids.flat_map do |id|
+        [id] + @graph.dependents_of(id).map { |key| @ids_by_key[key] || key }
+      end
+      expanded.uniq
+    end
+
+    # @return [Hash{String=>String}] digest per schema id
+    def current_state
+      @current_state ||= @entries.to_h do |entry|
+        [entry.id, Digest::SHA256.file(entry.path.to_s).hexdigest]
+      end
+    end
+
+    # Persist the current state for the next incremental build.
+    def self.write_state(path, state)
+      FileUtils.mkdir_p(File.dirname(path))
+      temp = "#{path}.#{Process.pid}.tmp"
+      File.write(temp, JSON.pretty_generate(state))
+      File.rename(temp, path)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+
+    # @return [Hash{String=>String}] the previous state, empty when absent
+    def self.read_state(path)
+      return {} unless path && File.exist?(path)
+
+      JSON.parse(File.read(path))
+    end
+  end
+end

data/lib/suma/change_classification.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Suma
+  # The typed change taxonomy (S3): every schema change is classified as
+  # additive, compatible, breaking, or editorial.
+  #
+  # The mapping is data — a frozen Hash keyed by the eengine action — so a
+  # finer-grained rule is a one-line addition. Modifications are classified
+  # as breaking conservatively: eengine reports structural deltas (type
+  # changes, attribute additions on entities, interface changes) without
+  # enough detail to prove backwards compatibility, so additive/editorial
+  # claims are only made where the action itself guarantees them.
+  class ChangeClassification
+    ADDITIVE = "additive"
+    COMPATIBLE = "compatible"
+    BREAKING = "breaking"
+    EDITORIAL = "editorial"
+
+    BY_ACTION = {
+      "added" => ADDITIVE,
+      "removed" => BREAKING,
+      "modified" => BREAKING,
+      "mapping" => EDITORIAL,
+    }.freeze
+
+    ALL = [ADDITIVE, COMPATIBLE, BREAKING, EDITORIAL].freeze
+
+    # @param action [String, Symbol] added / removed / modified / mapping
+    # @return [String] one of ALL
+    def self.classify(action:)
+      BY_ACTION.fetch(action.to_s) do
+        raise Error, "[suma] unknown change action #{action.inspect} " \
+                     "(known: #{BY_ACTION.keys.sort.join(', ')})"
+      end
+    end
+  end
+end

data/lib/suma/change_impact.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "expressir"
+require "pathname"
+
+module Suma
+  # Change-impact analysis (S3): given a changed schema, which schemas and
+  # AP publications are affected?
+  #
+  # Walks the reverse interface closure of the CorpusGraph, so the answer
+  # is transitive: every schema that USEs FROM the changed schema directly
+  # or through other schemas is reported, and every AP publication whose
+  # dependency closure contains the changed schema is flagged.
+  class ChangeImpact
+    attr_reader :graph, :schema_manifest_file
+
+    # @param graph [CorpusGraph]
+    # @param schema_manifest_file [String] corpus manifest, for AP detection
+    def initialize(graph, schema_manifest_file)
+      @graph = graph
+      @schema_manifest_file = schema_manifest_file
+    end
+
+    # @param schema_id [String] the changed schema
+    # @return [Array<String>] transitively affected schema ids
+    def affected_schemas(schema_id)
+      graph.dependents_of(schema_id)
+    end
+
+    # @param schema_id [String] the changed schema
+    # @return [Array<String>] AP publication leads whose closure includes it
+    def affected_publications(schema_id)
+      target = schema_id.to_s.downcase
+      application_protocol_ids.select do |lead|
+        graph.dependency_closure(lead).include?(target)
+      end.sort
+    end
+
+    # @param schema_id [String]
+    # @return [Hash]
+    def report(schema_id)
+      {
+        "schema" => schema_id,
+        "affected_schemas" => affected_schemas(schema_id),
+        "affected_publications" => affected_publications(schema_id),
+      }
+    end
+
+    private
+
+    def application_protocol_ids
+      manifest = Expressir::SchemaManifest.from_file(
+        File.expand_path(schema_manifest_file),
+      )
+      manifest.schemas.select do |entry|
+        SchemaCategory.for_schema(id: entry.id, path: entry.path) ==
+          SchemaCategory::APPLICATION_PROTOCOLS
+      end.map { |entry| entry.id.downcase }
+    end
+  end
+end

data/lib/suma/change_manifest.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "expressir/changes"
+
+module Suma
+  # One typed change entry: which element changed, how, and whether the
+  # change is additive/compatible/breaking/editorial.
+  class ChangeEntry < Lutaml::Model::Serializable
+    attribute :element, :string
+    attribute :element_type, :string
+    attribute :action, :string
+    attribute :classification, :string
+    attribute :description, :string, collection: true
+
+    yaml do
+      map "element", to: :element
+      map "element_type", to: :element_type
+      map "action", to: :action
+      map "classification", to: :classification
+      map "description", to: :description
+    end
+  end
+
+  # The typed change manifest for one schema edition pair (S3): the
+  # machine-readable companion to eengine's .changes.yaml.
+  #
+  # Built from the Expressir::Changes::SchemaChange model (the same model
+  # the .changes.yaml embodies), adding the classification dimension and a
+  # rendered changelog.
+  class ChangeManifest < Lutaml::Model::Serializable
+    attribute :schema, :string
+    attribute :version, :integer
+    attribute :entries, ChangeEntry, collection: true
+
+    yaml do
+      map "schema", to: :schema
+      map "version", to: :version
+      map "entries", to: :entries
+    end
+
+    class << self
+      # Build a manifest from a SchemaChange model.
+      #
+      # @param change [Expressir::Changes::SchemaChange]
+      # @param version [Integer, String, nil] version to select
+      #   (default: the latest)
+      # @return [ChangeManifest]
+      def from_schema_change(change, version: nil)
+        selected = select_version(change.versions, version)
+        return new(schema: change.schema) if selected.nil?
+
+        new(
+          schema: change.schema,
+          version: selected.version,
+          entries: entries_for(selected),
+        )
+      end
+
+      # Build a manifest from a .changes.yaml file.
+      #
+      # @param path [String]
+      # @param version [Integer, String, nil]
+      # @return [ChangeManifest]
+      def from_file(path, version: nil)
+        from_schema_change(
+          Expressir::Changes::SchemaChange.from_file(path),
+          version: version,
+        )
+      end
+
+      private
+
+      def select_version(versions, version)
+        return versions.last if version.nil?
+
+        versions.find { |candidate| candidate.version == version.to_i }
+      end
+
+      def entries_for(version_change)
+        entries = []
+        entries.concat(item_entries(version_change.additions, "added"))
+        entries.concat(item_entries(version_change.modifications, "modified"))
+        entries.concat(item_entries(version_change.deletions, "removed"))
+        entries.concat(mapping_entries(version_change.mappings))
+        entries.concat(mapping_entries(version_change.changes))
+        entries
+      end
+
+      def item_entries(items, action)
+        Array(items).map do |item|
+          ChangeEntry.new(
+            element: item.name,
+            element_type: item.type,
+            action: action,
+            classification: ChangeClassification.classify(action: action),
+            description: Array(item.description),
+          )
+        end
+      end
+
+      def mapping_entries(mappings)
+        Array(mappings).map do |mapping|
+          ChangeEntry.new(
+            element: mapping.name,
+            element_type: "MAPPING",
+            action: "mapping",
+            classification: ChangeClassification::EDITORIAL,
+            description: [mapping.description].compact,
+          )
+        end
+      end
+    end
+
+    # Counts per classification.
+    #
+    # @return [Hash{String => Integer}]
+    def summary
+      entries.group_by(&:classification)
+        .transform_values(&:size)
+        .sort.to_h
+    end
+
+    # @return [Boolean]
+    def breaking?
+      entries.any? do |entry|
+        entry.classification == ChangeClassification::BREAKING
+      end
+    end
+
+    # Render a markdown changelog section.
+    #
+    # @return [String]
+    def to_changelog
+      lines = ["## Schema `#{schema}` — version #{version}", ""]
+      entries.sort_by { |entry| [entry.classification, entry.element.to_s] }
+        .each do |entry|
+        lines << "- **#{entry.classification}** — #{entry.element_type} " \
+                 "`#{entry.element}` #{entry.action}"
+        Array(entry.description).each do |description|
+          lines << "  - #{description}"
+        end
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/suma/cli/build.rb

@@ -16,6 +16,23 @@ module Suma
                       desc: "Memory-bounded staged build: compile each member in " \
                             "its own process (sequential) and reinflate. For large " \
                             "collections that OOM a single-process build (suma#94)."
+      option :incremental, type: :boolean, default: false,
+                           desc: "Re-render only changed schemas and their " \
+                                 "transitive dependents (state file defaults " \
+                                 "to plain_schemas/.suma-build-state.json)"
+      option :state_file, type: :string,
+                          desc: "Path to the incremental build state file"
+      option :jobs, type: :numeric, default: 1,
+                    desc: "Concurrent schema export workers (document " \
+                          "compilation remains sequential)"
+      option :provenance, type: :string,
+                          desc: "Write a provenance manifest (sha256 of inputs " \
+                                "and outputs + toolchain versions) to this path"
+      option :sign, type: :string, banner: "METHOD",
+                    desc: "Sign the provenance manifest: minisign or sigstore"
+      option :sign_key, type: :string,
+                        desc: "Signing key (minisign requires it; sigstore " \
+                              "signs keylessly when omitted)"
 
       def build(metanorma_site_manifest)
         unless File.exist?(metanorma_site_manifest)
@@ -39,6 +56,12 @@ module Suma
           compile: options[:compile],
           output_directory: "_site",
           staged: options[:staged],
+          incremental: options[:incremental],
+          state_file: options[:state_file],
+          jobs: options[:jobs],
+          provenance_file: options[:provenance],
+          sign_method: options[:sign],
+          sign_key: options[:sign_key],
         ).run
       end
 

data/lib/suma/cli/compare.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 require "thor"
 
 module Suma
@@ -39,6 +41,16 @@ module Suma
                                  desc: "Override auto-detected reference repo root"
       option :verbose, type: :boolean, default: false,
                        desc: "Enable verbose output"
+      option :typed_output, type: :string, banner: "FILE",
+                            desc: "Write the typed ChangeManifest " \
+                                  "(classification + descriptions) as YAML"
+      option :changelog, type: :boolean, default: false,
+                         desc: "Print a markdown changelog for the changes"
+      option :impact, type: :boolean, default: false,
+                      desc: "Print affected schemas and AP publications " \
+                            "(requires --manifest)"
+      option :manifest, type: :string, banner: "SCHEMAS_YAML",
+                        desc: "Corpus schema manifest, for --impact"
 
       def compare(trial_schema, reference_schema)
         comparer = SchemaComparer.new(trial_schema, reference_schema, options)
@@ -47,12 +59,47 @@ module Suma
 
         if result.nil?
           say "No changes detected between schemas", :yellow
-        else
-          say "Change YAML file: #{result}", :green
+          return
         end
+
+        say "Change YAML file: #{result}", :green
+        report_typed_changes(result, trial_schema)
       rescue Suma::Error => e
         raise Thor::Error, e.message
       end
+
+      private
+
+      def report_typed_changes(change_yaml, trial_schema)
+        manifest = ChangeManifest.from_file(change_yaml,
+                                            version: options[:version])
+        write_typed_output(manifest)
+        say manifest.to_changelog if options[:changelog]
+        print_impact(manifest, trial_schema) if options[:impact]
+      end
+
+      def write_typed_output(manifest)
+        path = options[:typed_output]
+        return unless path
+
+        File.write(path, manifest.to_yaml)
+        say "Typed change manifest: #{path}", :green
+      end
+
+      def print_impact(manifest, trial_schema)
+        unless options[:manifest]
+          raise Thor::Error, "--impact requires --manifest SCHEMAS_YAML"
+        end
+
+        graph = CorpusGraph.from_manifest(options[:manifest])
+        impact = ChangeImpact.new(graph, options[:manifest])
+          .report(changed_schema_id(manifest, trial_schema))
+        say impact.to_yaml
+      end
+
+      def changed_schema_id(manifest, trial_schema)
+        manifest.schema || File.basename(trial_schema, ".exp")
+      end
     end
   end
 end

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,