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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ec72c7b217d3e48437dcdb1e8166654efe8b27fe3888d35d90eeeb31fcfa0c8c
4
- data.tar.gz: b8de7786425d0a890ff2452b78b50b667e895e39fe45552c4d2e37c69a80a4c3
3
+ metadata.gz: d5d575d0453395ba5141ec7780917df605ff9fc26293bd31fa383ab4bf76db04
4
+ data.tar.gz: 75adf95a072fa1d188e18216ea73423255898c4f4d4914cb2229b3f6a5f8bf88
5
5
  SHA512:
6
- metadata.gz: 528513b4102743cb1fc16d599fc3760b4e1dd8eafa3cd5ea5ce305a50f9f0a19f37777aeff2a5e15b936003050635c27ab9153b2d2892eb4aade644a1372e6ac
7
- data.tar.gz: 7fa772560fdbb6ead5720db8dc8381eaa094426766d111a51968a222899eaa6a29f6ce89b1c692e37ce1275ab87b557434ffb32747d45e8c8d1f4d7e41f2ac74
6
+ metadata.gz: a9faed0ef7cc9f65234fa8add36851d815780e558ef618663413239b2b27a8679682dfacb9faa1cd7cab8e9997fe4e812b76982c9bb24498bbf1e1880751b3c8
7
+ data.tar.gz: f6ef3034f68217f1702235584cc338e028785d1581d971fd79bb786cd546fc5b86450c842747974c57867b0901b82f721b5b5ce65ad2048cd90723251788d25f
@@ -51,6 +51,8 @@ module Principles
51
51
  def dispatch(line)
52
52
  return printed(running_version) if line.option("version")
53
53
 
54
+ return printed(help_topic(line)) if line.help_words?
55
+
54
56
  command = line.command or return printed(help.overview)
55
57
  return printed(help_for(command)) if line.option("help")
56
58
 
@@ -148,6 +150,13 @@ module Principles
148
150
  #: () -> String
149
151
  def running_version = Data::RunningVersion.new.to_s
150
152
 
153
+ # The page help COMMAND asks for, as COMMAND --help prints it, or the overview for help alone (#1167).
154
+ #: (CommandLine) -> String
155
+ def help_topic(line)
156
+ topic = line.help_topic
157
+ topic ? help_for(topic) : help.overview
158
+ end
159
+
151
160
  # A command's --help, from the steps command-steps.json lists for it.
152
161
  #: (String) -> String
153
162
  def help_for(command)
@@ -5,6 +5,7 @@ require "optparse"
5
5
  require_relative "invocation_options"
6
6
  require_relative "after_commit_hook_options"
7
7
  require_relative "session_start_options"
8
+ require_relative "list_open_findings_options"
8
9
  require_relative "start_audit_options"
9
10
  require_relative "models/command_steps"
10
11
  require_relative "prose_list"
@@ -58,6 +59,14 @@ module Principles
58
59
  #: () -> bool
59
60
  def project_given? = @options.given.include?("project")
60
61
 
62
+ # Whether the words ask for help by word, as help or help COMMAND, which an agent tries before --help (#1167).
63
+ #: () -> bool
64
+ def help_words? = @arguments.first == "help"
65
+
66
+ # The command help COMMAND names, or nil for help alone.
67
+ #: () -> String?
68
+ def help_topic = @arguments[1]
69
+
61
70
  # The command named first; nil when none is, and refused when this tool has no such command.
62
71
  #: () -> String?
63
72
  def command
@@ -98,12 +107,13 @@ module Principles
98
107
 
99
108
  # Each argument the command needs and was not given, named in one refusal: an agent that met one refusal per
100
109
  # missing argument repaired them one at a time (#1083). Each option command-steps.json says it requires is one.
110
+ # The repair names the command's usage, which shows what to give (#1273).
101
111
  #: (String) -> void
102
112
  def check_missing(name)
103
113
  missing = positionals.missing + missing_options(name)
104
114
  return if missing.empty?
105
115
 
106
- raise OptionParser::MissingArgument, "#{name} needs #{ProseList.new(missing)}"
116
+ raise UsageRefusal.new("missing argument: #{name} needs #{ProseList.new(missing)}", help_repair(name))
107
117
  end
108
118
 
109
119
  # The options command name requires and was not given, as a refusal names them.
@@ -148,12 +158,13 @@ module Principles
148
158
  end
