principles 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. checksums.yaml +4 -4
  2. data/lib/principles/cli.rb +9 -0
  3. data/lib/principles/command_line.rb +22 -5
  4. data/lib/principles/command_routes.rb +2 -2
  5. data/lib/principles/controllers/acknowledgement.rb +79 -102
  6. data/lib/principles/controllers/answer.rb +7 -6
  7. data/lib/principles/controllers/assessment.rb +13 -21
  8. data/lib/principles/controllers/audit.rb +24 -4
  9. data/lib/principles/controllers/audit_completion.rb +7 -3
  10. data/lib/principles/controllers/correction.rb +13 -6
  11. data/lib/principles/controllers/full_audit_request.rb +7 -2
  12. data/lib/principles/controllers/member_acknowledgement.rb +137 -0
  13. data/lib/principles/controllers/member_problems_report.rb +31 -23
  14. data/lib/principles/data/command-steps.json +9 -9
  15. data/lib/principles/data/schemas/acknowledgement-answer.schema.json +3 -2
  16. data/lib/principles/data/schemas/acknowledgements-answer.schema.json +88 -0
  17. data/lib/principles/data/schemas/assessment-answer.schema.json +15 -1
  18. data/lib/principles/data/schemas/command-steps.schema.json +1 -1
  19. data/lib/principles/data/schemas/correction-answer.schema.json +6 -54
  20. data/lib/principles/invocation_options.rb +5 -4
  21. data/lib/principles/list_open_findings_options.rb +23 -0
  22. data/lib/principles/models/acknowledged_check.rb +94 -0
  23. data/lib/principles/models/acknowledgement.rb +18 -36
  24. data/lib/principles/models/acknowledgement_left_as_printed.rb +25 -4
  25. data/lib/principles/models/acknowledgements.rb +99 -0
  26. data/lib/principles/models/answered_time.rb +9 -0
  27. data/lib/principles/models/assessment_report.rb +13 -13
  28. data/lib/principles/models/audit.rb +17 -4
  29. data/lib/principles/models/audit_record.rb +5 -0
  30. data/lib/principles/models/correction_basis.rb +14 -5
  31. data/lib/principles/models/list_member_problems_check.rb +80 -0
  32. data/lib/principles/models/listed_members.rb +49 -0
  33. data/lib/principles/models/loading_decision.rb +17 -8
  34. data/lib/principles/models/loads_to_check.rb +0 -1
  35. data/lib/principles/models/member_assessments.rb +11 -2
  36. data/lib/principles/models/member_problems.rb +9 -5
  37. data/lib/principles/models/member_sighting.rb +5 -8
  38. data/lib/principles/models/problem_report.rb +19 -4
  39. data/lib/principles/models/project.rb +5 -4
  40. data/lib/principles/models/reported_check.rb +14 -11
  41. data/lib/principles/models/request_id.rb +1 -1
  42. data/lib/principles/models/sent_answer.rb +29 -9
  43. data/lib/principles/positional_arguments.rb +3 -2
  44. data/lib/principles/session_start_options.rb +3 -3
  45. data/lib/principles/start_audit_options.rb +10 -2
  46. data/lib/principles/version.rb +2 -2
  47. data/lib/principles/views/acknowledgement_result.rb +46 -12
  48. data/lib/principles/views/assessed_members.rb +26 -5
  49. data/lib/principles/views/assessment_request.rb +22 -3
  50. data/lib/principles/views/audit_result.rb +9 -1
  51. data/lib/principles/views/check_result_template.rb +18 -17
  52. data/lib/principles/views/correction_request.rb +6 -9
  53. data/lib/principles/views/findings_result.rb +21 -0
  54. data/lib/principles/views/invocation.rb +19 -4
  55. data/lib/principles/views/loads_to_check_result.rb +3 -2
  56. data/lib/principles/views/member_row.rb +61 -0
  57. data/lib/principles/views/members_a_commit_changed.rb +2 -1
  58. data/lib/principles/views/members_with_no_baseline.rb +8 -1
  59. data/lib/principles/views/one_member_check_result_template.rb +21 -9
  60. data/lib/principles/views/open_findings_line.rb +2 -1
  61. data/lib/principles/views/problem_lines.rb +48 -45
  62. data/lib/principles/views/problem_result.rb +55 -26
  63. data/lib/principles/views/prompts/acknowledge-a-change/report-the-exit-status-its-own-listing-gives.md +3 -0
  64. data/lib/principles/views/prompts/acknowledge-a-change/say-whether-each-change-keeps-its-meaning.md +8 -0
  65. data/lib/principles/views/prompts/assess-every-member/decide-each-member-loading.md +2 -1
  66. data/lib/principles/views/prompts/assess-every-member/run-the-check-then-report-it.md +2 -2
  67. data/lib/principles/views/prompts/assess-every-member/run-the-reviewed-check-and-say-what-its-review-rested-on.md +5 -3
  68. data/lib/principles/views/prompts/learn-what-a-command-does/every-command-and-how-they-chain.md +1 -2
  69. data/lib/principles/views/prompts/learn-what-a-command-does/list-member-problems.md +15 -15
  70. data/lib/principles/views/prompts/learn-what-a-command-does/list-open-findings.md +65 -61
  71. data/lib/principles/views/prompts/learn-what-a-command-does/show-answer-check.md +7 -7
  72. data/lib/principles/views/prompts/learn-what-a-command-does/start-audit.md +8 -8
  73. data/lib/principles/views/prompts/learn-what-a-command-does/submit-answer.md +37 -37
  74. data/lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md +1 -1
  75. data/lib/principles/views/prompts/start-a-session/every-loaded-line-costs-every-session.md +1 -0
  76. data/lib/principles/views/prompts/start-a-session/start-with-the-principles-skill.md +1 -0
  77. metadata +13 -1
