create-groundwork 0.0.0-stage → 3.1.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/CHANGELOG.md +87 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +63 -0
- package/README.md +81 -2
- package/dist/commands.js +294 -0
- package/dist/create.js +4 -0
- package/dist/engine.js +124 -0
- package/dist/groundwork.js +4 -0
- package/dist/profiles.js +77 -0
- package/dist/prompter.js +42 -0
- package/dist/scaffold.js +274 -0
- package/dist/text.js +31 -0
- package/package.json +48 -4
- package/template/.github/README.md +14 -0
- package/template/.github/pull_request_template.md +22 -0
- package/template/.github/workflows/docs-check.yml +23 -0
- package/template/AGENTS.md +88 -0
- package/template/BUILD.md +27 -0
- package/template/LICENSE.md +5 -0
- package/template/PROJECT.md +26 -0
- package/template/README.md +40 -0
- package/template/_gitignore +26 -0
- package/template/config/README.md +3 -0
- package/template/docs/README.md +53 -0
- package/template/docs/architecture/REPOSITORY_STRUCTURE.md +37 -0
- package/template/docs/architecture/SYSTEM_DESIGN.md +30 -0
- package/template/docs/architecture/adr/0000-template.md +28 -0
- package/template/docs/architecture/adr/README.md +11 -0
- package/template/docs/architecture/system-design/README.md +15 -0
- package/template/docs/engineering/SECURITY.md +22 -0
- package/template/docs/engineering/TEST_STRATEGY.md +33 -0
- package/template/docs/examples/EXAMPLE.md +56 -0
- package/template/docs/examples/PROFILES.md +75 -0
- package/template/docs/plans/README.md +10 -0
- package/template/docs/plans/_template/PLAN.md +39 -0
- package/template/docs/product/PRD.md +39 -0
- package/template/docs/product/SPEC.md +63 -0
- package/template/docs/product/specs/README.md +37 -0
- package/template/docs/product/specs/_template/SPEC.md +78 -0
- package/template/infrastructure/README.md +3 -0
- package/template/profiles/README.md +96 -0
- package/template/profiles/ai-systems/README.md +44 -0
- package/template/profiles/ai-systems/profile.json +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md +37 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md +26 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/SAFETY.md +35 -0
- package/template/profiles/application/README.md +43 -0
- package/template/profiles/application/profile.json +47 -0
- package/template/profiles/application/templates/docs/application/RELEASES.md +28 -0
- package/template/profiles/backend-api/README.md +40 -0
- package/template/profiles/backend-api/profile.json +42 -0
- package/template/profiles/backend-api/templates/docs/backend-api/DATA.md +27 -0
- package/template/profiles/core/profile.json +74 -0
- package/template/profiles/core/templates/docs/architecture/contracts/README.md +11 -0
- package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md +30 -0
- package/template/profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md +35 -0
- package/template/profiles/core/templates/docs/design/DESIGN.md +202 -0
- package/template/profiles/web/README.md +41 -0
- package/template/profiles/web/profile.json +34 -0
- package/template/profiles/web/templates/docs/web/CONTENT.md +39 -0
- package/template/profiles/web/templates/docs/web/SEO.md +35 -0
- package/template/scaffold-manifest.json +77 -0
- package/template/scripts/README.md +29 -0
- package/template/scripts/check_docs.py +989 -0
- package/template/scripts/groundwork.py +716 -0
- package/template/src/README.md +3 -0
- package/template/tests/README.md +3 -0
|
@@ -0,0 +1,989 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate Groundwork documentation consistency.
|
|
3
|
+
|
|
4
|
+
What it checks (errors — exit 1):
|
|
5
|
+
1. `scaffold-manifest.json`: valid, sorted, and `file_count` matches the
|
|
6
|
+
list. Template files must stay intact: every listed file must exist on
|
|
7
|
+
disk, so a deleted template file must also be removed from the manifest.
|
|
8
|
+
New files under the user-owned areas `src/`, `tests/`, `config/`,
|
|
9
|
+
`infrastructure/` and `scripts/` (except `scripts/check_docs.py`,
|
|
10
|
+
`scripts/groundwork.py` and `scripts/README.md`, which belong to the
|
|
11
|
+
template) do not need to be listed, nor does Groundwork's own
|
|
12
|
+
`.groundwork/` folder; new files elsewhere do.
|
|
13
|
+
2. The Feature Specification Index in `docs/product/SPEC.md` covers every
|
|
14
|
+
feature specification under `docs/product/specs/` (excluding `_template`),
|
|
15
|
+
and every indexed specification exists.
|
|
16
|
+
3. Requirement IDs (`{SCOPE}-{TYPE}-NNN`, TYPE is FR, NFR or BR):
|
|
17
|
+
- grammar violations in markdown files;
|
|
18
|
+
- an ID defined more than once — an ID counts as defined only when it is
|
|
19
|
+
the first cell of a requirement table row in `docs/product/SPEC.md`, a
|
|
20
|
+
feature spec, or (for capabilities) `docs/product/PRD.md`;
|
|
21
|
+
- a feature spec's declared ID prefix must match the IDs it defines;
|
|
22
|
+
- an ID referenced in a document under `docs/`, or in any file under
|
|
23
|
+
`tests/` or `src/`, must be defined;
|
|
24
|
+
- capability IDs (`CAP-NNN`) defined in the PRD must be unique, and a
|
|
25
|
+
`CAP-NNN` referenced in a spec, another document under `docs/`, or a
|
|
26
|
+
file under `tests/` or `src/` must be defined in the PRD;
|
|
27
|
+
- a `CAP-` token that is not exactly three digits (such as `CAP-9999`)
|
|
28
|
+
is a spelling error, checked in markdown and in files under `tests/`
|
|
29
|
+
and `src/`. In code files nothing is skipped. Requirement ID spelling
|
|
30
|
+
is not checked in code files, because code often holds tokens that
|
|
31
|
+
only look like requirement IDs.
|
|
32
|
+
4. Relative markdown links between repository files resolve.
|
|
33
|
+
5. Profiles (only when a `profiles/` folder exists; see `profiles/README.md`):
|
|
34
|
+
- every `profiles/<id>/profile.json` is valid JSON and matches the
|
|
35
|
+
manifest schema, and its `id` matches its folder;
|
|
36
|
+
- every document has exactly one owner: core, or the one profile that
|
|
37
|
+
has a template for it. A profile may list only its own documents and
|
|
38
|
+
core documents; every template must be listed by its profile;
|
|
39
|
+
- the profiles named on the `- Profiles:` line in `PROJECT.md` exist,
|
|
40
|
+
their dependencies (`requires`) are active, and no two active
|
|
41
|
+
profiles are declared incompatible;
|
|
42
|
+
- every document required by core or an active profile exists.
|
|
43
|
+
|
|
44
|
+
What it warns about (printed; only fails the run under the matching flag):
|
|
45
|
+
- hygiene warnings — fail under `--strict`:
|
|
46
|
+
- a spec, `SYSTEM_DESIGN.md` or ADR status value outside the allowed
|
|
47
|
+
vocabulary (checked only once the placeholder text has been replaced);
|
|
48
|
+
- a capability in the PRD that no requirement serves;
|
|
49
|
+
- a document owned by a profile that is not active (only once profiles
|
|
50
|
+
are chosen in `PROJECT.md`);
|
|
51
|
+
- a check an active profile declares that has no row in the tooling
|
|
52
|
+
table in `AGENTS.md`.
|
|
53
|
+
- coverage warnings — fail under `--strict-coverage`:
|
|
54
|
+
- a requirement defined but never referenced by any document under `docs/`
|
|
55
|
+
or any file under `tests/` or `src/` (placeholder rows in the root
|
|
56
|
+
`SPEC.md` are exempt).
|
|
57
|
+
|
|
58
|
+
Three modes: default (only errors fail), `--strict` (hygiene warnings fail
|
|
59
|
+
too), `--strict-coverage` (coverage warnings fail too). `--strict-coverage`
|
|
60
|
+
does not include `--strict`. Use both flags together to fail on everything.
|
|
61
|
+
|
|
62
|
+
Illustrative text: on a line containing "for example", "such as" or "e.g.",
|
|
63
|
+
IDs written inside inline code (backticks) are ignored. IDs outside inline
|
|
64
|
+
code on such lines are still checked. `docs/examples/` and the document
|
|
65
|
+
templates under `profiles/<id>/templates/` are ignored by the ID and link
|
|
66
|
+
checks; templates are checked once they are copied into place.
|
|
67
|
+
|
|
68
|
+
Run after adding, renaming or removing documents, feature specifications,
|
|
69
|
+
requirement IDs or links. Read-only; Python 3 standard library only.
|
|
70
|
+
"""
|
|
71
|
+
|
|
72
|
+
from __future__ import annotations
|
|
73
|
+
|
|
74
|
+
import argparse
|
|
75
|
+
import json
|
|
76
|
+
import re
|
|
77
|
+
import sys
|
|
78
|
+
from pathlib import Path
|
|
79
|
+
|
|
80
|
+
ROOT = Path(__file__).resolve().parent.parent
|
|
81
|
+
MANIFEST = ROOT / "scaffold-manifest.json"
|
|
82
|
+
PRD = ROOT / "docs" / "product" / "PRD.md"
|
|
83
|
+
SPEC = ROOT / "docs" / "product" / "SPEC.md"
|
|
84
|
+
SPECS_DIR = ROOT / "docs" / "product" / "specs"
|
|
85
|
+
DOCS = ROOT / "docs"
|
|
86
|
+
EXAMPLES_DIR = DOCS / "examples"
|
|
87
|
+
SYSTEM_DESIGN = ROOT / "docs" / "architecture" / "SYSTEM_DESIGN.md"
|
|
88
|
+
ADR_DIR = ROOT / "docs" / "architecture" / "adr"
|
|
89
|
+
ADR_TEMPLATE = "0000-template.md"
|
|
90
|
+
PROJECT = ROOT / "PROJECT.md"
|
|
91
|
+
AGENTS = ROOT / "AGENTS.md"
|
|
92
|
+
PROFILES_DIR = ROOT / "profiles"
|
|
93
|
+
PROFILE_FILE = "profile.json"
|
|
94
|
+
PROFILE_TEMPLATES = "templates"
|
|
95
|
+
CORE = "core"
|
|
96
|
+
PROFILE_SCHEMA = 1
|
|
97
|
+
# Fields every manifest has; ordinary profiles add the selection fields.
|
|
98
|
+
CORE_FIELDS = {"schema", "id", "name", "purpose", "documents"}
|
|
99
|
+
PROFILE_FIELDS = CORE_FIELDS | {"use_when", "not_when", "requires", "incompatible_with", "checks"}
|
|
100
|
+
PROFILE_ID = re.compile(r"[a-z][a-z0-9-]*")
|
|
101
|
+
# The active-profile line in PROJECT.md ("- Profiles: web, ai-systems").
|
|
102
|
+
PROFILES_BULLET = re.compile(r"^\s*-\s*Profiles:\s*(.*?)\s*$")
|
|
103
|
+
|
|
104
|
+
PLACEHOLDER_TARGETS = {"specs/feature-name/SPEC.md"}
|
|
105
|
+
|
|
106
|
+
# Areas the user owns once the project starts: new files there are not
|
|
107
|
+
# required to be in the manifest.
|
|
108
|
+
USER_OWNED_DIRS = ("src", "tests", "config", "infrastructure", "scripts")
|
|
109
|
+
# ...except the template's own scripts.
|
|
110
|
+
TEMPLATE_SCRIPTS = {"scripts/check_docs.py", "scripts/README.md", "scripts/groundwork.py"}
|
|
111
|
+
# Groundwork's own per-project records (`.groundwork/config.json`); written
|
|
112
|
+
# by the tools, never listed in the manifest.
|
|
113
|
+
TOOL_DIRS = (".groundwork",)
|
|
114
|
+
|
|
115
|
+
# {SCOPE}-{TYPE}-NNN, where TYPE is a requirement kind.
|
|
116
|
+
ID_STRICT = re.compile(r"\b[A-Z][A-Z0-9]{1,9}-(?:FR|NFR|BR)-\d{3}\b")
|
|
117
|
+
# Tokens that resemble requirement IDs and must match the grammar above.
|
|
118
|
+
ID_LOOKALIKE = re.compile(r"\b[A-Z]{2,10}-[A-Z]{2,10}-\d{1,4}\b")
|
|
119
|
+
# Product capability IDs: CAP-NNN.
|
|
120
|
+
CAP_STRICT = re.compile(r"\bCAP-\d{3}\b")
|
|
121
|
+
# Any CAP- followed by digits; tokens must match CAP_STRICT.
|
|
122
|
+
CAP_LOOKALIKE = re.compile(r"\bCAP-\d+\b")
|
|
123
|
+
# A line that starts a markdown table row.
|
|
124
|
+
TABLE_LINE = re.compile(r"^\s*\|")
|
|
125
|
+
FEATURE_INDEX_LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
|
|
126
|
+
INLINE_CODE = re.compile(r"`[^`]*`")
|
|
127
|
+
ILLUSTRATIVE = ("for example", "such as", "e.g.")
|
|
128
|
+
# ADR status bullets ("- Status: ...").
|
|
129
|
+
STATUS_BULLET = re.compile(r"^\s*-\s*Status:\s*(.+?)\s*$")
|
|
130
|
+
|
|
131
|
+
# Document and specification status values (see docs/README.md).
|
|
132
|
+
DOC_STATUS = ("Draft", "In Review", "Approved", "Superseded")
|
|
133
|
+
# ADR status values (see docs/README.md).
|
|
134
|
+
ADR_STATUS = ("Proposed", "Accepted", "Rejected", "Superseded")
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def read_text(path: Path) -> str:
|
|
138
|
+
try:
|
|
139
|
+
return path.read_text(encoding="utf-8")
|
|
140
|
+
except (OSError, UnicodeDecodeError):
|
|
141
|
+
return ""
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def markdown_files() -> list[Path]:
|
|
145
|
+
return sorted(p for p in ROOT.rglob("*.md") if ".git" not in p.parts)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def feature_specs() -> list[Path]:
|
|
149
|
+
return sorted(p for p in SPECS_DIR.glob("*/SPEC.md") if p.parent.name != "_template")
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def defining_files() -> set[Path]:
|
|
153
|
+
files = {SPEC.resolve()}
|
|
154
|
+
files.update(p.resolve() for p in feature_specs())
|
|
155
|
+
return files
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def is_profile_template(path: Path) -> bool:
|
|
159
|
+
"""True for files under `profiles/<id>/templates/`."""
|
|
160
|
+
try:
|
|
161
|
+
parts = path.resolve().relative_to(ROOT).parts
|
|
162
|
+
except ValueError:
|
|
163
|
+
return False
|
|
164
|
+
return len(parts) > 3 and parts[0] == PROFILES_DIR.name and parts[2] == PROFILE_TEMPLATES
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def checkable_markdown(path: Path) -> bool:
|
|
168
|
+
"""False for templates and the example, which are ignored."""
|
|
169
|
+
return (
|
|
170
|
+
"_template" not in path.parts
|
|
171
|
+
and EXAMPLES_DIR not in path.parents
|
|
172
|
+
and not is_profile_template(path)
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def protected_spans(line: str) -> list[tuple[int, int]]:
|
|
177
|
+
"""Spans of inline code whose IDs count as illustrative and are skipped."""
|
|
178
|
+
lowered = line.lower()
|
|
179
|
+
if not any(marker in lowered for marker in ILLUSTRATIVE):
|
|
180
|
+
return []
|
|
181
|
+
return [(m.start(), m.end()) for m in INLINE_CODE.finditer(line)]
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def iter_tokens(line: str, pattern: re.Pattern[str]):
|
|
185
|
+
protected = protected_spans(line)
|
|
186
|
+
for match in pattern.finditer(line):
|
|
187
|
+
if any(start <= match.start() and match.end() <= end for start, end in protected):
|
|
188
|
+
continue
|
|
189
|
+
yield match
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def table_rows(text: str):
|
|
193
|
+
"""Cells of each markdown table row; non-table lines are skipped."""
|
|
194
|
+
for line in text.splitlines():
|
|
195
|
+
if not TABLE_LINE.match(line):
|
|
196
|
+
continue
|
|
197
|
+
yield [cell.strip() for cell in line.strip().strip("|").split("|")]
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def is_requirement_id(value: str) -> bool:
|
|
201
|
+
return bool(ID_STRICT.fullmatch(value))
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def is_capability_id(value: str) -> bool:
|
|
205
|
+
return bool(CAP_STRICT.fullmatch(value))
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def is_placeholder_row(cells: list[str]) -> bool:
|
|
209
|
+
"""A template row: every cell after the ID is empty or bracketed."""
|
|
210
|
+
body = cells[1:]
|
|
211
|
+
return all(cell == "" or cell.startswith("[") for cell in body)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def is_placeholder_status(value: str) -> bool:
|
|
215
|
+
value = value.strip()
|
|
216
|
+
return not value or value.startswith("[") or " / " in value
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def is_user_owned(relative: Path) -> bool:
|
|
220
|
+
"""True for new files the user may add without updating the manifest."""
|
|
221
|
+
if not relative.parts:
|
|
222
|
+
return False
|
|
223
|
+
if "/".join(relative.parts) in TEMPLATE_SCRIPTS:
|
|
224
|
+
return False
|
|
225
|
+
return relative.parts[0] in USER_OWNED_DIRS or relative.parts[0] in TOOL_DIRS
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def check_manifest() -> list[str]:
|
|
229
|
+
manifest = json.loads(MANIFEST.read_text(encoding="utf-8"))
|
|
230
|
+
files = manifest["files"]
|
|
231
|
+
problems: list[str] = []
|
|
232
|
+
|
|
233
|
+
if manifest["file_count"] != len(files):
|
|
234
|
+
problems.append(
|
|
235
|
+
f"scaffold-manifest.json: file_count is {manifest['file_count']}"
|
|
236
|
+
f" but the list has {len(files)} entries"
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
if files != sorted(files):
|
|
240
|
+
problems.append("scaffold-manifest.json: the file list is not sorted")
|
|
241
|
+
|
|
242
|
+
actual = sorted(
|
|
243
|
+
path.relative_to(ROOT)
|
|
244
|
+
for path in ROOT.rglob("*")
|
|
245
|
+
if path.is_file()
|
|
246
|
+
and ".git" not in path.parts
|
|
247
|
+
and "__pycache__" not in path.parts
|
|
248
|
+
)
|
|
249
|
+
actual_names = [str(relative) for relative in actual]
|
|
250
|
+
|
|
251
|
+
# Template files must stay intact: listed files must exist, and new
|
|
252
|
+
# files outside the user-owned areas must be listed too.
|
|
253
|
+
for stale in sorted(set(files) - set(actual_names)):
|
|
254
|
+
problems.append(
|
|
255
|
+
f"{stale}: listed in the manifest but missing on disk"
|
|
256
|
+
" — restore the file, or remove it from scaffold-manifest.json"
|
|
257
|
+
)
|
|
258
|
+
for missing in sorted(
|
|
259
|
+
relative for relative in actual if not is_user_owned(relative)
|
|
260
|
+
):
|
|
261
|
+
if str(missing) not in files:
|
|
262
|
+
problems.append(
|
|
263
|
+
f"{missing}: on disk but not in the manifest"
|
|
264
|
+
" — add it to scaffold-manifest.json"
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
return problems
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def check_feature_index() -> list[str]:
|
|
271
|
+
text = SPEC.read_text(encoding="utf-8")
|
|
272
|
+
indexed = {
|
|
273
|
+
match.group(1)
|
|
274
|
+
for match in FEATURE_INDEX_LINK.finditer(text)
|
|
275
|
+
if match.group(1).startswith("specs/") and match.group(1).endswith("SPEC.md")
|
|
276
|
+
}
|
|
277
|
+
indexed -= PLACEHOLDER_TARGETS
|
|
278
|
+
|
|
279
|
+
on_disk = {
|
|
280
|
+
f"specs/{path.parent.name}/SPEC.md"
|
|
281
|
+
for path in SPECS_DIR.glob("*/SPEC.md")
|
|
282
|
+
if path.parent.name != "_template"
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
problems = [
|
|
286
|
+
f"docs/product/{target}: linked in the feature index but missing on disk"
|
|
287
|
+
for target in sorted(indexed - on_disk)
|
|
288
|
+
]
|
|
289
|
+
problems += [
|
|
290
|
+
f"docs/product/{target}: on disk but missing from the feature index in SPEC.md"
|
|
291
|
+
for target in sorted(on_disk - indexed)
|
|
292
|
+
]
|
|
293
|
+
return problems
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def collect_definitions() -> tuple[dict[str, str], dict[str, str], dict[str, str], list[str]]:
|
|
297
|
+
"""Scan the defining files and the PRD.
|
|
298
|
+
|
|
299
|
+
Returns (requirement owner, real requirement rows, capability owner,
|
|
300
|
+
errors). An ID is defined only as the first cell of a table row; rows
|
|
301
|
+
whose remaining cells are all placeholders still define their ID but are
|
|
302
|
+
reported separately so they can be exempt from reference warnings.
|
|
303
|
+
"""
|
|
304
|
+
row_owner: dict[str, str] = {}
|
|
305
|
+
real_rows: dict[str, str] = {}
|
|
306
|
+
capability_owner: dict[str, str] = {}
|
|
307
|
+
problems: list[str] = []
|
|
308
|
+
|
|
309
|
+
sources = [(PRD, False)] + [(path, True) for path in sorted(defining_files())]
|
|
310
|
+
for path, is_requirement_table in sources:
|
|
311
|
+
rel = str(path.relative_to(ROOT))
|
|
312
|
+
text = read_text(path)
|
|
313
|
+
seen: set[str] = set()
|
|
314
|
+
for cells in table_rows(text):
|
|
315
|
+
token = cells[0]
|
|
316
|
+
if is_requirement_table and is_requirement_id(token):
|
|
317
|
+
if token in row_owner and row_owner[token] != rel:
|
|
318
|
+
problems.append(
|
|
319
|
+
f"{row_owner[token]} and {rel} both define requirement ID {token}"
|
|
320
|
+
)
|
|
321
|
+
elif token in seen:
|
|
322
|
+
problems.append(f"{rel}: requirement ID {token} is defined more than once")
|
|
323
|
+
row_owner.setdefault(token, rel)
|
|
324
|
+
seen.add(token)
|
|
325
|
+
if not is_placeholder_row(cells):
|
|
326
|
+
real_rows.setdefault(token, rel)
|
|
327
|
+
elif not is_requirement_table and is_capability_id(token):
|
|
328
|
+
if token in capability_owner:
|
|
329
|
+
problems.append(f"{rel}: capability ID {token} is defined more than once")
|
|
330
|
+
capability_owner.setdefault(token, rel)
|
|
331
|
+
|
|
332
|
+
if is_requirement_table:
|
|
333
|
+
prefix_match = re.search(r"\*\*Requirement ID prefix:\*\*\s*(\S+)", text)
|
|
334
|
+
if prefix_match:
|
|
335
|
+
prefix = prefix_match.group(1)
|
|
336
|
+
if not re.fullmatch(r"[A-Z][A-Z0-9]{1,9}", prefix):
|
|
337
|
+
problems.append(
|
|
338
|
+
f"{rel}: requirement ID prefix '{prefix}' is not valid"
|
|
339
|
+
" — use capital letters and digits, starting with a letter"
|
|
340
|
+
)
|
|
341
|
+
for token in set(row_owner):
|
|
342
|
+
if token.startswith(prefix + "-"):
|
|
343
|
+
continue
|
|
344
|
+
if row_owner[token] == rel:
|
|
345
|
+
problems.append(
|
|
346
|
+
f"{rel}: requirement ID {token} does not use the declared prefix {prefix}"
|
|
347
|
+
)
|
|
348
|
+
|
|
349
|
+
return row_owner, real_rows, capability_owner, problems
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
def code_files() -> list[Path]:
|
|
353
|
+
"""Every file under `tests/` and `src/`, except `__pycache__`."""
|
|
354
|
+
files: set[Path] = set()
|
|
355
|
+
for base in (ROOT / "tests", ROOT / "src"):
|
|
356
|
+
if base.is_dir():
|
|
357
|
+
files.update(
|
|
358
|
+
path
|
|
359
|
+
for path in base.rglob("*")
|
|
360
|
+
if path.is_file() and "__pycache__" not in path.parts
|
|
361
|
+
)
|
|
362
|
+
return sorted(files)
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
def reference_files() -> list[Path]:
|
|
366
|
+
"""Files whose IDs count as references: documents under `docs/`
|
|
367
|
+
(excluding defining files, templates and the example) plus every file
|
|
368
|
+
under `tests/` and `src/`."""
|
|
369
|
+
files: set[Path] = set()
|
|
370
|
+
for path in markdown_files():
|
|
371
|
+
if not checkable_markdown(path):
|
|
372
|
+
continue
|
|
373
|
+
if path.resolve() in defining_files():
|
|
374
|
+
continue
|
|
375
|
+
if DOCS in path.parents:
|
|
376
|
+
files.add(path)
|
|
377
|
+
files.update(code_files())
|
|
378
|
+
return sorted(files)
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def check_references(row_owner: dict[str, str], capability_owner: dict[str, str]) -> list[str]:
|
|
382
|
+
problems: list[str] = []
|
|
383
|
+
|
|
384
|
+
for path in reference_files():
|
|
385
|
+
rel = str(path.relative_to(ROOT))
|
|
386
|
+
for line in read_text(path).splitlines():
|
|
387
|
+
for match in iter_tokens(line, ID_STRICT):
|
|
388
|
+
token = match.group(0)
|
|
389
|
+
if token not in row_owner:
|
|
390
|
+
problems.append(
|
|
391
|
+
f"{rel}: requirement ID {token} is not defined in SPEC.md or a feature spec"
|
|
392
|
+
)
|
|
393
|
+
for match in iter_tokens(line, CAP_STRICT):
|
|
394
|
+
token = match.group(0)
|
|
395
|
+
if token not in capability_owner:
|
|
396
|
+
problems.append(
|
|
397
|
+
f"{rel}: capability {token} is not defined in docs/product/PRD.md"
|
|
398
|
+
)
|
|
399
|
+
|
|
400
|
+
# Requirement specs' own capability references (the Serves columns).
|
|
401
|
+
for path in sorted(defining_files()):
|
|
402
|
+
rel = str(path.relative_to(ROOT))
|
|
403
|
+
for line in read_text(path).splitlines():
|
|
404
|
+
for match in iter_tokens(line, CAP_STRICT):
|
|
405
|
+
token = match.group(0)
|
|
406
|
+
if token not in capability_owner:
|
|
407
|
+
problems.append(
|
|
408
|
+
f"{rel}: capability {token} is not defined in docs/product/PRD.md"
|
|
409
|
+
)
|
|
410
|
+
return problems
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
def check_grammar() -> list[str]:
|
|
414
|
+
problems: list[str] = []
|
|
415
|
+
for path in markdown_files():
|
|
416
|
+
if not checkable_markdown(path):
|
|
417
|
+
continue
|
|
418
|
+
rel = str(path.relative_to(ROOT))
|
|
419
|
+
for line in read_text(path).splitlines():
|
|
420
|
+
for match in iter_tokens(line, ID_LOOKALIKE):
|
|
421
|
+
token = match.group(0)
|
|
422
|
+
if not is_requirement_id(token):
|
|
423
|
+
problems.append(
|
|
424
|
+
f"{rel}: '{token}' looks like a requirement ID"
|
|
425
|
+
" but is not written as SCOPE-TYPE-NNN (for example AUTH-FR-001)"
|
|
426
|
+
)
|
|
427
|
+
for match in iter_tokens(line, CAP_LOOKALIKE):
|
|
428
|
+
token = match.group(0)
|
|
429
|
+
if not is_capability_id(token):
|
|
430
|
+
problems.append(
|
|
431
|
+
f"{rel}: '{token}' looks like a capability ID"
|
|
432
|
+
" but is not written as CAP-NNN (three digits)"
|
|
433
|
+
)
|
|
434
|
+
# Code files: capability spelling only, and nothing is skipped — the
|
|
435
|
+
# illustrative-line rule is a markdown rule. Requirement ID spelling
|
|
436
|
+
# stays markdown-only because code often holds tokens that only look
|
|
437
|
+
# like requirement IDs.
|
|
438
|
+
for path in code_files():
|
|
439
|
+
rel = str(path.relative_to(ROOT))
|
|
440
|
+
for line in read_text(path).splitlines():
|
|
441
|
+
for match in CAP_LOOKALIKE.finditer(line):
|
|
442
|
+
token = match.group(0)
|
|
443
|
+
if not is_capability_id(token):
|
|
444
|
+
problems.append(
|
|
445
|
+
f"{rel}: '{token}' looks like a capability ID"
|
|
446
|
+
" but is not written as CAP-NNN (three digits)"
|
|
447
|
+
)
|
|
448
|
+
return problems
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
def check_unreferenced(row_owner: dict[str, str], real_rows: dict[str, str]) -> list[str]:
|
|
452
|
+
"""Coverage warnings: defined requirements nothing else mentions."""
|
|
453
|
+
warnings: list[str] = []
|
|
454
|
+
|
|
455
|
+
referenced: dict[str, set[str]] = {}
|
|
456
|
+
sources = set(reference_files()) | defining_files()
|
|
457
|
+
for path in sorted(sources):
|
|
458
|
+
if not checkable_markdown(path):
|
|
459
|
+
continue
|
|
460
|
+
rel = str(path.relative_to(ROOT))
|
|
461
|
+
for line in read_text(path).splitlines():
|
|
462
|
+
for match in iter_tokens(line, ID_STRICT):
|
|
463
|
+
referenced.setdefault(match.group(0), set()).add(rel)
|
|
464
|
+
|
|
465
|
+
for token, owner in sorted(real_rows.items()):
|
|
466
|
+
files = referenced.get(token, {owner})
|
|
467
|
+
if all(rel == owner for rel in files):
|
|
468
|
+
warnings.append(
|
|
469
|
+
f"{owner}: requirement {token} is defined but never referenced"
|
|
470
|
+
" by any document, plan or test"
|
|
471
|
+
)
|
|
472
|
+
return warnings
|
|
473
|
+
|
|
474
|
+
|
|
475
|
+
def check_unserved(capability_owner: dict[str, str]) -> list[str]:
|
|
476
|
+
"""Hygiene warnings: PRD capabilities no requirement serves."""
|
|
477
|
+
warnings: list[str] = []
|
|
478
|
+
|
|
479
|
+
served: set[str] = set()
|
|
480
|
+
for path in sorted(defining_files()):
|
|
481
|
+
for line in read_text(path).splitlines():
|
|
482
|
+
served.update(match.group(0) for match in iter_tokens(line, CAP_STRICT))
|
|
483
|
+
|
|
484
|
+
for token in sorted(capability_owner):
|
|
485
|
+
if token not in served:
|
|
486
|
+
warnings.append(
|
|
487
|
+
f"docs/product/PRD.md: capability {token} is not served by"
|
|
488
|
+
" any requirement in SPEC.md or a feature spec"
|
|
489
|
+
)
|
|
490
|
+
return warnings
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
def check_adr_status() -> list[str]:
|
|
494
|
+
"""Hygiene warnings: ADR status values outside the vocabulary."""
|
|
495
|
+
warnings: list[str] = []
|
|
496
|
+
allowed = ", ".join(ADR_STATUS)
|
|
497
|
+
for path in sorted(ADR_DIR.glob("*.md")):
|
|
498
|
+
if path.name == ADR_TEMPLATE:
|
|
499
|
+
continue
|
|
500
|
+
rel = str(path.relative_to(ROOT))
|
|
501
|
+
for line in read_text(path).splitlines():
|
|
502
|
+
match = STATUS_BULLET.match(line)
|
|
503
|
+
if match and not is_placeholder_status(match.group(1)):
|
|
504
|
+
if match.group(1) not in ADR_STATUS:
|
|
505
|
+
warnings.append(f"{rel}: ADR status '{match.group(1)}' is not one of {allowed}")
|
|
506
|
+
return warnings
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def check_status() -> list[str]:
|
|
510
|
+
warnings: list[str] = []
|
|
511
|
+
|
|
512
|
+
def warn(path: Path, value: str, allowed: tuple[str, ...]) -> str:
|
|
513
|
+
return f"{path.relative_to(ROOT)}: status '{value}' is not one of {', '.join(allowed)}"
|
|
514
|
+
|
|
515
|
+
for line in read_text(SYSTEM_DESIGN).splitlines():
|
|
516
|
+
match = STATUS_BULLET.match(line)
|
|
517
|
+
if match and not is_placeholder_status(match.group(1)):
|
|
518
|
+
if match.group(1) not in DOC_STATUS:
|
|
519
|
+
warnings.append(warn(SYSTEM_DESIGN, match.group(1), DOC_STATUS))
|
|
520
|
+
|
|
521
|
+
for path in feature_specs():
|
|
522
|
+
for line in read_text(path).splitlines():
|
|
523
|
+
match = re.match(r"^\*\*Status:\*\*\s*(.+?)\s*$", line)
|
|
524
|
+
if match and not is_placeholder_status(match.group(1)):
|
|
525
|
+
if match.group(1) not in DOC_STATUS:
|
|
526
|
+
warnings.append(warn(path, match.group(1), DOC_STATUS))
|
|
527
|
+
|
|
528
|
+
for cells in table_rows(read_text(SPEC)):
|
|
529
|
+
if len(cells) != 3 or "specs/" not in cells[1] or "feature-name" in cells[1]:
|
|
530
|
+
continue
|
|
531
|
+
if is_placeholder_status(cells[2]):
|
|
532
|
+
continue
|
|
533
|
+
if cells[2] not in DOC_STATUS:
|
|
534
|
+
warnings.append(warn(SPEC, cells[2], DOC_STATUS))
|
|
535
|
+
return warnings
|
|
536
|
+
|
|
537
|
+
|
|
538
|
+
def check_links() -> list[str]:
|
|
539
|
+
problems: list[str] = []
|
|
540
|
+
link = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
|
|
541
|
+
for path in markdown_files():
|
|
542
|
+
if not checkable_markdown(path):
|
|
543
|
+
continue
|
|
544
|
+
rel = str(path.relative_to(ROOT))
|
|
545
|
+
for match in link.finditer(read_text(path)):
|
|
546
|
+
target = match.group(1)
|
|
547
|
+
if target.startswith(("http://", "https://", "mailto:", "#")):
|
|
548
|
+
continue
|
|
549
|
+
if target in PLACEHOLDER_TARGETS or "[" in target:
|
|
550
|
+
continue
|
|
551
|
+
clean = target.split("#", 1)[0]
|
|
552
|
+
if not clean:
|
|
553
|
+
continue
|
|
554
|
+
if not (path.parent / clean).resolve().exists():
|
|
555
|
+
problems.append(f"{rel}: broken link to {target}")
|
|
556
|
+
return problems
|
|
557
|
+
|
|
558
|
+
|
|
559
|
+
# --- Profiles -------------------------------------------------------------
|
|
560
|
+
# A profile is `profiles/<id>/profile.json` plus, for every document it
|
|
561
|
+
# owns, a template at `profiles/<id>/templates/<document path>`. Core is
|
|
562
|
+
# the always-active profile `profiles/core/`; it also owns the documents
|
|
563
|
+
# shipped in place. See `profiles/README.md` for the schema and the rules.
|
|
564
|
+
|
|
565
|
+
|
|
566
|
+
def template_paths(directory: Path) -> set[str]:
|
|
567
|
+
"""Document paths a profile has templates for (and therefore owns)."""
|
|
568
|
+
base = directory / PROFILE_TEMPLATES
|
|
569
|
+
if not base.is_dir():
|
|
570
|
+
return set()
|
|
571
|
+
return {
|
|
572
|
+
path.relative_to(base).as_posix()
|
|
573
|
+
for path in base.rglob("*")
|
|
574
|
+
if path.is_file() and "__pycache__" not in path.parts
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
|
|
578
|
+
def has_manifest(profile_id: str) -> bool:
|
|
579
|
+
"""True when a profile folder has a manifest, valid or not."""
|
|
580
|
+
return PROFILE_ID.fullmatch(profile_id) is not None and (
|
|
581
|
+
PROFILES_DIR / profile_id / PROFILE_FILE
|
|
582
|
+
).is_file()
|
|
583
|
+
|
|
584
|
+
|
|
585
|
+
def template_for(profile_id: str, document: str) -> Path:
|
|
586
|
+
return PROFILES_DIR / profile_id / PROFILE_TEMPLATES / document
|
|
587
|
+
|
|
588
|
+
|
|
589
|
+
def is_text_list(value: object, allow_empty: bool = True) -> bool:
|
|
590
|
+
return (
|
|
591
|
+
isinstance(value, list)
|
|
592
|
+
and (allow_empty or bool(value))
|
|
593
|
+
and all(isinstance(item, str) and item.strip() for item in value)
|
|
594
|
+
)
|
|
595
|
+
|
|
596
|
+
|
|
597
|
+
def validate_profile(directory: Path, data: object) -> list[str]:
|
|
598
|
+
"""Schema problems in one manifest, without the leading file name."""
|
|
599
|
+
if not isinstance(data, dict):
|
|
600
|
+
return ["must be a JSON object"]
|
|
601
|
+
is_core = directory.name == CORE
|
|
602
|
+
allowed = CORE_FIELDS if is_core else PROFILE_FIELDS
|
|
603
|
+
missing = [f"missing field '{key}'" for key in sorted(allowed - data.keys())]
|
|
604
|
+
problems = [f"unknown field '{key}'" for key in sorted(data.keys() - allowed)]
|
|
605
|
+
if missing:
|
|
606
|
+
return missing + problems
|
|
607
|
+
|
|
608
|
+
if data["schema"] != PROFILE_SCHEMA:
|
|
609
|
+
problems.append(f"schema is {data['schema']!r}, but this checker understands {PROFILE_SCHEMA}")
|
|
610
|
+
if not isinstance(data["id"], str) or not PROFILE_ID.fullmatch(data["id"]):
|
|
611
|
+
problems.append("id must be lowercase letters, digits and hyphens, starting with a letter")
|
|
612
|
+
elif data["id"] != directory.name:
|
|
613
|
+
problems.append(f"id '{data['id']}' does not match its folder name '{directory.name}'")
|
|
614
|
+
for key in ("name", "purpose"):
|
|
615
|
+
if not isinstance(data[key], str) or not data[key].strip():
|
|
616
|
+
problems.append(f"'{key}' must be a non-empty string")
|
|
617
|
+
|
|
618
|
+
if not is_core:
|
|
619
|
+
if not is_text_list(data["use_when"], allow_empty=False):
|
|
620
|
+
problems.append("'use_when' must be a non-empty list of strings")
|
|
621
|
+
if not is_text_list(data["not_when"]):
|
|
622
|
+
problems.append("'not_when' must be a list of strings")
|
|
623
|
+
if not is_text_list(data["incompatible_with"]):
|
|
624
|
+
problems.append("'incompatible_with' must be a list of profile IDs")
|
|
625
|
+
requires = data["requires"]
|
|
626
|
+
if not isinstance(requires, list) or not all(
|
|
627
|
+
(isinstance(entry, str) and entry) or is_text_list(entry, allow_empty=False)
|
|
628
|
+
for entry in requires
|
|
629
|
+
):
|
|
630
|
+
problems.append(
|
|
631
|
+
"'requires' must be a list whose entries are a profile ID"
|
|
632
|
+
" or a list of profile IDs (any one of them will do)"
|
|
633
|
+
)
|
|
634
|
+
checks = data["checks"]
|
|
635
|
+
if not isinstance(checks, list) or not all(
|
|
636
|
+
isinstance(check, dict)
|
|
637
|
+
and check.keys() == {"name", "what"}
|
|
638
|
+
and all(isinstance(check[key], str) and check[key].strip() for key in check)
|
|
639
|
+
for check in checks
|
|
640
|
+
):
|
|
641
|
+
problems.append("'checks' must be a list of objects with exactly 'name' and 'what'")
|
|
642
|
+
|
|
643
|
+
documents = data["documents"]
|
|
644
|
+
if not isinstance(documents, list):
|
|
645
|
+
return problems + ["'documents' must be a list"]
|
|
646
|
+
listed: set[str] = set()
|
|
647
|
+
for index, doc in enumerate(documents):
|
|
648
|
+
where = f"documents[{index}]"
|
|
649
|
+
if not isinstance(doc, dict) or not {"path", "required"} <= doc.keys() <= {"path", "required", "when"}:
|
|
650
|
+
problems.append(f"{where} must have 'path' and 'required', and optionally 'when'")
|
|
651
|
+
continue
|
|
652
|
+
path, required = doc["path"], doc["required"]
|
|
653
|
+
if (
|
|
654
|
+
not isinstance(path, str)
|
|
655
|
+
or not path
|
|
656
|
+
or path.startswith("/")
|
|
657
|
+
or "\\" in path
|
|
658
|
+
or ".." in path.split("/")
|
|
659
|
+
or path.split("/")[0] == PROFILES_DIR.name
|
|
660
|
+
):
|
|
661
|
+
problems.append(f"{where}: path must be a relative path outside profiles/, written with '/'")
|
|
662
|
+
continue
|
|
663
|
+
if not isinstance(required, bool):
|
|
664
|
+
problems.append(f"{path}: 'required' must be true or false")
|
|
665
|
+
elif not required and not (isinstance(doc.get("when"), str) and doc["when"].strip()):
|
|
666
|
+
problems.append(f"{path}: an optional document needs a 'when' saying when to create it")
|
|
667
|
+
elif required and "when" in doc:
|
|
668
|
+
problems.append(f"{path}: a required document has no 'when' — remove it, or make the document optional")
|
|
669
|
+
if path in listed:
|
|
670
|
+
problems.append(f"{path}: listed more than once")
|
|
671
|
+
listed.add(path)
|
|
672
|
+
|
|
673
|
+
for orphan in sorted(template_paths(directory) - listed):
|
|
674
|
+
problems.append(
|
|
675
|
+
f"template {PROFILE_TEMPLATES}/{orphan} is not listed in 'documents'"
|
|
676
|
+
" — list it, or delete the template"
|
|
677
|
+
)
|
|
678
|
+
if not is_core and not (directory / "README.md").is_file():
|
|
679
|
+
problems.append("profile has no README.md with its standards and agent instructions")
|
|
680
|
+
return problems
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def load_profiles() -> tuple[dict[str, dict], list[str]]:
|
|
684
|
+
"""Valid manifests by ID, and the problems found. Empty without `profiles/`."""
|
|
685
|
+
profiles: dict[str, dict] = {}
|
|
686
|
+
problems: list[str] = []
|
|
687
|
+
if not PROFILES_DIR.is_dir():
|
|
688
|
+
return profiles, problems
|
|
689
|
+
for directory in sorted(path for path in PROFILES_DIR.iterdir() if path.is_dir()):
|
|
690
|
+
if directory.name == "__pycache__":
|
|
691
|
+
continue
|
|
692
|
+
manifest = directory / PROFILE_FILE
|
|
693
|
+
rel = manifest.relative_to(ROOT).as_posix()
|
|
694
|
+
if not manifest.is_file():
|
|
695
|
+
problems.append(f"{rel}: missing — every folder in profiles/ needs a {PROFILE_FILE}")
|
|
696
|
+
continue
|
|
697
|
+
try:
|
|
698
|
+
data = json.loads(manifest.read_text(encoding="utf-8"))
|
|
699
|
+
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
|
|
700
|
+
problems.append(f"{rel}: not valid JSON ({error})")
|
|
701
|
+
continue
|
|
702
|
+
found = validate_profile(directory, data)
|
|
703
|
+
problems += [f"{rel}: {problem}" for problem in found]
|
|
704
|
+
if not found:
|
|
705
|
+
profiles[data["id"]] = data
|
|
706
|
+
if CORE not in profiles and not any(f"profiles/{CORE}/" in p for p in problems):
|
|
707
|
+
problems.append(f"profiles/{CORE}/{PROFILE_FILE}: missing — core is required once profiles/ exists")
|
|
708
|
+
return profiles, problems
|
|
709
|
+
|
|
710
|
+
|
|
711
|
+
def document_owners(profiles: dict[str, dict]) -> tuple[dict[str, str], list[str]]:
|
|
712
|
+
"""Map each document path to its one owner, and report ownership problems.
|
|
713
|
+
|
|
714
|
+
Core owns every document it lists. Any other profile owns exactly the
|
|
715
|
+
documents it has templates for. A profile may list its own documents
|
|
716
|
+
and core documents, never another profile's.
|
|
717
|
+
"""
|
|
718
|
+
owners: dict[str, str] = {}
|
|
719
|
+
problems: list[str] = []
|
|
720
|
+
order = ([CORE] if CORE in profiles else []) + sorted(p for p in profiles if p != CORE)
|
|
721
|
+
|
|
722
|
+
for profile_id in order:
|
|
723
|
+
owned = template_paths(PROFILES_DIR / profile_id)
|
|
724
|
+
if profile_id == CORE:
|
|
725
|
+
owned |= {doc["path"] for doc in profiles[CORE]["documents"]}
|
|
726
|
+
for path in sorted(owned):
|
|
727
|
+
if path in owners:
|
|
728
|
+
problems.append(
|
|
729
|
+
f"{path}: owned by both the {owners[path]} and {profile_id} profiles"
|
|
730
|
+
" — a document has one owner; if several profiles need it, move it into core"
|
|
731
|
+
)
|
|
732
|
+
continue
|
|
733
|
+
owners[path] = profile_id
|
|
734
|
+
|
|
735
|
+
# Without a valid core, every core reference would look ownerless; the
|
|
736
|
+
# missing or broken core manifest is already reported.
|
|
737
|
+
check_references_to = order if CORE in profiles else []
|
|
738
|
+
for profile_id in check_references_to:
|
|
739
|
+
for doc in profiles[profile_id]["documents"]:
|
|
740
|
+
path = doc["path"]
|
|
741
|
+
owner = owners.get(path)
|
|
742
|
+
rel = f"profiles/{profile_id}/{PROFILE_FILE}"
|
|
743
|
+
if owner is None:
|
|
744
|
+
problems.append(
|
|
745
|
+
f"{rel}: {path} has no template — add"
|
|
746
|
+
f" profiles/{profile_id}/{PROFILE_TEMPLATES}/{path}"
|
|
747
|
+
)
|
|
748
|
+
elif owner not in (profile_id, CORE):
|
|
749
|
+
problems.append(
|
|
750
|
+
f"{rel}: lists {path}, which the {owner} profile owns"
|
|
751
|
+
" — a profile may list only its own documents and core documents;"
|
|
752
|
+
" if several profiles need it, move it into core"
|
|
753
|
+
)
|
|
754
|
+
|
|
755
|
+
for profile_id in order:
|
|
756
|
+
data = profiles[profile_id]
|
|
757
|
+
if profile_id == CORE:
|
|
758
|
+
continue
|
|
759
|
+
rel = f"profiles/{profile_id}/{PROFILE_FILE}"
|
|
760
|
+
named = [
|
|
761
|
+
other
|
|
762
|
+
for entry in data["requires"]
|
|
763
|
+
for other in ([entry] if isinstance(entry, str) else entry)
|
|
764
|
+
] + list(data["incompatible_with"])
|
|
765
|
+
for other in named:
|
|
766
|
+
if other == profile_id:
|
|
767
|
+
problems.append(f"{rel}: a profile cannot require or exclude itself")
|
|
768
|
+
elif other == CORE:
|
|
769
|
+
problems.append(f"{rel}: core is always active — don't name it in 'requires' or 'incompatible_with'")
|
|
770
|
+
elif other not in profiles and not has_manifest(other):
|
|
771
|
+
problems.append(f"{rel}: names unknown profile '{other}'")
|
|
772
|
+
return owners, problems
|
|
773
|
+
|
|
774
|
+
|
|
775
|
+
def parse_profiles(value: str) -> list[str] | None:
|
|
776
|
+
"""The IDs on a `- Profiles:` line; None while it is still a placeholder."""
|
|
777
|
+
value = value.strip()
|
|
778
|
+
if not value or value.startswith("["):
|
|
779
|
+
return None
|
|
780
|
+
if value.lower() == "none":
|
|
781
|
+
return []
|
|
782
|
+
return [part.strip() for part in value.split(",") if part.strip()]
|
|
783
|
+
|
|
784
|
+
|
|
785
|
+
def declared_profiles() -> list[str] | None:
|
|
786
|
+
"""Profiles chosen in PROJECT.md; None when not chosen yet."""
|
|
787
|
+
for line in read_text(PROJECT).splitlines():
|
|
788
|
+
match = PROFILES_BULLET.match(line)
|
|
789
|
+
if match:
|
|
790
|
+
return parse_profiles(match.group(1))
|
|
791
|
+
return None
|
|
792
|
+
|
|
793
|
+
|
|
794
|
+
def check_selection(selected: list[str], profiles: dict[str, dict]) -> list[str]:
|
|
795
|
+
"""Unknown IDs, missing dependencies and incompatible pairs."""
|
|
796
|
+
problems: list[str] = []
|
|
797
|
+
known = ", ".join(sorted(p for p in profiles if p != CORE)) or "none"
|
|
798
|
+
seen: set[str] = set()
|
|
799
|
+
for profile_id in selected:
|
|
800
|
+
if profile_id in seen:
|
|
801
|
+
problems.append(f"PROJECT.md: profile '{profile_id}' is listed twice")
|
|
802
|
+
seen.add(profile_id)
|
|
803
|
+
if profile_id == CORE:
|
|
804
|
+
problems.append("PROJECT.md: core is always active — don't list it under Profiles")
|
|
805
|
+
elif profile_id not in profiles and has_manifest(profile_id):
|
|
806
|
+
problems.append(f"PROJECT.md: profile '{profile_id}' has manifest errors — fix them first")
|
|
807
|
+
elif profile_id not in profiles:
|
|
808
|
+
problems.append(f"PROJECT.md: unknown profile '{profile_id}' — known profiles: {known}")
|
|
809
|
+
|
|
810
|
+
active = [p for p in dict.fromkeys(selected) if p in profiles and p != CORE]
|
|
811
|
+
for profile_id in active:
|
|
812
|
+
for entry in profiles[profile_id]["requires"]:
|
|
813
|
+
options = [entry] if isinstance(entry, str) else list(entry)
|
|
814
|
+
if not any(option in active for option in options):
|
|
815
|
+
wanted = options[0] if len(options) == 1 else "one of " + ", ".join(options)
|
|
816
|
+
problems.append(
|
|
817
|
+
f"PROJECT.md: the {profile_id} profile requires {wanted}, which is not active"
|
|
818
|
+
)
|
|
819
|
+
reported: set[tuple[str, str]] = set()
|
|
820
|
+
for profile_id in active:
|
|
821
|
+
for other in profiles[profile_id]["incompatible_with"]:
|
|
822
|
+
pair = tuple(sorted((profile_id, other)))
|
|
823
|
+
if other in active and pair not in reported:
|
|
824
|
+
reported.add(pair)
|
|
825
|
+
problems.append(
|
|
826
|
+
f"PROJECT.md: the {pair[0]} and {pair[1]} profiles are declared incompatible"
|
|
827
|
+
" — choose one, or record in an ADR why the system needs both and change the manifests"
|
|
828
|
+
)
|
|
829
|
+
return problems
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
def active_profiles(selected: list[str] | None, profiles: dict[str, dict]) -> list[str]:
|
|
833
|
+
"""Core plus the valid selected profiles, in a stable order."""
|
|
834
|
+
chosen = [p for p in dict.fromkeys(selected or []) if p in profiles and p != CORE]
|
|
835
|
+
return ([CORE] if CORE in profiles else []) + chosen
|
|
836
|
+
|
|
837
|
+
|
|
838
|
+
def required_documents(active: list[str], profiles: dict[str, dict]) -> dict[str, list[str]]:
|
|
839
|
+
"""Each required document, with the active profiles that require it."""
|
|
840
|
+
required: dict[str, list[str]] = {}
|
|
841
|
+
for profile_id in active:
|
|
842
|
+
for doc in profiles[profile_id]["documents"]:
|
|
843
|
+
if doc["required"]:
|
|
844
|
+
required.setdefault(doc["path"], []).append(profile_id)
|
|
845
|
+
return required
|
|
846
|
+
|
|
847
|
+
|
|
848
|
+
def check_required_documents(
|
|
849
|
+
active: list[str], profiles: dict[str, dict], owners: dict[str, str]
|
|
850
|
+
) -> list[str]:
|
|
851
|
+
problems: list[str] = []
|
|
852
|
+
for path, needed_by in sorted(required_documents(active, profiles).items()):
|
|
853
|
+
if (ROOT / path).exists():
|
|
854
|
+
continue
|
|
855
|
+
owner = owners.get(path, CORE)
|
|
856
|
+
if template_for(owner, path).is_file():
|
|
857
|
+
fix = (
|
|
858
|
+
"run python3 scripts/groundwork.py init with your profiles,"
|
|
859
|
+
f" or copy profiles/{owner}/{PROFILE_TEMPLATES}/{path}"
|
|
860
|
+
)
|
|
861
|
+
else:
|
|
862
|
+
fix = "restore it from the Groundwork release"
|
|
863
|
+
problems.append(f"{path}: required by {', '.join(needed_by)} but missing — {fix}")
|
|
864
|
+
return problems
|
|
865
|
+
|
|
866
|
+
|
|
867
|
+
def check_inactive_documents(
|
|
868
|
+
selected: list[str] | None, active: list[str], owners: dict[str, str]
|
|
869
|
+
) -> list[str]:
|
|
870
|
+
"""Hygiene warnings: documents that belong to a profile not in use."""
|
|
871
|
+
if selected is None:
|
|
872
|
+
return []
|
|
873
|
+
return [
|
|
874
|
+
f"{path}: belongs to the {owner} profile, which PROJECT.md does not list"
|
|
875
|
+
" — add the profile, or delete the document"
|
|
876
|
+
for path, owner in sorted(owners.items())
|
|
877
|
+
if owner not in active and (ROOT / path).exists()
|
|
878
|
+
]
|
|
879
|
+
|
|
880
|
+
|
|
881
|
+
def tooling_concerns() -> list[str]:
|
|
882
|
+
"""First cells of the tooling table in AGENTS.md, lowercased."""
|
|
883
|
+
concerns: list[str] = []
|
|
884
|
+
inside = False
|
|
885
|
+
for line in read_text(AGENTS).splitlines():
|
|
886
|
+
if line.lstrip().startswith("#"):
|
|
887
|
+
inside = "tooling" in line.lower()
|
|
888
|
+
continue
|
|
889
|
+
if inside and TABLE_LINE.match(line):
|
|
890
|
+
first = line.strip().strip("|").split("|")[0].strip()
|
|
891
|
+
if first and set(first) - set("-: "):
|
|
892
|
+
concerns.append(first.lower())
|
|
893
|
+
return concerns
|
|
894
|
+
|
|
895
|
+
|
|
896
|
+
def missing_checks(active: list[str], profiles: dict[str, dict]) -> list[tuple[str, dict]]:
|
|
897
|
+
"""(profile, check) pairs with no tooling-table row; one per check name."""
|
|
898
|
+
concerns = tooling_concerns()
|
|
899
|
+
missing: list[tuple[str, dict]] = []
|
|
900
|
+
seen: set[str] = set()
|
|
901
|
+
for profile_id in active:
|
|
902
|
+
for check in profiles[profile_id].get("checks", []):
|
|
903
|
+
name = check["name"].lower()
|
|
904
|
+
if name in seen or any(concern.startswith(name) for concern in concerns):
|
|
905
|
+
continue
|
|
906
|
+
seen.add(name)
|
|
907
|
+
missing.append((profile_id, check))
|
|
908
|
+
return missing
|
|
909
|
+
|
|
910
|
+
|
|
911
|
+
def check_profile_tooling(active: list[str], profiles: dict[str, dict]) -> list[str]:
|
|
912
|
+
"""Hygiene warnings: profile checks with no row in the tooling table."""
|
|
913
|
+
return [
|
|
914
|
+
f"AGENTS.md: the {profile_id} profile needs the '{check['name']}' check"
|
|
915
|
+
" — add a row to the tooling table naming the tool, or say why it doesn't apply"
|
|
916
|
+
for profile_id, check in missing_checks(active, profiles)
|
|
917
|
+
]
|
|
918
|
+
|
|
919
|
+
|
|
920
|
+
def profile_results() -> tuple[list[str], list[str], str]:
|
|
921
|
+
"""Profile errors, profile hygiene warnings, and a one-line summary."""
|
|
922
|
+
if not PROFILES_DIR.is_dir():
|
|
923
|
+
return [], [], ""
|
|
924
|
+
profiles, errors = load_profiles()
|
|
925
|
+
owners, ownership_problems = document_owners(profiles)
|
|
926
|
+
selected = declared_profiles()
|
|
927
|
+
errors += ownership_problems + check_selection(selected or [], profiles)
|
|
928
|
+
active = active_profiles(selected, profiles)
|
|
929
|
+
errors += check_required_documents(active, profiles, owners)
|
|
930
|
+
warnings = check_inactive_documents(selected, active, owners) + check_profile_tooling(active, profiles)
|
|
931
|
+
if selected is None:
|
|
932
|
+
summary = "profiles: not chosen yet"
|
|
933
|
+
else:
|
|
934
|
+
summary = "profiles: " + (", ".join(selected) or "none (core only)")
|
|
935
|
+
return errors, warnings, summary
|
|
936
|
+
|
|
937
|
+
|
|
938
|
+
def main() -> int:
|
|
939
|
+
parser = argparse.ArgumentParser(description="Validate Groundwork documentation consistency.")
|
|
940
|
+
parser.add_argument(
|
|
941
|
+
"--strict",
|
|
942
|
+
action="store_true",
|
|
943
|
+
help="treat hygiene warnings (status values, unserved capabilities, profile hygiene) as errors",
|
|
944
|
+
)
|
|
945
|
+
parser.add_argument(
|
|
946
|
+
"--strict-coverage",
|
|
947
|
+
action="store_true",
|
|
948
|
+
help="treat coverage warnings (requirements nothing references) as errors",
|
|
949
|
+
)
|
|
950
|
+
args = parser.parse_args()
|
|
951
|
+
|
|
952
|
+
row_owner, real_rows, capability_owner, definition_problems = collect_definitions()
|
|
953
|
+
profile_errors, profile_warnings, profile_summary = profile_results()
|
|
954
|
+
errors = (
|
|
955
|
+
check_manifest()
|
|
956
|
+
+ check_feature_index()
|
|
957
|
+
+ definition_problems
|
|
958
|
+
+ check_references(row_owner, capability_owner)
|
|
959
|
+
+ check_grammar()
|
|
960
|
+
+ check_links()
|
|
961
|
+
+ profile_errors
|
|
962
|
+
)
|
|
963
|
+
hygiene_warnings = (
|
|
964
|
+
check_unserved(capability_owner) + check_status() + check_adr_status() + profile_warnings
|
|
965
|
+
)
|
|
966
|
+
coverage_warnings = check_unreferenced(row_owner, real_rows)
|
|
967
|
+
warnings = hygiene_warnings + coverage_warnings
|
|
968
|
+
|
|
969
|
+
for problem in errors:
|
|
970
|
+
print(f"FAIL: {problem}")
|
|
971
|
+
for warning in hygiene_warnings:
|
|
972
|
+
print(f"WARN: {warning}")
|
|
973
|
+
for warning in coverage_warnings:
|
|
974
|
+
print(f"WARN (coverage): {warning}")
|
|
975
|
+
|
|
976
|
+
if errors or (args.strict and hygiene_warnings) or (args.strict_coverage and coverage_warnings):
|
|
977
|
+
return 1
|
|
978
|
+
checked = "manifest, feature index, requirement IDs and links are consistent"
|
|
979
|
+
if profile_summary:
|
|
980
|
+
checked = f"manifest, feature index, requirement IDs, links and profiles are consistent ({profile_summary})"
|
|
981
|
+
if warnings:
|
|
982
|
+
print(f"OK (warnings above): {checked}")
|
|
983
|
+
return 0
|
|
984
|
+
print(f"OK: {checked}")
|
|
985
|
+
return 0
|
|
986
|
+
|
|
987
|
+
|
|
988
|
+
if __name__ == "__main__":
|
|
989
|
+
sys.exit(main())
|