149
159
 
150
160
  # Options checked together, each set owning what is wrong with it as given: --session-start (#717), the
151
- # after-commit hook's pair on the command it runs (D73) and the audit start-audit begins (#760); the first fault is
152
- # refused.
161
+ # after-commit hook's pair on the command it runs (D73), the audit start-audit begins (#760) and the form
162
+ # list-open-findings prints (#1156); the first fault is refused.
153
163
  #: (String) -> void
154
164
  def check_combined_options(name)
155
165
  hook = (AfterCommitHookOptions.new(@options) if name == AfterCommitHookOptions::COMMAND)
156
- sets = [SessionStartOptions.new(@options), hook, StartAuditOptions.new(@options)].compact
166
+ sets = [SessionStartOptions.new(@options), hook, StartAuditOptions.new(@options),
167
+ ListOpenFindingsOptions.new(@options)].compact
157
168
  fault = sets.filter_map(&:fault).first or return
158
169
  raise UsageRefusal.new(fault, help_repair(name))
159
170
  end
@@ -177,7 +188,13 @@ module Principles
177
188
  #: (String) -> Models::CommandSteps::Command?
178
189
  def steps(name) = Models::CommandSteps.load.command(name)
179
190
 
191
+ # The command's usage, which names every option it takes, so a near-miss such as --heading for --section shows
192
+ # beside the refusal (#1273), then where to see what each takes. The usage leaves out the executable, so it is not
193
+ # read as a command to run as printed.
180
194
  #: (String) -> String
181
- def help_repair(name) = "To see what it takes: #{@executable} #{name} --help"
195
+ def help_repair(name)
196
+ usage = steps(name)&.usage or return "To see what it takes: #{@executable} #{name} --help"
197
+ "Usage: #{usage}\nTo see what each takes: #{@executable} #{name} --help"
198
+ end
182
199
  end
183
200
  end
@@ -54,8 +54,8 @@ module Principles
54
54
  "remove-member-check" => Route.new(Controllers::MemberEntries, %w[id member]),
55
55
  "remove-member" => Route.new(Controllers::MemberEntries, %w[id member]),
56
56
  "start-audit" => Route.new(Controllers::Audit, %w[id]),
57
- "submit-answer" => Route.new(Controllers::Answer, %w[request_id]),
58
- "show-answer-check" => Route.new(Controllers::Answer, %w[request_id])
57
+ "submit-answer" => Route.new(Controllers::Answer, %w[request_id?]),
58
+ "show-answer-check" => Route.new(Controllers::Answer, %w[request_id?])
59
59
  }.freeze #: Hash[String, Route]
60
60
 
61
61
  # Each command's positional arguments, in order, as CommandLine takes them.
@@ -1,13 +1,12 @@
1
1
  # typed: strict
2
2
  # frozen_string_literal: true
3
3
 
4
- require "json"
5
4
  require "time"
6
5
  require_relative "answer_phase"
6
+ require_relative "member_acknowledgement"
7
7
  require_relative "../models/acknowledgement"
8
- require_relative "../models/check_since_last_audit"
8
+ require_relative "../models/acknowledgements"
9
9
  require_relative "../models/reported_check"
10
- require_relative "../views/one_member_check_result_template"
11
10
  require_relative "../views/acknowledgement_result"
12
11
 
13
12
  module Principles
@@ -21,10 +20,8 @@ module Principles
21
20
  #: (String, String) -> Hash[String, untyped]
22
21
  def start(id, member_id)
23
22
  naming_the_executable(rerun: one_member_audit(id)) do
24
- acknowledgement, change, check = asked(id, member_id)
25
- view.request(request_id: acknowledgement.request_id.to_s, principle_id: id, change: change,
26
- context: { **acknowledgement.open_findings, **instruction_for(check) },
27
- placeholders: placeholders(check&.to_h, change))
23
+ member = of(id, member_id)
24
+ view.request(request_id: member.acknowledgement.request_id.to_s, principle_id: id, asked: member.asked)
28
25
  .merge("wrote" => [])
29
26
  end
30
27
  end
@@ -34,9 +31,22 @@ module Principles
34
31
  #: (String, String) -> Hash[String, untyped]
35
32
  def to_fill(id, member_id)
36
33
  naming_the_executable(rerun: one_member_audit(id)) do
