textus 0.15.0 → 0.20.0

data/lib/textus/manifest/entry.rb

@@ -5,78 +5,6 @@ module Textus
       # 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 = 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
-      # publish_each template.
-      def publish_target_for(full_key)
-        return nil if @publish_each.nil?
-
-        entry_segs = @key.split(".")
-        key_segs = full_key.split(".")
-        raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
-
-        remaining = key_segs[entry_segs.length..] || []
-        leaf = remaining.join("/")
-        basename = remaining.last || ""
-        ext = Textus::Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
-
-        vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
-        @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
-      end
-
-      # Signal-based zone-kind predicates: derive the "kind" of a zone from its
-      # 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?("builder")
-      end
-
-      def in_proposal_zone?
-        zone_writers.include?("agent")
-      end
-
-      private
-
-      def zone_writers
-        @manifest.zone_writers(@zone)
-      rescue UsageError => e
-        raise UsageError.new("entry '#{@key}': #{e.message}")
-      end
     end
   end
 end

data/lib/textus/manifest/resolution.rb

@@ -0,0 +1,5 @@
+module Textus
+  class Manifest
+    Resolution = Data.define(:entry, :path, :remaining)
+  end
+end

data/lib/textus/manifest/resolver.rb

@@ -0,0 +1,109 @@
+module Textus
+  class Manifest
+    class Resolver
+      def initialize(manifest)
+        @manifest = manifest
+      end
+
+      def resolve(key)
+        @manifest.validate_key!(key)
+        segments = key.split(".")
+        candidates = @manifest.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(@manifest.entries.reject { |e| nested_entry?(e) }.map(&:key))
+        candidates.uniq!
+        Key::Distance.suggest(key, candidates, limit: 5)
+      rescue StandardError
+        []
+      end
+
+      def enumerate(prefix: nil)
+        out = @manifest.entries.flat_map { |entry| nested_entry?(entry) ? enumerate_nested(entry) : enumerate_leaf(entry) }
+        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.is_a?(Textus::Manifest::Entry::Nested) || entry.raw["nested"] == true
+      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)
+
+          index_fn = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+          path = if index_fn
+                   File.join(@manifest.root, "zones", entry.path, *remaining, index_fn)
+                 else
+                   primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+                   File.join(@manifest.root, "zones", entry.path, *remaining) + primary_ext
+                 end
+          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)
+        base = File.join(@manifest.root, "zones", entry.path)
+        return [] unless File.directory?(base)
+
+        entry_index_filename = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+        glob_pattern = entry_index_filename ? "**/#{entry_index_filename}" : nested_glob(entry.format)
+        Dir.glob(File.join(base, glob_pattern)).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)}/?}, "")
+        entry_if = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+        stripped = entry_if ? File.dirname(rel) : 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} — run 'textus key normalize --dry-run'")
+          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(@manifest, entry)
+      end
+
+      def nested_glob(format)
+        Textus::Entry.for_format(format).nested_glob
+      end
+    end
+  end
+end

data/lib/textus/manifest/schema.rb

@@ -4,7 +4,7 @@ module Textus
       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
+        key path zone kind schema owner nested format
         compute template publish_to publish_each
         intake events inject_intro index_filename
       ].freeze

data/lib/textus/manifest.rb

@@ -1,17 +1,10 @@
 require "yaml"
 require_relative "manifest/schema"
+require_relative "manifest/resolution"
+require_relative "manifest/resolver"
 
 module Textus
   class Manifest
-    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
-
-    def self.version_hint_for(version)
-      version == "textus/2" ? TEXTUS_2_HINT : nil
-    end
-
-    private_class_method :version_hint_for
-
     attr_reader :root, :entries, :raw
 
     def zones
@@ -58,7 +51,6 @@ module Textus
       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!
@@ -86,53 +78,8 @@ module Textus
       rules.for(key)
     end
 
