project-spec 0.9.2 → 0.11.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.
@@ -34,7 +34,7 @@ Existing clones reuse the shared checkpoint.
34
34
 
35
35
  Follow the repository's task coordination for substantive writes, and respect other people's claims on specific notes and source areas.
36
36
 
37
- **Spec notes.** Read each relevant diff in its execution context. Inspect the mapped notes, connected rules and uncovered files; a new route or service may need a new area or note. Classify every pending path as reviewed, excluded with a concrete reason, or deferred. A generated asset may be excluded; an unknown behavior may not be excluded just to empty the queue. Credential files are not evidence and their contents never enter the vault. Update claims from the code, keep manual text and stable IDs, and resolve deleted or renamed sources by investigation. A changed registration point (a new job, route, email, role or flag) updates the reference note that lists that kind of thing; a changed form or screen updates its feature note. A note you re-read gets what it is missing, what the feature is for and its rules with their values, and loses what a reader does not need; see "Leave each page better" in the skill. For a renamed or split file, point `sources` at where the rule lives now and re-read the page. If evidence is truly gone, keep the note as `stale` or `superseded` with a line saying what could not be found; open a gap only if a question about the product remains. a missing note is not evidence of missing functionality.
37
+ **Spec notes.** A note the scan lists as affected whose sources carry no freshness warning was already reviewed after the change, usually by the task that made it ([Record a change](../SKILL.md#record-a-change)): give it `unchanged` with the reason "recorded with the change" and read it again only when the diff shows something its page lacks. For the rest, read each relevant diff in its execution context. Inspect the mapped notes, connected rules and uncovered files; a new route or service may need a new area or note. Classify every pending path as reviewed, excluded with a concrete reason, or deferred. A generated asset may be excluded; an unknown behavior may not be excluded just to empty the queue. Credential files are not evidence and their contents never enter the vault. Update claims from the code, keep manual text and stable IDs, and resolve deleted or renamed sources by investigation. A changed registration point (a new job, route, email, role or flag) updates the reference note that lists that kind of thing; a changed form or screen updates its feature note. A note you re-read gets what it is missing, what the feature is for and its rules with their values, and loses what a reader does not need; see "Leave each page better" in the skill. For a renamed or split file, point `sources` at where the rule lives now and re-read the page. If evidence is truly gone, keep the note as `stale` or `superseded` with a line saying what could not be found; open a gap only if a question about the product remains. a missing note is not evidence of missing functionality.
38
38
 
39
39
  **Gaps.** List the gaps whose `sources` include a changed path, and any gap whose described behavior the diff touches. For each, re-read the current code:
40
40
 
@@ -34,6 +34,8 @@ LOG_LINE = re.compile(r'\b(console|logger|log|logging|Sentry|debug)\s*\.\s*\w+\s
34
34
  NOT_PROSE = re.compile(r'[{}<>;=\\]|\$\(|^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b|https?://|\w+\.\w+\(|\w/\w+/\w')
35
35
  # A named number: MAX_ATTACHMENTS = 10, TTL_MS: number = 60 * 60 * 1000
36
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
+ # A docstring describes the code to its reader; nobody using the product sees it.
38
+ DOCSTRING = re.compile(r'''^[ \t]*[rRuU]?("""|\'\'\')[\s\S]*?\1''', re.M)
37
39
  PUNCTUATION = str.maketrans({'‘': "'", '’': "'", '“': '"', '”': '"', '–': '-', '—': '-', ' ': ' '})
38
40
 
39
41
 
@@ -53,7 +55,7 @@ def is_sentence(text):
53
55
 
54
56
  def sentences_in(text):
55
57
  found = []
56
- for line in text.split('\n'):
58
+ for line in DOCSTRING.sub('', text).split('\n'):
57
59
  if LOG_LINE.search(line):
58
60
  continue
59
61
  for _, inner in QUOTED.findall(line):
@@ -184,13 +186,15 @@ def main(argv=None):
184
186
  if prefixes:
185
187
  items = [(name, 'says', s) for name, f in files.items() for s in f['unquoted']]
186
188
  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:')
189
+ print(f'\n{len(items)} things under {", ".join(prefixes)} that no page mentions:' if items
190
+ else f'\nNothing under {", ".join(prefixes)} is missing from the pages.')
188
191
  for name, verb, what in (items if args.all else items[:60]):
189
192
  print(f' {name} {verb}: {what}')
190
193
  if not args.all and len(items) > 60:
191
194
  print(f' ... and {len(items) - 60} more (--all prints them)')
192
195
  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:')
196
+ print(f'\n{len(uncited)} of {len(files)} files there are cited by no page; the largest:' if uncited
197
+ else f'\nEvery one of the {len(files)} files there is cited by a page.')
194
198
  for lines, name in reversed(uncited[-(len(uncited) if args.all else 15):]):
195
199
  print(f' {name} ({lines} lines)')
196
200
  return 0
@@ -23,7 +23,7 @@ RECHECKS = ('not-checked', 'confirmed', 'not-reproduced', 'outdated')
23
23
  DECISIONS = ('open', 'accepted', 'rejected', 'deferred', 'done', 'duplicate')
24
24
  DECIDED = ('accepted', 'rejected', 'deferred')
25
25
  STATE_ORDER = ('needs-recheck', 'needs-decision', 'accepted', 'deferred', 'rejected', 'done', 'duplicate')
26
- GAP_ONLY = ('kind', 'recheck', 'rechecked_by', 'rechecked_on', 'decision', 'decided_by', 'decided_on', 'duplicate_of')
26
+ GAP_ONLY = ('kind', 'recheck', 'rechecked_by', 'rechecked_on', 'decision', 'decided_by', 'decided_on', 'duplicate_of', 'created')
27
27
  GAP_SECTIONS = ('Current behavior', 'Gap', 'Evidence', 'Recheck', 'Discussion', 'Decision')
28
28
  LAYERS = {'area': 'spec', 'note': 'spec', 'gap': 'gap', 'plan': 'gap', 'index': 'nav', 'run': 'nav'}
29
29
  UNCOUNTED = ' (uncommitted change, not counted)' # suffix of a freshness warning that --ignore-dirty does not count
@@ -253,6 +253,8 @@ def validate_gap(meta):
253
253
  raise ValueError("decided_by must be a person's name: an agent may not decide, only record what a person decided")
254
254
  if 'decided_on' in meta:
255
255
  check_date('decided_on', meta['decided_on'])
256
+ if 'created' in meta:
257
+ check_date('created', meta['created'])
256
258
  if meta['decision'] == 'duplicate':
257
259
  if not meta.get('duplicate_of', '').strip():
258
260
  raise ValueError("duplicate_of is required when decision is 'duplicate': give the id of the other gap")
@@ -683,10 +685,28 @@ def graph_of(notes, edges, warnings):
683
685
  'edges': [{'source': a, 'target': b} for a, b in edges], 'warnings': warnings}
684
686
 
685
687
 
686
- def viewer_html(payload):
687
- template = (Path(__file__).resolve().parent.parent / 'assets/viewer.html').read_text(encoding='utf-8')
688
+ VIEWER = None # --viewer FILE: a page of your own to show the vault with
689
+
690
+
691
+ def viewer_template():
692
+ """The text of the viewer page. The page is not part of the skill, which holds only what writing a spec needs:
693
+ it comes with the project-spec package, with a copy made by `install --with-viewer`, or from --viewer."""
694
+ here = Path(__file__).resolve().parent
695
+ places = [Path(VIEWER)] if VIEWER else [here.parent / 'assets/viewer.html', *([here.parents[2] / 'viewer/viewer.html'] if len(here.parents) > 2 else [])]
696
+ found = next((place for place in places if place.is_file()), None)
697
+ if not found:
698
+ raise ValueError(f'--viewer {VIEWER} is not a file' if VIEWER else
699
+ 'the viewer is not part of this copy of the skill. Run `npx project-spec serve` in the repository (the viewer comes '
700
+ 'with the npm package), add it to this copy with `npx project-spec install --dir <folder of the skill copies> --with-viewer`, '
701
+ 'or open the vault folder in Obsidian')
702
+ template = found.read_text(encoding='utf-8')
688
703
  if template.count('__KNOWLEDGE_DATA__') != 1:
689
- raise ValueError('viewer template must contain exactly one placeholder')
704
+ raise ValueError(f'{found} must contain the placeholder __KNOWLEDGE_DATA__ exactly once')
705
+ return template
706
+
707
+
708
+ def viewer_html(payload):
709
+ template = viewer_template()
690
710
  serialized = json.dumps(payload, ensure_ascii=False).replace('&', '\\u0026').replace('<', '\\u003c').replace('>', '\\u003e').replace('\u2028', '\\u2028').replace('\u2029', '\\u2029')
691
711
  return template.replace('__KNOWLEDGE_DATA__', serialized)
692
712
 
@@ -801,6 +821,40 @@ def vault_history(repo, vault):
801
821
  return commits
802
822
 
803
823
 
824
+ _added_cache = {}
825
+
826
+
827
+ def added_dates(repo, vault):
828
+ """The day each vault page was first committed, by its path in the vault. Empty outside a Git work tree.
829
+
830
+ A gap's own `created` property wins over this; the history only answers for pages written before that property
831
+ existed. A renamed page counts from the rename. Cached per HEAD, because every page load asks for it.
832
+ """
833
+ spec, prefix = page_pathspec(repo, vault)
834
+ head = run_git(repo, ['rev-parse', 'HEAD']) if spec else None
835
+ if spec is None or head.returncode:
836
+ return {}
837
+ key = (str(repo), str(vault), head.stdout.strip())
838
+ if key not in _added_cache:
839
+ top = run_git(repo, ['rev-parse', '--show-prefix']).stdout.decode(errors='replace').strip()
840
+ try:
841
+ log = run_git(repo, ['-c', 'core.quotepath=off', 'log', '--date=short', '--no-color', '--no-renames', '--diff-filter=A',
842
+ '--name-only', '--format=%x01%H%x02%ad', '--', *spec], timeout=20)
843
+ except subprocess.TimeoutExpired:
844
+ return {}
845
+ found, boundary = {}, shallow_commits(repo)
846
+ for chunk in (log.stdout.decode('utf-8', errors='replace').split('\x01')[1:] if not log.returncode else []):
847
+ header, _, names = chunk.partition('\n')
848
+ sha, _, date = header.partition('\x02')
849
+ if sha in boundary: # its parents were not fetched, so every page looks added there
850
+ continue
851
+ for name in names.split('\n'):
852
+ if name.startswith(top + prefix):
853
+ found[name[len(top + prefix):]] = date.strip() # newest first, so the oldest commit has the last word
854
+ _added_cache[key] = found
855
+ return _added_cache[key]
856
+
857
+
804
858
  def vault_pending(repo, vault):
805
859
  """Vault pages with uncommitted changes: [{path, status}], empty outside Git."""
806
860
  spec, prefix = page_pathspec(repo, vault)
@@ -824,7 +878,11 @@ def vault_pending(repo, vault):
824
878
 
825
879
  def page_payload(repo, vault, notes, edges, warnings, sources=True):
826
880
  files = cited_files(repo, vault, notes)[0] if sources else {}
827
- return graph_of(notes, edges, warnings) | {
881
+ graph, first = graph_of(notes, edges, warnings), added_dates(repo, vault)
882
+ for node, note in zip(graph['nodes'], notes):
883
+ # When a gap appeared: the day its page says, else the day the page was first committed, else unknown (a new page).
884
+ node['added'] = note['meta'].get('created', '') or first.get(note['path'], '') if note['meta']['type'] == 'gap' else ''
885
+ return graph | {
828
886
  'vaultPath': Path(os.path.relpath(vault, repo)).as_posix(), 'files': files,
829
887
  'history': vault_history(repo, vault), 'pending': vault_pending(repo, vault)}
830
888
 
@@ -903,6 +961,8 @@ def main(argv=None):
903
961
  parser.add_argument('--port', type=int, default=8757, help='serve: port on 127.0.0.1 (another free port is used if it is taken)')
904
962
  parser.add_argument('--open', action='store_true', help='serve: open the page in the default browser')
905
963
  parser.add_argument('--out', type=Path, help='build: the HTML file to write, outside the vault')
964
+ parser.add_argument('--viewer', type=Path, metavar='FILE',
965
+ help='serve, build: a page of your own instead of the viewer; it gets the data where it says __KNOWLEDGE_DATA__')
906
966
  parser.add_argument('--with-sources', action='store_true', help='build: include the text of the repository files the pages cite')
907
967
  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
968
  parser.add_argument('--allow-missing-sources', action='store_true',
@@ -933,6 +993,15 @@ def main(argv=None):
933
993
  vault = args.vault.resolve() if args.vault else find_vault(repo)
934
994
  if not vault.is_dir():
935
995
  parser.error('repo and vault must be existing directories')
996
+ if args.viewer and args.command not in ('serve', 'build'):
997
+ parser.error('--viewer is only for serve and build')
998
+ if args.command in ('serve', 'build'):
999
+ global VIEWER
1000
+ VIEWER = args.viewer.resolve() if args.viewer else None
1001
+ try:
1002
+ viewer_template()
1003
+ except (OSError, ValueError) as exc:
1004
+ parser.error(str(exc))
936
1005
  if args.command == 'serve':
937
1006
  try:
938
1007
  server = make_server(repo, vault, args.port)