principles 0.0.1

data/lib/principles/models/member_maps.rb

@@ -0,0 +1,185 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/map_files"
+require_relative "member_map"
+require_relative "meta_principle"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Every member map in the project, loaded and saved through Data::MapFiles.
+    class MemberMaps
+      # A principle id names its principle in lower-kebab-case.
+      ID_FORMAT = Data::PrincipleId::FORMAT #: Regexp
+
+      #: (Data::MapFiles) -> void
+      def initialize(files)
+        @files = files
+      end
+
+      #: () -> Array[String]
+      def ids
+        @files.ids
+      end
+
+      # The id of map id, or of every map when id is nil; an id no map has is refused, as find refuses it.
+      #: (String?) -> Array[String]
+      def ids_of(id)
+        return ids unless id
+
+        find(id)
+        [id]
+      end
+
+      # Every path a map this tool can read names, once each; a map it cannot read names none, so one broken map
+      # still leaves the others' files known.
+      #: () -> Array[String]
+      def readable_paths
+        ids.flat_map do |id|
+          find(id).members.paths
+        rescue Error
+          []
+        end.uniq
+      end
+
+      # Whether a map named id exists, whatever it holds.
+      #: (String) -> bool
+      def mapped?(id) = @files.exist?(id)
+
+      # Whether principles is set up: the meta-principle's map names a keeping place, a member of any kind. That says
+      # a place is named, not that the principle is held, which its audit finds. A map this version cannot read, in a
+      # newer format, unparseable or invalid, counts, since it may well have members, so no read refuses over it (D75).
+      #: () -> bool
+      def set_up?
+        return false unless mapped?(MetaPrinciple::ID)
+
+        begin
+          !find(MetaPrinciple::ID).unstarted?
+        rescue Error
+          true
+        end
+      end
+
+      # The map named id, refused when there is none; Data::MapFiles refuses one that is unparseable.
+      #: (String) -> MemberMap
+      def find(id)
+        refuse_unknown(id)
+        unique(MemberMap.new(id, @files.read(id)))
+      end
+
+      # The map id as text read elsewhere holds it, such as its file at commit, the one an audit began from.
+      #: (String, String, ?commit: String?) -> MemberMap
+      def parsed(id, text, commit: nil)
+        unique(MemberMap.new(id, @files.parse(id, text, commit: commit)), commit)
+      end
+
+      # A new map for id with no members, not yet saved. It is refused unless id is lower-kebab-case and not
+      # yet mapped, and is not the meta-principle's, which setup starts; only then is the description asked for.
+      #: (String) { () -> String } -> MemberMap
+      def create(id, &)
+        refuse_unavailable(id)
+        refuse_meta_principle_id(id)
+        MemberMap.new(id, { "description" => yield, "members" => [] })
+      end
+
+      # The map a new member of principle id joins: the map named id, or, while the meta-principle has none, the map
+      # it starts with, not yet saved, so that map is written only with its first member (T74). Any other id no map
+      # has is refused, as find refuses it.
+      #: (String) -> MemberMap
+      def addable(id)
+        return find(id) if mapped?(id) || !started_by_setup?(id)
+
+        MemberMap.new(id, MetaPrinciple.starting_fields)
+      end
+
+      # The map named id, refused when it has no members to audit.
+      #: (String) -> MemberMap
+      def auditable(id)
+        map = find(id)
+        return map unless map.members.empty?
+
+        raise Error.new("map_has_no_members", "#{id} has no members to audit",
+                        "Add its members: #{Error::EXECUTABLE} add-member #{id} PATH --role ROLE", file(id))
+      end
+
+      # Writes map's file and names it, relative to the project.
+      #: (MemberMap) -> String
+      def save(map)
+        @files.write(map.id, map.to_h)
+        file(map.id)
+      end
+
+      # The file map id is kept in, relative to the project.
+      #: (String) -> String
+      def file(id)
+        @files.relative(id)
+      end
+
+      # The file map id was kept in under the folder's earlier name, relative to the project (#536).
+      #: (String) -> String
+      def earlier_file(id)
+        @files.earlier_relative(id)
+      end
+
+      private
+
+      # Whether principle id's map is started by setup and written by the add-member it prints, never by
+      # create-principle: only the meta-principle's, whose description and activation ship with the tool (T74).
+      #: (String) -> bool
+      def started_by_setup?(id) = id == MetaPrinciple::ID
+
+      # map, refused when two of its members share an id or a key, as MapMembers#refuse_repeats says.
+      #: (MemberMap, ?String?) -> MemberMap
+      def unique(map, commit = nil)
+        where = commit ? "#{file(map.id)} at commit #{commit[0, 12]}" : file(map.id)
+        map.members.refuse_repeats(where: where, file: file(map.id))
+        map
+      end
+
+      # A principle no map names, with the commands that create one and list the rest. For the meta-principle's id the
+      # repair leads to setup, not create-principle, which would give its map another description and no activation;
+      # setup writes no map, and the add-member it prints creates it (T74).
+      #: (String) -> void
+      def refuse_unknown(id)
+        return if mapped?(id)
+
+        raise Error.new("unknown_principle", "No map named #{id}",
+                        "#{creating(id)}\nTo see the mapped ids: #{Error::EXECUTABLE} list-principles")
+      end
+
+      # The repair line that creates principle id's map.
+      #: (String) -> String
+      def creating(id)
+        return MetaPrinciple::SET_UP if started_by_setup?(id)
+
+        "To create it: #{Error::EXECUTABLE} create-principle #{id} --description TEXT"
+      end
+
+      # The meta-principle's map is written by the add-member setup prints, with its first member; create-principle
+      # would write it with no members, another description and no activation (T74).
+      #: (String) -> void
+      def refuse_meta_principle_id(id)
+        return unless started_by_setup?(id)
+
+        raise Error.new("meta_principle_id",
+                        "#{id} is set up by show-meta-principle-passage, whose printed add-member creates its map " \
+                        "with its first member", MetaPrinciple::SET_UP)
+      end
+
+      #: (String) -> void
+      def refuse_unavailable(id)
+        unless id.match?(ID_FORMAT)
+          raise Error.new("invalid_id", "#{id} is not lower-kebab-case",
+                          "Name the principle in lower-kebab-case, such as express-intent.")
+        end
+        return unless @files.exist?(id)
+
+        raise Error.new("principle_exists", "#{id} is already mapped",
+                        "To change its description: #{Error::EXECUTABLE} change-description #{id} --description TEXT",
+                        file(id))
+      end
+    end
+  end
+end

