principles 0.0.1

data/lib/principles/data/schemas/command-steps.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "command-steps.schema.json",
+  "title": "Command steps",
+  "description": "The steps each command runs, marked this tool's (cli) or the agent's, with the refusals each cli step can raise and where each step leads. Each command's --help and the workflow diagram are drawn from it.",
+  "type": "object",
+  "required": ["groups", "refusal_groups", "commands"],
+  "additionalProperties": false,
+  "$defs": {
+    "slug": { "type": "string", "pattern": "^[a-z]+(-[a-z]+)*$" },
+    "code": { "type": "string", "pattern": "^[a-z]+(_[a-z]+)*$" },
+    "prose": { "type": "string", "minLength": 1 },
+    "step": {
+      "type": "object",
+      "required": ["id", "actor", "does"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/slug" },
+        "actor": { "enum": ["cli", "agent"] },
+        "does": { "$ref": "#/$defs/prose" },
+        "refuses": { "type": "array", "items": { "$ref": "#/$defs/code" }, "minItems": 1, "uniqueItems": true },
+        "refuses_like": { "type": "array", "items": { "$ref": "#/$defs/slug" }, "minItems": 1, "uniqueItems": true },
+        "prompt": { "type": "string", "pattern": "^[a-z]+(-[a-z]+)+/[a-z]+(-[a-z]+)+$" },
+        "checks": { "$ref": "#/$defs/prose" },
+        "cannot_check": { "$ref": "#/$defs/prose" },
+        "answer_with": { "$ref": "#/$defs/slug" },
+        "answer_when": { "$ref": "#/$defs/prose" },
+        "answer_usage": { "$ref": "#/$defs/prose" },
+        "next": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "required": ["to", "when"],
+            "additionalProperties": false,
+            "properties": { "to": { "$ref": "#/$defs/slug" }, "when": { "$ref": "#/$defs/prose" } }
+          }
+        }
+      },
+      "if": { "properties": { "actor": { "const": "agent" } } },
+      "then": { "not": { "anyOf": [{ "required": ["refuses"] }, { "required": ["refuses_like"] }] } }
+    }
+  },
+  "properties": {
+    "groups": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "heading", "writes"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "$ref": "#/$defs/slug" }, "heading": { "$ref": "#/$defs/prose" }, "writes": { "$ref": "#/$defs/prose" }
+        }
+      }
+    },
+    "refusal_groups": {
+      "type": "object",
+      "required": ["any-command"],
+      "propertyNames": { "$ref": "#/$defs/slug" },
+      "additionalProperties": { "type": "array", "items": { "$ref": "#/$defs/code" }, "minItems": 1, "uniqueItems": true }
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "usage", "group", "options", "summary", "help", "steps"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "$ref": "#/$defs/slug" },
+          "usage": { "$ref": "#/$defs/prose" },
+          "group": { "$ref": "#/$defs/slug" },
+          "options": { "type": "array", "uniqueItems": true,
+                       "items": { "enum": ["description", "path", "section", "starting-at", "ending-at", "query", "role", "check", "file", "short", "session-start", "commits-after", "hook-event", "member", "when-files", "when-invoked", "always", "write-ups"] } },
+          "summary": { "$ref": "#/$defs/prose" },
+          "help": { "type": "string", "pattern": "^[a-z]+(-[a-z]+)+/[a-z]+(-[a-z]+)+$" },
+          "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/step" } }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "correction-answer-guide.schema.json",
+  "title": "Correction answer guide",
+  "description": "Example shapes the correction request shows, one disposition for each action, beside the template, which leaves each action null for the agent to choose (#708).",
+  "type": "object",
+  "required": ["disposition"],
+  "additionalProperties": false,
+  "properties": {
+    "disposition": {
+      "type": "object",
+      "required": ["fixed", "deferred", "accepted", "disagreed"],
+      "additionalProperties": false,
+      "properties": {
+        "fixed": {
+          "type": "object",
+          "required": ["action", "reason", "changed_members", "evidence", "reassessment", "recorded_at"],
+          "additionalProperties": false,
+          "properties": {
+            "action": { "const": "fixed" },
+            "reason": { "type": "string", "minLength": 1 },
+            "changed_members": { "type": "array", "items": { "type": "string" } },
+            "evidence": { "type": "array", "items": { "type": "object" } },
+            "reassessment": { "type": "string", "minLength": 1 },
+            "recorded_at": { "type": ["object", "null"] }
+          }
+        },
+        "deferred": {
+          "type": "object",
+          "required": ["action", "reason", "changed_members", "evidence", "recorded_at", "waits_on"],
+          "additionalProperties": false,
+          "properties": {
+            "action": { "const": "deferred" },
+            "reason": { "type": "string", "minLength": 1 },
+            "changed_members": { "type": "array", "items": { "type": "string" } },
+            "evidence": { "type": "array", "items": { "type": "object" } },
+            "recorded_at": { "type": ["object", "null"] },
+            "waits_on": { "type": "string", "minLength": 1 }
+          }
+        },
+        "accepted": {
+          "type": "object",
+          "required": ["action", "reason", "changed_members", "evidence", "recorded_at"],
+          "additionalProperties": false,
+          "properties": {
+            "action": { "const": "accepted" },
+            "reason": { "type": "string", "minLength": 1 },
+            "changed_members": { "type": "array", "items": { "type": "string" } },
+            "evidence": { "type": "array", "items": { "type": "object" } },
+            "recorded_at": { "type": ["object", "null"] }
+          }
+        },
+        "disagreed": {
+          "type": "object",
+          "required": ["action", "reason", "changed_members", "evidence", "recorded_at"],
+          "additionalProperties": false,
+          "properties": {
+            "action": { "const": "disagreed" },
+            "reason": { "type": "string", "minLength": 1 },
+            "changed_members": { "type": "array", "items": { "type": "string" } },
+            "evidence": { "type": "array", "items": { "type": "object" } },
+            "recorded_at": { "type": ["object", "null"] }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,306 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "correction-answer.schema.json",
+  "title": "Correction answer",
+  "description": "What an agent answers an audit's correction request with: the request's id and basis, one disposition per finding, any members its fixes moved (D28), and in each fix any members whose role or check it changed (D40). Fields this tool does not read are refused, to catch a misspelt field (D29). The rules across fields, such as one disposition per finding, stay in Models::CorrectionAnswer and Models::DeclaredMapChanges.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "request_id",
+    "basis",
+    "dispositions"
+  ],
+  "properties": {
+    "request_id": {
+      "type": "string"
+    },
+    "basis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base_commit",
+        "map_version",
+        "last_completed_revision",
+        "findings"
+      ],
+      "properties": {
+        "last_completed_revision": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "A digest of the last completed audit record when the correction request was printed, or null when there was none. Copy it as the template gives it."
+        },
+        "base_commit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "\\A[0-9a-f]{40}([0-9a-f]{24})?\\z",
+          "description": "A full commit sha, as start-audit gave it, or null outside git. This tool refuses anything else before running git."
+        },
+        "map_version": {
+          "type": "string"
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "member_ids"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "member_ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "problem": {
+                "type": "string",
+                "description": "The finding's problem as the assessment stated it, carried so the completed record keeps it (D34)."
+              },
+              "evidence": {
+                "type": "array",
+                "description": "The evidence the assessment raised the finding with, carried so the completed record keeps it (D64). Absent from a basis printed before it was kept.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "path"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    },
+                    "heading": {
+                      "type": "string"
+                    },
+                    "starting_at": {
+                      "type": "string"
+                    },
+                    "ending_at": {
+                      "type": "string"
+                    },
+                    "query": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "recent_decision_paths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The paths the assessment's recent decision cites as evidence, which the record does not keep, carried so the completed audit asks to commit those that differ from HEAD (#860). Copy it as the template gives it."
+        },
+        "entry_fields": {
+          "type": "object",
+          "description": "By member id, the fields the assessment reported for each member's record entry: its assessment (D49), its check's result (D30) and its accepted loading decision (#355), carried from the assessment so the completed record keeps them.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "check_result": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "command"
+                ],
+                "properties": {
+                  "command": {
+                    "type": "string"
+                  },
+                  "exit_status": {
+                    "type": "integer"
+                  },
+                  "not_run_reason": {
+                    "type": "string"
+                  },
+                  "review_basis": {
+                    "type": "string"
+                  },
+                  "review_basis_since": {
+                    "type": "string"
+                  }
+                }
+              },
+              "loading_accepted": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "reason",
+                  "loads"
+                ],
+                "properties": {
+                  "reason": {
+                    "type": "string"
+                  },
+                  "loads": {
+                    "type": "object"
+                  }
+                }
+              },
+              "assessment": {
+                "type": "object",
+                "description": "The member's assessment as the assessment gave it, with the grounds it was judged on, which the completed record keeps (D49)."
+              }
+            }
+          }
+        },
+        "prior_findings": {
+          "type": "object",
+          "description": "The assessment's decisions on prior findings, carried so the completed record keeps the ones that still hold (D35).",
+          "required": [
+            "kept",
+            "closed",
+            "inherited"
+          ],
+          "properties": {
+            "kept": {
+              "type": "array"
+            },
+            "closed": {
+              "type": "array"
+            },
+            "inherited": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    "dispositions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "finding_id",
+          "action",
+          "reason",
+          "evidence",
+          "changed_members"
+        ],
+        "properties": {
+          "finding_id": {
+            "type": "string"
+          },
+          "action": {
+            "type": ["string", "null"],
+            "description": "fixed, deferred, accepted or disagreed, which the agent chooses: the template leaves it null, and Models::CorrectionAnswer refuses null or any other value with invalid_disposition (#708)."
+          },
+          "reason": {
+            "type": "string"
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "path"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "path": {
+                  "type": "string"
+                },
+                "heading": {
+                  "type": "string"
+                },
+                "starting_at": {
+                  "type": "string"
+                },
+                "ending_at": {
+                  "type": "string"
+                },
+                "query": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "recorded_at": {
+            "x-type-refusal-advice": {
+              "keys": [
+                "heading",
+                "starting_at"
+              ],
+              "says": "plus starting_at (or heading) when the file holds more than this finding"
+            },
+            "type": [
+              "object",
+              "null"
+            ],
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "heading": {
+                "type": "string"
+              },
+              "starting_at": {
+                "type": "string"
+              },
+              "ending_at": {
+                "type": "string"
+              },
+              "query": {
+                "type": "string"
+              }
+            }
+          },
+          "changed_members": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "changed_map_entries": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "reassessment": {
+            "type": "string"
+          },
+          "waits_on": {
+            "type": ["string", "null"],
+            "description": "On a deferral, one line saying whom it waits on and to decide what; null on any disposition. Models::CorrectionAnswer refuses a value on another action, or one not one line (D52)."
+          }
+        }
+      }
+    },
+    "moved_members": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "from",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

