textus 0.55.2 → 0.56.0

data/lib/textus/dispatch/middleware/audit_index.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Dispatch
-    module Middleware
-      # Shadows successful write operations into the SQLite audit_events table
-      # synchronously after dispatch, without the command knowing. Read verbs
-      # and failed writes pass through unchanged.
-      class AuditIndex < Base
-        middleware_name :audit_index
-
-        INDEXED_CONTRACTS = [
-          Contracts::PutEntry,
-          Contracts::DeleteKey,
-          Contracts::MoveKey,
-        ].freeze
-
-        def initialize(job_store:, audit_log:)
-          super()
-          @job_store = job_store
-          @audit_log = audit_log
-        end
-
-        def call(container:, command:, call:, next_handler:) # rubocop:disable Lint/UnusedMethodArgument
-          result = next_handler.call(command, call)
-          return result unless result.success? && INDEXED_CONTRACTS.include?(command.class)
-
-          key = command.respond_to?(:key) ? command.key : nil
-          return result unless key
-
-          seq = @audit_log.latest_seq
-          verb = command.class.name.split("::").last
-                        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-                        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-                        .downcase
-
-          @job_store.insert_audit_event(
-            seq: seq,
-            ts: Time.now.utc.iso8601,
-            role: call.role,
-            verb: verb,
-            key: key,
-            etag_before: nil,
-            etag_after: result.value.is_a?(Hash) ? result.value["etag"] : nil,
-          )
-          result
-        end
-      end
-    end
-  end
-end

data/lib/textus/dispatch/middleware/auth.rb

@@ -1,40 +0,0 @@
-module Textus
-  module Dispatch
-    module Middleware
-      class Auth < Base
-        middleware_name :auth
-
-        def call(container:, command:, call:, next_handler:)
-          verb = VerbRegistry.contract_to_verb!(command.class).to_sym
-          key = key_for(command)
-
-          rule_preds = key ? rule_declared_predicates(verb, container.manifest, key) : []
-
-          Manifest::Policy::Predicates.evaluate(
-            manifest: container.manifest, schemas: container.schemas,
-            action: verb, actor: call.role, key: key,
-            rule_predicates: rule_preds
-          )
-
-          next_handler.call(command, call)
-        end
-
-        private
-
-        def rule_declared_predicates(verb, manifest, key)
-          guard_map = manifest.rules.for(key).guard
-          return [] if guard_map.nil?
-
-          Array(guard_map[verb.to_s])
-        end
-
-        def key_for(command)
-          if command.respond_to?(:key) then command.key
-          elsif command.respond_to?(:old_key) then command.old_key
-          elsif command.respond_to?(:pending_key) then command.pending_key
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/dispatch/middleware/base.rb

@@ -1,26 +0,0 @@
-module Textus
-  module Dispatch
-    module Middleware
-      class Base
-        def self.inherited(subclass)
-          super
-          subclass.instance_variable_set(:@middleware_name, nil)
-        end
-
-        class << self
-          def middleware_name(name = nil)
-            if name
-              @middleware_name = name.to_s
-            else
-              @middleware_name || name.split("::").last.downcase
-            end
-          end
-        end
-
-        def call(container:, command:, call:, next_handler:)
-          raise NotImplementedError
-        end
-      end
-    end
-  end
-end

data/lib/textus/dispatch/middleware/binder.rb

@@ -1,20 +0,0 @@
-module Textus
-  module Dispatch
-    module Middleware
-      class Binder < Base
-        middleware_name :binder
-
-        def call(container:, command:, call:, next_handler:) # rubocop:disable Lint/UnusedMethodArgument
-          return next_handler.call(command, call) unless command.is_a?(Dispatch::Binder::Pending)
-
-          spec = command.spec
-          contract_class = VerbRegistry.contract_class_for(spec.verb) or
-            raise Textus::UsageError.new("unknown command verb: #{spec.verb}")
-          resolved = Dispatch::Binder.bind(spec, command.inputs)
-          built = Dispatch::Pipeline.build_command(contract_class, resolved)
-          next_handler.call(built, call)
-        end
-      end
-    end
-  end
-end

data/lib/textus/dispatch/middleware/cascade.rb

