principles 0.0.1

data/lib/principles/data/repository.rb

@@ -0,0 +1,165 @@
+# 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 git repository holding the project, if there is one. This tool only reads it: the commit at HEAD,
+    # which paths differ from it, and a file's text at a commit. git's own messages are kept off this tool's
+    # output.
+    class Repository
+      # The only revisions this tool hands git: HEAD or a full commit sha (SHA-1 or SHA-256), optionally its first
+      # parent. None can be read as an option or a wider revision expression.
+      REVISION = /\A(?:HEAD|\h{40}(?:\h{24})?)\^?\z/ #: Regexp
+
+      # git reads each path this tool passes as itself, never as a glob or a :(magic) pathspec, so a member's
+      # file name cannot take in other files.
+      LITERAL = { "GIT_LITERAL_PATHSPECS" => "1" }.freeze #: Hash[String, String]
+
+      #: (String) -> void
+      def initialize(root)
+        @root = root
+      end
+
+      # Whether the project is inside a git work tree.
+      #: () -> bool
+      def inside?
+        output, ok = git(["rev-parse", "--is-inside-work-tree"])
+        ok && output.strip == "true"
+      end
+
+      # The full sha of the last commit that changed path, or nil outside git or when no commit has.
+      #: (String) -> String?
+      def last_commit(path)
+        sha, ok = git(["log", "-1", "--format=%H", "--", path])
+        ok && !sha.strip.empty? ? sha.strip : nil
+      end
+
+      # Whether path, relative to the project, is absent from the working tree.
+      #: (String) -> bool
+      def absent?(path)
+        !File.exist?(File.join(@root, path))
+      end
+
+      # Each rename git detects between commit and the working tree, as {"from", "to", "similarity"}, with paths
+      # relative to the project; none outside git or when commit is not there, as in a shallow clone.
+      #: (String) -> Array[Hash[String, untyped]]
+      def renames_since(commit)
+        output, ok = git(["diff", "-M", "-z", "--name-status", "--relative", "--diff-filter=R", revision(commit), "--"])
+        return [] unless ok
+
+        output.force_encoding("UTF-8").split("\0").each_slice(3).filter_map do |status, from, to|
+          next unless status.to_s.start_with?("R") && from && to
+
+          { "from" => from, "to" => to, "similarity" => status.to_s.delete_prefix("R").to_i }
+        end
+      end
+
+      # The full sha at HEAD, or nil outside git or before the first commit.
+      #: () -> String?
+      def head
+        sha, ok = git(["rev-parse", "--verify", "--quiet", "HEAD"])
+        ok && !sha.strip.empty? ? sha.strip : nil
+      end
+
+      # Which of paths, relative to the project, are untracked or ignored, or differ from HEAD in the index
+      # or the working tree. Before the first commit, every path does.
+      #: (Array[String]) -> Array[String]
+      def uncommitted(paths)
+        return [] if paths.empty?
+        return paths.uniq.sort unless head
+
+        changed, = git(["diff", "--name-only", "--relative", "-z", "HEAD", "--", *paths])
+        untracked, = git(["ls-files", "--others", "-z", "--", *paths])
+        (changed.split("\0") + untracked.split("\0")).uniq.sort
+      end
+
+      # Which of paths, relative to the project, git does not track and does not ignore. Before the first
+      # commit, every path not staged is one.
+      #: (Array[String]) -> Array[String]
+      def untracked(paths)
+        return [] if paths.empty?
+
+        output, = git(["ls-files", "--others", "--exclude-standard", "-z", "--", *paths])
+        output.split("\0").sort
+      end
+
+      # Which of paths, relative to the project, git does not track, ignored or not. Unlike untracked, it names an
+      # ignored file too, since git holds it no more than an untracked one (#896).
+      #: (Array[String]) -> Array[String]
+      def not_tracked(paths)
+        return [] if paths.empty?
+
+        output, = git(["ls-files", "--others", "-z", "--", *paths])
+        output.split("\0").sort
+      end
+
+      # Every file in the project that differs from HEAD, is gone since it, or is untracked, sorted. Unlike
+      # uncommitted, it leaves ignored files out: it is asked about the whole project, where an ignored file is
+      # one the owner chose to keep out of git, while uncommitted is asked about named members, which an audit
+      # needs committed (#390, #409). Before the first commit, every file not ignored is one.
+      #: () -> Array[String]
+      def changed_files
+        changed, = head ? git(["diff", "--name-only", "--relative", "-z", "HEAD"]) : [""]
+        untracked, = git(["ls-files", "--others", "--exclude-standard", "-z"])
+        (changed.split("\0") + untracked.split("\0")).uniq.sort
+      end
+
+      # path's text at commit, or nil when the commit does not hold it.
+      #: (String, String) -> String?
+      def text_at(commit, path)
+        text, ok = git(["show", "--end-of-options", "#{revision(commit)}:./#{path}"])
+        ok ? text.force_encoding("UTF-8") : nil
+      end
+
+      # The commits after commit, up to HEAD, that changed any of paths, newest first, each as its short sha and
+      # subject line.
+      #: (String, Array[String]) -> Array[Hash[String, String]]
+      def commits_since(commit, paths)
+        output, ok = git(["log", "--format=%h%x00%s", "--end-of-options", "#{revision(commit)}..HEAD", "--", *paths])
+        return [] unless ok
+
+        output.force_encoding("UTF-8").lines.map do |line|
+          sha, subject = line.chomp.split("\0", 2)
+          { "commit" => sha.to_s, "subject" => subject.to_s }
+        end
+      end
+
+      # Every commit on HEAD's first-parent line that changed any of paths, newest first, each as its full and
+      # short sha, subject line, author date and whether it is a root commit ("true" or "false"); none outside git.
+      # since leaves out since and every commit before it.
+      #: (Array[String], ?since: String?) -> Array[Hash[String, String]]
+      def commits_touching(paths, since: nil)
+        range = since ? "#{revision(since)}..HEAD" : "HEAD"
+        output, ok = git(["log", "--first-parent", "--format=%H%x00%h%x00%s%x00%aI%x00%P", "--end-of-options", range,
+                          "--", *paths])
+        return [] unless ok
+
+        output.force_encoding("UTF-8").lines.map do |line|
+          sha, short, subject, authored_at, parents = line.chomp.split("\0", 5)
+          { "sha" => sha.to_s, "commit" => short.to_s, "subject" => subject.to_s, "authored_at" => authored_at.to_s,
+            "root" => parents.to_s.empty?.to_s }
+        end
+      end
+
+      private
+
+      # commit, once it is known to be a revision this tool hands git. Answers are checked against their schema
+      # first, so reaching here with anything else is a defect in this tool, not a refusal for the agent.
+      #: (String) -> String
+      def revision(commit)
+        raise ArgumentError, "not a revision this tool reads: #{commit.inspect}" unless REVISION.match?(commit)
+
+        commit
+      end
+
+      #: (Array[String]) -> [String, bool]
+      def git(arguments)
+        output = IO.popen(LITERAL, ["git", "-C", @root, *arguments], err: File::NULL, &:read)
+        [output, Process.last_status&.success? || false]
+      rescue SystemCallError
+        ["", false]
+      end
+    end
+  end
+end