37
- acknowledgement, change, check = asked(id, member_id)
38
- view.answer_to_fill(request_id: acknowledgement.request_id.to_s, change: change,
39
- placeholders: placeholders(check&.to_h, change))
34
+ member = of(id, member_id)
35
+ view.answer_to_fill(request_id: member.acknowledgement.request_id.to_s, asked: member.asked)
36
+ end
37
+ end
38
+
39
+ # The request for several of principle id's members in one answer (#1169), or with to_fill its answer alone:
40
+ # each member as its own request shows it.
41
+ #: (String, Array[String], to_fill: bool) -> Hash[String, untyped]
42
+ def several(id, member_ids, to_fill:)
43
+ naming_the_executable(rerun: one_member_audit(id)) do
44
+ members = member_ids.map { of(id, it) }
45
+ request_id = several_of(id, members).request_id.to_s
46
+ asked = members.map(&:asked)
47
+ next view.several_to_fill(request_id:, members: asked) if to_fill
48
+
49
+ view.several_request(request_id:, principle_id: id, members: asked).merge("wrote" => [])
40
50
  end
41
51
  end
42
52
 
@@ -44,20 +54,22 @@ module Principles
44
54
  # @override
45
55
  #: (Models::SubmittedAnswer) -> [Views::AnsweredRequest, Array[Models::AuditRecord]]
46
56
  def answered(submitted)
47
- request_id = submitted.request_id
48
- response = submitted.response
49
- id = request_id.principle_id
50
- acknowledgement, member, = prepared(id, response.fetch("basis").fetch("member_id"))
51
- stale(id, member.id) unless acknowledgement.request_id.to_s == request_id.to_s
52
- [view.acknowledged(principle_id: id, member_id: member.id, file: @audit_records.file(id)),
53
- [accepted(id, acknowledgement, member, response)]]
57
+ return several_answered(submitted) if submitted.request_id.phase == Models::Acknowledgements::PHASE
58
+
59
+ id = submitted.request_id.principle_id
60
+ member = answering(submitted)
61
+ [view.acknowledged(principle_id: id, member_id: member.member.id, file: @audit_records.file(id)),
62
+ [member.accepted(submitted.response, at: Time.now.utc.iso8601)]]
54
63
  end
55
64
 
56
65
  # The refusals an answer meets before its shape: any phase's, then a placeholder its template printed left in,
57
66
  # which the shape would refuse in meaning_kept without naming it (#773), or in a checked member's exit_status
58
- # with a repair this template does not take (#1170).
67
+ # with a repair this template does not take (#1170), read in each member's entry of an answer to several (#1169).
59
68
  #: (Models::RequestId) -> Array[Models::RefusalBeforeShape]
60
- def before_shape(request_id) = [*super, Models::Acknowledgement::LEFT_AS_PRINTED]
69
+ def before_shape(request_id)
70
+ left = Models::Acknowledgement::LEFT_AS_PRINTED
71
+ [*super, request_id.phase == Models::Acknowledgements::PHASE ? left.in_each_member : left]
72
+ end
61
73
 
62
74
  private
63
75
 
@@ -67,53 +79,8 @@ module Principles
67
79
  # @override
68
80
  #: (Models::RequestId) -> Hash[String, untyped]?
69
81
  def printed_placeholders(_request_id)