@@ -1,53 +0,0 @@
-module Textus
-  module Dispatch
-    module Middleware
-      class Cascade < Base
-        middleware_name :cascade
-
-        CASCADE_VERBS = %i[put propose accept reject key_mv key_delete].freeze
-
-        TRIGGER_TYPE_MAP = {
-          Contracts::PutEntry => "entry.written",
-          Contracts::ProposeEntry => "entry.written",
-          Contracts::DeleteKey => "entry.deleted",
-          Contracts::MoveKey => "entry.moved",
-          Contracts::AcceptProposal => "proposal.accepted",
-          Contracts::RejectProposal => "proposal.rejected",
-        }.freeze
-
-        def call(container:, command:, call:, next_handler:)
-          result = next_handler.call(command, call)
-          return result unless result.success? && cascadable?(command)
-
-          key = cascade_key(command)
-          return result unless key
-
-          trigger_type = TRIGGER_TYPE_MAP[command.class]
-          jobs = Textus::Store::Jobs::Planner.new(container: container).plan(
-            trigger: { "type" => trigger_type, "target" => key },
-            role: call.role,
-          )
-          queue = Textus::Store::Jobs::Queue.new(store: container.job_store)
-          jobs.each { |j| queue.enqueue(j) }
-          result
-        end
-
-        private
-
-        def cascadable?(command)
-          CASCADE_VERBS.include?(VerbRegistry.contract_to_verb!(command.class).to_sym)
-        end
-
-        def cascade_key(command)
-          case command
-          when Contracts::PutEntry, Contracts::DeleteKey then command.key
-          when Contracts::MoveKey                        then command.new_key
-          when Contracts::AcceptProposal,
-               Contracts::RejectProposal                 then command.pending_key
-          when Contracts::ProposeEntry                   then command.key
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/dispatch/pipeline.rb

@@ -1,35 +0,0 @@
-module Textus
-  module Dispatch
-    class Pipeline
-      attr_reader :container
-
-      def initialize(registry:, container:, middleware: [])
-        @registry = registry
-        @middleware = middleware
-        @container = container
-      end
-
-      def dispatch(command, call:)
-        stack = @middleware.reverse.reduce(->(cmd, c) { execute(cmd, c) }) do |next_mw, mw|
-          ->(cmd, c) { mw.call(container: @container, command: cmd, call: c, next_handler: next_mw) }
-        end
-        stack.call(command, call)
-      end
-
-      def self.build_command(contract_class, inputs)
-        members = contract_class.members
-        kwargs = members.to_h do |member|
-          [member, inputs[member]]
-        end
-        contract_class.new(**kwargs)
-      end
-
-      private
-
-      def execute(command, call)
-        handler = @registry.for(command.class)
-        handler.call(command, call)
-      end
-    end
-  end
-end

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

@@ -1,34 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class AuditLog < Check
-        def call
-          path = Textus::Store::Layout.new(root).audit_log_path
-          Textus::Port::AuditLog.new(root).verify_integrity.map do |v|
-            {
-              "code" => "audit.parse_error",
-              "level" => "warning",
-              "subject" => "#{path}:#{v["lineno"]}",
-              "message" => violation_message(v),
-              "fix" => "inspect #{path} at line #{v["lineno"]} and remove the corrupted row",
-            }
-          end
-        end
-
-        private
-
-        def violation_message(v)
-          case v["reason"]
-          when "invalid_json"
-            "audit log line #{v["lineno"]} is invalid JSON: #{v["detail"]}"
-          when "short_tsv"
-            "audit log line #{v["lineno"]} #{v["detail"]} " \
-            "(consider migrating to NDJSON)"
-          else
-            v["detail"]
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,29 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # ADR 0079: generator/build drift — a derived/external entry whose sources
-      # changed since its generated.at. Dependency-based (not age-based), so it
-      # stays OUT of the lifecycle/freshness unification and lives here as a
-      # health signal. This is the surviving home for what the removed `stale`
-      # verb reported.
-      class GeneratorDrift < Check
-        def call
-          detector = Textus::Store::Freshness::DriftDetector.new(
-            manifest: manifest,
-            file_stat: Textus::Port::Storage::FileStat.new,
-            clock: Textus::Port::Clock.new,
-          )
-          manifest.data.entries.flat_map { |m| detector.drift_rows(m) }.map do |row|
-            {
-              "code" => "generator_drift",
-              "level" => "warning",
-              "subject" => row["key"],
-              "message" => row["reason"],
-              "fix" => "rematerialize the entry: `textus drain`",
-            }
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,60 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class IllegalKeys < Check
-        def call
-          out = []
-          manifest.data.entries.each do |entry|
-            next unless entry.nested?
-            next if entry.publish_mode.keyless? # publish_tree files are opaque payload, never keys (ADR 0047)
-
-            base = File.join(root, Textus::Key::Path.normalize_relative_path(entry.path))
-            next unless File.directory?(base)
-
-            check_all_paths(entry, base, out)
-          end
-          out
-        end
-
-        private
-
-        def check_all_paths(entry, base, out)
-          walk_nested(base) do |abs_path, is_dir|
-            rel = abs_path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-            next if entry.ignored?(rel)
-
-            basename = File.basename(abs_path)
-            stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-            next if stem.match?(Key::Grammar::SEGMENT)
-
-            out << issue(abs_path, stem)
-          end
-        end
-
-        def issue(abs_path, stem)
-          {
-            "code" => "key.illegal",
-            "level" => "error",
-            "subject" => abs_path,
-            "path" => abs_path,
-            "message" => "illegal key segment '#{stem}' at #{abs_path}",
-            "fix" => "rename the file/directory so each segment matches [a-z0-9][a-z0-9-]* " \
-                     "(lowercase, digits, hyphens)",
-          }
-        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
-  end
-end

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

