principles 0.0.1

data/lib/principles/models/prior_finding_outcomes.rb

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "decided_prior_findings"
+require_relative "kept_prior_finding"
+require_relative "prior_finding_decision"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What the next full audit's decisions, once PriorFindings has checked them, do to each finding the last audit
+    # left open (D35): the findings kept, as the record keeps them, the ones closed, and, for each new finding that
+    # raises a prior one again, when that one was first raised.
+    class PriorFindingOutcomes
+      # decisions are the checked decisions, each on the finding it decides.
+      #: (Array[PriorFindingDecision]) -> void
+      def initialize(decisions)
+        @decisions = decisions
+        freeze
+      end
+
+      # What the decisions do to each finding, which each kept finding answers for itself.
+      #: () -> DecidedPriorFindings
+      def decided
+        holding = of(["still_holds"]).map(&:kept)
+        DecidedPriorFindings.new(
+          { "kept" => holding.map(&:to_h), "closed" => of(PriorFindingDecision::CLOSING).map(&:closed),
+            "inherited" => first_raised(of(["raised_again"])), "dropped" => holding.filter_map(&:dropped_write_up),
+            "waits_on_dropped" => holding.filter_map(&:waits_on_dropped),
+            "evidence_replaced" => holding.flat_map(&:swaps) }
+        )
+      end
+
+      private
+
+      #: (Array[String]) -> Array[PriorFindingDecision]
+      def of(kinds) = @decisions.select { |decision| kinds.include?(decision.kind) }
+
+      # When each finding raised again was first raised, by the id of the new finding it became. Two raised as one
+      # new finding are refused, since only one first_raised_at can pass on.
+      #: (Array[PriorFindingDecision]) -> Hash[String, String?]
+      def first_raised(raised)
+        raised.group_by(&:raised_as).to_h do |as, same|
+          raised_once(as, same.map { |decision| decision.finding.id })
+          [as, same.fetch(0).finding.first_raised_at]
+        end
+      end
+
+      #: (String, Array[String]) -> void
+      def raised_once(as, ids)
+        return if ids.one?
+
+        raise Error.new("invalid_decision", "#{ids.join(", ")} are raised again as one new finding, #{as}",
+                        "Raise one again as #{as} and close the others as withdrawn, with a reason naming #{as}, " \
+                        "or raise each as its own new finding.")
+      end
+    end
+  end
+end

data/lib/principles/models/prior_findings.rb

