textus 0.55.1 → 0.56.0

data/lib/textus/doctor/check/unowned_schema_fields.rb

@@ -1,40 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class UnownedSchemaFields < Check
-        def call
-          dir = geometry.schemas_dir
-          return [] unless File.directory?(dir)
-
-          Dir.glob(File.join(dir, "*.yaml")).flat_map do |path|
-            issues_for(path)
-          end
-        end
-
-        private
-
-        def issues_for(path)
-          schema = safe_load(path)
-          return [] if schema.nil?
-
-          unowned = schema.unowned_fields
-          return [] if unowned.empty?
-
-          [{
-            "code" => "schema.unowned_fields",
-            "level" => "info",
-            "subject" => schema.name || File.basename(path, ".yaml"),
-            "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
-            "fix" => "add 'maintained_by: <role>' to each field in #{path} (optional but recommended)",
-          }]
-        end
-
-        def safe_load(path)
-          Schema.load(path)
-        rescue StandardError
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check.rb

@@ -1,41 +0,0 @@
-module Textus
-  module Doctor
-    # Abstract base for a single doctor check. Each concrete check inspects
-    # one slice of store health and returns an array of issue hashes:
-    #   { "code" => String, "level" => "error"|"warning"|"info",
-    #     "subject" => String, "message" => String, "fix" => String (optional) }
-    class Check
-      # Snake-case name used in --checks flag and ALL_CHECKS list. Default
-      # derives from the class name; override if the SPEC name diverges.
-      def self.name_key
-        @name_key ||= name.split("::").last
-                          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-                          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-                          .downcase
-      end
-
-      def initialize(container, role: Textus::Value::Role::DEFAULT)
-        @container = container
-        @role      = role
-      end
-
-      def call
-        raise NotImplementedError.new("#{self.class.name}#call not implemented")
-      end
-
-      protected
-
-      def root     = @container.root
-      def geometry = @container.geometry
-      def manifest = @container.manifest
-
-      # Dispatch a verb through Gate.
-      def dispatch(verb, *args, **kwargs)
-        klass = Textus::Action::VERBS[verb]
-        spec = klass.contract if klass.respond_to?(:contract?) && klass.contract?
-        inputs = spec ? Textus::Gate::Binder.inputs_from_ordered(spec, args, kwargs) : kwargs
-        @container.gate.dispatch(spec:, inputs:, role: @role)
-      end
-    end
-  end
-end

data/lib/textus/doctor/validator.rb

@@ -1,93 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Doctor
-    class Validator
-      def initialize(reader:, manifest:, audit_log:, schema_for:)
-        @reader    = reader
-        @manifest  = manifest
-        @audit_log = audit_log
-        @schema_for = schema_for
-      end
-
-      def call(container:, call:)
-        @container = container
-        @call      = call
-        violations = []
-        check_content_violations(violations)
-        check_role_authority_violations(violations)
-        { "protocol" => Textus::PROTOCOL, "ok" => violations.empty?, "violations" => violations }
-      end
-
-      private
-
-      def check_content_violations(violations)
-        @manifest.resolver.enumerate.each do |row|
-          key    = row[:key]
-          mentry = row[:manifest_entry]
-          env    = fetch_envelope(key, violations) or next
-          schema = mentry.schema && @schema_for.call(mentry.schema)
-          next unless schema
-
-          begin
-            validate_schema!(schema, env, mentry.format)
-          rescue Textus::Error => e
-            violations << { "key" => key, "code" => e.code, "message" => e.message }
-          end
-        end
-      end
-
-      def check_role_authority_violations(violations)
-        @manifest.resolver.enumerate.each do |row|
-          mentry = row[:manifest_entry]
-          next unless mentry.schema
-
-          schema = @schema_for.call(mentry.schema)
-          next unless schema
-
-          env = begin
-            @reader.call(row[:key], @container, @call)
-          rescue StandardError
-            next
-          end
-          append_authority_violations(violations, row[:key], env, schema)
-        end
-      end
-
-      def append_authority_violations(violations, key, env, schema)
-        last_writer = @audit_log.last_writer_for(key)
-        return if last_writer.nil?
-
-        last_writer_is_authority =
-          @manifest.policy.roles_with_capability("author").include?(last_writer)
-        env.meta.each_key do |field|
-          owner = schema.maintained_by(field)
-          next if owner.nil? || last_writer == owner || last_writer_is_authority
-
-          violations << {
-            "key" => key,
-            "code" => "role_authority",
-            "field" => field,
-            "expected" => owner,
-            "last_writer" => last_writer,
-          }
-        end
-      end
-
-      def fetch_envelope(key, violations)
-        @reader.call(key, @container, @call)
-      rescue Textus::Error => e
-        violations << { "key" => key, "code" => e.code, "message" => e.message }
-        nil
-      end
-
-      def validate_schema!(schema, envelope, format)
-        payload = case format
-                  when "json", "yaml" then envelope.content || {}
-                  else envelope.meta || {}
-                  end
-        schema.validate!(payload)
-      end
-    end
-  end
-end