data/lib/principles/models/member_moves.rb

@@ -0,0 +1,95 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member"
+require_relative "member_map"
+
+module Principles
+  # The domain: maps, audits and command steps, with every rule a schema cannot express.
+  # models/CLAUDE.md owns the boundary.
+  module Models
+    # The members a correction says the agent moved after the audit began, from each old id to its new one. A
+    # fix can rewrite the text a member's locator quotes; the agent then runs move-member and declares the
+    # move, and this tool checks it against the map at the base commit (D28).
+    class MemberMoves
+      #: (untyped) -> void
+      def initialize(moves)
+        @moves = parsed(moves) #: Hash[String, String]
+        freeze
+      end
+
+      #: () -> bool
+      def empty?
+        @moves.empty?
+      end
+
+      # Refuses moves outside git, where there is no base map to check them against.
+      #: (String?, principle_id: String) -> String
+      def check_in_git(base, principle_id:)
+        return base if base
+
+        raise Error.new("moves_need_git", "moved_members needs git, to read the map #{principle_id} began from",
+                        "Outside git, start a fresh audit: #{Error::EXECUTABLE} start-audit #{principle_id}")
+      end
+
+      # The base map with each declared member moved to its place in current, each keeping its role.
+      #: (MemberMap, MemberMap) -> MemberMap
+      def applied(base, current)
+        @moves.reduce(base) { |map, (from, to)| map.moving(from, located(current, to)) }
+      end
+
+      # The refusal of a map that changed beyond the moves declared.
+      #: (String, String) -> Error
+      def undeclared(principle_id, map_file)
+        Error.new("undeclared_move", "The map of #{principle_id} changed during this audit beyond the moves declared",
+                  "Declare each member you moved in moved_members, or start a fresh audit: " \
+                  "#{Error::EXECUTABLE} start-audit #{principle_id}", map_file)
+      end
+
+      # The member's id after the declared moves.
+      #: (String) -> String
+      def renamed(member_id)
+        @moves.fetch(member_id, member_id)
+      end
+
+      # Each finding with its members' ids after the moves.
+      #: (Array[untyped]) -> Array[untyped]
+      def findings(findings)
+        findings.map { |finding| finding.merge("member_ids" => finding.fetch("member_ids").map { |id| renamed(id) }) }
+      end
+
+      # The values in by_id, such as each member's hash or its record entry's fields, keyed by each member's id
+      # after the moves.
+      #: [V] (Hash[String, V]) -> Hash[String, V]
+      def hashes(by_id)
+        by_id.transform_keys { |id| renamed(id) }
+      end
+
+      private
+
+      #: (untyped) -> Hash[String, String]
+      def parsed(moves)
+        return {} if moves.nil?
+
+        unless moves.is_a?(Array) && moves.all? { |move| move.is_a?(Hash) && move.values_at("from", "to").all?(String) }
+          raise Error.new("invalid_answer", "moved_members must be a list of {\"from\": OLD_ID, \"to\": NEW_ID}",
+                          "List each member you moved with move-member, by its id before and after.")
+        end
+
+        moves.to_h { |move| [move.fetch("from"), move.fetch("to")] }
+      end
+
+      # The current member to's place in its file, without its role.
+      #: (MemberMap, String) -> Hash[String, untyped]
+      def located(current, to)
+        unless current.members.taken?(to)
+          raise Error.new("unknown_member", "#{to} is not a member of #{current.id}",
+                          "Name in moved_members the id show-principle lists after the move.")
+        end
+
+        current.members.found(to).to_h.except("role")
+      end
+    end
+  end
+end

