project-spec 0.8.0 → 0.9.1
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 +62 -325
- package/bin/project-spec.mjs +6 -2
- package/package.json +1 -1
- package/skills/project-knowledge/SKILL.md +27 -8
- package/skills/project-knowledge/assets/viewer.html +236 -62
- package/skills/project-knowledge/references/format.md +10 -5
- package/skills/project-knowledge/references/gaps.md +1 -1
- package/skills/project-knowledge/scripts/coverage.py +200 -0
- package/skills/project-knowledge/scripts/knowledge.py +62 -19
- package/skills/project-knowledge/scripts/test_coverage.py +128 -0
- package/skills/project-knowledge/scripts/test_knowledge.py +75 -0
- package/skills/spec-change/references/gaps.md +1 -1
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""List what the code has that no spec page mentions yet, using only the standard library.
|
|
3
|
+
|
|
4
|
+
It reads the application's code files and the spec pages and compares three things a spec is supposed to hold:
|
|
5
|
+
the files pages cite, the sentences a person can see (messages, labels, empty states) and the numeric limits.
|
|
6
|
+
What it prints is a list of places to read, not a score: a sentence that is not on a page may be a button that
|
|
7
|
+
only opens something, which the spec leaves out on purpose.
|
|
8
|
+
"""
|
|
9
|
+
import argparse
|
|
10
|
+
import os
|
|
11
|
+
import posixpath
|
|
12
|
+
import re
|
|
13
|
+
import sys
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
import knowledge
|
|
17
|
+
|
|
18
|
+
CODE = {'.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte', '.py', '.rb', '.go', '.rs', '.java', '.kt', '.kts',
|
|
19
|
+
'.swift', '.cs', '.php', '.dart', '.ex', '.exs', '.scala', '.sql', '.c', '.cc', '.cpp', '.h', '.m', '.mm'}
|
|
20
|
+
SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', 'out', 'vendor', 'target', '.next', '.nuxt', '.expo', 'coverage', '__pycache__',
|
|
21
|
+
'.venv', 'venv', 'Pods', '.gradle', 'bin', 'obj', '.turbo', '.cache', 'generated', '__generated__',
|
|
22
|
+
# A migration is the history of the schema, not what the product does today.
|
|
23
|
+
'migrations', 'Migrations', 'migration'}
|
|
24
|
+
# A file with this many sentences is text someone wrote for readers (an article, a template, legal terms): the spec
|
|
25
|
+
# lists such things, it does not quote them, so they count as files and lines only.
|
|
26
|
+
CONTENT_SENTENCES = 40
|
|
27
|
+
# Tests, fixtures and stories say what the code does in someone else's words; they are not what a person sees.
|
|
28
|
+
TEST_DIR = re.compile(r'(^|/)(tests?|__tests__|__mocks__|__snapshots__|fixtures?|testdata|e2e|stories|specs?|mocks?|seeds?)(/|$)', re.I)
|
|
29
|
+
TEST_FILE = re.compile(r'(\.(test|spec|stories|e2e|mock|fixture)\.|_test\.|(^|/)test_[^/]*$|\.d\.ts$|\.min\.|\.generated\.|\.g\.dart$)', re.I)
|
|
30
|
+
FILE_LIMIT = 1_000_000
|
|
31
|
+
QUOTED = re.compile(r'''(["'`])((?:\\.|(?!\1)[^\\\n])*)\1''')
|
|
32
|
+
JSX_TEXT = re.compile(r'>\s*([A-Z][^<>{}\n]{10,200}?)\s*<')
|
|
33
|
+
LOG_LINE = re.compile(r'\b(console|logger|log|logging|Sentry|debug)\s*\.\s*\w+\s*\(|^\s*(import|from|describe|it|test|#include|using|package)\b|^\s*(//|#|\*|/\*)')
|
|
34
|
+
NOT_PROSE = re.compile(r'[{}<>;=\\]|\$\(|^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b|https?://|\w+\.\w+\(|\w/\w+/\w')
|
|
35
|
+
# A named number: MAX_ATTACHMENTS = 10, TTL_MS: number = 60 * 60 * 1000
|
|
36
|
+
LIMIT = re.compile(r'\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\s*(?::[^=\n]{1,40})?=\s*([-+]?\d[\d_.]*(?:\s*[*/+-]\s*\d[\d_.]*)*)\s*[;,]?\s*(?:(?://|#).*)?$', re.M)
|
|
37
|
+
PUNCTUATION = str.maketrans({'‘': "'", '’': "'", '“': '"', '”': '"', '–': '-', '—': '-', ' ': ' '})
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def plain(text):
|
|
41
|
+
"""Text as it is compared: case, curly quotes, runs of spaces and Markdown's escaped pipe do not count."""
|
|
42
|
+
return re.sub(r'\s+', ' ', text.translate(PUNCTUATION).replace('\\|', '|')).casefold().strip()
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def is_sentence(text):
|
|
46
|
+
"""Does this string read like something shown to a person, rather than a key, a class list or a query?"""
|
|
47
|
+
text = text.strip()
|
|
48
|
+
if not 12 <= len(text) <= 200 or not text[0].isupper() or len(text.split()) < 3 or NOT_PROSE.search(text):
|
|
49
|
+
return False
|
|
50
|
+
letters = sum(1 for c in text if c.isalpha() or c == ' ')
|
|
51
|
+
return letters / len(text) >= 0.8
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def sentences_in(text):
|
|
55
|
+
found = []
|
|
56
|
+
for line in text.split('\n'):
|
|
57
|
+
if LOG_LINE.search(line):
|
|
58
|
+
continue
|
|
59
|
+
for _, inner in QUOTED.findall(line):
|
|
60
|
+
inner = re.sub(r"\\(['\"`])", r'\1', inner)
|
|
61
|
+
if is_sentence(inner):
|
|
62
|
+
found.append(inner.strip())
|
|
63
|
+
found += [m.strip() for m in JSX_TEXT.findall(line) if is_sentence(m)]
|
|
64
|
+
return list(dict.fromkeys(found))
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def code_files(repo, vault):
|
|
68
|
+
"""Repository-relative paths of the application's own code: tracked or untracked but not ignored, no tests."""
|
|
69
|
+
listed = knowledge.run_git(repo, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'])
|
|
70
|
+
if listed.returncode == 0:
|
|
71
|
+
names = [os.fsdecode(n) for n in listed.stdout.split(b'\0') if n]
|
|
72
|
+
else:
|
|
73
|
+
names = []
|
|
74
|
+
for folder, dirs, files in os.walk(repo):
|
|
75
|
+
dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith('.'))
|
|
76
|
+
names += [Path(os.path.relpath(Path(folder) / f, repo)).as_posix() for f in sorted(files)]
|
|
77
|
+
inside = Path(os.path.relpath(vault, repo)).as_posix() + '/'
|
|
78
|
+
return sorted(n for n in names
|
|
79
|
+
if posixpath.splitext(n)[1].lower() in CODE and not n.startswith(inside)
|
|
80
|
+
and not any(part in SKIP_DIRS for part in n.split('/')[:-1])
|
|
81
|
+
and not TEST_DIR.search(posixpath.dirname(n)) and not TEST_FILE.search(n))
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def measure(repo, vault, notes, prefixes=()):
|
|
85
|
+
"""Per code file: lines, whether a page cites it, and the sentences and limits no page mentions."""
|
|
86
|
+
spec = [n for n in notes if n['meta']['type'] in {'area', 'note'}]
|
|
87
|
+
pages = plain('\n'.join(f"{n['meta']['title']}\n{n['meta'].get('summary', '')}\n{n['body']}" for n in spec))
|
|
88
|
+
words = set(re.findall(r'[A-Z][A-Z0-9_]+', '\n'.join(n['body'] for n in spec)))
|
|
89
|
+
cited = {posixpath.normpath(s) for n in spec for s in n['meta']['sources']}
|
|
90
|
+
files = {}
|
|
91
|
+
for name in code_files(repo, vault):
|
|
92
|
+
if prefixes and not any(name == p or name.startswith(p.rstrip('/') + '/') for p in prefixes):
|
|
93
|
+
continue
|
|
94
|
+
path = repo / name
|
|
95
|
+
try:
|
|
96
|
+
if path.is_symlink() or path.stat().st_size > FILE_LIMIT:
|
|
97
|
+
continue
|
|
98
|
+
text = path.read_bytes().decode('utf-8')
|
|
99
|
+
except (OSError, UnicodeDecodeError):
|
|
100
|
+
continue
|
|
101
|
+
sentences = sentences_in(text)
|
|
102
|
+
content = len(sentences) >= CONTENT_SENTENCES
|
|
103
|
+
if content:
|
|
104
|
+
sentences = []
|
|
105
|
+
limits = list(dict.fromkeys(LIMIT.findall(text)))
|
|
106
|
+
files[name] = {
|
|
107
|
+
'lines': text.count('\n') + 1, 'cited': name in cited, 'content': content, 'sentences': len(sentences), 'limits': len(limits),
|
|
108
|
+
'unquoted': [s for s in sentences if plain(s).rstrip('.!?:…') not in pages],
|
|
109
|
+
'unnamed': [(n, v.strip()) for n, v in limits if n not in words]}
|
|
110
|
+
return files
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def folders(files, prefixes=()):
|
|
114
|
+
"""Group files into the places to read: a folder no page cites anything in is one line, however deep it goes.
|
|
115
|
+
|
|
116
|
+
With prefixes (the folders the caller asked about) a line never names a folder above the one asked for."""
|
|
117
|
+
cited_under = {}
|
|
118
|
+
for name, info in files.items():
|
|
119
|
+
if info['cited']:
|
|
120
|
+
parts = name.split('/')[:-1]
|
|
121
|
+
for i in range(len(parts) + 1):
|
|
122
|
+
cited_under['/'.join(parts[:i])] = True
|
|
123
|
+
groups = {}
|
|
124
|
+
for name, info in files.items():
|
|
125
|
+
parts = name.split('/')[:-1]
|
|
126
|
+
folder = '/'.join(parts)
|
|
127
|
+
floor = max((len(p.split('/')) for p in prefixes if name.startswith(p.rstrip('/') + '/')), default=1)
|
|
128
|
+
# Climb to the highest folder that still has no cited file under it.
|
|
129
|
+
for i in range(min(floor, len(parts)) or 1, len(parts) + 1):
|
|
130
|
+
if not cited_under.get('/'.join(parts[:i])):
|
|
131
|
+
folder = '/'.join(parts[:i])
|
|
132
|
+
break
|
|
133
|
+
g = groups.setdefault(folder or '.', {'files': 0, 'lines': 0, 'cited': 0, 'sentences': 0, 'unquoted': 0, 'limits': 0, 'unnamed': 0})
|
|
134
|
+
g['files'] += 1
|
|
135
|
+
g['lines'] += info['lines']
|
|
136
|
+
g['cited'] += info['cited']
|
|
137
|
+
g['sentences'] += info['sentences']
|
|
138
|
+
g['unquoted'] += len(info['unquoted'])
|
|
139
|
+
g['limits'] += info['limits']
|
|
140
|
+
g['unnamed'] += len(info['unnamed'])
|
|
141
|
+
return groups
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def main(argv=None):
|
|
145
|
+
parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
|
|
146
|
+
parser.add_argument('--repo', required=True, type=Path)
|
|
147
|
+
parser.add_argument('--vault', type=Path, help='default: the single vault under knowledge/ in the repository')
|
|
148
|
+
parser.add_argument('--path', action='append', default=[], metavar='FOLDER',
|
|
149
|
+
help='only this folder or file of the repository, and list each sentence and limit no page mentions; repeatable')
|
|
150
|
+
parser.add_argument('--all', action='store_true', help='print every line instead of the first 40 folders or 60 items')
|
|
151
|
+
args = parser.parse_args(argv)
|
|
152
|
+
repo = args.repo.resolve()
|
|
153
|
+
if not repo.is_dir():
|
|
154
|
+
parser.error('repo must be an existing directory')
|
|
155
|
+
try:
|
|
156
|
+
vault = args.vault.resolve() if args.vault else knowledge.find_vault(repo)
|
|
157
|
+
except ValueError as exc:
|
|
158
|
+
parser.error(str(exc))
|
|
159
|
+
if not vault.is_dir():
|
|
160
|
+
parser.error('repo and vault must be existing directories')
|
|
161
|
+
notes, _, errors, _, _ = knowledge.load_vault(repo, vault, freshness=False, absent=[])
|
|
162
|
+
if errors:
|
|
163
|
+
print(f'coverage: the vault has {len(errors)} errors; pages with errors are not counted (run check)', file=sys.stderr)
|
|
164
|
+
prefixes = [posixpath.normpath(p.replace(os.sep, '/')) for p in args.path]
|
|
165
|
+
files = measure(repo, vault, notes, prefixes)
|
|
166
|
+
if not files:
|
|
167
|
+
print('coverage: no code files found' + (' under ' + ', '.join(prefixes) if prefixes else ''))
|
|
168
|
+
return 0
|
|
169
|
+
total = lambda key: sum(len(f[key]) if isinstance(f[key], list) else f[key] for f in files.values())
|
|
170
|
+
print(f"coverage: {len(files)} code files, {total('lines')} lines; pages cite {total('cited')} of them")
|
|
171
|
+
print(f"coverage: {total('sentences')} sentences a person can see, {total('unquoted')} on no page; "
|
|
172
|
+
f"{total('limits')} named numbers, {total('unnamed')} on no page")
|
|
173
|
+
texts = sum(1 for f in files.values() if f['content'])
|
|
174
|
+
print('coverage: this is a list of places to read, not a score; tests, fixtures, migrations and generated code are left out'
|
|
175
|
+
+ (f'; {texts} files that are mostly text (articles, templates) count as files only' if texts else ''))
|
|
176
|
+
groups = sorted(folders(files, prefixes).items(), key=lambda kv: (-(kv[1]['unquoted'] + kv[1]['unnamed']), -kv[1]['lines'], kv[0]))
|
|
177
|
+
shown = groups if args.all else groups[:40]
|
|
178
|
+
width = max(len(name) for name, _ in shown)
|
|
179
|
+
print(f"\n{'folder'.ljust(width)} files lines cited sentences not on a page numbers not on a page")
|
|
180
|
+
for name, g in shown:
|
|
181
|
+
print(f"{name.ljust(width)} {g['files']:5} {g['lines']:6} {g['cited']:5} {g['unquoted']:9} of {g['sentences']:<9} {g['unnamed']:7} of {g['limits']}")
|
|
182
|
+
if len(groups) > len(shown):
|
|
183
|
+
print(f'... and {len(groups) - len(shown)} more folders (--all prints them)')
|
|
184
|
+
if prefixes:
|
|
185
|
+
items = [(name, 'says', s) for name, f in files.items() for s in f['unquoted']]
|
|
186
|
+
items += [(name, 'sets', f'{n} = {v}') for name, f in files.items() for n, v in f['unnamed']]
|
|
187
|
+
print(f'\n{len(items)} things under {", ".join(prefixes)} that no page mentions:')
|
|
188
|
+
for name, verb, what in (items if args.all else items[:60]):
|
|
189
|
+
print(f' {name} {verb}: {what}')
|
|
190
|
+
if not args.all and len(items) > 60:
|
|
191
|
+
print(f' ... and {len(items) - 60} more (--all prints them)')
|
|
192
|
+
uncited = sorted((f['lines'], name) for name, f in files.items() if not f['cited'])
|
|
193
|
+
print(f'\n{len(uncited)} of {len(files)} files there are cited by no page; the largest:')
|
|
194
|
+
for lines, name in reversed(uncited[-(len(uncited) if args.all else 15):]):
|
|
195
|
+
print(f' {name} ({lines} lines)')
|
|
196
|
+
return 0
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
if __name__ == '__main__':
|
|
200
|
+
sys.exit(main())
|
|
@@ -37,7 +37,7 @@ RULE_ROW = re.compile(r'^ {0,3}\|[ \t]*(BR-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{2,4})[ \t
|
|
|
37
37
|
MD_REF = re.compile(r'^ {0,3}\[[^\]\n]+\]:\s*(<[^>]*>|\S+)', re.M)
|
|
38
38
|
GAP_PAGE_ONLY = ('priority', 'confidence')
|
|
39
39
|
ARRAYS = {'areas', 'sources', 'tags', 'aliases', 'task_ids'}
|
|
40
|
-
STRINGS = {'id', 'title', 'type', 'status', 'updated', 'summary', 'verification', 'priority', 'confidence', 'gap',
|
|
40
|
+
STRINGS = {'id', 'title', 'type', 'status', 'updated', 'summary', 'verification', 'priority', 'confidence', 'gap', 'parent',
|
|
41
41
|
*GAP_ONLY}
|
|
42
42
|
REQUIRED = {'id', 'title', 'type', 'areas', 'sources', 'updated'}
|
|
43
43
|
LINK = re.compile(r'(!?)\[\[([^\[\]\n]+)\]\]') # no brackets inside, so a run of '[[' cannot backtrack
|
|
@@ -215,6 +215,8 @@ def validate_meta(meta):
|
|
|
215
215
|
raise ValueError(f"status must be one of {', '.join(sorted(allowed))}{hint}")
|
|
216
216
|
if kind == 'note' and meta['status'] == 'current' and not meta['sources']:
|
|
217
217
|
raise ValueError('current note requires sources')
|
|
218
|
+
if 'parent' in meta and (kind != 'note' or not meta['parent'].strip()):
|
|
219
|
+
raise ValueError('parent is only valid on note pages and names the feature note this one is a part of')
|
|
218
220
|
if kind == 'plan':
|
|
219
221
|
if not meta.get('gap', '').strip():
|
|
220
222
|
raise ValueError('plan requires gap: the id of the accepted gap it implements')
|
|
@@ -313,20 +315,29 @@ def line_ending_variant(data, old):
|
|
|
313
315
|
return old in {hashlib.sha256(lf).hexdigest(), hashlib.sha256(lf.replace(b'\n', b'\r\n')).hexdigest()}
|
|
314
316
|
|
|
315
317
|
|
|
318
|
+
def run_git(repo, args, **options):
|
|
319
|
+
"""Git's answer for the repository. Where Git is not installed (a build container, say) it is the answer
|
|
320
|
+
of a folder that is not a work tree, so the caller goes on without history instead of stopping."""
|
|
321
|
+
try:
|
|
322
|
+
return subprocess.run(['git', '-C', str(repo), *args], capture_output=True, **options)
|
|
323
|
+
except FileNotFoundError:
|
|
324
|
+
return subprocess.CompletedProcess(args, 127, b'', b'')
|
|
325
|
+
|
|
326
|
+
|
|
316
327
|
def head_blob(repo, source):
|
|
317
328
|
"""Bytes of the source as committed at HEAD, or None when HEAD has no such file (untracked, new or no commits)."""
|
|
318
|
-
result =
|
|
329
|
+
result = run_git(repo, ['cat-file', 'blob', f'HEAD:./{posixpath.normpath(source)}'])
|
|
319
330
|
return None if result.returncode else result.stdout
|
|
320
331
|
|
|
321
332
|
|
|
322
333
|
def uncommitted_paths(repo):
|
|
323
334
|
"""Repo-relative paths Git reports as modified, staged or untracked (one status call), or None outside a work tree."""
|
|
324
|
-
probe =
|
|
335
|
+
probe = run_git(repo, ['rev-parse', '--is-inside-work-tree', '--show-prefix'])
|
|
325
336
|
lines = probe.stdout.decode(errors='replace').split('\n')
|
|
326
337
|
if probe.returncode or lines[0] != 'true':
|
|
327
338
|
return None
|
|
328
339
|
prefix = lines[1] if len(lines) > 1 else ''
|
|
329
|
-
status =
|
|
340
|
+
status = run_git(repo, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])
|
|
330
341
|
if status.returncode:
|
|
331
342
|
return None
|
|
332
343
|
raw, found, i = status.stdout.split(b'\0'), set(), 0
|
|
@@ -347,10 +358,13 @@ def error_page(message):
|
|
|
347
358
|
return head if head.endswith('.md') else None
|
|
348
359
|
|
|
349
360
|
|
|
350
|
-
def load_vault(repo, vault, freshness=True, dirty=None, report=None):
|
|
361
|
+
def load_vault(repo, vault, freshness=True, dirty=None, report=None, absent=None):
|
|
351
362
|
"""dirty: repo-relative paths with uncommitted changes. Their freshness warning is marked, not counted, only when
|
|
352
363
|
the accepted fingerprint equals the file's HEAD blob (up to LF/CRLF), so the sole drift is uncommitted.
|
|
353
364
|
|
|
365
|
+
absent, when given, collects cited files that are not there instead of reporting them: for a build that sees
|
|
366
|
+
only part of the repository, such as a Docker build context. Their pages are not marked as changed.
|
|
367
|
+
|
|
354
368
|
report, when given, receives 'failed': {page path: parsed id or None} for pages that failed validation.
|
|
355
369
|
"""
|
|
356
370
|
errors, warnings, notes, failed, failed_kind, cascade = [], [], [], {}, {}, []
|
|
@@ -415,10 +429,26 @@ def load_vault(repo, vault, freshness=True, dirty=None, report=None):
|
|
|
415
429
|
paths[stem] = note
|
|
416
430
|
basenames.setdefault(PurePosixPath(stem).name, []).append(note)
|
|
417
431
|
area_ids = {n['meta']['id'] for n in notes if n['meta']['type'] == 'area'}
|
|
418
|
-
edges, attachments, rule_pages = set(), {}, {}
|
|
432
|
+
edges, attachments, rule_pages, linked, parts = set(), {}, {}, set(), []
|
|
419
433
|
for note in notes:
|
|
420
434
|
meta, rel = note['meta'], note['path']
|
|
421
435
|
note['stale'] = False
|
|
436
|
+
if meta.get('parent'):
|
|
437
|
+
# Three levels and no more: an area, its features, and the parts of a feature that is too big for one page.
|
|
438
|
+
other, name = ids.get(meta['parent']), meta['parent']
|
|
439
|
+
if other is None and name in failed_ids and failed_id_kinds[name] & {None, 'note'}:
|
|
440
|
+
cascade.append(f'{rel}: parent {name} names a page that failed validation')
|
|
441
|
+
elif other is None or other['meta']['type'] != 'note':
|
|
442
|
+
errors.append(f'{rel}: parent {name} is not the id of an existing note')
|
|
443
|
+
elif other is note:
|
|
444
|
+
errors.append(f'{rel}: parent must name a different note')
|
|
445
|
+
elif other['meta'].get('parent'):
|
|
446
|
+
errors.append(f"{rel}: parent {name} is itself a part of {other['meta']['parent']}; a part belongs to a feature, not to another part")
|
|
447
|
+
elif other['meta']['areas'][:1] != meta['areas'][:1]:
|
|
448
|
+
errors.append(f"{rel}: parent {name} is in another area; a part has the same first area as its feature")
|
|
449
|
+
else:
|
|
450
|
+
edges.add((other['meta']['id'], meta['id']))
|
|
451
|
+
parts.append((other, note))
|
|
422
452
|
if meta['type'] == 'gap':
|
|
423
453
|
note['state'] = gap_state(meta)
|
|
424
454
|
if meta['type'] == 'gap' and meta.get('duplicate_of'):
|
|
@@ -495,6 +525,7 @@ def load_vault(repo, vault, freshness=True, dirty=None, report=None):
|
|
|
495
525
|
"if that part needs its own link, make it its own note and list it here")
|
|
496
526
|
else:
|
|
497
527
|
edges.add((meta['id'], choices[0]['meta']['id']))
|
|
528
|
+
linked.add((meta['id'], choices[0]['meta']['id']))
|
|
498
529
|
if meta['type'] == 'area':
|
|
499
530
|
# An area page is a map of its notes. A table on it is behavior written in the wrong place.
|
|
500
531
|
tables = sum(1 for line in text.split('\n') if TABLE_RULE.match(line))
|
|
@@ -541,6 +572,9 @@ def load_vault(repo, vault, freshness=True, dirty=None, report=None):
|
|
|
541
572
|
if credential_path(path.resolve().relative_to(repo).as_posix()):
|
|
542
573
|
raise ValueError('credential source is forbidden')
|
|
543
574
|
if not path.is_file():
|
|
575
|
+
if absent is not None and not path.exists():
|
|
576
|
+
absent.append(source)
|
|
577
|
+
continue
|
|
544
578
|
if closed:
|
|
545
579
|
warnings.append(f'{rel}: missing source {source}')
|
|
546
580
|
note['stale'] = True
|
|
@@ -564,6 +598,10 @@ def load_vault(repo, vault, freshness=True, dirty=None, report=None):
|
|
|
564
598
|
note['stale'] = True
|
|
565
599
|
except (OSError, ValueError) as exc:
|
|
566
600
|
errors.append(f'{rel}: {source}: {exc}')
|
|
601
|
+
for feature, part in parts:
|
|
602
|
+
# The viewer nests a part under its feature from `parent`; a plain Markdown reader has only the link.
|
|
603
|
+
if (feature['meta']['id'], part['meta']['id']) not in linked:
|
|
604
|
+
errors.append(f"{part['path']}: its feature {feature['path']} does not link to it; list every part on the feature's page")
|
|
567
605
|
if report is not None:
|
|
568
606
|
report['failed'] = failed
|
|
569
607
|
report['cascade'] = cascade
|
|
@@ -634,7 +672,7 @@ def node_of(note):
|
|
|
634
672
|
'kind': m.get('kind', ''), 'recheck': m.get('recheck', ''), 'recheckedBy': m.get('rechecked_by', ''),
|
|
635
673
|
'recheckedOn': m.get('rechecked_on', ''), 'decision': m.get('decision', ''), 'decidedBy': m.get('decided_by', ''),
|
|
636
674
|
'decidedOn': m.get('decided_on', ''), 'priority': m.get('priority', ''), 'confidence': m.get('confidence', ''),
|
|
637
|
-
'duplicateOf': m.get('duplicate_of', ''), 'recheckOutdated': gap and (m['recheck'] == 'outdated' or recheck_marker(note)), 'state': note.get('state', ''), 'gap': m.get('gap', ''),
|
|
675
|
+
'parent': m.get('parent', ''), 'duplicateOf': m.get('duplicate_of', ''), 'recheckOutdated': gap and (m['recheck'] == 'outdated' or recheck_marker(note)), 'state': note.get('state', ''), 'gap': m.get('gap', ''),
|
|
638
676
|
'layer': LAYERS[m['type']]}
|
|
639
677
|
|
|
640
678
|
|
|
@@ -691,7 +729,7 @@ def front_value(line):
|
|
|
691
729
|
|
|
692
730
|
def shallow_commits(repo):
|
|
693
731
|
"""Commits whose parents a shallow clone left out. Empty in a full clone and outside Git."""
|
|
694
|
-
found =
|
|
732
|
+
found = run_git(repo, ['rev-parse', '--git-path', 'shallow'])
|
|
695
733
|
if found.returncode:
|
|
696
734
|
return set()
|
|
697
735
|
try:
|
|
@@ -709,21 +747,21 @@ def vault_history(repo, vault):
|
|
|
709
747
|
spec, prefix = page_pathspec(repo, vault)
|
|
710
748
|
if spec is None:
|
|
711
749
|
return []
|
|
712
|
-
head =
|
|
750
|
+
head = run_git(repo, ['rev-parse', 'HEAD'])
|
|
713
751
|
if head.returncode:
|
|
714
752
|
return []
|
|
715
753
|
key = (str(repo), str(vault), head.stdout.strip())
|
|
716
754
|
if key in _history_cache:
|
|
717
755
|
return _history_cache[key]
|
|
718
756
|
# Git prints paths from the top of the work tree, which may be above the repository folder given here.
|
|
719
|
-
top =
|
|
757
|
+
top = run_git(repo, ['rev-parse', '--show-prefix']).stdout.decode(errors='replace').strip()
|
|
720
758
|
prefix = top + prefix
|
|
721
759
|
# A marker nobody could have written into a commit message or a page beforehand separates the commits.
|
|
722
760
|
marker = '\x01' + os.urandom(12).hex() + '\x01'
|
|
723
761
|
try:
|
|
724
|
-
log =
|
|
762
|
+
log = run_git(repo, ['-c', 'core.quotepath=off', 'log', f'-n{HISTORY_COMMITS}', '--date=short', '--no-color',
|
|
725
763
|
'--no-renames', '-p', '-U0', f'--format={marker}%H%x02%ad%x02%s', '--', *spec],
|
|
726
|
-
|
|
764
|
+
timeout=20)
|
|
727
765
|
except subprocess.TimeoutExpired:
|
|
728
766
|
return []
|
|
729
767
|
if log.returncode:
|
|
@@ -768,11 +806,10 @@ def vault_pending(repo, vault):
|
|
|
768
806
|
spec, prefix = page_pathspec(repo, vault)
|
|
769
807
|
if spec is None:
|
|
770
808
|
return []
|
|
771
|
-
status =
|
|
772
|
-
capture_output=True)
|
|
809
|
+
status = run_git(repo, ['-c', 'core.quotepath=off', 'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', *spec])
|
|
773
810
|
if status.returncode:
|
|
774
811
|
return []
|
|
775
|
-
top =
|
|
812
|
+
top = run_git(repo, ['rev-parse', '--show-prefix']).stdout.decode(errors='replace').strip()
|
|
776
813
|
pending = []
|
|
777
814
|
for item in status.stdout.split(b'\0'):
|
|
778
815
|
text = os.fsdecode(item)
|
|
@@ -823,7 +860,7 @@ def built_page(repo, vault, notes, edges, warnings, with_sources=False, source_u
|
|
|
823
860
|
The text of cited repository files is left out unless asked for, because the file may be shown to people
|
|
824
861
|
who cannot read the repository. Returns (html, payload).
|
|
825
862
|
"""
|
|
826
|
-
head =
|
|
863
|
+
head = run_git(repo, ['rev-parse', 'HEAD'])
|
|
827
864
|
commit = '' if head.returncode else head.stdout.decode('ascii', errors='replace').strip()
|
|
828
865
|
payload = page_payload(repo, vault, notes, edges, warnings, with_sources) | {
|
|
829
866
|
'built': True, 'commit': commit, 'sourceUrl': source_base(source_url, commit) if source_url else ''}
|
|
@@ -868,6 +905,8 @@ def main(argv=None):
|
|
|
868
905
|
parser.add_argument('--out', type=Path, help='build: the HTML file to write, outside the vault')
|
|
869
906
|
parser.add_argument('--with-sources', action='store_true', help='build: include the text of the repository files the pages cite')
|
|
870
907
|
parser.add_argument('--source-url', default='', help='build: where a cited file can be read, e.g. https://github.com/OWNER/REPO/blob/{commit}')
|
|
908
|
+
parser.add_argument('--allow-missing-sources', action='store_true',
|
|
909
|
+
help='build: do not stop when a cited file is not there, for a build that sees only part of the repository')
|
|
871
910
|
parser.add_argument('--ignore-dirty', action='store_true',
|
|
872
911
|
help='check: do not count freshness warnings for sources with uncommitted changes (needs a Git work tree)')
|
|
873
912
|
group = parser.add_mutually_exclusive_group()
|
|
@@ -882,8 +921,8 @@ def main(argv=None):
|
|
|
882
921
|
parser.error('--open is only for serve')
|
|
883
922
|
if args.command == 'build' and not args.out:
|
|
884
923
|
parser.error('build requires --out FILE')
|
|
885
|
-
if args.command != 'build' and (args.out or args.with_sources or args.source_url):
|
|
886
|
-
parser.error('--out, --with-sources
|
|
924
|
+
if args.command != 'build' and (args.out or args.with_sources or args.source_url or args.allow_missing_sources):
|
|
925
|
+
parser.error('--out, --with-sources, --source-url and --allow-missing-sources are only for build')
|
|
887
926
|
if args.command == 'snapshot' and not (args.all or args.notes):
|
|
888
927
|
parser.error('snapshot requires --all or --notes')
|
|
889
928
|
if args.command != 'snapshot' and (args.all or args.notes):
|
|
@@ -917,7 +956,8 @@ def main(argv=None):
|
|
|
917
956
|
if dirty is None:
|
|
918
957
|
parser.error('--ignore-dirty needs --repo to be a Git work tree')
|
|
919
958
|
report = {}
|
|
920
|
-
|
|
959
|
+
absent = [] if args.allow_missing_sources else None
|
|
960
|
+
notes, edges, errors, warnings, baseline = load_vault(repo, vault, args.command != 'snapshot', dirty, report, absent)
|
|
921
961
|
ignored = []
|
|
922
962
|
if args.command == 'snapshot' and args.notes:
|
|
923
963
|
# Only the selected pages must be valid; errors elsewhere are counted, not blocking.
|
|
@@ -964,6 +1004,9 @@ def main(argv=None):
|
|
|
964
1004
|
+ (f', commit {payload["commit"][:7]}' if payload['commit'] else ''))
|
|
965
1005
|
print('build: ' + (f'the text of {files} cited source files is inside the file; show it only to people who may read the repository'
|
|
966
1006
|
if args.with_sources else 'cited source files are named but their text is not included (--with-sources adds it)'))
|
|
1007
|
+
if absent:
|
|
1008
|
+
names = sorted(set(absent))
|
|
1009
|
+
print(f'build: {len(names)} cited files are not in this folder, so nobody compared them with the pages: ' + ', '.join(names[:8]) + (' ...' if len(names) > 8 else ''))
|
|
967
1010
|
if shallow_commits(repo):
|
|
968
1011
|
print('build: this is a shallow clone, so the Changes page starts at the first commit that was fetched in full; fetch the whole history to show more')
|
|
969
1012
|
return 0
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import subprocess
|
|
3
|
+
import sys
|
|
4
|
+
import tempfile
|
|
5
|
+
import unittest
|
|
6
|
+
from contextlib import redirect_stderr, redirect_stdout
|
|
7
|
+
from io import StringIO
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
11
|
+
import coverage as c # noqa: E402
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class CoverageTests(unittest.TestCase):
|
|
15
|
+
def setUp(self):
|
|
16
|
+
self.temp = tempfile.TemporaryDirectory()
|
|
17
|
+
self.repo = Path(self.temp.name).resolve() / 'repo'
|
|
18
|
+
self.vault = self.repo / 'knowledge/demo'
|
|
19
|
+
(self.vault / 'notes').mkdir(parents=True)
|
|
20
|
+
(self.vault / 'areas').mkdir()
|
|
21
|
+
self.page('00-index.md', 'index', 'index', areas=[], body='[[areas/chat]]')
|
|
22
|
+
self.page('areas/chat.md', 'chat', 'area', areas=[], body='[[notes/chats]]')
|
|
23
|
+
self.page('notes/chats.md', 'chats', sources=['src/chat/send.ts'],
|
|
24
|
+
body='A message is refused with "Message can’t be empty". At most 10 photos (`CHAT_MAX_MEDIA`).\n\n'
|
|
25
|
+
'| ID | Rule |\n| --- | --- |\n| BR-CHAT-01 | Only group chats can be renamed, by a member \\| staff. |')
|
|
26
|
+
self.code('src/chat/send.ts', '''
|
|
27
|
+
export const CHAT_MAX_MEDIA = 10;
|
|
28
|
+
export const COLD_OUTREACH_PER_HOUR: number = 5; // new people
|
|
29
|
+
const RETRY_MS = 60 * 1000
|
|
30
|
+
const queryKey = "chats.list";
|
|
31
|
+
throw new Error("Message can't be empty");
|
|
32
|
+
throw new Error('Only group chats can be renamed');
|
|
33
|
+
throw new Error("You cannot remove yourself");
|
|
34
|
+
console.error("Failed to load the chat list");
|
|
35
|
+
const cls = "flex items-center gap-2 Text here";
|
|
36
|
+
const sql = "SELECT id FROM chats WHERE owner = 1";
|
|
37
|
+
''')
|
|
38
|
+
self.code('src/chat/window/Header.tsx', '<Button>Back to chat list</Button>\n<p>{count} unread</p>\nconst t = `Hello ${name}, welcome back`;')
|
|
39
|
+
self.code('src/chat/window/deep/Picker.tsx', 'const label = "Smileys and people";')
|
|
40
|
+
self.code('src/chat/send.test.ts', 'it("says this in a test only", () => {})')
|
|
41
|
+
self.code('src/chat/__tests__/more.ts', 'const s = "Only in a test folder";')
|
|
42
|
+
self.code('src/orders/pay.py', 'MAX_TOTAL = 5000\nmessage = "The order was already paid"\n')
|
|
43
|
+
self.code('database/migrations/001.sql', "INSERT INTO t VALUES ('A sentence in a migration');")
|
|
44
|
+
self.code('node_modules/x/index.js', 'const s = "A sentence in a dependency";')
|
|
45
|
+
self.code('src/help/article.ts', '\n'.join(f'const p{i} = "This is paragraph number {i} of an article";' for i in range(45)))
|
|
46
|
+
(self.repo / 'README.md').write_text('Not code. "A sentence in the readme file"', encoding='utf-8')
|
|
47
|
+
|
|
48
|
+
def tearDown(self):
|
|
49
|
+
self.temp.cleanup()
|
|
50
|
+
|
|
51
|
+
def page(self, path, ident, ptype='note', areas=None, sources=None, body=''):
|
|
52
|
+
meta = {'id': ident, 'title': 'Page ' + ident, 'type': ptype, 'status': 'current', 'areas': ['chat'] if areas is None else areas,
|
|
53
|
+
'sources': sources or [], 'updated': '2026-11-18'}
|
|
54
|
+
(self.vault / path).write_text('---\n' + ''.join(f'{key}: {json.dumps(value)}\n' for key, value in meta.items()) + '---\n' + body, encoding='utf-8')
|
|
55
|
+
|
|
56
|
+
def code(self, path, text):
|
|
57
|
+
file = self.repo / path
|
|
58
|
+
file.parent.mkdir(parents=True, exist_ok=True)
|
|
59
|
+
file.write_text(text, encoding='utf-8')
|
|
60
|
+
|
|
61
|
+
def run_cli(self, *args):
|
|
62
|
+
out, err = StringIO(), StringIO()
|
|
63
|
+
with redirect_stdout(out), redirect_stderr(err):
|
|
64
|
+
status = c.main(['--repo', str(self.repo), *args])
|
|
65
|
+
return status, out.getvalue(), err.getvalue()
|
|
66
|
+
|
|
67
|
+
def measured(self, *prefixes):
|
|
68
|
+
import knowledge
|
|
69
|
+
notes = knowledge.load_vault(self.repo, self.vault, freshness=False, absent=[])[0]
|
|
70
|
+
return c.measure(self.repo, self.vault, notes, prefixes)
|
|
71
|
+
|
|
72
|
+
def test_reads_only_the_application_code(self):
|
|
73
|
+
self.assertEqual(sorted(self.measured()), ['src/chat/send.ts', 'src/chat/window/Header.tsx', 'src/chat/window/deep/Picker.tsx',
|
|
74
|
+
'src/help/article.ts', 'src/orders/pay.py'])
|
|
75
|
+
# with Git, an ignored folder is left out as well, and an untracked file is still read
|
|
76
|
+
subprocess.run(['git', '-C', str(self.repo), 'init', '-q'], check=True)
|
|
77
|
+
(self.repo / '.gitignore').write_text('src/orders/\n', encoding='utf-8')
|
|
78
|
+
self.assertNotIn('src/orders/pay.py', self.measured())
|
|
79
|
+
self.assertIn('src/chat/send.ts', self.measured())
|
|
80
|
+
|
|
81
|
+
def test_finds_the_sentences_and_numbers_no_page_mentions(self):
|
|
82
|
+
files = self.measured()
|
|
83
|
+
send = files['src/chat/send.ts']
|
|
84
|
+
self.assertEqual((send['cited'], send['sentences'], send['limits']), (True, 3, 3))
|
|
85
|
+
self.assertEqual(send['unquoted'], ['You cannot remove yourself'], 'a curly apostrophe and a table row still match; logs, class lists and queries are not sentences')
|
|
86
|
+
self.assertEqual(send['unnamed'], [('COLD_OUTREACH_PER_HOUR', '5'), ('RETRY_MS', '60 * 1000')])
|
|
87
|
+
self.assertEqual(files['src/chat/window/Header.tsx']['unquoted'], ['Back to chat list'], 'text between tags counts; text with a placeholder does not')
|
|
88
|
+
self.assertEqual(files['src/orders/pay.py']['unnamed'], [('MAX_TOTAL', '5000')])
|
|
89
|
+
article = files['src/help/article.ts']
|
|
90
|
+
self.assertEqual((article['content'], article['sentences'], article['unquoted']), (True, 0, []), 'an article counts as a file only')
|
|
91
|
+
|
|
92
|
+
def test_groups_by_folder_and_keeps_an_uncited_folder_as_one_line(self):
|
|
93
|
+
groups = c.folders(self.measured())
|
|
94
|
+
self.assertEqual(sorted(groups), ['src/chat', 'src/chat/window', 'src/help', 'src/orders'])
|
|
95
|
+
self.assertEqual(groups['src/chat/window'], {'files': 2, 'lines': 4, 'cited': 0, 'sentences': 2, 'unquoted': 2, 'limits': 0, 'unnamed': 0})
|
|
96
|
+
self.assertEqual((groups['src/chat']['files'], groups['src/chat']['cited']), (1, 1))
|
|
97
|
+
# nothing cited anywhere: one line per top folder, and never above the folder that was asked for
|
|
98
|
+
self.page('notes/chats.md', 'chats', sources=['README.md'])
|
|
99
|
+
self.assertEqual(sorted(c.folders(self.measured())), ['src'])
|
|
100
|
+
self.assertEqual(sorted(c.folders(self.measured('src/chat'), ['src/chat'])), ['src/chat'])
|
|
101
|
+
|
|
102
|
+
def test_report_lists_what_to_read(self):
|
|
103
|
+
status, out, err = self.run_cli()
|
|
104
|
+
self.assertEqual((status, err), (0, ''))
|
|
105
|
+
self.assertIn('coverage: 5 code files, ', out)
|
|
106
|
+
self.assertIn('pages cite 1 of them', out)
|
|
107
|
+
self.assertIn('6 sentences a person can see, 4 on no page; 4 named numbers, 3 on no page', out)
|
|
108
|
+
self.assertIn('1 files that are mostly text (articles, templates) count as files only', out)
|
|
109
|
+
self.assertLess(out.index('src/chat/window'), out.index('src/help'), 'the folder with the most to read comes first')
|
|
110
|
+
self.assertNotIn('things under', out)
|
|
111
|
+
status, out, _ = self.run_cli('--path', 'src/chat/')
|
|
112
|
+
self.assertIn('coverage: 3 code files', out)
|
|
113
|
+
self.assertIn('5 things under src/chat that no page mentions:', out)
|
|
114
|
+
self.assertIn(' src/chat/send.ts says: You cannot remove yourself', out)
|
|
115
|
+
self.assertIn(' src/chat/send.ts sets: RETRY_MS = 60 * 1000', out)
|
|
116
|
+
self.assertIn('2 of 3 files there are cited by no page', out)
|
|
117
|
+
self.assertEqual(self.run_cli('--path', 'nowhere')[1].strip(), 'coverage: no code files found under nowhere')
|
|
118
|
+
|
|
119
|
+
def test_a_vault_with_errors_is_reported_and_still_measured(self):
|
|
120
|
+
self.page('notes/bad.md', 'bad', sources=['src/chat/send.ts'], body='[[missing-page]]')
|
|
121
|
+
status, out, err = self.run_cli()
|
|
122
|
+
self.assertEqual(status, 0)
|
|
123
|
+
self.assertIn('the vault has 1 errors', err)
|
|
124
|
+
self.assertIn('coverage: 5 code files', out)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
if __name__ == '__main__':
|
|
128
|
+
unittest.main()
|