textus 0.5.0 → 0.8.0

data/lib/textus/doctor.rb

@@ -1,32 +1,41 @@
-require "digest"
-require "json"
 require "timeout"
 
 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 # rubocop:disable Metrics/ModuleLength -- 9 built-in checks + extension dispatch
+  module Doctor
     LEVELS = %w[error warning info].freeze
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
-    ALL_CHECKS = %w[
-      manifest_files schemas templates extensions illegal_keys
-      sentinels audit_log unowned_schema_fields schema_violations
+
+    CHECKS = [
+      Check::ManifestFiles,
+      Check::Schemas,
+      Check::Templates,
+      Check::Hooks,
+      Check::IllegalKeys,
+      Check::Sentinels,
+      Check::AuditLog,
+      Check::UnownedSchemaFields,
+      Check::SchemaViolations,
     ].freeze
 
+    ALL_CHECKS = CHECKS.map(&:name_key).freeze
+
     module_function
 
     def run(store, checks: nil)
-      selected = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
-      unknown = selected - ALL_CHECKS
+      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
 
-      issues = run_builtin_checks(store, selected)
-      issues.concat(run_registered_checks(store)) # extensions always run
+      selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
+      issues = selected.flat_map { |c| c.new(store).call }
+      issues.concat(run_registered_checks(store))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -37,263 +46,11 @@ module Textus
       }
     end
 
