suma 0.5.9 → 0.5.10

data/lib/suma/cli/extract_terms.rb

@@ -14,7 +14,7 @@ module Suma
                    desc: "URN for the dataset source " \
                          "(used for section references)"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :edition, type: :numeric,
                        desc: "Owning edition recorded on each concept"
       option :language_codes, type: :array,

data/lib/suma/cli/generate_register.rb

@@ -18,7 +18,7 @@ module Suma
       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)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :year, type: :numeric,
                     desc: "Edition year for the register"
       option :supersedes, type: :string,

data/lib/suma/cli/ingest_translations.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Suma
+  module Cli
+    # Ingest translated localized-concept content into extracted concepts.
+    class IngestTranslations < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "ingest_translations CONCEPTS_DIR TRANSLATIONS_FILE",
+           "Overlay translated localized-concept content onto extracted " \
+           "Glossarist concepts; fields the translations omit fall back " \
+           "to the source-language content"
+      option :output, type: :string, aliases: "-o",
+                      desc: "Write updated concepts here (default: " \
+                            "update CONCEPTS_DIR in place)"
+
+      def ingest_translations(concepts_dir, translations_file)
+        unless File.file?(translations_file)
+          raise Errno::ENOENT, translations_file
+        end
+
+        applied = TranslationIngester.new(
+          concepts_dir: concepts_dir,
+          translations: translations_file,
+          output_dir: options[:output],
+        ).ingest
+        Utils.log "Applied #{applied.values.sum(&:size)} translation(s) " \
+                  "to #{applied.size} concept(s)."
+      end
+    end
+  end
+end

data/lib/suma/cli/package_gcr.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Suma
+  module Cli
+    # Package extracted concepts into a GCR archive for the Vocabulary
+    # Browser.
+    class PackageGcr < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "package_gcr CONCEPTS_DIR",
+           "Package extracted Glossarist concepts into a .gcr archive"
+      option :register, type: :string, required: true,
+                        desc: "register.yaml (dataset identity)"
+      option :shortname, type: :string, required: true,
+                         desc: "Dataset id (matches datasets.yml `id`)"
+      option :version, type: :string, required: true,
+                       desc: "Semver of this dataset release"
+      option :title, type: :string, required: true,
+                     desc: "Human-readable dataset title"
+      option :description, type: :string, required: true,
+                           desc: "Dataset description"
+      option :created_at, type: :string,
+                          desc: "Package timestamp (ISO 8601); pin for " \
+                                "reproducible archives"
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Output directory for the .gcr archives"
+
+      def package_gcr(concepts_dir)
+        GcrPackage.new(
+          concepts_dir: concepts_dir,
+          register_file: options[:register],
+          shortname: options[:shortname],
+          version: options[:version],
+          title: options[:title],
+          description: options[:description],
+          created_at: pinned_time,
+        ).write(options[:output])
+      end
+
+      private
+
+      def pinned_time
+        options[:created_at] && Time.iso8601(options[:created_at])
+      end
+    end
+  end
+end

data/lib/suma/cli/validate.rb

@@ -62,6 +62,22 @@ module Suma
         fail_on_new_drift(*drift.check(path), path)
       end
 
+      desc "anchors SCHEMA_DOCS_PATH",
+           "Validate rendered schema docs: every Expressir cross-reference " \
+           "and in-page link resolves to an anchor in its HTML"
+      def anchors(schema_docs_path = "schema_docs")
+        violations = AnchorValidator.new(schema_docs_path).validate
+        if violations.empty?
+          puts "All anchors resolve: no dead links."
+          return
+        end
+
+        puts violations.map { |v| "#{v.file}: #{v.link} — #{v.reason}" }
+          .join("\n")
+        raise Thor::Error,
+              "Anchor validation failed: #{violations.size} dead link(s)"
+      end
+
       private
 
       # Print the closure report and raise on any unresolved reference.

data/lib/suma/cli.rb

@@ -2,7 +2,8 @@
 
 module Suma
   module Cli
-    autoload :Core,             "suma/cli/core"
+    autoload :Core, "suma/cli/core"
+    autoload :ArtifactServerCli, "suma/cli/artifact_server_cli"
     autoload :Build,            "suma/cli/build"
     autoload :CheckSvgQuality,  "suma/cli/check_svg_quality"
     autoload :Compare,          "suma/cli/compare"
@@ -11,6 +12,8 @@ module Suma
     autoload :ExtractTerms,     "suma/cli/extract_terms"
     autoload :GenerateRegister, "suma/cli/generate_register"
     autoload :GenerateSchemas,  "suma/cli/generate_schemas"