@@ -7,25 +7,25 @@ require_relative "prompts"
7
7
  module Principles
8
8
  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
9
9
  module Views
10
- # The check_result a checked member's assessment template starts with: its command, an exit_status placeholder
11
- # that says what to do before replacing it with the run's status, and not_run_reason, the alternative, as a
12
- # placeholder an answer leaves as printed when it reports a run (#993). A check no audit has run, or one changed
13
- # since, is reviewed before it runs (#227), so it also gives review_basis to fill (D63), and any hidden character
14
- # it holds is named where that decision is made (#260).
10
+ # The check_result a checked member's assessment template starts with: its command, a short exit_status
11
+ # placeholder where the run's status goes, and not_run_reason, the alternative, as a placeholder an answer leaves
12
+ # as printed when it reports a run (#993), with its instruction, what to do before replacing it (#1191). A check
13
+ # no audit has run, or one changed since, is reviewed before it runs (#227), so it also gives review_basis to fill
14
+ # (D63), and any hidden character it holds is named where that decision is made (#260).
15
15
  class CheckResultTemplate
16
16
  # The template for the checked member a request lists as entry, with its check, how that stands to the last
17
17
  # audit's and any hidden characters in it; nil for a member without a check.
18
18
  #: (Hash[String, untyped], reviewed_placeholders: Hash[String, String],
19
- #| unchanged_placeholders: Hash[String, String]) -> Hash[String, untyped]?
19
+ #| unchanged_placeholders: Hash[String, String]) -> CheckResultTemplate?
20
20
  def self.for(entry, reviewed_placeholders:, unchanged_placeholders:)
21
21
  check = entry["check"] or return
22
22
  new(check, entry["check_since_last_audit"], entry.fetch("check_hidden_characters", []),
23
- reviewed_placeholders:, unchanged_placeholders:).to_h
23
+ reviewed_placeholders:, unchanged_placeholders:)
24
24
  end
25
25
 
26
- # reviewed_placeholders gives the text of not_run_reason and review_basis, which an answer leaves as printed to
27
- # give neither, for a check reviewed before it runs; unchanged_placeholders gives it for one the last audit ran,
28
- # whose review_basis left as printed keeps the line that audit kept (#1010).
26
+ # reviewed_placeholders gives the text of exit_status, and of not_run_reason and review_basis, which an answer
27
+ # leaves as printed to give neither, for a check reviewed before it runs; unchanged_placeholders gives it for one
28
+ # the last audit ran, whose review_basis left as printed keeps the line that audit kept (#1010).
29
29
  #: (String, Hash[String, untyped]?, ?Array[String], reviewed_placeholders: Hash[String, String],
30
30
  #| unchanged_placeholders: Hash[String, String]) -> void
31
31
  def initialize(check, since_last_audit, hidden_characters = [], reviewed_placeholders:, unchanged_placeholders:)
@@ -39,20 +39,21 @@ module Principles
39
39
 
40
40
  #: () -> Hash[String, untyped]
41
41
  def to_h