70
- placeholders(Models::ReportedCheck::UNCHANGED_PLACEHOLDERS.to_h
71
- .merge("exit_status" => Models::Acknowledgement::EXIT_STATUS_PLACEHOLDER))
72
- end
73
-
74
- # The acknowledgement of principle id's member, its change since its baseline, as the request shows it, and the
75
- # check_result its answer fills with the instruction beside it, if the member has a check.
76
- #: (String, String)
77
- #| -> [Models::Acknowledgement, Views::MemberChangeSinceBaseline, Views::OneMemberCheckResultTemplate?]
78
- def asked(id, member_id)
79
- acknowledgement, member, base = prepared(id, member_id)
80
- baseline, lines = since_baseline(id, acknowledgement, member)
81
- check = check_template(id, member)
82
- [acknowledgement,
83
- Views::MemberChangeSinceBaseline.new(
84
- member: shown(acknowledgement, member, baseline), member_lines: lines.shown(taken: bytes_of(check)),
85
- first_changed_lines: acknowledgement.first_changed_lines(lines),
86
- commits: commits(acknowledgement, baseline, base), paths: acknowledgement.paths_since(baseline)
87
- ), check]
88
- end
89
-
90
- # The request's check_instruction for a checked member, how to run and report its check; none without one (#1170).
91
- #: (Views::OneMemberCheckResultTemplate?) -> Hash[String, String]
92
- def instruction_for(check) = check ? { "check_instruction" => check.instruction } : {}
93
-
94
- # The bytes the check's template and instruction take as the request prints them, which the member's lines
95
- # give up (#1119).
96
- #: (Views::OneMemberCheckResultTemplate?) -> Integer
97
- def bytes_of(check) = check ? JSON.pretty_generate(check.to_h).bytesize + check.instruction.bytesize : 0
98
-
99
- # The text the template prints in each field the agent writes: its judgement's placeholders, meaning_kept's
100
- # chosen by whether the change's first_changed_lines is a pure insertion (#1142), and check_result's for a
101
- # checked member. The quotes the answer reads as first_changed_lines when left out are not printed (#1170).
102
- #: (Hash[String, untyped]?, ?Views::MemberChangeSinceBaseline?) -> Hash[String, untyped]
103
- def placeholders(check_result, change = nil)
104
- quotes = change&.first_changed_lines.to_h
105
- { **Models::Acknowledgement.placeholders_beside(quotes),
106
- **(check_result ? { "check_result" => check_result } : {}) }
107
- end
108
-
109
- # The check_result a checked member's answer fills, for the check the last audit ran, which a one-member audit
110
- # requires (D30, D63, #1071), asking for a passing run alone (#1112); nil for a member without a check.
111
- #: (String, Models::Member) -> Views::OneMemberCheckResultTemplate?
112
- def check_template(id, member)
113
- checks = Models::CheckSinceLastAudit.new(principle_history: principle_history(id),
114
- record: @audit_records.find(id))
115
- Views::OneMemberCheckResultTemplate.for(checks.entry(member),
116
- exit_status: Models::Acknowledgement::EXIT_STATUS_PLACEHOLDER)
82
+ MemberAcknowledgement.placeholders(Models::ReportedCheck::UNCHANGED_PLACEHOLDERS.to_h
83
+ .merge("exit_status" => Models::Acknowledgement::EXIT_STATUS_PLACEHOLDER))
117
84
  end
118
85
 
119
86
  # The one-member audit of principle id's member, as a refusal naming a near miss leads its repair with (D56).
@@ -122,55 +89,65 @@ module Principles
122
89
  ->(member) { invocation.in_project("start-audit", id, options: ["--member", member]) }
123
90
  end
124
91
 
125
- # The record with the acknowledgement in it, once its quotes are found at the baseline and now.
126
- #: (String, Models::Acknowledgement, Models::Member, untyped) -> Models::AuditRecord
127
- def accepted(id, acknowledgement, member, response)
128
- _baseline, lines = since_baseline(id, acknowledgement, member)
129
- acknowledgement.accepted(response, lines, at: Time.now.utc.iso8601)
92
+ # The member the answer acknowledges, refused as stale unless its request is still the one the answer answers.
93
+ #: (Models::SubmittedAnswer) -> MemberAcknowledgement
94
+ def answering(submitted)
95
+ id = submitted.request_id.principle_id
96
+ member = of(id, submitted.response.fetch("basis").fetch("member_id"))
97
+ stale(id, member.member.id) unless member.acknowledgement.request_id == submitted.request_id
98
+ member
130
99
  end
131
100
 
132
- # The member as the request shows it, with where it was at its baseline when it has moved since (#547).
133
- #: (Models::Acknowledgement, Models::Member, Models::Placement) -> Hash[String, untyped]
134
- def shown(acknowledgement, member, baseline)
135
- moved_from = acknowledgement.moved_from(baseline)
136
- { "id" => member.id, "role" => member.role, **(member.check ? { "check" => member.check } : {}),
137
- "evidence" => [member.reference],
138
- **(moved_from ? { "evidence_at_baseline" => [moved_from] } : {}) }
101
+ # The result of answering a request for several members, and the one record their acknowledgements change.
102
+ #: (Models::SubmittedAnswer) -> [Views::AnsweredRequest, Array[Models::AuditRecord]]
103
+ def several_answered(submitted)
104
+ id = submitted.request_id.principle_id
105
+ several, members = answering_several(submitted)
106
+ [view.several_acknowledged(principle_id: id, member_ids: members.map { it.member.id },
107
+ file: @audit_records.file(id)),
108
+ [all_accepted(several, members, submitted.response)]]
139
109
  end
