principles 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51ce6acd3b9d638e2948da0d6e41e0eb4b7656dff90a976bf976f4232020c431
+  data.tar.gz: 803b232afd27b6050db0197f2d77accc7afe852545d17000f2c768a4138aa402
+SHA512:
+  metadata.gz: bb6296b076b2b9ce37d5ad707d1b8312a95edd7e0341da94ee9f7da1587471536db19d1fb3afe072de8f297100fe02da308a7f553b13e99608509413eadcdd0a
+  data.tar.gz: 89b4e1074966cc96af2769263ac1ed9210dd0175c3d0c4490ff681dbfc41da09157a20189e1380e06ae61c5fea7cc261b479c1d1bd1783265163ebd167baafa9

data/exe/principles

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# typed: strict
+# frozen_string_literal: true
+
+# A Ruby this tool cannot run on is refused, or handed to one it can, before lib/ loads.
+require_relative "../lib/principles/supported_ruby"
+Principles::SupportedRuby.new(RUBY_VERSION, ENV.to_h).run_here_or_on_another(__FILE__, ARGV)
+
+require_relative "../lib/principles"
+exit Principles::CLI.run(ARGV)

data/lib/principles/after_commit_hook_options.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation_options"
+
+module Principles
+  # The options the plugin's after-commit hook gives list-member-problems, --commits-after and --hook-event (D73),
+  # and what is wrong with them as given, which CommandLine refuses as a usage error.
+  class AfterCommitHookOptions
+    # The events Claude Code runs the after-commit hook on, which --hook-event echoes back to it.
+    EVENTS = %w[PostToolUse PostToolUseFailure].freeze #: Array[String]
+    # A commit's full sha, SHA-1 or SHA-256, which the hook resolves HEAD@{1} to before passing it.
+    FULL_SHA = /\A\h{40}(?:\h{24})?\z/ #: Regexp
+
+    #: (InvocationOptions) -> void
+    def initialize(options)
+      @after = options.value("commits_after") #: String?
+      @event = options.value("hook_event") #: String?
+      @short = !options.value("short").nil? #: bool
+      freeze
+    end
+
+    # What is wrong with the options as given, or nil when they fit or neither is given.
+    #: () -> String?
+    def fault
+      after = @after
+      event = @event
+      return if after.nil? && event.nil?
+      return "--commits-after and --hook-event are given together, for the after-commit hook" unless after && event
+
+      value_fault(after, event) || ("--commits-after prints the hook's JSON, not the --short lines" if @short)
+    end
+
+    private
+
+    # What is wrong with either value, or nil when both are ones the hook passes.
+    #: (String, String) -> String?
+    def value_fault(after, event)
+      return "--hook-event takes PostToolUse or PostToolUseFailure, not #{event}" unless EVENTS.include?(event)
+
+      "--commits-after takes a commit's full sha, not #{after}" unless FULL_SHA.match?(after)
+    end
+  end
+end