data/lib/principles/data/schemas/member-map.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "member-map.schema.json",
+  "title": "Member map",
+  "description": "A principle's committed map, .principles/maps/ID.json: what the principle is, and each member that carries it. Fields this schema does not name are allowed, so an older version can read a map a newer one wrote (D29).",
+  "type": "object",
+  "required": ["description", "members"],
+  "properties": {
+    "format": { "type": "integer", "description": "The oldest map format that can read this map without losing what it says. Missing means 1. This tool writes it only when a member uses a field from a later format, and refuses a map whose format is newer than it knows." },
+    "description": { "type": "string", "minLength": 1 },
+    "activation": {
+      "type": "object",
+      "description": "When the principle's work is in hand, as the agent declared it with change-activation (D38): when files matching one of its globs are read or changed, when its work is invoked, or always. change-activation writes files only with when files; a hand-edited map is not yet checked for that.",
+      "required": ["when"],
+      "additionalProperties": false,
+      "properties": {
+        "when": { "enum": ["files", "invoked", "always"] },
+        "files": { "type": "array", "items": { "type": "string", "pattern": "\\S" } }
+      }
+    },
+    "members": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "role"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "section": { "type": "string", "minLength": 1 },
+          "starting_at": { "type": "string", "minLength": 1 },
+          "query": { "type": "string", "minLength": 1 },
+          "ending_at": { "type": "string", "minLength": 1 },
+          "role": { "type": "string", "minLength": 1 },
+          "key": { "type": "string", "minLength": 1, "description": "What the member is known by across moves, which its audit record files its hash under. Absent, it is the member's id. move-member stores the old id here on a member's first move, and add-member gives a member a key of its own when its id is the key of a member that moved away." },
+          "check": { "type": "string", "minLength": 1, "description": "The command that enforces this member, which an audit asks the agent to run and report. This tool never runs it (D30)." }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "repointing-answer.schema.json",
+  "title": "Repointing answer",
+  "description": "What an agent answers a repoint of a principle's open findings' write-ups with (D59): the request's id and basis, then for each finding a new recorded_at, or null to leave it, and a one-line reason. Fields this tool does not read are refused (D29). Models::Repoint locates each new pointer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["request_id", "basis", "repoints"],
+  "properties": {
+    "request_id": { "type": "string" },
+    "basis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["revision"],
+      "properties": {
+        "revision": { "type": ["string", "null"] }
+      }
+    },
+    "repoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["finding_id", "recorded_at", "reason"],
+        "properties": {
+          "finding_id": { "type": "string", "minLength": 1 },
+          "recorded_at": {
+            "type": ["object", "null"],
+            "required": ["path"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string" },
+              "heading": { "type": "string" },
+              "starting_at": { "type": "string" },
+              "ending_at": { "type": "string" },
+              "query": { "type": "string" }
+            }
+          },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  }
+}