140
110
 
141
- # The commits the request names: the baseline's, HEAD, and the audit's base when the baseline is later (#550).
142
- #: (Models::Acknowledgement, Models::Placement, String?) -> Hash[String, String]
143
- def commits(acknowledgement, baseline, base)
144
- audit_base = acknowledgement.audit_base(baseline)
145
- { "baseline" => baseline.commit, "base" => base.to_s, **(audit_base ? { "audit_base" => audit_base } : {}) }
111
+ # The members the answer acknowledges, refused as stale unless their request is still the one it answers.
112
+ #: (Models::SubmittedAnswer) -> [Models::Acknowledgements, Array[MemberAcknowledgement]]
113
+ def answering_several(submitted)
114
+ id = submitted.request_id.principle_id
115
+ members = submitted.response.fetch("basis").fetch("member_ids").map { of(id, it) }
116
+ several = several_of(id, members)
117
+ stale(id, members.map { it.member.id }) unless several.request_id == submitted.request_id
118
+ [several, members]
146
119
  end
147
120
 
148
- # The member's baseline, the oldest commit from the one it was last judged at that holds the text the audit
149
- # record vouches for, placed as that commit's map placed it or as it is placed now (#547, #550), and its own
150
- # lines there and now, which the answer's quotes are checked against (#379).
151
- #: (String, Models::Acknowledgement, Models::Member) -> [Models::Placement, Models::MemberLines]
152
- def since_baseline(_id, acknowledgement, member)
153
- placements = acknowledgement.placements_in(@project)
154
- baseline = acknowledgement.baseline(placements)
155
- lines = @project.member_lines(member.locator, since: baseline.commit, then_locator: baseline.locator)
156
- [baseline, acknowledgement.compared(lines)]
121
+ # The record with each member's acknowledgement in it, once the answer holds for every one of them.
122
+ #: (Models::Acknowledgements, Array[MemberAcknowledgement], untyped) -> Models::AuditRecord
123
+ def all_accepted(several, members, response)
124
+ at = Time.now.utc.iso8601
125
+ by_id = members.to_h { [it.member.id, it] }
126
+ acknowledging = by_id.keys
127
+ several.accepted(response) do |member_id, entry, into|
128
+ by_id.fetch(member_id).accepted(entry, at:, acknowledging:, into:)
129
+ end
157
130
  end
158
131
 
159
- #: (String, String) -> [Models::Acknowledgement, Models::Member, String?]
160
- def prepared(id, member_id)
161
- member = Models::Member.new(@principles.find(id).member(member_id))
162
- base = @history.base_commit(id, [@principles.file(id), member.path])
163
- now = @project.locate(member.locator).fetch("sha256")
164
- [Models::Acknowledgement.new(principle_id: id, member: member, record: @audit_records.find(id), base: base,
165
- now_sha256: now), member, base]
132
+ # The acknowledgements of several of principle id's members, each under its member's id, in one request.
133
+ #: (String, Array[MemberAcknowledgement]) -> Models::Acknowledgements
134
+ def several_of(id, members)
135
+ named = members.map { [it.member.id, it.acknowledgement.request_id] }
136
+ Models::Acknowledgements.of(principle_id: id, members: named)
166
137
  end
167
138
 
168
- #: (String, String) -> bot
169
- def stale(id, member_id)
139
+ # principle_id's member member_id, as its one-member audit asks and answers it.
140
+ #: (String, String) -> MemberAcknowledgement
141
+ def of(id, member_id) = handed(MemberAcknowledgement, principle_id: id, member_id:)
142
+
143
+ # Refuses an answer to a request that no longer matches the project, naming the request for the same members.
144
+ #: (String, String | Array[String]) -> bot
145
+ def stale(id, member_ids)
146
+ options = Array(member_ids).flat_map { ["--member", it] }
170
147
  raise Error.new("stale_request", "This request no longer matches #{id}: the member, its baseline or the " \
171
148
  "commit it was based on has changed since it was printed",
172
149
  "Start it again and answer the new request: " \
173
- "#{invocation.in_project("start-audit", id, options: ["--member", member_id])}")
150
+ "#{invocation.in_project("start-audit", id, options:)}")
174
151
  end
175
152
 
