textus 0.12.1 → 0.14.1

data/lib/textus/manifest/entry/parser.rb

@@ -0,0 +1,84 @@
+module Textus
+  class Manifest
+    class Entry
+      module Parser
+        COMPUTE_KINDS = %w[projection external].freeze
+
+        def self.call(manifest, raw)
+          key = raw["key"] or raise UsageError.new("manifest entry missing key")
+          path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
+          zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
+
+          nested = raw["nested"] == true
+          compute, projection, generator = parse_compute(raw, key)
+          intake_handler, intake_config = parse_intake(raw["intake"])
+          format = resolve_format(raw, path, nested)
+
+          Textus::Manifest::Entry.new(
+            manifest: manifest, raw: raw,
+            key: key, path: path, zone: zone,
+            schema: raw["schema"], owner: raw["owner"],
+            nested: nested,
+            template: raw["template"],
+            publish_to: Array(raw["publish_to"]),
+            publish_each: raw["publish_each"],
+            events: raw["events"] || {},
+            inject_intro: raw["inject_intro"] == true,
+            index_filename: raw["index_filename"],
+            format: format,
+            compute: compute, projection: projection, generator: generator,
+            intake_handler: intake_handler, intake_config: intake_config
+          )
+        end
+
+        def self.parse_compute(raw, key)
+          src = raw["compute"]
+          return [nil, nil, nil] if src.nil?
+
+          kind = src["kind"]
+          unless COMPUTE_KINDS.include?(kind)
+            raise BadManifest.new(
+              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
+            )
+          end
+
+          frozen = src.freeze
+          if kind == "projection"
+            [frozen, frozen, nil]
+          else
+            [frozen, nil, frozen]
+          end
+        end
+
+        def self.parse_intake(src)
+          src ||= {}
+          [src["handler"], src["config"] || {}]
+        end
+
+        def self.resolve_format(raw, path, nested)
+          declared = raw["format"]
+          ext = File.extname(path)
+          inferred = Textus::Entry.infer_from_extension(ext)
+
+          if declared.nil?
+            return inferred if inferred
+            return "markdown" if ext == "" && nested
+            return "markdown" if ext == ""
+
+            return "markdown"
+          end
+
+          raise UsageError.new("entry '#{raw["key"]}': unknown format #{declared.inspect}") unless Textus::Entry.formats.include?(declared)
+
+          if ext != "" && inferred && inferred != declared
+            raise UsageError.new(
+              "entry '#{raw["key"]}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
+            )
+          end
+
+          declared
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/events.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module Events
+          def self.call(entry)
+            pubsub_events = Textus::Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
+            entry.events.each_key do |evt|
+              next if pubsub_events.include?(evt.to_sym)
+
+              raise UsageError.new(
+                "entry '#{entry.key}': unknown event '#{evt}' in events: block. " \
+                "Known events: #{pubsub_events.join(", ")}.",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -0,0 +1,26 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module FormatMatrix
+          def self.call(entry)
+            begin
+              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested)
+            rescue UsageError => e
+              raise UsageError.new("entry '#{entry.key}': #{e.message}")
+            end
+
+            if entry.format == "text" && !entry.schema.nil?
+              raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
+            end
+
+            return unless entry.in_generator_zone? && entry.template.nil? && entry.generator.nil? &&
+                          %w[markdown text].include?(entry.format) && !entry.nested
+
+            raise UsageError.new("entry '#{entry.key}': derived #{entry.format} entries require a template")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/index_filename.rb

