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.
@@ -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 = subprocess.run(['git', '-C', str(repo), 'cat-file', 'blob', f'HEAD:./{posixpath.normpath(source)}'], capture_output=True)
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--is-inside-work-tree', '--show-prefix'], capture_output=True)
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 = subprocess.run(['git', '-C', str(repo), 'status', '--porcelain=v1', '-z', '--untracked-files=all'], capture_output=True)
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--git-path', 'shallow'], capture_output=True)
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', 'HEAD'], capture_output=True)
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--show-prefix'], capture_output=True).stdout.decode(errors='replace').strip()
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 = subprocess.run(['git', '-C', str(repo), '-c', 'core.quotepath=off', 'log', f'-n{HISTORY_COMMITS}', '--date=short', '--no-color',
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
- capture_output=True, timeout=20)
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 = subprocess.run(['git', '-C', str(repo), '-c', 'core.quotepath=off', 'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', *spec],
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--show-prefix'], capture_output=True).stdout.decode(errors='replace').strip()
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 = subprocess.run(['git', '-C', str(repo), 'rev-parse', 'HEAD'], capture_output=True)
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 and --source-url are only for build')
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
- notes, edges, errors, warnings, baseline = load_vault(repo, vault, args.command != 'snapshot', dirty, report)
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()