176
153
  #: () -> Views::AcknowledgementResult
@@ -21,7 +21,7 @@ module Principles
21
21
  # The controller that answers for each phase a request id may name.
22
22
  PHASE_CONTROLLERS = {
23
23
  "assessment" => Assessment, "correction" => Correction, "acknowledgement" => Acknowledgement,
24
- "repointing" => Repoint
24
+ "acknowledgements" => Acknowledgement, "repointing" => Repoint
25
25
  }.freeze #: Hash[String, Class[AnswerPhase]]
26
26
 
27
27
  #: (String, String?, Hash[String, untyped]) -> untyped
@@ -37,13 +37,14 @@ module Principles
37
37
 
38
38
  private
39
39
 
40
- # The answer from --file, where - means it was read from stdin, to the request REQUEST_ID names, checked against
41
- # the schema for the phase that id names once its head says it answers a request that still matches the project,
42
- # with the prior findings a full audit's request listed, which checking its head found (#1052).
40
+ # The answer from --file, where - means it was read from stdin, to the request REQUEST_ID names, or the answer's
41
+ # own request_id when none is given (#995), checked against the schema for the phase that id names once its head
42
+ # says it answers a request that still matches the project, with the prior findings a full audit's request
43
+ # listed, which checking its head found (#1052).
43
44
  #: (Hash[String, untyped]) -> Models::SubmittedAnswer
44
45
  def submitted(options)
45
- request_id = Models::RequestId.parse(options.fetch("request_id"))
46
- sent = @project.answer(options.fetch("file"), stdin: options["stdin"], phase: request_id.phase)
46
+ sent = @project.answer(options.fetch("file"), stdin: options["stdin"], given: options["request_id"])
47
+ request_id = sent.request_id
47
48
  prior = checked_head(request_id, sent.head)
48
49
  Models::SubmittedAnswer.new(request_id, sent.checked(phase(request_id).before_shape(request_id)), prior)
49
50
  end
@@ -100,15 +100,18 @@ module Principles
100
100
  correction_request(start, audit, findings, decided, assessed)
101
101
  end
102
102
 
103
- # The correction request for findings, and outside git the open record that keeps what the audit began from.
103
+ # The correction request for findings, and the open record that keeps the assessment, whose digest its basis
104
+ # carries in place of the assessment, so the correction reads it back from the record (D87).
104
105
  # It is refused before it is printed once the last completed record changed, so no fix is made for an audit
105
- # that cannot complete (D50). The check results travel in the basis, so the completed record keeps them (D30).
106
+ # that cannot complete (D50). The check results travel in the record, so the completed record keeps them (D30).
106
107
  #: (Models::AuditStart, Models::Audit, Array[untyped], Models::DecidedPriorFindings, Models::AssessmentBasis)
107
108
  #| -> [untyped, Array[Models::AuditRecord]]
108
109
  def correction_request(start, audit, findings, decided, assessed)
109
110
  assessed.printed_after.confirm_unchanged(audit.id, @audit_records.find(audit.id))
110
- basis = printed_basis(start, findings, decided, assessed)
111
- [request_to_correct(basis, audit, findings), open_record_changes(start, audit, basis.to_h)]
111
+ record = open_record(start, audit, findings)
112
+ basis = Models::CorrectionBasis.printed(start, findings: findings, prior: decided, revision: assessed.revision,
113
+ open_record: record)
114
+ [request_to_correct(basis, audit, findings), @audit_records.changes(record)]
112
115
  end
113
116
 
114
117
  # The correction request for findings, answered under an id that digests its basis and the members now.
@@ -119,24 +122,13 @@ module Principles
119
122
  placeholders: Models::Disposition::TEMPLATE_PLACEHOLDERS)
120
123
  end
121
124
 