42
- { "command" => @check, "exit_status" => [@notes.hidden_characters, run_and_report].compact.join(" "),
42
+ { "command" => @check, "exit_status" => @placeholders.fetch("exit_status"),
43
43
  "not_run_reason" => @placeholders.fetch("not_run_reason"),
44
44
  "review_basis" => @placeholders.fetch("review_basis") }
45
45
  end
46
46
 
47
- private
48
-
49
- # What to do before replacing exit_status, then that a named check runs at every full audit, which holds for
50
- # each status.
47
+ # What to do before replacing exit_status, with what the check hides, then that a named check runs at every
48
+ # full audit, which holds for each status.
51
49
  #: () -> String
52
- def run_and_report
53
- [*steps, Prompts.text("assess-every-member/run-a-named-check-at-every-full-audit")].join(" ")
50
+ def instruction
51
+ [@notes.hidden_characters, *steps, Prompts.text("assess-every-member/run-a-named-check-at-every-full-audit")]
52
+ .compact.join(" ")
54
53
  end
55
54
 
55
+ private
56
+
56
57
  # An unchanged check is run and reported, keeping any line its last review rested on; a new or changed one is
57
58
  # reviewed first, its review introduced by what it is, then run and reported with what that review rested on,
58
59
  # as both ask the same way.
@@ -77,18 +77,15 @@ module Principles
77
77
  end
78
78
 
79
79
  # What submitting the assessment stored, and what submitting it again would do, so an assessment submitted
80
- # twice plainly replaced nothing: in git, where the audit has a base commit, nothing; outside git, the open
81
- # record, which keeps what the audit began from.
80
+ # twice plainly replaced nothing: the open record, which keeps the assessment and, outside git, what the audit
81
+ # began from, and which in git is never committed, since the correction completes it (D87).
82
82
  #: () -> String
83
83
  def stored
84
- again = "Submitting the same assessment again prints this same request"
85
- unless @head.based_on_a_commit?
86
- return "This audit's open record, listed under wrote when it was first written, keeps what the audit " \
87
- "began from. #{again} and leaves that record as it is."
88
- end
84
+ kept = "This audit's open record, listed under wrote when it was first written, keeps your assessment"
85
+ again = "Submitting the same assessment again prints this same request and leaves that record as it is."
86
+ return "#{kept} and what the audit began from. #{again}" unless @head.based_on_a_commit?
89
87
 
90
- "Nothing is stored yet: this request was computed from your assessment and the project. #{again} and " \
91
- "replaces nothing; the audit record is written when the audit completes."
88
+ "#{kept} until this correction completes the audit; do not commit it. #{again}"
92
89
  end
93
90
  end
94
91
  end
@@ -2,6 +2,8 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  require_relative "invocation"
5
+ require_relative "problem_lines"
6
+ require_relative "visible_text"
5
7
 
6
8
  module Principles
7
9
  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
@@ -27,8 +29,27 @@ module Principles
27
29
  { "findings" => findings, "scope" => SCOPE, "next_action" => next_action(findings) }
28
30
  end
29
31
 
32
+ # list-open-findings --lines: each finding on a line, its principle, id and whom it waits on, so the agent can
33
+ # see which to raise without a script over the list (#1156). Free text is escaped, and its line breaks read as
34
+ # spaces, so each finding stays on its own line (#227).
35
+ #: (Array[Hash[String, untyped]]) -> Lines
36
+ def lines(findings)
37
+ text = findings.map { |finding| "#{line(finding)}\n" }.join
38
+ Lines.new(stdout: findings.empty? ? "#{NONE_OPEN}\n" : text, stderr: "", status: 0)
39
+ end
40
+
30
41
  private
31
42
 
43
+ #: (Hash[String, untyped]) -> String
44
+ def line(finding)
45
+ waits_on = finding["waits_on"]
46
+ waits = waits_on ? "waits on: #{one_line(waits_on)}" : "waits on no one named"
47
+ "#{finding.fetch("principle")}\t#{one_line(finding.fetch("finding_id"))}\t#{waits}"
48
+ end
49
+
50
+ #: (String) -> String
51
+ def one_line(text) = VisibleText.new(text.gsub(/\s+/, " ")).to_s
52
+
32
53
  #: (Array[Hash[String, untyped]]) -> String
33
54
  def next_action(findings)
34
55
  return NONE_OPEN if findings.empty?
@@ -15,13 +15,24 @@ module Principles
15
15
  #: String
16
16
  attr_reader :project
17
17
 
18
- #: (executable: String, project: String) -> void
19
- def initialize(executable:, project:)
18
+ # named says whether each command names the project; without_project leaves it out.
19
+ #: (executable: String, project: String, ?named: bool) -> void
20
+ def initialize(executable:, project:, named: true)
20
21
  @executable = executable
21
22
  @project = project
23
+ @named = named
22
24
  freeze
23
25
  end
24
26
 
27
+ # The same invocation, its commands leaving out --project, for output that names the project once and whose
28
+ # commands run from there, as list-member-problems --short's stderr does (#1263).
29
+ #: () -> Invocation
30
+ def without_project = Invocation.new(executable: @executable, project: @project, named: false)
31
+
32
+ # The project as a shell word, as --project gives it.
33
+ #: () -> String
34
+ def project_word = shell_word(@project)
35
+
25
36
  # A command to run in this project, which it names right after the executable, as model repairs do (#580).
26
37
  # Each value is shell-quoted, because ids, paths and headings come from project files that anyone may have
27
38
  # written (#227). options are flags with their values, such as
@@ -46,10 +57,10 @@ module Principles
46
57
  flags = options.map { |value| shell_word(value) }
47
58
  words = values.map { |value| shell_word(value) }
48
59
  if values.any? { |value| value.start_with?("-") }
49
- return [@executable, project_option, command, *flags, usage, "--", *words].compact.join(" ")
60
+ return [@executable, named_project, command, *flags, usage, "--", *words].compact.join(" ")
50
61
  end
51
62
 
52
- [@executable, project_option, command, *words, *flags, usage].compact.join(" ")
63
+ [@executable, named_project, command, *words, *flags, usage].compact.join(" ")
53
64
  end
54
65
 
55
66
  #: () -> String
@@ -59,6 +70,10 @@ module Principles
59
70
 
60
71
  private
61
72
 
73
+ # --project and the project, or nil when the commands leave it out.
74
+ #: () -> String?
75
+ def named_project = @named ? project_option : nil
76
+
62
77
  #: (String) -> String
63
78
  def shell_word(value) = ShellWord.new(value).to_s
64
79
  end
@@ -11,8 +11,9 @@ module Principles
11
11
  # How a full audit's request shows the members to check against the principle's activation (#355 slice 3).
12
12
  class LoadsToCheckResult
13
13
  # What a decision may be, as the answer printed alone says where it is written (#746).
14
- DECISION = "accepted, with reason saying why the member loads as it does; if the activation is wrong " \
15
- "instead, change it and start the audit again" #: String
14
+ DECISION = "accepted, with reason saying why the member loads as it does; kept, with no reason, where " \
15
+ "last_accepted.since_accepted is unchanged; if the activation is wrong instead, change it and " \
16
+ "start the audit again" #: String
16
17
 
17
18
  # listed is the members to check, nil when there are none, and id the principle they belong to; placeholders
18
19
  # is the text the template alone prints in each field of a decision beside it, which left is not given (#994).
@@ -0,0 +1,61 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ require_relative "visible_text"
5
+
6
+ module Principles
7
+ # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
8
+ module Views
9
+ # One changed member as a line of tab-separated fields, each written through VisibleText: its principle, id,
10
+ # newest commit that changed it (or "uncommitted"), that commit's subject, and what it was compared with:
11
+ # "audit" or "mapping_commit", then "waiting_on_an_upgrade" for one compared with hashes a later copy wrote.
12
+ # The after-commit hook prints it (D73), and list-member-problems --short its short form, without the subject.
13
+ class MemberRow
14
+ # member is one entry of list-member-problems' "members", with its "history".
15
+ #: (Hash[String, untyped]) -> void
16
+ def initialize(member)
17
+ @member = member
18
+ freeze
19
+ end
20
+
21
+ #: () -> String
22
+ def to_s
23
+ history = @member.fetch("history", {})
24
+ newest = history.fetch("commits", []).first
25
+ joined([*head, newest ? described(newest, history) : "not committed yet", *tail])
26
+ end
27
+
28
+ # The row without the commit's subject, which repeats on every row one commit changed and which
29
+ # list-member-problems' JSON keeps (#1263).
30
+ #: () -> String
31
+ def short = joined([*head, *tail])
32
+
33
+ private
34
+
35
+ # The principle, id and newest commit that changed the member, or "uncommitted".
36
+ #: () -> Array[String]
37
+ def head
38
+ newest = @member.fetch("history", {}).fetch("commits", []).first
39
+ [@member.fetch("principle"), @member.fetch("id"), newest ? newest.fetch("commit") : "uncommitted"]
40
+ end
41
+
42
+ # What the member was compared with, and whether its audit waits on an upgrade.
43
+ #: () -> Array[String]
44
+ def tail = [@member.dig("since", "baseline").to_s, *("waiting_on_an_upgrade" if @member["waiting_on_an_upgrade"])]
45
+
46
+ #: (Array[String]) -> String
47
+ def joined(fields) = fields.map { |field| VisibleText.new(field).to_s }.join("\t")
48
+
49
+ # The newest commit's subject, with how many earlier commits changed the member, and whether it changed
50
+ # again on disk.
51
+ #: (Hash[String, untyped], Hash[String, untyped]) -> String
52
+ def described(newest, history)
53
+ earlier = history.fetch("commits").length - 1
54
+ more = history.dig("stopped_at", "reason") == "limit" ? " or more" : ""
55
+ notes = [("+#{earlier}#{more} earlier" if earlier.positive?),
56
+ ("also uncommitted" if history["uncommitted"])].compact
57
+ notes.empty? ? newest.fetch("subject") : "#{newest.fetch("subject")} (#{notes.join("; ")})"
58
+ end
59
+ end
60
+ end
61
+ end
@@ -3,6 +3,7 @@
3
3
 
4
4
  require "json"
5
5
  require_relative "invocation"
6
+ require_relative "member_row"
6
7
  require_relative "problem_lines"
7
8
  require_relative "prompts"
8
9
  require_relative "record_waiting_on_an_upgrade"
@@ -70,7 +71,7 @@ module Principles
70
71
  end
71
72
 
72
73
  #: (Array[Hash[String, untyped]]) -> Array[String]
73
- def rows(members) = members.map { |member| ProblemLines.new(@invocation).row(member) }
74
+ def rows(members) = members.map { MemberRow.new(it).to_s }
74
75
 
75
76
  # The line saying how many other changed members list-member-problems still lists, or none when it lists none.
76
77
  #: (Integer) -> Array[String]
@@ -27,17 +27,24 @@ module Principles
27
27
  "#{one? ? "it" : "they"} changed is not yet known.#{remedy}"
28
28
  end
29
29
 
30
+ # Whether its remedy names the audit command, as it does unless committing files gives the baseline (#1279).
31
+ #: () -> bool
32
+ def names_a_command? = !committing?
33
+
30
34
  private
31
35
 
32
36
  #: () -> bool
33
37
  def one? = @count == 1
34
38
 
39
+ #: () -> bool
40
+ def committing? = @because == "not_committed" && !@files.empty?
41
+
35
42
  # What gives the members a baseline: a completed audit outside git, or in git committing the files that
36
43
  # differ from HEAD, or an audit again when none does, since every file is committed already (#710 X3). The
37
44
  # audit command starts a line of its own, after its purpose.
38
45
  #: () -> String
39
46
  def remedy
40
- return " Committing #{ProseList.new(@files)} #{gives}." if @because == "not_committed" && !@files.empty?
47
+ return " Committing #{ProseList.new(@files)} #{gives}." if committing?
41
48
 
42
49
  "#{all_committed if @because == "not_committed"}\nA completed audit #{gives}: #{@audit}"
43
50
  end
@@ -17,30 +17,42 @@ module Principles
17
17
  # The template for the checked member a request lists as entry, with how its check stands to the last audit's
18
18
  # and any hidden characters in it; nil for a member without a check. exit_status is the placeholder it prints
19
19
  # there, its one field: the answer reads the command as the request printed it and keeps the line the last
20
- # review rested on, so neither is printed to fill (#1166, #1170).
21
- #: (Hash[String, untyped], exit_status: String) -> OneMemberCheckResultTemplate?
22
- def self.for(entry, exit_status:)
20
+ # review rested on, so neither is printed to fill (#1166, #1170). own_listing says the check is this tool's own
21
+ # list-member-problems, which exits 3 while it lists the member (#1276).
22
+ #: (Hash[String, untyped], exit_status: String, ?own_listing: bool) -> OneMemberCheckResultTemplate?
23
+ def self.for(entry, exit_status:, own_listing: false)
23
24
  return unless entry["check"]
24
25
 
25
- new(CheckNotes.new(entry["check_since_last_audit"], entry.fetch("check_hidden_characters", [])), exit_status:)
26
+ new(CheckNotes.new(entry["check_since_last_audit"], entry.fetch("check_hidden_characters", [])), exit_status:,
27
+ own_listing:)
26
28
  end
27
29
 
28
- #: (CheckNotes, exit_status: String) -> void
29
- def initialize(notes, exit_status:)
30
+ #: (CheckNotes, exit_status: String, ?own_listing: bool) -> void
31
+ def initialize(notes, exit_status:, own_listing: false)
30
32
  @notes = notes
31
33
  @exit_status = exit_status
34
+ @own_listing = own_listing
32
35
  freeze
33
36
  end
34
37
 
35
- # The check_result to fill.
38
+ # The check_result to fill, with an empty listed_members slot for this tool's own list-member-problems, whose
39
+ # instruction says what goes there (#1278).
36
40
  #: () -> Hash[String, untyped]
37
- def to_h = { "exit_status" => @exit_status }
41
+ def to_h = { "exit_status" => @exit_status, **(@own_listing ? { "listed_members" => [] } : {}) }
38
42
 
39
43
  # What to do before filling exit_status, which the request gives as context.check_instruction.
40
44
  #: () -> String
41
45
  def instruction
42
46
  [@notes.hidden_characters, Prompts.text("acknowledge-a-change/run-the-check-and-report-it-passing"),
43
- *@notes.kept_review].compact.join(" ")
47
+ *@notes.kept_review, own_listing].compact.join(" ")
48
+ end
49
+
50
+ private
51
+
52
+ # What to report for this tool's own list-member-problems, which exits 3 while it lists the member (#1276).
53
+ #: () -> String?
54
+ def own_listing
55
+ Prompts.text("acknowledge-a-change/report-the-exit-status-its-own-listing-gives") if @own_listing
44
56
  end
