textus 0.10.5 → 0.14.0

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,40 +1,44 @@
 module Textus
   class Manifest
     class Entry
-      PUBLISH_EACH_VARS = %w[leaf basename key ext].freeze
-      PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
-
-      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
-
-      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
-        @generator = raw["generator"]
-        @projection = raw["projection"]
-        @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
@@ -56,178 +60,23 @@ module Textus
       end
 
       # Signal-based zone-kind predicates: derive the "kind" of a zone from its
-      # writable_by signals rather than its literal name, so detection keeps
+      # write_policy signals rather than its literal name, so detection keeps
       # working when users rename the default zones.
       def in_generator_zone?
-        zone_writers.include?("build")
+        zone_writers.include?("builder")
       end
 
       def in_proposal_zone?
-        zone_writers.include?("ai")
+        zone_writers.include?("agent")
       end
 
       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_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/{policies.rb → rules.rb}

@@ -1,8 +1,8 @@
 module Textus
   class Manifest
-    class Policies
-      PolicySet = Data.define(:refresh, :handler_allowlist, :promote, :retention)
-      EMPTY_SET = PolicySet.new(refresh: nil, handler_allowlist: nil, promote: nil, retention: nil)
+    class Rules
+      RuleSet = Data.define(:refresh, :handler_allowlist, :promote, :retention)
+      EMPTY_SET = RuleSet.new(refresh: nil, handler_allowlist: nil, promote: nil, retention: nil)
 
       def self.parse(raw)
         new(Array(raw).map { |b| Block.new(b) })
@@ -21,7 +21,7 @@ module Textus
 
           slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
         end
-        PolicySet.new(
+        RuleSet.new(
           refresh: pick(slots[:refresh], :refresh, key),
           handler_allowlist: pick(slots[:handler_allowlist], :handler_allowlist, key),
           promote: pick(slots[:promote], :promote, key),
@@ -47,10 +47,10 @@ module Textus
         attr_reader :match, :refresh, :handler_allowlist, :promote, :retention
 
         def initialize(raw)
-          @match = raw["match"] or raise Textus::UsageError.new("policy block missing match:")
+          @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
           @refresh = parse_refresh(raw["refresh"])
-          @handler_allowlist = parse_handler_allowlist(raw["handler_allowlist"])
-          @promote = parse_promote(raw["promote_requires"])
+          @handler_allowlist = parse_handler_allowlist(raw["intake_handler_allowlist"])
+          @promote = parse_promotion(raw["promotion"])
           @retention = raw["retention"] # reserved — passthrough only
         end
 
@@ -72,10 +72,12 @@ module Textus
           Textus::Domain::Policy::HandlerAllowlist.new(handlers: arr)
         end
 
-        def parse_promote(arr)
-          return nil if arr.nil?
+        def parse_promotion(h)
+          return nil if h.nil?
+
+          raise Textus::BadManifest.new("promotion: must be a hash with a 'requires:' array") unless h.is_a?(Hash) && h.key?("requires")
 
-          Textus::Domain::Policy::Promote.new(requires: arr)
+          Textus::Domain::Policy::Promote.new(requires: Array(h["requires"]))
         end
       end
     end

data/lib/textus/manifest/schema.rb

@@ -0,0 +1,49 @@
+module Textus
+  class Manifest
+    module Schema
+      ROOT_KEYS    = %w[version zones entries rules].freeze
+      ZONE_KEYS    = %w[name write_policy read_policy].freeze
+      ENTRY_KEYS   = %w[
+        key path zone schema owner nested format
+        compute template publish_to publish_each
+        intake events inject_intro index_filename
+      ].freeze
+      COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
+      INTAKE_KEYS  = %w[handler config].freeze
+      RULE_KEYS    = %w[match refresh intake_handler_allowlist promotion retention].freeze
+      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms].freeze
+      PROMOTION_KEYS = %w[requires].freeze
+
+      def self.validate!(raw)
+        raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
+
+        walk(raw, ROOT_KEYS, "$")
+        Array(raw["zones"]).each_with_index do |z, i|
+          walk(z, ZONE_KEYS, "$.zones[#{i}]")
+        end
+        Array(raw["entries"]).each_with_index do |e, i|
+          path = "$.entries[#{i}]"
+          walk(e, ENTRY_KEYS, path)
+          walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
+          walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
+        end
+        Array(raw["rules"]).each_with_index do |r, i|
+          path = "$.rules[#{i}]"
+          walk(r, RULE_KEYS, path)
+          walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh") if r["refresh"].is_a?(Hash)
+          walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
+        end
+      end
+
+      def self.walk(hash, allowed, path)
+        return unless hash.is_a?(Hash)
+
+        hash.each_key do |k|
+          next if allowed.include?(k)
+
+          raise BadManifest.new("unknown key '#{k}' at '#{path}'")
+        end
+      end
+    end
+  end
+end