data/lib/principles/data/running_version.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "English"
+require_relative "../version"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The version that is running: what a build stamped, or, in a checkout, the release
+    # with the commit it runs from, as RELEASE.g<short sha>. The g keeps a development version a RubyGems
+    # prerelease even when every character of the sha is a digit.
+    class RunningVersion
+      # git archive writes the short sha of the commit it archives here, since .gitattributes marks this file
+      # export-subst; a checkout keeps the placeholder as written (#898).
+      ARCHIVED_COMMIT = "$Format:%h$" #: String
+
+      #: (?String, ?archived_commit: String) -> void
+      def initialize(checkout = File.expand_path("../../..", __dir__), archived_commit: ARCHIVED_COMMIT)
+        @checkout = checkout
+        @archived_commit = archived_commit
+      end
+
+      #: () -> String
+      def to_s
+        BUILT_VERSION || "#{RELEASE}.g#{commit}"
+      end
+
+      private
+
+      # The short sha an archive wrote, which names its commit even inside another repository; else the commit the
+      # checkout is at, or "unknown" outside git.
+      #: () -> String
+      def commit
+        return @archived_commit if @archived_commit.match?(/\A\h+\z/)
+
+        sha = IO.popen(["git", "-C", @checkout, "rev-parse", "--short", "HEAD"], err: File::NULL, &:read).to_s.strip
+        $CHILD_STATUS&.success? && !sha.empty? ? sha : "unknown"
+      rescue SystemCallError
+        "unknown"
+      end
+    end
+  end
+end

data/lib/principles/data/schema_check.rb