-    # Returns [Manifest::Entry, resolved_path, remaining_segments]
-    def resolve(key)
-      validate_key!(key)
-      segments = key.split(".")
-      # longest-prefix match
-      candidates = @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..]
-      if remaining.empty?
-        path = resolve_leaf_path(entry)
-        [entry, path, []]
-      else
-        raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless entry.nested
-
-        path = if entry.index_filename
-                 File.join(@root, "zones", entry.path, *remaining, entry.index_filename)
-               else
-                 primary_ext = Textus::Entry.for_format(entry.format).extensions.first
-                 File.join(@root, "zones", entry.path, *remaining) + primary_ext
-               end
-        [entry, path, remaining]
-      end
-    end
-
-    # Returns up to 5 dotted keys from the manifest that look similar to the
-    # requested key, ranked by shared-prefix length then Levenshtein distance.
-    def suggestions_for(key)
-      candidates = enumerate.map { |r| r[:key] }
-      # Include declared (non-nested) entry keys even if file is missing.
-      candidates.concat(@entries.reject(&:nested).map(&:key))
-      candidates.uniq!
-      Key::Distance.suggest(key, candidates, limit: 5)
-    rescue StandardError
-      []
-    end
-
-    # Enumerate all entry files reachable through the manifest. Returns
-    # [{ key:, path:, manifest_entry: }, ...]
-    def enumerate(prefix: nil)
-      out = @entries.flat_map { |entry| entry.nested ? enumerate_nested(entry) : enumerate_leaf(entry) }
-      out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
-      out.sort_by { |row| row[:key] }
+    def resolver
+      @resolver ||= Resolver.new(self)
     end
 
     def validate_key!(key)
@@ -143,51 +90,8 @@ module Textus
 
     private
 
-    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)
-      base = File.join(@root, "zones", entry.path)
-      return [] unless File.directory?(base)
-
-      glob_pattern = entry.index_filename ? "**/#{entry.index_filename}" : nested_glob(entry.format)
-      Dir.glob(File.join(base, glob_pattern)).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)}/?}, "")
-      stripped = entry.index_filename ? File.dirname(rel) : 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} — run 'textus key normalize --dry-run'")
-        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 validate_declared_keys!
       @entries.each { |e| validate_key!(e.key) }
     end
-
-    def resolve_leaf_path(entry)
-      Textus::Key::Path.resolve(self, entry)
-    end
-
-    def nested_glob(format)
-      Textus::Entry.for_format(format).nested_glob
-    end
   end
 end

data/lib/textus/operations.rb

@@ -1,45 +1,169 @@
 module Textus
   # Single canonical entrypoint for invoking application use-cases against a
-  # store. Mirrors the directory structure under `lib/textus/application/`:
+  # store. Public surface is flat — one method per use case:
   #
   #   ops = Textus::Operations.for(store, role: "agent")
-  #   ops.writes.put.call(key, body: "...")
-  #   ops.reads.get.call(key)               # pure read
-  #   ops.reads.get_or_refresh.call(key)    # read + refresh-on-stale
-  #   ops.refresh.worker.call(key)
-  #
-  # Replaces the prior `Textus::Composition` module (deleted in v0.12.2).
+  #   ops.put(key, body: "...")
+  #   ops.get(key)               # pure read
+  #   ops.get_or_refresh(key)    # read + refresh-on-stale
+  #   ops.refresh(key)           # synchronous worker refresh
+  #   ops.refresh_all(prefix: ..., zone: ...)
   class Operations
     def self.for(store, role: Role::DEFAULT, correlation_id: nil, dry_run: false)