45
57
  end
46
58
  end
@@ -88,7 +88,8 @@ module Principles
88
88
  findings: "#{how_long(waiting)} (#{named(waiting)})",
89
89
  without_waits_on: without_waits_on(count, waiting.fetch("without_waits_on", 0)),
90
90
  write_ups: write_ups(not_found),
91
- them: them, each: each, command: @invocation.in_project("list-open-findings"))
91
+ them: them, each: each,
92
+ command: @invocation.in_project("list-open-findings", options: ["--lines"]))
92
93
  end
93
94
 
94
95
  # A resumed session's line: its conversation already holds the line printed when that context began, so this
@@ -1,8 +1,10 @@
1
1
  # typed: strict
2
2
  # frozen_string_literal: true
3
3
 
4
+ require_relative "member_row"
4
5
  require_relative "visible_text"
5
6
  require_relative "invocation"
7
+ require_relative "prompts"
6
8
 
7
9
  module Principles
8
10
  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
@@ -11,15 +13,13 @@ module Principles
11
13
  Lines = Struct.new(:stdout, :stderr, :status, keyword_init: true)
12
14
 
13
15
  # list-member-problems --short, for a commit hook or heartbeat that acts on an exit status and short lines
14
- # alone (#291): one tab-separated line per changed member on stdout, exit 3 when a member an audit assessed
15
- # changed and 4 when only members no audit assessed were edited (D44), and on stderr what to do next and
16
+ # alone (#291): one tab-separated line per changed member on stdout, then one per principle counting its members
17
+ # no audit has assessed (#1254), exit 3 when there is any line to act on, and on stderr what to do next and
16
18
  # anything an empty stdout would hide.
