textus 0.55.1 → 0.56.0

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
-          gen = Textus::Core::Freshness::Evaluator.new(
-            manifest: manifest,
-            file_stat: Textus::Port::Storage::FileStat.new,
-            clock: Textus::Port::Clock.new,
-          )
-          manifest.data.entries.flat_map { |m| gen.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/notebook_sources.rb

@@ -1,50 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class NotebookSources < Check
-        def call
-          issues = []
-          manifest.resolver.enumerate.each do |row|
-            next unless row[:key].start_with?("notebook.notes.")
-            next unless row[:path] && File.exist?(row[:path])
-
-            sources = parse_sources(row[:path])
-            sources.each do |raw_key|
-              next if raw_entry_exists?(raw_key)
-
-              issues << {
-                "code" => "notebook.source_missing",
-                "level" => "warning",
-                "subject" => row[:key],
-                "message" => "notebook entry '#{row[:key]}' references raw key '#{raw_key}' " \
-                             "which does not exist in the store",
-                "fix" => "re-ingest the source: textus ingest ..., or remove the stale sources: entry",
-              }
-            end
-          end
-          issues
-        end
-
-        private
-
-        def parse_sources(path)
-          content = File.read(path)
-          match = content.match(/\A---\n(.*?)\n---/m)
-          return [] unless match
-
-          front = YAML.safe_load(match[1])
-          Array(front&.dig("sources"))
-        rescue StandardError
-          []
-        end
-
-        def raw_entry_exists?(key)
-          path = manifest.resolver.resolve(key).path
-          File.exist?(path)
-        rescue Textus::UnknownKey, Textus::Error
-          false
-        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::Geometry.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

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

@@ -1,28 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Surfaces YAML parse failures for files in <store>/schemas/. Without
-      # this check, malformed schemas are silently skipped by other doctor
-      # checks (UnownedSchemaFields rescues, Schemas only checks filenames),
-      # leaving the operator with no signal that a schema is broken.
-      class SchemaParseError < Check
-        def call
-          dir = geometry.schemas_dir
-          return [] unless File.directory?(dir)
-
-          Dir.glob(File.join(dir, "*.yaml")).each_with_object([]) do |path, out|
-            Schema.load(path)
-          rescue StandardError => e
-            out << {
-              "code" => "schema.parse_error",
-              "level" => "error",
-              "subject" => path,
-              "message" => "schema failed to parse: #{e.class}: #{e.message}",
-              "fix" => "fix the YAML at #{path} (check indentation, quoted scalars, and aliases)",
-            }
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,28 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class SchemaViolations < Check
-        def call
-          result = Textus::Doctor::Validator.new(
-            reader: ->(key, ctnr, c) { Value::Result.unwrap(Textus::Action::Get.call(container: ctnr, call: c, key: key)) },
-            manifest: @container.manifest,
-            audit_log: @container.audit_log,
-            schema_for: ->(name) { @container.schemas.fetch_or_nil(name) },
-          ).call(container: @container, call: Textus::Value::Call.build(role: Textus::Value::Role::DEFAULT))
-
-          result["violations"].map do |v|
-            fix = v["expected"] &&
-                  "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"
-            {
-              "code" => v["code"],
-              "level" => "error",
-              "subject" => v["key"],
-              "message" => v["message"] || "#{v["code"]} on #{v["key"]}",
-              "fix" => fix,
-            }.compact
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,26 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Schemas < Check
-        def call
-          out = []
-          manifest.data.entries.each do |entry|
-            next if entry.schema.nil?
-
-            sp = geometry.schema_path(entry.schema)
-            next if File.exist?(sp)
-
-            out << {
-              "code" => "schema.missing",
-              "level" => "error",
-              "subject" => entry.key,
-              "message" => "schema '#{entry.schema}' not found at #{sp}",
-              "fix" => "create the schema file or run 'textus schema init #{entry.schema} --from=<key>'",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

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

@@ -1,60 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Sentinels < Check
-        def call
-          store      = Textus::Port::SentinelStore.new
-          file_stat  = Textus::Port::Storage::FileStat.new
-          dir        = Textus::Store::Geometry.new(root).sentinels_root
-          return [] unless file_stat.directory?(dir)
-
-          repo_root = File.dirname(root)
-          file_stat.glob(File.join(dir, "**", "*#{Textus::Port::SentinelStore::SUFFIX}")).flat_map do |sentinel_path|
-            inspect_sentinel(sentinel_path, repo_root, store, file_stat)
-          end
-        end
-
-        private
-
-        def inspect_sentinel(sentinel_path, repo_root, store, file_stat)
-          sentinel = store.load(sentinel_path, repo_root)
-          return [parse_error_issue(sentinel_path)] if sentinel.nil?
-          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?(file_stat)
-          return [drift_issue(sentinel)] if sentinel.drift?(file_stat)
-
-          []
-        end
-
-        def parse_error_issue(sentinel_path)
-          {
-            "code" => "sentinel.parse_error",
-            "level" => "warning",
-            "subject" => sentinel_path,
-            "message" => "sentinel is not valid JSON",
-            "fix" => "delete #{sentinel_path} and re-run 'textus drain' to regenerate",
-          }
-        end
-
-        def orphan_issue(sentinel_path, sentinel)
-          {
-            "code" => "sentinel.orphan",
-            "level" => "warning",
-            "subject" => sentinel_path,
-            "message" => "sentinel target #{sentinel.target.inspect} no longer exists",
-            "fix" => "delete #{sentinel_path} (the published file is gone) or restore the target",
-          }
-        end
-
-        def drift_issue(sentinel)
-          {
-            "code" => "sentinel.drift",
-            "level" => "warning",
-            "subject" => sentinel.target,
-            "message" => "published file at #{sentinel.target} was modified out-of-band",
-            "fix" => "re-run 'textus drain' to overwrite, or copy the manual edit back into the store source",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,54 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Warns when a knowledge-lane doc's `**reviewed** YYYY-MM (vX.Y)` stamp
-      # is more than MINOR_THRESHOLD minor versions behind Textus::VERSION.
-      # The stamp is the human staleness signal declared in docs conventions
-      # (knowledge.docs-index); this check makes it machine-enforced.
-      class StaleReviewedStamp < Check
-        STAMP_RE = /\*\*reviewed\*\*\s+\d{4}-\d{2}\s+\(v(\d+\.\d+(?:\.\d+)?)\)/
-        MINOR_THRESHOLD = 5
-
-        def call
-          current_minor = parse_minor(Textus::VERSION)
-          issues = []
-
-          manifest.resolver.enumerate.each do |row|
-            next unless row[:key].to_s.start_with?("knowledge.")
-            next unless row[:path] && File.file?(row[:path])
-
-            body = File.read(row[:path])
-            m = body.match(STAMP_RE)
-            next unless m
-
-            reviewed_minor = parse_minor(m[1])
-            behind = current_minor - reviewed_minor
-            next unless behind > MINOR_THRESHOLD
-
-            issues << stale_issue(row[:key], m[1], behind)
-          end
-
-          issues
-        end
-
-        private
-
-        def parse_minor(version_str)
-          version_str.sub(/\Av/, "").split(".").map(&:to_i)[1] || 0
-        end
-
-        def stale_issue(key, stamp_version, behind)
-          current_short = Textus::VERSION[/\A\d+\.\d+/]
-          {
-            "code" => "stale_reviewed_stamp",
-            "level" => "warning",
-            "subject" => key.to_s,
-            "message" => "reviewed at v#{stamp_version}; current is v#{Textus::VERSION} " \
-                         "(#{behind} minor versions behind, threshold is #{MINOR_THRESHOLD})",
-            "fix" => "review the doc and update the stamp to: **reviewed** YYYY-MM (v#{current_short})",
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,29 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Templates < Check
-        def call
-          out = []
-          manifest.data.entries.each do |entry|
-            entry.publish_targets.each do |target|
-              template = target.template
-              next if template.nil?
-
-              tp = geometry.template_path(template)
-              next if File.exist?(tp)
-
-              out << {
-                "code" => "template.missing",
-                "level" => "error",
-                "subject" => entry.key,
-                "message" => "template '#{template}' not found at #{tp}",
-                "fix" => "create the file at #{tp} or update the publish target's template: field",
-              }
-            end
-          end
-          out
-        end
-      end
-    end
-  end
-end