+    autoload :IngestTranslations, "suma/cli/ingest_translations"
+    autoload :PackageGcr,       "suma/cli/package_gcr"
     autoload :Reformat,         "suma/cli/reformat"
     autoload :Resolve,          "suma/cli/resolve"
     autoload :Validate,         "suma/cli/validate"

data/lib/suma/closure_validator.rb

@@ -15,9 +15,11 @@ module Suma
   # and inter-schema interfaces.
   #
   # A reference resolves against, in order: the enclosing schema's declared
-  # elements, elements of schemas it interfaces to, the enclosing entity's
-  # own attributes (for entity-scoped expressions), the enclosing rule's
-  # applies-to attributes and variables, and the EXPRESS builtin vocabulary.
+  # elements, elements of schemas it interfaces to (with USE-FROM cascade),
+  # the enclosing entity's own and inherited attributes (for entity-scoped
+  # expressions), the enclosing rule's applies-to attributes and variables,
+  # QUERY-bound variables, and the EXPRESS builtin vocabulary. Attribute
+  # accesses (var.attr) are not schema-level references and are excluded.
   #
   # The predicate is zero-tolerance: any unresolved reference is a
   # violation, and `violations.empty?` is the corpus well-formedness gate.
@@ -56,10 +58,18 @@ module Suma
       manifest = Expressir::SchemaManifest.from_file(
         File.expand_path(manifest_file),
       )
-      manifest.schemas.flat_map do |entry|
-        repo = Expressir::Express::Parser.from_file(entry.path.to_s)
+      parsed = manifest.schemas.map do |entry|
+        [entry, Expressir::Express::Parser.from_file(entry.path.to_s)]
+      end
+      corpus_entities = parsed.flat_map { |_, repo| repo.schemas }
+        .flat_map do |schema|
+          schema.children.grep(Expressir::Model::Declarations::Entity)
+        end
+        .to_h { |entity| [entity.id.downcase, entity] }
+
+      parsed.flat_map do |entry, repo|
         repo.schemas.flat_map do |schema|
-          validate_schema(entry.path.to_s, schema)
+          validate_schema(entry.path.to_s, schema, corpus_entities)
         end
       end
     end
@@ -68,10 +78,14 @@ module Suma
     #
     # @param file [String] source file path (for diagnostics)
     # @param schema [Expressir::Model::Declarations::Schema]
+    # @param corpus_entities [Hash{String=>Entity}] every entity of the
+    #   corpus by downcased id, for cross-schema attribute inheritance
     # @return [Array<UnresolvedReference>]
-    def validate_schema(file, schema)
+    def validate_schema(file, schema, corpus_entities = {})
       violations = []
       scope = SchemaScope.new(schema, graph)
+      entities = schema.children.grep(Expressir::Model::Declarations::Entity)
+        .to_h { |entity| [entity.id.downcase, entity] }
 
       schema.interfaces.each do |interface|
         next if graph.schema_exists?(interface.schema.id)
@@ -83,7 +97,8 @@ module Suma
 
       schema.children.each do |owner|
         violations.concat(declared_element_references(file, schema.id, owner,
-                                                      scope))
+                                                      scope, entities,
+                                                      corpus_entities))
       end
       violations
     end
@@ -91,8 +106,9 @@ module Suma
     private
 
     # Type- and structure-position references of one declared element.
-    def declared_element_references(file, schema_id, owner, scope)
-      refs = typed_references(owner)
+    def declared_element_references(file, schema_id, owner, scope, entities,
+                                    corpus_entities)
+      refs = typed_references(owner, entities, corpus_entities)
       refs.filter_map do |(kind, identifier)|
         if resolvable?(identifier, scope)
           nil
@@ -107,11 +123,13 @@ module Suma
     end
 
     # (kind, identifier) pairs from every position of one declaration.
-    def typed_references(owner)
+    def typed_references(owner, entities, corpus_entities)
       case owner
-      when Expressir::Model::Declarations::Entity then entity_references(owner)
+      when Expressir::Model::Declarations::Entity
+        entity_references(owner, entities, corpus_entities)
       when Expressir::Model::Declarations::Type then type_references(owner)
-      when Expressir::Model::Declarations::Rule then rule_references(owner)
+      when Expressir::Model::Declarations::Rule
+        rule_references(owner)
       when Expressir::Model::Declarations::Constant
         datatype_references(owner.type, "constant")
       when Expressir::Model::Declarations::Function
@@ -122,9 +140,10 @@ module Suma
       end
     end
 
-    def entity_references(entity)
+    def entity_references(entity, entities, corpus_entities)
+      locals = attribute_scope(entity, entities, corpus_entities)
       refs = (entity.where_rules || []).flat_map do |rule|
