textus 0.55.2 → 0.56.0

data/lib/textus/manifest/resolver.rb

@@ -1,118 +0,0 @@
-module Textus
-  class Manifest
-    class Resolver
-      Resolution = ::Data.define(:entry, :path, :remaining)
-
-      def initialize(data)
-        @data = data
-      end
-
-      def resolve(key)
-        @data.validate_key!(key)
-        segments = key.split(".")
-        candidates = @data.entries
-                          .map { |e| [e, e.key.split(".")] }
-                          .select { |(_, esegs)| esegs == segments[0, esegs.length] }
-                          .sort_by { |(_, esegs)| -esegs.length }
-        raise UnknownKey.new(key, suggestions: suggestions_for(key)) if candidates.empty?
-
-        entry, esegs = candidates.first
-        remaining = segments[esegs.length..]
-        build_resolution(entry, remaining, key)
-      end
-
-      def suggestions_for(key)
-        candidates = enumerate.map { |r| r[:key] }
-        candidates.concat(@data.entries.reject { |e| nested_entry?(e) }.map(&:key))
-        candidates.uniq!
-        Key::Distance.suggest(key, candidates, limit: 5)
-      rescue StandardError
-        []
-      end
-
-      def enumerate(prefix: nil, include_keyless: false)
-        out = @data.entries.flat_map do |entry|
-          nested_entry?(entry) ? enumerate_nested(entry, include_keyless: include_keyless) : enumerate_leaf(entry)
-        end
-        out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
-        out.sort_by { |row| row[:key] }
-      end
-
-      private
-
-      # Returns true for entries that behave as nested (Nested subclass, or any
-      # entry with nested: true in the raw YAML — e.g. Intake entries covering
-      # a directory of leaf files).
-      def nested_entry?(entry)
-        entry.nested?
-      end
-
-      def build_resolution(entry, remaining, key)
-        if remaining.empty?
-          Resolution.new(entry: entry, path: resolve_leaf_path(entry), remaining: [])
-        else
-          raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless nested_entry?(entry)
-
-          primary_ext = Textus::Format.for(entry.format).extensions.first
-          base = Textus::Key::Path.normalize_relative_path(entry.path)
-          path = File.join(@data.root, base, *remaining) + primary_ext
-          Resolution.new(entry: entry, path: path, remaining: remaining)
-        end
-      end
-
-      def enumerate_leaf(entry)
-        fp = resolve_leaf_path(entry)
-        File.exist?(fp) ? [{ key: entry.key, path: fp, manifest_entry: entry }] : []
-      end
-
-      def enumerate_nested(entry, include_keyless: false)
-        # publish_tree mirrors opaque payload by path — its files are never
-        # enumerated as keys (ADR 0047). Ask the resolved mode, not the path.
-        # The `include_keyless:` override is used only by the projection lister
-        # so that `from: project` selects can read source data from keyless
-        # nested entries (e.g. knowledge.decisions) without exposing them as
-        # addressable store keys in the public `list` surface.
-        return [] if entry.publish_mode.keyless? && !include_keyless
-
-        base = File.join(@data.root, Textus::Key::Path.normalize_relative_path(entry.path))
-        return [] unless File.directory?(base)
-
-        Dir.glob(File.join(base, nested_glob(entry.format)))
-           .filter_map { |path| nested_row_for(entry, base, path) }
-      end
-
-      def nested_row_for(entry, base, path)
-        rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-        return nil if entry.ignored?(rel)
-
-        stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
-        segs = stripped.split("/").reject { |s| s.empty? || s == "." }
-        return nil if segs.empty?
-
-        illegal = segs.find { |s| !valid_segment?(s) }
-        if illegal
-          warn("textus: skipping illegal key segment '#{illegal}' at #{path} — " \
-               "rename to match [a-z0-9][a-z0-9-]* (run 'textus doctor' for the full list)")
-          return nil
-        end
-
-        { key: (entry.key.split(".") + segs).join("."), path: path, manifest_entry: entry }
-      end
-
-      def valid_segment?(seg)
-        return false if seg.nil? || seg.empty?
-        return false if seg.length > Key::Grammar::MAX_SEGMENT_LEN
-
-        seg.match?(Key::Grammar::SEGMENT)
-      end
-
-      def resolve_leaf_path(entry)
-        Textus::Key::Path.resolve(@data, entry)
-      end
-
-      def nested_glob(format)
-        Textus::Format.for(format).nested_glob
-      end
-    end
-  end
-end