data/lib/principles/error.rb

@@ -0,0 +1,102 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # A refusal: a stable code, what went wrong and how to repair it, printed as one JSON object.
+  class Error < StandardError
+    # Stands in a model's repair for the running executable, which only the controller knows. The
+    # controller puts the executable in with #naming before the refusal is printed.
+    EXECUTABLE = "{executable}"
+
+    # A command a refusal's repair names for values it holds, such as a member id, left unquoted, since a model
+    # cannot quote: the controller prints it through Views::Invocation, the one owner of shell quoting, after its
+    # purpose and a colon, on a line of its own (D56, #729). options are flags with their values, quoted the same
+    # way; usage is this tool's own placeholder text, such as "--role ROLE", left for the agent to fill.
+    class RepairCommand
+      #: String
+      attr_reader :purpose, :command
+      #: Array[String]
+      attr_reader :values, :options
+      #: String?
+      attr_reader :usage
+
+      #: (purpose: String, command: String, values: Array[String], ?options: Array[String], ?usage: String?) -> void
+      def initialize(purpose:, command:, values:, options: [], usage: nil)
+        @purpose = purpose
+        @command = command
+        @values = values
+        @options = options
+        @usage = usage
+        freeze
+      end
+    end
+
+    #: Hash[String, untyped]
+    attr_reader :payload
+
+    # fields are the failing JSON pointers of a malformed file or answer, each with what is wrong there (D29).
+    #: (String, String, String, ?String?, ?fields: Array[Hash[String, String]]?) -> void
+    def initialize(code, message, repair, path = nil, fields: nil)
+      super(message)
+      @payload = { "status" => "refused", "code" => code, "message" => message,
+                   "repair" => repair } #: Hash[String, untyped]
+      @payload["path"] = path if path
+      @payload["fields"] = fields if fields
+      @commands = [] #: Array[RepairCommand]
+    end
+
+    # The repair's commands still to print, which follow its text.
+    #: Array[RepairCommand]
+    attr_reader :commands
+
+    # This refusal with commands, which its repair names after its text, for the controller to print.
+    #: (Array[RepairCommand]) -> Error
+    def ending_with(commands)
+      @commands = commands
+      self
+    end
+
+    # This refusal with more of what it is about, such as the members it lists, each with its own refusal.
+    #: (Hash[String, untyped]) -> Error
+    def including(details)
+      @payload.merge!(details)
+      self
+    end
+
+    # This refusal with each of its commands printed by the block, after its purpose, a line each after the repair's
+    # text (D56).
+    #: () { (RepairCommand) -> String } -> Error
+    def printing_commands(&)
+      return self if @commands.empty?
+
+      lines = @commands.map { |command| "#{command.purpose}: #{yield(command)}" }
+      repaired([payload.fetch("repair"), *lines].reject(&:empty?).join("\n"), [])
+    end
+
+    # This refusal, when it names under did_you_mean the one mapped id an id it was given nearly matches, with its
+    # repair led by the command the block prints for that id; this tool never runs a command on the near miss
+    # itself (D56, #729). Otherwise this refusal as it is.
+    #: () { (String) -> String } -> Error
+    def rerun_with_near_miss(&)
+      mapped = payload["did_you_mean"] or return self
+      repaired("To run it with that id: #{yield(mapped)}\n#{payload.fetch("repair")}")
+    end
+
+    # This refusal with executable in place of each EXECUTABLE its repair names.
+    #: (String) -> Error
+    def naming(executable)
+      repaired(payload.fetch("repair").gsub(EXECUTABLE, executable))
+    end
+
+    private
+
+    # This refusal with repair in place of its own, keeping everything else.
+    #: (String, ?Array[RepairCommand]) -> Error
+    def repaired(repair, commands = @commands)
+      copy = Error.new(payload.fetch("code"), payload.fetch("message"), repair).including(payload.except("repair"))
+                  .ending_with(commands)
+      copy.set_backtrace(backtrace || [])
+      copy
+    end
+  end
+end