122
- # The basis a correction request prints, for the agent to hand back with its answer.
123
- # Its revision is the one the assessment was printed after, carried forward, so the correction is refused once
124
- # that record changes (#646, D50).
125
- #: (Models::AuditStart, Array[untyped], Models::DecidedPriorFindings, Models::AssessmentBasis)
126
- #| -> Models::CorrectionBasis
127
- def printed_basis(start, findings, decided, assessed)
128
- Models::CorrectionBasis.printed(start, findings: findings, prior: decided, revision: assessed.revision)
129
- end
130
-
131
- # Outside git, the open record that keeps what the audit began from, and the last completed record, so a
132
- # restarted audit still lists its prior findings (D35); in git, nothing.
133
- #: (Models::AuditStart, Models::Audit, Hash[String, untyped]) -> Array[Models::AuditRecord]
134
- def open_record_changes(start, audit, basis)
135
- return [] if start.base
136
-
125
+ # The open record that keeps the assessment, and outside git what the audit began from, and the last completed
126
+ # record, so a restarted audit still lists its prior findings (D35), in git as outside it (D87).
127
+ #: (Models::AuditStart, Models::Audit, Array[untyped]) -> Models::AuditRecord
128
+ def open_record(start, audit, findings)
137
129
  last = @audit_records.find(audit.id)&.last_completed
138
- record = handed(AuditCompletion).record(start, basis.fetch("findings"), "open", audit.now, last)
139
- @audit_records.changes(record)
130
+ raised = findings.map { |finding| finding.slice(*Models::RecordedFinding::RAISED_FIELDS) }
131
+ handed(AuditCompletion).record(start, raised, "open", audit.now, last)
140
132
  end
141
133
  end
142
134
  end
@@ -24,7 +24,7 @@ module Principles
24
24
  naming_the_executable do
25
25
  case command
26
26
  when "show-audit" then shown_audit(required_id(id))
27
- when "list-open-findings" then options["short"] ? open_findings_line(id, options) : open_findings(id)
27
+ when "list-open-findings" then listed_open_findings(id, options)
28
28
  else unknown(command)
29
29
  end
30
30
  end
@@ -65,13 +65,33 @@ module Principles
65
65
  @audit_records.fetch(id).shown.merge(waiting_beside(id), "wrote" => [])
66
66
  end
67
67
 
68
- # A one-member audit of member_id (D33), or its answer alone to fill (#773).
69
- #: (String, String, to_fill: bool) -> Hash[String, untyped]
70
- def acknowledge(id, member_id, to_fill:)
68
+ # A one-member audit of the member member_ids names (D33), or of several members in one request (#1169), or its
69
+ # answer alone to fill (#773).
70
+ #: (String, Array[String], to_fill: bool) -> Hash[String, untyped]
71
+ def acknowledge(id, member_ids, to_fill:)
71
72
  acknowledgement = handed(Acknowledgement)
73
+ member_id = member_ids.first.to_s
74
+ return acknowledgement.several(id, member_ids, to_fill:) if member_ids.size > 1
75
+
72
76
  to_fill ? acknowledgement.to_fill(id, member_id) : acknowledgement.start(id, member_id)
73
77
  end
74
78
 
79
+ # The open findings in the form the options ask for: the session-start hook's one line with --short, a line each
80
+ # with --lines (#1156), or the full list.
81
+ #: (String?, Hash[String, untyped]) -> untyped
82
+ def listed_open_findings(id, options)
83
+ return open_findings_line(id, options) if options["short"]
84
+ return open_findings_lines(id) if options["lines"]
85
+
86
+ open_findings(id)
87
+ end
88
+
89
+ # Each open finding on a line, with whom it waits on (#1156).
90
+ #: (String?) -> Views::Lines
91
+ def open_findings_lines(id)
92
+ Views::FindingsResult.new(invocation).lines(open_records(id).flat_map(&:left_open).map(&:listed))
93
+ end
94
+
75
95
  # The findings the last completed audit of map id, or of every map, deferred or accepted (#292, D35). Across
76
96
  # every map, it names each principle whose record a later copy wrote, so a list left without one that cannot be
77
97
  # read does not look whole (D85, V8).
@@ -20,13 +20,16 @@ module Principles
20
20
  class AuditCompletion < Command
21
21
  # map_changes are the changes a correction declared to the map, which name the map file to commit (D40).
22
22
  # replacing is the revision of the last completed record when the request that completes the audit was
23
- # printed, which refuses to replace a record changed since (#646).
23
+ # printed, which refuses to replace a record changed since (#646). read_back_from is the record a correction
24
+ # read the audit's assessment back from, which, when completed, only an identical retry completes again (D24,
25
+ # D87).
24
26
  #: (Models::Project, tool: RunningTool, ?map_changes: Models::DeclaredMapChanges?,