17
19
  class ProblemLines
18
- # The exit status that says a member's own text changed since an audit or acknowledgement assessed it; 1 and
19
- # 2 already mean refused and usage error.
20
+ # The exit status that says a member's own text changed since an audit or acknowledgement assessed it, or that
21
+ # no audit has assessed a member; 1 and 2 already mean refused and usage error.
20
22
  CHANGED = 3
21
- # The exit status that says only members no audit has assessed were edited since they were mapped.
22
- UNASSESSED_ONLY = 4
23
23
 
24
24
  NO_MAPS = "No principle is mapped in this project, so there is nothing to check."
25
25
 
@@ -30,60 +30,63 @@ module Principles
30
30
  end
31
31
 
32
32
  # report is list-member-problems' JSON result: its "members", "counts" and "next_action".
33
- # assessed_change says whether a member an audit assessed changed, and unassessed_change whether a member no
34
- # audit assessed was edited since mapping; the model decides both, so the status follows from them alone.
35
- #: (Hash[String, untyped], nothing_changed: String, assessed_change: bool, unassessed_change: bool) -> Lines
36
- def short(report, nothing_changed:, assessed_change:, unassessed_change:)
37
- members = report.fetch("members")
38
- Lines.new(stdout: members.map { |member| "#{row(member)}\n" }.join,
39
- stderr: notes(report, nothing_changed).map { |note| "#{note}\n" }.join,
40
- status: status(assessed_change, unassessed_change))
33
+ # assessed_change says whether a member an audit assessed changed, and never_assessed counts, by principle,
34
+ # the members no audit has assessed; the model decides both, so the status follows from them alone.
35
+ # names_a_command says whether next_action names one, as ProblemResult says (#1279).
36
+ #: (Hash[String, untyped], nothing_changed: String, assessed_change: bool,
37
+ #| never_assessed: Hash[String, Integer], names_a_command: bool) -> Lines
38
+ def short(report, nothing_changed:, assessed_change:, never_assessed:, names_a_command:)
39
+ rows = report.fetch("members").map { MemberRow.new(it).short } +
40
+ never_assessed.map { |id, count| counted(id, count) }
41
+ Lines.new(stdout: rows.map { "#{it}\n" }.join,
42
+ stderr: notes(report, nothing_changed, names_a_command).map { |note| "#{note}\n" }.join,
43
+ status: assessed_change || !never_assessed.empty? ? CHANGED : 0)
41
44
  end
