textus 0.4.0 → 0.8.0

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

@@ -0,0 +1,57 @@
+require "digest"
+require "json"
+
+module Textus
+  module Doctor
+    class Check
+      class Sentinels < Check
+        def call
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Textus
+  module Doctor
+    class Check
+      class Templates < Check
+        def call
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Textus
+  module Doctor
+    class Check
+      class UnownedSchemaFields < Check
+        def call
+          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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check.rb

@@ -0,0 +1,30 @@
+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(store)
+        @store = store
+      end
+
+      def call
+        raise NotImplementedError.new("#{self.class.name}#call not implemented")
+      end
+
+      protected
+
+      attr_reader :store
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -1,27 +1,40 @@
-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 -- 8 built-in checks + extension dispatch
+  module Doctor
     LEVELS = %w[error warning info].freeze
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
+    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)
-      issues = []
-      issues.concat(check_manifest_files(store))
-      issues.concat(check_schemas(store))
-      issues.concat(check_templates(store))
-      issues.concat(check_extensions(store))
-      issues.concat(check_illegal_keys(store))
-      issues.concat(check_sentinels(store))
-      issues.concat(check_audit_log(store))
-      issues.concat(check_unowned_schema_fields(store))
+    def run(store, checks: nil)
+      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(store).call }
       issues.concat(run_registered_checks(store))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
@@ -33,236 +46,11 @@ module Textus
       }
     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?
-
-        # Audit log is TSV, not NDJSON. Treat as malformed if it doesn't have
-        # at least 6 tab-separated fields (timestamp, role, verb, key, etag_before, etag_after).
-        fields = stripped.split("\t")
-        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)",
-            "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-          }
-          next
-        end
-
-        extras = fields[6]
-        next if extras.nil? || extras.empty?
-
-        begin
-          JSON.parse(extras)
-        rescue JSON::ParserError => e
-          out << {
-            "code" => "audit.parse_error",
-            "level" => "warning",
-            "subject" => "#{path}:#{lineno}",
-            "message" => "audit log line #{lineno} extras JSON malformed: #{e.message}",
-            "fix" => "inspect #{path} at line #{lineno} and fix the JSON in the last column",
-          }
-        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 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)
@@ -294,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?
@@ -17,13 +17,15 @@ module Textus
 
         meta = parsed["_meta"]
         fm = meta.is_a?(Hash) ? meta : {}
-        { "frontmatter" => fm, "body" => raw, "content" => parsed }
+        content_without_meta = parsed.except("_meta")
+        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
-        _ = frontmatter
+      def self.serialize(meta:, body:, content: nil)
         if content.is_a?(Hash)
-          out = ::JSON.pretty_generate(content)
+          # Re-inject _meta as the first key so on-disk shape is stable.
+          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?
@@ -35,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,11 +3,11 @@ 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?
-        return { "frontmatter" => {}, "body" => raw, "content" => nil } unless raw.start_with?("---\n") || raw.start_with?("---\r\n")
+        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("---")
@@ -22,12 +22,12 @@ module Textus
           raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
         end
         fm = {} unless fm.is_a?(Hash)
-        { "frontmatter" => fm, "body" => body, "content" => nil }
+        { "_meta" => fm, "body" => body, "content" => nil }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
+      def self.serialize(meta:, body:, content: nil)
         _ = content # markdown ignores content
-        fm_yaml = frontmatter.empty? ? "" : ::YAML.dump(frontmatter).sub(/\A---\n/, "")
+        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}"

data/lib/textus/entry/text.rb

@@ -1,16 +1,16 @@
 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?
 
-        { "frontmatter" => {}, "body" => raw, "content" => nil }
+        { "_meta" => {}, "body" => raw, "content" => nil }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
-        _ = frontmatter
+      def self.serialize(meta:, body:, content: nil)
+        _ = meta
         _ = content
         b = body.to_s
         b += "\n" unless b.empty? || b.end_with?("\n")

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?
@@ -17,13 +17,15 @@ module Textus
 
         meta = parsed["_meta"]
         fm = meta.is_a?(Hash) ? meta : {}
-        { "frontmatter" => fm, "body" => raw, "content" => parsed }
+        content_without_meta = parsed.except("_meta")
+        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
-        _ = frontmatter
+      def self.serialize(meta:, body:, content: nil)
         if content.is_a?(Hash)
-          ::YAML.dump(content).sub(/\A---\n/, "")
+          # Re-inject _meta as the first key so on-disk shape is stable.
+          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")
@@ -33,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
@@ -23,8 +18,8 @@ module Textus
       for_format(format).parse(raw, path: path)
     end
 
-    def self.serialize(frontmatter: {}, body: "", content: nil, format: "markdown")
-      for_format(format).serialize(frontmatter: frontmatter, body: body, content: content)
+    def self.serialize(meta: {}, body: "", content: nil, format: "markdown")
+      for_format(format).serialize(meta: meta, body: body, content: content)
     end
   end
 end