data/lib/principles/cli.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "data/running_version"
+require_relative "models/project"
+require_relative "command_routes"
+require_relative "controllers/help"
+require_relative "command_line"
+
+module Principles
+  # Parses one invocation, runs its step and prints the JSON result. Every refusal is one JSON object
+  # naming its code and repair, because an agent's shell may merge stdout and stderr.
+  class CLI
+    # The repair for a shape error raised from this tool's own code. Such an error cannot say which file was at
+    # fault, so the repair names every file a command reads, and blames none (D29).
+    SHAPE_REPAIR = "A file this command read is not in the shape this tool writes: the map in " \
+                   ".principles/maps/ID.json, its audit record in .principles/audits/ID.json, or the answer given " \
+                   "with --file. Compare it with git, or with the request's response_template."
+
+    # Runs one invocation and returns its exit status: 0 for a result, 1 for a refusal, 2 for a usage error, and 3
+    # when list-member-problems --short finds a member an audit assessed changed, or 4 when it finds only edits to
+    # members no audit has assessed (D44). executable is the command every printed command
+    # names: the entry point says how it is run.
+    #: (Array[String], ?IO, ?IO, ?IO, ?executable: String) -> Integer
+    def self.run(argv, stdout = $stdout, stderr = $stderr, stdin = $stdin,
+                 executable: Controllers::Command::INVOCATION)
+      new(stdout, stderr, stdin, executable: executable).run(argv)
+    end
+
+    #: (IO, IO, IO, executable: String) -> void
+    def initialize(stdout, stderr, stdin, executable:)
+      @stdout = stdout
+      @stderr = stderr
+      @stdin = stdin
+      @executable = executable
+    end
+
+    #: (Array[String]) -> Integer
+    def run(argv)
+      dispatch(CommandLine.new(argv, positional: CommandRoutes::POSITIONAL, executable: @executable))
+    rescue Error => e
+      refused(e.payload, 1)
+    rescue OptionParser::ParseError, KeyError, TypeError, NoMethodError, ArgumentError, SystemCallError => e
+      refused(refusal(e), e.is_a?(OptionParser::ParseError) ? 2 : 1)
+    end
+
+    private
+
+    #: (CommandLine) -> Integer
+    def dispatch(line)
+      return printed(running_version) if line.option("version")
+
+      command = line.command or return printed(help.overview)
+      return printed(help_for(command)) if line.option("help")
+
+      line.check
+      printed_result(result(command, line))
+    end
+
+    # The command's result, from the controller for its group.
+    #: (String, CommandLine) -> untyped
+    def result(command, line)
+      options = line.command_options
+      # One byte past the limit is enough for the answer's own check to refuse it as too large.
+      options["stdin"] = @stdin.read(Data::BoundedFile::LIMIT + 1).to_s if options["file"] == "-"
+      project = Models::Project.at(options.fetch("project"))
+      CommandRoutes::CONTROLLERS.fetch(command).new(project, tool: running_tool)
+                                .call(command, line.id, options)
+    end
+
+    # The JSON object an agent reads for a failure that is not one of this tool's refusals.
+    #: (StandardError) -> Hash[untyped, untyped]
+    def refusal(error)
+      case error
+      when OptionParser::ParseError
+        failure(error, status: "usage_error", code: "invalid_invocation", repair: usage_repair(error))
+      when SystemCallError
+        failure(error, status: "refused", code: "filesystem_error",
+                       repair: "Check the project path and file permissions, then retry.")
+      else
+        failure(error, status: "refused", code: "invalid_shape", repair: SHAPE_REPAIR)
+      end
+    end
+
+    # The repair a refused command line carries for the command it names, or the advice to see every command.
+    #: (OptionParser::ParseError) -> String
+    def usage_repair(error)
+      error.is_a?(CommandLine::UsageRefusal) ? error.repair : "To see every command: #{@executable} --help"
+    end
+
+    # Prints the refusal for the agent and returns the exit status.
+    #: (Hash[untyped, untyped], Integer) -> Integer
+    def refused(payload, status)
+      @stderr.puts(visible(JSON.generate(payload)))
+      status
+    end
+
+    #: (StandardError, status: String, code: String, repair: String) -> Hash[Symbol, String]
+    def failure(error, status:, code:, repair:)
+      { status: status, code: code, message: error.message, repair: repair }
+    end
+
+    # json with every invisible formatting character and line or paragraph separator escaped, as JSON allows.
+    # Text from project files can hold a right-to-left override or a zero-width space, which makes a printed
+    # check or id look like something it is not (#227).
+    #: (String) -> String
+    def visible(json)
+      json.gsub(/[\p{Cf}\p{Zl}\p{Zp}]/) do |character|
+        character.encode("UTF-16BE").unpack("n*").map { |unit| format("\\u%04x", unit) }.join
+      end
+    end
+
+    # A result prints as JSON, or as lines with their own exit status, as list-member-problems --short does.
+    #: (untyped) -> Integer
+    def printed_result(result)
+      return printed(visible(JSON.pretty_generate(result))) unless result.is_a?(Views::Lines)
+
+      @stdout.print(result.stdout)
+      @stderr.print(result.stderr)
+      result.status
+    end
+
+    #: (String) -> Integer
+    def printed(text)
+      @stdout.puts(text)
+      0
+    end
+
+    #: () -> Controllers::Help
+    def help
+      Controllers::Help.new(tool: running_tool)
+    end
+
+    # This run of the tool: the executable it was invoked as, and its version, read only when a command needs it.
+    #: () -> Controllers::RunningTool
+    def running_tool = Controllers::RunningTool.new(executable: @executable, version: -> { running_version })
+
+    # The version of this tool that is running, as a build stamped it or a checkout's commit gives it.
+    #: () -> String
+    def running_version = Data::RunningVersion.new.to_s
+
+    # A command's --help, from the steps command-steps.json lists for it.
+    #: (String) -> String
+    def help_for(command)
+      help.command(command) || raise(OptionParser::InvalidArgument, "#{command} has no help")
+    end
+  end
+end