@@ -0,0 +1,109 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "audit_record"
+require_relative "decided_prior_findings"
+require_relative "prior_finding_outcomes"
+require_relative "prior_finding_decision"
+require_relative "member"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The findings the last completed audit deferred or accepted, which the next full audit must decide one by
+    # one (D35): each still holds, was resolved, was withdrawn, or is raised again as a new finding. This tool
+    # lists them and checks the decisions; whether a finding still holds is the agent's judgement.
+    class PriorFindings
+      # record is the last audit's record, or nil; members are the map's members now, and now each one's hash.
+      #: (record: AuditRecord?, members: MapMembers, now: Hash[String, String]) -> void
+      def initialize(record:, members:, now:)
+        @record = record
+        @left_open = record&.left_open || [] #: Array[OpenFinding]
+        @members = members
+        @now = now
+        freeze
+      end
+
+      # Each prior finding as the next audit's request lists it, under its members' ids now, with whether each
+      # member changed since that audit.
+      #: () -> Array[Hash[String, untyped]]
+      def listed
+        @left_open.map { |finding| finding.for_next_audit_against(@members, @now) }
+      end
+
+      # Each prior finding as the request shows it: as listed, and with a last_audited_commit, each evidence item with
+      # what since says of it now against that commit (#858, #877). The request id digests listed, so these facts never
+      # make an answer stale.
+      #: () { (EvidenceItem, String) -> Hash[String, bool] } -> Array[Hash[String, untyped]]
+      def shown(&since)
+        base = last_audited_commit or return listed
+
+        @left_open.map { |finding| finding.for_next_audit_against(@members, @now) { |item| since.call(item, base) } }
+      end
+
+      # The commit the audit that left these findings open, raising or keeping each, was based on: what each evidence
+      # item's text is compared at (#858). nil outside git, or with no record. The record AuditRecord#left_open reads
+      # them from gives it, so the two cannot disagree.
+      #: () -> String?
+      def last_audited_commit = @record&.last_completed&.base_commit
+
+      # What the request id digests, so an answer to a request made before the record changed is stale.
+      #: () -> Array[Hash[String, untyped]]
+      def digested
+        listed.map { |finding| finding.slice("finding_id", "member_ids", "problem", "action", "first_raised_at") }
+      end
+
+      # The decisions, checked against the listed findings and this audit's new findings. locate checks that a
+      # new recorded_at resolves, as a deferral's is checked; records read the record a claim of an earlier
+      # first_raised_at cites (D53).
+      #: (untyped, Array[untyped], ?records: AuditRecords?) { (Locator) -> void } -> DecidedPriorFindings
+      def decided(decisions, findings, records: nil, &locate)
+        new_ids = findings.map { |finding| finding.fetch("id") }
+        decisions = checked(complete(decisions, left_open_by_id.keys), new_ids, locate, records)
+        PriorFindingOutcomes.new(decisions).decided.tap { it.distinct_from(new_ids) }
+      end
+
+      private
+
+      # The decisions, each on the finding it decides, once checked against it and this audit's new findings.
+      #: (Array[Hash[String, untyped]], Array[String], ^(Locator) -> void, AuditRecords?)
+      #|  -> Array[PriorFindingDecision]
+      def checked(decisions, new_ids, locate, records)
+        open = left_open_by_id
+        decisions.each_with_index.map do |each, index|
+          decision = PriorFindingDecision.new(each, open.fetch(each["finding_id"]), new_ids,
+                                              at: "/prior_finding_decisions/#{index}", members: @members)
+          check(decision, locate, records)
+          decision
+        end
+      end
+
+      # Refuses decision unless it is sound for the finding it decides, given this audit's new findings, and any
+      # earlier first_raised_at it claims is borne out by the record it cites, which records read (D53).
+      #: (PriorFindingDecision, ^(Locator) -> void, AuditRecords?) -> void
+      def check(decision, locate, records)
+        decision.check(locate)
+        decision.first_raised_claim.check(records, principle_id)
+      end
+
+      # The principle whose record left the prior findings open; none is decided without one.
+      #: () -> String
+      def principle_id = @record ? @record.principle_id : ""
+
+      #: () -> Hash[String, OpenFinding]
+      def left_open_by_id = @left_open.to_h { |finding| [finding.id, finding] }
+
+      #: (untyped, Array[String]) -> Array[Hash[String, untyped]]
+      def complete(decisions, expected)
+        decisions = [] unless decisions.is_a?(Array)
+        decided = decisions.map { |decision| decision.is_a?(Hash) ? decision["finding_id"] : nil }
+        return decisions if decided.sort == expected.sort
+
+        raise Error.new("incomplete_prior_findings", "Decide each prior finding exactly once: #{expected.join(", ")}",
+                        "Give prior_finding_decisions one {finding_id, decision} for each prior finding the request " \
+                        "lists, with decision still_holds, resolved, withdrawn or raised_again.")
+      end
+    end
+  end
+end

data/lib/principles/models/problem_report.rb

