okstra 0.231.1 → 0.233.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 +19 -271
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +88 -286
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +45 -25
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +53 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +67 -36
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +45 -20
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +107 -38
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
import json
|
|
5
|
+
from pathlib import Path, PurePosixPath
|
|
6
|
+
from typing import Mapping, Sequence, cast
|
|
7
|
+
|
|
8
|
+
from .json_boundary import load_owned_object
|
|
9
|
+
from .qa_procedures import canonical_json_digest, content_digest
|
|
10
|
+
from .qa_commands import QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid
|
|
11
|
+
from .paths import find_asset_root
|
|
12
|
+
from .verification_input_types import FrozenProcedure, FrozenReviewPolicy
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def capture_review_policy(
|
|
16
|
+
project: Path, config: Mapping[str, object], *, additional_sources: Sequence[Path] = (),
|
|
17
|
+
) -> FrozenReviewPolicy:
|
|
18
|
+
architecture = config.get("architecture", {})
|
|
19
|
+
if not isinstance(architecture, dict):
|
|
20
|
+
raise ValueError("review policy: architecture must be an object")
|
|
21
|
+
style = architecture.get("style", "undeclared")
|
|
22
|
+
if style not in ("undeclared", "none", "layered", "hexagonal"):
|
|
23
|
+
raise ValueError("review policy: invalid architecture style")
|
|
24
|
+
declared = config.get("reviewRulePacks", [])
|
|
25
|
+
if not isinstance(declared, list):
|
|
26
|
+
raise ValueError("review policy: reviewRulePacks must be a list")
|
|
27
|
+
paths = [project / name for name in ("AGENTS.md", "CLAUDE.md")
|
|
28
|
+
if (project / name).exists()]
|
|
29
|
+
paths.extend(additional_sources)
|
|
30
|
+
for entry in declared:
|
|
31
|
+
if not isinstance(entry, str) or not entry.strip():
|
|
32
|
+
raise ValueError("review policy: rule path must be a non-blank string")
|
|
33
|
+
path = Path(entry).expanduser()
|
|
34
|
+
if not path.is_absolute():
|
|
35
|
+
raise ValueError("review policy: rule path must be absolute")
|
|
36
|
+
paths.append(path)
|
|
37
|
+
sources: dict[str, FrozenProcedure] = {}
|
|
38
|
+
for path in dict.fromkeys(paths):
|
|
39
|
+
_capture_rule_source(path, sources)
|
|
40
|
+
root = find_asset_root(("prompts", "coding-preflight", "review-rules.json"))
|
|
41
|
+
if root is None:
|
|
42
|
+
raise ValueError("review policy: coding preflight catalog is unavailable")
|
|
43
|
+
pack = root / "prompts" / "coding-preflight"
|
|
44
|
+
for path in sorted(pack.rglob("*.md")):
|
|
45
|
+
_capture_rule_source(path, sources)
|
|
46
|
+
_capture_rule_source(pack / "review-rules.json", sources)
|
|
47
|
+
return {"schemaVersion": "1.0", "architecture": style, "sources": sources}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _capture_rule_source(path: Path, sources: dict[str, FrozenProcedure]) -> None:
|
|
51
|
+
identity = str(path.absolute())
|
|
52
|
+
if identity in sources:
|
|
53
|
+
return
|
|
54
|
+
try:
|
|
55
|
+
raw = path.read_bytes()
|
|
56
|
+
body = raw.decode("utf-8")
|
|
57
|
+
except (OSError, UnicodeError) as exc:
|
|
58
|
+
raise ValueError(f"review policy: cannot read {path}: {exc}") from exc
|
|
59
|
+
sources[identity] = {"body": body, "digest": content_digest(raw)}
|
|
60
|
+
for reference in re.findall(r"\]\((references/[^)\s#]+\.md)(?:#[^)]*)?\)", body):
|
|
61
|
+
relative = Path(reference)
|
|
62
|
+
if ".." in relative.parts:
|
|
63
|
+
raise ValueError(f"review policy: reference escapes rule directory: {reference}")
|
|
64
|
+
_capture_rule_source(path.parent / relative, sources)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def review_policy_errors(policy: object) -> list[str]:
|
|
68
|
+
required = {"schemaVersion", "architecture", "sources"}
|
|
69
|
+
if (not isinstance(policy, dict) or not required.issubset(policy)
|
|
70
|
+
or set(policy).difference(required | {"authorPolicyDigest"})):
|
|
71
|
+
return ["review policy: invalid fields"]
|
|
72
|
+
if "authorPolicyDigest" in policy and (
|
|
73
|
+
not isinstance(policy["authorPolicyDigest"], str)
|
|
74
|
+
or not QA_SOURCE_DIGEST_PATTERN.fullmatch(policy["authorPolicyDigest"])):
|
|
75
|
+
return ["review policy: invalid author policy digest"]
|
|
76
|
+
if policy["schemaVersion"] != "1.0":
|
|
77
|
+
return ["review policy: unsupported version"]
|
|
78
|
+
if policy["architecture"] not in ("undeclared", "none", "layered", "hexagonal"):
|
|
79
|
+
return ["review policy: invalid architecture style"]
|
|
80
|
+
sources = policy["sources"]
|
|
81
|
+
if not isinstance(sources, dict):
|
|
82
|
+
return ["review policy: sources must be an object"]
|
|
83
|
+
for path, source in sources.items():
|
|
84
|
+
if not isinstance(path, str) or not Path(path).is_absolute():
|
|
85
|
+
return ["review policy: source path must be absolute"]
|
|
86
|
+
if (not isinstance(source, dict) or set(source) != {"body", "digest"}
|
|
87
|
+
or not isinstance(source["body"], str)):
|
|
88
|
+
return ["review policy: invalid source"]
|
|
89
|
+
if content_digest(source["body"].encode("utf-8")) != source["digest"]:
|
|
90
|
+
return [f"review policy: source digest mismatch: {path}"]
|
|
91
|
+
return []
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def read_review_policy(path: Path) -> FrozenReviewPolicy:
|
|
95
|
+
return cast(FrozenReviewPolicy, load_owned_object(
|
|
96
|
+
path, artifact="frozen review policy", schema={"type": "object"},
|
|
97
|
+
validate_cross_fields=review_policy_errors,
|
|
98
|
+
))
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def publish_review_policy(
|
|
102
|
+
project: Path, destination: Path, policy: FrozenReviewPolicy,
|
|
103
|
+
) -> tuple[Path, str]:
|
|
104
|
+
from .verification_inputs import publish_verification_snapshot
|
|
105
|
+
|
|
106
|
+
return publish_verification_snapshot(
|
|
107
|
+
project, destination, capture=lambda: dict(policy), artifact="frozen review policy",
|
|
108
|
+
schema={"type": "object"}, validate_cross_fields=review_policy_errors,
|
|
109
|
+
comparison_key=dict,
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def code_review_guidance_paths(policy: FrozenReviewPolicy) -> tuple[str, ...]:
|
|
114
|
+
paths: list[str] = []
|
|
115
|
+
for source in policy["sources"]:
|
|
116
|
+
if source.endswith("/skills/okstra-code-review/SKILL.md"):
|
|
117
|
+
folder = Path(source).parent
|
|
118
|
+
paths.extend(str(path) for path in (
|
|
119
|
+
folder / "SKILL.md", folder / "references/census-rules.md",
|
|
120
|
+
folder / "references/review-calibration.md",
|
|
121
|
+
) if str(path) in policy["sources"])
|
|
122
|
+
return tuple(paths)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def capture_code_review_policy(
|
|
126
|
+
project: Path, config: Mapping[str, object], *,
|
|
127
|
+
additional_sources: Sequence[Path] = (), policy: FrozenReviewPolicy | None = None,
|
|
128
|
+
) -> FrozenReviewPolicy:
|
|
129
|
+
root = find_asset_root(("skills", "okstra-code-review", "SKILL.md"))
|
|
130
|
+
skill = ((root / "skills/okstra-code-review") if root
|
|
131
|
+
else Path.home() / ".agents/skills/okstra-code-review")
|
|
132
|
+
sources = (skill / "SKILL.md", skill / "references/census-rules.md",
|
|
133
|
+
skill / "references/review-calibration.md", *additional_sources)
|
|
134
|
+
if policy is None:
|
|
135
|
+
policy = capture_review_policy(project, config)
|
|
136
|
+
errors = review_policy_errors(policy)
|
|
137
|
+
if errors:
|
|
138
|
+
raise ValueError("; ".join(errors))
|
|
139
|
+
captured = {path: dict(source) for path, source in policy["sources"].items()}
|
|
140
|
+
for source in sources:
|
|
141
|
+
_capture_rule_source(source, captured)
|
|
142
|
+
return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
|
|
143
|
+
"sources": captured, "authorPolicyDigest": canonical_json_digest(policy)}
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def render_review_rule_catalog(policy: FrozenReviewPolicy) -> str:
|
|
147
|
+
from .code_review_census import render_rule_catalog
|
|
148
|
+
|
|
149
|
+
path = review_policy_catalog_path(policy)
|
|
150
|
+
root = str(path.parent)
|
|
151
|
+
catalog = policy["sources"][str(path)]
|
|
152
|
+
return render_rule_catalog(
|
|
153
|
+
catalog["body"], Path(root),
|
|
154
|
+
include_architecture=root + "/architectures/hexagonal.md" in policy["sources"],
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
_LANGUAGE_SUFFIXES = {
|
|
159
|
+
".js": "javascript-typescript", ".jsx": "javascript-typescript",
|
|
160
|
+
".ts": "javascript-typescript", ".tsx": "javascript-typescript",
|
|
161
|
+
".mjs": "javascript-typescript", ".cjs": "javascript-typescript",
|
|
162
|
+
".mts": "javascript-typescript", ".cts": "javascript-typescript",
|
|
163
|
+
".py": "python", ".rs": "rust", ".java": "java",
|
|
164
|
+
".kt": "kotlin", ".kts": "kotlin", ".sql": "sql",
|
|
165
|
+
}
|
|
166
|
+
_LANGUAGE_MANIFESTS = {
|
|
167
|
+
"package.json": "javascript-typescript", "pyproject.toml": "python",
|
|
168
|
+
"requirements.txt": "python", "setup.py": "python", "setup.cfg": "python",
|
|
169
|
+
"Cargo.toml": "rust", "pom.xml": "java", "build.gradle": "java",
|
|
170
|
+
"build.gradle.kts": "kotlin",
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def review_policy_catalog_path(policy: FrozenReviewPolicy) -> Path:
|
|
175
|
+
paths = [Path(path) for path in policy["sources"]
|
|
176
|
+
if path.endswith("/prompts/coding-preflight/review-rules.json")]
|
|
177
|
+
if len(paths) != 1:
|
|
178
|
+
raise ValueError("required frozen review resource is missing or ambiguous: review-rules.json")
|
|
179
|
+
return paths[0]
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _language_resources(source_paths: Sequence[str]) -> set[str]:
|
|
183
|
+
languages: set[str] = set()
|
|
184
|
+
for source in source_paths:
|
|
185
|
+
path = PurePosixPath(source)
|
|
186
|
+
if not qa_relative_path_valid(source):
|
|
187
|
+
raise ValueError("review source paths must be repository-relative")
|
|
188
|
+
language = _LANGUAGE_SUFFIXES.get(path.suffix) or _LANGUAGE_MANIFESTS.get(path.name)
|
|
189
|
+
if language:
|
|
190
|
+
languages.add(language)
|
|
191
|
+
if ("migration" in source.lower() or path.name == "schema.prisma"):
|
|
192
|
+
languages.add("sql")
|
|
193
|
+
return {f"languages/{language}.md" for language in languages}
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def review_policy_context(
|
|
197
|
+
project: Path, head: str, source_paths: Sequence[str], *, base: str = "",
|
|
198
|
+
) -> tuple[tuple[str, ...], dict[str, str]]:
|
|
199
|
+
paths, manifests, _ = _review_context_side(project, head, source_paths)
|
|
200
|
+
if base:
|
|
201
|
+
previous, old_manifests, commit = _review_context_side(project, base, source_paths)
|
|
202
|
+
paths = tuple(dict.fromkeys((*paths, *previous)))
|
|
203
|
+
for path, body in old_manifests.items():
|
|
204
|
+
if manifests.get(path) != body:
|
|
205
|
+
manifests[f"base:{commit}/{path}"] = body
|
|
206
|
+
return paths, manifests
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _review_context_side(
|
|
210
|
+
project: Path, head: str, source_paths: Sequence[str],
|
|
211
|
+
) -> tuple[tuple[str, ...], dict[str, str], str]:
|
|
212
|
+
from .review_verdicts import _head_tree
|
|
213
|
+
|
|
214
|
+
_language_resources(source_paths)
|
|
215
|
+
tree = _head_tree(project, head)
|
|
216
|
+
files = tree._git("ls-tree", "-r", "--name-only", tree.commit)
|
|
217
|
+
if files.returncode:
|
|
218
|
+
raise ValueError("cannot read the frozen review project layout")
|
|
219
|
+
paths = tuple(files.stdout.decode("utf-8").splitlines())
|
|
220
|
+
manifests: set[str] = set()
|
|
221
|
+
for source in source_paths:
|
|
222
|
+
directory = PurePosixPath(source).parent
|
|
223
|
+
for parent in (directory, *directory.parents):
|
|
224
|
+
candidate = (parent / "package.json").as_posix()
|
|
225
|
+
if candidate in paths:
|
|
226
|
+
manifests.add(candidate)
|
|
227
|
+
break
|
|
228
|
+
contents: dict[str, str] = {}
|
|
229
|
+
for manifest in sorted(manifests):
|
|
230
|
+
result = tree._git("show", f"{tree.commit}:{manifest}")
|
|
231
|
+
if result.returncode:
|
|
232
|
+
raise ValueError("cannot read the frozen review package manifest")
|
|
233
|
+
contents[manifest] = result.stdout.decode("utf-8")
|
|
234
|
+
return paths, contents, tree.commit
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def _node_server_work(source_paths: Sequence[str], manifests: Mapping[str, str]) -> bool:
|
|
238
|
+
if any(PurePosixPath(path).suffix in (".mjs", ".cjs", ".mts", ".cts")
|
|
239
|
+
or PurePosixPath(path).name in ("server.js", "server.ts", "nest-cli.json")
|
|
240
|
+
or any(part in ("server", "api", "controllers", "commands")
|
|
241
|
+
for part in PurePosixPath(path).parts) for path in source_paths):
|
|
242
|
+
return True
|
|
243
|
+
for path, body in manifests.items():
|
|
244
|
+
if PurePosixPath(path).name != "package.json":
|
|
245
|
+
continue
|
|
246
|
+
package = json.loads(body)
|
|
247
|
+
if not isinstance(package, dict):
|
|
248
|
+
raise ValueError("review package manifest must be an object")
|
|
249
|
+
dependencies = package.get("dependencies", {})
|
|
250
|
+
dev_dependencies = package.get("devDependencies", {})
|
|
251
|
+
if not isinstance(dependencies, dict) or not isinstance(dev_dependencies, dict):
|
|
252
|
+
raise ValueError("review package dependencies must be objects")
|
|
253
|
+
dependencies = {**dependencies, **dev_dependencies}
|
|
254
|
+
if any(name in ("express", "fastify", "koa", "hapi") or name.startswith("@nestjs/")
|
|
255
|
+
for name in dependencies):
|
|
256
|
+
return True
|
|
257
|
+
if package.get("bin"):
|
|
258
|
+
return True
|
|
259
|
+
return False
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def _hexagonal_work(policy: FrozenReviewPolicy, project_paths: Sequence[str]) -> bool:
|
|
263
|
+
style = policy["architecture"]
|
|
264
|
+
if style != "undeclared":
|
|
265
|
+
return style == "hexagonal"
|
|
266
|
+
parts = {part for path in project_paths for part in PurePosixPath(path).parts}
|
|
267
|
+
return (any(".port." in PurePosixPath(path).name for path in project_paths)
|
|
268
|
+
or {"domain", "ports", "adapters"} <= parts
|
|
269
|
+
or {"core", "infrastructure", "application"} <= parts)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def select_review_policy(
|
|
273
|
+
policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
|
|
274
|
+
project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
|
|
275
|
+
guidance_paths: Sequence[str] = (),
|
|
276
|
+
resources: Sequence[str] = (),
|
|
277
|
+
) -> FrozenReviewPolicy:
|
|
278
|
+
errors = review_policy_errors(policy)
|
|
279
|
+
if errors:
|
|
280
|
+
raise ValueError("; ".join(errors))
|
|
281
|
+
selected_resources = {"overview.md", "clean-code.md", "review-rules.json"}
|
|
282
|
+
selected_resources.update(_language_resources(source_paths))
|
|
283
|
+
root = str(review_policy_catalog_path(policy).parent)
|
|
284
|
+
for resource in resources:
|
|
285
|
+
if (not qa_relative_path_valid(resource) or root is None
|
|
286
|
+
or root + "/" + resource not in policy["sources"]):
|
|
287
|
+
raise ValueError(f"review resource was not captured in the frozen pack: {resource}")
|
|
288
|
+
if resource == "architectures/hexagonal.md" and policy["architecture"] in ("none", "layered"):
|
|
289
|
+
raise ValueError("review resource conflicts with the declared architecture")
|
|
290
|
+
selected_resources.add(resource)
|
|
291
|
+
if "frameworks/node-server.md" in selected_resources:
|
|
292
|
+
selected_resources.add("languages/javascript-typescript.md")
|
|
293
|
+
if any(name.endswith("javascript-typescript.md") for name in selected_resources):
|
|
294
|
+
if _node_server_work(source_paths, manifest_contents or {}):
|
|
295
|
+
selected_resources.add("frameworks/node-server.md")
|
|
296
|
+
if _hexagonal_work(policy, (*source_paths, *project_paths)):
|
|
297
|
+
selected_resources.add("architectures/hexagonal.md")
|
|
298
|
+
missing = [name for name in sorted(selected_resources)
|
|
299
|
+
if root + "/" + name not in policy["sources"]]
|
|
300
|
+
if missing:
|
|
301
|
+
raise ValueError("required frozen review resources are missing: " + ", ".join(missing))
|
|
302
|
+
selected: dict[str, FrozenProcedure] = {}
|
|
303
|
+
for path, source in policy["sources"].items():
|
|
304
|
+
if path in guidance_paths and not path.endswith("/references/review-calibration.md"):
|
|
305
|
+
continue
|
|
306
|
+
if root and path.startswith(root + "/") and path[len(root) + 1:] not in selected_resources:
|
|
307
|
+
continue
|
|
308
|
+
selected[path] = dict(source)
|
|
309
|
+
return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
|
|
310
|
+
"sources": selected}
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def render_review_policy(
|
|
314
|
+
policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
|
|
315
|
+
project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
|
|
316
|
+
guidance_paths: Sequence[str] = (),
|
|
317
|
+
resources: Sequence[str] = (),
|
|
318
|
+
) -> str:
|
|
319
|
+
selected = select_review_policy(
|
|
320
|
+
policy, source_paths, project_paths=project_paths,
|
|
321
|
+
manifest_contents=manifest_contents, guidance_paths=guidance_paths,
|
|
322
|
+
resources=resources,
|
|
323
|
+
)
|
|
324
|
+
body = render_selected_review_policy(selected)
|
|
325
|
+
omitted = policy["sources"].keys() - selected["sources"].keys()
|
|
326
|
+
if not omitted:
|
|
327
|
+
return body
|
|
328
|
+
rows = [body, "\n### Available archived resources (not loaded)\n\n"]
|
|
329
|
+
rows.extend(f"- {path} ({policy['sources'][path]['digest']})\n" for path in sorted(omitted))
|
|
330
|
+
rows.append("\nUse verification-input --source-path for each changed source file and "
|
|
331
|
+
"--resource for additional applicable pack resources. "
|
|
332
|
+
"Do not treat this inventory as read content.\n")
|
|
333
|
+
return "".join(rows)
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def render_selected_review_policy(policy: FrozenReviewPolicy) -> str:
|
|
337
|
+
errors = review_policy_errors(policy)
|
|
338
|
+
if errors:
|
|
339
|
+
raise ValueError("; ".join(errors))
|
|
340
|
+
rows = ["\n## Frozen Review Policy\n\n",
|
|
341
|
+
f"Architecture style: {policy['architecture']}\n"]
|
|
342
|
+
for path, source in policy["sources"].items():
|
|
343
|
+
rows.extend([f"\n### Rule source: {path}\n",
|
|
344
|
+
f"Digest: {source['digest']}\n\n", source["body"], "\n"])
|
|
345
|
+
return "".join(rows)
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def read_review_architecture(project: Path, manifest: Mapping[str, object]) -> str:
|
|
349
|
+
from okstra_project.resolver import resolve_architecture
|
|
350
|
+
from .qa_procedures import safe_qa_path
|
|
351
|
+
from .verification_input_ref import VerificationInputReference
|
|
352
|
+
from .verification_inputs import read_verification_inputs
|
|
353
|
+
|
|
354
|
+
reference = VerificationInputReference.from_artifact_fields(manifest)
|
|
355
|
+
if reference is not None:
|
|
356
|
+
inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
|
|
357
|
+
if "reviewPolicy" in inputs:
|
|
358
|
+
return inputs["reviewPolicy"]["architecture"]
|
|
359
|
+
return resolve_architecture(project)
|
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
import subprocess
|
|
5
|
+
from collections.abc import Sequence
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from pathlib import Path, PurePosixPath
|
|
8
|
+
|
|
9
|
+
from .convergence_provenance import id_occurs_wordbounded
|
|
10
|
+
from .coverage_census import CellVerdicts, split_coverage_verdict_section
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@dataclass(frozen=True)
|
|
14
|
+
class ReviewCell:
|
|
15
|
+
target: str
|
|
16
|
+
group: str
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class ReviewCensus:
|
|
21
|
+
rules: dict[str, tuple[str, ...]]
|
|
22
|
+
cells: dict[str, ReviewCell]
|
|
23
|
+
references: dict[str, str]
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _table_fields(line: str) -> list[str]:
|
|
27
|
+
# Markdown writes a literal pipe inside a table cell as `\|`.
|
|
28
|
+
fields = re.split(r"(?<!\\)\|", line.strip().strip("|"))
|
|
29
|
+
return [field.strip().replace("\\|", "|") for field in fields]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def read_review_census(path: Path, *, allow_empty: bool = False) -> ReviewCensus:
|
|
33
|
+
return parse_review_census(path.read_text(encoding="utf-8"), allow_empty=allow_empty)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def parse_review_census(text: str, *, allow_empty: bool = False) -> ReviewCensus:
|
|
37
|
+
rules: dict[str, list[str]] = {}
|
|
38
|
+
cells: dict[str, ReviewCell] = {}
|
|
39
|
+
rule_ids: set[str] = set()
|
|
40
|
+
pairs: set[tuple[str, str]] = set()
|
|
41
|
+
references: set[tuple[str, str]] = set()
|
|
42
|
+
rule_references: dict[str, str] = {}
|
|
43
|
+
section = ""
|
|
44
|
+
for line in text.splitlines():
|
|
45
|
+
if line.startswith("## "):
|
|
46
|
+
section = line.strip()
|
|
47
|
+
if section not in ("## Rules", "## Cells") or not line.strip().startswith("|"):
|
|
48
|
+
continue
|
|
49
|
+
fields = _table_fields(line)
|
|
50
|
+
header = fields[0] in ("Rule", "Cell")
|
|
51
|
+
if header or all(re.fullmatch(r"[-:]+", f) for f in fields):
|
|
52
|
+
continue
|
|
53
|
+
if len(fields) != 3 or not all(fields):
|
|
54
|
+
raise ValueError("malformed grouped census row")
|
|
55
|
+
identity, value, reference = fields
|
|
56
|
+
if section == "## Rules":
|
|
57
|
+
if not re.fullmatch(r"[A-Z][A-Z0-9]*", identity) or identity in rule_ids:
|
|
58
|
+
raise ValueError("invalid or duplicate rule ID")
|
|
59
|
+
if (value, reference) in references:
|
|
60
|
+
raise ValueError("duplicate group and rule reference")
|
|
61
|
+
if value not in ("structural", "semantic", "state-and-tests", "general"):
|
|
62
|
+
raise ValueError("unknown rule group")
|
|
63
|
+
rule_ids.add(identity)
|
|
64
|
+
references.add((value, reference))
|
|
65
|
+
rule_references[identity] = reference
|
|
66
|
+
rules.setdefault(value, []).append(identity)
|
|
67
|
+
else:
|
|
68
|
+
if not re.fullmatch(r"C-CR-[0-9]+", identity) or identity in cells:
|
|
69
|
+
raise ValueError("invalid or duplicate cell ID")
|
|
70
|
+
if (value, reference) in pairs:
|
|
71
|
+
raise ValueError("duplicate target and group")
|
|
72
|
+
target = PurePosixPath(value.partition(":")[0])
|
|
73
|
+
if target.is_absolute() or ".." in target.parts:
|
|
74
|
+
raise ValueError("target must be project-relative")
|
|
75
|
+
pairs.add((value, reference))
|
|
76
|
+
cells[identity] = ReviewCell(value, reference)
|
|
77
|
+
if not rules or (not cells and not allow_empty):
|
|
78
|
+
raise ValueError("census needs Rules and Cells tables")
|
|
79
|
+
if any(cell.group not in rules for cell in cells.values()):
|
|
80
|
+
raise ValueError("cell names an unknown rule group")
|
|
81
|
+
return ReviewCensus(
|
|
82
|
+
{group: tuple(ids) for group, ids in rules.items()}, cells, rule_references,
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _keyed_values(text: str) -> dict[str, str]:
|
|
87
|
+
values: dict[str, str] = {}
|
|
88
|
+
if text == "-":
|
|
89
|
+
return values
|
|
90
|
+
# Reviewers write prose reasons; only a semicolon before the next `RULE=` separates assignments.
|
|
91
|
+
for entry in re.split(r";(?=\s*[A-Z][A-Z0-9]*=)", text):
|
|
92
|
+
key, separator, value = entry.partition("=")
|
|
93
|
+
key, value = key.strip(), value.strip()
|
|
94
|
+
if not separator or not key or not value or key in values:
|
|
95
|
+
raise ValueError(f"empty or duplicate rule assignment: {entry.strip()!r}")
|
|
96
|
+
values[key] = value
|
|
97
|
+
return values
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
@dataclass
|
|
101
|
+
class _HeadTree:
|
|
102
|
+
"""리뷰 대상 커밋이 담은 파일.
|
|
103
|
+
|
|
104
|
+
프로젝트 루트에는 다른 커밋이 체크아웃돼 있을 수 있다.
|
|
105
|
+
"""
|
|
106
|
+
|
|
107
|
+
root: Path
|
|
108
|
+
commit: str
|
|
109
|
+
line_counts: dict[str, int] = field(default_factory=dict)
|
|
110
|
+
base: _HeadTree | None = None
|
|
111
|
+
|
|
112
|
+
def line_count(self, path: str) -> int:
|
|
113
|
+
if path not in self.line_counts:
|
|
114
|
+
self.line_counts[path] = self._read_line_count(path)
|
|
115
|
+
return self.line_counts[path]
|
|
116
|
+
|
|
117
|
+
def _git(self, *args: str) -> subprocess.CompletedProcess[bytes]:
|
|
118
|
+
return subprocess.run(
|
|
119
|
+
["git", "--literal-pathspecs", "-C", str(self.root), *args],
|
|
120
|
+
capture_output=True, check=False,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
def _read_line_count(self, path: str) -> int:
|
|
124
|
+
listing = self._git("ls-tree", "-z", self.commit, "--", path)
|
|
125
|
+
if listing.returncode != 0:
|
|
126
|
+
raise ValueError("cannot list the head commit")
|
|
127
|
+
entries = [entry for entry in listing.stdout.split(b"\0") if entry]
|
|
128
|
+
named = (entry.partition(b"\t") for entry in entries)
|
|
129
|
+
matched = [
|
|
130
|
+
meta.split() for meta, _, name in named
|
|
131
|
+
if name.decode("utf-8", "surrogateescape") == path
|
|
132
|
+
]
|
|
133
|
+
if not matched:
|
|
134
|
+
raise ValueError("source evidence file does not exist at head")
|
|
135
|
+
mode, kind, blob = matched[0]
|
|
136
|
+
if kind != b"blob" or mode == b"120000":
|
|
137
|
+
raise ValueError("source evidence is not a regular file at head")
|
|
138
|
+
content = self._git("cat-file", "blob", blob.decode())
|
|
139
|
+
if content.returncode != 0:
|
|
140
|
+
raise ValueError("cannot read source evidence at head")
|
|
141
|
+
return len(content.stdout.decode("utf-8").splitlines())
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _head_tree(project_root: Path, head: str) -> _HeadTree:
|
|
145
|
+
resolved = subprocess.run(
|
|
146
|
+
["git", "-C", str(project_root), "rev-parse", "--verify", "--quiet",
|
|
147
|
+
"--end-of-options", f"{head}^{{commit}}"],
|
|
148
|
+
capture_output=True, text=True, check=False,
|
|
149
|
+
)
|
|
150
|
+
if resolved.returncode != 0:
|
|
151
|
+
raise ValueError(f"--head {head!r} is not a commit in {project_root}")
|
|
152
|
+
return _HeadTree(project_root, resolved.stdout.strip())
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _source_evidence(tree: _HeadTree, cell: ReviewCell, evidence: str) -> str:
|
|
156
|
+
source = evidence.strip("`")
|
|
157
|
+
if source.startswith("base:"):
|
|
158
|
+
if tree.base is None:
|
|
159
|
+
raise ValueError("base-side evidence requires --base")
|
|
160
|
+
tree = tree.base
|
|
161
|
+
source = source.removeprefix("base:")
|
|
162
|
+
target = cell.target.partition(":")[0]
|
|
163
|
+
match = re.fullmatch(re.escape(target) + r":(0|[1-9][0-9]*)`?(?:[ \t]+\S.*)?", source)
|
|
164
|
+
if match is None:
|
|
165
|
+
raise ValueError("evidence must cite the target source path:line")
|
|
166
|
+
relative = PurePosixPath(target)
|
|
167
|
+
if relative.is_absolute() or ".." in relative.parts:
|
|
168
|
+
raise ValueError("source evidence escapes project")
|
|
169
|
+
count = tree.line_count(target)
|
|
170
|
+
if int(match[1]) > count or (int(match[1]) == 0 and count != 0):
|
|
171
|
+
raise ValueError("source evidence line does not exist at head")
|
|
172
|
+
return evidence
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def _checked_rule_evidence(
|
|
176
|
+
tree: _HeadTree, cell: ReviewCell, checked: Sequence[str], text: str,
|
|
177
|
+
) -> str:
|
|
178
|
+
anchor, _, raw = text.partition(" :: ")
|
|
179
|
+
_source_evidence(tree, cell, anchor)
|
|
180
|
+
observations = _keyed_values(raw.strip() or "-")
|
|
181
|
+
required = set(checked) & {"G2", "G3", "G5"} if cell.group == "general" else set()
|
|
182
|
+
missing = required - observations.keys()
|
|
183
|
+
if missing:
|
|
184
|
+
raise ValueError("missing clean check evidence: " + ", ".join(sorted(missing)))
|
|
185
|
+
if observations.keys() - set(checked):
|
|
186
|
+
raise ValueError("clean check evidence names an unchecked rule")
|
|
187
|
+
for observation in observations.values():
|
|
188
|
+
match = re.fullmatch(r"(`?.+?:(?:0|[1-9][0-9]*)`?) (.+)", observation)
|
|
189
|
+
if match is None:
|
|
190
|
+
raise ValueError("clean check evidence needs source path:line and an observation")
|
|
191
|
+
if re.fullmatch(r"(?:checked|clean|no issues?|none|n/?a)", match[2], re.I):
|
|
192
|
+
raise ValueError("clean check evidence needs an observation, not a verdict label")
|
|
193
|
+
citation = match[1].strip("`")
|
|
194
|
+
source_cell = ReviewCell(citation.removeprefix("base:").partition(":")[0], cell.group)
|
|
195
|
+
_source_evidence(tree, source_cell, citation)
|
|
196
|
+
return text
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _group_verdict(
|
|
200
|
+
fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
|
|
201
|
+
tree: _HeadTree, references: Sequence[str],
|
|
202
|
+
) -> tuple[str, str]:
|
|
203
|
+
if len(fields) != 5:
|
|
204
|
+
raise ValueError("expected Cell, Checked, N/A, Findings, Evidence columns")
|
|
205
|
+
checked = [] if fields[1] == "-" else [rule.strip() for rule in fields[1].split(",")]
|
|
206
|
+
excluded = _keyed_values(fields[2])
|
|
207
|
+
findings = _keyed_values(fields[3])
|
|
208
|
+
assigned = checked + list(excluded) + list(findings)
|
|
209
|
+
if len(set(assigned)) != len(assigned):
|
|
210
|
+
raise ValueError("duplicate or conflicting rule verdicts")
|
|
211
|
+
unknown = set(assigned) - set(expected)
|
|
212
|
+
if unknown:
|
|
213
|
+
raise ValueError("unknown rules: " + ", ".join(sorted(unknown)))
|
|
214
|
+
missing = set(expected) - set(assigned)
|
|
215
|
+
if missing:
|
|
216
|
+
raise ValueError("unchecked rules: " + ", ".join(sorted(missing)))
|
|
217
|
+
for reason in excluded.values():
|
|
218
|
+
if re.fullmatch(r"(?:[A-Z][0-9]+|[a-z]+:[0-9]+)", reason):
|
|
219
|
+
raise ValueError("n/a needs an inline applicability reason, not an alias")
|
|
220
|
+
for ids in findings.values():
|
|
221
|
+
for item in ids.split(","):
|
|
222
|
+
item = item.strip()
|
|
223
|
+
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", item):
|
|
224
|
+
raise ValueError("invalid finding ID")
|
|
225
|
+
if not any(id_occurs_wordbounded(body, item) for body in references):
|
|
226
|
+
raise ValueError(f"finding {item} has no finding body")
|
|
227
|
+
evidence = _checked_rule_evidence(tree, cell, checked, fields[4])
|
|
228
|
+
if findings:
|
|
229
|
+
return "finding", "; ".join(findings.values())
|
|
230
|
+
if checked:
|
|
231
|
+
return "clean", evidence
|
|
232
|
+
return "n/a", "; ".join(excluded.values())
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _group_results(
|
|
236
|
+
body: str, census: ReviewCensus, tree: _HeadTree, references: Sequence[str],
|
|
237
|
+
) -> CellVerdicts:
|
|
238
|
+
section, _ = split_coverage_verdict_section(body)
|
|
239
|
+
verdicts: dict[str, tuple[str, str]] = {}
|
|
240
|
+
reasons: dict[str, str] = {}
|
|
241
|
+
seen: set[str] = set()
|
|
242
|
+
unknown: list[str] = []
|
|
243
|
+
for line in section:
|
|
244
|
+
if not line.strip().startswith("|"):
|
|
245
|
+
continue
|
|
246
|
+
fields = _table_fields(line)
|
|
247
|
+
identity = fields[0]
|
|
248
|
+
if identity not in census.cells:
|
|
249
|
+
if identity.startswith("C-") and identity not in unknown:
|
|
250
|
+
unknown.append(identity)
|
|
251
|
+
continue
|
|
252
|
+
if identity in seen:
|
|
253
|
+
verdicts.pop(identity, None)
|
|
254
|
+
reasons[identity] = "duplicate cell row"
|
|
255
|
+
continue
|
|
256
|
+
seen.add(identity)
|
|
257
|
+
cell = census.cells[identity]
|
|
258
|
+
try:
|
|
259
|
+
verdicts[identity] = _group_verdict(
|
|
260
|
+
fields, census.rules[cell.group], cell, tree, references,
|
|
261
|
+
)
|
|
262
|
+
except (OSError, ValueError) as exc:
|
|
263
|
+
reasons[identity] = str(exc)
|
|
264
|
+
return CellVerdicts(
|
|
265
|
+
verdicts,
|
|
266
|
+
{key: reasons.get(key, "no grouped verdict row") for key in census.cells if key not in verdicts},
|
|
267
|
+
tuple(unknown),
|
|
268
|
+
)
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def parse_review_verdicts(
|
|
273
|
+
project: Path, census: ReviewCensus, bodies: Sequence[str], head: str, *, base: str = "",
|
|
274
|
+
) -> CellVerdicts:
|
|
275
|
+
tree = _head_tree(project, head)
|
|
276
|
+
if base:
|
|
277
|
+
tree.base = _head_tree(project, base)
|
|
278
|
+
verdicts: dict[str, tuple[str, str]] = {}
|
|
279
|
+
missing: dict[str, str] = {}
|
|
280
|
+
unknown: list[str] = []
|
|
281
|
+
references = [split_coverage_verdict_section(body)[1] for body in bodies]
|
|
282
|
+
for body in bodies:
|
|
283
|
+
parsed = _group_results(body, census, tree, references)
|
|
284
|
+
unknown.extend(key for key in parsed.unknown if key not in unknown)
|
|
285
|
+
for key, verdict in parsed.verdicts.items():
|
|
286
|
+
verdicts.setdefault(key, verdict)
|
|
287
|
+
missing.update(parsed.missing)
|
|
288
|
+
return CellVerdicts(
|
|
289
|
+
verdicts, {key: missing[key] for key in census.cells if key not in verdicts},
|
|
290
|
+
tuple(unknown),
|
|
291
|
+
)
|