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.
- package/README.md +52 -14
- package/bin/project-spec.mjs +129 -15
- package/package.json +2 -1
- package/skills/project-knowledge/SKILL.md +23 -7
- package/skills/project-knowledge/references/agents.md +30 -0
- package/skills/project-knowledge/references/format.md +5 -3
- package/skills/project-knowledge/references/gaps.md +7 -2
- package/skills/project-knowledge/references/sync.md +1 -1
- package/skills/project-knowledge/scripts/coverage.py +7 -3
- package/skills/project-knowledge/scripts/knowledge.py +74 -5
- package/{skills/project-knowledge/assets → viewer}/viewer.html +251 -52
- package/skills/project-knowledge/scripts/test_coverage.py +0 -128
- package/skills/project-knowledge/scripts/test_knowledge.py +0 -1276
- package/skills/project-knowledge/scripts/test_maintain.py +0 -864
- package/skills/project-knowledge/scripts/test_merge.py +0 -165
- package/skills/spec-change/LICENSE +0 -21
- package/skills/spec-change/SKILL.md +0 -63
- package/skills/spec-change/agents/openai.yaml +0 -4
- package/skills/spec-change/references/gaps.md +0 -159
- /package/skills/{spec-change → project-knowledge}/references/plan.md +0 -0
|
@@ -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.**
|
|
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
|
-
|
|
687
|
-
|
|
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('
|
|
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
|
-
|
|
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)
|