42
45
 
43
- # One changed member's row, its fields tab-separated: its principle, id, newest commit that changed it (or
44
- # "uncommitted"), that commit's subject, and what it was compared with: "audit" or "mapping_commit". The
45
- # after-commit hook prints the same row for each member a commit changed (D73).
46
- #: (Hash[String, untyped]) -> String
47
- def row(member)
48
- history = member.fetch("history", {})
49
- newest = history.fetch("commits", []).first
50
- fields = [member.fetch("principle"), member.fetch("id"), newest ? newest.fetch("commit") : "uncommitted",
51
- newest ? described(newest, history) : "not committed yet", member.dig("since", "baseline"),
52
- *("waiting_on_an_upgrade" if member["waiting_on_an_upgrade"])]
53
- fields.map { |field| VisibleText.new(field.to_s).to_s }.join("\t")
46
+ # short's lines for a session-start hook (#1261): on stdout, first the context universal, unless source is
47
+ # resume, whose conversation holds it already (#1260), then one line for each principle with a changed member an
48
+ # audit or acknowledgement assessed, counting them, with the command that lists them, from changed, in place of
49
+ # the rows and never-assessed counts, which an always-loaded carrier cannot afford, then the principles skill as
50
+ # where to start, which the hook printed before (#986, #1260); stderr and the status kept. Its command leaves
51
+ # out --project, as the hook's own commands do, since a session runs in its project.
52
+ #: (Lines, changed: Hash[String, Integer], source: String) -> Lines
53
+ def at_session_start(short, changed:, source:)
54
+ counts = changed.map { |id, count| changed_line(id, count) }
55
+ stdout = [*(Prompts.text("start-a-session/every-loaded-line-costs-every-session") unless source == "resume"),
56
+ *counts, *(Prompts.text("start-a-session/start-with-the-principles-skill") unless counts.empty?)]
57
+ Lines.new(stdout: stdout.map { "#{it}\n" }.join, stderr: short.stderr, status: short.status)
54
58
  end
55
59
 
56
60
  private
57
61
 
58
- #: (bool, bool) -> Integer
59
- def status(assessed_change, unassessed_change)
60
- return CHANGED if assessed_change
61
-
62
- unassessed_change ? UNASSESSED_ONLY : 0
62
+ # The session-start line counting principle id's changed audited members, with the command that lists them.
63
+ #: (String, Integer) -> String
64
+ def changed_line(id, count)
65
+ "#{count} audited member#{"s" unless count == 1} of #{VisibleText.new(id)} changed: " \
66
+ "#{@invocation.without_project.in_project("list-member-problems", id, options: ["--short"])}"
63
67
  end
64
68
 
