principles 0.0.1

data/lib/principles/data/json_text.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # JSON text that an agent or a person wrote, parsed so that an object naming one key twice is refused on
+    # every json version. Ruby 3.4's own json keeps the last of two duplicates without a word, so a reviewer
+    # reading a diff could see one value while this tool used the other.
+    class JsonText
+      # An object under construction, which refuses a key it already holds.
+      class UniqueKeys
+        #: () -> void
+        def initialize
+          @pairs = {} #: Hash[untyped, untyped]
+        end
+
+        #: (untyped, untyped) -> untyped
+        def []=(key, value)
+          raise JSON::ParserError, "duplicate key #{key.inspect}" if @pairs.key?(key)
+
+          @pairs[key] = value
+        end
+
+        #: () -> Hash[untyped, untyped]
+        def to_h
+          @pairs
+        end
+      end
+
+      #: (String) -> void
+      def initialize(text)
+        @text = text
+        freeze
+      end
+
+      # The parsed value, made only of plain hashes and arrays; raises JSON::ParserError on a duplicate key.
+      #: () -> untyped
+      def parsed
+        plain(JSON.parse(@text, object_class: UniqueKeys))
+      end
+
+      private
+
+      #: (untyped) -> untyped
+      def plain(value)
+        case value
+        when UniqueKeys then value.to_h.transform_values { |each| plain(each) }
+        when Array then value.map { |each| plain(each) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/principles/data/known_fields.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The fields a schema names, kept from data at every depth. This tool's schemas allow fields they do not
+    # name, so an older version can read a newer file (D29), but a field a person or agent added must never
+    # be printed back as if this tool had said it.
+    class KnownFields
+      #: (Hash[String, untyped]) -> void
+      def initialize(schema)
+        @schema = schema
+        freeze
+      end
+
+      # data with only the named fields; data is assumed to fit the schema.
+      #: (untyped, ?Hash[String, untyped]) -> untyped
+      def of(data, schema = @schema)
+        case data
+        when Hash then named(data, schema)
+        when Array then schema["items"] ? data.map { |each| of(each, schema.fetch("items")) } : data
+        else data
+        end
+      end
+
+      private
+
+      # An object's named fields, and every field when the schema gives one schema for all its values.
+      #: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def named(data, schema)
+        properties = schema.fetch("properties", {})
+        each_value = schema["additionalProperties"]
+        data.each_with_object({}) do |(key, value), kept|
+          if properties.key?(key) then kept[key] = of(value, properties.fetch(key))
+          elsif each_value.is_a?(Hash) then kept[key] = of(value, each_value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/principles/data/linked_path.rb

@@ -0,0 +1,102 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # A path in the project, as its symbolic links lead it. A host may load an instruction file through a link, and
+    # git holds a link as the name of its target, so the text at path depends on every link on the way, a linked
+    # folder's included, and on the file they lead to (#695).
+    class LinkedPath
+      # The most links followed, as an operating system caps them, so a cycle ends.
+      MOST_LINKS = 40
+
+      # One link on the way to a path: where it is, the target it names, and the parts of the path beyond it.
+      class Hop
+        #: String
+        attr_reader :link, :target
+
+        #: Array[String]
+        attr_reader :rest
+
+        #: (String, String, Array[String]) -> void
+        def initialize(link, target, rest)
+          @link = link
+          @target = target
+          @rest = rest
+          freeze
+        end
+      end
+
+      # read_link gives the target the link at a path relative to root names, as the disk holds it, or nil for a
+      # path that is not a link.
+      #: (path: String, root: String, read_link: ^(String) -> String?) -> void
+      def initialize(path:, root:, read_link:)
+        @path = path
+        @root = root
+        @read_link = read_link
+        freeze
+      end
+
+      # The paths, relative to root, that the text at path depends on: each link on the way, in order, then the file
+      # they lead to. A path with no link gives itself. So does one whose links leave the project or never end, which
+      # reading it refuses.
+      #: () -> Array[String]
+      def text_paths
+        links = [] #: Array[String]
+        current = @path #: String
+        MOST_LINKS.times do
+          hop = first_link(current) or return [*links, current]
+          links << hop.link
+          followed = followed(hop) or return [@path]
+          current = followed
+        end
+        [@path]
+      end
+
+      # The file the links lead to, the last of text_paths: path itself when it passes through no link.
+      #: () -> String
+      def leads_to = text_paths.fetch(-1)
+
+      private
+
+      # The first link on the way to path; nil when there is none.
+      #: (String) -> Hop?
+      def first_link(path)
+        parts = path.split("/")
+        (1..parts.length).each do |count|
+          link = parts.take(count).join("/")
+          target = @read_link.call(link) or next
+          return Hop.new(link, target, parts.drop(count))
+        end
+        nil
+      end
+
+      # The path the hop's target and the parts beyond it name, relative to root; nil when it leaves the project.
+      #: (Hop) -> String?
+      def followed(hop)
+        target = hop.target
+        if target.start_with?("/")
+          return unless target.start_with?("#{@root}/")
+
+          return [target.delete_prefix("#{@root}/"), *hop.rest].join("/")
+        end
+        normal([*hop.link.split("/")[0...-1], *target.split("/"), *hop.rest])
+      end
+
+      # parts joined, with each "." dropped and each ".." taking away the part before it; nil when one has none to
+      # take, so the path would leave the project.
+      #: (Array[String]) -> String?
+      def normal(parts)
+        kept = [] #: Array[String]
+        parts.each do |part|
+          next if part.empty? || part == "."
+          return nil if part == ".." && kept.empty?
+
+          part == ".." ? kept.pop : kept.push(part)
+        end
+        kept.join("/")
+      end
+    end
+  end
+end

data/lib/principles/data/map_files.rb

@@ -0,0 +1,104 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+require_relative "schema_check"
+require_relative "principles_subfolder"
+require_relative "json_text"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The member maps this tool writes from the agent's answers: one JSON file per principle under
+    # .principles/maps/, committed in the audited repository. A map holds a description and its members,
+    # each a project file, optionally narrowed to one Markdown section, with the role it plays.
+    class MapFiles
+      # The newest map format this version reads. Models::MemberMap says which member fields need which
+      # format, and a spec ties the two together.
+      NEWEST_FORMAT = 2
+
+      #: (PrinciplesSubfolder) -> void
+      def initialize(directory)
+        @directory = directory
+      end
+
+      #: () -> Array[String]
+      def ids
+        @directory.ids
+      end
+
+      # Which of the folder and its earlier name hold this subfolder (#536).
+      #: () -> Array[String]
+      def held_in
+        @directory.held_in
+      end
+
+      #: (String) -> bool
+      def exist?(id)
+        @directory.exist?(id)
+      end
+
+      # The map id, which exists: Models::MemberMaps refuses one that does not, since which command creates it is
+      # a decision.
+      #: (String) -> Hash[String, untyped]
+      def read(id)
+        parse(id, @directory.read(id, shown_as: relative(id)))
+      end
+
+      # The map id from text read elsewhere, such as the map's file at commit, checked against its schema.
+      #: (String, String, ?commit: String?) -> Hash[String, untyped]
+      def parse(id, text, commit: nil)
+        map = JsonText.new(text).parsed
+        refuse_newer(id, map, commit)
+        problems = SchemaCheck.new("member-map").problems(map)
+        return map if problems.empty?
+
+        raise Error.new("invalid_map", "#{where(id, commit)} is not in the shape this tool writes",
+                        "Repair each field listed, or restore the map from version control.", relative(id),
+                        fields: problems)
+      rescue JSON::ParserError => e
+        raise Error.new("unparseable_map", e.message, "Repair this map file or restore it from version control.",
+                        relative(id))
+      end
+
+      #: (String, Hash[String, untyped]) -> void
+      def write(id, map)
+        @directory.write(id, "#{JSON.pretty_generate(map)}\n")
+      end
+
+      #: (String) -> String
+      def relative(id)
+        File.join(PrinciplesSubfolder::FOLDER, "maps", "#{id}.json")
+      end
+
+      # Where map id was kept before the folder took its name now, so history reads it at earlier commits (#536).
+      #: (String) -> String
+      def earlier_relative(id)
+        File.join(PrinciplesSubfolder::EARLIER_FOLDER, "maps", "#{id}.json")
+      end
+
+      private
+
+      # Refuses a map a newer version wrote, before its schema is checked: its fields may be ones this
+      # version cannot read without losing what they say, and the agent must not be told to repair or
+      # restore a map that is not broken.
+      #: (String, untyped, String?) -> void
+      def refuse_newer(id, map, commit)
+        format = map.is_a?(Hash) ? map["format"] : nil
+        return unless format.is_a?(Integer) && format > NEWEST_FORMAT
+
+        raise Error.new("newer_format", "#{where(id, commit)} is format #{format}, written by a newer version " \
+                                        "than this one; this one reads up to format #{NEWEST_FORMAT}",
+                        "Update the installed principles plugin or gem, then run the command again. " \
+                        "Leave the map as it is: it is not broken.",
+                        relative(id))
+      end
+
+      #: (String, String?) -> String
+      def where(id, commit)
+        commit ? "#{relative(id)} at commit #{commit[0, 12]}" : relative(id)
+      end
+    end
+  end
+end

data/lib/principles/data/principle_id.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # A principle id as a file name under .principles: lower-kebab-case, so it names one file in its directory
+    # and never a path outside it. Every map and audit file is reached through one, whichever command asked.
+    class PrincipleId
+      FORMAT = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/ #: Regexp
+
+      #: (String) -> void
+      def initialize(id)
+        unless id.match?(FORMAT)
+          raise Error.new("invalid_id", "#{id.inspect} is not a principle id, which is lower-kebab-case",
+                          "To see the mapped ids: #{Error::EXECUTABLE} list-principles")
+        end
+
+        @id = id
+        freeze
+      end
+
+      # The file this id names in directory.
+      #: (String) -> String
+      def file_in(directory)
+        File.join(directory, "#{@id}.json")
+      end
+    end
+  end
+end

data/lib/principles/data/principles_subfolder.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+require_relative "../error"
+require_relative "principle_id"
+require_relative "bounded_file"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # One of this tool's own directories, .principles/maps or .principles/audits, holding one JSON file per id
+    # as bytes; MapFiles and AuditFiles keep the rules for what those bytes say. A cloned project may hold
+    # a committed symbolic link at .principles or at the directory, which would send this tool's reads and
+    # writes outside the project, so each use refuses one.
+    class PrinciplesSubfolder
+      # The folder a project keeps its maps and audit records in.
+      FOLDER = ".principles"
+      # Its name before the rename to principles; a project an older version mapped still holds it (#536).
+      EARLIER_FOLDER = ".memeplex"
+
+      #: (String, String) -> void
+      def initialize(root, name)
+        @root = root
+        @name = name
+        freeze
+      end
+
+      # The directory's path, once neither it nor FOLDER is a symbolic link.
+      #: () -> String
+      def path
+        [FOLDER, File.join(FOLDER, @name)].each { |relative| refuse_link(relative) }
+        File.join(@root, FOLDER, @name)
+      end
+
+      # Which of FOLDER and EARLIER_FOLDER hold this subfolder, in that order, so a model can refuse a project
+      # whose maps or records have not moved. A file an older version left beside no subfolder holds none.
+      #: () -> Array[String]
+      def held_in
+        [FOLDER, EARLIER_FOLDER].select { |folder| File.directory?(File.join(@root, folder, @name)) }
+      end
+
+      # The file id names in this directory.
+      #: (String) -> String
+      def file(id)
+        PrincipleId.new(id).file_in(path)
+      end
+
+      # The ids of the JSON files in this directory, sorted.
+      #: () -> Array[String]
+      def ids
+        Dir.glob(File.join(path, "*.json")).map { |each| File.basename(each, ".json") }.sort
+      end
+
+      #: (String) -> bool
+      def exist?(id)
+        File.exist?(file(id))
+      end
+
+      # The text of id's file, read within BoundedFile's limit and named as shown_as in a refusal.
+      #: (String, shown_as: String) -> String
+      def read(id, shown_as:)
+        BoundedFile.new(file(id), shown_as: shown_as).read
+      end
+
+      # Writes text as id's file, whole or not at all: it is written beside the file, then renamed over it.
+      #: (String, String) -> void
+      def write(id, text)
+        directory = path
+        FileUtils.mkdir_p(directory)
+        Tempfile.create([id, ".json"], directory) do |temporary|
+          temporary.write(text)
+          temporary.flush
+          File.rename(temporary.path, file(id))
+        end
+      end
+
+      private
+
+      #: (String) -> void
+      def refuse_link(relative)
+        return unless File.symlink?(File.join(@root, relative))
+
+        raise Error.new("symlinked_directory",
+                        "#{relative} is a symbolic link, so a read or write there would leave the " \
+                        "project",
+                        "Replace the link with a real directory, then restore its files from version control.",
+                        relative)
+      end
+    end
+  end
+end

data/lib/principles/data/project_files.rb

@@ -0,0 +1,109 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require_relative "../error"
+require_relative "json_text"
+require_relative "bounded_file"
+require_relative "candidate_files_found"
+require_relative "linked_path"
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # Reads the selected project's files: resolves paths inside it, reads members' text and lists candidates.
+    class ProjectFiles
+      #: String
+      attr_reader :root
+
+      #: (String) -> void
+      def initialize(root)
+        @root = File.realpath(root) #: String
+      end
+
+      # A project file's text, refused unless it is a readable UTF-8 file inside the project.
+      # Models::MemberFile finds a member's place in it.
+      #: (String) -> String
+      def read_text(path)
+        text = BoundedFile.new(resolve(path), shown_as: path).read
+        unless text.valid_encoding?
+          raise Error.new("invalid_encoding", "Cannot read UTF-8 text", "Choose a text member.",
+                          path)
+        end
+
+        text
+      rescue SystemCallError => e
+        raise Error.new("unreadable_file", e.message, "Restore a readable project-local file, then retry.", path)
+      end
+
+      # The paths the text at path depends on, each symbolic link on the way and then the file they lead to, as
+      # LinkedPath gives them; path alone when it passes through no link (#695).
+      #: (String) -> Array[String]
+      def text_paths(path) = linked(path).text_paths
+
+      # The file path's links lead to, read in place of path; path itself when it passes through no link (#695).
+      #: (String) -> String
+      def leads_to(path) = linked(path).leads_to
+
+      # path as the links on the disk lead it.
+      #: (String) -> LinkedPath
+      def linked(path)
+        LinkedPath.new(path: path, root: @root, read_link: lambda { |relative|
+          absolute = File.join(@root, relative)
+          File.readlink(absolute) if File.symlink?(absolute)
+        })
+      end
+
+      # Whether path names a file inside the project; its contents are not read.
+      #: (String) -> bool
+      def file?(path)
+        absolute = File.expand_path(path, @root)
+        absolute.start_with?("#{@root}/") && File.file?(absolute)
+      end
+
+      #: (String) -> String
+      def resolve(path)
+        absolute = File.expand_path(path, @root)
+        check_inside(absolute, path)
+        unless File.file?(absolute)
+          raise Error.new("not_a_file", "Reference does not name a file", "Select a regular text file.",
+                          path)
+        end
+
+        absolute
+      rescue SystemCallError => e
+        raise Error.new("unreadable_file", e.message, "Restore the referenced file or correct its path.", path)
+      end
+
+      # Refuses a path that leaves the project, directly or through a link.
+      #: (String, String) -> void
+      def check_inside(absolute, path)
+        return if absolute.start_with?("#{@root}/") && File.realpath(absolute).start_with?("#{@root}/")
+
+        raise Error.new("outside_project", "Reference is outside the selected project",
+                        "Choose a file inside this project; external scopes are not supported in this alpha.", path)
+      end
+
+      # The instruction files hosts load by convention, as CandidateFilesFound lists them.
+      #: () -> Hash[String, untyped]
+      def inventory = CandidateFilesFound.new(self).to_h
+
+      #: (String) -> untyped
+      def read_json(path)
+        parse_json(BoundedFile.new(path).read, path)
+      rescue SystemCallError => e
+        raise Error.new("unreadable_file", e.message, "Supply a readable JSON file.", path)
+      end
+
+      # JSON from text read elsewhere, such as stdin, named by source in a refusal.
+      #: (String, String) -> untyped
+      def parse_json(text, source)
+        BoundedFile.new(source).refuse_larger(text.bytesize)
+        JsonText.new(text).parsed
+      rescue JSON::ParserError => e
+        raise Error.new("unparseable_json", e.message, "Repair this JSON and retry; no response was accepted.",
+                        source)
+      end
+    end
+  end
+end