@@ -0,0 +1,45 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module IndexFilename
+          def self.call(entry)
+            return if entry.index_filename.nil?
+
+            check_shape!(entry)
+            check_extension!(entry)
+          end
+
+          def self.check_shape!(entry)
+            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested
+
+            unless entry.index_filename.is_a?(String) && !entry.index_filename.empty?
+              raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
+            end
+
+            return unless entry.index_filename.include?("/") || File.basename(entry.index_filename) != entry.index_filename
+
+            raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
+          end
+
+          def self.check_extension!(entry)
+            ext = File.extname(entry.index_filename)
+            inferred = Textus::Entry.infer_from_extension(ext)
+
+            if inferred.nil?
+              raise UsageError.new(
+                "entry '#{entry.key}': index_filename #{entry.index_filename.inspect} has unknown extension #{ext.inspect}",
+              )
+            end
+            return if inferred == entry.format
+
+            raise UsageError.new(
+              "entry '#{entry.key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
+              "but entry format is #{entry.format.inspect}",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/inject_intro.rb

@@ -0,0 +1,18 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module InjectIntro
+          def self.call(entry)
+            return unless entry.inject_intro
+
+            raise UsageError.new("entry '#{entry.key}': inject_intro: is only valid on derived entries") unless entry.in_generator_zone?
+            return unless entry.template.nil?
+
+            raise UsageError.new("entry '#{entry.key}': inject_intro: requires a template:")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -0,0 +1,37 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module PublishEach
+          KNOWN_VARS = %w[leaf basename key ext].freeze
+          VAR_RE = /\{([a-z]+)\}/
+          REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
+
+          def self.call(entry)
+            return if entry.publish_each.nil?
+
+            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested
+            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless entry.publish_to.empty?
+            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless entry.publish_each.is_a?(String)
+
+            used_vars = entry.publish_each.scan(VAR_RE).flatten
+            unknown = used_vars - KNOWN_VARS
+            unless unknown.empty?
+              raise UsageError.new(
+                "entry '#{entry.key}': publish_each uses unknown template variable(s) " \
+                "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{KNOWN_VARS.map { |v| "{#{v}}" }.join(", ")}.",
+              )
+            end
+
+            return if used_vars.any? { |v| REQUIRED_DISCRIMINATOR_VARS.include?(v) }
+
+            raise UsageError.new(
+              "entry '#{entry.key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
+              "(else every leaf would clobber the same target).",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators.rb

@@ -0,0 +1,20 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        REGISTERED = [
+          Events,
+          PublishEach,
+          InjectIntro,
+          IndexFilename,
+          FormatMatrix,
+        ].freeze
+
+        def self.run_all(entry)
+          REGISTERED.each { |v| v.call(entry) }
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry.rb

@@ -1,41 +1,44 @@
 module Textus
   class Manifest
     class Entry
-      PUBLISH_EACH_VARS = %w[leaf basename key ext].freeze
-      PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
-
-      COMPUTE_KINDS = %w[projection external].freeze
-
-      attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
-                  :projection, :template, :publish_to, :publish_each,
-                  :intake_handler, :intake_config,
-                  :events, :inject_intro, :index_filename, :compute
-
-      def initialize(manifest, raw)
+      # Re-exported for backward compatibility with callers that referenced these
+      # constants on Entry. Canonical source is the PublishEach validator.
+      PUBLISH_EACH_VARS = Validators::PublishEach::KNOWN_VARS
+      PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
+
+      attr_reader :raw, :key, :path, :zone, :schema, :owner, :nested,
+                  :template, :publish_to, :publish_each,
+                  :events, :inject_intro, :index_filename, :format,
+                  :compute, :projection, :generator,
+                  :intake_handler, :intake_config
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, nested:,
+                     template:, publish_to:, publish_each:, events:, inject_intro:,
+                     index_filename:, format:, compute:, projection:, generator:,
+                     intake_handler:, intake_config:)
         @manifest = manifest
         @raw = raw
-        @key = raw["key"] or raise UsageError.new("manifest entry missing key")
-        @path = raw["path"] or raise UsageError.new("manifest entry '#{@key}' missing path")
-        @zone = raw["zone"] or raise UsageError.new("manifest entry '#{@key}' missing zone")
-        @schema = raw["schema"]
-        @owner = raw["owner"]
-        @nested = raw["nested"] == true
-        parse_compute!(raw)
-        @template = raw["template"]
-        @publish_to = Array(raw["publish_to"])
-        @publish_each = raw["publish_each"]
-        @events = raw["events"] || {}
-        @inject_intro = raw["inject_intro"] == true
-        @index_filename = raw["index_filename"]
-        @format = resolve_format!(raw["format"])
-
-        validate_events!
-        parse_intake!(raw["intake"])
-        validate_format_matrix!
-        validate_publish_each!
-        validate_inject_intro!
-        validate_index_filename!
+        @key = key
+        @path = path
+        @zone = zone
+        @schema = schema
+        @owner = owner
+        @nested = nested
+        @template = template
+        @publish_to = publish_to
+        @publish_each = publish_each
+        @events = events
+        @inject_intro = inject_intro
+        @index_filename = index_filename
+        @format = format
+        @compute = compute
+        @projection = projection
+        @generator = generator
+        @intake_handler = intake_handler
+        @intake_config = intake_config
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Resolves the per-leaf target path (relative to repo root) for a full
       # dotted key under this entry's prefix. Returns nil if this entry has no
@@ -69,192 +72,11 @@ module Textus
 
       private
 
-      # `index_filename:` makes a nested entry treat a fixed basename (e.g.
-      # `SKILL.md`) as the per-directory row. The directory path becomes the
-      # key suffix; sibling files are not enumerated. Allows projecting
-      # spec-mandated filenames that would otherwise be rejected by the
-      # lowercase-only key segment grammar.
-      def validate_index_filename!
-        return if @index_filename.nil?
-
-        raise UsageError.new("entry '#{@key}': index_filename requires nested: true") unless @nested
-        unless @index_filename.is_a?(String) && !@index_filename.empty?
-          raise UsageError.new("entry '#{@key}': index_filename must be a non-empty string")
-        end
-        if @index_filename.include?("/") || File.basename(@index_filename) != @index_filename
-          raise UsageError.new("entry '#{@key}': index_filename must be a bare basename (no slashes)")
-        end
-
-        ext = File.extname(@index_filename)
-        inferred = Manifest::EXT_TO_FORMAT[ext]
-        if inferred.nil?
-          raise UsageError.new(
-            "entry '#{@key}': index_filename #{@index_filename.inspect} has unknown extension #{ext.inspect}",
-          )
-        end
-        return if inferred == @format
-
-        raise UsageError.new(
-          "entry '#{@key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
-          "but entry format is #{@format.inspect}",
-        )
-      end
-
       def zone_writers
         @manifest.zone_writers(@zone)
       rescue UsageError => e
         raise UsageError.new("entry '#{@key}': #{e.message}")
       end
-
-      def validate_inject_intro!
-        return unless @inject_intro
-
-        unless in_generator_zone?
-          raise UsageError.new(
-            "entry '#{@key}': inject_intro: is only valid on derived entries",
-          )
-        end
-        return unless @template.nil?
-
-        raise UsageError.new(
-          "entry '#{@key}': inject_intro: requires a template:",
-        )
-      end
-
-      def validate_publish_each!
-        return if @publish_each.nil?
-
-        raise UsageError.new("entry '#{@key}': publish_each requires nested: true") unless @nested
-        raise UsageError.new("entry '#{@key}': publish_to and publish_each are mutually exclusive") unless @publish_to.empty?
-        raise UsageError.new("entry '#{@key}': publish_each must be a string") unless @publish_each.is_a?(String)
-
-        used_vars = @publish_each.scan(PUBLISH_EACH_VAR_RE).flatten
-        unknown = used_vars - PUBLISH_EACH_VARS
-        unless unknown.empty?
-          raise UsageError.new(
-            "entry '#{@key}': publish_each uses unknown template variable(s) " \
-            "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{PUBLISH_EACH_VARS.map { |v| "{#{v}}" }.join(", ")}.",
-          )
-        end
-
-        required = %w[leaf basename key]
-        return if used_vars.any? { |v| required.include?(v) }
-
-        raise UsageError.new(
-          "entry '#{@key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
-          "(else every leaf would clobber the same target).",
-        )
-      end
-
-      def resolve_format!(declared)
-        ext = File.extname(@path)
-        inferred = Manifest::EXT_TO_FORMAT[ext]
-
-        if declared.nil?
-          return inferred if inferred
-          # No extension: nested defaults to markdown, leaf with no ext also markdown.
-          return "markdown" if ext == "" && @nested
-          return "markdown" if ext == ""
-        else
-          unless Manifest::EXT_TO_FORMAT.values.include?(declared)
-            raise UsageError.new("entry '#{@key}': unknown format #{declared.inspect}")
-          end
-          # If the path has an extension, the declared format must match.
-          if ext != "" && inferred && inferred != declared
-            raise UsageError.new(
-              "entry '#{@key}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
-            )
-          end
-          return declared
-        end
-
-        "markdown"
-      end
-
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def validate_format_matrix!
-        ext = File.extname(@path)
-
-        case @format
-        when "markdown"
-          # .md, or no extension (will be appended). Anything else is a mismatch caught above.
-          raise UsageError.new("entry '#{@key}': markdown format requires '.md' path (got #{ext.inspect})") if ext != "" && ext != ".md"
-        when "json"
-          if @nested
-            # nested json: path is a directory; ext must be empty.
-            raise UsageError.new("entry '#{@key}': nested json path must not have an extension") if ext != ""
-          elsif ext != ".json"
-            raise UsageError.new("entry '#{@key}': json format requires '.json' path (got #{ext.inspect})")
-          end
-        when "yaml"
-          if @nested
-            raise UsageError.new("entry '#{@key}': nested yaml path must not have an extension") if ext != ""
-          elsif ext != ".yaml" && ext != ".yml"
-            raise UsageError.new("entry '#{@key}': yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
-          end
-        when "text"
-          if @nested
-            raise UsageError.new("entry '#{@key}': nested text path must not have an extension") if ext != ""
-          elsif ext != ".txt" && ext != ""
-            raise UsageError.new("entry '#{@key}': text format requires '.txt' or no extension (got #{ext.inspect})")
-          end
-        end
-
-        # Schema rules.
-        raise UsageError.new("entry '#{@key}': text format must not declare a schema") if @format == "text" && !@schema.nil?
-
-        # Template-required-for-derived rules. Skipped for entries materialized by an
-        # external generator: command (those produce the bytes themselves).
-        if in_generator_zone? && @template.nil? && @generator.nil? &&
-           (@format == "markdown" || @format == "text") && !@nested
-          raise UsageError.new("entry '#{@key}': derived #{@format} entries require a template")
-        end
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
-      def parse_compute!(raw)
-        src = raw["compute"]
-        unless src
-          @compute = nil
-          @projection = nil
-          @generator = nil
-          return
-        end
-
-        kind = src["kind"]
-        unless COMPUTE_KINDS.include?(kind)
-          raise BadManifest.new(
-            "entry '#{@key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
-          )
-        end
-
-        @compute = src.freeze
-        if kind == "projection"
-          @projection = @compute
-          @generator  = nil
-        else
-          @generator  = @compute
-          @projection = nil
-        end
-      end
-
-      def parse_intake!(src)
-        src ||= {}
-        @intake_handler = src["handler"]
-        @intake_config  = src["config"] || {}
-      end
-
-      def validate_events!
-        pubsub_events = Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
-        @events.each_key do |evt|
-          next if pubsub_events.include?(evt.to_sym)
-
-          raise UsageError.new(
-            "entry '#{@key}': unknown event '#{evt}' in events: block. " \
-            "Known events: #{pubsub_events.join(", ")}.",
-          )
-        end
-      end
     end
   end
 end

data/lib/textus/manifest.rb

@@ -3,14 +3,6 @@ require_relative "manifest/schema"
 
 module Textus
   class Manifest
-    EXT_TO_FORMAT = {
-      ".md" => "markdown",
-      ".json" => "json",
-      ".yaml" => "yaml",
-      ".yml" => "yaml",
-      ".txt" => "text",
-    }.freeze
-
     TEXTUS_2_HINT = "Install textus 0.11.x to run the migrator, then upgrade to this version. " \
                     "See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110".freeze
 
@@ -47,14 +39,7 @@ module Textus
 
     def self.parse(yaml_text, root: ".")
       raw = YAML.safe_load(yaml_text, aliases: false)
-      unless raw["version"] == PROTOCOL
-        raise BadFrontmatter.new(
-          "<string>",
-          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-          hint: version_hint_for(raw["version"]),
-        )
-      end
-
+      check_version!(raw, "<string>")
       new(root, raw)
     end
 
@@ -63,17 +48,21 @@ module Textus
       raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
 
       raw = YAML.safe_load_file(manifest_path, aliases: false)
-      unless raw["version"] == PROTOCOL
-        raise BadFrontmatter.new(
-          manifest_path,
-          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-          hint: version_hint_for(raw["version"]),
-        )
-      end
-
+      check_version!(raw, manifest_path)
       new(root, raw)
     end
 
+    def self.check_version!(raw, source)
+      return if raw["version"] == PROTOCOL
+
+      raise BadFrontmatter.new(
+        source,
+        "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+        hint: version_hint_for(raw["version"]),
+      )
+    end
+    private_class_method :check_version!
+
     def initialize(root, raw)
       @root = root
       @raw = raw
@@ -81,7 +70,11 @@ module Textus
 
       Schema.validate!(raw)
 
-      @entries = Array(raw["entries"]).map { |e| Manifest::Entry.new(self, e) }
+      @entries = Array(raw["entries"]).map do |e|
+        entry = Manifest::Entry::Parser.call(self, e)
+        Manifest::Entry::Validators.run_all(entry)
+        entry
+      end
       validate_declared_keys!
     end
 
@@ -194,13 +187,7 @@ module Textus
     end
 
     def nested_glob(format)
-      case format
-      when "markdown" then "**/*.md"
-      when "json" then "**/*.json"
-      when "yaml" then "**/*.{yaml,yml}"
-      when "text" then "**/*.txt"
-      else raise UsageError.new("unknown format #{format.inspect} for nested glob")
-      end
+      Textus::Entry.for_format(format).nested_glob
     end
   end
 end

data/lib/textus/operations/reads.rb

@@ -0,0 +1,39 @@
+module Textus
+  class Operations
+    class Reads
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def get
+        Application::Reads::Get.new(ctx: @ctx, orchestrator: orchestrator)
+      end
+
+      def freshness      = Application::Reads::Freshness.new(ctx: @ctx)
+      def audit          = Application::Reads::Audit.new(ctx: @ctx)
+      def blame          = Application::Reads::Blame.new(ctx: @ctx)
+      def policy_explain = Application::Reads::PolicyExplain.new(ctx: @ctx)
+      def list           = Application::Reads::List.new(ctx: @ctx)
+      def where           = Application::Reads::Where.new(ctx: @ctx)
+      def uid             = Application::Reads::Uid.new(ctx: @ctx)
+      def schema_envelope = Application::Reads::SchemaEnvelope.new(ctx: @ctx)
+      def deps            = Application::Reads::Deps.new(ctx: @ctx)
+      def rdeps           = Application::Reads::Rdeps.new(ctx: @ctx)
+      def published       = Application::Reads::Published.new(ctx: @ctx)
+      def stale           = Application::Reads::Stale.new(ctx: @ctx)
+      def validate_all    = Application::Reads::ValidateAll.new(ctx: @ctx)
+
+      private
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus),
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+    end
+  end
+end

data/lib/textus/operations/refresh.rb

@@ -0,0 +1,27 @@
+module Textus
+  class Operations
+    class Refresh
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def worker
+        Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: worker,
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+
+      def all
+        Application::Refresh::All.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+    end
+  end
+end