@@ -0,0 +1,110 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_problems"
+require_relative "missing_files"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # What list-member-problems reports across the maps it reads: refused while any member's reference is
+    # broken, so a gate can stop on its exit status alone, and otherwise every changed member and a count of
+    # each state.
+    class ProblemReport
+      # history, when given, lets each missing file carry the rename git detects for it (#276).
+      #: (Array[MemberProblems], ?history: ProjectHistory?) -> void
+      def initialize(maps, history: nil)
+        @maps = maps
+        @history = history
+        freeze
+      end
+
+      # The changed members and the count of each state, refused when any member is broken. Given a block, each
+      # changed member gains the history the block makes of its map id, member, baseline hash and hash now.
+      #: () ?{ (String, Member, String, String) -> Hash[String, untyped] } -> Hash[String, untyped]
+      def checked(&)
+        broken = @maps.flat_map(&:broken)
+        refuse(broken) unless broken.empty?
+
+        { "members" => changed(&),
+          "counts" => @maps.flat_map(&:entries).map { |each| each.fetch("state") }.tally.sort.to_h,
+          "compared_with" => compared_with, **no_baseline_because, **awaiting_first_audit_field }
+      end
+
+      # The principles that await their first full audit, in map order, which list-member-problems names in one
+      # line (D58, #731).
+      #: () -> Array[String]
+      def awaiting_first_audit = @maps.select(&:awaits_first_audit?).map(&:principle_id)
+
+      # Whether any map's member changed since an audit or acknowledgement assessed it, not only since it was
+      # mapped, which --short exits 3 for rather than 4 (D44).
+      #: () -> bool
+      def assessed_change? = @maps.any?(&:assessed_change?)
+
+      # For each map with a changed member a one-member audit may judge, the ids of those members, which
+      # list-member-problems offers that audit for, one command each (#626, D56).
+      #: () -> Hash[String, Array[String]]
+      def acknowledgeable
+        @maps.to_h { |map| [map.principle_id, map.acknowledgeable_member_ids] }.reject { |_, ids| ids.empty? }
+      end
+
+      # For each map with members no baseline holds, its map file and the files those members are in, and in git
+      # only those of them that differ from HEAD or are untracked, since committing an unchanged file does nothing
+      # (#710 X3). In git the list is empty when every one is committed already.
+      #: (MemberMaps) -> Hash[String, Array[String]]
+      def files_to_commit(member_maps)
+        no_baseline_paths.to_h do |id, paths|
+          files = [member_maps.file(id), *paths]
+          [id, @history&.inside_git? ? @history.uncommitted(files) : files]
+        end
+      end
+
+      private
+
+      # Each map's files holding a member with no baseline, by map id; a map with none is left out.
+      #: () -> Hash[String, Array[String]]
+      def no_baseline_paths
+        @maps.to_h { |map| [map.principle_id, map.no_baseline_paths] }.reject { |_, paths| paths.empty? }
+      end
+
+      #: () ?{ (String, Member, String, String) -> Hash[String, untyped] } -> Array[Hash[String, untyped]]
+      def changed(&history)
+        @maps.flat_map do |map|
+          next map.changed unless history
+
+          map.changed { |member, baseline, now| history.call(map.principle_id, member, baseline, now) }
+        end
+      end
+
+      # Each map's count of members by the baseline they were compared with; a map with none is left out.
+      #: () -> Hash[String, Hash[String, Integer]]
+      def compared_with
+        @maps.to_h { |map| [map.principle_id, map.compared_with] }.reject { |_, counts| counts.empty? }
+      end
+
+      # Why each map's members with no baseline have none, under no_baseline_because, or nothing when all have one.
+      #: () -> Hash[String, Hash[String, String]]
+      def no_baseline_because
+        because = @maps.to_h { |map| [map.principle_id, map.no_baseline_because] }.compact
+        because.empty? ? {} : { "no_baseline_because" => because }
+      end
+
+      # awaiting_first_audit under its own key, or nothing when no principle awaits one.
+      #: () -> Hash[String, Array[String]]
+      def awaiting_first_audit_field
+        awaiting = awaiting_first_audit
+        awaiting.empty? ? {} : { "awaiting_first_audit" => awaiting }
+      end
+
+      #: (Array[Hash[String, untyped]]) -> bot
+      def refuse(broken)
+        named = broken.map { |each| [each["principle"], each["id"]].compact.join(" ") }
+        missing = MissingFiles.new(broken, history: @history)
+        raise missing.refusal("#{broken.length} members cannot be found or read: #{named.join(", ")}",
+                              rerun: "#{Error::EXECUTABLE} list-member-problems",
+                              note: "A map listed as unreadable_map needs its own refusal's repair. ")
+      end
+    end
+  end
+end

data/lib/principles/models/project.rb

