textus 0.15.0 → 0.20.0

data/lib/textus/migrate_keys.rb

@@ -1,187 +0,0 @@
-module Textus
-  # Run-once helper that renames files/directories whose basenames don't
-  # conform to the strict key grammar (§3 of plan-1.2). Only walks
-  # nested: true manifest entries — leaf entries with illegal declared
-  # keys are caught by Manifest load and must be fixed by hand.
-  module MigrateKeys
-    SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
-
-    module_function
-
-    # Returns the envelope hash described in plan-1.2 §3.
-    def run(store, write: false)
-      plan = build_plan(store)
-      collisions = plan[:collisions]
-      renames = plan[:renames]
-
-      ok = collisions.empty?
-      apply!(store, renames) if write && ok
-
-      {
-        "protocol" => Textus::PROTOCOL,
-        "mode" => write ? "write" : "dry-run",
-        "renames" => renames.map { |r| envelope_rename(r) },
-        "collisions" => collisions.map { |c| envelope_collision(c) },
-        "ok" => ok,
-      }
-    end
-
-    # ------------------------------------------------------------------
-    # Plan construction
-    # ------------------------------------------------------------------
-
-    # Returns { renames: [...], collisions: [...] }
-    # Each rename: { from:, to:, old_key:, new_key:, kind: :file|:dir }
-    # Each collision: { target:, sources: [...] }
-    def build_plan(store) # rubocop:disable Metrics/AbcSize
-      renames = []
-      target_buckets = Hash.new { |h, k| h[k] = [] } # target_path => [source_path, ...]
-
-      store.manifest.entries.each do |entry|
-        next unless entry.nested
-
-        base = File.join(store.root, "zones", entry.path)
-        next unless File.directory?(base)
-
-        # Walk depth-first. Order matters when computing the "new key"
-        # for files inside a renamed directory: we record renames bottom-up,
-        # so children are renamed before their parents on apply.
-        walk(base) do |abs_path, is_dir|
-          next if abs_path == base
-
-          basename = File.basename(abs_path)
-          stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-          next if stem.match?(SEGMENT)
-
-          new_stem = normalize(stem)
-          # Skip if normalization yields the same stem (e.g. already-legal
-          # under a different lens). In practice match?(SEGMENT) catches that
-          # above; this is a safety net.
-          next if new_stem == stem
-
-          new_basename = is_dir ? new_stem : new_stem + File.extname(basename)
-          target = File.join(File.dirname(abs_path), new_basename)
-          target_buckets[target] << abs_path
-
-          renames << {
-            from: abs_path,
-            to: target,
-            kind: is_dir ? :dir : :file,
-            entry: entry,
-            base: base,
-          }
-        end
-      end
-
-      collisions = target_buckets.select { |_, srcs| srcs.length > 1 }
-                                 .map { |t, srcs| { target: t, sources: srcs.sort } }
-
-      # Drop colliding entries from renames (we won't apply any of them)
-      colliding_targets = collisions.to_set { |c| c[:target] }
-      renames.reject! { |r| colliding_targets.include?(r[:to]) }
-
-      # Sort renames bottom-up (deepest path first) so children move before parents.
-      renames.sort_by! { |r| -r[:from].count("/") }
-
-      { renames: renames, collisions: collisions }
-    end
-
-    # Yields [absolute_path, is_dir] for every entry under root. Depth-first.
-    def walk(root, &block)
-      Dir.each_child(root) do |name|
-        abs = File.join(root, name)
-        if File.directory?(abs)
-          walk(abs, &block)
-          yield abs, true
-        else
-          yield abs, false
-        end
-      end
-    end
-
-    # Deterministic transform per plan §3.
-    def normalize(s)
-      s = s.downcase
-      s = s.gsub(/[^a-z0-9-]/, "-") # ., _, and anything else become -
-      s = s.gsub(/-+/, "-")
-      s.sub(/\A-+/, "").sub(/-+\z/, "")
-    end
-
-    # ------------------------------------------------------------------
-    # Apply
-    # ------------------------------------------------------------------
-
-    def apply!(store, renames)
-      audit = Store::AuditLog.new(store.root)
-      renames.each do |r|
-        # Bottom-up order means a child's ancestors haven't moved yet, so
-        # `from`/`to` are valid as-recorded. The audit `key` reflects the
-        # eventual full key once every rename in this batch has applied.
-        from = r[:from]
-        to = r[:to]
-        File.rename(from, to)
-        new_key = compute_new_key(r, renames)
-        audit.append(
-          role: "runner",
-          verb: "migrate-keys",
-          key: new_key,
-          etag_before: nil,
-          etag_after: nil,
-          extras: { "from" => from, "to" => to },
-        )
-      end
-    end
-
-    # If an ancestor of `path` was renamed earlier in this batch, rewrite the path.
-    def resolve_current_path(path, renames)
-      out = path
-      renames.each do |r|
-        prefix = r[:from] + "/"
-        out = r[:to] + out[r[:from].length..] if out.start_with?(prefix)
-      end
-      out
-    end
-
-    # New full key after applying all renames up through this one.
-    def compute_new_key(rename, renames)
-      base = rename[:base]
-      entry = rename[:entry]
-      new_to = resolve_current_path(rename[:to], renames)
-
-      rel = new_to.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-      stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "") unless rename[:kind] == :dir
-      stripped ||= rel
-      segs = stripped.split("/").reject(&:empty?)
-      (entry.key.split(".") + segs).join(".")
-    end
-
-    # ------------------------------------------------------------------
-    # Envelope helpers
-    # ------------------------------------------------------------------
-
-    def envelope_rename(r)
-      {
-        "from" => r[:from],
-        "to" => r[:to],
-        "old_key" => path_to_key(r[:from], r[:base], r[:entry], r[:kind]),
-        "new_key" => path_to_key(r[:to], r[:base], r[:entry], r[:kind]),
-      }
-    end
-
-    def envelope_collision(col)
-      { "target" => col[:target], "sources" => col[:sources] }
-    end
-
-    def path_to_key(path, base, entry, kind)
-      rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-      stripped =
-        if kind == :dir
-          rel
-        else
-          rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
-        end
-      segs = stripped.split("/").reject(&:empty?)
-      (entry.key.split(".") + segs).join(".")
-    end
-  end
-end

