suma 0.5.8 → 0.5.10

data/lib/suma/artifact_server.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Suma
+  # Development server for the emitted URN artifact tree: serves the
+  # static files at their URN-derived paths, negotiating JSON vs HTML by
+  # the Accept header. Production hosting maps the same paths statically.
+  class ArtifactServer
+    DEFAULT_PORT = 2113
+
+    attr_reader :directory, :port
+
+    # @param directory [String] the resolve output directory
+    # @param port [Integer] TCP port; 0 picks an ephemeral port
+    def initialize(directory, port: DEFAULT_PORT)
+      @directory = File.expand_path(directory)
+      @port = port
+    end
+
+    # Resolve one HTTP request to a response.
+    #
+    # @param path [String] request path (with or without extension)
+    # @param accept [String, nil] Accept header value
+    # @return [Array(String, String, String)] status, content type, body
+    def call(path, accept = nil)
+      clean = path.to_s.split("?").first.to_s
+      return not_found if clean.include?("..")
+
+      clean = "/index.html" if clean.empty? || clean == "/"
+      file = artifact_file(clean, accept)
+      return not_found unless file
+
+      ["200", content_type(file), File.read(file, encoding: "utf-8")]
+    end
+
+    # Handle a single connection (one HTTP request).
+    def serve(socket)
+      request = socket.gets&.strip
+      return unless request
+
+      accept = read_headers(socket)["accept"]
+      status, type, body = call(request.split[1].to_s, accept)
+      socket.write(
+        "HTTP/1.1 #{status} #{status_name(status)}\r\n" \
+        "Content-Type: #{type}\r\nContent-Length: #{body.bytesize}\r\n" \
+        "Connection: close\r\n\r\n#{body}",
+      )
+    ensure
+      socket&.close
+    end
+
+    # Accept connections until interrupted.
+    def start
+      server = TCPServer.new("localhost", @port)
+      @port = server.addr[1]
+      Utils.log "Serving #{@directory} at http://localhost:#{@port}"
+      loop { serve(server.accept) }
+    ensure
+      server&.close
+    end
+
+    private
+
+    def read_headers(socket)
+      headers = {}
+      while (line = socket.gets) && line != "\r\n" && !line.strip.empty?
+        key, value = line.split(":", 2)
+        headers[key.strip.downcase] = value.strip if value
+      end
+      headers
+    end
+
+    def artifact_file(clean, accept)
+      base = clean.delete_prefix("/")
+      candidates = if base.end_with?(".json", ".html")
+                     [base]
+                   else
+                     wants_json = accept.to_s.include?("application/json")
+                     ["#{base}.#{wants_json ? 'json' : 'html'}"]
+                   end
+      candidates.map { |candidate| File.join(@directory, candidate) }
+        .find { |file| File.file?(file) }
+    end
+
+    def content_type(file)
+      if file.end_with?(".json")
+        "application/json"
+      else
+        "text/html; charset=utf-8"
+      end
+    end
+
+    def not_found
+      ["404", "text/plain", "not found\n"]
+    end
+
+    def status_name(status)
+      status == "200" ? "OK" : "Not Found"
+    end
+  end
+end

data/lib/suma/cli/artifact_server_cli.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Suma
+  module Cli
+    # Serve the emitted URN artifact tree with Accept negotiation.
+    class ArtifactServerCli < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "serve DIRECTORY", "Serve resolved URN artifacts locally"
+      option :port, type: :numeric, default: ArtifactServer::DEFAULT_PORT,
+                    desc: "TCP port to listen on"
+      def serve(directory)
+        Utils.log "Ctrl-C stops the server."
+        ArtifactServer.new(directory, port: options[:port]).start
+      end
+    end
+  end
+end

data/lib/suma/cli/build.rb

@@ -33,6 +33,9 @@ module Suma
       option :sign_key, type: :string,
                         desc: "Signing key (minisign requires it; sigstore " \
                               "signs keylessly when omitted)"
+      option :no_valid, type: :boolean, default: false,
+                        desc: "Skip Metanorma document validation " \
+                              "(equivalent of metanorma --no-valid)"
 
       def build(metanorma_site_manifest)
         unless File.exist?(metanorma_site_manifest)
@@ -62,6 +65,7 @@ module Suma
           provenance_file: options[:provenance],
           sign_method: options[:sign],
           sign_key: options[:sign_key],
+          no_valid: options[:no_valid],
         ).run
       end
 

data/lib/suma/cli/core.rb

@@ -42,6 +42,8 @@ module Suma
                     desc: "Sign the provenance manifest: minisign or sigstore"
       option :sign_key, type: :string,
                         desc: "Signing key (sigstore signs keylessly when omitted)"
+      option :no_valid, type: :boolean, default: false,
+                        desc: "Skip Metanorma document validation"
       def build(_site_manifest)
         Cli::Build.start
       end
@@ -70,6 +72,8 @@ module Suma
                        desc: "Owning edition recorded on each concept"
       option :language_codes, type: :array,
                               desc: "Additional linked localization languages"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       def extract_terms(schema_manifest_file, glossarist_output_path)
         TermExtractor.new(
           schema_manifest_file,
@@ -78,6 +82,7 @@ module Suma
           language_code: options[:language_code],
           edition: options[:edition],
           language_codes: options[:language_codes],
+          profile: options[:profile],
         ).call
       end
 
@@ -94,7 +99,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,
@@ -141,7 +146,7 @@ module Suma
                                  "USE-FROM/REFERENCE closure (manifest " \
                                  "input only)"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :format, type: :string, default: "express", banner: "FORMAT",
                       desc: "Output format: express (default) or owl"
       option :corpus, type: :boolean, default: false,
@@ -164,8 +169,7 @@ 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
+      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"
@@ -183,6 +187,48 @@ module Suma
         Cli::Resolve.start
       end
 
+      desc "package-gcr CONCEPTS_DIR",
+           "Package extracted concepts into a .gcr archive"
+      # Mirrors so Core accepts the switches Cli::PackageGcr reparses; the
+      # inner class owns their declarations.
+      option :register, type: :string, required: true,
+                        desc: "register.yaml (dataset identity)"
+      option :shortname, type: :string, required: true,
+                         desc: "Dataset 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 (pin for reproducibility)"
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Output directory for the .gcr archives"
+      def package_gcr(_concepts_dir)
+        Cli::PackageGcr.start
+      end
+
+      desc "ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE",
+           "Overlay translated localized-concept content onto extracted " \
+           "Glossarist concepts"
+      # Mirrors so Core accepts the switches Cli::IngestTranslations
+      # reparses; the inner class owns their declarations.
+      option :output, type: :string, aliases: "-o",
+                      desc: "Write updated concepts here (default: " \
+                            "update CONCEPTS_DIR in place)"
+      def ingest_translations(_concepts_dir, _translations_file)
+        Cli::IngestTranslations.start
+      end
+
+      desc "serve DIRECTORY", "Serve resolved URN artifacts locally"
+      option :port, type: :numeric,
+                    default: Suma::ArtifactServer::DEFAULT_PORT,
+                    desc: "TCP port to listen on"
+      def serve(_directory)
+        Cli::ArtifactServerCli.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

@@ -35,7 +35,7 @@ module Suma
                                  "USE-FROM/REFERENCE closure (manifest " \
                                  "input only)"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :format, type: :string, default: "express", banner: "FORMAT",
                       desc: "Output format: express (default) or owl"
       option :corpus, type: :boolean, default: false,

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?