@@ -0,0 +1,214 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../data/project_files"
+require_relative "../data/schema_check"
+require_relative "../data/map_files"
+require_relative "../data/audit_files"
+require_relative "../data/principles_subfolder"
+require_relative "../data/repository"
+require_relative "candidate_inventory"
+require_relative "entry_files"
+require_relative "member"
+require_relative "member_file"
+require_relative "hook_commands"
+require_relative "loaded_files"
+require_relative "located_text"
+require_relative "member_loads"
+require_relative "member_lines"
+require_relative "member_maps"
+require_relative "member_snapshots"
+require_relative "missing_files"
+require_relative "locate_refusal"
+require_relative "audit_records"
+require_relative "project_history"
+require_relative "principles_folder_move"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The user's project as this tool reads it: its instruction files, each member's text, the answers an
+    # agent hands in, and the maps, audit records and git history kept beside them. Controllers reach the
+    # project only through this model. It is handed its four data adapters, so a spec can hand it stand-ins
+    # that meet the same contracts (#337).
+    class Project
+      # The project at root, with its maps, audit records and history.
+      #: (String) -> Project
+      def self.at(root)
+        files = Data::ProjectFiles.new(root)
+        new(files: files, maps: Data::MapFiles.new(Data::PrinciplesSubfolder.new(files.root, "maps")),
+            audits: Data::AuditFiles.new(Data::PrinciplesSubfolder.new(files.root, "audits")),
+            repository: Data::Repository.new(files.root))
+      end
+
+      #: (files: Data::ProjectFiles, maps: Data::MapFiles, audits: Data::AuditFiles,
+      #|  repository: Data::Repository) -> void
+      def initialize(files:, maps:, audits:, repository:)
+        @files = files
+        @maps = maps
+        @audits = audits
+        @repository = repository
+      end
+
+      # The project's root, resolved.
+      #: () -> String
+      def root
+        @files.root
+      end
+
+      #: () -> MemberMaps
+      def member_maps
+        refuse_unmoved_folder
+        MemberMaps.new(@maps)
+      end
+
+      #: () -> AuditRecords
+      def audit_records
+        refuse_unmoved_folder
+        AuditRecords.new(@audits, history)
+      end
+
+      #: () -> ProjectHistory
+      def history
+        ProjectHistory.new(@repository, @files)
+      end
+
+      # Whether two paths name one file, as their symbolic links lead them, so an edit through either is an edit
+      # to both (#695).
+      #: (String, String) -> bool
+      def same_file?(path, other) = @files.leads_to(path) == @files.leads_to(other)
+
+      # Where a member is in its file now, and the hash of what it says there.
+      #: (Locator) -> Hash[String, untyped]
+      def locate(locator)
+        member_file(locator.path).locate(locator)
+      end
+
+      # The text locator finds now, as one value: its path, its lines and the hash of what it says (#909).
+      #: (Locator) -> LocatedText
+      def located_text(locator) = LocatedText.of(locate(locator))
+
+      # The member at locator, its lines in its file at commit beside its lines now, which an audit shows the
+      # agent so it judges the member's own change without the rest of its file's (#379); nil when commit lacks the
+      # file or its locator finds nothing there, as after a move, which each caller says in its own terms (#459).
+      # then_locator places it at commit where it was elsewhere then, as before a move (#547).
+      #: (Locator, since: String, ?then_locator: Locator) -> MemberLines?
+      def member_lines(locator, since:, then_locator: locator)
+        before = history.lines_at(since, then_locator) or return nil
+
+        MemberLines.new(at_baseline: before, now: member_file(locator.path).lines_of(locator))
+      end
+
+      # As member_lines, since the last full audit's commit, or that it cannot be found there, so a full audit still
+      # starts (#457).
+      #: (Locator, since: String) -> (MemberLines | MemberLinesNotFoundAtLastAudit)
+      def member_lines_since_last_audit(locator, since:)
+        member_lines(locator, since: since) || MemberLinesNotFoundAtLastAudit.new
+      end
+
+      # The project file at path as the type that finds a member in it, refused when it cannot be read.
+      #: (String) -> MemberFile
+      def member_file(path)
+        MemberFile.for(path: path, text: @files.read_text(path))
+      end
+
+      # Each of map's members by id, where it is in its file now and the hash of what it says there. It is
+      # refused once, listing every member that cannot be found or read, so the agent repairs them together.
+      #: (MemberMap) -> MemberSnapshots
+      def snapshots(map)
+        broken = [] #: Array[Hash[String, untyped]]
+        found = map.members.to_h do |member|
+          [member.id, locate(member.locator)]
+        rescue Error => e
+          broken << { "id" => member.id }.merge(e.payload.except("status"))
+          [member.id, {}]
+        end
+        broken.empty? ? MemberSnapshots.new(found) : refuse_broken(map.id, broken)
+      end
+
+      # The superseded, git-ignored file where an older version kept audit runs; this version never reads it.
+      OLDER_STATE = ".memeplex/state.json" #: String
+
+      # The files beside the maps that an older version wrote and this one does not read, so an audit kept
+      # only there is no baseline.
+      #: () -> Array[String]
+      def unread_older_files
+        @files.file?(OLDER_STATE) ? [OLDER_STATE] : []
+      end
+
+      # Each member's hash now by key, or the refusal that says why its text cannot be found or read.
+      #: (MapMembers) -> Hash[String, untyped]
+      def current_by_key(members)
+        members.to_h do |member|
+          [member.key, locate(member.locator).fetch("sha256")]
+        rescue Error => e
+          [member.key, e.payload]
+        end
+      end
+
+      #: (String, Array[Hash[String, untyped]]) -> bot
+      def refuse_broken(map_id, broken)
+        ids = broken.map { |member| member.fetch("id") }.join(", ")
+        missing = MissingFiles.new(broken, principle: map_id, history: history)
+        raise missing.refusal("#{broken.length} of #{map_id}'s members cannot be found or read: #{ids}")
+      end
+
+      # A member's text now and how fresh it is, which the block says from its hash. A member whose place
+      # in its file is gone is locator_lost; one whose file cannot be read is unavailable. Both keep the
+      # refusal.
+      #: (Locator) { (String) -> String } -> Hash[String, untyped]
+      def freshness(locator, &)
+        now = locate(locator)
+        { "snapshot" => now, "freshness" => yield(now.fetch("sha256")) }
+      rescue Error => e
+        { "freshness" => LocateRefusal.new(e.payload).member_state, "error" => e.payload }
+      end
+
+      # Each member's MemberLoads by id: when each host loads it into context, with the size of what loads, and
+      # the project hooks whose commands name its file, read once for them all unless the caller already read them.
+      #: (MapMembers, ?HookCommands) -> Hash[String, MemberLoads]
+      def member_loads(members, hooks = hook_commands)
+        members.to_h { |member| [member.id, MemberLoads.read(@files, member.locator, hooks: hooks)] }
+      end
+
+      # The files members load, each read whole once, with the project's hooks as hooks read them (#483).
+      #: (MapMembers, HookCommands) -> LoadedFiles
+      def loaded_files(members, hooks) = LoadedFiles.read(@files, members, hooks: hooks)
+
+      #: () -> HookCommands
+      def hook_commands
+        HookCommands.read(@files)
+      end
+
+      # The root entry files every session of a host loads, whether one links the other and which git does not
+      # track.
+      #: () -> EntryFiles
+      def entry_files = EntryFiles.read(@files, history)
+
+      ANSWER_REPAIR = "Repair each field listed, starting from the request's response_template."
+
+      # An answer to a phase's request from file, where - means it was read from stdin, checked against the
+      # phase's answer schema (D29).
+      #: (String, stdin: String?, phase: String) -> untyped
+      def answer(file, stdin:, phase:)
+        parsed = file == "-" ? @files.parse_json(stdin.to_s, "-") : @files.read_json(file)
+        Data::SchemaCheck.new("#{phase}-answer").checked(parsed, code: "invalid_answer", source: file,
+                                                                 repair: ANSWER_REPAIR)
+      end
+
+      # What list-candidate-files found: the candidate files as it lists them, and which git does not track.
+      #: () -> CandidateInventory
+      def candidate_files
+        CandidateInventory.found(@files.inventory, history)
+      end
+
+      private
+
+      # Refuses while the maps or records are still in the folder's earlier name (#536).
+      #: () -> void
+      def refuse_unmoved_folder
+        PrinciplesFolderMove.new(@maps.held_in | @audits.held_in).refuse_while_pending
+      end
+    end
+  end
+end