-      ctx = Application::Context.new(
+      new(
+        ctx: Application::Context.build(role: role, correlation_id: correlation_id, dry_run: dry_run),
+        manifest: store.manifest,
+        file_store: store.file_store,
+        schemas: store.schemas,
+        audit_log: store.audit_log,
+        bus: store.bus,
+        root: store.root,
         store: store,
-        role: role,
-        correlation_id: correlation_id,
-        dry_run: dry_run,
       )
-      new(ctx)
     end
 
-    attr_reader :ctx
+    attr_reader :ctx, :store
 
-    def initialize(ctx)
-      @ctx = ctx
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(ctx:, manifest:, file_store:, schemas:, audit_log:, bus:, root:, store:)
+      @ctx        = ctx
+      @manifest   = manifest
+      @file_store = file_store
+      @schemas    = schemas
+      @audit_log  = audit_log
+      @bus        = bus
+      @root       = root
+      @store      = store
+      @authorizer = Textus::Domain::Authorizer.new(manifest: @manifest)
     end
+    # rubocop:enable Metrics/ParameterLists
 
-    def writes
-      @writes ||= Writes.new(@ctx)
+    def with_role(role)
+      self.class.new(
+        ctx: @ctx.with_role(role),
+        manifest: @manifest, file_store: @file_store, schemas: @schemas,
+        audit_log: @audit_log, bus: @bus,
+        root: @root, store: @store
+      )
     end
 
-    def reads
-      @reads ||= Reads.new(@ctx)
+    def hook_context
+      @hook_context ||= Textus::Hooks::Context.new(ops: self)
     end
 
-    def refresh
-      @refresh ||= Refresh.new(@ctx)
+    # writes
+    def put(...)
+      Application::Writes::Put.new(
+        ctx: @ctx, manifest: @manifest, envelope_io: envelope_io,
+        bus: @bus, authorizer: @authorizer, hook_context: hook_context
+      ).call(...)
     end
 
-    def with_role(role)
-      self.class.new(@ctx.with_role(role))
+    def delete(...)
+      Application::Writes::Delete.new(
+        ctx: @ctx, manifest: @manifest, envelope_io: envelope_io,
+        bus: @bus, authorizer: @authorizer, hook_context: hook_context
+      ).call(...)
+    end
+
+    def mv(...)
+      Application::Writes::Mv.new(
+        ctx: @ctx, manifest: @manifest, envelope_io: envelope_io,
+        bus: @bus, authorizer: @authorizer, hook_context: hook_context
+      ).call(...)
+    end
+
+    def accept(...)
+      Application::Writes::Accept.new(
+        ctx: @ctx, manifest: @manifest, file_store: @file_store, schemas: @schemas,
+        envelope_io: envelope_io, bus: @bus, authorizer: @authorizer, hook_context: hook_context
+      ).call(...)
+    end
+
+    def reject(...)
+      Application::Writes::Reject.new(
+        ctx: @ctx, manifest: @manifest, file_store: @file_store,
+        envelope_io: envelope_io, bus: @bus, authorizer: @authorizer, hook_context: hook_context
+      ).call(...)
+    end
+
+    def publish(...)
+      Application::Writes::Publish.new(
+        ctx: @ctx, manifest: @manifest, file_store: @file_store,
+        bus: @bus, root: @root, store: @store, hook_context: hook_context
+      ).call(...)
+    end
+
+    # reads
+    def get(...)
+      Application::Reads::Get.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call(...)
+    end
+
+    def get_or_refresh(...)
+      Application::Reads::GetOrRefresh.new(
+        manifest: @manifest,
+        get: Application::Reads::Get.new(ctx: @ctx, manifest: @manifest, file_store: @file_store),
+        orchestrator: orchestrator,
+      ).call(...)
+    end
+
+    def list(...)            = Application::Reads::List.new(manifest: @manifest).call(...)
+    def where(...)           = Application::Reads::Where.new(manifest: @manifest).call(...)
+    def uid(...)             = Application::Reads::Uid.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call(...)
+    def schema_envelope(...) = Application::Reads::SchemaEnvelope.new(manifest: @manifest, schemas: @schemas).call(...)
+    def deps(...)            = Application::Reads::Deps.new(manifest: @manifest).call(...)
+    def rdeps(...)           = Application::Reads::Rdeps.new(manifest: @manifest).call(...)
+    def published(...)       = Application::Reads::Published.new(manifest: @manifest).call(...)
+    def stale(...)           = Application::Reads::Stale.new(manifest: @manifest).call(...)
+    def audit(...)           = Application::Reads::Audit.new(manifest: @manifest, root: @root).call(...)
+    def blame(...)           = Application::Reads::Blame.new(manifest: @manifest, root: @root).call(...)
+    def policy_explain(...)  = Application::Reads::PolicyExplain.new(manifest: @manifest).call(...)
+    def freshness(...)       = Application::Reads::Freshness.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call(...)
+
+    def validate_all(...)
+      Application::Reads::ValidateAll.new(
+        ctx: @ctx, manifest: @manifest, file_store: @file_store, schemas: @schemas, audit_log: @audit_log,
+      ).call(...)
+    end
+
+    # refresh
+    def refresh(key) = refresh_worker.run(key)
+
+    def refresh_all(**)
+      Application::Refresh::All.new(
+        ctx: @ctx, manifest: @manifest, envelope_io: envelope_io, bus: @bus,
+        store: @store, authorizer: @authorizer, hook_context: hook_context
+      ).call(**)
+    end
+
+    private
+
+    def envelope_io
+      @envelope_io ||= Application::Writes::EnvelopeIO.new(
+        file_store: @file_store,
+        manifest: @manifest,
+        schemas: @schemas,
+        audit_log: @audit_log,
+        ctx: @ctx,
+      )
+    end
+
+    def refresh_worker
+      @refresh_worker ||= Application::Refresh::Worker.new(
+        ctx: @ctx, manifest: @manifest, envelope_io: envelope_io, bus: @bus,
+        store: @store, authorizer: @authorizer, hook_context: hook_context
+      )
+    end
+
+    def orchestrator
+      @orchestrator ||= Application::Refresh::Orchestrator.new(
+        worker: refresh_worker,
+        store_root: @root,
+        bus: @bus,
+        store: @store,
+        ctx: @ctx,
+        hook_context: hook_context,
+      )
     end
   end
 end

data/lib/textus/schema/tools.rb

@@ -6,7 +6,7 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = Textus::Operations.for(store).reads.get.call(from)
+        env = Textus::Operations.for(store).get(from)
         meta = env.meta
         schema = {
           "name" => name,
@@ -24,8 +24,8 @@ module Textus
       def self.diff(store, name:)
         schema = load_schema(store, name)
         drift = []
-        store.manifest.enumerate.each do |row|
-          env = Textus::Operations.for(store).reads.get.call(row[:key])
+        store.manifest.resolver.enumerate.each do |row|
+          env = Textus::Operations.for(store).get(row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -51,8 +51,8 @@ module Textus
 
         ops = Textus::Operations.for(store, role: "human")
         touched = []
-        store.manifest.enumerate.each do |row|
-          env = ops.reads.get.call(row[:key])
+        store.manifest.resolver.enumerate.each do |row|
+          env = ops.get(row[:key])
           meta = env.meta.dup
           changed = false
           renames.each do |old, new|
@@ -63,7 +63,7 @@ module Textus
           end
           next unless changed
 
-          ops.writes.put.call(row[:key], meta: meta, body: env.body)
+          ops.put(row[:key], meta: meta, body: env.body)
           touched << row[:key]
         end
         { "protocol" => PROTOCOL, "migrated" => touched, "renames" => renames }
@@ -81,7 +81,7 @@ module Textus
       end
 
       def self.load_schema(store, name)
-        store.schema_for(name)
+        store.schemas.fetch(name)
       rescue IoError
         raise UsageError.new("schema not found: #{name}")
       end

data/lib/textus/schemas.rb

@@ -0,0 +1,46 @@
+module Textus
+  # Eager-loading schema cache. Loads every *.yaml under +dir+ at construction.
+  # A missing directory is treated as "no schemas" (does not raise) to mirror
+  # the lazy behavior previously embedded in Store#schema_for.
+  class Schemas
+    def initialize(dir)
+      @dir = dir
+      @schemas = {}
+      load_all
+    end
+
+    def fetch(name)
+      @schemas[name] || raise(IoError.new("schema not found: #{File.join(@dir, "#{name}.yaml")}"))
+    end
+
+    # Only nil short-circuits. A missing-but-named schema still raises IoError.
+    def fetch_or_nil(name)
+      return nil if name.nil?
+
+      fetch(name)
+    end
+
+    def all
+      @schemas.values
+    end
+
+    private
+
+    def load_all
+      return unless File.directory?(@dir)
+
+      Dir.glob(File.join(@dir, "*.yaml")).each do |path|
+        name = File.basename(path, ".yaml")
+        begin
+          @schemas[name] = Schema.load(path)
+        rescue StandardError
+          # Tolerate broken schema files at construction time so the rest of
+          # the store remains loadable. Surfacing the failure is the job of
+          # Doctor::Check::SchemaParseError. Lookups via #fetch still raise
+          # IoError for the missing-but-named schema.
+          next
+        end
+      end
+    end
+  end
+end