okstra 0.229.0 → 0.230.0
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.
- package/README.md +1 -5
- package/dist/cli-registry.mjs +0 -18
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/lifecycle/doctor.mjs +0 -15
- package/dist/commands/lifecycle/doctor.mjs.map +1 -1
- package/dist/lib/skill-catalog.mjs +4 -4
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +105 -16
- package/docs/architecture.md +13 -14
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +11 -18
- package/package.json +1 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/prompts/launch.template.md +5 -5
- package/runtime/prompts/lead/convergence.md +4 -4
- package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
- package/runtime/prompts/lead/phase-routing.md +1 -1
- package/runtime/prompts/lead/report-writer.md +3 -3
- package/runtime/prompts/lead/team-contract.md +3 -3
- package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
- package/runtime/python/okstra_ctl/cmux.py +4 -2
- package/runtime/python/okstra_ctl/code_review_census.py +194 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
- package/runtime/python/okstra_ctl/code_review_target.py +38 -2
- package/runtime/python/okstra_ctl/conformance.py +30 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
- package/runtime/python/okstra_ctl/correction_round.py +19 -13
- package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
- package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
- package/runtime/python/okstra_ctl/generated_input.py +21 -0
- package/runtime/python/okstra_ctl/ids.py +1 -41
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
- package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
- package/runtime/python/okstra_ctl/locks.py +28 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
- package/runtime/python/okstra_ctl/paths.py +75 -33
- package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
- package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
- package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
- package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
- package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
- package/runtime/python/okstra_ctl/process_group.py +26 -3
- package/runtime/python/okstra_ctl/qa_commands.py +5 -1
- package/runtime/python/okstra_ctl/recap.py +1 -2
- package/runtime/python/okstra_ctl/render.py +10 -2
- package/runtime/python/okstra_ctl/report_finalize.py +3 -3
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
- package/runtime/python/okstra_ctl/run.py +24 -20
- package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
- package/runtime/python/okstra_ctl/verification_capture.py +291 -0
- package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
- package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
- package/runtime/python/okstra_ctl/verification_generation.py +22 -12
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
- package/runtime/python/okstra_ctl/verification_target.py +10 -3
- package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
- package/runtime/python/okstra_ctl/wizard/render.py +2 -1
- package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
- package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
- package/runtime/python/okstra_ctl/worker_runner.py +1 -1
- package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
- package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
- package/runtime/skills/okstra-code-review/SKILL.md +7 -5
- package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
- package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +6 -6
- package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-setup/SKILL.md +2 -3
- package/runtime/validators/validate-run.py +110 -19
- package/docs/cli.md +0 -1060
- package/docs/container.md +0 -100
- package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
- package/docs/performance-improvement-plan-v2.md +0 -369
- package/runtime/python/okstra_ctl/container.py +0 -702
- package/runtime/python/okstra_ctl/rollup.py +0 -241
- package/runtime/python/okstra_ctl/usage_report.py +0 -362
- package/runtime/skills/okstra-container-build/SKILL.md +0 -139
- package/runtime/skills/okstra-inspect/SKILL.md +0 -100
- package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
- package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
- package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
- package/runtime/skills/okstra-inspect/facets/history.md +0 -86
- package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
- package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
- package/runtime/skills/okstra-inspect/facets/report.md +0 -57
- package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
- package/runtime/skills/okstra-inspect/facets/status.md +0 -163
- package/runtime/skills/okstra-inspect/facets/time.md +0 -57
- package/runtime/skills/okstra-rollup/SKILL.md +0 -75
- package/runtime/skills/okstra-usage/SKILL.md +0 -71
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""Build a code-review census from a diff, so membership stays mechanical."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import ast
|
|
5
|
+
import re
|
|
6
|
+
import subprocess
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from pathlib import Path, PurePosixPath
|
|
9
|
+
|
|
10
|
+
from .code_review_coverage import read_review_census
|
|
11
|
+
|
|
12
|
+
_GROUPS = ("structural", "semantic", "state-and-tests", "general")
|
|
13
|
+
_FILE_GROUPS = {
|
|
14
|
+
"source": ("structural", "state-and-tests", "general"),
|
|
15
|
+
"test": ("state-and-tests",),
|
|
16
|
+
}
|
|
17
|
+
_ALWAYS_CENSUSED = ("skills/", "prompts/", "agents/", "templates/")
|
|
18
|
+
_LOCKFILES = {
|
|
19
|
+
"package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock",
|
|
20
|
+
"Cargo.lock", "uv.lock", "Gemfile.lock", "composer.lock",
|
|
21
|
+
}
|
|
22
|
+
_GENERATED_ROOTS = ("dist/", "runtime/", "build/")
|
|
23
|
+
_DATA_SUFFIXES = {".json", ".yml", ".yaml", ".toml", ".ini", ".cfg", ".csv"}
|
|
24
|
+
_PROSE_SUFFIXES = {".md", ".markdown", ".rst", ".txt"}
|
|
25
|
+
_UNPARSED_CODE_SUFFIXES = {
|
|
26
|
+
".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".sh", ".bash",
|
|
27
|
+
".go", ".rs", ".java", ".kt", ".kts", ".rb", ".php", ".swift", ".c", ".h",
|
|
28
|
+
".cc", ".cpp", ".hpp", ".cs", ".scala",
|
|
29
|
+
}
|
|
30
|
+
_TEST_PATH = re.compile(
|
|
31
|
+
r"(^|/)(tests?|spec|__tests__)/|(^|/)test_[^/]+\.py$|_test\.[^/]+$"
|
|
32
|
+
r"|\.(test|spec)\.[^/]+$"
|
|
33
|
+
)
|
|
34
|
+
_POSITION = re.compile(r":\d+(?::\d+)?(?= )")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class CensusResult:
|
|
39
|
+
text: str
|
|
40
|
+
unresolved: tuple[str, ...]
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def build_review_census(
|
|
44
|
+
repo: Path, base: str, head: str, rules_source: Path,
|
|
45
|
+
changed: dict[str, set[int]], *, previous: Path | None = None,
|
|
46
|
+
) -> CensusResult:
|
|
47
|
+
rules = _rules_section(rules_source.read_text(encoding="utf-8"))
|
|
48
|
+
files = _changed_files(repo, base, head)
|
|
49
|
+
cells: list[tuple[str, str]] = []
|
|
50
|
+
exclusions: list[tuple[str, str]] = []
|
|
51
|
+
unresolved: list[str] = []
|
|
52
|
+
functions: list[str] = []
|
|
53
|
+
for path, binary in files:
|
|
54
|
+
reason = _exclusion(path, binary)
|
|
55
|
+
if reason:
|
|
56
|
+
exclusions.append((path, reason))
|
|
57
|
+
continue
|
|
58
|
+
kind = "test" if _TEST_PATH.search(path) else "source"
|
|
59
|
+
cells.extend((path, group) for group in _FILE_GROUPS[kind])
|
|
60
|
+
if kind == "test" or path not in changed:
|
|
61
|
+
continue
|
|
62
|
+
suffix = PurePosixPath(path).suffix
|
|
63
|
+
if suffix == ".py":
|
|
64
|
+
functions.extend(_changed_functions(repo, head, path, changed[path]))
|
|
65
|
+
elif suffix in _UNPARSED_CODE_SUFFIXES:
|
|
66
|
+
unresolved.append(path)
|
|
67
|
+
cells.extend((target, "semantic") for target in functions)
|
|
68
|
+
ordered = sorted(cells, key=lambda cell: _GROUPS.index(cell[1]))
|
|
69
|
+
ids, retired, new = _assign_ids(ordered, previous)
|
|
70
|
+
text = _render(rules, ordered, ids, exclusions, files, unresolved, retired, new,
|
|
71
|
+
previous is not None)
|
|
72
|
+
return CensusResult(text, tuple(unresolved))
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _rules_section(text: str) -> str:
|
|
76
|
+
start = text.find("## Rules")
|
|
77
|
+
if start < 0:
|
|
78
|
+
raise ValueError("rules source has no ## Rules table")
|
|
79
|
+
end = text.find("\n## ", start + 1)
|
|
80
|
+
return text[start:] if end < 0 else text[start:end + 1]
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _changed_files(repo: Path, base: str, head: str) -> list[tuple[str, bool]]:
|
|
84
|
+
listed = subprocess.run(
|
|
85
|
+
["git", "-C", str(repo), "diff", "--numstat", "-z", "-M", "--no-ext-diff",
|
|
86
|
+
f"{base}..{head}", "--"],
|
|
87
|
+
capture_output=True, check=True,
|
|
88
|
+
).stdout.decode("utf-8", "surrogateescape").split("\0")
|
|
89
|
+
files: list[tuple[str, bool]] = []
|
|
90
|
+
entries = iter(listed)
|
|
91
|
+
for entry in entries:
|
|
92
|
+
if not entry:
|
|
93
|
+
continue
|
|
94
|
+
added, _, rest = entry.partition("\t")
|
|
95
|
+
_deleted, _, path = rest.partition("\t")
|
|
96
|
+
if not path:
|
|
97
|
+
next(entries)
|
|
98
|
+
path = next(entries)
|
|
99
|
+
files.append((path, added == "-"))
|
|
100
|
+
return files
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _exclusion(path: str, binary: bool) -> str | None:
|
|
104
|
+
if path.startswith(_ALWAYS_CENSUSED):
|
|
105
|
+
return None
|
|
106
|
+
name = PurePosixPath(path).name
|
|
107
|
+
suffix = PurePosixPath(path).suffix.lower()
|
|
108
|
+
if name in _LOCKFILES or name.endswith(".sum"):
|
|
109
|
+
return "lockfile"
|
|
110
|
+
if path.startswith(_GENERATED_ROOTS):
|
|
111
|
+
return "generated build output"
|
|
112
|
+
if binary:
|
|
113
|
+
return "binary file"
|
|
114
|
+
if suffix in _DATA_SUFFIXES:
|
|
115
|
+
return "configuration or data without executable project code"
|
|
116
|
+
if suffix in _PROSE_SUFFIXES:
|
|
117
|
+
return "prose documentation without executable or agent-directive content"
|
|
118
|
+
return None
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _changed_functions(
|
|
122
|
+
repo: Path, head: str, path: str, lines: set[int],
|
|
123
|
+
) -> list[str]:
|
|
124
|
+
source = subprocess.run(
|
|
125
|
+
["git", "-C", str(repo), "show", f"{head}:{path}"],
|
|
126
|
+
capture_output=True, check=True,
|
|
127
|
+
).stdout.decode("utf-8")
|
|
128
|
+
touched: list[str] = []
|
|
129
|
+
|
|
130
|
+
def visit(node: ast.AST, prefix: str) -> None:
|
|
131
|
+
for child in ast.iter_child_nodes(node):
|
|
132
|
+
if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
133
|
+
start = min([child.lineno, *(d.lineno for d in child.decorator_list)])
|
|
134
|
+
if lines.intersection(range(start, (child.end_lineno or start) + 1)):
|
|
135
|
+
touched.append(f"{path}:{child.lineno} {prefix}{child.name}")
|
|
136
|
+
visit(child, f"{prefix}{child.name}.")
|
|
137
|
+
elif isinstance(child, ast.ClassDef):
|
|
138
|
+
visit(child, f"{prefix}{child.name}.")
|
|
139
|
+
|
|
140
|
+
visit(ast.parse(source, filename=path), "")
|
|
141
|
+
return touched
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _identity(target: str, group: str) -> tuple[str, str]:
|
|
145
|
+
return _POSITION.sub("", target, count=1), group
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _assign_ids(
|
|
149
|
+
cells: list[tuple[str, str]], previous: Path | None,
|
|
150
|
+
) -> tuple[list[str], list[str], list[str]]:
|
|
151
|
+
known: dict[tuple[str, str], str] = {}
|
|
152
|
+
highest = 0
|
|
153
|
+
if previous is not None:
|
|
154
|
+
old = read_review_census(previous)
|
|
155
|
+
for identity, cell in old.cells.items():
|
|
156
|
+
known[_identity(cell.target, cell.group)] = identity
|
|
157
|
+
highest = max(highest, int(identity.removeprefix("C-CR-")))
|
|
158
|
+
ids: list[str] = []
|
|
159
|
+
new: list[str] = []
|
|
160
|
+
for target, group in cells:
|
|
161
|
+
identity = known.pop(_identity(target, group), None)
|
|
162
|
+
if identity is None:
|
|
163
|
+
highest += 1
|
|
164
|
+
identity = f"C-CR-{highest:04d}"
|
|
165
|
+
new.append(identity)
|
|
166
|
+
ids.append(identity)
|
|
167
|
+
return ids, sorted(known.values()), new
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _render(
|
|
171
|
+
rules: str, cells: list[tuple[str, str]], ids: list[str],
|
|
172
|
+
exclusions: list[tuple[str, str]], files: list[tuple[str, bool]],
|
|
173
|
+
unresolved: list[str], retired: list[str], new: list[str], has_previous: bool,
|
|
174
|
+
) -> str:
|
|
175
|
+
rows = [rules.rstrip("\n"), "", "## Cells"]
|
|
176
|
+
rows += ["| Cell | Target | Group |", "|---|---|---|"]
|
|
177
|
+
rows += [f"| {cell_id} | {target} | {group} |"
|
|
178
|
+
for cell_id, (target, group) in zip(ids, cells)]
|
|
179
|
+
rows += ["", "## Exclusions"]
|
|
180
|
+
rows += [f"- `{path}`: {reason}." for path, reason in exclusions] or ["- none"]
|
|
181
|
+
censused = len({target.partition(":")[0] for target, _ in cells})
|
|
182
|
+
rows += [
|
|
183
|
+
"", "## Accounting",
|
|
184
|
+
f"- Changed files: {len(files)}; censused: {censused}; "
|
|
185
|
+
f"excluded: {len(exclusions)}",
|
|
186
|
+
"- Unresolved function boundaries: " + (", ".join(unresolved) or "-"),
|
|
187
|
+
]
|
|
188
|
+
if has_previous:
|
|
189
|
+
rows += [
|
|
190
|
+
"", "## Changes from previous census",
|
|
191
|
+
"- Retired: " + (", ".join(retired) or "-"),
|
|
192
|
+
"- New: " + (", ".join(new) or "-"),
|
|
193
|
+
]
|
|
194
|
+
return "\n".join(rows) + "\n"
|
|
@@ -26,7 +26,9 @@ class ReviewCensus:
|
|
|
26
26
|
|
|
27
27
|
|
|
28
28
|
def _table_fields(line: str) -> list[str]:
|
|
29
|
-
|
|
29
|
+
# Markdown writes a literal pipe inside a table cell as `\|`.
|
|
30
|
+
fields = re.split(r"(?<!\\)\|", line.strip().strip("|"))
|
|
31
|
+
return [field.strip().replace("\\|", "|") for field in fields]
|
|
30
32
|
|
|
31
33
|
|
|
32
34
|
def read_review_census(path: Path) -> ReviewCensus:
|
|
@@ -111,8 +111,8 @@ def review_scope(
|
|
|
111
111
|
return full("rule catalog changed")
|
|
112
112
|
verdicts = check_review_coverage(root, previous_census, completions, prior.commit,
|
|
113
113
|
base=base_commit)
|
|
114
|
-
if verdicts.
|
|
115
|
-
return full("previous review
|
|
114
|
+
if verdicts.unknown:
|
|
115
|
+
return full("previous review names unknown cells")
|
|
116
116
|
try:
|
|
117
117
|
dependencies = _prior_inputs(
|
|
118
118
|
root, completions, old,
|
|
@@ -139,16 +139,19 @@ def _partition(
|
|
|
139
139
|
known = set().union(*dependencies.values()) if dependencies else set()
|
|
140
140
|
unknown = changed - known
|
|
141
141
|
carry = []
|
|
142
|
+
# A changed path outside every recorded inventory reopens only the cells that
|
|
143
|
+
# list it; reviewers still search the delta for effects the inventory missed.
|
|
142
144
|
for identity, cell in census.cells.items():
|
|
143
145
|
sources = dependencies.get(identity, set())
|
|
144
146
|
target = cell.target.partition(":")[0]
|
|
145
|
-
if (
|
|
147
|
+
if (old.cells.get(identity) == cell and target in sources
|
|
146
148
|
and not changed.intersection(sources)
|
|
147
149
|
and verdicts.get(identity, ("missing", ""))[0] in ("clean", "n/a")):
|
|
148
150
|
carry.append(identity)
|
|
149
|
-
reason =
|
|
150
|
-
|
|
151
|
-
|
|
151
|
+
reason = "review changed dependencies, prior findings and unverified cells"
|
|
152
|
+
if unknown:
|
|
153
|
+
reason += "; search unmapped changed inputs: " + ", ".join(sorted(unknown))
|
|
154
|
+
reason += "; attest carry boundaries"
|
|
152
155
|
carry_ids = set(carry)
|
|
153
156
|
return ReviewScope(
|
|
154
157
|
baseline,
|
|
@@ -107,6 +107,9 @@ instead of a checked-out tree. This is read-only — it never creates
|
|
|
107
107
|
directories or files. `check-coverage` reads head evidence at `--head` and explicit
|
|
108
108
|
base evidence at `--base`, never the working tree, prints covered cells, missing rules and unknown cells, and exits
|
|
109
109
|
1 for incomplete coverage and 2 for invalid input or completion evidence.
|
|
110
|
+
`census` writes the range's census to `--out`, copying the Rules table from
|
|
111
|
+
`--rules` and keeping IDs from `--previous-census`; it exits 1 when changed
|
|
112
|
+
non-Python code still needs function cells added by hand.
|
|
110
113
|
"""
|
|
111
114
|
|
|
112
115
|
|
|
@@ -117,7 +120,10 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
117
120
|
prog="okstra code-review",
|
|
118
121
|
description="Resolve a code review's diff range and result file path, or check finding citations."
|
|
119
122
|
)
|
|
120
|
-
parser.add_argument(
|
|
123
|
+
parser.add_argument(
|
|
124
|
+
"command",
|
|
125
|
+
choices=("target", "check-lines", "check-coverage", "scope", "census"),
|
|
126
|
+
)
|
|
121
127
|
parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
|
|
122
128
|
parser.add_argument("--stage", type=int, default=0, help="stage number to review")
|
|
123
129
|
parser.add_argument("--branch", default="", help="branch to review")
|
|
@@ -138,7 +144,11 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
138
144
|
parser.add_argument("--completion", action="append", default=[],
|
|
139
145
|
help="check-coverage: verified reviewer completion (repeat for gap-fills)")
|
|
140
146
|
parser.add_argument("--previous-head", default="", help="scope: previous reviewed commit")
|
|
141
|
-
parser.add_argument("--previous-census", default="",
|
|
147
|
+
parser.add_argument("--previous-census", default="",
|
|
148
|
+
help="scope, census: previous full census")
|
|
149
|
+
parser.add_argument("--rules", default="",
|
|
150
|
+
help="census: file whose ## Rules table the census copies")
|
|
151
|
+
parser.add_argument("--out", default="", help="census: file to write the census to")
|
|
142
152
|
parser.add_argument("--policy", action="append", default=[],
|
|
143
153
|
help="scope: policy/calibration source to fingerprint (repeatable)")
|
|
144
154
|
parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
|
|
@@ -341,6 +351,8 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
341
351
|
|
|
342
352
|
if args.command == "scope":
|
|
343
353
|
return _scope(args, Path(project_root))
|
|
354
|
+
if args.command == "census":
|
|
355
|
+
return _census(args, Path(project_root))
|
|
344
356
|
if args.command == "check-coverage":
|
|
345
357
|
return _check_coverage(args, Path(project_root))
|
|
346
358
|
if args.command == "check-lines":
|
|
@@ -370,6 +382,30 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
370
382
|
return 0
|
|
371
383
|
|
|
372
384
|
|
|
385
|
+
def _census(args: argparse.Namespace, project_root: Path) -> int:
|
|
386
|
+
from .code_review_census import build_review_census
|
|
387
|
+
from .code_review_coverage import read_review_census
|
|
388
|
+
|
|
389
|
+
if not (args.base and args.head and args.rules and args.out):
|
|
390
|
+
print("census: pass --base, --head, --rules and --out", file=sys.stderr)
|
|
391
|
+
return 2
|
|
392
|
+
try:
|
|
393
|
+
result = build_review_census(
|
|
394
|
+
project_root, args.base, args.head, Path(args.rules),
|
|
395
|
+
changed_lines(project_root, args.base, args.head),
|
|
396
|
+
previous=Path(args.previous_census) if args.previous_census else None,
|
|
397
|
+
)
|
|
398
|
+
out = Path(args.out)
|
|
399
|
+
out.write_text(result.text, encoding="utf-8")
|
|
400
|
+
read_review_census(out)
|
|
401
|
+
except (OSError, ValueError, SyntaxError, StateError,
|
|
402
|
+
subprocess.CalledProcessError) as exc:
|
|
403
|
+
print(f"census: {exc}", file=sys.stderr)
|
|
404
|
+
return 2
|
|
405
|
+
print(result.text, end="")
|
|
406
|
+
return 1 if result.unresolved else 0
|
|
407
|
+
|
|
408
|
+
|
|
373
409
|
def _scope(args: argparse.Namespace, project_root: Path) -> int:
|
|
374
410
|
from .agent.invocation import AgentInvocationError
|
|
375
411
|
from .code_review_scope import review_scope
|
|
@@ -16,8 +16,10 @@ import fnmatch
|
|
|
16
16
|
import re
|
|
17
17
|
from dataclasses import dataclass
|
|
18
18
|
from pathlib import Path
|
|
19
|
+
from typing import Any, Mapping
|
|
19
20
|
|
|
20
21
|
from .qa_commands import verification_command_defects
|
|
22
|
+
from .qa_procedures import content_digest
|
|
21
23
|
|
|
22
24
|
# diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
|
|
23
25
|
CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
|
|
@@ -476,6 +478,34 @@ def parse_qa_result(stdout: str) -> QaResult:
|
|
|
476
478
|
return QaResult(overall=overall, requirements=requirements)
|
|
477
479
|
|
|
478
480
|
|
|
481
|
+
def execution_evidence_defect(record: Mapping[str, Any], stdout: bytes) -> str | None:
|
|
482
|
+
"""Why an evidence-mode execution record cannot back a result; None when it can."""
|
|
483
|
+
if record.get("status") != "completed":
|
|
484
|
+
return f"status is {record.get('status')}"
|
|
485
|
+
stream = record.get("stdout")
|
|
486
|
+
if (not isinstance(stream, Mapping) or stream.get("bytes") != len(stdout)
|
|
487
|
+
or stream.get("digest") != content_digest(stdout)):
|
|
488
|
+
return "saved stdout is not the output the record observed"
|
|
489
|
+
return None
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
def qa_result_from_execution(
|
|
493
|
+
record: Mapping[str, Any], stdout: bytes,
|
|
494
|
+
) -> QaResult | None:
|
|
495
|
+
"""Derive one stage's result from an evidence-mode execution record.
|
|
496
|
+
|
|
497
|
+
None means no usable evidence; `execution_evidence_defect` says why.
|
|
498
|
+
"""
|
|
499
|
+
if execution_evidence_defect(record, stdout) is not None:
|
|
500
|
+
return None
|
|
501
|
+
result = parse_qa_result(stdout.decode("utf-8", errors="replace"))
|
|
502
|
+
# The marker is the script's claim; the observed exit is the runner's. A
|
|
503
|
+
# signalled run records no exit code, so it is never zero here either.
|
|
504
|
+
if result.overall == "PASS" and record.get("exitCode") != 0:
|
|
505
|
+
return QaResult(overall="FAIL", requirements=result.requirements)
|
|
506
|
+
return result
|
|
507
|
+
|
|
508
|
+
|
|
479
509
|
@dataclass
|
|
480
510
|
class ConformanceVerdict:
|
|
481
511
|
stage_key: str
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
"""Select the verification execution records that decide stage conformance.
|
|
2
|
+
|
|
3
|
+
Each stage is decided by the newest sealed generation that lists it. An
|
|
4
|
+
implementation run takes the result from the stage QA owner only; final
|
|
5
|
+
verification needs a PASS from every verifier it dispatched.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Iterable, Mapping
|
|
12
|
+
|
|
13
|
+
from .agent.invocation import AgentInvocationError
|
|
14
|
+
from .conformance import QaResult, execution_evidence_defect, qa_result_from_execution
|
|
15
|
+
from .execution_identity import ExecutionManifest, Invocation
|
|
16
|
+
from .execution_manifest import read_execution_manifest
|
|
17
|
+
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
18
|
+
from .paths import RunRef
|
|
19
|
+
from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
|
|
20
|
+
from .qa_procedures import content_digest
|
|
21
|
+
from .verification_conformance import conformance_stage
|
|
22
|
+
from .verification_dispatch import verification_generation_number
|
|
23
|
+
from .verification_evidence import (
|
|
24
|
+
conformance_check_owner_ref, read_verification_execution_record,
|
|
25
|
+
)
|
|
26
|
+
from .verification_generation import (
|
|
27
|
+
VerificationGenerationRecord, read_verification_generation,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True)
|
|
32
|
+
class StageEvidence:
|
|
33
|
+
"""`records` are the latest record files examined for this stage, including
|
|
34
|
+
the `rejections`: records that are no usable evidence, with the reason."""
|
|
35
|
+
|
|
36
|
+
result: QaResult | None
|
|
37
|
+
records: tuple[Path, ...]
|
|
38
|
+
rejections: Mapping[Path, str] = field(default_factory=dict)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True)
|
|
42
|
+
class RunConformanceEvidence:
|
|
43
|
+
"""`stages` are the conformance stages a bound verifier generation requires."""
|
|
44
|
+
|
|
45
|
+
stages: frozenset[int]
|
|
46
|
+
results: Mapping[str, StageEvidence]
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass(frozen=True)
|
|
50
|
+
class _VerifierOutcome:
|
|
51
|
+
result: QaResult | None
|
|
52
|
+
record: Path | None = None
|
|
53
|
+
rejection: str | None = None
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
_NO_OUTCOME = _VerifierOutcome(None)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class _BoundInvocation:
|
|
61
|
+
"""One verifier invocation and the generation its dispatch kind seals."""
|
|
62
|
+
|
|
63
|
+
invocation: Invocation
|
|
64
|
+
generation_number: int
|
|
65
|
+
index: int
|
|
66
|
+
generation: VerificationGenerationRecord | None
|
|
67
|
+
generation_ref: dict[str, str]
|
|
68
|
+
|
|
69
|
+
def seals(self, stage: int) -> bool:
|
|
70
|
+
return (self.generation is not None
|
|
71
|
+
and stage in self.generation.get("conformanceStages", ()))
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def collect_conformance_evidence(
|
|
75
|
+
project: Path, manifest_path: Path, stage_keys: Iterable[str],
|
|
76
|
+
) -> RunConformanceEvidence:
|
|
77
|
+
try:
|
|
78
|
+
return _collect(project.resolve(), manifest_path.resolve(), tuple(stage_keys))
|
|
79
|
+
except (AgentInvocationError, OSError) as exc:
|
|
80
|
+
raise ValueError(str(exc)) from exc
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _collect(
|
|
84
|
+
project: Path, manifest_path: Path, stage_keys: tuple[str, ...],
|
|
85
|
+
) -> RunConformanceEvidence:
|
|
86
|
+
manifest = load_owned_object(manifest_path, artifact="run manifest")
|
|
87
|
+
ref = RunRef.from_manifest(manifest_path, manifest)
|
|
88
|
+
audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(manifest.get("taskType"))
|
|
89
|
+
if audience is None:
|
|
90
|
+
raise ValueError("verification evidence requires a QA-executing run")
|
|
91
|
+
execution = read_execution_manifest(manifest_path)
|
|
92
|
+
verifiers = _bound_verifiers(project, ref, execution, audience)
|
|
93
|
+
owner = conformance_check_owner_ref(manifest)
|
|
94
|
+
counted = list(verifiers) if owner is None else [owner]
|
|
95
|
+
latest_attempt = _latest_attempts(execution)
|
|
96
|
+
return RunConformanceEvidence(_required_stages(verifiers), {
|
|
97
|
+
key: _stage_evidence(ref, verifiers, counted, key, latest_attempt)
|
|
98
|
+
for key in stage_keys
|
|
99
|
+
})
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _stage_evidence(
|
|
103
|
+
ref: RunRef, verifiers: Mapping[str, list[_BoundInvocation]],
|
|
104
|
+
counted: list[str], stage_key: str, latest_attempt: Mapping[str, int],
|
|
105
|
+
) -> StageEvidence:
|
|
106
|
+
"""A counted verifier with no invocation bound to the newest generation that
|
|
107
|
+
seals the stage leaves it without a result; an older generation's record
|
|
108
|
+
observed the work before the round that sealed the newer one."""
|
|
109
|
+
try:
|
|
110
|
+
stage = conformance_stage(stage_key)
|
|
111
|
+
except ValueError:
|
|
112
|
+
# expected-miss: a malformed key names no stage a generation can seal,
|
|
113
|
+
# so no record can exist for it.
|
|
114
|
+
return StageEvidence(None, ())
|
|
115
|
+
newest = max((binding.generation_number for bindings in verifiers.values()
|
|
116
|
+
for binding in bindings if binding.seals(stage)), default=None)
|
|
117
|
+
if newest is None:
|
|
118
|
+
return StageEvidence(None, ())
|
|
119
|
+
return _combine([
|
|
120
|
+
_verifier_result(ref, role_execution_ref, verifiers.get(role_execution_ref, []),
|
|
121
|
+
newest, stage_key, latest_attempt)
|
|
122
|
+
for role_execution_ref in counted
|
|
123
|
+
])
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def _bound_verifiers(
|
|
127
|
+
project: Path, ref: RunRef, execution: ExecutionManifest, audience: str,
|
|
128
|
+
) -> dict[str, list[_BoundInvocation]]:
|
|
129
|
+
"""Each verifier's invocations, newest first."""
|
|
130
|
+
verifiers: dict[str, list[_BoundInvocation]] = {}
|
|
131
|
+
for index, invocation in enumerate(execution.invocations):
|
|
132
|
+
if invocation.duty_id == audience:
|
|
133
|
+
verifiers.setdefault(invocation.role_execution_ref, []).append(
|
|
134
|
+
_bind(project, ref, invocation, index),
|
|
135
|
+
)
|
|
136
|
+
for bindings in verifiers.values():
|
|
137
|
+
bindings.sort(key=lambda binding: (binding.generation_number, binding.index),
|
|
138
|
+
reverse=True)
|
|
139
|
+
return verifiers
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _latest_attempts(execution: ExecutionManifest) -> dict[str, int]:
|
|
143
|
+
latest: dict[str, int] = {}
|
|
144
|
+
for row in execution.attempts:
|
|
145
|
+
latest[row.invocation_ref] = max(row.attempt, latest.get(row.invocation_ref, 0))
|
|
146
|
+
return latest
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _required_stages(verifiers: Mapping[str, list[_BoundInvocation]]) -> frozenset[int]:
|
|
150
|
+
return frozenset(
|
|
151
|
+
stage for bindings in verifiers.values() for binding in bindings
|
|
152
|
+
if binding.generation is not None
|
|
153
|
+
for stage in binding.generation.get("conformanceStages", ())
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _bind(
|
|
158
|
+
project: Path, ref: RunRef, invocation: Invocation, index: int,
|
|
159
|
+
) -> _BoundInvocation:
|
|
160
|
+
number = verification_generation_number(invocation.dispatch_kind)
|
|
161
|
+
path = ref.verification_generation(number)
|
|
162
|
+
relative = path.relative_to(project).as_posix()
|
|
163
|
+
if not path.is_file():
|
|
164
|
+
return _BoundInvocation(invocation, number, index, None,
|
|
165
|
+
{"path": relative, "digest": ""})
|
|
166
|
+
digest = content_digest(path.read_bytes())
|
|
167
|
+
return _BoundInvocation(invocation, number, index,
|
|
168
|
+
read_verification_generation(path, digest),
|
|
169
|
+
{"path": relative, "digest": digest})
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _verifier_result(
|
|
173
|
+
ref: RunRef, role_execution_ref: str, bindings: list[_BoundInvocation],
|
|
174
|
+
generation_number: int, stage_key: str, latest_attempt: Mapping[str, int],
|
|
175
|
+
) -> _VerifierOutcome:
|
|
176
|
+
chosen = next((binding for binding in bindings if binding.generation is not None
|
|
177
|
+
and binding.generation_number == generation_number), None)
|
|
178
|
+
if chosen is None:
|
|
179
|
+
return _NO_OUTCOME
|
|
180
|
+
invocation_ref = chosen.invocation.invocation_ref
|
|
181
|
+
attempt = latest_attempt.get(invocation_ref)
|
|
182
|
+
if attempt is None:
|
|
183
|
+
return _NO_OUTCOME
|
|
184
|
+
check_ref = f"conformance:{stage_key}"
|
|
185
|
+
check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref)
|
|
186
|
+
if check_run is None:
|
|
187
|
+
return _NO_OUTCOME
|
|
188
|
+
run_dir = ref.verification_execution_dir(
|
|
189
|
+
invocation_ref, attempt, check_ref, check_run,
|
|
190
|
+
)
|
|
191
|
+
expected = {
|
|
192
|
+
"invocationRef": invocation_ref, "roleExecutionRef": role_execution_ref,
|
|
193
|
+
"attempt": attempt, "checkRef": check_ref, "checkRun": check_run,
|
|
194
|
+
"verificationGeneration": chosen.generation_ref,
|
|
195
|
+
}
|
|
196
|
+
record_path = run_dir / "record.json"
|
|
197
|
+
result, rejection = _recorded_result(run_dir, expected)
|
|
198
|
+
return _VerifierOutcome(result, record_path, rejection)
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def _recorded_result(
|
|
202
|
+
run_dir: Path, expected: Mapping[str, object],
|
|
203
|
+
) -> tuple[QaResult | None, str | None]:
|
|
204
|
+
try:
|
|
205
|
+
record = read_verification_execution_record(run_dir / "record.json")
|
|
206
|
+
except (JsonBoundaryError, OSError) as exc:
|
|
207
|
+
return None, f"record is unreadable ({exc})"
|
|
208
|
+
if any(record[name] != value for name, value in expected.items()):
|
|
209
|
+
return None, ("record identity, attempt, check run or generation differs "
|
|
210
|
+
"from its location")
|
|
211
|
+
try:
|
|
212
|
+
output = (run_dir / "stdout.log").read_bytes()
|
|
213
|
+
except OSError as exc:
|
|
214
|
+
return None, f"saved stdout is unreadable ({exc})"
|
|
215
|
+
defect = execution_evidence_defect(record, output)
|
|
216
|
+
if defect is not None:
|
|
217
|
+
return None, defect
|
|
218
|
+
return qa_result_from_execution(record, output), None
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _combine(outcomes: list[_VerifierOutcome]) -> StageEvidence:
|
|
222
|
+
records = tuple(outcome.record for outcome in outcomes if outcome.record is not None)
|
|
223
|
+
rejections = {outcome.record: outcome.rejection for outcome in outcomes
|
|
224
|
+
if outcome.record is not None and outcome.rejection is not None}
|
|
225
|
+
values = [outcome.result for outcome in outcomes]
|
|
226
|
+
if not values:
|
|
227
|
+
return StageEvidence(None, records, rejections)
|
|
228
|
+
for overall in ("FAIL", "MISSING"):
|
|
229
|
+
found = next((result for result in values
|
|
230
|
+
if result is not None and result.overall == overall), None)
|
|
231
|
+
if found is not None:
|
|
232
|
+
return StageEvidence(found, records, rejections)
|
|
233
|
+
if any(result is None for result in values):
|
|
234
|
+
return StageEvidence(None, records, rejections)
|
|
235
|
+
return StageEvidence(values[0], records, rejections)
|
|
@@ -13,7 +13,7 @@ import re
|
|
|
13
13
|
from pathlib import Path
|
|
14
14
|
from typing import Mapping, Sequence
|
|
15
15
|
|
|
16
|
-
from .execution_identity import ExecutionManifest
|
|
16
|
+
from .execution_identity import Attempt, ExecutionManifest
|
|
17
17
|
from .file_size_cap import FILE_LINE_LIMIT, FileSizeViolation
|
|
18
18
|
from .json_boundary import load_owned_object
|
|
19
19
|
|
|
@@ -72,6 +72,23 @@ def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_n
|
|
|
72
72
|
return f"-{scope}-reverify-r{round_number}-" in invocation_ref
|
|
73
73
|
|
|
74
74
|
|
|
75
|
+
def completed_round_attempts(
|
|
76
|
+
manifest: ExecutionManifest, round_number: int | None, role: str,
|
|
77
|
+
) -> list[Attempt]:
|
|
78
|
+
"""Finished `ok` attempts of `role` in correction round N (None: initial)."""
|
|
79
|
+
roles = {row.role_execution_ref: row.role for row in manifest.role_executions}
|
|
80
|
+
invocations = {
|
|
81
|
+
row.invocation_ref for row in manifest.invocations
|
|
82
|
+
if correction_round(row.dispatch_kind) == round_number
|
|
83
|
+
and roles.get(row.role_execution_ref) == role
|
|
84
|
+
}
|
|
85
|
+
return [
|
|
86
|
+
row for row in manifest.attempts
|
|
87
|
+
if row.invocation_ref in invocations
|
|
88
|
+
and row.finished_at is not None and row.status == "ok"
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
|
|
75
92
|
def validate_correction_dispatch(
|
|
76
93
|
manifest: ExecutionManifest, jobs: Sequence[object],
|
|
77
94
|
) -> None:
|
|
@@ -82,19 +99,8 @@ def validate_correction_dispatch(
|
|
|
82
99
|
verifier reads a tree the fix has not reached, as the executor/verifier batch split
|
|
83
100
|
already guards for the initial round.
|
|
84
101
|
"""
|
|
85
|
-
roles = {row.role_execution_ref: row.role for row in manifest.role_executions}
|
|
86
|
-
finished_ok = {
|
|
87
|
-
row.invocation_ref for row in manifest.attempts
|
|
88
|
-
if row.finished_at is not None and row.status == "ok"
|
|
89
|
-
}
|
|
90
|
-
|
|
91
102
|
def completed(round_number: int, role: str) -> bool:
|
|
92
|
-
return
|
|
93
|
-
correction_round(row.dispatch_kind) == round_number
|
|
94
|
-
and roles.get(row.role_execution_ref) == role
|
|
95
|
-
and row.invocation_ref in finished_ok
|
|
96
|
-
for row in manifest.invocations
|
|
97
|
-
)
|
|
103
|
+
return bool(completed_round_attempts(manifest, round_number, role))
|
|
98
104
|
|
|
99
105
|
for job in jobs:
|
|
100
106
|
round_number = correction_round(getattr(job, "dispatch_kind", ""))
|
|
@@ -2506,7 +2506,7 @@ def _record_wrapper_failure(
|
|
|
2506
2506
|
and that Lead does not need to re-record it. Nothing did: no code path
|
|
2507
2507
|
anywhere called the error-log writer, so every wrapper failure vanished, and
|
|
2508
2508
|
with it the `instruction-set/prior-run-errors.md` digest the next run reads
|
|
2509
|
-
and the
|
|
2509
|
+
and the error report. The dispatcher is the only component
|
|
2510
2510
|
that holds the exit code, so it is the one that writes.
|
|
2511
2511
|
|
|
2512
2512
|
Never raises. Logging is bookkeeping around a dispatch that has already
|
|
@@ -133,6 +133,7 @@ WORKER_STATUSES = frozenset(
|
|
|
133
133
|
NON_TERMINAL_WORKER_STATUSES = frozenset({"in-progress"})
|
|
134
134
|
TERMINAL_WORKER_STATUSES = WORKER_STATUSES - NON_TERMINAL_WORKER_STATUSES
|
|
135
135
|
REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
|
|
136
|
+
UNSUCCESSFUL_WORKER_STATUSES = TERMINAL_WORKER_STATUSES - {"completed"}
|
|
136
137
|
|
|
137
138
|
|
|
138
139
|
def generate_claude_session_id() -> str:
|