65
- # The newest commit's subject, with how many earlier commits changed the member, and whether it changed
66
- # again on disk.
67
- #: (Hash[String, untyped], Hash[String, untyped]) -> String
68
- def described(newest, history)
69
- earlier = history.fetch("commits").length - 1
70
- more = history.dig("stopped_at", "reason") == "limit" ? " or more" : ""
71
- notes = [("+#{earlier}#{more} earlier" if earlier.positive?),
72
- ("also uncommitted" if history["uncommitted"])].compact
73
- notes.empty? ? newest.fetch("subject") : "#{newest.fetch("subject")} (#{notes.join("; ")})"
74
- end
69
+ # The line counting principle id's members no audit has assessed, which a reader tells from a member's row by
70
+ # its two fields (#1254).
71
+ #: (String, Integer) -> String
72
+ def counted(id, count) = "#{VisibleText.new(id)}\t#{count} never assessed"
75
73
 
76
74
  # What the agent does next, and what an empty stdout would otherwise hide: no maps, or, in next_action,
77
75
  # each principle's members with no baseline to compare with and what gives them one (#564), and each
78
76
  # principle waiting on an upgrade, whose members are not counted, so they leave counts empty (D85, V8).
79
- #: (Hash[String, untyped], String) -> Array[String]
80
- def notes(report, nothing_changed)
77
+ #: (Hash[String, untyped], String, bool) -> Array[String]
78
+ def notes(report, nothing_changed, names_a_command)
81
79
  no_maps = report.fetch("counts").empty? && !report.key?("empty_maps") &&
82
80
  !report.key?("records_waiting_on_an_upgrade")
83
- [(NO_MAPS if no_maps),
84
- (report.fetch("next_action") unless report.fetch("next_action") == nothing_changed),
85
- ("Details: #{@invocation.in_project("list-member-problems")}" unless report.fetch("members").empty?)].compact
81
+ action = report.fetch("next_action")
82
+ [(NO_MAPS if no_maps), (project_line if names_a_command),
83
+ (action unless action == nothing_changed)].compact
86
84
  end
85
+
86
+ # The project once, before the first command stderr prints, where they run since they leave out --project,
87
+ # and how to see the details rows leave out, such as each commit's subject (#1263).
88
+ #: () -> String
89
+ def project_line = "In #{@invocation.project_word} (details: drop --short):"
87
90
  end
88
91
  end
89
92
  end
@@ -18,6 +18,10 @@ module Principles
18
18
  OLDER_STATE = "An older version of this tool kept audit runs in this file. This version does not read " \
19
19
  "it, so an audit recorded only there is not a baseline. Start a new audit to make one."
20
20
 
21
+ # The lead before the acknowledgements, which leaves the agent to judge each change (#1263).
22
+ ACKNOWLEDGE_LEAD = "Acknowledge members that still say the same thing; if one's meaning changed, or its check " \
23
+ "is new, changed or fails, run start-audit ID:"
24
+
21
25
  #: (Invocation) -> void
22
26
  def initialize(invocation)
23
27
  @invocation = invocation
@@ -32,53 +36,78 @@ module Principles
32
36
  #| ?acknowledgeable: Hash[String, Array[String]], ?waiting: Array[RecordWaitingOnAnUpgrade])
33
37
  #| -> Hash[String, untyped]
34
38
  def checked(report, not_read: [], no_baseline_files: {}, acknowledgeable: {}, waiting: [])
39
+ checked_naming_commands(report, not_read:, no_baseline_files:, acknowledgeable:, waiting:).first
40
+ end
41
+
42
+ # The same result, and whether its next_action names a command, before which --short names the project once
43
+ # (#1263), so no view reads the action's text to find one (#1279).
44
+ #: (Hash[String, untyped], ?not_read: Array[String], ?no_baseline_files: Hash[String, Array[String]],
45
+ #| ?acknowledgeable: Hash[String, Array[String]], ?waiting: Array[RecordWaitingOnAnUpgrade])
46
+ #| -> [Hash[String, untyped], bool]
47
+ def checked_naming_commands(report, not_read: [], no_baseline_files: {}, acknowledgeable: {}, waiting: [])
35
48
  unless not_read.empty?
36
49
  report = report.merge("not_read" => not_read.map { |file| { "file" => file, "because" => OLDER_STATE } })
37
50
  end
38
51
  report = report.merge("records_waiting_on_an_upgrade" => waiting.map(&:to_h)) unless waiting.empty?
39
- report.merge("next_action" => next_action(report, no_baseline_files:, acknowledgeable:, waiting:))
52
+ action, commands = next_action(report, no_baseline_files:, acknowledgeable:, waiting:)
53
+ [report.merge("next_action" => action), commands]
40
54
  end
41
55
 
42
56
  private
43
57
 
44
- # What to do next for report, each kind of action on lines of its own, or NOTHING_CHANGED when none applies.
58
+ # What to do next for report, each kind of action on lines of its own, or NOTHING_CHANGED when none applies,
59
+ # and whether it names a command: every changed, unaudited and mapping action does, a no-baseline one as it
60
+ # says, and neither the mapping notice nor a waiting principle's update sentence does.
45
61
  #: (Hash[String, untyped], no_baseline_files: Hash[String, Array[String]],