data/lib/principles/models/member_problems.rb

@@ -0,0 +1,253 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "audit_record"
+require_relative "map_members"
+require_relative "member_map_history"
+require_relative "member_state"
+require_relative "locate_refusal"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # One map's members, each as broken, changed, unchanged, unchanged since its mapping commit or with no
+    # baseline, against what this tool last knew of its text: the last audit's hash for it, or else its text at
+    # the commit that mapped it where it is.
+    # A member is changed only when its own text changed, so an edit elsewhere in its file is not one.
+    class MemberProblems
+      # What this tool last knew of each member's text, by key: the last audit's hashes and the commit it began
+      # from, and each member's hash and commit at the commit that mapped it where it is (#243).
+      class Baselines
+        # The last audit's hashes for members' map, and each member's hash and commit at the commit that mapped it
+        # where it is, read with the map as that commit held it; none outside git.
+        #: (Project, MapMembers) -> Baselines
+        def self.of(project, members)
+          id = members.principle_id
+          audit = project.audit_records.find(id)
+          mapped = MemberMapHistory.new(id: id, history: project.history, member_maps: project.member_maps)
+                                   .mapped_baselines(members.keys)
+          new(audit: audit, mapped: mapped.transform_values { |each| each.fetch("sha256") },
+              mapped_in: mapped.transform_values { |each| each.fetch("commit") }, in_git: project.history.inside_git?)
+        end
+
+        # Whether the project is in git, so a member with no baseline is one no commit holds yet.
+        #: bool
+        attr_reader :in_git
+
+        # audit is the principle's audit record, if any: its hashes, the commit it began from and whether it is
+        # completed, so a one-member audit is offered only where one would be accepted (#626).
+        #: (audit: AuditRecord?, mapped: Hash[String, String], mapped_in: Hash[String, String], in_git: bool)
+        #|  -> void
+        def initialize(audit:, mapped:, mapped_in:, in_git:)
+          @audited = audit&.members&.hashes_by_key || {} #: Hash[String, String]
+          @audit = audit #: AuditRecord?
+          @audit_base = audit&.base_commit #: String?
+          @mapped = mapped
+          @mapped_in = mapped_in
+          @in_git = in_git
+          freeze
+        end
+
+        # The hash this tool last knew for the member known by key, and what it was: the last audit's, or else its
+        # hash at the commit that mapped it, with why no audit gave one; neither when it has no baseline.
+        #: (String) -> [String?, Hash[String, untyped]?]
+        def of(key)
+          if @audited.key?(key)
+            [@audited[key], { "baseline" => "audit", "commit" => @audit_base }]
+          elsif @mapped.key?(key)
+            [@mapped[key], { "baseline" => "mapping_commit", "commit" => @mapped_in[key],
+                             "no_audit_because" => @audited.empty? ? "no_audit_record" : "not_in_last_audit" }]
+          else
+            [nil, nil]
+          end
+        end
+
+        # Why a member these baselines do not hold has none: in git no commit holds it where its map places
+        # it, and outside git there is no history.
+        #: () -> String
+        def none_because = @in_git ? "not_committed" : "outside_git"
+
+        # Whether no full audit of the principle has completed: it has no record, or an open one that keeps none
+        # (D58).
+        #: () -> bool
+        def no_completed_audit?
+          audit = @audit
+          audit.nil? || audit.last_completed.nil?
+        end
+
+        # Whether a one-member audit may judge member's change to now_sha256: in git, and where the audit record gives
+        # no refusal, which Acknowledgement refuses by too, so list-member-problems offers no command certain to be
+        # refused (#626, #632).
+        #: (Member, String?) -> bool
+        def acknowledgeable?(member, now_sha256)
+          audit = @audit
+          @in_git && !audit.nil? && audit.acknowledgement_refusal(member, now_sha256:).nil?
+        end
+      end
+
+      # One map's members in project against what this tool last knew of each. A map that cannot be read is
+      # refused when it was asked for, and listed as broken among every map.
+      #: (Project, String, ?listing_all: bool) -> MemberProblems
+      def self.for(project, id, listing_all: false)
+        members = project.member_maps.find(id).members
+        new(members: members, now: project.current_by_key(members), baselines: Baselines.of(project, members))
+      rescue Error => e
+        raise unless listing_all
+
+        none = MapMembers.new(id, [])
+        new(members: none, now: {}, baselines: Baselines.of(project, none), unreadable: e.payload)
+      end
+
+      # now holds, for each member by key, its hash now or the refusal that says why it cannot be found.
+      # unreadable is the refusal for a map this tool could not read, which is listed as one broken entry.
+      #: (members: MapMembers, now: Hash[String, untyped],
+      #|  baselines: Baselines, ?unreadable: Hash[String, untyped]?) -> void
+      def initialize(members:, now:, baselines:, unreadable: nil)
+        @members = members
+        @now = now
+        @baselines = baselines
+        @unreadable = unreadable
+        freeze
+      end
+
+      # Every member as one entry: its map, id and state, and for a changed member what it was compared with.
+      #: () -> Array[Hash[String, untyped]]
+      def entries
+        if @unreadable
+          return [{ "principle" => principle_id, "state" => "unreadable_map" }.merge(@unreadable.except("status"))]
+        end
+
+        @members.map { |member| entry(member) }
+      end
+
+      # The entries whose reference is broken.
+      #: () -> Array[Hash[String, untyped]]
+      def broken
+        entries.select { |each| MemberState::BROKEN.include?(each.fetch("state")) }
+      end
+
+      # Whether a member an audit or acknowledgement assessed changed since, rather than only a member edited since
+      # the commit that mapped it, which no audit assessed (D44).
+      #: () -> bool
+      def assessed_change? = changed_members.any? { |member| assessed?(member) }
+
+      # The entries whose own text changed since this tool last knew it, those an audit assessed first. Given a
+      # block, each gains "history", what the block makes of its member, the hash it was compared with, and its
+      # hash now.
+      #: () ?{ (Member, String, String) -> Hash[String, untyped] } -> Array[Hash[String, untyped]]
+      def changed(&history)
+        assessed, unassessed = changed_members.partition { |member| assessed?(member) }
+        (assessed + unassessed).map do |member|
+          listed = entry(member)
+          next listed unless history
+
+          listed.merge("history" => history.call(member, baseline(member.key).first.to_s, @now[member.key].to_s))
+        end
+      end
+
+      # Each member in paths whose own text changed or whose reference is now broken, with its state, as a completed
+      # audit names them for another map that shares a file the audit's fixes changed (#410).
+      #: (Array[String]) -> Array[MemberState]
+      def changed_or_broken_in(paths)
+        return [] if @unreadable
+
+        @members.in_files(paths).map { |member| MemberState.new(member.id, entry(member).fetch("state")) }
+                .select(&:changed_or_broken?)
+      end
+
+      # Each member no audit has judged as it is now, by id with its state: changed or broken since what this tool
+      # last knew of it, or never assessed, having only its mapping commit or no baseline at all (D71, D44). A map
+      # this tool cannot read is one entry, with no id, whose state is unreadable_map.
+      #: () -> Array[Hash[String, untyped]]
+      def unjudged = entries.reject { it.fetch("state") == "unchanged" }.map { it.slice("id", "state") }
+
+      #: () -> String
+      def principle_id = @members.principle_id
+
+      # The ids of the members whose own text changed and whose change a one-member audit may judge on its own, so
+      # list-member-problems fills that audit's command for each (D56, #728).
+      #: () -> Array[String]
+      def acknowledgeable_member_ids
+        changed_members.select { |member| @baselines.acknowledgeable?(member, @now[member.key]) }.map(&:id)
+      end
+
+      # How many members found in their files were compared with each baseline, audit or mapping_commit, or had
+      # none (no_baseline), so an unchanged member compared only with the commit that mapped it is not read as
+      # unchanged since an audit.
+      #: () -> Hash[String, Integer]
+      def compared_with
+        return {} if @unreadable
+
+        found = @members.reject { |member| @now[member.key].is_a?(Hash) }
+        found.map { |member| baseline(member.key).last&.fetch("baseline") || "no_baseline" }.tally.sort.to_h
+      end
+
+      # Whether the principle awaits its first full audit: none has completed and a member is found, in git one a
+      # commit or an open audit gives a baseline, since until a commit holds its map committing gives its members
+      # one (D58, #731 R7).
+      #: () -> bool
+      def awaits_first_audit?
+        return false unless @baselines.no_completed_audit?
+
+        bases = compared_with.keys
+        @baselines.in_git ? bases.any? { it != "no_baseline" } : !bases.empty?
+      end
+
+      # Why members found in their files have no baseline, or nil when every one has one. Outside git a principle
+      # awaiting its first full audit has none either: that audit is the one remedy, which awaits_first_audit? names.
+      #: () -> String?
+      def no_baseline_because
+        return if no_baseline_paths.empty? || (awaits_first_audit? && !@baselines.in_git)
+
+        @baselines.none_because
+      end
+
+      # Each file holding a member found with no baseline, once.
+      #: () -> Array[String]
+      def no_baseline_paths
+        return [] if @unreadable
+
+        @members.select { |member| !@now[member.key].is_a?(Hash) && baseline(member.key).last.nil? }
+                .map(&:path).uniq
+      end
+
+      private
+
+      # The members whose own text changed since this tool last knew it; none in a map that cannot be read.
+      #: () -> Array[Member]
+      def changed_members
+        return [] if @unreadable
+
+        @members.select { |member| entry(member).fetch("state") == "changed" }
+      end
+
+      #: (Member) -> bool
+      def assessed?(member) = baseline(member.key).last&.fetch("baseline") == "audit"
+
+      #: (Member) -> Hash[String, untyped]
+      def entry(member)
+        listed = { "principle" => principle_id, "id" => member.id }
+        now = @now[member.key]
+        return compared(listed, member.key, now.to_s) unless now.is_a?(Hash)
+
+        listed.merge("state" => LocateRefusal.new(now).member_state).merge(now.except("status"))
+      end
+
+      # listed, compared with the last audit's hash for key, or else with its hash at the commit that mapped it.
+      # An unchanged member compared only with the commit that mapped it has never been assessed, so it is
+      # counted apart from one an audit assessed: counts is read first, and "unchanged" alone reads as audited (#569).
+      #: (Hash[String, untyped], String, String) -> Hash[String, untyped]
+      def compared(listed, key, sha)
+        then_sha, since = baseline(key)
+        return listed.merge("state" => "no_baseline") unless since
+        return listed.merge("state" => "changed", "since" => since) unless then_sha == sha
+
+        listed.merge("state" => since["baseline"] == "mapping_commit" ? "unchanged_since_mapping" : "unchanged")
+      end
+
+      #: (String) -> [String?, Hash[String, untyped]?]
+      def baseline(key) = @baselines.of(key)
+    end
+  end
+end