-    def run_builtin_checks(store, selected)
-      issues = []
-      issues.concat(check_manifest_files(store))        if selected.include?("manifest_files")
-      issues.concat(check_schemas(store))               if selected.include?("schemas")
-      issues.concat(check_templates(store))             if selected.include?("templates")
-      issues.concat(check_extensions(store))            if selected.include?("extensions")
-      issues.concat(check_illegal_keys(store))          if selected.include?("illegal_keys")
-      issues.concat(check_sentinels(store))             if selected.include?("sentinels")
-      issues.concat(check_audit_log(store))             if selected.include?("audit_log")
-      issues.concat(check_unowned_schema_fields(store)) if selected.include?("unowned_schema_fields")
-      issues.concat(check_schema_violations(store))     if selected.include?("schema_violations")
-      issues
-    end
-
-    # --- Checks -----------------------------------------------------------
-
-    def check_manifest_files(store)
-      out = []
-      store.manifest.entries.each do |entry|
-        next if entry.nested
-
-        path = leaf_path_for(store, entry)
-        next if File.exist?(path)
-
-        out << {
-          "code" => "manifest.missing_file",
-          "level" => "info",
-          "subject" => entry.key,
-          "message" => "declared entry has no file on disk at #{path}",
-          "fix" => "create the entry with 'textus put #{entry.key} --stdin --as=<role>' " \
-                   "(or leave empty if not yet authored)",
-        }
-      end
-      out
-    end
-
-    def check_schemas(store)
-      out = []
-      store.manifest.entries.each do |entry|
-        next if entry.schema.nil?
-
-        sp = File.join(store.root, "schemas", "#{entry.schema}.yaml")
-        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
-
-    def check_templates(store)
-      out = []
-      store.manifest.entries.each do |entry|
-        next if entry.template.nil?
-
-        tp = File.join(store.root, "templates", entry.template)
-        next if File.exist?(tp)
-
-        out << {
-          "code" => "template.missing",
-          "level" => "error",
-          "subject" => entry.key,
-          "message" => "template '#{entry.template}' not found at #{tp}",
-          "fix" => "create the file at #{tp} or update the entry's template: field",
-        }
-      end
-      out
-    end
-
-    def check_extensions(store)
-      out = []
-      dir = File.join(store.root, "extensions")
-      return out unless File.directory?(dir)
-
-      Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
-        registry = ExtensionRegistry.new
-        Textus.with_registry(registry) do
-          load(f)
-        end
-      rescue StandardError, ScriptError => e
-        out << {
-          "code" => "extension.load_failed",
-          "level" => "error",
-          "subject" => File.basename(f),
-          "message" => "#{e.class}: #{e.message}",
-          "fix" => "open #{f} and fix the syntax/load error",
-        }
-      end
-      out
-    end
-
-    def check_illegal_keys(store)
-      out = []
-      store.manifest.entries.each do |entry|
-        next unless entry.nested
-
-        base = File.join(store.root, "zones", entry.path)
-        next unless File.directory?(base)
-
-        walk_nested(base) do |abs_path, is_dir|
-          basename = File.basename(abs_path)
-          stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-          next if stem.match?(Manifest::KEY_SEGMENT)
-
-          proposed = Textus::MigrateKeys.normalize(stem)
-          out << {
-            "code" => "key.illegal",
-            "level" => "error",
-            "subject" => abs_path,
-            "path" => abs_path,
-            "proposed_key" => proposed,
-            "message" => "illegal key segment '#{stem}' at #{abs_path}",
-            "fix" => "run 'textus migrate-keys --dry-run' then '--write' to rename to '#{proposed}'",
-          }
-        end
-      end
-      out
-    end
-
-    def check_sentinels(store)
-      out = []
-      dir = File.join(store.root, "sentinels")
-      return out unless File.directory?(dir)
-
-      Dir.glob(File.join(dir, "**", "*.textus-managed.json")).each do |sp| # rubocop:disable Metrics/BlockLength
-        begin
-          data = JSON.parse(File.read(sp))
-        rescue JSON::ParserError => e
-          out << {
-            "code" => "sentinel.parse_error",
-            "level" => "warning",
-            "subject" => sp,
-            "message" => "sentinel is not valid JSON: #{e.message}",
-            "fix" => "delete #{sp} and re-run 'textus build' to regenerate",
-          }
-          next
-        end
-
-        target = data["target"]
-        recorded_sha = data["sha256"]
-
-        if target.nil? || !File.exist?(target)
-          out << {
-            "code" => "sentinel.orphan",
-            "level" => "warning",
-            "subject" => sp,
-            "message" => "sentinel target #{target.inspect} no longer exists",
-            "fix" => "delete #{sp} (the published file is gone) or restore the target",
-          }
-          next
-        end
-
-        current_sha = Digest::SHA256.hexdigest(File.binread(target))
-        next if recorded_sha.nil? || current_sha == recorded_sha
-
-        out << {
-          "code" => "sentinel.drift",
-          "level" => "warning",
-          "subject" => target,
-          "message" => "published file at #{target} was modified out-of-band",
-          "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
-        }
-      end
-      out
-    end
-
-    def check_audit_log(store)
-      out = []
-      path = File.join(store.root, "audit.log")
-      return out unless File.exist?(path)
-
-      File.foreach(path).with_index(1) do |line, lineno| # rubocop:disable Metrics/BlockLength
-        stripped = line.chomp
-        next if stripped.empty?
-
-        if stripped.start_with?("{")
-          begin
-            JSON.parse(stripped)
-          rescue JSON::ParserError => e
-            out << {
-              "code" => "audit.parse_error",
-              "level" => "warning",
-              "subject" => "#{path}:#{lineno}",
-              "message" => "audit log line #{lineno} is invalid JSON: #{e.message}",
-              "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-            }
-          end
-        else
-          # Legacy TSV: minimum 6 fields. Removed in 0.6.
-          fields = stripped.split("\t")
-          next if fields.length >= 6
-
-          out << {
-            "code" => "audit.parse_error",
-            "level" => "warning",
-            "subject" => "#{path}:#{lineno}",
-            "message" => "audit log line #{lineno} has #{fields.length} fields " \
-                         "(expected >=6 for legacy TSV; consider migrating to NDJSON)",
-            "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-          }
-        end
-      end
-      out
-    end
-
-    def check_unowned_schema_fields(store)
-      out = []
-      dir = File.join(store.root, "schemas")
-      return out unless File.directory?(dir)
-
-      Dir.glob(File.join(dir, "*.yaml")).sort.each do |sp| # rubocop:disable Lint/RedundantDirGlobSort
-        schema = begin
-          Schema.load(sp)
-        rescue StandardError
-          next
-        end
-        unowned = schema.fields.each_with_object([]) do |(name, spec), acc|
-          acc << name if spec.is_a?(Hash) && spec["maintained_by"].nil?
-        end
-        next if unowned.empty?
-
-        out << {
-          "code" => "schema.unowned_fields",
-          "level" => "info",
-          "subject" => schema.name || File.basename(sp, ".yaml"),
-          "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
-          "fix" => "add 'maintained_by: <role>' to each field in #{sp} (optional but recommended)",
-        }
-      end
-      out
-    end
-
-    def check_schema_violations(store)
-      res = store.validate_all
-      res["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
-
     def run_registered_checks(store)
       out = []
-      view = StoreView.new(store)
-      store.registry.doctor_check_names.each do |name|
-        callable = store.registry.doctor_check(name)
+      view = Store::View.new(store)
+      store.registry.rpc_names(:check).each do |name|
+        callable = store.registry.rpc_callable(:check, name)
         begin
           result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
           if result.is_a?(Array)
@@ -325,28 +82,5 @@ module Textus
         "fix" => fix,
       }
     end
-
-    # --- Helpers ----------------------------------------------------------
-
-    def leaf_path_for(store, entry)
-      primary_ext = Entry.for_format(entry.format).extensions.first
-      if File.extname(entry.path) == ""
-        File.join(store.root, "zones", entry.path + primary_ext)
-      else
-        File.join(store.root, "zones", entry.path)
-      end
-    end
-
-    def walk_nested(root, &block)
-      Dir.each_child(root) do |name|
-        abs = File.join(root, name)
-        if File.directory?(abs)
-          walk_nested(abs, &block)
-          yield abs, true
-        else
-          yield abs, false
-        end
-      end
-    end
   end
 end

data/lib/textus/entry/base.rb

@@ -0,0 +1,30 @@
+module Textus
+  module Entry
+    # Abstract base for entry format strategies. Each concrete strategy
+    # owns parsing, serialization, file-extension claims, and schema
+    # validation for entries declared with its 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
+
+      # Default: validate the meta hash. Overridden by formats that put the
+      # validatable payload elsewhere (json/yaml put it under "content").
+      def self.validate_against(schema, parsed)
+        schema.validate!(parsed["_meta"] || {})
+      end
+    end
+  end
+end

data/lib/textus/entry/json.rb

@@ -3,7 +3,7 @@ require "json"
 module Textus
   module Entry
     # JSON entry storage. Top-level must be an object so we can carry _meta.
-    module Json
+    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?
@@ -37,6 +37,10 @@ module Textus
         end
       end
 
+      def self.validate_against(schema, parsed)
+        schema.validate!(parsed["content"] || {})
+      end
+
       def self.extensions = [".json"]
     end
   end

data/lib/textus/entry/markdown.rb

@@ -3,7 +3,7 @@ require "yaml"
 module Textus
   module Entry
     # Markdown with YAML frontmatter. Original Entry implementation.
-    module Markdown
+    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?

data/lib/textus/entry/text.rb

@@ -1,7 +1,7 @@
 module Textus
   module Entry
     # Plain-text entry storage. No frontmatter or structured content.
-    module Text
+    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?

data/lib/textus/entry/yaml.rb

@@ -3,7 +3,7 @@ require "yaml"
 module Textus
   module Entry
     # YAML entry storage. Top-level must be a mapping so we can carry _meta.
-    module Yaml
+    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?
@@ -35,6 +35,10 @@ module Textus
         end
       end
 
+      def self.validate_against(schema, parsed)
+        schema.validate!(parsed["content"] || {})
+      end
+
       def self.extensions = [".yaml", ".yml"]
     end
   end

data/lib/textus/entry.rb

@@ -1,8 +1,3 @@
-require_relative "entry/markdown"
-require_relative "entry/json"
-require_relative "entry/yaml"
-require_relative "entry/text"
-
 module Textus
   # Public entry-format dispatcher.
   module Entry

data/lib/textus/envelope.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Textus
+  module Envelope
+    # rubocop:disable Metrics/ParameterLists
+    def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil)
+      # rubocop:enable Metrics/ParameterLists
+      env = {
+        "protocol" => PROTOCOL,
+        "key" => key,
+        "zone" => mentry.zone,
+        "owner" => mentry.owner,
+        "path" => path,
+        "format" => mentry.format,
+        "_meta" => meta,
+        "body" => body,
+        "etag" => etag,
+        "schema_ref" => mentry.schema,
+        "uid" => extract_uid(meta),
+      }
+      env["content"] = content unless content.nil?
+      env
+    end
+
+    def self.extract_uid(meta)
+      v = meta.is_a?(Hash) ? meta["uid"] : nil
+      v.is_a?(String) ? v : nil
+    end
+  end
+end

data/lib/textus/hooks/builtin.rb

@@ -0,0 +1,70 @@
+require "json"
+require "csv"
+require "yaml"
+require "rexml/document"
+
+module Textus
+  module Hooks
+    module Builtin
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def self.register_all
+        Textus.hook(:fetch, :json) do |store:, config:, args:|
+          _ = store
+          _ = args
+          data = JSON.parse(config["bytes"].to_s)
+          { _meta: {}, body: YAML.dump(data) }
+        end
+
+        Textus.hook(:fetch, :csv) do |store:, config:, args:|
+          _ = store
+          _ = args
+          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
+          { _meta: {}, body: YAML.dump(rows) }
+        end
+
+        Textus.hook(:fetch, :"markdown-links") do |store:, config:, args:|
+          _ = store
+          _ = args
+          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
+            { "text" => text, "href" => href }
+          end
+          { _meta: {}, body: YAML.dump(links) }
+        end
+
+        Textus.hook(:fetch, :"ical-events") do |store:, config:, args:|
+          _ = store
+          _ = args
+          events = []
+          current = nil
+          config["bytes"].to_s.each_line do |line|
+            line = line.strip
+            case line
+            when "BEGIN:VEVENT" then current = {}
+            when "END:VEVENT"
+              events << current if current
+              current = nil
+            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
+              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
+            end
+          end
+          { _meta: {}, body: YAML.dump(events) }
+        end
+
+        Textus.hook(:fetch, :rss) do |store:, config:, args:|
+          _ = store
+          _ = args
+          doc = REXML::Document.new(config["bytes"].to_s)
+          items = doc.elements.to_a("//item").map do |item|
+            {
+              "title" => item.elements["title"]&.text,
+              "link" => item.elements["link"]&.text,
+              "pubDate" => item.elements["pubDate"]&.text,
+            }
+          end
+          { _meta: {}, body: YAML.dump(items) }
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/textus/hooks/dispatcher.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Textus
+  module Hooks
+    class Dispatcher
+      HOOK_TIMEOUT_SECONDS = 2
+
+      def initialize(audit_log:)
+        @audit_log = audit_log
+        @subscribers = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def subscribe(event, name, keys: nil, &block)
+        @subscribers[event.to_sym] << { name: name.to_sym, callable: block, keys: keys }
+      end
+
+      def publish(event, **kwargs)
+        key = kwargs[:key] || "-"
+        @subscribers[event.to_sym].each do |sub|
+          next unless match?(sub[:keys], key)
+
+          invoke(event, sub, key, kwargs)
+        end
+      end
+
+      private
+
+      def invoke(event, sub, key, kwargs)
+        Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**kwargs) }
+      rescue StandardError => e
+        extras = { "event" => event.to_s, "hook" => sub[:name].to_s, "error" => "#{e.class}: #{e.message}" }
+        extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
+        extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
+        @audit_log.append(
+          role: "script", verb: "event_error", key: key,
+          etag_before: nil, etag_after: nil, extras: extras
+        )
+      end
+
+      def match?(globs, key)
+        return true if globs.nil?
+
+        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
+      end
+    end
+  end
+end

data/lib/textus/hooks/loader.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Hooks
+    module Loader
+      THREAD_REGISTRY_KEY = :__textus_active_registry__
+      private_constant :THREAD_REGISTRY_KEY
+
+      def self.with_registry(registry)
+        prev = Thread.current[THREAD_REGISTRY_KEY]
+        Thread.current[THREAD_REGISTRY_KEY] = registry
+        yield
+      ensure
+        Thread.current[THREAD_REGISTRY_KEY] = prev
+      end
+
+      def self.current_registry
+        Thread.current[THREAD_REGISTRY_KEY] or
+          raise UsageError.new("no active registry; hook code must be loaded by a Store")
+      end
+    end
+  end
+
+  # Public DSL — unchanged surface
+  def self.with_registry(registry, &) = Hooks::Loader.with_registry(registry, &)
+  def self.current_registry           = Hooks::Loader.current_registry
+  def self.hook(event, name, **, &)   = Hooks::Loader.current_registry.register(event, name, **, &)
+end