-        expression_references(rule.expression, "where")
+        expression_references(rule.expression, "where", locals)
       end
       entity.attributes.each do |attribute|
         refs.concat(datatype_references(attribute.type, "attribute"))
@@ -141,8 +160,11 @@ module Suma
 
     def rule_references(rule)
       refs = rule.applies_to.map { |ref| ["rule_applies_to", ref.id] }
+      locals = Array(rule.variables).filter_map do |variable|
+        variable.id&.downcase
+      end
       refs += (rule.where_rules || []).flat_map do |where|
-        expression_references(where.expression, "where")
+        expression_references(where.expression, "where", locals)
       end
       refs += (rule.variables || []).flat_map do |variable|
         datatype_references(variable.type, "variable")
@@ -162,8 +184,20 @@ module Suma
 
     def subtype_constraint_references(constraint)
       refs = []
-      refs << ["subtype_constraint", constraint.entity.id] if constraint.entity
-      refs.concat(supertype_references(constraint))
+      if constraint.applies_to.is_a?(Expressir::Model::References::SimpleReference)
+        refs << ["subtype_constraint", constraint.applies_to.id]
+      end
+      Array(constraint.total_over).each do |ref|
+        next unless ref.is_a?(Expressir::Model::References::SimpleReference)
+
+        refs << ["total_over", ref.id]
+      end
+      if constraint.supertype_expression
+        refs.concat(
+          expression_references(constraint.supertype_expression, "supertype"),
+        )
+      end
+      refs
     end
 
     def supertype_references(owner)
@@ -183,14 +217,84 @@ module Suma
       expression_references(node, kind)
     end
 
-    def expression_references(node, kind)
+    def expression_references(node, kind, locals = [])
+      scoped = locals + query_variables(node) +
+        attribute_access_identifiers(node)
       refs = []
       walk(node) do |child|
-        refs << [kind, child.id] if simple_reference?(child)
+        next unless simple_reference?(child)
+        next if child.id == "?"
+        next if scoped.include?(child.id.to_s.downcase)
+
+        refs << [kind, child.id]
       end
       refs
     end
 
+    # QUERY expressions bind their variable inside the query; collect every
+    # bound variable name in the tree so the walk can skip them.
+    def query_variables(node)
+      found = []
+      walk(node) do |child|
+        if child.is_a?(Expressir::Model::Expressions::QueryExpression) &&
+            child.id
+          found << child.id.to_s.downcase
+        end
+      end
+      found
+    end
+
+    # Attribute accesses (var.attr, SELF\entity.attr) resolve against the
+    # base value's type, not the schema — neither the accessed attribute
+    # nor the base identifier is a schema-level reference.
+    def attribute_access_identifiers(node)
+      found = []
+      walk(node) do |child|
+        next unless child.is_a?(Expressir::Model::References::AttributeReference)
+
+        collect_access_identifier(found, child.ref)
+        collect_access_identifier(found, child.attribute)
+      end
+      found
+    end
+
+    def collect_access_identifier(found, part)
+      return unless part.is_a?(Expressir::Model::References::SimpleReference)
+      return unless part.id
+
+      found << part.id.to_s.downcase
+    end
+
+    # Bare identifiers in an entity's expressions resolve against the
+    # entity's own attributes and those inherited through its supertype
+    # chain, following subtypes across schemas when the parent entity is
+    # in the corpus (name-keyed; EXPRESS entity names are schema-scoped,
+    # but cross-schema parents resolve through interface visibility, so
+    # the name is the identity the child's source references).
+    def attribute_scope(entity, entities, corpus_entities)
+      names = []
+      queue = [entity]
+      seen = {}
+      until queue.empty?
+        current = queue.shift
+        key = current.id.to_s.downcase
+        next if seen[key]
+
+        seen[key] = true
+        Array(current.attributes).each do |attribute|
+          names << attribute.id.downcase if attribute.id
+        end
+        supertype_references(current).each do |(kind, name)|
+          next unless kind == "subtype_of"
+
+          parent = entities[name.downcase] ||
+            corpus_entities[name.downcase]
+          queue << parent if parent
+        end
+      end
+      names
+    end
+
     def simple_reference?(node)
       node.is_a?(Expressir::Model::References::SimpleReference) &&
         !node.id.nil?

data/lib/suma/corpus_graph.rb

@@ -13,6 +13,12 @@ module Suma
   # change-impact analysis (S3) and dependency-driven builds (S6). Nodes are
   # schemas and their declared elements; edges are USE/REFERENCE interfaces.
   class CorpusGraph
