okstra 0.227.0 → 0.228.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 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
|
@@ -39,6 +39,17 @@ def _schema_enum(definition: str) -> frozenset[str]:
|
|
|
39
39
|
return frozenset(str(value) for value in values)
|
|
40
40
|
|
|
41
41
|
|
|
42
|
+
@lru_cache(maxsize=None)
|
|
43
|
+
def _schema_pattern(definition: str) -> str:
|
|
44
|
+
schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
|
|
45
|
+
pattern = (schema.get("$defs") or {}).get(definition, {}).get("pattern")
|
|
46
|
+
if not isinstance(pattern, str) or not pattern:
|
|
47
|
+
raise ApprovalDecisionError(
|
|
48
|
+
f"report schema has no pattern for {definition!r}"
|
|
49
|
+
)
|
|
50
|
+
return pattern
|
|
51
|
+
|
|
52
|
+
|
|
42
53
|
DISPOSITIONS = frozenset({"select", "accept-risk", "request-revision", "reject"})
|
|
43
54
|
REACHES = frozenset({"in-repo", "cross-repo"})
|
|
44
55
|
SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
|
|
@@ -223,6 +234,7 @@ def open_decision(
|
|
|
223
234
|
classification: str, origin: str, user_confirmation: str,
|
|
224
235
|
unblock_condition: str, recommended_disposition: str,
|
|
225
236
|
options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
|
|
237
|
+
candidate_ref: str = "",
|
|
226
238
|
) -> None:
|
|
227
239
|
row = _decision_row(
|
|
228
240
|
clarification_id=clarification_id, ticket_id=ticket_id,
|
|
@@ -239,10 +251,19 @@ def open_decision(
|
|
|
239
251
|
raise ApprovalDecisionError(f"duplicate active clarification: {clarification_id}")
|
|
240
252
|
if supersedes:
|
|
241
253
|
row["supersedes"] = _superseded_carried_ids(ledger, supersedes)
|
|
254
|
+
if candidate_ref:
|
|
255
|
+
row["candidateRef"] = _candidate_ref(candidate_ref)
|
|
242
256
|
active.append(row)
|
|
243
257
|
write_json_atomic(ledger_path, ledger)
|
|
244
258
|
|
|
245
259
|
|
|
260
|
+
def _candidate_ref(value: str) -> str:
|
|
261
|
+
ref = value.strip()
|
|
262
|
+
if re.search(_schema_pattern("ImplementationOptionId"), ref) is None:
|
|
263
|
+
raise ApprovalDecisionError(f"candidate_ref must be an option id (IO-NNN): {value!r}")
|
|
264
|
+
return ref
|
|
265
|
+
|
|
266
|
+
|
|
246
267
|
def _superseded_carried_ids(
|
|
247
268
|
ledger: Mapping[str, Any], supersedes: Sequence[str],
|
|
248
269
|
) -> list[str]:
|
|
@@ -442,6 +463,14 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
|
|
|
442
463
|
"Repeat for several ids."
|
|
443
464
|
),
|
|
444
465
|
)
|
|
466
|
+
parser.add_argument(
|
|
467
|
+
"--candidate-ref",
|
|
468
|
+
default="",
|
|
469
|
+
help=(
|
|
470
|
+
"the implementation option (IO-NNN) this decision is about. A "
|
|
471
|
+
"candidate's splitAcceptance may cite only a decision opened for it."
|
|
472
|
+
),
|
|
473
|
+
)
|
|
445
474
|
|
|
446
475
|
|
|
447
476
|
_CLI_EPILOG = r"""Usage:
|
|
@@ -523,7 +552,7 @@ def _open_from_args(args: argparse.Namespace) -> None:
|
|
|
523
552
|
# 행이고, 이월 행은 `answered` 로 실린다.
|
|
524
553
|
_QUESTION_FIELDS = (
|
|
525
554
|
"id", "ticketId", "kind", "statement", "expectedForm", "blocks", "origin",
|
|
526
|
-
"options",
|
|
555
|
+
"options", "candidateRef",
|
|
527
556
|
)
|
|
528
557
|
|
|
529
558
|
|
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
"""Project an approved implementation-planning report onto one stage.
|
|
2
2
|
|
|
3
|
-
An implementation executor owns exactly one stage,
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
its reads overran the CLI's tool-output limit before it made an edit.
|
|
3
|
+
An implementation executor owns exactly one stage, while the whole plan record
|
|
4
|
+
also carries every other stage, the planning phase's verification ledger and the
|
|
5
|
+
approver's presentation. Reading that record end-to-end can overrun a CLI's
|
|
6
|
+
tool-output limit before the executor makes an edit.
|
|
8
7
|
|
|
9
8
|
The extract keeps everything the stage can act on and drops only what is named
|
|
10
9
|
in `OMITTED`, each with the reason, so a reader can tell an omission from a gap.
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
Requirement-coverage and validation rows, the two families whose rows carry
|
|
11
|
+
`stageRefs`, keep the stage's rows plus every row that names no stage
|
|
12
|
+
(`plan_items.stage_scope` reads that as "applies to every stage"). Every row of
|
|
13
|
+
a plan-item family carries the `P-*` id the plan-body verification and lead
|
|
14
|
+
directives cite it by. The full record stays the source of record behind
|
|
15
|
+
`sourcePlanPath`.
|
|
15
16
|
"""
|
|
16
17
|
from __future__ import annotations
|
|
17
18
|
|
|
@@ -20,26 +21,22 @@ import re
|
|
|
20
21
|
from pathlib import Path
|
|
21
22
|
from typing import Any, Mapping
|
|
22
23
|
|
|
24
|
+
from .design_surfaces import PATH_CHARS, stages_touching_declared_path
|
|
23
25
|
from .json_boundary import load_owned_object, write_owned_object_atomic
|
|
24
|
-
from .plan_items import PLAN_ITEM_SOURCES
|
|
26
|
+
from .plan_items import PLAN_ITEM_SOURCES, stage_scope
|
|
25
27
|
|
|
26
28
|
EXTRACT_KIND = "approved-plan-stage-extract"
|
|
27
29
|
EXTRACT_SCHEMA_VERSION = 1
|
|
28
30
|
|
|
29
|
-
# implementationPlanning row families filtered to the stage
|
|
30
|
-
#
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
"validationChecklist",
|
|
34
|
-
"rollbackStrategy",
|
|
35
|
-
"dependencyMigrationRisk",
|
|
36
|
-
"crossProjectDependencies",
|
|
37
|
-
)
|
|
31
|
+
# implementationPlanning row families filtered to the stage: the report schema
|
|
32
|
+
# gives `stageRefs` to these rows only. Every other implementationPlanning key
|
|
33
|
+
# is carried whole unless OMITTED names it.
|
|
34
|
+
_STAGE_ROW_FAMILIES = ("requirementCoverage", "validationChecklist")
|
|
38
35
|
# plan_items numbers a row family by position (`P-Val-4` is the fourth
|
|
39
36
|
# validation row); a filtered list loses the position, so the id travels on the row.
|
|
40
37
|
_PLAN_ITEM_PREFIX = {
|
|
41
38
|
family: prefix for family, prefix, _ in PLAN_ITEM_SOURCES
|
|
42
|
-
if family in _STAGE_ROW_FAMILIES
|
|
39
|
+
if family in (*_STAGE_ROW_FAMILIES, "rollbackStrategy", "dependencyMigrationRisk")
|
|
43
40
|
}
|
|
44
41
|
# Top-level report keys an executor acts on. Everything else at the top level is
|
|
45
42
|
# report presentation, audit, or accounting and is listed in OMITTED.
|
|
@@ -59,20 +56,30 @@ OMITTED = {
|
|
|
59
56
|
"the stage-scoped effective decision is inlined in the executor prompt "
|
|
60
57
|
"under Effective design preparation"
|
|
61
58
|
),
|
|
62
|
-
"implementationPlanning.userNarrative":
|
|
63
|
-
|
|
59
|
+
"implementationPlanning.userNarrative": (
|
|
60
|
+
"plain-language explanation for the human reader"
|
|
61
|
+
),
|
|
62
|
+
"implementationPlanning.stages[other]": (
|
|
63
|
+
"stages this run does not own; their Stage Map rows stay"
|
|
64
|
+
),
|
|
64
65
|
"implementationPlanning.directionRealization.fileStructure[other]": (
|
|
65
|
-
"file rows whose path this stage's entry never names"
|
|
66
|
+
"file rows whose path or id this stage's entry never names and that the "
|
|
67
|
+
"planning gate's path mapping assigns to no step of this stage"
|
|
66
68
|
),
|
|
67
69
|
"<rows of another stage>": (
|
|
68
|
-
"requirementCoverage / validationChecklist
|
|
69
|
-
"
|
|
70
|
-
"exclude this stage and whose id this stage's entry never cites"
|
|
70
|
+
"requirementCoverage / validationChecklist rows whose stageRefs exclude "
|
|
71
|
+
"this stage and whose id this stage's entry never cites"
|
|
71
72
|
),
|
|
72
|
-
|
|
73
|
+
(
|
|
74
|
+
"humanSummary, verdictCard, rationale, summary, finalVerdict, "
|
|
75
|
+
"recommendedNextSteps"
|
|
76
|
+
): (
|
|
73
77
|
"report presentation for the approver"
|
|
74
78
|
),
|
|
75
|
-
|
|
79
|
+
(
|
|
80
|
+
"crossVerification, agentActivity, evidence, executionStatus, "
|
|
81
|
+
"executionRoles, tokenUsage"
|
|
82
|
+
): (
|
|
76
83
|
"planning-run audit and accounting"
|
|
77
84
|
),
|
|
78
85
|
"meta, frontmatter, header": "report identity",
|
|
@@ -101,8 +108,12 @@ def stage_extract_payload(
|
|
|
101
108
|
carried_planning[key] = [stage_entry]
|
|
102
109
|
elif key in _STAGE_ROW_FAMILIES:
|
|
103
110
|
carried_planning[key] = _stage_rows(value, key, stage_number, cited_text)
|
|
111
|
+
elif key in _PLAN_ITEM_PREFIX:
|
|
112
|
+
carried_planning[key] = _numbered_rows(value, key)
|
|
104
113
|
elif key == "directionRealization" and isinstance(value, Mapping):
|
|
105
|
-
carried_planning[key] = _direction_realization(
|
|
114
|
+
carried_planning[key] = _direction_realization(
|
|
115
|
+
value, stage_number, stage_entry, cited_text
|
|
116
|
+
)
|
|
106
117
|
else:
|
|
107
118
|
carried_planning[key] = value
|
|
108
119
|
payload: dict[str, Any] = {
|
|
@@ -123,24 +134,23 @@ def stage_extract_payload(
|
|
|
123
134
|
return payload
|
|
124
135
|
|
|
125
136
|
|
|
126
|
-
def
|
|
127
|
-
|
|
128
|
-
stage_number: int,
|
|
129
|
-
output_path: Path,
|
|
130
|
-
) -> bool:
|
|
131
|
-
"""Write the extract for a `.data.json` plan; False when the plan is not one.
|
|
137
|
+
def load_stage_extract(plan_path: Path, stage_number: int) -> dict[str, Any] | None:
|
|
138
|
+
"""The extract of a `.data.json` plan; None when the plan is not one.
|
|
132
139
|
|
|
133
140
|
A Markdown plan predates the report record and has no structure to project,
|
|
134
141
|
and a missing file is reported by the prompt's own plan anchor, so neither
|
|
135
142
|
is an error here — the executor reads the plan as it did before.
|
|
136
143
|
"""
|
|
137
144
|
if not plan_path.name.endswith(".data.json") or not plan_path.is_file():
|
|
138
|
-
return
|
|
145
|
+
return None
|
|
139
146
|
report = load_owned_object(plan_path, artifact="approved implementation plan")
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
147
|
+
return stage_extract_payload(report, stage_number, str(plan_path))
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def write_stage_extract(output_path: Path, payload: Mapping[str, Any]) -> None:
|
|
151
|
+
write_owned_object_atomic(
|
|
152
|
+
output_path, payload, artifact="approved plan stage extract"
|
|
153
|
+
)
|
|
144
154
|
|
|
145
155
|
|
|
146
156
|
def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str, Any]:
|
|
@@ -153,42 +163,41 @@ def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str,
|
|
|
153
163
|
raise StageExtractError(f"approved plan has no stage {stage_number}")
|
|
154
164
|
|
|
155
165
|
|
|
156
|
-
def
|
|
157
|
-
rows: Any,
|
|
158
|
-
family: str,
|
|
159
|
-
stage_number: int,
|
|
160
|
-
cited_text: str,
|
|
161
|
-
) -> list[Any]:
|
|
166
|
+
def _numbered_rows(rows: Any, family: str) -> Any:
|
|
162
167
|
if not isinstance(rows, list):
|
|
163
168
|
return rows
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
169
|
+
prefix = _PLAN_ITEM_PREFIX[family]
|
|
170
|
+
return [
|
|
171
|
+
{"planItemId": f"{prefix}-{position}", **row}
|
|
172
|
+
if isinstance(row, Mapping)
|
|
173
|
+
else row
|
|
174
|
+
for position, row in enumerate(rows, start=1)
|
|
175
|
+
]
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def _stage_rows(rows: Any, family: str, stage_number: int, cited_text: str) -> Any:
|
|
179
|
+
numbered = _numbered_rows(rows, family)
|
|
180
|
+
if not isinstance(numbered, list):
|
|
181
|
+
return numbered
|
|
182
|
+
return [
|
|
183
|
+
row for row in numbered
|
|
184
|
+
if not isinstance(row, Mapping) or _row_applies(row, stage_number, cited_text)
|
|
185
|
+
]
|
|
176
186
|
|
|
177
187
|
|
|
178
188
|
def _row_applies(row: Mapping[str, Any], stage_number: int, cited_text: str) -> bool:
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
[value for value in refs if isinstance(value, int) and not isinstance(value, bool)]
|
|
182
|
-
if isinstance(refs, list) else []
|
|
183
|
-
)
|
|
184
|
-
if not stages or stage_number in stages:
|
|
189
|
+
scope = stage_scope(row)
|
|
190
|
+
if scope is None or stage_number in scope:
|
|
185
191
|
return True
|
|
186
192
|
row_id = row.get("id")
|
|
187
193
|
return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
|
|
188
194
|
|
|
189
195
|
|
|
190
196
|
def _direction_realization(
|
|
191
|
-
realization: Mapping[str, Any],
|
|
197
|
+
realization: Mapping[str, Any],
|
|
198
|
+
stage_number: int,
|
|
199
|
+
stage_entry: Mapping[str, Any],
|
|
200
|
+
cited_text: str,
|
|
192
201
|
) -> dict[str, Any]:
|
|
193
202
|
carried = dict(realization)
|
|
194
203
|
rows = realization.get("fileStructure")
|
|
@@ -197,10 +206,35 @@ def _direction_realization(
|
|
|
197
206
|
row for row in rows
|
|
198
207
|
if not isinstance(row, Mapping)
|
|
199
208
|
or not isinstance(row.get("path"), str)
|
|
200
|
-
or row
|
|
209
|
+
or _file_row_applies(row, stage_number, stage_entry, cited_text)
|
|
201
210
|
]
|
|
202
211
|
return carried
|
|
203
212
|
|
|
204
213
|
|
|
214
|
+
def _file_row_applies(
|
|
215
|
+
row: Mapping[str, Any],
|
|
216
|
+
stage_number: int,
|
|
217
|
+
stage_entry: Mapping[str, Any],
|
|
218
|
+
cited_text: str,
|
|
219
|
+
) -> bool:
|
|
220
|
+
path = row["path"]
|
|
221
|
+
if _names_path(cited_text, path):
|
|
222
|
+
return True
|
|
223
|
+
if stage_number in stages_touching_declared_path(path, {stage_number: stage_entry}):
|
|
224
|
+
return True
|
|
225
|
+
row_id = row.get("id")
|
|
226
|
+
return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _names_path(text: str, path: str) -> bool:
|
|
230
|
+
# The stage entry is prose in the report language, unlike the gate's path
|
|
231
|
+
# cells: a path may carry a `./` prefix, end a sentence or touch a non-ASCII
|
|
232
|
+
# particle, but must not sit inside a longer path.
|
|
233
|
+
pattern = (
|
|
234
|
+
rf"(?<![{PATH_CHARS}])(?:\./)?{re.escape(path)}(?=\.?(?![{PATH_CHARS}]))"
|
|
235
|
+
)
|
|
236
|
+
return re.search(pattern, text, flags=re.ASCII) is not None
|
|
237
|
+
|
|
238
|
+
|
|
205
239
|
def _cites(text: str, identifier: str) -> bool:
|
|
206
240
|
return re.search(rf"(?<![\w-]){re.escape(identifier)}(?![\w-])", text) is not None
|
|
@@ -10,20 +10,37 @@ task worktree 는 체크아웃이라 프로젝트 루트의 git 미추적 파일
|
|
|
10
10
|
from __future__ import annotations
|
|
11
11
|
|
|
12
12
|
import argparse
|
|
13
|
+
import bisect
|
|
13
14
|
import datetime as dt
|
|
15
|
+
import itertools
|
|
16
|
+
import os
|
|
14
17
|
import re
|
|
15
18
|
import subprocess
|
|
16
19
|
import sys
|
|
17
20
|
from pathlib import Path
|
|
18
21
|
|
|
19
|
-
from .analysis_packet import
|
|
22
|
+
from .analysis_packet import (
|
|
23
|
+
BY_REFERENCE_FORMAT,
|
|
24
|
+
MAX_CITED_DOCUMENT_BYTES,
|
|
25
|
+
_fence_mask,
|
|
26
|
+
_section_map,
|
|
27
|
+
exceeds_cited_document_limit,
|
|
28
|
+
file_source_entries,
|
|
29
|
+
project_relative_ref,
|
|
30
|
+
)
|
|
20
31
|
|
|
21
32
|
SOURCE_MATERIAL = "Source Material"
|
|
22
33
|
ATTACH_FETCHED_VIA = "okstra brief-sources attach"
|
|
23
34
|
_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
|
|
24
35
|
_FRONTMATTER_RE = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
|
|
25
36
|
_TOKEN_RE = re.compile(r"[^\s`'\"()\[\]<>{},;|*]+")
|
|
26
|
-
|
|
37
|
+
# Inline code, a double-quoted string and a Markdown link target can hold a path with
|
|
38
|
+
# spaces. A link target needs no closing `)`: requiring one made every unclosed `](`
|
|
39
|
+
# rescan the rest of the line. Code and quotes keep their closers, so a stray `"`
|
|
40
|
+
# (an inch mark) does not swallow the span after it.
|
|
41
|
+
_SPAN_RE = re.compile(r"`([^`\n]+)`|\"([^\"\n]+)\"|\]\(<?([^)>\n]*)")
|
|
42
|
+
_FRAGMENT_RE = re.compile(r"[#?].*\Z")
|
|
43
|
+
_LINE_SUFFIX_RE = re.compile(r":\d+(?:-\d+)?\Z")
|
|
27
44
|
_SOURCE_NUMBER_RE = re.compile(r"\A### Source (\d+)\b")
|
|
28
45
|
# okstra 자신의 산출물(브리프, 그룹 맥락, 보고서)은 okstra 가 직접 운반한다.
|
|
29
46
|
_OKSTRA_HOME = ".okstra"
|
|
@@ -38,19 +55,17 @@ def _body_lines(text: str) -> list[str]:
|
|
|
38
55
|
|
|
39
56
|
def _project_file(token: str, root: Path) -> str | None:
|
|
40
57
|
"""토큰이 프로젝트 루트 아래 파일을 가리키면 루트 기준 posix 경로를 돌려준다."""
|
|
41
|
-
if "
|
|
58
|
+
if "://" in token:
|
|
42
59
|
return None
|
|
43
|
-
token = _LINE_SUFFIX_RE.sub("", token.rstrip(".:"))
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
try:
|
|
47
|
-
relative = path.relative_to(root)
|
|
48
|
-
except ValueError:
|
|
60
|
+
token = _LINE_SUFFIX_RE.sub("", _FRAGMENT_RE.sub("", token.strip().rstrip(".:")))
|
|
61
|
+
relative = project_relative_ref(token, root)
|
|
62
|
+
if relative is None:
|
|
49
63
|
return None
|
|
50
|
-
|
|
64
|
+
path = root / relative
|
|
65
|
+
if (relative == "." or Path(relative).parts[0] == _OKSTRA_HOME
|
|
51
66
|
or path.suffix.lower() not in DOCUMENT_SUFFIXES or not path.is_file()):
|
|
52
67
|
return None
|
|
53
|
-
return relative
|
|
68
|
+
return relative
|
|
54
69
|
|
|
55
70
|
|
|
56
71
|
def _cited_in_body(text: str, root: Path) -> list[str]:
|
|
@@ -58,46 +73,92 @@ def _cited_in_body(text: str, root: Path) -> list[str]:
|
|
|
58
73
|
lines = _body_lines(text)
|
|
59
74
|
section = ""
|
|
60
75
|
for line, fenced in zip(lines, _fence_mask(lines)):
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
if line.startswith("## "):
|
|
76
|
+
# A fenced `## ` line is quoted text, not a section boundary; fenced
|
|
77
|
+
# commands still cite paths.
|
|
78
|
+
if not fenced and line.startswith("## "):
|
|
64
79
|
section = line[3:].strip()
|
|
65
80
|
continue
|
|
66
81
|
if section == SOURCE_MATERIAL:
|
|
67
82
|
continue
|
|
68
|
-
for
|
|
69
|
-
|
|
70
|
-
paths.setdefault(relative)
|
|
83
|
+
for relative in _line_citations(line, root):
|
|
84
|
+
paths.setdefault(relative)
|
|
71
85
|
return list(paths)
|
|
72
86
|
|
|
73
87
|
|
|
88
|
+
def _line_citations(line: str, root: Path) -> list[str]:
|
|
89
|
+
"""Project documents one body line cites, in order of appearance.
|
|
90
|
+
|
|
91
|
+
A word inside a span that names a document is part of that path, not a
|
|
92
|
+
citation of its own (`spaces.md` in `` `docs/spec with spaces.md` ``).
|
|
93
|
+
"""
|
|
94
|
+
found: list[tuple[int, str]] = []
|
|
95
|
+
covered: list[tuple[int, int]] = []
|
|
96
|
+
for match in _SPAN_RE.finditer(line):
|
|
97
|
+
for group_index, group in enumerate(match.groups(), 1):
|
|
98
|
+
if group and (relative := _project_file(group, root)) is not None:
|
|
99
|
+
found.append((match.start(group_index), relative))
|
|
100
|
+
covered.append((match.start(group_index), match.end(group_index)))
|
|
101
|
+
# Spans and tokens both come in line order, so one forward pointer finds the span
|
|
102
|
+
# that could cover each token.
|
|
103
|
+
span = 0
|
|
104
|
+
for match in _TOKEN_RE.finditer(line):
|
|
105
|
+
while span < len(covered) and covered[span][1] <= match.start():
|
|
106
|
+
span += 1
|
|
107
|
+
if span < len(covered) and covered[span][0] <= match.start():
|
|
108
|
+
continue
|
|
109
|
+
if (relative := _project_file(match.group(), root)) is not None:
|
|
110
|
+
found.append((match.start(), relative))
|
|
111
|
+
return [relative for _, relative in sorted(found)]
|
|
112
|
+
|
|
113
|
+
|
|
74
114
|
def _sourced(text: str, root: Path) -> set[str]:
|
|
115
|
+
"""Project files that Source Material file entries name, as prepare reads them."""
|
|
75
116
|
source_material = _section_map(_HTML_COMMENT_RE.sub("", text)).get(SOURCE_MATERIAL, "")
|
|
76
117
|
return {
|
|
77
118
|
relative
|
|
78
119
|
for ref, _ in file_source_entries(source_material)
|
|
79
|
-
|
|
80
|
-
if (relative := _project_file(token, root)) is not None
|
|
120
|
+
if (relative := project_relative_ref(ref, root)) is not None
|
|
81
121
|
}
|
|
82
122
|
|
|
83
123
|
|
|
84
|
-
|
|
85
|
-
"""
|
|
86
|
-
|
|
87
|
-
|
|
124
|
+
class GitQueryError(RuntimeError):
|
|
125
|
+
"""git could not report which cited paths it tracks, inside a git work tree."""
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
|
|
129
|
+
# LC_ALL=C keeps the "not a git repository" message matchable in any locale.
|
|
130
|
+
return subprocess.run(
|
|
131
|
+
["git", "-C", str(root), *args],
|
|
88
132
|
capture_output=True,
|
|
89
133
|
text=True,
|
|
90
134
|
check=False,
|
|
135
|
+
env={**os.environ, "LC_ALL": "C"},
|
|
91
136
|
)
|
|
92
|
-
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _git_tracked(root: Path, paths: list[str]) -> set[str] | None:
|
|
140
|
+
"""`paths` 중 git 이 추적하는 것. git 저장소가 아니면 None — worktree 가 없으니 검사할 것도 없다."""
|
|
141
|
+
inside = _git(root, "rev-parse", "--is-inside-work-tree")
|
|
142
|
+
if inside.returncode != 0:
|
|
143
|
+
if "not a git repository" in inside.stderr:
|
|
144
|
+
return None
|
|
145
|
+
raise GitQueryError(
|
|
146
|
+
f"git rev-parse --is-inside-work-tree in {root} failed: "
|
|
147
|
+
f"{inside.stderr.strip()}"
|
|
148
|
+
)
|
|
149
|
+
if inside.stdout.strip() != "true":
|
|
93
150
|
return None
|
|
151
|
+
proc = _git(root, "ls-files", "-z", "--", *paths)
|
|
152
|
+
if proc.returncode != 0:
|
|
153
|
+
raise GitQueryError(f"git ls-files in {root} failed: {proc.stderr.strip()}")
|
|
94
154
|
return {name for name in proc.stdout.split("\0") if name}
|
|
95
155
|
|
|
96
156
|
|
|
97
157
|
def uncited_local_documents(text: str, project_root: Path) -> list[str]:
|
|
98
158
|
"""본문이 이름을 댄 git 미추적 프로젝트 파일 중 Source Material 의 file 항목이 없는 것."""
|
|
99
159
|
root = project_root.resolve()
|
|
100
|
-
|
|
160
|
+
sourced = _sourced(text, root)
|
|
161
|
+
cited = [path for path in _cited_in_body(text, root) if path not in sourced]
|
|
101
162
|
if not cited:
|
|
102
163
|
return []
|
|
103
164
|
tracked = _git_tracked(root, cited)
|
|
@@ -106,12 +167,26 @@ def uncited_local_documents(text: str, project_root: Path) -> list[str]:
|
|
|
106
167
|
return [path for path in cited if path not in tracked]
|
|
107
168
|
|
|
108
169
|
|
|
109
|
-
def
|
|
170
|
+
def too_large_to_cite(root: Path, relative: str) -> bool:
|
|
171
|
+
"""Whether prepare refuses to copy this project file into the analysis packet."""
|
|
172
|
+
return exceeds_cited_document_limit((root / relative).stat().st_size)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
TOO_LARGE_REASON = (
|
|
176
|
+
f"over {MAX_CITED_DOCUMENT_BYTES} bytes, which prepare does not copy into the "
|
|
177
|
+
"analysis packet; capture the cited part as-is in Source Material instead"
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def by_reference_source_entry(
|
|
182
|
+
index: int, ref: str, fetched_via: str, fetched_at: str
|
|
183
|
+
) -> list[str]:
|
|
184
|
+
"""Lines of one `### Source N — file` entry that points at `ref`."""
|
|
110
185
|
return [
|
|
111
186
|
f"### Source {index} — file",
|
|
112
187
|
"",
|
|
113
188
|
f"- ref: {ref}",
|
|
114
|
-
f"- fetched-via: {
|
|
189
|
+
f"- fetched-via: {fetched_via}",
|
|
115
190
|
f"- fetched-at: {fetched_at}",
|
|
116
191
|
f"- format: {BY_REFERENCE_FORMAT}",
|
|
117
192
|
"",
|
|
@@ -127,39 +202,82 @@ def attach_missing_sources(brief_path: Path, project_root: Path, *, now: dt.date
|
|
|
127
202
|
missing = uncited_local_documents(text, project_root)
|
|
128
203
|
if not missing:
|
|
129
204
|
return []
|
|
205
|
+
root = project_root.resolve()
|
|
206
|
+
if large := [ref for ref in missing if too_large_to_cite(root, ref)]:
|
|
207
|
+
raise ValueError(f"{brief_path}: {', '.join(large)} {TOO_LARGE_REASON}")
|
|
130
208
|
lines = text.split("\n")
|
|
131
|
-
|
|
209
|
+
visible = _blank_html_comments(text).split("\n")
|
|
210
|
+
start, end = _source_material_bounds(visible, brief_path)
|
|
211
|
+
after = _insertion_line(text, visible, start, end)
|
|
212
|
+
first = _last_source_number(visible, start, end) + 1
|
|
213
|
+
entries = [""]
|
|
214
|
+
for number, ref in enumerate(missing, first):
|
|
215
|
+
entries.extend(by_reference_source_entry(
|
|
216
|
+
number, ref, ATTACH_FETCHED_VIA, now.strftime("%Y-%m-%d %H:%M")))
|
|
217
|
+
tail = lines[after + 1:]
|
|
218
|
+
if tail and not tail[0].strip():
|
|
219
|
+
entries.pop()
|
|
220
|
+
brief_path.write_text(
|
|
221
|
+
"\n".join([*lines[:after + 1], *entries, *tail]), encoding="utf-8"
|
|
222
|
+
)
|
|
223
|
+
return missing
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _blank_html_comments(text: str) -> str:
|
|
227
|
+
"""`text` with comment characters replaced by spaces and its newlines kept.
|
|
228
|
+
|
|
229
|
+
Its lines align with the brief's, and its headings are the ones the
|
|
230
|
+
detector sees after it strips comments.
|
|
231
|
+
"""
|
|
232
|
+
return _HTML_COMMENT_RE.sub(lambda m: re.sub(r"[^\n]", " ", m.group()), text)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _source_material_bounds(visible: list[str], brief_path: Path) -> tuple[int, int]:
|
|
236
|
+
"""Lines of the `## Source Material` heading and the next `## ` heading (or EOF)."""
|
|
237
|
+
mask = _fence_mask(visible)
|
|
132
238
|
start = next(
|
|
133
|
-
(i for i, (line, fenced) in enumerate(zip(
|
|
239
|
+
(i for i, (line, fenced) in enumerate(zip(visible, mask))
|
|
134
240
|
if not fenced and line.strip() == f"## {SOURCE_MATERIAL}"),
|
|
135
241
|
None,
|
|
136
242
|
)
|
|
137
243
|
if start is None:
|
|
138
244
|
raise ValueError(f"{brief_path}: no `## {SOURCE_MATERIAL}` section to attach to")
|
|
139
245
|
end = next(
|
|
140
|
-
(i for i in range(start + 1, len(
|
|
141
|
-
|
|
246
|
+
(i for i in range(start + 1, len(visible))
|
|
247
|
+
if not mask[i] and visible[i].startswith("## ")),
|
|
248
|
+
len(visible),
|
|
142
249
|
)
|
|
250
|
+
return start, end
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def _last_source_number(visible: list[str], start: int, end: int) -> int:
|
|
254
|
+
mask = _fence_mask(visible)
|
|
143
255
|
numbers = [int(m.group(1)) for i in range(start + 1, end) if not mask[i]
|
|
144
|
-
if (m := _SOURCE_NUMBER_RE.match(
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
256
|
+
if (m := _SOURCE_NUMBER_RE.match(visible[i]))]
|
|
257
|
+
return max(numbers, default=0)
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _insertion_line(text: str, visible: list[str], start: int, end: int) -> int:
|
|
261
|
+
"""The section line after which new entries go.
|
|
262
|
+
|
|
263
|
+
It is the last line with visible text, or the line where a comment opened
|
|
264
|
+
on that line closes, so the entry neither enters the comment nor precedes
|
|
265
|
+
text the line still carries.
|
|
266
|
+
"""
|
|
267
|
+
line = next((i for i in range(end - 1, start, -1) if visible[i].strip()), start)
|
|
268
|
+
offsets = itertools.accumulate(len(row) + 1 for row in visible)
|
|
269
|
+
newlines = [offset - 1 for offset in offsets]
|
|
270
|
+
for match in _HTML_COMMENT_RE.finditer(text):
|
|
271
|
+
if match.start() <= newlines[line] < match.end():
|
|
272
|
+
line = bisect.bisect_left(newlines, match.end() - 1)
|
|
273
|
+
return line
|
|
156
274
|
|
|
157
275
|
|
|
158
276
|
def _attach_command(args: argparse.Namespace) -> int:
|
|
159
277
|
brief = Path(args.brief).resolve()
|
|
160
278
|
try:
|
|
161
279
|
added = attach_missing_sources(brief, Path(args.project_root), now=dt.datetime.now())
|
|
162
|
-
except ValueError as exc:
|
|
280
|
+
except (OSError, ValueError, GitQueryError) as exc:
|
|
163
281
|
print(f"brief-sources: {exc}", file=sys.stderr)
|
|
164
282
|
return 2
|
|
165
283
|
if not added:
|