data/lib/textus/operations/reads.rb

@@ -1,56 +0,0 @@
-module Textus
-  class Operations
-    class Reads
-      # `get`              — pure read; returns envelope + freshness verdict;
-      #                      never triggers refresh; no orchestrator dependency.
-      # `get_or_refresh`   — composes `get` with the refresh orchestrator; runs
-      #                      refresh per policy when the verdict says stale.
-      #                      Use this for interactive reads where the caller
-      #                      wants the freshest envelope obtainable.
-      #
-      # Pick `get` for materialization paths (build, projection, schema tooling).
-      # Pick `get_or_refresh` for interactive `textus get` and equivalent.
-      def initialize(ctx)
-        @ctx = ctx
-      end
-
-      def get
-        Application::Reads::Get.new(ctx: @ctx)
-      end
-
-      def get_or_refresh # rubocop:disable Naming/AccessorMethodName
-        Application::Reads::GetOrRefresh.new(
-          ctx: @ctx,
-          get: get,
-          orchestrator: orchestrator,
-        )
-      end
-
-      def freshness      = Application::Reads::Freshness.new(ctx: @ctx)
-      def audit          = Application::Reads::Audit.new(ctx: @ctx)
-      def blame          = Application::Reads::Blame.new(ctx: @ctx)
-      def policy_explain = Application::Reads::PolicyExplain.new(ctx: @ctx)
-      def list           = Application::Reads::List.new(ctx: @ctx)
-      def where           = Application::Reads::Where.new(ctx: @ctx)
-      def uid             = Application::Reads::Uid.new(ctx: @ctx)
-      def schema_envelope = Application::Reads::SchemaEnvelope.new(ctx: @ctx)
-      def deps            = Application::Reads::Deps.new(ctx: @ctx)
-      def rdeps           = Application::Reads::Rdeps.new(ctx: @ctx)
-      def published       = Application::Reads::Published.new(ctx: @ctx)
-      def stale           = Application::Reads::Stale.new(ctx: @ctx)
-      def validate_all    = Application::Reads::ValidateAll.new(ctx: @ctx)
-
-      private
-
-      def orchestrator
-        Application::Refresh::Orchestrator.new(
-          worker: Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus),
-          bus: @ctx.store.bus,
-          store_root: @ctx.store.root,
-          store: @ctx.store,
-          role: @ctx.role,
-        )
-      end
-    end
-  end
-end

data/lib/textus/operations/refresh.rb

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

data/lib/textus/operations/writes.rb

