project-spec 0.7.0 → 0.9.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 +74 -1
- package/bin/project-spec.mjs +8 -2
- package/package.json +1 -1
- package/skills/project-knowledge/SKILL.md +28 -9
- package/skills/project-knowledge/assets/viewer.html +139 -26
- package/skills/project-knowledge/references/format.md +12 -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 +127 -21
- package/skills/project-knowledge/scripts/test_coverage.py +128 -0
- package/skills/project-knowledge/scripts/test_knowledge.py +155 -0
- package/skills/spec-change/references/gaps.md +1 -1
package/README.md
CHANGED
|
@@ -51,7 +51,7 @@ It is made for one loop:
|
|
|
51
51
|
| --- | --- |
|
|
52
52
|
|  |  |
|
|
53
53
|
| **Recent changes** | **Gap queue** |
|
|
54
|
-
|  |  |
|
|
54
|
+
|  |  |
|
|
55
55
|
|
|
56
56
|

|
|
57
57
|
|
|
@@ -88,6 +88,58 @@ alias spec='python3 ~/.claude/skills/project-knowledge/scripts/knowledge.py serv
|
|
|
88
88
|
|
|
89
89
|
The vault is found by itself when the repository has one under `knowledge/`; otherwise add `--vault PATH`. The page is served on port 8757, or another free port when that one is taken; `--port N` picks one. `project-spec serve` opens the browser unless you add `--no-open`; the helper opens it only with `--open`. If the vault has errors, the page lists them.
|
|
90
90
|
|
|
91
|
+
### Show it on a server
|
|
92
|
+
|
|
93
|
+
`serve` is for your own machine. To let the rest of the team read the spec on a development or staging server, write the viewer as one file and let your application return it:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
project-spec build --out build/spec.html \
|
|
97
|
+
--source-url 'https://github.com/OWNER/REPO/blob/{commit}'
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Without the package the command is `python3 <skill>/scripts/knowledge.py build --repo . --out build/spec.html`. The file is the whole viewer: the pages, the search, the map, the gap queue and the history, with no other files and no network requests. It is a copy of the vault at the moment of the build, so build it again on every deploy.
|
|
101
|
+
|
|
102
|
+
| Option | What it does |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `--out FILE` | Where to write the page. It must be outside the vault: nothing is generated into the vault. |
|
|
105
|
+
| `--source-url URL` | Where a cited file can be read. The file's path in the repository is added to this address, and `{commit}` becomes the commit the page was built from. Without it, cited files are shown as names. |
|
|
106
|
+
| `--with-sources` | Put the text of the cited files into the page, as `serve` does, so they open inside the viewer. Leave it out when people who may not read the repository can open the page. |
|
|
107
|
+
| `--allow-missing-sources` | Do not stop when a cited file is not there. For a build that sees only part of the repository, such as a Docker build whose `.dockerignore` leaves files out. The command lists the files it did not find. |
|
|
108
|
+
|
|
109
|
+
The spec describes how the product works inside, and with `--with-sources` it carries source code. So treat the file like the repository:
|
|
110
|
+
|
|
111
|
+
- Keep it out of folders the web server publishes by itself (`public/`, `static/`). Return it from a route that checks who is asking.
|
|
112
|
+
- Build it only for the environments that should have it, and make the route answer 404 everywhere else.
|
|
113
|
+
- If your application sets a `Content-Security-Policy`, the page needs inline scripts and styles and nothing else.
|
|
114
|
+
|
|
115
|
+
For example, a route in a Next.js application (a sketch: put your own sign-in check where `signedIn()` is):
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
// src/app/development/spec/route.ts
|
|
119
|
+
import { readFile } from "node:fs/promises";
|
|
120
|
+
import path from "node:path";
|
|
121
|
+
|
|
122
|
+
export const dynamic = "force-dynamic";
|
|
123
|
+
|
|
124
|
+
export async function GET() {
|
|
125
|
+
if (process.env.SPEC_PAGE !== "on" || !(await signedIn())) {
|
|
126
|
+
return new Response("Not found", { status: 404 });
|
|
127
|
+
}
|
|
128
|
+
const page = await readFile(path.join(process.cwd(), "build/spec.html"));
|
|
129
|
+
return new Response(page, {
|
|
130
|
+
headers: {
|
|
131
|
+
"Content-Type": "text/html; charset=utf-8",
|
|
132
|
+
"Cache-Control": "no-store",
|
|
133
|
+
"X-Robots-Tag": "noindex",
|
|
134
|
+
"Content-Security-Policy":
|
|
135
|
+
"default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'",
|
|
136
|
+
},
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The build needs Python, so run it where the application is built (a CI job or a build stage), not inside a running container that has none. Without Git, or without the `.git` folder (a Docker build usually leaves it out), the page is built all the same, with an empty history and no commit to put into `{commit}`. The **Recent changes** page comes from the Git history: in a shallow clone it starts at the first commit that was fetched in full, and the command says so. In GitHub Actions, `fetch-depth: 0` on the checkout step gives it the whole history.
|
|
142
|
+
|
|
91
143
|
## What a feature page says
|
|
92
144
|
|
|
93
145
|
Every feature, screen or flow has one page, and all of them have the same sections in the same order. A section the feature does not have is left out.
|
|
@@ -124,6 +176,25 @@ A rule's number is its name. It stays the same when the rule's text changes, a n
|
|
|
124
176
|
|
|
125
177
|
Things the code registers in one place and no single feature owns (background jobs, emails, routes, roles, plan limits) are listed in reference pages: one table with every item. A page cites the one to five files that decide its behavior. When one of them changes, the page is marked "Code changed since the last check" until someone re-reads it.
|
|
126
178
|
|
|
179
|
+
### Big features and several apps
|
|
180
|
+
|
|
181
|
+
A feature that is too big for one page (more than about twenty rules, or several kinds of use, such as direct, group and support chats) has **parts**. The vault then has three levels: the area, the feature, and its parts. The feature's page says what it is for and lists its parts; each part is a page of the same shape with its own rules. The viewer shows the parts under their feature.
|
|
182
|
+
|
|
183
|
+
When the product has several clients, such as a web app and a mobile app, a feature page has one more section, `## Where the apps differ`: a table with what each client does, one row per difference.
|
|
184
|
+
|
|
185
|
+
### How deep the first map goes
|
|
186
|
+
|
|
187
|
+
The first map starts with an inventory: every page or screen, every server procedure, every job and email, counted from the place that registers them. The agent then takes one feature at a time and finishes it before starting the next. A page whose feature was not read to the end is marked **Partial** and says what is left. A first map of a large project is therefore a number of finished features and a list of the ones not started, not a thin page about everything.
|
|
188
|
+
|
|
189
|
+
One command shows what is still missing, by reading the code and the pages:
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
project-spec coverage # every folder, the least covered first
|
|
193
|
+
project-spec coverage --path src/features/chat # one feature: each message and limit no page mentions
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Without the package: `python3 <skill>/scripts/coverage.py --repo .`. For each folder it prints how many files a page cites, and how many messages a person can see and how many named limits are on no page. It is a list of places to read, not a score: some of what it lists is left out of the spec on purpose.
|
|
197
|
+
|
|
127
198
|
## Why use this?
|
|
128
199
|
|
|
129
200
|
- **Onboarding:** follow a workflow across UI, API, policy, persistence and tests without rediscovering the same paths every session.
|
|
@@ -145,6 +216,8 @@ The package is [`project-spec`](https://www.npmjs.com/package/project-spec) on t
|
|
|
145
216
|
```sh
|
|
146
217
|
npx project-spec install --claude # or --codex, or --dir knowledge/tooling
|
|
147
218
|
npx project-spec serve # the viewer for the project in the current folder
|
|
219
|
+
npx project-spec build --out FILE # the same viewer as one file, to show on a server
|
|
220
|
+
npx project-spec coverage # what the code has that no spec page mentions yet
|
|
148
221
|
```
|
|
149
222
|
|
|
150
223
|
Then ask your agent to use the `project-knowledge` skill ([example prompts](#example-prompts)).
|
package/bin/project-spec.mjs
CHANGED
|
@@ -13,8 +13,9 @@ const SKILLS = path.join(ROOT, 'skills');
|
|
|
13
13
|
const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
|
|
14
14
|
const MARKER = '.project-spec.json'; // written into every copy: which version it is and what its files looked like
|
|
15
15
|
const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
|
|
16
|
-
const KNOWLEDGE = new Set(['serve', 'check', 'snapshot']);
|
|
16
|
+
const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
|
|
17
17
|
const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
|
|
18
|
+
const COVERAGE = 'coverage'; // its own helper, which takes no command word
|
|
18
19
|
// Skills earlier versions shipped; project-knowledge and spec-change took over what they did.
|
|
19
20
|
const RETIRED = ['spec-audit', 'spec-investigation', 'spec-plan'];
|
|
20
21
|
// Folders inside a project where a copy of the skills may live.
|
|
@@ -25,8 +26,12 @@ const USAGE = `project-spec ${PACKAGE.version}
|
|
|
25
26
|
Read the spec
|
|
26
27
|
project-spec serve [--repo DIR] [--vault DIR] [--port N] [--no-open]
|
|
27
28
|
Open the viewer for the repository (default: the current folder).
|
|
29
|
+
project-spec build --out FILE [--source-url URL] [--with-sources] [--allow-missing-sources]
|
|
30
|
+
Write the viewer as one HTML file, to show the spec on a server.
|
|
28
31
|
project-spec check | snapshot [options]
|
|
29
32
|
The knowledge helper; --repo defaults to the current folder.
|
|
33
|
+
project-spec coverage [--path FOLDER]... [--all]
|
|
34
|
+
What the code has that no spec page mentions yet: folders, messages and limits.
|
|
30
35
|
project-spec scan | receipt | finish [options]
|
|
31
36
|
The sync helper; --repo defaults to the current folder.
|
|
32
37
|
|
|
@@ -251,7 +256,7 @@ function python(script, command, args) {
|
|
|
251
256
|
if (!flag(args, '--no-open') && !args.includes('--open')) args.push('--open');
|
|
252
257
|
}
|
|
253
258
|
const exe = process.env.PROJECT_SPEC_PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
|
|
254
|
-
const full = [path.join(SKILLS, 'project-knowledge', 'scripts', script), command, ...args];
|
|
259
|
+
const full = [path.join(SKILLS, 'project-knowledge', 'scripts', script), ...(command === COVERAGE ? [] : [command]), ...args];
|
|
255
260
|
if (process.env.PROJECT_SPEC_DRY_RUN) return console.log([exe, ...full].join(' ')), 0;
|
|
256
261
|
const run = spawnSync(exe, full, { stdio: 'inherit' });
|
|
257
262
|
if (run.error) throw new Problem(`could not start ${exe}: ${run.error.message}. The helpers need Python 3.10 or newer; set PROJECT_SPEC_PYTHON to its path.`);
|
|
@@ -267,6 +272,7 @@ function main(argv) {
|
|
|
267
272
|
if (command === 'update') return update(args);
|
|
268
273
|
if (KNOWLEDGE.has(command)) return python('knowledge.py', command, args);
|
|
269
274
|
if (MAINTAIN.has(command)) return python('maintain.py', command, args);
|
|
275
|
+
if (command === COVERAGE) return python('coverage.py', command, args);
|
|
270
276
|
throw new Problem(`unknown command: ${command}\n\n${USAGE}`);
|
|
271
277
|
}
|
|
272
278
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "project-spec",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Agent skills that read a repository and keep a spec people can read: one page per feature, every business rule numbered. Local viewer and one command to install and update the skills.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -38,11 +38,11 @@ The full property list, section layout and example are in [gaps.md](references/g
|
|
|
38
38
|
|
|
39
39
|
Natural-language requests are fine; these are modes, not a required CLI.
|
|
40
40
|
|
|
41
|
-
- **map** (a new vault):
|
|
41
|
+
- **map** (a new vault): take the inventory of what the product has, then go through its features one at a time and finish each before starting the next ([Research before writing](#research-before-writing)). A first map is measured by how many features are finished, not by how many pages exist: thirty finished features and a list of forty not started is a better first map than seventy thin pages. A pass that runs out of time says on the run page which features are finished, which are partial and which were not started, and never calls itself full.
|
|
42
42
|
- **update**: revisit claims affected since the previous run, preserve manually written knowledge, add discoveries, and fill in what the pages you touch are missing (see [Leave each page better](#leave-each-page-better)).
|
|
43
43
|
- **sync**: reconcile changes from all contributors since the last reviewed Git checkpoint. Read [the sync workflow](references/sync.md); a sync with work you cannot accept yet (for example another contributor's uncommitted files) uses `deferred` and ends as a partial finish with exit status 3 and the checkpoint unmoved.
|
|
44
44
|
- **merge**: reconcile two contributors' vault updates from their common Git base. Read [the merge workflow](references/merge.md).
|
|
45
|
-
- **explore <area or question>**: deepen a bounded area and link the result into the vault. Deepening an area means its feature notes first: what each one is for and every rule a person would look up, with its values. Then the lists the code keeps in one place, such as its background jobs. A request to "fill in", "complete"
|
|
45
|
+
- **explore <area or question>**: deepen a bounded area and link the result into the vault. Deepening an area means its feature notes first: what each one is for and every rule a person would look up, with its values, until [the feature is finished](#when-a-feature-is-finished). Then the lists the code keeps in one place, such as its background jobs. A request to "fill in", "complete", "backfill" or "go deeper" means this mode, and so does a reader saying a page is thin.
|
|
46
46
|
- **gaps**: work the queue. List gaps by state; re-verify open gaps against the current code; every kind of gap is rechecked, proposals and questions about unexplained behavior included, because the recheck asks only whether the page's `Current behavior` still describes the code (`confirmed (still holds)` or `not reproduced (no longer holds)`) and never whether a proposal is worth doing, which is the person's decision. For a proposal that usually means confirming the capability is absent. Record each result in the gap's `Recheck` section with `recheck`, `rechecked_by` (`agent` for checks you ran), `rechecked_on`; set `recheck: "outdated"` on a gap whose cited source changed since its recorded recheck (keeping the other two fields); set `done` where the code now closes the question, recording that reading as a `not-reproduced` recheck by `agent` ([closing a gap as done](references/gaps.md#closing-a-gap-as-done)); mark duplicates. Then hand the `needs-decision` gaps to people with the options you found in `Discussion`. Never decide one yourself. When a person decides in the conversation, record it with their name; if you do not know their name, ask rather than writing `agent`.
|
|
47
47
|
- **audit <document or feature>**: compare written requirements with the code, keeping what the code satisfies apart from what needs action. Read [the audit guide](references/audit.md). In a vault each finding that needs action becomes its own gap; without a vault the audit is a report.
|
|
48
48
|
- **investigate <question>** or **recheck <gap>**: answer one question about behavior from repository and runtime evidence, or re-check a single gap and write the result into it. Read [the investigation guide](references/investigate.md). It works without a vault too.
|
|
@@ -58,9 +58,23 @@ Write vault content in English unless the user asks for another language, whatev
|
|
|
58
58
|
|
|
59
59
|
1. Read the repository's instructions and any task coordination they require. Preserve existing edits. Record the exact revision and whether you read uncommitted files. Application source is read-only: this skill writes only inside the vault.
|
|
60
60
|
2. Inspect manifests, entrypoints, routes, schema and migrations, services and tests. Skip dependencies, build output, credential files, raw logs and customer data. Never use the vault itself as evidence about the application.
|
|
61
|
-
3.
|
|
62
|
-
4.
|
|
63
|
-
5.
|
|
61
|
+
3. **Take the inventory before writing a page.** List what the product has from the places that register it, every item and not a sample: the pages or screens of every client (web, mobile, admin), the API procedures or endpoints, the jobs, the emails. Count them. Run `coverage` (below) for the size of each folder. Group the items into features and write that list on the run page with each feature's size: its entry points, its folders, its lines. This list is the plan and the ledger of the whole map. A directory name establishes neither a feature nor a behavior, so check a group against what its entry points do.
|
|
62
|
+
4. **Split a big feature before writing it.** One page holds what a person reads in one sitting: about twenty rules. A feature with more than about eight entry points, more than about 2,000 lines of its own code, or several kinds of user or flow (direct, group and support chats) will not fit, and squeezing it into one page is how fifty rules become thirteen. Give it a feature note and one note per part ("A feature with parts" under [Write the spec](#write-the-spec)).
|
|
63
|
+
5. **Go deep before going wide.** Take one feature and finish it before starting the next. Read every one of its entry points on every client and follow each to the file that decides the behavior (the schema, the service, the policy, the component). Read its rules off the code: a `max(60)` in a schema, a `disabled={items.length === 0}` on a button, a `CHECK` constraint, a default value, a permission check, every `throw` and every refusal. Read the words a person sees too, the labels, the error messages and what an empty list says, and quote them. For the things the code registers in one place (the queue and cron registrations, the route table, the email templates, the roles, the flags), enumerate from that place, every item.
|
|
64
|
+
6. **Read each client.** When the product has more than one client, read the feature in each of them. Two clients calling the same server procedure does not make them the same: one may lack a screen, a check or a confirmation. Write what differs on the feature's page ([Write the spec](#write-the-spec)); a difference that looks unintended is also a gap.
|
|
65
|
+
7. Track what was read, merely discovered, excluded or changing in each area. Discovery is not review, and a note count is not completeness. When the session will not cover everything, stop at the end of a feature, not in the middle of all of them.
|
|
66
|
+
|
|
67
|
+
### When a feature is finished
|
|
68
|
+
|
|
69
|
+
A feature is finished when nothing is left on its list, not when its page looks complete. Run the report for its folders:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
python3 "$SKILL_DIR/scripts/coverage.py" --repo "$REPO" --vault "$VAULT" --path src/features/chat --path mobile/src/chat
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
It prints the files there that no page cites, and each sentence a person can see and each named number (`CHAT_MAX_MEDIA = 10`) that no page mentions. Go through that list. Each item is one of three things: a rule that belongs on the page (add it, quoting the message or naming the number), something the spec leaves out on purpose (a control that only opens or closes, a label, a log line), or code you have not read (read it). Run it again until what is left is only the second kind. Without `--path` the report ranks every folder of the repository by how much it has that no page mentions, which is how you find the features nobody wrote down at all.
|
|
76
|
+
|
|
77
|
+
The report is a list of places to read, not a score, and it cannot see a rule that has no message and no named number, so it does not replace reading the entry points. A page whose feature is not finished has `status: "partial"` and ends with a line saying what is left ("Not read yet: the support chat screens, the mobile app"); `current` means the whole feature was read. Put the report's first lines for each finished feature on the run page.
|
|
64
78
|
|
|
65
79
|
Delegate only when the user or repository instructions allow it; give each helper a disjoint area and integrate their evidence before accepting a claim.
|
|
66
80
|
|
|
@@ -76,13 +90,16 @@ Write for the person who asks "what does this do, and what are its rules", not f
|
|
|
76
90
|
3. `## Fields`, when the feature has a form: a table with one row per field (`Field`, `Required`, `Rule`, `Message when refused`).
|
|
77
91
|
4. `## Business rules`: a table with one numbered rule per row (`ID`, `Rule`): who may do it, when an action is available, disabled or hidden, limits and defaults, what is kept, sent or deleted, and when. One or two sentences per rule, with the value. A field's rule is in `Fields` and is not repeated here.
|
|
78
92
|
|
|
93
|
+
5. `## Where the apps differ`, when the product has several clients: a table with one row per difference (`What`, then one column per client, such as `Web` and `Mobile`). Say what each client does, in a few words; "same" is not a row. When the clients were compared and nothing differs, write that one sentence instead of the table, and say which clients were compared.
|
|
94
|
+
|
|
79
95
|
Use these headings as written and in this order, and leave out a section the feature does not have. Links to the notes it depends on go in the sentence or rule where they matter. Everything about the feature is on this page: do not move its fields, its actions or who may use them to another page, because a reader of Profile should not need four pages to learn what Profile does. A note is as long as its rules need; split a long note by feature or flow, never by kind of fact.
|
|
96
|
+
- **A feature with parts.** The vault has three levels and no more: an area, its features, and the parts of a feature that is too big for one page. A part is a feature note with `parent: "<id of the feature note>"`, in the same area, about one flow or one kind of use: "Group chats", "Support chats", "Sending a message". The feature's own note stays short: what the feature is for, how its parts fit together, the rules that hold in every part, and `## Parts`, a list with a link to each part and one line saying what it covers. Each rule is written once, in the part it belongs to, with the part's own rule word (`BR-GROUPCHAT-01`). The area page lists the feature, not its parts. Split when the page would pass about twenty rules or the feature has several kinds of user or flow; do not split a feature that fits one page, and never make a part of a part. `check` rejects a part whose feature does not link to it.
|
|
80
97
|
- **A rule's number is its name.** Write it `BR-<FEATURE>-<NN>`, for example `BR-PROFILE-01`: a short upper-case word for the feature, the same in all rules of the note and used by no other note, then a number counting up from 01. People quote these numbers in tickets, tests and conversations, so a rule keeps its number when its text changes, a new rule gets the next free number, and the number of a rule that no longer exists is never used again. Never renumber to close a hole or to reorder. `check` rejects a number that appears twice.
|
|
81
98
|
- **Write down the business rules, with their values.** The concrete rule is the content and a description of the mechanism is not enough: "a name is required and at most 60 characters, and longer input is refused with 'Name is too long'", not "the form validates the name". For every form, action and job say what is required, the limits (length, range, count, size, format, uniqueness), defaults, rounding and time zones, when an action is available, disabled or hidden ("Send is disabled while the list is empty"), what an empty list shows, what needs a confirmation, which error the person sees, and who may do it. Leave out controls that only open, close, go somewhere or try again: an action is worth a line when it changes something or has a condition. When the browser and the server check different things, write both; when they disagree, open a `conflict` gap. A note that says "validates input" or "uses a worker" without the rules it applies is not finished.
|
|
82
99
|
- **Say it in the product's words.** "Saving is refused", "the list reloads", "only owners see it", not "the mutation rejects", "refetches", "the RPC requires a nonempty team ID". Name a constant, a job or a route in code formatting when someone would search for it; keep the rest of the code's vocabulary out.
|
|
83
100
|
- **The summary says what the feature is for**, in one or two plain sentences, as a person who never opens the code would say it: no file names, symbols, status codes or words like "verified", and not a rule picked from the page ("The form accepts 1-120 characters" is a rule, not a summary). The viewer shows it under the title and in every list. It is still a claim about the code: it says no more than the page proves. Do not infer design rationale; cite a comment or ADR in the source, or say it is unknown.
|
|
84
101
|
- **A reference note** is a list of things the code registers in one place and that belong to no single feature: the background jobs, the emails and notifications, the routes, the roles and what each may do, the plan limits, the flags, the states of a record. It is one table, one row per item, every item, with the count and where the list comes from ("all 7 jobs registered in `worker/index.ts`"), so a later sync can tell when one is added; put that place in `sources`. A cell holds a value in a few words, two short sentences at most; an item that needs more has a feature note, and the row links to it. Do not write a list note for form fields or for the actions on a screen (they are in the feature's note), for a kind the area has only one or two of, or for a kind it does not have. Each rule is written once: in the feature's note when it belongs to a feature, in the list when it does not.
|
|
85
|
-
- **Cite the few files that decide the behavior.** `sources` holds the files where the rule is written (the schema, the service, the component), usually one to five. Every source is a tripwire: when it changes, the page is marked for re-reading. So leave out shared plumbing (the router, a layout, the base client), files that merely sit on the path, and tests unless a test is what the claim rests on. In the text, name the symbol a rule comes from (`INVITE_TTL_DAYS`) and link a file where it helps, without line numbers: a line number points at the wrong line after the next edit, a name still finds the place. When files are renamed or split, `check` reports the missing path; point `sources` at where the rule lives now and re-read the page.
|
|
102
|
+
- **Cite the few files that decide the behavior.** `sources` holds the files where the rule is written (the schema, the service, the component), usually one to five. A page that needs many more to back its rules is usually a feature that should have parts. Every source is a tripwire: when it changes, the page is marked for re-reading. So leave out shared plumbing (the router, a layout, the base client), files that merely sit on the path, and tests unless a test is what the claim rests on. In the text, name the symbol a rule comes from (`INVITE_TTL_DAYS`) and link a file where it helps, without line numbers: a line number points at the wrong line after the next edit, a name still finds the place. When files are renamed or split, `check` reports the missing path; point `sources` at where the rule lives now and re-read the page.
|
|
86
103
|
- **What you ran goes on the run page**, not in the note: commands, PASS, FAIL or NOT RUN, the revision. A note has no "Verification" section and no line naming its area (the frontmatter has it and the viewer shows it). Reading a test does not mean it passes today, so do not write that it does.
|
|
87
104
|
- Link related spec pages with `[[notes/example|label]]` in the sentence that needs them, and say how they relate (depends on, constrains, produces, supersedes). A note belongs to one area; give it a second only when both areas' readers would look for it there. Every substantive page needs an area and a path from the index. Add cross-area links for a reason, not for graph density.
|
|
88
105
|
- A requirements document or ticket is documented intent. It can be quoted in a gap's `Evidence`; it is not a source for what the code does, so never list it in a spec page's `sources` or describe its labels in spec text.
|
|
@@ -122,18 +139,20 @@ python3 "$SKILL_DIR/scripts/knowledge.py" check --repo "$REPO" --vault "$VAULT"
|
|
|
122
139
|
python3 "$SKILL_DIR/scripts/knowledge.py" snapshot --repo "$REPO" --vault "$VAULT" --notes note-id area-id
|
|
123
140
|
```
|
|
124
141
|
|
|
125
|
-
`check` validates structure and freshness; it cannot judge prose or coverage. `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
|
|
142
|
+
`check` validates structure and freshness; it cannot judge prose or coverage. `coverage.py` lists what the code has that no page mentions ([When a feature is finished](#when-a-feature-is-finished)). `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
|
|
126
143
|
|
|
127
|
-
To read the result, run `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` (add `--vault` when the repository has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The command is long, so when you hand over offer to give it a short name in the project: a `spec` script in `package.json` (`project-spec serve` when the project has the `project-spec-skills` package, otherwise the full command), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead.
|
|
144
|
+
To read the result, run `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` (add `--vault` when the repository has several vaults under `knowledge/`), or open the folder as an Obsidian vault. The command is long, so when you hand over offer to give it a short name in the project: a `spec` script in `package.json` (`project-spec serve` when the project has the `project-spec-skills` package, otherwise the full command), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `knowledge.py build --repo <repository> --out <file outside the vault>` writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
|
|
128
145
|
|
|
129
146
|
Before handing over, read what you wrote as the person who will use it, not as its author. Open one area page and two of the notes you wrote or changed, and ask:
|
|
130
147
|
|
|
131
148
|
- Does the note start by saying what the feature is for and who uses it, before any rule?
|
|
132
149
|
- Is each rule one numbered row a person could quote, with its value, and did every rule that was already there keep its number?
|
|
133
150
|
- Could someone answer "how long may a name be", "when is this button disabled" or "which jobs run at night" from the page without opening the code? If the answer is in the code you read but not on the page, add it.
|
|
151
|
+
- Did `coverage --path` for the feature's folders end with only things the spec leaves out on purpose? Is every page whose feature is not finished marked `partial`, with what is left?
|
|
152
|
+
- Does a feature with more than about twenty rules have parts, and does a product with several clients say on each feature page where they differ?
|
|
134
153
|
- Is everything about one feature on its own page, or does the reader have to collect it from several?
|
|
135
154
|
- Would a person who never opens the code understand every sentence? Would the page survive a file being renamed?
|
|
136
155
|
- Does the area page only map, with its missing lists named?
|
|
137
156
|
- Is every doubt a gap about the product, and nothing in the queue a to-do of the vault itself?
|
|
138
157
|
|
|
139
|
-
Then validate and, when tools allow, open the viewer. Report real counts, coverage
|
|
158
|
+
Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory are finished, partial and not started, the first lines of the `coverage` report for the whole repository, the checks you ran and how to open the result. Do not describe a map as full or complete while the inventory has features that are not finished. Keep structural validation, application tests and GUI checks separate. Committing and pushing are left to the user.
|
|
@@ -228,6 +228,10 @@
|
|
|
228
228
|
padding-left: 40px;
|
|
229
229
|
color: var(--muted);
|
|
230
230
|
}
|
|
231
|
+
.tree-row.part {
|
|
232
|
+
padding-left: 58px;
|
|
233
|
+
font-size: 0.94em;
|
|
234
|
+
}
|
|
231
235
|
|
|
232
236
|
/* Top bar: where you are, and what you can do with the page. */
|
|
233
237
|
.topbar {
|
|
@@ -1558,8 +1562,9 @@
|
|
|
1558
1562
|
(n) => n && typeof n === "object",
|
|
1559
1563
|
),
|
|
1560
1564
|
edges = Array.isArray(data.edges) ? data.edges : [];
|
|
1561
|
-
// Sent by `knowledge.py serve`
|
|
1562
|
-
// repository, its Git history and its uncommitted pages.
|
|
1565
|
+
// Sent by `knowledge.py serve` and `build`: the text of cited repository files (build leaves it out
|
|
1566
|
+
// unless asked), the vault's place in the repository, its Git history and its uncommitted pages.
|
|
1567
|
+
// A page without them still works.
|
|
1563
1568
|
const files =
|
|
1564
1569
|
data.files && typeof data.files === "object" ? data.files : {},
|
|
1565
1570
|
vaultPath = typeof data.vaultPath === "string" ? data.vaultPath : "",
|
|
@@ -1570,6 +1575,15 @@
|
|
|
1570
1575
|
(p) => p && typeof p === "object",
|
|
1571
1576
|
);
|
|
1572
1577
|
const live = data.live === true;
|
|
1578
|
+
// A page written by `knowledge.py build` to be put on a server: a copy of one moment, read by people
|
|
1579
|
+
// who may not have the repository. `sourceUrl` is where a cited file can be read instead.
|
|
1580
|
+
const built = data.built === true,
|
|
1581
|
+
builtCommit = typeof data.commit === "string" ? data.commit : "",
|
|
1582
|
+
builtOn = typeof data.generatedAt === "string" ? data.generatedAt.slice(0, 10) : "",
|
|
1583
|
+
sourceUrl =
|
|
1584
|
+
built && typeof data.sourceUrl === "string" && /^https?:\/\/[^\s/]/i.test(data.sourceUrl)
|
|
1585
|
+
? data.sourceUrl.replace(/\/+$/, "")
|
|
1586
|
+
: "";
|
|
1573
1587
|
const byId = new Map(nodes.map((n) => [n.id, n])),
|
|
1574
1588
|
byPath = new Map(
|
|
1575
1589
|
nodes.map((n) => [String(n.path || "").replace(/\.md$/i, ""), n]),
|
|
@@ -1665,6 +1679,20 @@
|
|
|
1665
1679
|
const i = STATES.indexOf(stateOf(n));
|
|
1666
1680
|
return i < 0 ? STATES.length : i;
|
|
1667
1681
|
};
|
|
1682
|
+
// Priority is free text. The usual words and P0-P4 sort from most to least urgent, any other
|
|
1683
|
+
// value after them, and a gap without a priority last.
|
|
1684
|
+
const PRIORITY_RANKS = { critical: 0, urgent: 0, highest: 0, high: 1, medium: 2, normal: 2, low: 3, lowest: 4 };
|
|
1685
|
+
const priorityOf = (n) => str(n.priority).trim().toLowerCase();
|
|
1686
|
+
const priorityRank = (n) => {
|
|
1687
|
+
const p = priorityOf(n),
|
|
1688
|
+
digit = /^p?([0-4])$/.exec(p);
|
|
1689
|
+
if (!p) return 6;
|
|
1690
|
+
if (digit) return +digit[1];
|
|
1691
|
+
return Object.prototype.hasOwnProperty.call(PRIORITY_RANKS, p) ? PRIORITY_RANKS[p] : 5;
|
|
1692
|
+
};
|
|
1693
|
+
// The order of every list of gaps: by state, then the most urgent first, then by title.
|
|
1694
|
+
const byGapOrder = (a, b) =>
|
|
1695
|
+
stateRank(a) - stateRank(b) || priorityRank(a) - priorityRank(b) || byTitle(a, b);
|
|
1668
1696
|
const stateClass = (n) =>
|
|
1669
1697
|
isGap(n)
|
|
1670
1698
|
? "st-" + stateOf(n)
|
|
@@ -1694,7 +1722,13 @@
|
|
|
1694
1722
|
const areas = nodes.filter((n) => n.type === "area").sort(byTitle);
|
|
1695
1723
|
$("#project-title").textContent = projectTitle;
|
|
1696
1724
|
$("#project-title").title = projectTitle;
|
|
1697
|
-
$("#header-note").textContent = live
|
|
1725
|
+
$("#header-note").textContent = live
|
|
1726
|
+
? "Spec · live from disk"
|
|
1727
|
+
: built
|
|
1728
|
+
? "Spec" + (builtOn ? " · built " + builtOn : "")
|
|
1729
|
+
: "Spec";
|
|
1730
|
+
// The line is too narrow for the commit as well, so it is in the tooltip.
|
|
1731
|
+
if (built && builtCommit) $("#header-note").title = "Built from commit " + builtCommit;
|
|
1698
1732
|
// Small things kept in this browser only: where you were, what you picked. Never required.
|
|
1699
1733
|
const store = {
|
|
1700
1734
|
key: (name) => "spec-viewer:" + projectTitle + ":" + name,
|
|
@@ -1834,8 +1868,9 @@
|
|
|
1834
1868
|
return out.join("/");
|
|
1835
1869
|
}
|
|
1836
1870
|
const hasFile = (key) => Object.prototype.hasOwnProperty.call(files, key);
|
|
1837
|
-
// A relative Markdown link
|
|
1838
|
-
|
|
1871
|
+
// A relative Markdown link read as a place in the repository: the file and which lines it names.
|
|
1872
|
+
// Null for an address, an anchor or a path that leaves the repository.
|
|
1873
|
+
function repoTarget(raw, n) {
|
|
1839
1874
|
let t = String(raw).trim();
|
|
1840
1875
|
if (t.startsWith("<") && t.endsWith(">")) t = t.slice(1, -1);
|
|
1841
1876
|
if (!t || t[0] === "#" || t[0] === "/" || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(t))
|
|
@@ -1849,10 +1884,27 @@
|
|
|
1849
1884
|
const dir = String(n.path || "").split("/").slice(0, -1).join("/");
|
|
1850
1885
|
// Vault pages link relative to themselves inside the vault; a cited document links relative to itself in the repository.
|
|
1851
1886
|
const key = normPath(n.repoFile ? [dir, t] : [vaultPath, dir, t]);
|
|
1852
|
-
if (!
|
|
1887
|
+
if (!key || key.split("/")[0] === "..") return null;
|
|
1853
1888
|
const m = hash.match(/^L(\d+)(?:-L?(\d+))?$/i);
|
|
1854
1889
|
return { key, from: m ? +m[1] : 0, to: m ? +(m[2] || m[1]) : 0 };
|
|
1855
1890
|
}
|
|
1891
|
+
// The same link when the text of that file came with the page, so it can be opened in place.
|
|
1892
|
+
function fileRef(raw, n) {
|
|
1893
|
+
const ref = repoTarget(raw, n);
|
|
1894
|
+
return ref && hasFile(ref.key) ? ref : null;
|
|
1895
|
+
}
|
|
1896
|
+
// A cited file on the code host a built page was given: a new tab, since the reader leaves the spec.
|
|
1897
|
+
function sourceLink(ref, text) {
|
|
1898
|
+
const a = el("a", text);
|
|
1899
|
+
a.href =
|
|
1900
|
+
sourceUrl +
|
|
1901
|
+
"/" +
|
|
1902
|
+
ref.key.split("/").map(encodeURIComponent).join("/") +
|
|
1903
|
+
(ref.from ? "#L" + ref.from + (ref.to > ref.from ? "-L" + ref.to : "") : "");
|
|
1904
|
+
a.target = "_blank";
|
|
1905
|
+
a.rel = "noopener noreferrer";
|
|
1906
|
+
return a;
|
|
1907
|
+
}
|
|
1856
1908
|
const isMarkdownFile = (key) => /\.(md|markdown)$/i.test(key);
|
|
1857
1909
|
let fileState = null;
|
|
1858
1910
|
function fileButton(ref, text) {
|
|
@@ -1888,7 +1940,7 @@
|
|
|
1888
1940
|
? "Lines " + ref.from + "–" + ref.to
|
|
1889
1941
|
: "Line " + ref.from) + " · "
|
|
1890
1942
|
: "") +
|
|
1891
|
-
(live ? "Read from disk when this page loaded" : "Copy taken when this
|
|
1943
|
+
(live ? "Read from disk when this page loaded" : "Copy taken when this page was built") +
|
|
1892
1944
|
(file.truncated ? " · only the beginning of the file is shown" : "");
|
|
1893
1945
|
actions.replaceChildren();
|
|
1894
1946
|
if (isMarkdownFile(ref.key))
|
|
@@ -1957,9 +2009,16 @@
|
|
|
1957
2009
|
else {
|
|
1958
2010
|
const parts = token.match(/^\[([^\]]+)\]\(([^)]+)\)$/),
|
|
1959
2011
|
ref = parts && fileRef(parts[2], n),
|
|
1960
|
-
|
|
2012
|
+
// On a built page a relative link would lead into the site that hosts it, not to the file.
|
|
2013
|
+
away = parts && !ref && built && !n.repoFile ? repoTarget(parts[2], n) : null,
|
|
2014
|
+
href = parts && !ref && !away && !n.repoFile && safeHref(parts[2], n);
|
|
1961
2015
|
if (ref) parent.append(fileButton(ref, parts[1]));
|
|
1962
|
-
else if (
|
|
2016
|
+
else if (away && sourceUrl) parent.append(sourceLink(away, parts[1]));
|
|
2017
|
+
else if (away) {
|
|
2018
|
+
const name = el("span", parts[1]);
|
|
2019
|
+
name.title = away.key;
|
|
2020
|
+
parent.append(name);
|
|
2021
|
+
} else if (href) {
|
|
1963
2022
|
const a = el("a", parts[1]);
|
|
1964
2023
|
a.href = href;
|
|
1965
2024
|
parent.append(a);
|
|
@@ -2140,7 +2199,7 @@
|
|
|
2140
2199
|
if (g && isGap(g)) out.set(g.id, g);
|
|
2141
2200
|
});
|
|
2142
2201
|
return [...out.values()].sort(
|
|
2143
|
-
|
|
2202
|
+
byGapOrder,
|
|
2144
2203
|
);
|
|
2145
2204
|
}
|
|
2146
2205
|
const planOf = (g) => nodes.find((p) => isPlan(p) && p.gap === g.id);
|
|
@@ -2215,11 +2274,18 @@
|
|
|
2215
2274
|
}
|
|
2216
2275
|
const primaryArea = (n) => (n.areas || [])[0] || "";
|
|
2217
2276
|
const isFeature = (n) => n.type === "note" && n.status !== "superseded";
|
|
2277
|
+
// A part of a feature: a note whose `parent` names another note. One level only, so the tree is
|
|
2278
|
+
// area, feature, part; a parent that is missing or is itself a part is ignored.
|
|
2279
|
+
const parentOf = (n) => {
|
|
2280
|
+
const p = n.type === "note" && str(n.parent) ? byId.get(n.parent) : null;
|
|
2281
|
+
return p && p !== n && isFeature(p) && !str(p.parent) ? p : null;
|
|
2282
|
+
};
|
|
2283
|
+
const partsOf = (n) => nodes.filter((p) => isFeature(p) && parentOf(p) === n).sort(byTitle);
|
|
2218
2284
|
const featuresOf = (area) =>
|
|
2219
|
-
nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id).sort(byTitle);
|
|
2285
|
+
nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id && !parentOf(n)).sort(byTitle);
|
|
2220
2286
|
const looseFeatures = () =>
|
|
2221
2287
|
nodes
|
|
2222
|
-
.filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area")
|
|
2288
|
+
.filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area" && !parentOf(n))
|
|
2223
2289
|
.sort(byTitle);
|
|
2224
2290
|
const waiting = (n) =>
|
|
2225
2291
|
gapsAbout(n).filter((g) =>
|
|
@@ -2333,15 +2399,23 @@
|
|
|
2333
2399
|
});
|
|
2334
2400
|
const tree = $("#tree");
|
|
2335
2401
|
tree.replaceChildren();
|
|
2336
|
-
const noteRow = (f) => {
|
|
2337
|
-
const b = button(null, "tree-row note", () => openNode(f)),
|
|
2338
|
-
open = waiting(f).length
|
|
2402
|
+
const noteRow = (f, cls, folded) => {
|
|
2403
|
+
const b = button(null, "tree-row note" + (cls ? " " + cls : ""), () => openNode(f)),
|
|
2404
|
+
open = waiting(f).length,
|
|
2405
|
+
meta = [open && open + " open", folded && plural(folded, "part")].filter(Boolean).join(" · ");
|
|
2339
2406
|
b.append(el("span", f.title, "label"));
|
|
2340
2407
|
b.title = f.title; // the row shows one line; the full name is a hover away
|
|
2341
|
-
if (
|
|
2408
|
+
if (meta) b.append(el("span", meta, "meta"));
|
|
2342
2409
|
b.setAttribute("aria-current", selected === f ? "page" : "false");
|
|
2343
2410
|
return b;
|
|
2344
2411
|
};
|
|
2412
|
+
// A feature's parts are listed under it while the reader is on the feature or on one of them.
|
|
2413
|
+
const featureRows = (f) => {
|
|
2414
|
+
const parts = partsOf(f),
|
|
2415
|
+
unfolded = parts.length && (selected === f || parts.includes(selected));
|
|
2416
|
+
tree.append(noteRow(f, "", unfolded ? 0 : parts.length));
|
|
2417
|
+
if (unfolded) parts.forEach((p) => tree.append(noteRow(p, "part")));
|
|
2418
|
+
};
|
|
2345
2419
|
areas.forEach((a) => {
|
|
2346
2420
|
const open = openAreas.has(a.id),
|
|
2347
2421
|
line = el("div", null, "tree-area"),
|
|
@@ -2362,12 +2436,12 @@
|
|
|
2362
2436
|
name.setAttribute("aria-current", selected === a ? "page" : "false");
|
|
2363
2437
|
line.append(twist, name);
|
|
2364
2438
|
tree.append(line);
|
|
2365
|
-
if (open) featuresOf(a).forEach(
|
|
2439
|
+
if (open) featuresOf(a).forEach(featureRows);
|
|
2366
2440
|
});
|
|
2367
2441
|
const loose = looseFeatures();
|
|
2368
2442
|
if (loose.length) {
|
|
2369
2443
|
tree.append(el("div", "Other", "eyebrow"));
|
|
2370
|
-
loose.forEach(
|
|
2444
|
+
loose.forEach(featureRows);
|
|
2371
2445
|
}
|
|
2372
2446
|
if (!areas.length && !loose.length) tree.append(el("p", "No pages yet.", "empty"));
|
|
2373
2447
|
}
|
|
@@ -2383,6 +2457,7 @@
|
|
|
2383
2457
|
if (n) {
|
|
2384
2458
|
const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
|
|
2385
2459
|
if (parent && parent.type === "area") parts.push([parent.title, { name: "page", id: parent.id }]);
|
|
2460
|
+
if (parentOf(n)) parts.push([parentOf(n).title, { name: "page", id: parentOf(n).id }]);
|
|
2386
2461
|
if (isGap(n) || isPlan(n)) parts.push(["Gaps", { name: "gaps", id: "" }]);
|
|
2387
2462
|
if (isPlan(n) && byId.get(n.gap)) parts.push([byId.get(n.gap).title, { name: "page", id: n.gap }]);
|
|
2388
2463
|
parts.push([n.title, null]);
|
|
@@ -2437,6 +2512,16 @@
|
|
|
2437
2512
|
open = waiting(f).length;
|
|
2438
2513
|
item.append(button(f.title, "rowlink", () => openNode(f)));
|
|
2439
2514
|
if (str(f.summary).trim()) item.append(el("p", f.summary, "muted"));
|
|
2515
|
+
const parts = partsOf(f);
|
|
2516
|
+
if (parts.length) {
|
|
2517
|
+
const line = el("p", null, "muted small parts");
|
|
2518
|
+
line.append(el("span", plural(parts.length, "part") + ": "));
|
|
2519
|
+
parts.forEach((part, i) => {
|
|
2520
|
+
if (i) line.append(document.createTextNode(", "));
|
|
2521
|
+
line.append(button(part.title, "wiki", () => openNode(part)));
|
|
2522
|
+
});
|
|
2523
|
+
item.append(line);
|
|
2524
|
+
}
|
|
2440
2525
|
if (open) item.append(el("span", plural(open, "open question"), "muted small"));
|
|
2441
2526
|
box.append(item);
|
|
2442
2527
|
});
|
|
@@ -2464,7 +2549,8 @@
|
|
|
2464
2549
|
};
|
|
2465
2550
|
const sourceLine = (src) => {
|
|
2466
2551
|
const key = normPath([src]);
|
|
2467
|
-
|
|
2552
|
+
const ref = { key, from: 0, to: 0 };
|
|
2553
|
+
return hasFile(key) ? fileButton(ref, src) : sourceUrl && key ? sourceLink(ref, src) : el("span", src);
|
|
2468
2554
|
};
|
|
2469
2555
|
|
|
2470
2556
|
// --- Views ---------------------------------------------------------------------------------------
|
|
@@ -2499,6 +2585,8 @@
|
|
|
2499
2585
|
path.append(button(projectTitle, null, () => go({ name: "home", id: "" })));
|
|
2500
2586
|
const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
|
|
2501
2587
|
if (parent && parent.type === "area") path.append(button(parent.title, null, () => openNode(parent)));
|
|
2588
|
+
const feature = parentOf(n);
|
|
2589
|
+
if (feature) path.append(button(feature.title, null, () => openNode(feature)));
|
|
2502
2590
|
if (isGap(n) || isPlan(n)) path.append(button("Gaps", null, () => go({ name: "gaps", id: "" })));
|
|
2503
2591
|
path.append(el("span", n.title, "now"));
|
|
2504
2592
|
card.append(path);
|
|
@@ -2509,7 +2597,7 @@
|
|
|
2509
2597
|
// Pages this one links to or is linked from: a short list beside the text, not a block inside it.
|
|
2510
2598
|
if (layerOf(n) === "spec") {
|
|
2511
2599
|
const related = neighbours(n, "spec").filter(
|
|
2512
|
-
(r) => r.id !== parent?.id && !(n.type === "area" && primaryArea(r) === n.id),
|
|
2600
|
+
(r) => r.id !== parent?.id && r !== feature && !(n.type === "area" && primaryArea(r) === n.id),
|
|
2513
2601
|
);
|
|
2514
2602
|
if (related.length) {
|
|
2515
2603
|
const list = el("div", null, "recent"),
|
|
@@ -2644,7 +2732,8 @@
|
|
|
2644
2732
|
|
|
2645
2733
|
let gapState = "all",
|
|
2646
2734
|
gapArea = "",
|
|
2647
|
-
gapKind = ""
|
|
2735
|
+
gapKind = "",
|
|
2736
|
+
gapPriority = ""; // "" for all, "none" for gaps without one, otherwise the value
|
|
2648
2737
|
const selectOf = (label, options, value, pick) => {
|
|
2649
2738
|
const s = el("select");
|
|
2650
2739
|
s.setAttribute("aria-label", label);
|
|
@@ -2666,7 +2755,11 @@
|
|
|
2666
2755
|
head.title = "Questions about what is missing, unverified or could be added. Each one is rechecked and then decided by a person.";
|
|
2667
2756
|
box.append(head);
|
|
2668
2757
|
const pool = nodes.filter(
|
|
2669
|
-
(n) =>
|
|
2758
|
+
(n) =>
|
|
2759
|
+
isGap(n) &&
|
|
2760
|
+
inArea(n, gapArea) &&
|
|
2761
|
+
(!gapKind || n.kind === gapKind) &&
|
|
2762
|
+
(!gapPriority || (priorityOf(n) || "none") === gapPriority),
|
|
2670
2763
|
),
|
|
2671
2764
|
again = () => show();
|
|
2672
2765
|
head.append(
|
|
@@ -2701,9 +2794,29 @@
|
|
|
2701
2794
|
again();
|
|
2702
2795
|
}),
|
|
2703
2796
|
);
|
|
2797
|
+
// Only the priorities the queue has, most urgent first; nothing to pick when no gap has one.
|
|
2798
|
+
const priorities = [...new Set(nodes.filter(isGap).map(priorityOf).filter(Boolean))].sort(
|
|
2799
|
+
(a, b) => priorityRank({ priority: a }) - priorityRank({ priority: b }) || a.localeCompare(b),
|
|
2800
|
+
);
|
|
2801
|
+
if (priorities.length || gapPriority)
|
|
2802
|
+
head.append(
|
|
2803
|
+
selectOf(
|
|
2804
|
+
"Priority",
|
|
2805
|
+
[
|
|
2806
|
+
["", "All priorities"],
|
|
2807
|
+
...priorities.map((p) => [p, p[0].toUpperCase() + p.slice(1) + " priority"]),
|
|
2808
|
+
["none", "No priority"],
|
|
2809
|
+
],
|
|
2810
|
+
gapPriority,
|
|
2811
|
+
(v) => {
|
|
2812
|
+
gapPriority = v;
|
|
2813
|
+
again();
|
|
2814
|
+
},
|
|
2815
|
+
),
|
|
2816
|
+
);
|
|
2704
2817
|
const shown = pool
|
|
2705
2818
|
.filter((g) => gapState === "all" || stateOf(g) === gapState)
|
|
2706
|
-
.sort(
|
|
2819
|
+
.sort(byGapOrder);
|
|
2707
2820
|
if (shown.length) {
|
|
2708
2821
|
const card = el("section", null, "card");
|
|
2709
2822
|
card.id = "gap-list";
|
|
@@ -2735,7 +2848,7 @@
|
|
|
2735
2848
|
}),
|
|
2736
2849
|
);
|
|
2737
2850
|
const shown = gaps
|
|
2738
|
-
? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort(
|
|
2851
|
+
? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort(byGapOrder)
|
|
2739
2852
|
: nodes.filter((n) => layerOf(n) === "spec" && inArea(n, mapArea));
|
|
2740
2853
|
draw(graphModel(shown), false);
|
|
2741
2854
|
}
|
|
@@ -2891,7 +3004,7 @@
|
|
|
2891
3004
|
"p",
|
|
2892
3005
|
historyLog.length
|
|
2893
3006
|
? "Nothing in the history matches this filter."
|
|
2894
|
-
: live
|
|
3007
|
+
: live || built
|
|
2895
3008
|
? "No Git history was found for this vault."
|
|
2896
3009
|
: "History is shown when the spec is opened with the serve command.",
|
|
2897
3010
|
"empty",
|
|
@@ -3369,7 +3482,7 @@
|
|
|
3369
3482
|
? model.context.has(x.id)
|
|
3370
3483
|
? 1
|
|
3371
3484
|
: -1
|
|
3372
|
-
:
|
|
3485
|
+
: byGapOrder(x, y),
|
|
3373
3486
|
);
|
|
3374
3487
|
const cols = Math.max(
|
|
3375
3488
|
1,
|