@@ -0,0 +1,139 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+require_relative "expected_type"
+require_relative "known_fields"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # Checks parsed JSON against one of the schemas in schemas/, with the standard library alone, so a run
+    # needs no gem (D29). It supports only KEYWORDS, which is what this tool's own schemas use; a spec fails on
+    # a schema that uses another, and a conformance spec compares its verdicts with json_schemer's.
+    class SchemaCheck
+      # The keywords a schema may use, besides annotations such as title and description.
+      KEYWORDS = %w[type properties required additionalProperties items minLength pattern enum const].freeze
+      # This tool's own schema keyword, on an object that refuses fields it does not name: for a field an agent
+      # may put there by mistake, where it belongs instead, which its refusal adds (#769), as {field => text}.
+      UNREAD_FIELD_ADVICE = "x-unread-field-advice"
+      # Keywords that only describe, and check nothing; the refusal advice is worded into a refusal.
+      ANNOTATIONS = %W[$schema $id title description #{ExpectedType::ADVICE} #{UNREAD_FIELD_ADVICE}].freeze
+
+      #: (String) -> void
+      def initialize(name)
+        @schema = JSON.parse(File.read(File.join(__dir__, "schemas", "#{name}.schema.json"))) #: Hash[String, untyped]
+      end
+
+      # Each place data breaks the schema, as a JSON pointer and what is wrong there, sorted by pointer.
+      #: (untyped) -> Array[Hash[String, String]]
+      def problems(data)
+        found = [] #: Array[Hash[String, String]]
+        check(@schema, data, "", found)
+        found.sort_by { |problem| problem.fetch("pointer") }
+      end
+
+      # data with only the fields the schema names, for printing; KnownFields owns the rule.
+      #: (untyped) -> untyped
+      def known(data)
+        KnownFields.new(@schema).of(data)
+      end
+
+      # data when it fits the schema; otherwise a refusal with code, naming source and each failing field.
+      #: (untyped, code: String, source: String, repair: String) -> untyped
+      def checked(data, code:, source:, repair:)
+        found = problems(data)
+        return data if found.empty?
+
+        raise Error.new(code, "#{source} is not in the shape this tool reads", repair, source, fields: found)
+      end
+
+      private
+
+      #: (Hash[String, untyped], untyped, String, Array[Hash[String, String]]) -> void
+      def check(schema, value, pointer, found)
+        expected = ExpectedType.new(schema)
+        return found << problem(pointer, "must be #{expected}") unless expected.matches?(value)
+
+        check_value(schema, value, pointer, found)
+        check_object(schema, value, pointer, found) if value.is_a?(Hash)
+        check_items(schema, value, pointer, found) if value.is_a?(Array)
+      end
+
+      #: (Hash[String, untyped], untyped, String, Array[Hash[String, String]]) -> void
+      def check_value(schema, value, pointer, found)
+        found << problem(pointer, "must be #{JSON.generate(schema["const"])}") if mismatched_const?(schema, value)
+        found << problem(pointer, "must be one of #{choices(schema)}") if schema["enum"]&.include?(value) == false
+        check_string(schema, value, pointer, found) if value.is_a?(String)
+      end
+
+      #: (Hash[String, untyped], String, String, Array[Hash[String, String]]) -> void
+      def check_string(schema, value, pointer, found)
+        found << problem(pointer, "must not be empty") if too_short?(schema, value)
+        found << problem(pointer, "must match #{schema["pattern"]}") if unmatched?(schema, value)
+      end
+
+      #: (Hash[String, untyped], String) -> bool
+      def unmatched?(schema, value)
+        pattern = schema["pattern"]
+        pattern ? !Regexp.new(pattern).match?(value) : false
+      end
+
+      #: (Hash[String, untyped], untyped) -> bool
+      def mismatched_const?(schema, value)
+        schema.key?("const") && value != schema["const"]
+      end
+
+      #: (Hash[String, untyped]) -> String
+      def choices(schema)
+        schema.fetch("enum").map { |each| JSON.generate(each) }.join(", ")
+      end
+
+      #: (Hash[String, untyped], untyped) -> bool
+      def too_short?(schema, value)
+        minimum = schema["minLength"]
+        return false unless minimum && value.is_a?(String)
+
+        value.length < minimum
+      end
+
+      #: (Hash[String, untyped], Hash[String, untyped], String, Array[Hash[String, String]]) -> void
+      def check_object(schema, value, pointer, found)
+        schema.fetch("required", []).each do |key|
+          found << problem(child(pointer, key), "is required") unless value.key?(key)
+        end
+        value.each { |key, each| check_property(schema, key, each, pointer, found) }
+      end
+
+      #: (Hash[String, untyped], String, untyped, String, Array[Hash[String, String]]) -> void
+      def check_property(schema, key, value, pointer, found)
+        # A field the schema names, else additionalProperties: false refuses it, or a schema checks it.
+        property = schema.fetch("properties", {})[key] || schema["additionalProperties"]
+        if property.is_a?(Hash)
+          check(property, value, child(pointer, key), found)
+        elsif property == false
+          advice = schema.fetch(UNREAD_FIELD_ADVICE, {})[key]
+          found << problem(child(pointer, key), ["is not a field this tool reads here", *advice].join("; "))
+        end
+      end
+
+      #: (Hash[String, untyped], Array[untyped], String, Array[Hash[String, String]]) -> void
+      def check_items(schema, value, pointer, found)
+        items = schema["items"] or return
+        value.each_with_index { |each, index| check(items, each, child(pointer, index.to_s), found) }
+      end
+
+      # The pointer to key inside pointer, escaped as RFC 6901 asks.
+      #: (String, String) -> String
+      def child(pointer, key)
+        "#{pointer}/#{key.gsub("~", "~0").gsub("/", "~1")}"
+      end
+
+      #: (String, String) -> Hash[String, String]
+      def problem(pointer, text)
+        { "pointer" => pointer, "problem" => text }
+      end
+    end
+  end
+end

data/lib/principles/data/schemas/acknowledgement-answer.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "acknowledgement-answer.schema.json",
+  "title": "Acknowledgement answer",
+  "description": "What an agent answers a one-member audit with (D33): the request's id and basis, whether the change keeps the member's meaning, a one-line reason, and a line quoted from the member's text before the change and one from after it. Fields this tool does not read are refused (D29). Models::Acknowledgement checks the quotes and the reason.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["request_id", "basis", "meaning_kept", "reason", "old_line", "new_line"],
+  "properties": {
+    "request_id": { "type": "string" },
+    "basis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["base_commit", "member_id"],
+      "properties": {
+        "base_commit": { "type": "string" },
+        "member_id": { "type": "string" }
+      }
+    },
+    "meaning_kept": { "type": "boolean" },
+    "reason": { "type": "string", "minLength": 1 },
+    "old_line": { "type": "string", "minLength": 1 },
+    "new_line": { "type": "string", "minLength": 1 }
+  }
+}