data/lib/textus/doctor.rb

@@ -1,54 +0,0 @@
-module Textus
-  # Health check for a Textus store. Returns a JSON-friendly Hash envelope
-  # with an `issues` array and a summary. Each issue is a Hash with
-  # `code`, `level`, `subject`, `message`, and optionally `fix`.
-  module Doctor
-    LEVELS = %w[error warning info].freeze
-
-    CHECKS = [
-      Check::ProtocolVersion,
-      Check::ManifestFiles,
-      Check::Schemas,
-      Check::SchemaParseError,
-      Check::Templates,
-      Check::IllegalKeys,
-      Check::Sentinels,
-      Check::AuditLog,
-      Check::UnownedSchemaFields,
-      Check::SchemaViolations,
-      Check::RuleAmbiguity,
-      Check::OrphanedPublishTargets,
-      Check::PublishTreeIndexOverlap,
-      Check::ProposalTargets,
-      Check::GeneratorDrift,
-      Check::RawAssetPaths,
-      Check::NotebookSources,
-      Check::StaleReviewedStamp,
-    ].freeze
-
-    ALL_CHECKS = CHECKS.map(&:name_key).freeze
-
-    module_function
-
-    def build(container:, checks: nil, role: Textus::Value::Role::DEFAULT)
-      selected_keys = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
-      unknown = selected_keys - ALL_CHECKS
-      unless unknown.empty?
-        raise UsageError.new(
-          "unknown doctor check: #{unknown.first}. Valid checks: #{ALL_CHECKS.join(", ")}",
-        )
-      end
-
-      selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
-      issues = selected.flat_map { |c| c.new(container, role:).call }
-
-      summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
-      {
-        "protocol" => Textus::PROTOCOL,
-        "ok" => summary["error"].zero?,
-        "issues" => issues,
-        "summary" => summary,
-      }
-    end
-  end
-end

data/lib/textus/format/base.rb

@@ -1,49 +0,0 @@
-module Textus
-  module Format
-    class Base
-      def self.parse(_raw, path: nil)
-        _ = path
-        raise NotImplementedError.new("#{name}.parse not implemented")
-      end
-
-      def self.serialize(meta: {}, body: "", content: nil)
-        _ = meta
-        _ = body
-        _ = content
-        raise NotImplementedError.new("#{name}.serialize not implemented")
-      end
-
-      def self.extensions
-        raise NotImplementedError.new("#{name}.extensions not implemented")
-      end
-
-      def self.validate_against(schema, parsed)
-        schema.validate!(parsed["_meta"] || {})
-      end
-
-      def self.nested_glob
-        raise NotImplementedError.new("#{name}.nested_glob not implemented")
-      end
-
-      def self.validate_path_extension(_path, _nested)
-        raise NotImplementedError.new("#{name}.validate_path_extension not implemented")
-      end
-
-      def self.enforce_name_match!(_path, _meta)
-        raise NotImplementedError.new("#{name}.enforce_name_match! not implemented")
-      end
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = meta
-        _ = body
-        _ = content
-        _ = path
-        raise NotImplementedError.new("#{name}.serialize_for_put not implemented")
-      end
-
-      def self.rewrite_name(_path, _basename)
-        raise NotImplementedError.new("#{name}.rewrite_name not implemented")
-      end
-    end
-  end
-end

data/lib/textus/format/json.rb