data/lib/textus/manifest/rules.rb

@@ -1,86 +0,0 @@
-module Textus
-  class Manifest
-    class Rules
-      # Every structural member here derives from Schema::FIELD_REGISTRY (WS3),
-      # so a new rule field is added in one place. `in_pick` selects the fields
-      # that participate in the most-specific `for(key)` resolution.
-      PICK_FIELDS = Schema::FIELD_REGISTRY.select { |_, m| m[:in_pick] }.keys.freeze
-
-      RuleSet = ::Data.define(*PICK_FIELDS)
-      EMPTY_SET = RuleSet.new(**PICK_FIELDS.to_h { |f| [f, nil] })
-
-      def self.parse(raw)
-        new(Array(raw).map { |b| Block.new(b) })
-      end
-
-      def initialize(blocks)
-        @blocks = blocks
-      end
-
-      attr_reader :blocks
-
-      def for(key)
-        slots = PICK_FIELDS.to_h { |f| [f, []] }
-        @blocks.each do |b|
-          next unless Textus::Manifest::Policy::Matcher.matches?(b.match, key)
-
-          slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
-        end
-        RuleSet.new(**slots.to_h { |slot, blocks| [slot, pick(blocks, slot, key)] })
-      end
-
-      def explain(key)
-        @blocks.select { |b| Textus::Manifest::Policy::Matcher.matches?(b.match, key) }
-      end
-
-      private
-
-      def pick(blocks, slot, key)
-        return nil if blocks.empty?
-
-        globs = blocks.map(&:match)
-        winning = Textus::Manifest::Policy::Matcher.pick_most_specific(globs, key: key)
-        blocks.find { |b| b.match == winning }&.public_send(slot)
-      end
-
-      class Block
-        attr_reader :match, *Schema::FIELD_REGISTRY.keys
-
-        def initialize(raw)
-          @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
-          Schema::FIELD_REGISTRY.each do |field, meta|
-            instance_variable_set("@#{field}", parse_field(meta, raw[meta[:yaml_key]]))
-          end
-        end
-
-        private
-
-        # One dispatch over the registry, replacing the four bespoke parse_*
-        # methods. :deferred carries the raw Hash after a shape check (its
-        # contents validate later — guard predicates at Dispatch::Auth check time,
-        # ADR 0031); :immediate instantiates the policy class now. :tagged passes
-        # the raw Hash straight to a policy class that is a tagged union and
-        # dispatches on its discriminator field (e.g. upkeep's on:). A mapping
-        # field (sub_keys) splats its nested keys as kwargs; a scalar/array
-        # field passes its raw value under arg_key.
-        def parse_field(meta, value)
-          return nil if value.nil?
-
-          if meta[:validation] == :deferred
-            raise Textus::BadManifest.new("#{meta[:yaml_key]}: must be a map of transition => [predicates]") unless value.is_a?(Hash)
-
-            return value
-          end
-
-          return meta[:policy_class].new(value) if meta[:validation] == :tagged
-
-          if meta[:sub_keys]
-            meta[:policy_class].new(**meta[:sub_keys].to_h { |k| [k.to_sym, value[k]] })
-          else
-            meta[:policy_class].new(meta[:arg_key] => value)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/contract.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/schema"
-
-module Textus
-  class Manifest
-    module Schema
-      # rubocop:disable Metrics/BlockLength
-      Contract = Dry::Schema.JSON do
-        required(:lanes).value(:array).each do
-          hash do
-            required(:name).value(:string)
-            required(:kind).value(included_in?: Vocabulary::LANE_KINDS)
-            optional(:owner).value(:string)
-            optional(:desc).value(:string)
-          end
-        end
-
-        optional(:roles).value(:array).each do
-          hash do
-            required(:name).value(:string)
-            optional(:can).value(:array).each(:string)
-          end
-        end
-
-        optional(:entries).value(:array).each do
-          hash do
-            required(:key).value(:string)
-            required(:lane).value(:string)
-            optional(:path).value(:string)
-            optional(:owner).value(:string)
-            optional(:format).value(:string)
-            optional(:schema).maybe(:string)
-            optional(:kind).value(:string)
-            optional(:nested).value(:bool)
-            optional(:tracked).value(:bool)
-            optional(:ignore)
-            optional(:source)
-            optional(:publish).value(:array)
-          end
-        end
-
-        optional(:rules).value(:array).each do
-          hash do
-            optional(:match).value(:string)
-            optional(:guard)
-            optional(:retention)
-            optional(:react)
-          end
-        end
-
-        optional(:audit).hash do
-          optional(:max_size).value(:integer)
-          optional(:keep).value(:integer)
-        end
-        optional(:version).value(:string)
-      end
-      # rubocop:enable Metrics/BlockLength
-    end
-  end
-end