25
- #| ?replacing: Models::LastCompletedRevision?) -> void
26
- def initialize(project, tool:, map_changes: nil, replacing: nil)
27
+ #| ?replacing: Models::LastCompletedRevision?, ?read_back_from: Models::AuditRecord?) -> void
28
+ def initialize(project, tool:, map_changes: nil, replacing: nil, read_back_from: nil)
27
29
  super(project, tool: tool)
28
30
  @map_changes = map_changes #: Models::DeclaredMapChanges?
29
31
  @replacing = replacing #: Models::LastCompletedRevision?
32
+ @read_back_from = read_back_from #: Models::AuditRecord?
30
33
  end
31
34
 
32
35
  # The completed result, and the record change it makes, not yet written.
@@ -37,6 +40,7 @@ module Principles
37
40
  written = record(start, audit.outcomes(findings, dispositions, decided), "completed", audit.now)
38
41
  changes = @audit_records.changes(written)
39
42
  @replacing&.confirm_writable(audit.id, @audit_records.find(audit.id), changes)
43
+ audit.confirm_read_back(@read_back_from, changes)
40
44
  [Views::AnsweredRequest.new(completion_result(start, audit, dispositions, decided, written)), changes]
41
45
  end
42
46
 
@@ -59,11 +59,15 @@ module Principles
59
59
  moves = Models::MemberMoves.new(response["moved_members"])
60
60
  before = moves.hashes(confirmed_start(request_id, basis, audit, changes))
61
61
  findings = moves.findings(basis.findings)
62
- start = audit.resumed(basis, before, moves)
63
- completion(changes, basis).completed(start, audit, dispositions(response, findings, start, audit), findings,
64
- basis.prior_decided.moved(moves))
62
+ start = resumed(audit, basis, before, moves)
63
+ completion(changes, basis, audit).completed(start, audit, dispositions(response, findings, start, audit),
64
+ findings, basis.prior_decided.moved(moves))
65
65
  end
66
66
 
67
+ # What the audit a correction resumes began from, its assessment read back from the record it left (D87).
68
+ #: (Models::Audit, Models::CorrectionBasis, Hash[String, String], Models::MemberMoves) -> Models::AuditStart
69
+ def resumed(audit, basis, before, moves) = audit.resumed(basis, before, moves, @audit_records.find(audit.id))
70
+
67
71
  # The packaged answer guide, which the correction request prints, is the one owner of its samples, the text
68
72
  # the agent saw, so its sample for each action is handed to the model, which refuses a field given back as
69
73
  # its sample (#789). Should the tool be upgraded between request and answer, that answer is checked only
@@ -102,9 +106,12 @@ module Principles
102
106
  checked
103
107
  end
104
108
 
105
- #: (Models::DeclaredMapChanges, Models::CorrectionBasis) -> AuditCompletion
106
- def completion(map_changes, basis)
107
- handed(AuditCompletion, map_changes: map_changes, replacing: basis.printed_after)
109
+ # The completion of a correction, which read its assessment back from the audit's record: the open one or, for
110
+ # an identical retry, the completed one (D87).
111
+ #: (Models::DeclaredMapChanges, Models::CorrectionBasis, Models::Audit) -> AuditCompletion
112
+ def completion(map_changes, basis, audit)
113
+ handed(AuditCompletion, map_changes: map_changes, replacing: basis.printed_after,
114
+ read_back_from: @audit_records.find(audit.id))
108
115
  end
109
116
  end
110
117
  end
@@ -172,12 +172,17 @@ module Principles
172
172
  [@principles.file(@id), *map.members.map(&:path)]
173
173
  end
174
174
 
175
- # The request, with a notice when the last audit's record was left uncommitted.
175
+ # The request, with a notice when the last audit's record was left uncommitted: a completed one to commit, or an
176
+ # open one, which its correction completes, never to commit (D87).
176
177
  #: (Hash[String, untyped]) -> Hash[String, untyped]
177
178
  def with_record_notice(output)
178
179
  return output unless @base && uncommitted_record?
179
180
 
180
- output.merge("notice" => audit_result.uncommitted_record_notice(@audit_records.file(@id)))
181
+ file = @audit_records.file(@id)
182
+ record = @audit_records.find(@id)
183
+ left_open = record && !record.completed?
184
+ notice = left_open ? audit_result.open_record_notice(file) : audit_result.uncommitted_record_notice(file)
185
+ output.merge("notice" => notice)
181
186
  end
182
187
 
183
188
  # Whether the last audit's record exists but differs from the last commit, so it may be left behind.