data/lib/principles/data/schemas/answer-guide.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "answer-guide.schema.json",
+  "title": "Answer guide",
+  "description": "Example shapes the assessment request shows for the parts of an answer its template cannot show by example.",
+  "type": "object",
+  "required": ["finding", "member_delivery", "recent_decision", "reassessment", "check_result"],
+  "additionalProperties": false,
+  "properties": {
+    "finding": {
+      "type": "object",
+      "required": ["id", "member_ids", "problem", "consequence", "proposed_action", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "member_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "problem": { "type": "string" },
+        "consequence": { "type": "string" },
+        "proposed_action": { "type": "string" },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["path"],
+            "properties": {
+              "path": { "type": "string" },
+              "heading": { "type": "string" },
+              "starting_at": { "type": "string" },
+              "ending_at": { "type": "string" },
+              "query": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      }
+    },
+    "member_delivery": {
+      "type": "object",
+      "required": ["not_observed", "observed"],
+      "additionalProperties": false,
+      "properties": {
+        "not_observed": {
+          "type": "object",
+          "required": ["delivery"],
+          "properties": { "delivery": { "const": "not_observed" } },
+          "additionalProperties": false
+        },
+        "observed": {
+          "type": "object",
+          "required": ["delivery", "observation"],
+          "properties": { "delivery": { "const": "observed" }, "observation": { "type": "string" },
+                          "observed_at": { "type": "string" } },
+          "additionalProperties": false
+        }
+      }
+    },
+"recent_decision": {
+  "type": "object",
+  "required": ["assessed", "unavailable"],
+  "additionalProperties": false,
+  "properties": {
+    "assessed": {
+      "type": "object",
+      "required": ["assessment", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "assessment": { "type": "string" },
+        "evidence": { "$ref": "#/properties/finding/properties/evidence" }
+      }
+    },
+    "unavailable": {
+      "type": "object",
+      "required": ["unavailable_reason"],
+      "properties": { "unavailable_reason": { "type": "string" } },
+      "additionalProperties": false
+    }
+  }
+},
+"reassessment": { "type": "string" },
+"check_result": {
+  "type": "object",
+  "required": ["ran", "not_run", "limits"],
+  "additionalProperties": false,
+  "properties": {
+    "ran": {
+      "type": "object", "required": ["command", "exit_status"], "additionalProperties": false,
+      "properties": { "command": { "type": "string" }, "exit_status": { "type": "integer" },
+                      "review_basis": { "type": "string" } }
+    },
+    "not_run": {
+      "type": "object", "required": ["command", "not_run_reason"], "additionalProperties": false,
+      "properties": { "command": { "type": "string" }, "not_run_reason": { "type": "string" } }
+    },
+    "limits": { "type": "string" }
+  }
+}
+  }
+}