data/lib/textus/manifest/schema/keys.rb

@@ -1,90 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      # The manifest's key whitelists and the rule-field registry — the schema's
-      # data tables (ADR 0109; the vocabulary lives in Schema::Vocabulary).
-      module Keys
-        ROOT_KEYS  = %w[version roles lanes entries rules audit].freeze
-        ROLE_KEYS  = %w[name can].freeze
-        LANE_KEYS  = %w[name kind owner desc].freeze
-        ENTRY_KEYS = %w[
-          key path lane kind schema owner nested format
-          source publish tracked ignore
-        ].freeze
-        # ADR 0052: the typed publish block — `publish: { to: [...] }` (file
-        # fan-out) xor `publish: { tree: "dir" }` (subtree mirror).
-        PUBLISH_KEYS = %w[to tree].freeze
-        # entry-level external-generator block — only `from: external` is valid.
-        # `from: fetch` and `from: derive` and their specific fields (handler,
-        # config, ttl, select, pluck, sort_by, transform) were removed in the
-        # workflow redesign.
-        SOURCE_KEYS = %w[from command sources].freeze
-        # ADR 0093: rule-level GC slot. drop/archive only (refresh gone).
-        RETENTION_KEYS = %w[ttl action].freeze
-
-        # The ONE source of truth for the rule-block field set (WS3). Adding a
-        # rule field means adding one entry here; everything downstream derives
-        # from it so the ~9 enumeration sites the audit found can't drift:
-        #   - Schema::RULE_KEYS and the per-field sub-key walk (Schema::Validator)
-        #   - Rules: the RuleSet members, EMPTY_SET, the `for` slots accumulator,
-        #     Block's attr_readers, and the parse dispatch
-        #   - Doctor::Check::RuleAmbiguity SLOTS (in_ambiguity)
-        #   - Read::RuleList / Read::RuleExplain field membership
-        #     (in_rule_list / in_rule_explain)
-        #
-        # Per field:
-        #   yaml_key     manifest key used in a rule block
-        #   policy_class the Manifest::Policy backing the field (nil = raw value)
-        #   validation   :immediate (instantiate the policy at parse, surfacing
-        #                shape errors eagerly), :deferred (shape-check + carry
-        #                the raw Hash; guard predicates validate at Dispatch::Auth
-        #                build time, ADR 0031), or :tagged (pass the raw Hash to a
-        #                tagged-union policy that dispatches on its discriminator
-        #                field, e.g. upkeep's on:)
-        #   sub_keys     allowed nested keys for a mapping field (drives both the
-        #                schema sub-key walk and the kwargs splat into policy_class)
-        #   arg_key      for an immediate non-mapping field, the single kwarg the
-        #                raw value is passed under
-        #   in_pick      participates in the most-specific `for(key)` resolution
-        #   in_ambiguity linted by doctor's same-specificity tie check
-        #   in_rule_list shown in the whole-manifest rule_list view
-        #   in_rule_explain depths the field shows at: :lean and/or :detail
-        #
-        # Key order here fixes the order of RULE_KEYS (after match), the slots,
-        # the RuleSet members, and the doctor SLOTS.
-        FIELD_REGISTRY = {
-          guard: {
-            yaml_key: "guard",
-            policy_class: nil,
-            validation: :deferred, sub_keys: nil, arg_key: nil,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-          retention: {
-            yaml_key: "retention",
-            policy_class: Textus::Manifest::Policy::Retention,
-            validation: :tagged, sub_keys: RETENTION_KEYS, arg_key: nil,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-          react: {
-            yaml_key: "react",
-            policy_class: Textus::Manifest::Policy::React,
-            validation: :immediate, sub_keys: nil, arg_key: :raw,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-        }.freeze
-
-        RULE_KEYS = (["match"] + FIELD_REGISTRY.values.map { |m| m[:yaml_key] }).freeze
-        AUDIT_KEYS = %w[max_size keep].freeze
-        # Syntactic shape of an `owner:` subject token (the `patrick` in
-        # `human:patrick`) — the subject half of the owner-validation rule below.
-        # Role supplies the archetype set (Role::NAMES); this pattern is the
-        # owner-specific part, so it lives with the rule that composes them
-        # (ADR 0045 D1). Acting-role *names* are gated by Role::NAMES, not a regex.
-        OWNER_SUBJECT_PATTERN = /\A[a-z][a-z0-9_-]*\z/
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics/cross_field.rb

@@ -1,53 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module CrossField
-          def check_cross_field!(raw)
-            check_owners!(raw["lanes"], raw["entries"])
-            check_lane_kind_consistency!(raw)
-          end
-
-          def check_owners!(lanes, entries)
-            Array(lanes).each_with_index { |z, i| check_owner!(z["owner"], "$.lanes[#{i}]") }
-            Array(entries).each_with_index { |e, i| check_owner!(e["owner"], "$.entries[#{i}]") }
-          end
-
-          def check_owner!(owner, path)
-            return if owner.nil?
-            return if valid_owner?(owner)
-
-            raise BadManifest.new(
-              "invalid owner '#{owner}' at '#{path}' " \
-              "(expected <archetype> or <archetype>:<subject>, archetype one of: #{Textus::Value::Role::NAMES.join(", ")})",
-            )
-          end
-
-          def valid_owner?(token)
-            return false unless token.is_a?(String) && !token.empty?
-
-            archetype, subject = token.split(":", 2)
-            return false unless Textus::Value::Role::NAMES.include?(archetype)
-            return true if subject.nil?
-
-            OWNER_SUBJECT_PATTERN.match?(subject)
-          end
-
-          def check_lane_kind_consistency!(raw)
-            held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
-
-            Array(raw["lanes"]).each_with_index do |z, i|
-              verb = KIND_REQUIRES_VERB[z["kind"]]
-              next if verb.nil? || held.include?(verb)
-
-              raise BadManifest.new(
-                "lane '#{z["name"]}' (#{z["kind"]}) at '$.lanes[#{i}]' " \
-                "needs a role with capability '#{verb}'; none declared",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics/invariants.rb

@@ -1,125 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module Invariants
-          def check_invariants!(raw)
-            check_roles!(raw["roles"])
-            check_lanes!(raw["lanes"])
-            check_entries!(raw["entries"])
-            check_rules!(raw["rules"])
-            check_single_queue!(raw)
-            check_single_machine!(raw)
-            walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
-          end
-
-          def check_roles!(roles)
-            return if roles.nil?
-
-            roles.each_with_index do |r, i|
-              path = "$.roles[#{i}]"
-              name = r["name"]
-              unless Textus::Value::Role::NAMES.include?(name)
-                raise BadManifest.new(
-                  "unknown role name '#{name}' at '#{path}' (allowed: #{Textus::Value::Role::NAMES.join(", ")})",
-                )
-              end
-              Array(r["can"]).each do |verb|
-                next if CAPABILITIES.include?(verb)
-
-                hint = %w[ingest fetch].include?(verb) ? " — the quarantine capability folded into 'converge' (ADR 0090)" : ""
-                raise BadManifest.new(
-                  "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
-                  "(known: #{CAPABILITIES.join(", ")})#{hint}",
-                )
-              end
-            end
-
-            author_holders = roles.count { |r| Array(r["can"]).include?("author") }
-            return if author_holders <= 1
-
-            raise BadManifest.new(
-              "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
-            )
-          end
-
-          def check_lanes!(lanes)
-            Array(lanes).each_with_index do |z, i|
-              walk(z, LANE_KEYS, "$.lanes[#{i}]")
-              next unless %w[quarantine derived].include?(z["kind"])
-
-              raise BadManifest.new(
-                "lane kind '#{z["kind"]}' at '$.lanes[#{i}]' was folded into 'machine' (ADR 0091) — " \
-                "use `kind: machine`",
-              )
-            end
-          end
-
-          def check_entries!(entries)
-            Array(entries).each_with_index do |e, i|
-              path = "$.entries[#{i}]"
-              walk(e, ENTRY_KEYS, path)
-              check_publish_block!(e, path)
-              walk(e["source"], SOURCE_KEYS, "#{path}.source") if e.is_a?(Hash) && e["source"].is_a?(Hash)
-            end
-          end
-
-          def check_rules!(rules)
-            Array(rules).each_with_index do |r, i|
-              path = "$.rules[#{i}]"
-              walk(r, RULE_KEYS, path)
-              FIELD_REGISTRY.each_value do |meta|
-                next unless meta[:sub_keys]
-
-                value = r.is_a?(Hash) ? r[meta[:yaml_key]] : nil
-                walk(value, meta[:sub_keys], "#{path}.#{meta[:yaml_key]}") if value.is_a?(Hash)
-              end
-            end
-          end
-
-          def check_publish_block!(entry, path)
-            return unless entry.is_a?(Hash) && entry.key?("publish")
-
-            block = entry["publish"]
-            if block.is_a?(Hash)
-              raise BadManifest.new(
-                "publish: at '#{path}.publish' must be a list of targets (ADR 0094); the map form was retired.",
-              )
-            end
-            raise BadManifest.new("publish: must be a list of targets at '#{path}.publish'") unless block.is_a?(Array)
-
-            block.each_with_index do |t, i|
-              raise BadManifest.new("publish target ##{i} must be a mapping at '#{path}.publish'") unless t.is_a?(Hash)
-
-              walk(t, %w[to tree template inject_boot], "#{path}.publish[#{i}]")
-            end
-          end
-
-          def check_single_queue!(raw)
-            queues = Array(raw["lanes"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
-            return if queues.size <= 1
-
-            raise BadManifest.new("at most one lane may declare kind: queue (found: #{queues.join(", ")})")
-          end
-
-          def check_single_machine!(raw)
-            machines = Array(raw["lanes"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
-            return if machines.size <= 1
-
-            raise BadManifest.new("at most one lane may declare kind: machine (found: #{machines.join(", ")})")
-          end
-
-          def 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
-  end
-end

data/lib/textus/manifest/schema/semantics/migration.rb

@@ -1,83 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module Migration
-          def check_migration!(raw)
-            Array(raw["entries"]).each_with_index do |e, i|
-              path = "$.entries[#{i}]"
-              check_retired_publish_keys!(e, path)
-              check_retired_render_keys!(e, path)
-            end
-            check_rules_retired_keys!(raw["rules"])
-          end
-
-          def check_retired_publish_keys!(entry, path)
-            return unless entry.is_a?(Hash)
-
-            if entry.key?("publish_each")
-              raise BadManifest.new(
-                "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-                "mirror the subtree with `publish: { tree: \"...\" }`.",
-              )
-            end
-            if entry.key?("publish_to")
-              raise BadManifest.new(
-                "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-                "use `publish: { to: [...] }`.",
-              )
-            end
-            if entry.key?("publish_tree")
-              raise BadManifest.new(
-                "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-                "use `publish: { tree: \"...\" }`.",
-              )
-            end
-            return unless entry.key?("index_filename")
-
-            raise BadManifest.new(
-              "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}'.",
-            )
-          end
-
-          def check_retired_render_keys!(entry, path)
-            return unless entry.is_a?(Hash)
-
-            if entry.key?("template")
-              raise BadManifest.new(
-                "entry-level `template:` was removed at '#{path}' (ADR 0094): rendering is a " \
-                "publish concern — `publish: [{ to:, template: }]`.",
-              )
-            end
-            if entry.key?("inject_boot")
-              raise BadManifest.new(
-                "entry-level `inject_boot:` was removed at '#{path}' (ADR 0094).",
-              )
-            end
-            return unless entry.key?("provenance")
-
-            raise BadManifest.new("entry-level `provenance:` was removed at '#{path}' (ADR 0094).")
-          end
-
-          def check_rules_retired_keys!(rules)
-            Array(rules).each_with_index do |r, i|
-              path = "$.rules[#{i}]"
-              { "lifecycle" => "age GC moved to `retention:` rule", "materialize" => "removed (ADR 0093)" }
-                .each do |old, hint|
-                  next unless r.is_a?(Hash) && r.key?(old)
-
-                  raise BadManifest.new("`#{old}:` was removed at '#{path}' (ADR 0093) — #{hint}.")
-                end
-              next unless r.is_a?(Hash) && r.key?("upkeep")
-
-              raise BadManifest.new(
-                "rule key `upkeep:` was removed (ADR 0093): move age-GC to `retention:` " \
-                "and production to the entry's `source:`",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "semantics/invariants"
-require_relative "semantics/migration"
-require_relative "semantics/cross_field"
-
-module Textus
-  class Manifest
-    module Schema
-      # Cross-field rules and ADR migration hints. Called by Validator.validate!
-      # AFTER the structural dry-schema Contract passes. Operates on the raw hash.
-      module Semantics
-        extend Invariants
-        extend Migration
-        extend CrossField
-
-        module_function
-
-        def check!(raw)
-          check_migration!(raw)
-          check_invariants!(raw)
-          check_cross_field!(raw)
-        end
-      end
-    end
-  end
-end