@@ -1,102 +0,0 @@
-require "json"
-
-module Textus
-  module Format
-    class Json < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-
-        begin
-          parsed = ::JSON.parse(raw)
-        rescue ::JSON::ParserError => e
-          raise BadFrontmatter.new(path, "JSON parse failed: #{e.message}")
-        end
-        raise BadFrontmatter.new(path, "JSON top-level must be an object") unless parsed.is_a?(Hash)
-
-        meta = parsed["_meta"]
-        fm = meta.is_a?(Hash) ? meta : {}
-        content_without_meta = parsed.except("_meta")
-        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        if content.is_a?(Hash)
-          on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
-          out = ::JSON.pretty_generate(on_disk)
-          out += "\n" unless out.end_with?("\n")
-          out
-        elsif body && !body.to_s.empty?
-          b = body.to_s
-          b += "\n" unless b.end_with?("\n")
-          b
-        else
-          raise UsageError.new("json serialize requires :content or :body")
-        end
-      end
-
-      def self.validate_against(schema, parsed)
-        schema.validate!(parsed["content"] || {})
-      end
-
-      def self.extensions = [".json"]
-
-      def self.nested_glob = "**/*.json"
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        raise UsageError.new("put for json requires content: or body:") if content.nil? && (body.nil? || body.to_s.empty?)
-
-        if content.nil?
-          begin
-            parsed = parse(body.to_s, path: path)
-          rescue BadFrontmatter => e
-            raise BadContent.new(path, "bad_content: #{e.message}")
-          end
-          [body.to_s, parsed["_meta"], body.to_s, parsed["content"]]
-        else
-          bytes = serialize(meta: meta, body: "", content: content)
-          [bytes, meta, bytes, content]
-        end
-      end
-
-      def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
-        raw = File.binread(path)
-        parsed = parse(raw, path: path)
-        meta = parsed["_meta"]
-        return false unless meta.is_a?(Hash) && meta["name"].is_a?(String) && meta["name"] != basename
-
-        new_meta = meta.merge("name" => basename)
-        File.binwrite(path, serialize(meta: new_meta, body: "", content: parsed["content"]))
-        true
-      end
-
-      def self.enforce_name_match!(path, meta)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
-      end
-
-      def self.validate_path_extension(path, nested)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("nested json path must not have an extension")
-        end
-
-        return if ext == ".json"
-
-        raise UsageError.new("json format requires '.json' path (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: nil, content: data["content"] || data }
-      end
-    end
-  end
-end

data/lib/textus/format/markdown.rb

@@ -1,80 +0,0 @@
-require "yaml"
-
-module Textus
-  module Format
-    class Markdown < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-        return { "_meta" => {}, "body" => raw, "content" => nil } unless raw.start_with?("---\n") || raw.start_with?("---\r\n")
-
-        lines = raw.split(/\r?\n/, -1)
-        close_idx = lines[1..].index("---")
-        raise BadFrontmatter.new(path, "frontmatter not terminated") unless close_idx
-
-        close_idx += 1
-        fm_yaml = lines[1...close_idx].join("\n")
-        body = lines[(close_idx + 1)..].join("\n")
-        begin
-          fm = fm_yaml.strip.empty? ? {} : ::YAML.safe_load(fm_yaml, permitted_classes: [Date, Time], aliases: false)
-        rescue Psych::SyntaxError => e
-          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
-        end
-        fm = {} unless fm.is_a?(Hash)
-        { "_meta" => fm, "body" => body, "content" => nil }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        _ = content
-        fm_yaml = meta.empty? ? "" : ::YAML.dump(meta).sub(/\A---\n/, "")
-        body = body.to_s
-        body += "\n" unless body.empty? || body.end_with?("\n")
-        "---\n#{fm_yaml}---\n#{body}"
-      end
-
-      def self.extensions = [".md"]
-
-      def self.nested_glob = "**/*.md"
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = path
-        _ = content
-        bytes = serialize(meta: meta || {}, body: body.to_s)
-        [bytes, meta, body.to_s, nil]
-      end
-
-      def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
-        raw = File.binread(path)
-        parsed = parse(raw, path: path)
-        meta = parsed["_meta"] || {}
-        return false unless meta.is_a?(Hash) && meta["name"].is_a?(String) && meta["name"] != basename
-
-        new_meta = meta.merge("name" => basename)
-        File.binwrite(path, serialize(meta: new_meta, body: parsed["body"]))
-        true
-      end
-
-      def self.enforce_name_match!(path, meta)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
-      end
-
-      def self.validate_path_extension(path, _nested)
-        ext = File.extname(path)
-        return if ["", ".md"].include?(ext)
-
-        raise UsageError.new("markdown format requires '.md' path (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: (data["body"] || "").to_s, content: nil }
-      end
-    end
-  end
-end

data/lib/textus/format/shared.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Format
-    module Shared
-      ENFORCE_NAME_RE = /\.(md|json|yaml|yml|txt)\z/i
-
-      def self.enforce_name_match!(path, meta, extensions)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
-      end
-    end
-  end
-end

data/lib/textus/format/text.rb

@@ -1,55 +0,0 @@
-module Textus
-  module Format
-    class Text < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-
-        { "_meta" => {}, "body" => raw, "content" => nil }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        _ = meta
-        _ = content
-        b = body.to_s
-        b += "\n" unless b.empty? || b.end_with?("\n")
-        b
-      end
-
-      def self.extensions = [".txt"]
-
-      def self.nested_glob = "**/*.txt"
-
-      def self.enforce_name_match!(_path, _meta); end
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = path
-        _ = content
-        bytes = serialize(meta: meta || {}, body: body.to_s)
-        [bytes, meta, body.to_s, nil]
-      end
-
-      def self.rewrite_name(_path, _basename) # rubocop:disable Naming/PredicateMethod
-        false
-      end
-
-      def self.validate_path_extension(path, nested)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("nested text path must not have an extension")
-        end
-
-        return if [".txt", ""].include?(ext)
-
-        raise UsageError.new("text format requires '.txt' or no extension (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: (data["body"] || "").to_s, content: nil }
-      end
-    end
-  end
-end

data/lib/textus/format/yaml.rb

@@ -1,125 +0,0 @@
-require "yaml"
-
-module Textus
-  module Format
-    class Yaml < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-
-        begin
-          parsed = ::YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: false)
-        rescue Psych::SyntaxError, Psych::AliasesNotEnabled, Psych::DisallowedClass => e
-          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
-        end
-        raise BadFrontmatter.new(path, "YAML top-level must be a mapping") unless parsed.is_a?(Hash)
-
-        meta = parsed["_meta"]
-        fm = meta.is_a?(Hash) ? meta : {}
-        content_without_meta = parsed.except("_meta")
-        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        if content.is_a?(Hash)
-          on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
-          ::YAML.dump(on_disk).sub(/\A---\n/, "")
-        elsif body && !body.to_s.empty?
-          b = body.to_s
-          b += "\n" unless b.end_with?("\n")
-          b
-        else
-          raise UsageError.new("yaml serialize requires :content or :body")
-        end
-      end
-
-      def self.validate_against(schema, parsed)
-        schema.validate!(parsed["content"] || {})
-      end
-
-      RAW_REQUIRED = %w[ingested_at content_hash].freeze
-      RAW_SOURCE_KINDS = %w[url file asset].freeze
-
-      def self.validate_raw_entry!(parsed, lane)
-        return unless lane == "raw"
-
-        content = parsed["content"] || {}
-        return if content["superseded_by"]
-
-        missing = RAW_REQUIRED.reject { |f| content[f] }
-        raise Textus::BadContent.new(nil, "raw entry missing required field(s): #{missing.join(", ")}") if missing.any?
-
-        source = content["source"] || {}
-        kind = source["kind"]
-        unless RAW_SOURCE_KINDS.include?(kind)
-          raise Textus::BadContent.new(
-            nil, "raw entry source.kind must be #{RAW_SOURCE_KINDS.join("|")}, got #{kind.inspect}"
-          )
-        end
-
-        return unless kind == "url" && !source["url"]
-
-        raise Textus::BadContent.new(nil, "raw entry with source.kind=url must have source.url")
-      end
-
-      def self.extensions = [".yaml", ".yml"]
-
-      def self.nested_glob = "**/*.{yaml,yml}"
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        raise UsageError.new("put for yaml requires content: or body:") if content.nil? && (body.nil? || body.to_s.empty?)
-
-        if content.nil?
-          begin
-            parsed = parse(body.to_s, path: path)
-          rescue BadFrontmatter => e
-            raise BadContent.new(path, "bad_content: #{e.message}")
-          end
-          [body.to_s, parsed["_meta"], body.to_s, parsed["content"]]
-        else
-          bytes = serialize(meta: meta, body: "", content: content)
-          [bytes, meta, bytes, content]
-        end
-      end
-
-      def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
-        raw = File.binread(path)
-        parsed = parse(raw, path: path)
-        meta = parsed["_meta"]
-        return false unless meta.is_a?(Hash) && meta["name"].is_a?(String) && meta["name"] != basename
-
-        new_meta = meta.merge("name" => basename)
-        File.binwrite(path, serialize(meta: new_meta, body: "", content: parsed["content"]))
-        true
-      end
-
-      def self.enforce_name_match!(path, meta)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
-      end
-
-      def self.validate_path_extension(path, nested)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("nested yaml path must not have an extension")
-        end
-
-        return if [".yaml", ".yml"].include?(ext)
-
-        raise UsageError.new("yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: nil, content: data["content"] || data }
-      end
-    end
-  end
-end