@@ -1,21 +0,0 @@
-module Textus
-  class Operations
-    class Writes
-      def initialize(ctx)
-        @ctx = ctx
-      end
-
-      def put     = Application::Writes::Put.new(ctx: @ctx, bus: bus)
-      def delete  = Application::Writes::Delete.new(ctx: @ctx, bus: bus)
-      def mv      = Application::Writes::Mv.new(ctx: @ctx, bus: bus)
-      def accept  = Application::Writes::Accept.new(ctx: @ctx, bus: bus)
-      def build   = Application::Writes::Build.new(ctx: @ctx, bus: bus)
-      def publish = Application::Writes::Publish.new(ctx: @ctx, bus: bus)
-      def reject  = Application::Writes::Reject.new(ctx: @ctx, bus: bus)
-
-      private
-
-      def bus = @ctx.store.bus
-    end
-  end
-end

data/lib/textus/projection.rb

@@ -1,89 +0,0 @@
-require "time"
-require "timeout"
-
-module Textus
-  class Projection
-    MAX_LIMIT = 1000
-    REDUCER_TIMEOUT_SECONDS = 2
-
-    # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
-    #   semantics: pure read (`ops.reads.get`) for materialization paths;
-    #   `ops.reads.get_or_refresh` if you want refresh-on-stale.
-    # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
-    # `transform_resolver` — a callable `->(name) { callable_or_raise }`.
-    # `transform_context` — `Application::Context` handed to the transform reducer.
-    def initialize(reader:, spec:, lister:, transform_resolver:, transform_context:)
-      @reader             = reader
-      @spec               = spec || {}
-      @lister             = lister
-      @transform_resolver = transform_resolver
-      @transform_context  = transform_context
-      @limit = (@spec["limit"] || MAX_LIMIT).to_i
-      raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
-    end
-
-    def run
-      keys = collect_keys
-      explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
-      rows = keys.map do |key|
-        env = @reader.call(key)
-        row = pluck(env.meta, env.body)
-        explicit_pluck ? row : row.merge("_key" => key)
-      end
-      reduced = apply_reducer(rows)
-      # Reducers may return either an Array of rows (legacy / templated builds)
-      # or a Hash that becomes the structured-format payload base. In the Hash
-      # case, downstream sort/limit/position markers don't apply, and the
-      # builder owns `_meta.generated_at` so we don't stamp it here.
-      return reduced if reduced.is_a?(Hash)
-
-      rows = reduced
-      rows = sort(rows)
-      rows = rows.first(@limit)
-      mark_positions(rows)
-      { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
-    end
-
-    private
-
-    def apply_reducer(rows)
-      name = @spec["transform"] or return rows
-      callable = @transform_resolver.call(name)
-      Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-        callable.call(store: @transform_context, rows: rows, config: @spec["transform_config"] || {})
-      end
-    rescue Timeout::Error
-      raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
-    end
-
-    def collect_keys
-      prefixes = Array(@spec["select"])
-      prefixes.flat_map { |p| @lister.call(prefix: p).map { |row| row["key"] } }.uniq
-    end
-
-    def pluck(frontmatter, _body)
-      fields = @spec["pluck"]
-      if fields.nil? || fields == "*"
-        frontmatter
-      else
-        Array(fields).each_with_object({}) { |f, h| h[f] = frontmatter[f] if frontmatter.key?(f) }
-      end
-    end
-
-    # Adds `_first`, `_last`, and `_index` markers so templates can emit
-    # delimiters (e.g. JSON commas) via {{^_last}},{{/_last}}.
-    def mark_positions(rows)
-      last_idx = rows.length - 1
-      rows.each_with_index do |row, i|
-        row["_index"] = i
-        row["_first"] = i.zero?
-        row["_last"]  = (i == last_idx)
-      end
-    end
-
-    def sort(rows)
-      sb = @spec["sort_by"] or return rows
-      rows.sort_by { |r| r[sb].to_s }
-    end
-  end
-end

data/lib/textus/refresh.rb

@@ -1,39 +0,0 @@
-module Textus
-  module Refresh
-    def self.call(store, key, as:)
-      Textus::Operations.for(store, role: as).refresh.worker.run(key)
-    end
-
-    def self.refresh_stale(store, prefix: nil, zone: nil, as: "runner")
-      ops = Textus::Operations.for(store, role: as)
-      Textus::Application::Refresh::All.call(ops.ctx, prefix: prefix, zone: zone)
-    end
-
-    # Normalize the three accepted intake return shapes into the store's
-    # internal {frontmatter, body, content} representation.
-    def self.normalize_action_result(res, format:)
-      res = res.transform_keys(&:to_s) if res.is_a?(Hash)
-      res ||= {}
-      meta_val = res["_meta"]
-      body    = res["body"]
-      content = res["content"]
-
-      case format
-      when "markdown"
-        { meta: meta_val || {}, body: body.to_s, content: nil }
-      when "text"
-        { meta: {}, body: body.to_s, content: nil }
-      when "json", "yaml"
-        if !content.nil?
-          { meta: meta_val || {}, body: nil, content: content }
-        elsif !body.nil?
-          { meta: {}, body: body.to_s, content: nil }
-        else
-          raise UsageError.new("intake for #{format} returned neither content nor body")
-        end
-      else
-        raise UsageError.new("unknown format #{format.inspect}")
-      end
-    end
-  end
-end

data/lib/textus/store/reader.rb

@@ -1,69 +0,0 @@
-module Textus
-  class Store
-    class Reader
-      def initialize(store)
-        @store = store
-        @manifest = store.manifest
-      end
-
-      def get(key)
-        read_raw_envelope(key) || raise(UnknownKey.new(key, suggestions: @manifest.suggestions_for(key)))
-      end
-
-      # Reads the current on-disk state of key as a bare envelope, skipping
-      # freshness annotation to avoid recursion. Used by Freshness.refresh_sync
-      # after a sync refresh completes.
-      def read_raw_envelope(key)
-        mentry, path, = @manifest.resolve(key)
-        return nil unless File.exist?(path)
-
-        raw = File.binread(path)
-        parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-        Envelope.build(
-          key: key, mentry: mentry, path: path,
-          meta: parsed["_meta"], body: parsed["body"],
-          etag: Etag.for_bytes(raw), content: parsed["content"]
-        )
-      end
-
-      def list(prefix: nil, zone: nil)
-        rows = @manifest.enumerate(prefix: prefix)
-        rows = rows.select { |r| r[:manifest_entry].zone == zone } if zone
-        rows.map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
-      end
-
-      def where(key)
-        mentry, path, = @manifest.resolve(key)
-        { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
-      end
-
-      def schema_envelope(key)
-        mentry, = @manifest.resolve(key)
-        schema = @store.schema_for(mentry.schema)
-        { "protocol" => PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
-      end
-
-      # Returns the Textus UID for a key (or nil if the entry has none yet).
-      # Raises UnknownKey if the key doesn't resolve to a real file.
-      def uid(key)
-        get(key).uid
-      end
-
-      def deps(key)   = Dependencies.deps_of(@manifest, key)
-      def rdeps(key)  = Dependencies.rdeps_of(@manifest, key)
-      def published   = Dependencies.published_of(@manifest)
-
-      def stale(prefix: nil, zone: nil)
-        Staleness.new(manifest: @manifest).call(prefix: prefix, zone: zone)
-      end
-
-      def validate_all
-        Validator.new(
-          reader: self, manifest: @manifest,
-          audit_log: @store.audit_log,
-          schema_for: ->(name) { @store.schema_for(name) }
-        ).call
-      end
-    end
-  end
-end

data/lib/textus/store/validator.rb

@@ -1,82 +0,0 @@
-module Textus
-  class Store
-    class Validator
-      def initialize(reader:, manifest:, audit_log:, schema_for:)
-        @reader = reader
-        @manifest = manifest
-        @audit_log = audit_log
-        @schema_for = schema_for
-      end
-
-      def call
-        violations = []
-        check_content_violations(violations)
-        check_role_authority_violations(violations)
-        { "protocol" => PROTOCOL, "ok" => violations.empty?, "violations" => violations }
-      end
-
-      private
-
-      def check_content_violations(violations)
-        @manifest.enumerate.each do |row|
-          key = row[:key]
-          mentry = row[:manifest_entry]
-          env = fetch_envelope(key, violations) or next
-          schema = mentry.schema && @schema_for.call(mentry.schema)
-          next unless schema
-
-          begin
-            validate_schema!(schema, env, mentry.format)
-          rescue Textus::Error => e
-            violations << { "key" => key, "code" => e.code, "message" => e.message }
-          end
-        end
-      end
-
-      def check_role_authority_violations(violations)
-        @manifest.enumerate.each do |row|
-          mentry = row[:manifest_entry]
-          next unless mentry.schema
-
-          schema = @schema_for.call(mentry.schema)
-          next unless schema
-
-          env = begin
-            @reader.get(row[:key])
-          rescue StandardError
-            next
-          end
-          append_authority_violations(violations, row[:key], env, schema)
-        end
-      end
-
-      def append_authority_violations(violations, key, env, schema)
-        last_writer = @audit_log.last_writer_for(key)
-        return if last_writer.nil?
-
-        env.meta.each_key do |field|
-          owner = schema.maintained_by(field)
-          next if owner.nil? || last_writer == owner || last_writer == "human"
-
-          violations << { "key" => key, "code" => "role_authority",
-                          "field" => field, "expected" => owner, "last_writer" => last_writer }
-        end
-      end
-
-      def fetch_envelope(key, violations)
-        @reader.get(key)
-      rescue Textus::Error => e
-        violations << { "key" => key, "code" => e.code, "message" => e.message }
-        nil
-      end
-
-      def validate_schema!(schema, envelope, format)
-        payload = case format
-                  when "json", "yaml" then envelope.content || {}
-                  else envelope.meta || {}
-                  end
-        schema.validate!(payload)
-      end
-    end
-  end
-end

data/lib/textus/store/writer.rb

@@ -1,102 +0,0 @@
-require "fileutils"
-
-module Textus
-  class Store
-    class Writer
-      Payload = Data.define(:meta, :body, :content)
-
-      def initialize(store)
-        @store = store
-        @manifest = store.manifest
-        @reader = store.reader
-      end
-
-      # Pure I/O: validate, serialize, etag-check, write to disk, audit. No
-      # permission check and no event firing — those are handled by the caller
-      # (Application::Writes::Put).
-      def write_envelope_to_disk(key, mentry:, payload:, ctx:, if_etag: nil)
-        _, path, = @manifest.resolve(key)
-
-        meta = payload.meta || {}
-        strategy = Entry.for_format(mentry.format)
-
-        existing_uid = existing_uid_for(mentry, path)
-        meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
-
-        bytes, eff_meta, eff_body, eff_content = serialize_for_put(
-          mentry: mentry, path: path, strategy: strategy,
-          meta: meta, body: payload.body, content: content
-        )
-
-        enforce_name_match!(path, eff_meta, mentry.format)
-
-        schema = @store.schema_for(mentry.schema)
-        if schema
-          Entry.for_format(mentry.format).validate_against(
-            schema,
-            { "_meta" => eff_meta, "content" => eff_content },
-          )
-        end
-
-        etag_before = File.exist?(path) ? Etag.for_file(path) : nil
-        raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && (etag_before != if_etag)
-
-        FileUtils.mkdir_p(File.dirname(path))
-        File.binwrite(path, bytes)
-        etag_after = Etag.for_bytes(bytes)
-        @store.audit_log.append(
-          role: ctx.role, verb: "put", key: key,
-          etag_before: etag_before, etag_after: etag_after,
-          extras: ctx.correlation_id ? { "correlation_id" => ctx.correlation_id } : nil
-        )
-        Envelope.build(
-          key: key, mentry: mentry, path: path,
-          meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
-        )
-      end
-
-      def existing_uid_for(mentry, path)
-        return nil unless File.exist?(path)
-
-        raw = File.binread(path)
-        parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-        Envelope.extract_uid(parsed["_meta"])
-      rescue StandardError
-        nil
-      end
-
-      def ensure_uid(format, meta, content, existing_uid)
-        Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
-      end
-
-      def enforce_name_match!(path, meta, format)
-        Textus::Entry.for_format(format).enforce_name_match!(path, meta)
-      end
-
-      def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
-        _ = strategy
-        Textus::Entry.for_format(mentry.format).serialize_for_put(
-          meta: meta, body: body, content: content, path: path,
-        )
-      end
-
-      # Pure I/O: resolve path, validate etag, delete from disk, audit. No
-      # permission check and no event firing — those are handled by the caller
-      # (Application::Writes::Delete).
-      def delete_envelope_from_disk(key, ctx:, if_etag: nil)
-        _, path, = @manifest.resolve(key)
-        raise UnknownKey.new(key, suggestions: @manifest.suggestions_for(key)) unless File.exist?(path)
-
-        etag_before = Etag.for_file(path)
-        raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
-
-        File.delete(path)
-        @store.audit_log.append(
-          role: ctx.role, verb: "delete", key: key,
-          etag_before: etag_before, etag_after: nil,
-          extras: ctx.correlation_id ? { "correlation_id" => ctx.correlation_id } : nil
-        )
-      end
-    end
-  end
-end