textus 0.55.2 → 0.56.0

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

@@ -1,28 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Surfaces YAML parse failures for files in <store>/schemas/. Without
-      # this check, malformed schemas are silently skipped by other doctor
-      # checks (UnownedSchemaFields rescues, Schemas only checks filenames),
-      # leaving the operator with no signal that a schema is broken.
-      class SchemaParseError < Check
-        def call
-          dir = geometry.schemas_dir
-          return [] unless File.directory?(dir)
-
-          Dir.glob(File.join(dir, "*.yaml")).each_with_object([]) do |path, out|
-            Schema.load(path)
-          rescue StandardError => e
-            out << {
-              "code" => "schema.parse_error",
-              "level" => "error",
-              "subject" => path,
-              "message" => "schema failed to parse: #{e.class}: #{e.message}",
-              "fix" => "fix the YAML at #{path} (check indentation, quoted scalars, and aliases)",
-            }
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,28 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class SchemaViolations < Check
-        def call
-          result = Textus::Doctor::Validator.new(
-            reader: ->(key, ctnr, _c) { Textus::Store::Entry::Reader.from(container: ctnr).read(key) },
-            manifest: @container.manifest,
-            audit_log: @container.audit_log,
-            schema_for: ->(name) { @container.schemas.fetch_or_nil(name) },
-          ).call(container: @container, call: Textus::Value::Call.build(role: Textus::Value::Role::DEFAULT))
-
-          result["violations"].map do |v|
-            fix = v["expected"] &&
-                  "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"
-            {
-              "code" => v["code"],
-              "level" => "error",
-              "subject" => v["key"],
-              "message" => v["message"] || "#{v["code"]} on #{v["key"]}",
-              "fix" => fix,
-            }.compact
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,26 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Schemas < Check
-        def call
-          out = []
-          manifest.data.entries.each do |entry|
-            next if entry.schema.nil?
-
-            sp = geometry.schema_path(entry.schema)
-            next if File.exist?(sp)
-
-            out << {
-              "code" => "schema.missing",
-              "level" => "error",
-              "subject" => entry.key,
-              "message" => "schema '#{entry.schema}' not found at #{sp}",
-              "fix" => "create the schema file or run 'textus schema init #{entry.schema} --from=<key>'",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

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

@@ -1,55 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class ScratchpadSources < Check
-        def call
-          issues = []
-          manifest.resolver.enumerate.each do |row|
-            next unless row[:key].start_with?("scratchpad.notes.")
-            next unless row[:path] && File.exist?(row[:path])
-
-            sources = parse_sources(row[:path])
-            sources.each do |raw_key|
-              next if raw_entry_exists?(raw_key)
-
-              issues << {
-                "code" => "scratchpad.source_missing",
-                "level" => "warning",
-                "subject" => row[:key],
-                "message" => "scratchpad entry '#{row[:key]}' references raw key '#{raw_key}' " \
-                             "which does not exist in the store",
-                "fix" => "re-ingest the source: textus ingest ..., or remove the stale sources: entry",
-              }
-            end
-          end
-          issues
-        end
-
-        private
-
-        def parse_sources(path)
-          content = File.read(path)
-          match = content.match(/\A---\n(.*?)\n---/m)
-          return [] unless match
-
-          front = YAML.safe_load(match[1])
-          Array(front&.dig("sources")).filter_map do |s|
-            case s
-            when String then s
-            when Hash   then s["key"]
-            end
-          end
-        rescue StandardError
-          []
-        end
-
-        def raw_entry_exists?(key)
-          path = manifest.resolver.resolve(key).path
-          File.exist?(path)
-        rescue Textus::UnknownKey, Textus::Error
-          false
-        end
-      end
-    end
-  end
-end

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

@@ -1,60 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Sentinels < Check
-        def call
-          store      = Textus::Port::SentinelStore.new
-          file_stat  = Textus::Port::Storage::FileStat.new
-          dir        = Textus::Store::Layout.new(root).sentinels_root
-          return [] unless file_stat.directory?(dir)
-
-          repo_root = File.dirname(root)
-          file_stat.glob(File.join(dir, "**", "*#{Textus::Port::SentinelStore::SUFFIX}")).flat_map do |sentinel_path|
-            inspect_sentinel(sentinel_path, repo_root, store, file_stat)
-          end
-        end
-
-        private
-
-        def inspect_sentinel(sentinel_path, repo_root, store, file_stat)
-          sentinel = store.load(sentinel_path, repo_root)
-          return [parse_error_issue(sentinel_path)] if sentinel.nil?
-          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?(file_stat)
-          return [drift_issue(sentinel)] if sentinel.drift?(file_stat)
-
-          []
-        end
-
-        def parse_error_issue(sentinel_path)
-          {
-            "code" => "sentinel.parse_error",
-            "level" => "warning",
-            "subject" => sentinel_path,
-            "message" => "sentinel is not valid JSON",
-            "fix" => "delete #{sentinel_path} and re-run 'textus drain' to regenerate",
-          }
-        end
-
-        def orphan_issue(sentinel_path, sentinel)
-          {
-            "code" => "sentinel.orphan",
-            "level" => "warning",
-            "subject" => sentinel_path,
-            "message" => "sentinel target #{sentinel.target.inspect} no longer exists",
-            "fix" => "delete #{sentinel_path} (the published file is gone) or restore the target",
-          }
-        end
-
-        def drift_issue(sentinel)
-          {
-            "code" => "sentinel.drift",
-            "level" => "warning",
-            "subject" => sentinel.target,
-            "message" => "published file at #{sentinel.target} was modified out-of-band",
-            "fix" => "re-run 'textus drain' to overwrite, or copy the manual edit back into the store source",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,54 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Warns when a knowledge-lane doc's `**reviewed** YYYY-MM (vX.Y)` stamp
-      # is more than MINOR_THRESHOLD minor versions behind Textus::VERSION.
-      # The stamp is the human staleness signal declared in docs conventions
-      # (knowledge.docs-index); this check makes it machine-enforced.
-      class StaleReviewedStamp < Check
-        STAMP_RE = /\*\*reviewed\*\*\s+\d{4}-\d{2}\s+\(v(\d+\.\d+(?:\.\d+)?)\)/
-        MINOR_THRESHOLD = 5
-
-        def call
-          current_minor = parse_minor(Textus::VERSION)
-          issues = []
-
-          manifest.resolver.enumerate.each do |row|
-            next unless row[:key].to_s.start_with?("knowledge.")
-            next unless row[:path] && File.file?(row[:path])
-
-            body = File.read(row[:path])
-            m = body.match(STAMP_RE)
-            next unless m
-
-            reviewed_minor = parse_minor(m[1])
-            behind = current_minor - reviewed_minor
-            next unless behind > MINOR_THRESHOLD
-
-            issues << stale_issue(row[:key], m[1], behind)
-          end
-
-          issues
-        end
-
-        private
-
-        def parse_minor(version_str)
-          version_str.sub(/\Av/, "").split(".").map(&:to_i)[1] || 0
-        end
-
-        def stale_issue(key, stamp_version, behind)
-          current_short = Textus::VERSION[/\A\d+\.\d+/]
-          {
-            "code" => "stale_reviewed_stamp",
-            "level" => "warning",
-            "subject" => key.to_s,
-            "message" => "reviewed at v#{stamp_version}; current is v#{Textus::VERSION} " \
-                         "(#{behind} minor versions behind, threshold is #{MINOR_THRESHOLD})",
-            "fix" => "review the doc and update the stamp to: **reviewed** YYYY-MM (v#{current_short})",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,29 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Templates < Check
-        def call
-          out = []
-          manifest.data.entries.each do |entry|
-            entry.publish_targets.each do |target|
-              template = target.template
-              next if template.nil?
-
-              tp = geometry.template_path(template)
-              next if File.exist?(tp)
-
-              out << {
-                "code" => "template.missing",
-                "level" => "error",
-                "subject" => entry.key,
-                "message" => "template '#{template}' not found at #{tp}",
-                "fix" => "create the file at #{tp} or update the publish target's template: field",
-              }
-            end
-          end
-          out
-        end
-      end
-    end
-  end
-end

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,43 +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.layout
-      def manifest = @container.manifest
-
-      def dispatch(verb, *args, **kwargs)
-        contract_class = Textus::VerbRegistry.contract_class_for(verb)
-        members = contract_class.members
-        command_kwargs = members.each_with_index.to_h { |m, i| [m, args[i] || kwargs[m]] }
-        command = contract_class.new(**command_kwargs)
-        call = Textus::Value::Call.build(role: @role)
-        result = @container.pipeline.dispatch(command, call: call)
-        Textus::Value::Result.extract(result)
-      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::ScratchpadSources,
-      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,77 +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)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("#{format_name} nested path must not have an extension")
-        end
-
-        return if extensions.include?(ext)
-
-        raise UsageError.new("#{format_name} format requires '#{extensions.join("' or '")}' path (got #{ext.inspect})")
-      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.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"] || "", content: parsed["content"]))
-        true
-      end
-
-      def self.format_name
-        name.split("::").last.downcase
-      end
-
-      def self.validate_raw_entry!(_parsed, _lane); end
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = meta
-        _ = body
-        _ = content
-        _ = path
-        raise NotImplementedError.new("#{name}.serialize_for_put not implemented")
-      end
-    end
-  end
-end

data/lib/textus/format/json.rb

@@ -1,81 +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.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