@@ -1,25 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class ManifestFiles < Check
-        def call
-          manifest.data.entries.each_with_object([]) do |entry, out|
-            next if entry.nested?
-
-            path = Textus::Key::Path.resolve(manifest.data, 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
-        end
-      end
-    end
-  end
-end

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

@@ -1,35 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Flags published files whose recorded source no longer exists in the
-      # store. Per-leaf prune (ADR 0046) reconciles within a still-present
-      # leaf; a renamed or removed *whole* leaf orphans its entire target
-      # directory, which a per-entry build won't revisit. This check catches
-      # that drift without making `build` scan globally.
-      class OrphanedPublishTargets < Check
-        def call
-          sdir = Textus::Store::Layout.new(root).sentinels_root
-          return [] unless File.directory?(sdir)
-
-          repo_root = File.dirname(root)
-          store = Textus::Port::SentinelStore.new
-          glob = File.join(sdir, "**", "*#{Textus::Port::SentinelStore::SUFFIX}")
-          Dir.glob(glob).filter_map do |spath|
-            sentinel = store.load(spath, repo_root)
-            next nil if sentinel.nil? || sentinel.source.nil?
-            next nil if File.exist?(sentinel.source)
-
-            {
-              "code" => "publish.orphaned_target",
-              "level" => "warning",
-              "subject" => sentinel.target,
-              "message" => "published file #{sentinel.target} has no source in the store " \
-                           "(recorded source #{sentinel.source} is gone) — likely a renamed or removed leaf",
-              "fix" => "remove the stale copy and its sentinel: rm '#{sentinel.target}' '#{spath}'",
-            }
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Flags pending proposals whose `proposal.target_key` cannot ever be
-      # accepted: it points at a non-canon zone or resolves to no declared
-      # entry (ADR 0035). Reads the live queue zone; silent when there is no
-      # queue zone. Warnings, not errors — they are stale junk, not store
-      # corruption (the accept gate already refuses them).
-      class ProposalTargets < Check
-        def call
-          queue = manifest.policy.queue_lane
-          return [] unless queue
-
-          dispatch(:list, lane: queue).filter_map { |row| issue_for(row["key"]) }
-        end
-
-        private
-
-        def issue_for(key)
-          target = dispatch(:get, key).meta&.dig("proposal", "target_key")
-          return nil if target.nil? # not a proposal entry — skip
-
-          zone = manifest.resolver.resolve(target).entry.lane
-          return nil if manifest.policy.declared_kind(zone.to_s) == :canon
-
-          {
-            "code" => "proposal.target_not_canon",
-            "level" => "warning",
-            "subject" => key,
-            "message" => "proposal '#{key}' targets '#{target}' in zone '#{zone}' (not canon); it can never be accepted",
-            "fix" => "delete the proposal, or repoint target_key at a canon zone",
-          }
-        rescue Textus::UnknownKey
-          {
-            "code" => "proposal.target_unresolved",
-            "level" => "warning",
-            "subject" => key,
-            "message" => "proposal '#{key}' targets '#{target}', which resolves to no declared entry",
-            "fix" => "delete the proposal, or fix target_key",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,47 +0,0 @@
-require "yaml"
-
-module Textus
-  module Doctor
-    class Check
-      # Runs as a standalone module (Check::ProtocolVersion.run(root:)) and also
-      # as a class-based doctor check (ProtocolVersion.new(store).call).
-      class ProtocolVersion < Check
-        # Standalone interface: root is the project root (parent of .textus/).
-        def self.run(root:)
-          path = File.join(root, ".textus", "manifest.yaml")
-          return [] unless File.exist?(path)
-
-          doc = YAML.safe_load_file(path, aliases: false) || {}
-          version = doc["version"]
-          return [] if version == "textus/4"
-
-          [{
-            "code" => "protocol_mismatch",
-            "severity" => "error",
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
-            "hint" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
-          }]
-        end
-
-        # Doctor check interface: root is the .textus/ directory itself,
-        # so manifest.yaml lives directly inside it.
-        def call
-          path = geometry.manifest_path
-          return [] unless File.exist?(path)
-
-          doc = YAML.safe_load_file(path, aliases: false) || {}
-          version = doc["version"]
-          return [] if version == "textus/4"
-
-          [{
-            "code" => "protocol_mismatch",
-            "level" => "error",
-            "subject" => path,
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
-            "fix" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
-          }]
-        end
-      end
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # ADR 0047 Decision 4. A publish_tree entry prunes its WHOLE target dir on
-      # every build. If a derived entry's publish_to writes a file into that same
-      # dir, the tree's prune will delete it unless the tree `ignore`s that
-      # filename. Warn so the author adds the ignore before prune eats the index.
-      class PublishTreeIndexOverlap < Check
-        def call
-          entries = manifest.data.entries
-          trees = entries.select { |e| e.nested? && e.publish_tree }
-          return [] if trees.empty?
-
-          derived_targets = entries.flat_map do |e|
-            Array(e.publish_to).map { |rel| [e, rel] }
-          end
-
-          trees.flat_map do |tree|
-            target_prefix = "#{tree.publish_tree.chomp("/")}/"
-            derived_targets.filter_map do |(derived, rel)|
-              next nil unless rel.start_with?(target_prefix)
-
-              rel_to_target = rel.delete_prefix(target_prefix)
-              next nil if tree.ignored?(rel_to_target)
-
-              issue(tree, derived, rel, rel_to_target)
-            end
-          end
-        end
-
-        private
-
-        def issue(tree, derived, rel, rel_to_target)
-          basename = File.basename(rel_to_target)
-          {
-            "code" => "publish.tree_index_overlap",
-            "level" => "warning",
-            "subject" => tree.key,
-            "message" => "publish_tree '#{tree.publish_tree}' overlaps derived entry " \
-                         "'#{derived.key}' publish_to '#{rel}'; the tree's prune will delete it on rebuild",
-            "fix" => "add a glob covering '#{rel_to_target}' to entry '#{tree.key}' ignore " \
-                     "(e.g. ignore: [\"**/#{basename}\"])",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,50 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class RawAssetPaths < Check
-        def call
-          raw_lane = manifest.policy.lanes_of_kind(:raw).first
-          return [] unless raw_lane
-
-          issues = []
-          manifest.resolver.enumerate.each do |row|
-            next unless row[:key].start_with?("raw.")
-            next unless row[:path] && File.exist?(row[:path])
-
-            raw_content = load_content(row[:path])
-            next unless raw_content.is_a?(Hash)
-
-            asset = raw_content["asset"]
-            next unless asset.is_a?(String) && !asset.empty?
-
-            asset_path = find_asset_path(asset)
-            next if File.exist?(asset_path)
-
-            issues << {
-              "code" => "raw_asset.missing_file",
-              "level" => "error",
-              "subject" => row[:key],
-              "message" => "raw entry '#{row[:key]}' references asset '#{asset}' " \
-                           "which does not exist at #{asset_path}",
-              "fix" => "re-ingest the asset: textus key-delete #{row[:key]}, then textus ingest",
-            }
-          end
-          issues
-        end
-
-        private
-
-        def load_content(path)
-          require "yaml"
-          YAML.safe_load_file(path)
-        rescue StandardError
-          nil
-        end
-
-        def find_asset_path(asset_rel)
-          File.join(geometry.root, "assets", asset_rel)
-        end
-      end
-    end
-  end
-end

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

@@ -1,49 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Flags entries whose key is matched by two or more rule blocks of the
-      # SAME specificity in the same slot (lifecycle / handler_permit /
-      # guard / materialize). Ties are non-deterministic in the parser's pick step, so
-      # they're a configuration smell — surface them.
-      class RuleAmbiguity < Check
-        SLOTS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_ambiguity] }.keys.freeze
-
-        def call
-          out = []
-          rules = manifest.rules
-          manifest.data.entries.each do |mentry|
-            matches = rules.explain(mentry.key)
-            next if matches.length < 2
-
-            SLOTS.each { |slot| out.concat(ambiguities_for(mentry, slot, matches)) }
-          end
-          out
-        end
-
-        private
-
-        def ambiguities_for(mentry, slot, matches)
-          carriers = matches.select { |b| b.public_send(slot) }
-          return [] if carriers.length < 2
-
-          by_specificity = carriers.group_by { |b| Textus::Manifest::Policy::Matcher.specificity(b.match) }
-          tied = by_specificity.values.select { |group| group.length > 1 }
-          tied.map { |group| issue_for(mentry, slot, group) }
-        end
-
-        def issue_for(mentry, slot, group)
-          globs = group.map(&:match).sort
-          {
-            "code" => "rule.ambiguity",
-            "level" => "warning",
-            "subject" => mentry.key,
-            "message" => "entry '#{mentry.key}' matches #{group.length} rule blocks at the same " \
-                         "specificity for #{slot}: #{globs.join(", ")}",
-            "fix" => "narrow one of the conflicting match: globs in .textus/manifest.yaml so a single " \
-                     "block wins for this key",
-          }
-        end
-      end
-    end
-  end
-end