data/lib/principles/command_line.rb

@@ -0,0 +1,188 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "invocation_options"
+require_relative "after_commit_hook_options"
+require_relative "models/command_steps"
+
+module Principles
+  # One invocation's words: the command, its positional arguments and its options, refused with an
+  # OptionParser error when they do not fit what the command takes. CLI decides what to run from it.
+  class CommandLine
+    # The sources Claude Code's SessionStart hook names, which list-open-findings --short --session-start takes (#717).
+    SESSION_STARTS = %w[startup clear compact].freeze #: Array[String]
+
+    # argv is parsed at once; positional names each command's positional arguments, in order; executable is the
+    # invocation a refusal tells the agent to run --help with (#562).
+    #: (Array[String], positional: Hash[String, Array[String]], executable: String) -> void
+    def initialize(argv, positional:, executable:)
+      @positional = positional
+      @executable = executable
+      @options = InvocationOptions.new #: InvocationOptions
+      @arguments = argv.dup #: Array[String]
+      # The words as typed: parsing takes the options out of @arguments, and a value option is checked against
+      # the word that followed it (#750).
+      @words = argv.dup.freeze #: Array[String]
+      parse(argv)
+    end
+
+    # A usage refusal that carries the repair for the command it names, which CLI prints in place of its
+    # general advice (#576). It stays an OptionParser::ParseError, so it exits 2 like every usage refusal.
+    class UsageRefusal < OptionParser::ParseError
+      #: String
+      attr_reader :repair
+
+      #: (String, String) -> void
+      def initialize(fault, repair)
+        super()
+        @fault = fault
+        @repair = repair
+      end
+
+      #: () -> String
+      def message = @fault
+    end
+
+    # A parsed option's value, or true for a flag that was given.
+    #: (String) -> untyped
+    def option(name)
+      @options.value(name)
+    end
+
+    # The command named first; nil when none is, and refused when this tool has no such command.
+    #: () -> String?
+    def command
+      name = @arguments.first or return nil
+      return name if @positional.key?(name)
+
+      raise OptionParser::InvalidArgument, "unknown command #{name}"
+    end
+
+    # Refuses the wrong number of arguments, an option the command does not take or given an option as its value,
+    # and an answer command without --file.
+    #: () -> void
+    def check
+      name = command.to_s
+      check_arguments(name)
+      check_options(name)
+      check_values_are_not_options(name)
+      check_session_start(name)
+      check_hook_report(name)
+      check_audit_kind(name)
+      return unless %w[submit-answer show-answer-check].include?(name) && !@options.value("file")
+
+      raise OptionParser::MissingArgument, "#{name} needs --file FILE, or --file - for stdin"
+    end
+
+    # The principle id, for a command whose first argument is one.
+    #: () -> String?
+    def id
+      %w[id id?].include?(names.first) ? values.first : nil
+    end
+
+    # The options, with every positional argument but the id under its name.
+    #: () -> Hash[String, untyped]
+    def command_options
+      names.zip(values).each_with_object(@options.to_h) do |(name, value), all|
+        all[name] = value unless %w[id id?].include?(name)
+      end
+    end
+
+    private
+
+    #: () -> Array[String]
+    def names
+      @positional.fetch(command.to_s)
+    end
+
+    #: () -> Array[String]
+    def values
+      @arguments.drop(1)
+    end
+
+    #: (String) -> void
+    def check_arguments(name)
+      return if values.length.between?(names.count { |each| !each.end_with?("?") }, names.length)
+
+      takes = "#{name} takes #{shown_arguments}".strip.sub(/ takes\z/, " takes no arguments")
+      raise OptionParser::InvalidArgument, takes
+    end
+
+    # The positional arguments as usage shows them; a name ending in ? is optional and shown in brackets.
+    #: () -> String
+    def shown_arguments
+      names.map { |each| each.end_with?("?") ? "[#{each.chomp("?").upcase}]" : each.upcase }.join(" ")
+    end
+
+    # An option a command does not take is refused, so a mistyped command never runs as something else.
+    #: (String) -> void
+    def check_options(name)
+      taken = Models::CommandSteps.load.command(name)&.options || []
+      unknown = (@options.given - taken - ["project"]).map { |option| "--#{option}" }
+      return if unknown.empty?
+
+      raise UsageRefusal.new("#{name} does not take #{unknown.join(", ")}", help_repair(name))
+    end
+
+    # An option that takes a value takes the next word, whatever it is, so --member --help took --help as the member
+    # (#750). Only this tool's own option words are refused there, since a quote may start with dashes; such a word is
+    # given as a value after =, as --starting-at=--role is.
+    #: (String) -> void
+    def check_values_are_not_options(name)
+      @words.each_cons(2) do |pair|
+        option = pair.fetch(0)
+        value = pair.fetch(1)
+        next unless InvocationOptions.takes_a_value?(option) && InvocationOptions::WORDS.include?(value)
+
+        raise UsageRefusal.new("#{option} takes a value, not the option #{value}; to give that word as its value, " \
+                               "write #{option}=#{value}", help_repair(name))
+      end
+    end
+
+    # --session-start names one of the hook's sources, and words only the --short line.
+    #: (String) -> void
+    def check_session_start(name)
+      start = @options.value("session_start") or return
+      unless SESSION_STARTS.include?(start)
+        raise UsageRefusal.new("--session-start takes startup, clear or compact, not #{start}", help_repair(name))
+      end
+      return if @options.value("short")
+
+      raise UsageRefusal.new("--session-start words only the --short line", help_repair(name))
+    end
+
+    # --commits-after and --hook-event ask together for the after-commit hook's JSON, which --short's lines are not.
+    #: (String) -> void
+    def check_hook_report(name)
+      fault = AfterCommitHookOptions.new(@options).fault or return
+      raise UsageRefusal.new(fault, help_repair(name))
+    end
+
+    # --member and --write-ups each ask start-audit for a different audit, so only one may be given (#760).
+    #: (String) -> void
+    def check_audit_kind(name)
+      return unless @options.value("member") && @options.value("write_ups")
+
+      raise UsageRefusal.new("--member and --write-ups each start a different audit; give one", help_repair(name))
+    end
+
+    # Parses argv's options; an option no command defines fails here, before the command is checked, and is
+    # repaired with the help of the command argv names, or left to CLI's general advice when it names none.
+    #: (Array[String]) -> void
+    def parse(argv)
+      @options.parse!(@arguments)
+    rescue OptionParser::InvalidOption => e
+      name = named_command(argv) or raise
+      raise UsageRefusal.new(e.message, help_repair(name))
+    end
+
+    # The first word that names a command. The command comes first among the positional words, but an option
+    # and its value may come before it; a value that is itself a command's name leads to that command's help.
+    #: (Array[String]) -> String?
+    def named_command(argv) = argv.find { |word| @positional.key?(word) }
+
+    #: (String) -> String
+    def help_repair(name) = "To see what it takes: #{@executable} #{name} --help"
+  end
+end