+    # One USE/REFERENCE import: the target schema, its kind, and the named
+    # items (renames already applied — the visible name is +items+).
+    InterfaceEdge = Struct.new(:kind, :target, :items, keyword_init: true)
+
+    EMPTY_VISIBLE = {}.freeze
+
     attr_reader :schema_ids
 
     def initialize(repositories)
@@ -24,6 +30,7 @@ module Suma
         repo.schemas.each { |schema| add_schema(schema) }
       end
       @schema_ids = @schemas.keys
+      @visibility = build_visibility
       freeze
     end
 
@@ -47,20 +54,18 @@ module Suma
       @schemas.key?(normalize(id))
     end
 
-    # Does +schema_id+ (or a schema it interfaces to) declare +element_id+?
-    # EXPRESS resolves unqualified names against the local schema and
-    # implicitly-used schemas.
+    # Does +schema_id+ (or the schemas it imports) declare +element_id+?
+    # EXPRESS resolves unqualified names against the local schema and the
+    # schema's interface visibility, including USE-FROM cascades.
     #
     # @param schema_id [String]
     # @param element_id [String]
     # @return [Boolean]
     def element_visible?(schema_id, element_id)
       key = normalize(schema_id)
-      return false unless @elements.key?(key)
-
-      return true if @elements[key].key?(normalize(element_id))
+      return false unless @visibility.key?(key)
 
-      visible_from_interfaces(key).include?(normalize(element_id))
+      @visibility[key].key?(normalize(element_id))
     end
 
     # Schemas that +schema_id+ USEs FROM or REFERENCEs.
@@ -68,7 +73,7 @@ module Suma
     # @param schema_id [String]
     # @return [Array<String>] normalized ids of interface targets
     def interface_targets(schema_id)
-      @interfaces[normalize(schema_id)] || []
+      (@interfaces[normalize(schema_id)] || []).map(&:target)
     end
 
     # Transitive interface closure: every schema +schema_id+ depends on,
@@ -110,11 +115,21 @@ module Suma
       key = normalize(schema.id)
       @schemas[key] = true
       @elements[key] = declared_elements(schema)
-      targets = (schema.interfaces || [])
-        .filter_map { |i| i.schema&.id }
-        .map { |id| normalize(id) }
-        .uniq
-      @interfaces[key] = targets
+      @interfaces[key] = Array(schema.interfaces).filter_map do |interface|
+        build_edge(interface)
+      end
+    end
+
+    def build_edge(interface)
+      target = interface.schema&.id
+      return nil unless target
+
+      items = Array(interface.items).filter_map do |item|
+        item.id || (item.ref.id if item.ref.respond_to?(:id))
+      end
+      InterfaceEdge.new(kind: interface.kind.to_s,
+                        target: normalize(target),
+                        items: items)
     end
 
     def declared_elements(schema)
@@ -128,9 +143,57 @@ module Suma
       index
     end
 
-    def visible_from_interfaces(key)
-      (@interfaces[key] || []).flat_map do |target|
-        @elements[target]&.keys || []
+    # EXPRESS interface visibility (ISO 10303-11 §13.3): a schema sees its
+    # declarations plus its imports. An unrestricted USE re-exports
+    # everything its target makes visible, so visibility cascades through
+    # USE chains; a named import exposes only the named (renamed) items;
+    # a REFERENCE exposes the target's declarations without cascading.
+    #
+    # WG12 corpora ship circular USE interfaces, so this is a monotone
+    # fixed-point iteration — sound under cycles, and each pass only adds.
+    def build_visibility
+      visible = {}
+      @schemas.each_key { |key| visible[key] = (@elements[key] || {}).dup }
+
+      changed = true
+      while changed
+        changed = false
+        @schemas.each_key do |key|
+          changed ||= apply_visibility_pass(key, visible)
+        end
+      end
+      visible
+    end
+
+    def apply_visibility_pass(key, visible)
+      names = visible[key]
+      changed = false
+      (@interfaces[key] || []).each do |edge|
+        next unless @schemas.key?(edge.target)
+
+        changed ||= import_edge_names(names, edge, visible)
+      end
+      changed
+    end
+
+    def import_edge_names(names, edge, visible)
+      changed = false
+      imported_names(edge, visible).each_key do |name|
+        next if names.key?(name)
+
+        names[name] = true
+        changed = true
+      end
+      changed
+    end
+
+    def imported_names(edge, visible)
+      if edge.items.any?
+        edge.items.to_h { |name| [normalize(name), true] }
+      elsif edge.kind == "USE"
+        visible[edge.target] || EMPTY_VISIBLE
+      else
+        @elements[edge.target] || EMPTY_VISIBLE
       end
     end