46
- #| acknowledgeable: Hash[String, Array[String]], waiting: Array[RecordWaitingOnAnUpgrade]) -> String
62
+ #| acknowledgeable: Hash[String, Array[String]], waiting: Array[RecordWaitingOnAnUpgrade]) -> [String, bool]
47
63
  def next_action(report, no_baseline_files:, acknowledgeable:, waiting:)
48
64
  waits = waiting.map(&:principle)
49
65
  mapping = MapsNeedingMembersOrAudit.new(@invocation, report: report, files_to_commit: no_baseline_files,
50
66
  waiting: waits)
51
- action = [changed_action(report, acknowledgeable, waits), unaudited_action(report, waits), mapping.notice,
52
- *no_baseline_actions(report, no_baseline_files).map(&:to_s), *mapping.actions,
67
+ commanding = [changed_action(report, acknowledgeable, waits), unaudited_action(report, waits)].compact
68
+ no_baseline = no_baseline_actions(report, no_baseline_files)
69
+ action = [*commanding, mapping.notice, *no_baseline.map(&:to_s), *mapping.actions,
53
70
  *waiting.map(&:to_s)].compact.join("\n")
54
- action.empty? ? NOTHING_CHANGED : action
71
+ [action.empty? ? NOTHING_CHANGED : action, names_a_command?(commanding, no_baseline, mapping)]
72
+ end
73
+
74
+ # Whether any of the actions that may name a command does.
75
+ #: (Array[String], Array[MembersWithNoBaseline], MapsNeedingMembersOrAudit) -> bool
76
+ def names_a_command?(commanding, no_baseline, mapping)
77
+ !commanding.empty? || no_baseline.any?(&:names_a_command?) || !mapping.actions.empty?
55
78
  end
56
79
 
57
80
  # For each principle with a changed member, its audits, each command ending its own line (#568): where
58
- # acknowledgeable names a member a one-member audit may judge, that audit for each such member, filled and
59
- # shell-quoted so the agent types no id (#626, D56), then the full audit, each with when to use it; elsewhere
60
- # the full audit alone, with no condition, as nothing else applies (#633). None for a principle in waits, whose
61
- # audits wait on an upgrade (#1066).
81
+ # acknowledgeable names members a one-member audit may judge, one acknowledgement for all of them (#1169,
82
+ # #1263), filled and shell-quoted so the agent types no id (#626, D56), after one lead saying when to audit in
83
+ # full instead; the full audit for a principle with a changed member no acknowledgement may judge, with no
84
+ # condition, as nothing else applies to it (#633). None for a principle in waits, whose audits wait on an
85
+ # upgrade (#1066).
62
86
  #: (Hash[String, untyped], Hash[String, Array[String]], Array[String]) -> String?
63
87
  def changed_action(report, acknowledgeable, waits)
64
- principles = report.fetch("members").map { |member| member.fetch("principle") }.uniq - waits
65
- audits = principles.flat_map do |id|
66
- full = @invocation.in_project("start-audit", id)
67
- members = acknowledgeable.fetch(id, [])
68
- next "Audit #{id} in full to judge its changed members: #{full}" if members.empty?
69
-
70
- [*members.flat_map { |member| acknowledge_lines(id, member) },
71
- "When a change alters what a member of #{id} says, or its check is new, changed or does not pass, " \
72
- "audit it in full: #{full}"]
73
- end
74
- audits.empty? ? nil : audits.join("\n")
88
+ changed = report.fetch("members").group_by { it.fetch("principle") }.except(*waits)
89
+ acknowledging = changed.keys.filter_map { |id| acknowledge_line(id, acknowledgeable.fetch(id, [])) }
90
+ full = changed.filter_map { |id, members| full_audit_line(id, members, acknowledgeable.fetch(id, [])) }
91
+ lines = [*(ACKNOWLEDGE_LEAD unless acknowledging.empty?), *acknowledging, *full]
92
+ lines.empty? ? nil : lines.join("\n")
93
+ end
94
+
95
+ # The one-member audit acknowledging every member of principle id in members, or nil when there is none.
96
+ #: (String, Array[String]) -> String?
97
+ def acknowledge_line(id, members)
98
+ return if members.empty?
99
+
100
+ @invocation.in_project("start-audit", id, options: members.flat_map { ["--member", it] })
75
101
  end
76
102
 
77
- # The lead naming member, and on a line of its own the one-member audit that acknowledges its change.
78
- #: (String, String) -> Array[String]
79
- def acknowledge_lines(id, member)
80
- ["When #{member} still says the same thing, acknowledge it:",
81
- @invocation.in_project("start-audit", id, options: ["--member", member])]
103
+ # The full audit of principle id, for its changed members no acknowledgement may judge, or nil when the
104
+ # acknowledgement takes in every one.
105
+ #: (String, Array[Hash[String, untyped]], Array[String]) -> String?
106
+ def full_audit_line(id, members, acknowledgeable)
107
+ return if members.all? { acknowledgeable.include?(it.fetch("id")) }
108
+
109
+ other = acknowledgeable.empty? ? "" : " other"
110
+ "Audit #{id} in full to judge its#{other} changed members: #{@invocation.in_project("start-audit", id)}"
82
111
  end
83
112
 
84
113
  # Members compared only with the commit that mapped them have never been assessed, so neither "changed" nor