data/lib/principles/command_routes.rb

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "controllers/inventory"
+require_relative "controllers/mapping"
+require_relative "controllers/meta_principle_setup"
+require_relative "controllers/member_entries"
+require_relative "controllers/audit"
+require_relative "controllers/answer"
+
+module Principles
+  # Every command this tool runs, each with its route: the positional words it takes, which CommandLine parses, and
+  # the controller that runs it, which CLI hands the parsed line to.
+  module CommandRoutes
+    # One command's route.
+    class Route
+      #: Array[String]
+      attr_reader :positional
+      #: singleton(Controllers::Command)
+      attr_reader :controller
+
+      # positional names each positional argument in order, a trailing ? marking one the command may leave out; the
+      # rest are named options.
+      #: (singleton(Controllers::Command), Array[String]) -> void
+      def initialize(controller, positional)
+        @controller = controller
+        @positional = positional.freeze #: Array[String]
+        freeze
+      end
+    end
+
+    ROUTES = {
+      "list-candidate-files" => Route.new(Controllers::Inventory, []),
+      "list-principles" => Route.new(Controllers::Inventory, []),
+      "list-member-problems" => Route.new(Controllers::Inventory, %w[id?]),
+      "show-principle" => Route.new(Controllers::Inventory, %w[id]),
+      "show-audit" => Route.new(Controllers::Audit, %w[id]),
+      "list-open-findings" => Route.new(Controllers::Audit, %w[id?]),
+      "show-meta-principle-passage" => Route.new(Controllers::MetaPrincipleSetup, []),
+      "create-principle" => Route.new(Controllers::Mapping, %w[id]),
+      "change-description" => Route.new(Controllers::Mapping, %w[id]),
+      "change-activation" => Route.new(Controllers::Mapping, %w[id]),
+      "add-member" => Route.new(Controllers::MemberEntries, %w[id path]),
+      "move-member" => Route.new(Controllers::MemberEntries, %w[id member]),
+      "change-member-role" => Route.new(Controllers::MemberEntries, %w[id member]),
+      "change-member-check" => Route.new(Controllers::MemberEntries, %w[id member]),
+      "remove-member-check" => Route.new(Controllers::MemberEntries, %w[id member]),
+      "remove-member" => Route.new(Controllers::MemberEntries, %w[id member]),
+      "start-audit" => Route.new(Controllers::Audit, %w[id]),
+      "submit-answer" => Route.new(Controllers::Answer, %w[id]),
+      "show-answer-check" => Route.new(Controllers::Answer, %w[id])
+    }.freeze #: Hash[String, Route]
+
+    # Each command's positional arguments, in order, as CommandLine takes them.
+    POSITIONAL = ROUTES.transform_values(&:positional).freeze #: Hash[String, Array[String]]
+
+    # The controller that runs each command: one per set of commands that change for one reason.
+    CONTROLLERS = ROUTES.transform_values(&:controller).freeze #: Hash[String, singleton(Controllers::Command)]
+  end
+end

data/lib/principles/controllers/acknowledgement.rb

@@ -0,0 +1,106 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+require_relative "command"
+require_relative "../models/acknowledgement"
+require_relative "../views/acknowledgement_result"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # A one-member audit (D33): start-audit ID --member MEMBER asks whether a committed change keeps that member's
+    # meaning, and submit-answer moves its baseline in the audit record when the answer holds.
+    class Acknowledgement < Command
+      # The request for principle id's member.
+      #: (String, String) -> Hash[String, untyped]
+      def start(id, member_id)
+        naming_the_executable(rerun: one_member_audit(id)) do
+          acknowledgement, member, base = prepared(id, member_id)
+          baseline, lines = since_baseline(id, acknowledgement, member)
+          change = Views::MemberChangeSinceBaseline.new(
+            member: shown(acknowledgement, member, baseline), member_lines: lines.shown,
+            commits: commits(acknowledgement, baseline, base), paths: acknowledgement.paths_since(baseline)
+          )
+          view.request(request_id: acknowledgement.request_id.to_s, principle_id: id, change: change,
+                       open_findings: acknowledgement.open_findings).merge("wrote" => [])
+        end
+      end
+
+      # The result of answering request_id with response, and the record it changes, not yet written.
+      #: (Models::RequestId, untyped) -> [Hash[String, untyped], Array[Models::AuditRecord]]
+      def answered(request_id, response)
+        id = request_id.principle_id
+        acknowledgement, member, = prepared(id, response.fetch("basis").fetch("member_id"))
+        stale(id, member.id) unless acknowledgement.request_id.to_s == request_id.to_s
+        [view.acknowledged(principle_id: id, member_id: member.id, file: @audit_records.file(id)),
+         [accepted(id, acknowledgement, member, response)]]
+      end
+
+      private
+
+      # The one-member audit of principle id's member, as a refusal naming a near miss leads its repair with (D56).
+      #: (String) -> ^(String) -> String
+      def one_member_audit(id)
+        ->(member) { invocation.in_project("start-audit", id, options: ["--member", member]) }
+      end
+
+      # The record with the acknowledgement in it, once its quotes are found at the baseline and now.
+      #: (String, Models::Acknowledgement, Models::Member, untyped) -> Models::AuditRecord
+      def accepted(id, acknowledgement, member, response)
+        _baseline, lines = since_baseline(id, acknowledgement, member)
+        acknowledgement.accepted(response, before: lines.at_baseline, now: lines.now, at: Time.now.utc.iso8601)
+      end
+
+      # The member as the request shows it, with where it was at its baseline when it has moved since (#547).
+      #: (Models::Acknowledgement, Models::Member, Models::Placement) -> Hash[String, untyped]
+      def shown(acknowledgement, member, baseline)
+        moved_from = acknowledgement.moved_from(baseline)
+        { "id" => member.id, "role" => member.role, "evidence" => [member.reference],
+          **(moved_from ? { "evidence_at_baseline" => [moved_from] } : {}) }
+      end
+
+      # The commits the request names: the baseline's, HEAD, and the audit's base when the baseline is later (#550).
+      #: (Models::Acknowledgement, Models::Placement, String?) -> Hash[String, String]
+      def commits(acknowledgement, baseline, base)
+        audit_base = acknowledgement.audit_base(baseline)
+        { "baseline" => baseline.commit, "base" => base.to_s, **(audit_base ? { "audit_base" => audit_base } : {}) }
+      end
+
+      # The member's baseline, the oldest commit from the one it was last judged at that holds the text the audit
+      # record vouches for, placed as that commit's map placed it or as it is placed now (#547, #550), and its own
+      # lines there and now, which the answer's quotes are checked against (#379).
+      #: (String, Models::Acknowledgement, Models::Member) -> [Models::Placement, Models::MemberLines]
+      def since_baseline(id, acknowledgement, member)
+        placements = map_history(id).placements_since(acknowledgement.last_judged_commit, member.key,
+                                                      @member_maps.find(id).member(member.id))
+        baseline = acknowledgement.baseline(placements)
+        lines = @project.member_lines(member.locator, since: baseline.commit, then_locator: baseline.locator)
+        [baseline, acknowledgement.compared(lines)]
+      end
+
+      #: (String, String) -> [Models::Acknowledgement, Models::Member, String?]
+      def prepared(id, member_id)
+        member = Models::Member.new(@member_maps.find(id).member(member_id))
+        base = @history.base_commit(id, [@member_maps.file(id), member.path])
+        now = @project.locate(member.locator).fetch("sha256")
+        [Models::Acknowledgement.new(principle_id: id, member: member, record: @audit_records.find(id), base: base,
+                                     now_sha256: now), member, base]
+      end
+
+      #: (String, String) -> bot
+      def stale(id, member_id)
+        raise Error.new("stale_request", "This request no longer matches #{id}: the member, its baseline or the " \
+                                         "commit it was based on has changed since it was printed",
+                        "Start it again and answer the new request: " \
+                        "#{invocation.in_project("start-audit", id, options: ["--member", member_id])}")
+      end
+
+      #: () -> Views::AcknowledgementResult
+      def view
+        Views::AcknowledgementResult.new(invocation)
+      end
+    end
+  end
+end