project-spec 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +62 -325
- package/bin/project-spec.mjs +6 -2
- package/package.json +1 -1
- package/skills/project-knowledge/SKILL.md +27 -8
- package/skills/project-knowledge/assets/viewer.html +236 -62
- package/skills/project-knowledge/references/format.md +10 -5
- package/skills/project-knowledge/references/gaps.md +1 -1
- package/skills/project-knowledge/scripts/coverage.py +200 -0
- package/skills/project-knowledge/scripts/knowledge.py +62 -19
- package/skills/project-knowledge/scripts/test_coverage.py +128 -0
- package/skills/project-knowledge/scripts/test_knowledge.py +75 -0
- package/skills/spec-change/references/gaps.md +1 -1
|
@@ -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 {
|
|
@@ -243,8 +247,8 @@
|
|
|
243
247
|
background: var(--paper);
|
|
244
248
|
}
|
|
245
249
|
.icon-btn {
|
|
246
|
-
width:
|
|
247
|
-
height:
|
|
250
|
+
width: 36px;
|
|
251
|
+
height: 36px;
|
|
248
252
|
display: grid;
|
|
249
253
|
place-items: center;
|
|
250
254
|
border: 1px solid var(--line-strong);
|
|
@@ -306,11 +310,11 @@
|
|
|
306
310
|
font-weight: 600;
|
|
307
311
|
}
|
|
308
312
|
.btn {
|
|
309
|
-
height:
|
|
313
|
+
height: 36px;
|
|
310
314
|
display: inline-flex;
|
|
311
315
|
align-items: center;
|
|
312
316
|
gap: 8px;
|
|
313
|
-
padding: 0
|
|
317
|
+
padding: 0 14px;
|
|
314
318
|
border: 1px solid var(--line-strong);
|
|
315
319
|
border-radius: 999px;
|
|
316
320
|
background: var(--paper);
|
|
@@ -326,9 +330,8 @@
|
|
|
326
330
|
background: var(--accent);
|
|
327
331
|
}
|
|
328
332
|
.btn.large {
|
|
329
|
-
height:
|
|
330
|
-
padding: 0
|
|
331
|
-
font-size: 15px;
|
|
333
|
+
height: 40px;
|
|
334
|
+
padding: 0 18px;
|
|
332
335
|
}
|
|
333
336
|
.pillrow {
|
|
334
337
|
display: flex;
|
|
@@ -336,15 +339,15 @@
|
|
|
336
339
|
gap: 8px;
|
|
337
340
|
}
|
|
338
341
|
.pill {
|
|
339
|
-
height:
|
|
342
|
+
height: 34px;
|
|
340
343
|
display: inline-flex;
|
|
341
344
|
align-items: center;
|
|
342
|
-
gap:
|
|
343
|
-
padding: 0
|
|
345
|
+
gap: 7px;
|
|
346
|
+
padding: 0 13px;
|
|
344
347
|
border: 1px solid var(--line-strong);
|
|
345
348
|
border-radius: 999px;
|
|
346
349
|
background: var(--paper);
|
|
347
|
-
font: 600
|
|
350
|
+
font: 600 13px/1 var(--sans);
|
|
348
351
|
}
|
|
349
352
|
.pill[aria-pressed="true"] {
|
|
350
353
|
border-color: var(--ink);
|
|
@@ -356,12 +359,25 @@
|
|
|
356
359
|
opacity: 0.75;
|
|
357
360
|
}
|
|
358
361
|
select {
|
|
359
|
-
height:
|
|
360
|
-
padding: 0
|
|
362
|
+
height: 34px;
|
|
363
|
+
padding: 0 12px;
|
|
361
364
|
border: 1px solid var(--line-strong);
|
|
362
365
|
border-radius: 999px;
|
|
363
366
|
background: var(--paper);
|
|
364
|
-
font-size:
|
|
367
|
+
font-size: 13px;
|
|
368
|
+
}
|
|
369
|
+
/* A finger needs more room than a mouse pointer. */
|
|
370
|
+
@media (pointer: coarse) {
|
|
371
|
+
.btn,
|
|
372
|
+
.pill,
|
|
373
|
+
select {
|
|
374
|
+
height: 44px;
|
|
375
|
+
}
|
|
376
|
+
.icon-btn,
|
|
377
|
+
.xbtn {
|
|
378
|
+
width: 44px;
|
|
379
|
+
height: 44px;
|
|
380
|
+
}
|
|
365
381
|
}
|
|
366
382
|
|
|
367
383
|
/* Page */
|
|
@@ -417,6 +433,48 @@
|
|
|
417
433
|
gap: 24px;
|
|
418
434
|
max-width: 860px;
|
|
419
435
|
}
|
|
436
|
+
.stack.wide {
|
|
437
|
+
max-width: 1100px;
|
|
438
|
+
}
|
|
439
|
+
.area-grid {
|
|
440
|
+
display: grid;
|
|
441
|
+
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
|
|
442
|
+
gap: 16px;
|
|
443
|
+
}
|
|
444
|
+
.area-card h2 button {
|
|
445
|
+
border: 0;
|
|
446
|
+
padding: 0;
|
|
447
|
+
background: none;
|
|
448
|
+
font: inherit;
|
|
449
|
+
text-align: left;
|
|
450
|
+
}
|
|
451
|
+
.area-card h2 button:hover {
|
|
452
|
+
text-decoration: underline;
|
|
453
|
+
}
|
|
454
|
+
.area-card .names {
|
|
455
|
+
display: flex;
|
|
456
|
+
flex-direction: column;
|
|
457
|
+
gap: 6px;
|
|
458
|
+
margin-top: 4px;
|
|
459
|
+
}
|
|
460
|
+
.area-card .names button {
|
|
461
|
+
border: 0;
|
|
462
|
+
padding: 0;
|
|
463
|
+
background: none;
|
|
464
|
+
font-size: 14px;
|
|
465
|
+
text-align: left;
|
|
466
|
+
overflow: hidden;
|
|
467
|
+
text-overflow: ellipsis;
|
|
468
|
+
white-space: nowrap;
|
|
469
|
+
}
|
|
470
|
+
.area-card .names button:hover {
|
|
471
|
+
color: var(--accent-ink);
|
|
472
|
+
text-decoration: underline;
|
|
473
|
+
}
|
|
474
|
+
.area-card .names button.more {
|
|
475
|
+
color: var(--muted);
|
|
476
|
+
font-size: 13px;
|
|
477
|
+
}
|
|
420
478
|
.page {
|
|
421
479
|
display: flex;
|
|
422
480
|
flex-wrap: wrap;
|
|
@@ -486,20 +544,20 @@
|
|
|
486
544
|
.badge {
|
|
487
545
|
display: inline-flex;
|
|
488
546
|
align-items: center;
|
|
489
|
-
gap:
|
|
490
|
-
min-height:
|
|
491
|
-
padding: 0
|
|
547
|
+
gap: 6px;
|
|
548
|
+
min-height: 24px;
|
|
549
|
+
padding: 0 10px;
|
|
492
550
|
border-radius: 999px;
|
|
493
551
|
background: var(--soft);
|
|
494
552
|
color: var(--ink);
|
|
495
|
-
font-size:
|
|
553
|
+
font-size: 12px;
|
|
496
554
|
font-weight: 600;
|
|
497
555
|
white-space: nowrap;
|
|
498
556
|
}
|
|
499
557
|
.badge::before {
|
|
500
558
|
content: "";
|
|
501
|
-
width:
|
|
502
|
-
height:
|
|
559
|
+
width: 6px;
|
|
560
|
+
height: 6px;
|
|
503
561
|
border-radius: 999px;
|
|
504
562
|
background: var(--subtle);
|
|
505
563
|
}
|
|
@@ -542,10 +600,10 @@
|
|
|
542
600
|
gap: 8px;
|
|
543
601
|
}
|
|
544
602
|
.chip {
|
|
545
|
-
min-height:
|
|
603
|
+
min-height: 32px;
|
|
546
604
|
display: inline-flex;
|
|
547
605
|
align-items: center;
|
|
548
|
-
padding:
|
|
606
|
+
padding: 4px 13px;
|
|
549
607
|
border: 1px solid var(--line);
|
|
550
608
|
border-radius: 999px;
|
|
551
609
|
background: var(--paper);
|
|
@@ -893,8 +951,8 @@
|
|
|
893
951
|
}
|
|
894
952
|
.xbtn {
|
|
895
953
|
flex: none;
|
|
896
|
-
width:
|
|
897
|
-
height:
|
|
954
|
+
width: 36px;
|
|
955
|
+
height: 36px;
|
|
898
956
|
display: grid;
|
|
899
957
|
place-items: center;
|
|
900
958
|
border: 0;
|
|
@@ -1277,7 +1335,7 @@
|
|
|
1277
1335
|
min-height: 32px;
|
|
1278
1336
|
}
|
|
1279
1337
|
.copy-card .btn {
|
|
1280
|
-
height:
|
|
1338
|
+
height: 36px;
|
|
1281
1339
|
}
|
|
1282
1340
|
@media (max-width: 820px) {
|
|
1283
1341
|
.copy-card {
|
|
@@ -1675,6 +1733,20 @@
|
|
|
1675
1733
|
const i = STATES.indexOf(stateOf(n));
|
|
1676
1734
|
return i < 0 ? STATES.length : i;
|
|
1677
1735
|
};
|
|
1736
|
+
// Priority is free text. The usual words and P0-P4 sort from most to least urgent, any other
|
|
1737
|
+
// value after them, and a gap without a priority last.
|
|
1738
|
+
const PRIORITY_RANKS = { critical: 0, urgent: 0, highest: 0, high: 1, medium: 2, normal: 2, low: 3, lowest: 4 };
|
|
1739
|
+
const priorityOf = (n) => str(n.priority).trim().toLowerCase();
|
|
1740
|
+
const priorityRank = (n) => {
|
|
1741
|
+
const p = priorityOf(n),
|
|
1742
|
+
digit = /^p?([0-4])$/.exec(p);
|
|
1743
|
+
if (!p) return 6;
|
|
1744
|
+
if (digit) return +digit[1];
|
|
1745
|
+
return Object.prototype.hasOwnProperty.call(PRIORITY_RANKS, p) ? PRIORITY_RANKS[p] : 5;
|
|
1746
|
+
};
|
|
1747
|
+
// The order of every list of gaps: by state, then the most urgent first, then by title.
|
|
1748
|
+
const byGapOrder = (a, b) =>
|
|
1749
|
+
stateRank(a) - stateRank(b) || priorityRank(a) - priorityRank(b) || byTitle(a, b);
|
|
1678
1750
|
const stateClass = (n) =>
|
|
1679
1751
|
isGap(n)
|
|
1680
1752
|
? "st-" + stateOf(n)
|
|
@@ -2181,7 +2253,7 @@
|
|
|
2181
2253
|
if (g && isGap(g)) out.set(g.id, g);
|
|
2182
2254
|
});
|
|
2183
2255
|
return [...out.values()].sort(
|
|
2184
|
-
|
|
2256
|
+
byGapOrder,
|
|
2185
2257
|
);
|
|
2186
2258
|
}
|
|
2187
2259
|
const planOf = (g) => nodes.find((p) => isPlan(p) && p.gap === g.id);
|
|
@@ -2256,11 +2328,18 @@
|
|
|
2256
2328
|
}
|
|
2257
2329
|
const primaryArea = (n) => (n.areas || [])[0] || "";
|
|
2258
2330
|
const isFeature = (n) => n.type === "note" && n.status !== "superseded";
|
|
2331
|
+
// A part of a feature: a note whose `parent` names another note. One level only, so the tree is
|
|
2332
|
+
// area, feature, part; a parent that is missing or is itself a part is ignored.
|
|
2333
|
+
const parentOf = (n) => {
|
|
2334
|
+
const p = n.type === "note" && str(n.parent) ? byId.get(n.parent) : null;
|
|
2335
|
+
return p && p !== n && isFeature(p) && !str(p.parent) ? p : null;
|
|
2336
|
+
};
|
|
2337
|
+
const partsOf = (n) => nodes.filter((p) => isFeature(p) && parentOf(p) === n).sort(byTitle);
|
|
2259
2338
|
const featuresOf = (area) =>
|
|
2260
|
-
nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id).sort(byTitle);
|
|
2339
|
+
nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id && !parentOf(n)).sort(byTitle);
|
|
2261
2340
|
const looseFeatures = () =>
|
|
2262
2341
|
nodes
|
|
2263
|
-
.filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area")
|
|
2342
|
+
.filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area" && !parentOf(n))
|
|
2264
2343
|
.sort(byTitle);
|
|
2265
2344
|
const waiting = (n) =>
|
|
2266
2345
|
gapsAbout(n).filter((g) =>
|
|
@@ -2374,15 +2453,23 @@
|
|
|
2374
2453
|
});
|
|
2375
2454
|
const tree = $("#tree");
|
|
2376
2455
|
tree.replaceChildren();
|
|
2377
|
-
const noteRow = (f) => {
|
|
2378
|
-
const b = button(null, "tree-row note", () => openNode(f)),
|
|
2379
|
-
open = waiting(f).length
|
|
2456
|
+
const noteRow = (f, cls, folded) => {
|
|
2457
|
+
const b = button(null, "tree-row note" + (cls ? " " + cls : ""), () => openNode(f)),
|
|
2458
|
+
open = waiting(f).length,
|
|
2459
|
+
meta = [open && open + " open", folded && plural(folded, "part")].filter(Boolean).join(" · ");
|
|
2380
2460
|
b.append(el("span", f.title, "label"));
|
|
2381
2461
|
b.title = f.title; // the row shows one line; the full name is a hover away
|
|
2382
|
-
if (
|
|
2462
|
+
if (meta) b.append(el("span", meta, "meta"));
|
|
2383
2463
|
b.setAttribute("aria-current", selected === f ? "page" : "false");
|
|
2384
2464
|
return b;
|
|
2385
2465
|
};
|
|
2466
|
+
// A feature's parts are listed under it while the reader is on the feature or on one of them.
|
|
2467
|
+
const featureRows = (f) => {
|
|
2468
|
+
const parts = partsOf(f),
|
|
2469
|
+
unfolded = parts.length && (selected === f || parts.includes(selected));
|
|
2470
|
+
tree.append(noteRow(f, "", unfolded ? 0 : parts.length));
|
|
2471
|
+
if (unfolded) parts.forEach((p) => tree.append(noteRow(p, "part")));
|
|
2472
|
+
};
|
|
2386
2473
|
areas.forEach((a) => {
|
|
2387
2474
|
const open = openAreas.has(a.id),
|
|
2388
2475
|
line = el("div", null, "tree-area"),
|
|
@@ -2403,12 +2490,12 @@
|
|
|
2403
2490
|
name.setAttribute("aria-current", selected === a ? "page" : "false");
|
|
2404
2491
|
line.append(twist, name);
|
|
2405
2492
|
tree.append(line);
|
|
2406
|
-
if (open) featuresOf(a).forEach(
|
|
2493
|
+
if (open) featuresOf(a).forEach(featureRows);
|
|
2407
2494
|
});
|
|
2408
2495
|
const loose = looseFeatures();
|
|
2409
2496
|
if (loose.length) {
|
|
2410
2497
|
tree.append(el("div", "Other", "eyebrow"));
|
|
2411
|
-
loose.forEach(
|
|
2498
|
+
loose.forEach(featureRows);
|
|
2412
2499
|
}
|
|
2413
2500
|
if (!areas.length && !loose.length) tree.append(el("p", "No pages yet.", "empty"));
|
|
2414
2501
|
}
|
|
@@ -2424,6 +2511,7 @@
|
|
|
2424
2511
|
if (n) {
|
|
2425
2512
|
const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
|
|
2426
2513
|
if (parent && parent.type === "area") parts.push([parent.title, { name: "page", id: parent.id }]);
|
|
2514
|
+
if (parentOf(n)) parts.push([parentOf(n).title, { name: "page", id: parentOf(n).id }]);
|
|
2427
2515
|
if (isGap(n) || isPlan(n)) parts.push(["Gaps", { name: "gaps", id: "" }]);
|
|
2428
2516
|
if (isPlan(n) && byId.get(n.gap)) parts.push([byId.get(n.gap).title, { name: "page", id: n.gap }]);
|
|
2429
2517
|
parts.push([n.title, null]);
|
|
@@ -2478,6 +2566,16 @@
|
|
|
2478
2566
|
open = waiting(f).length;
|
|
2479
2567
|
item.append(button(f.title, "rowlink", () => openNode(f)));
|
|
2480
2568
|
if (str(f.summary).trim()) item.append(el("p", f.summary, "muted"));
|
|
2569
|
+
const parts = partsOf(f);
|
|
2570
|
+
if (parts.length) {
|
|
2571
|
+
const line = el("p", null, "muted small parts");
|
|
2572
|
+
line.append(el("span", plural(parts.length, "part") + ": "));
|
|
2573
|
+
parts.forEach((part, i) => {
|
|
2574
|
+
if (i) line.append(document.createTextNode(", "));
|
|
2575
|
+
line.append(button(part.title, "wiki", () => openNode(part)));
|
|
2576
|
+
});
|
|
2577
|
+
item.append(line);
|
|
2578
|
+
}
|
|
2481
2579
|
if (open) item.append(el("span", plural(open, "open question"), "muted small"));
|
|
2482
2580
|
box.append(item);
|
|
2483
2581
|
});
|
|
@@ -2510,18 +2608,38 @@
|
|
|
2510
2608
|
};
|
|
2511
2609
|
|
|
2512
2610
|
// --- Views ---------------------------------------------------------------------------------------
|
|
2611
|
+
// The overview is a map of the areas, not every feature of every area: a card says what the area
|
|
2612
|
+
// covers, how much is in it and names a few features; the area's own page has the full list.
|
|
2613
|
+
const HOME_NAMES = 5;
|
|
2614
|
+
function areaCard(a) {
|
|
2615
|
+
const card = el("section", null, "card pad area-card"),
|
|
2616
|
+
h = el("h2", null, "h2"),
|
|
2617
|
+
features = featuresOf(a),
|
|
2618
|
+
count = nodes.filter((n) => isFeature(n) && primaryArea(n) === a.id).length,
|
|
2619
|
+
open = nodes.filter((g) => isGap(g) && inArea(g, a.id) && ["needs-recheck", "needs-decision"].includes(stateOf(g))).length;
|
|
2620
|
+
h.append(button(a.title, null, () => openNode(a)));
|
|
2621
|
+
card.append(h);
|
|
2622
|
+
if (str(a.summary).trim()) card.append(el("p", a.summary, "muted"));
|
|
2623
|
+
card.append(el("p", [plural(count, "page"), open && plural(open, "open question")].filter(Boolean).join(" · "), "muted small"));
|
|
2624
|
+
const names = el("div", null, "names");
|
|
2625
|
+
features.slice(0, HOME_NAMES).forEach((f) => {
|
|
2626
|
+
const b = button(f.title, null, () => openNode(f));
|
|
2627
|
+
b.title = f.title;
|
|
2628
|
+
names.append(b);
|
|
2629
|
+
});
|
|
2630
|
+
if (features.length > HOME_NAMES)
|
|
2631
|
+
names.append(button("All " + features.length + " features", "more", () => openNode(a)));
|
|
2632
|
+
if (features.length) card.append(names);
|
|
2633
|
+
return card;
|
|
2634
|
+
}
|
|
2513
2635
|
function viewHome(view) {
|
|
2514
|
-
const box = el("div", null, "stack");
|
|
2636
|
+
const box = el("div", null, "stack wide");
|
|
2515
2637
|
box.append(header("Overview", projectTitle, "What the product does today, area by area."));
|
|
2516
|
-
areas.
|
|
2517
|
-
const
|
|
2518
|
-
|
|
2519
|
-
|
|
2520
|
-
|
|
2521
|
-
if (str(a.summary).trim()) section.append(el("p", a.summary, "muted"));
|
|
2522
|
-
section.append(featureList(featuresOf(a)));
|
|
2523
|
-
box.append(section);
|
|
2524
|
-
});
|
|
2638
|
+
if (areas.length) {
|
|
2639
|
+
const grid = el("div", null, "area-grid");
|
|
2640
|
+
areas.forEach((a) => grid.append(areaCard(a)));
|
|
2641
|
+
box.append(grid);
|
|
2642
|
+
}
|
|
2525
2643
|
const loose = looseFeatures();
|
|
2526
2644
|
if (loose.length) {
|
|
2527
2645
|
const section = el("section");
|
|
@@ -2541,6 +2659,8 @@
|
|
|
2541
2659
|
path.append(button(projectTitle, null, () => go({ name: "home", id: "" })));
|
|
2542
2660
|
const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
|
|
2543
2661
|
if (parent && parent.type === "area") path.append(button(parent.title, null, () => openNode(parent)));
|
|
2662
|
+
const feature = parentOf(n);
|
|
2663
|
+
if (feature) path.append(button(feature.title, null, () => openNode(feature)));
|
|
2544
2664
|
if (isGap(n) || isPlan(n)) path.append(button("Gaps", null, () => go({ name: "gaps", id: "" })));
|
|
2545
2665
|
path.append(el("span", n.title, "now"));
|
|
2546
2666
|
card.append(path);
|
|
@@ -2551,7 +2671,7 @@
|
|
|
2551
2671
|
// Pages this one links to or is linked from: a short list beside the text, not a block inside it.
|
|
2552
2672
|
if (layerOf(n) === "spec") {
|
|
2553
2673
|
const related = neighbours(n, "spec").filter(
|
|
2554
|
-
(r) => r.id !== parent?.id && !(n.type === "area" && primaryArea(r) === n.id),
|
|
2674
|
+
(r) => r.id !== parent?.id && r !== feature && !(n.type === "area" && primaryArea(r) === n.id),
|
|
2555
2675
|
);
|
|
2556
2676
|
if (related.length) {
|
|
2557
2677
|
const list = el("div", null, "recent"),
|
|
@@ -2572,6 +2692,22 @@
|
|
|
2572
2692
|
box.append(list);
|
|
2573
2693
|
}
|
|
2574
2694
|
}
|
|
2695
|
+
// A gap is a question about something: the features it links to, then its areas.
|
|
2696
|
+
if (isGap(n)) {
|
|
2697
|
+
const about = neighbours(n, "spec"),
|
|
2698
|
+
own = (n.areas || []).map((id) => byId.get(id)).filter((a) => a && a.type === "area"),
|
|
2699
|
+
pages = [...new Set([...about.filter((r) => r.type === "note"), ...about.filter((r) => r.type !== "note"), ...own])];
|
|
2700
|
+
if (pages.length) {
|
|
2701
|
+
const list = el("div", null, "recent");
|
|
2702
|
+
list.append(el("div", "This gap is about", "mono-label"));
|
|
2703
|
+
pages.forEach((r) => {
|
|
2704
|
+
const b = button(r.title, null, () => openNode(r));
|
|
2705
|
+
if (r.type !== "note") b.append(el("span", " · area", "muted"));
|
|
2706
|
+
list.append(b);
|
|
2707
|
+
});
|
|
2708
|
+
box.append(list);
|
|
2709
|
+
}
|
|
2710
|
+
}
|
|
2575
2711
|
const others = recent.filter((id) => id !== n.id).slice(0, 5);
|
|
2576
2712
|
if (others.length) {
|
|
2577
2713
|
const list = el("div", null, "recent");
|
|
@@ -2614,13 +2750,8 @@
|
|
|
2614
2750
|
|
|
2615
2751
|
if (isGap(n)) {
|
|
2616
2752
|
main.append(gapHeader(n));
|
|
2617
|
-
|
|
2618
|
-
|
|
2619
|
-
if (refs.length) {
|
|
2620
|
-
const chips = el("div", null, "chips");
|
|
2621
|
-
refs.forEach((r) => chips.append(button(r.title, "chip", () => openNode(r))));
|
|
2622
|
-
main.append(el("div", "Refers to", "mono-label"), chips);
|
|
2623
|
-
}
|
|
2753
|
+
// The pages the gap is about are listed beside the text ("This gap is about"), as on spec pages.
|
|
2754
|
+
const plan = planOf(n);
|
|
2624
2755
|
if (plan)
|
|
2625
2756
|
main.append(
|
|
2626
2757
|
linkBlock("Plan", [
|
|
@@ -2686,7 +2817,8 @@
|
|
|
2686
2817
|
|
|
2687
2818
|
let gapState = "all",
|
|
2688
2819
|
gapArea = "",
|
|
2689
|
-
gapKind = ""
|
|
2820
|
+
gapKind = "",
|
|
2821
|
+
gapPriority = ""; // "" for all, "none" for gaps without one, otherwise the value
|
|
2690
2822
|
const selectOf = (label, options, value, pick) => {
|
|
2691
2823
|
const s = el("select");
|
|
2692
2824
|
s.setAttribute("aria-label", label);
|
|
@@ -2708,7 +2840,11 @@
|
|
|
2708
2840
|
head.title = "Questions about what is missing, unverified or could be added. Each one is rechecked and then decided by a person.";
|
|
2709
2841
|
box.append(head);
|
|
2710
2842
|
const pool = nodes.filter(
|
|
2711
|
-
(n) =>
|
|
2843
|
+
(n) =>
|
|
2844
|
+
isGap(n) &&
|
|
2845
|
+
inArea(n, gapArea) &&
|
|
2846
|
+
(!gapKind || n.kind === gapKind) &&
|
|
2847
|
+
(!gapPriority || (priorityOf(n) || "none") === gapPriority),
|
|
2712
2848
|
),
|
|
2713
2849
|
again = () => show();
|
|
2714
2850
|
head.append(
|
|
@@ -2743,9 +2879,29 @@
|
|
|
2743
2879
|
again();
|
|
2744
2880
|
}),
|
|
2745
2881
|
);
|
|
2882
|
+
// Only the priorities the queue has, most urgent first; nothing to pick when no gap has one.
|
|
2883
|
+
const priorities = [...new Set(nodes.filter(isGap).map(priorityOf).filter(Boolean))].sort(
|
|
2884
|
+
(a, b) => priorityRank({ priority: a }) - priorityRank({ priority: b }) || a.localeCompare(b),
|
|
2885
|
+
);
|
|
2886
|
+
if (priorities.length || gapPriority)
|
|
2887
|
+
head.append(
|
|
2888
|
+
selectOf(
|
|
2889
|
+
"Priority",
|
|
2890
|
+
[
|
|
2891
|
+
["", "All priorities"],
|
|
2892
|
+
...priorities.map((p) => [p, p[0].toUpperCase() + p.slice(1) + " priority"]),
|
|
2893
|
+
["none", "No priority"],
|
|
2894
|
+
],
|
|
2895
|
+
gapPriority,
|
|
2896
|
+
(v) => {
|
|
2897
|
+
gapPriority = v;
|
|
2898
|
+
again();
|
|
2899
|
+
},
|
|
2900
|
+
),
|
|
2901
|
+
);
|
|
2746
2902
|
const shown = pool
|
|
2747
2903
|
.filter((g) => gapState === "all" || stateOf(g) === gapState)
|
|
2748
|
-
.sort(
|
|
2904
|
+
.sort(byGapOrder);
|
|
2749
2905
|
if (shown.length) {
|
|
2750
2906
|
const card = el("section", null, "card");
|
|
2751
2907
|
card.id = "gap-list";
|
|
@@ -2777,7 +2933,7 @@
|
|
|
2777
2933
|
}),
|
|
2778
2934
|
);
|
|
2779
2935
|
const shown = gaps
|
|
2780
|
-
? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort(
|
|
2936
|
+
? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort(byGapOrder)
|
|
2781
2937
|
: nodes.filter((n) => layerOf(n) === "spec" && inArea(n, mapArea));
|
|
2782
2938
|
draw(graphModel(shown), false);
|
|
2783
2939
|
}
|
|
@@ -3411,7 +3567,7 @@
|
|
|
3411
3567
|
? model.context.has(x.id)
|
|
3412
3568
|
? 1
|
|
3413
3569
|
: -1
|
|
3414
|
-
:
|
|
3570
|
+
: byGapOrder(x, y),
|
|
3415
3571
|
);
|
|
3416
3572
|
const cols = Math.max(
|
|
3417
3573
|
1,
|
|
@@ -3576,15 +3732,33 @@
|
|
|
3576
3732
|
function applyBox() {
|
|
3577
3733
|
graph.setAttribute("viewBox", `${box.x} ${box.y} ${box.w} ${box.h}`);
|
|
3578
3734
|
}
|
|
3579
|
-
|
|
3580
|
-
|
|
3581
|
-
|
|
3582
|
-
|
|
3583
|
-
|
|
3735
|
+
// f below 1 zooms in. (cx, cy) is the point of the map that stays where it is, as a share of the
|
|
3736
|
+
// view: the middle for the buttons, the pointer for the wheel. Zoom stops at 8x in and 4x out.
|
|
3737
|
+
function zoom(f, cx = 0.5, cy = 0.5) {
|
|
3738
|
+
const w = Math.min(Math.max(box.w * f, initialBox.w / 8), initialBox.w * 4),
|
|
3739
|
+
k = w / box.w,
|
|
3740
|
+
h = box.h * k;
|
|
3741
|
+
box.x += (box.w - w) * cx;
|
|
3742
|
+
box.y += (box.h - h) * cy;
|
|
3584
3743
|
box.w = w;
|
|
3585
3744
|
box.h = h;
|
|
3586
3745
|
applyBox();
|
|
3587
3746
|
}
|
|
3747
|
+
graph.addEventListener(
|
|
3748
|
+
"wheel",
|
|
3749
|
+
(e) => {
|
|
3750
|
+
if (!e.deltaY) return;
|
|
3751
|
+
e.preventDefault(); // the map takes the wheel; the page beside it still scrolls
|
|
3752
|
+
const rect = graph.getBoundingClientRect(),
|
|
3753
|
+
share = (v, size) => (size ? Math.min(Math.max(v / size, 0), 1) : 0.5);
|
|
3754
|
+
zoom(
|
|
3755
|
+
Math.exp(Math.max(-60, Math.min(60, e.deltaY)) * 0.004),
|
|
3756
|
+
share(e.clientX - rect.left, rect.width),
|
|
3757
|
+
share(e.clientY - rect.top, rect.height),
|
|
3758
|
+
);
|
|
3759
|
+
},
|
|
3760
|
+
{ passive: false },
|
|
3761
|
+
);
|
|
3588
3762
|
$("#zoom-in").addEventListener("click", () => zoom(0.8));
|
|
3589
3763
|
$("#zoom-out").addEventListener("click", () => zoom(1.25));
|
|
3590
3764
|
$("#reset").addEventListener("click", () => {
|
|
@@ -54,8 +54,8 @@ Required on every page: `id`, `title`, `type`, `areas`, `sources`, `updated`. `s
|
|
|
54
54
|
|
|
55
55
|
- `id`: unique stable ASCII slug (`[a-z0-9-]+`).
|
|
56
56
|
- `status` on `area` and `note`: `current`, `partial`, `stale`, `superseded`. On `index`, `run` and `plan` additionally `planned`.
|
|
57
|
-
- `current`: checked against the current sources. This is not a runtime test or a deployment claim; say in prose which version and environment you checked.
|
|
58
|
-
- `partial`:
|
|
57
|
+
- `current`: the whole feature was read and the page checked against the current sources. This is not a runtime test or a deployment claim; say in prose which version and environment you checked.
|
|
58
|
+
- `partial`: some of the feature or area was not read. The page ends with a line saying what is left, and stays `partial` until the feature is finished.
|
|
59
59
|
- `stale`: its sources changed or disappeared and it has not been re-read.
|
|
60
60
|
- `superseded`: replaced by another page, kept as a pointer.
|
|
61
61
|
- `planned` (index, run, plan): describes intent not yet carried out.
|
|
@@ -63,6 +63,7 @@ Required on every page: `id`, `title`, `type`, `areas`, `sources`, `updated`. `s
|
|
|
63
63
|
- `areas`: existing **area IDs**. Each `note`, `gap` and `plan` needs at least one. Area pages may list themselves or leave empty; index and run pages may be empty.
|
|
64
64
|
- `sources`: existing files read as evidence, repository-relative; no directories, credentials, absolute paths or paths escaping the repo. A `current` note needs evidence; gaps, plans and maps may have none.
|
|
65
65
|
- `updated`: last substantive review date (`YYYY-MM-DD`).
|
|
66
|
+
- Optional `parent`, on a `note` only: the `id` of the feature note this note is a part of. The vault has three levels: area, feature, part. The parent is a note of the same first area that has no `parent` itself, and its body links to each of its parts; `check` rejects anything else. The viewer lists a part under its feature.
|
|
66
67
|
- Optional `tags`, `aliases`, `task_ids`: string arrays. Optional `summary` and `verification`: strings. An area's `summary` introduces it in the viewer; a note's `summary` is its plain-language statement of what the product does, shown first in the viewer's Read view (write one for every note; `check` does not require it, so older vaults still open).
|
|
67
68
|
|
|
68
69
|
Gap-only properties are errors on any other page type, `gap` is an error on a page that is not a plan, and `priority` and `confidence` are allowed only on gap and plan pages. String properties (and strings inside arrays) may not contain control characters, including line separators. Gap-only properties (`kind`, `recheck`, `rechecked_by`, `rechecked_on`, `decision`, `decided_by`, `decided_on`, `duplicate_of`, optional `priority`, `confidence`) and the plan-only `gap` property are defined in [gaps.md](gaps.md), with the rules for who may set each. Gap state (`needs-recheck`, `needs-decision`, or the decision value) is derived from them and never written into Markdown. A recheck has one meaning for every gap kind: does the `Current behavior` section still describe the code? `confirmed` means it does (confirmed, still holds; for a proposal, the capability is still absent) and `not-reproduced` means it no longer does; neither judges whether a proposal is worth doing, which is a person's decision (see [what a recheck means](gaps.md#what-a-recheck-means)). `recheck: "outdated"` means the cited sources changed after the last recorded recheck; `rechecked_by` and `rechecked_on` stay, the `Recheck` section must have text, and an open gap with it is `needs-recheck`.
|
|
@@ -81,8 +82,10 @@ A **feature note** is the one page for one screen, feature, flow or rule, and al
|
|
|
81
82
|
| Flow | `## How it works` | What a person does and what happens, in order. Left out when there is no flow. |
|
|
82
83
|
| Fields | `## Fields` | One row per field of the feature's form: `Field`, `Required`, `Rule`, `Message when refused`. |
|
|
83
84
|
| Rules | `## Business rules` | One numbered rule per row: `ID`, `Rule`. Who may do it, when an action is available, limits, defaults, what is kept, sent or deleted, and when. |
|
|
85
|
+
| Clients | `## Where the apps differ` | Only when the product has several clients: one row per difference, `What` and a column per client (`Web`, `Mobile`). One sentence instead when they were compared and do not differ. |
|
|
86
|
+
| Parts | `## Parts` | Only on a feature that has parts: a link to each part and one line saying what it covers. |
|
|
84
87
|
|
|
85
|
-
The headings are written exactly so and come in this order; a section the feature does not have is left out. A field's rule is in `Fields` and is not repeated in `Business rules`. Usually 150-400 words
|
|
88
|
+
The headings are written exactly so and come in this order; a section the feature does not have is left out. A field's rule is in `Fields` and is not repeated in `Business rules`. Usually 150-400 words and up to about twenty rules. A feature that needs more gets parts: notes with `parent` set to the feature note, each about one flow or one kind of use, never one kind of fact, and each written in this same shape. The feature note then holds what the feature is for, how the parts fit, the rules that hold in every part, and `## Parts`.
|
|
86
89
|
|
|
87
90
|
A rule is numbered `BR-<FEATURE>-<NN>` (`BR-INVITE-03`): `BR`, a short upper-case word for the feature that is the same in all rules of the note and used by no other note, and a number from 01. The number is the rule's name, quoted in tickets, tests and gaps. A rule keeps it when its text changes; a new rule takes the next free number; the number of a removed rule is not used again; rules are never renumbered. One rule per row, one or two sentences, with the value.
|
|
88
91
|
|
|
@@ -164,7 +167,9 @@ The validator enforces these body rules:
|
|
|
164
167
|
|
|
165
168
|
## Helper
|
|
166
169
|
|
|
167
|
-
|
|
170
|
+
Four scripts in `$SKILL_DIR/scripts/`; see [SKILL.md](../SKILL.md) for the variables.
|
|
171
|
+
|
|
172
|
+
`coverage.py --repo PATH [--vault PATH] [--path FOLDER]... [--all]` reads the repository's code files and the spec pages (`area` and `note`) and prints what the code has that no page mentions. It writes nothing and always exits 0. Code files are the tracked and the untracked-but-not-ignored files with a source-code extension, outside the vault, without tests, fixtures, stories, mocks, migrations, dependencies and build output. For each folder it prints the number of files and lines, how many of the files a page cites in `sources`, how many **sentences a person can see** the folder has and how many are on no page, and the same for **named numbers**. A sentence is a string or text between tags of 12 to 200 characters that starts with a capital letter and has at least three words, outside log calls; it is on a page when a page contains it, ignoring case, curly quotes and spacing. A named number is an upper-case constant set to a number (`MAX_FILES = 10`); it is on a page when a page contains its name. A file with 40 or more sentences is an article or a template and counts as a file only. A folder in which no page cites any file is one line however deep it goes; folders are ordered by how much they have that no page mentions. With `--path` only those folders are read and every unmentioned sentence and number is listed with its file, then the largest files no page cites. The first 40 folders and 60 items are printed unless `--all` is given. The report finds places to read; it cannot find a rule that has neither a message nor a named number.
|
|
168
173
|
|
|
169
174
|
`knowledge.py {check,snapshot,serve,build} --repo PATH [--vault PATH]`
|
|
170
175
|
|
|
@@ -204,7 +209,7 @@ Canonical Markdown must not contain raw merge conflicts. Validation rejects comp
|
|
|
204
209
|
|
|
205
210
|
`serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the single vault under `knowledge/` (`knowledge/00-index.md` or `knowledge/*/00-index.md`) and stop with a message when there is none or several. It listens on `127.0.0.1` only (port 8757, or a free one when that is taken), answers only `/` and only when addressed as this machine, never writes, and builds the page again from disk on every request, so a reload shows the current files. When the vault has errors the page lists them. The page data is the graph above plus `live: true`, `vaultPath` (the vault's path relative to the repository), `history`, `pending` and `files`. `history` is the last 30 commits that touched vault pages (not `.knowledge/`), newest first, each `{"sha", "date", "subject", "pages", "more"}`; a page entry is `{"path", "status"}` with `status` `added`, `changed` or `removed`, plus `was` and `now` when the commit changed the page's `summary` (or, failing that, its `title`); at most 80 pages are listed per commit and `more` counts the rest. `pending` lists vault pages with uncommitted changes in the same `{"path", "status"}` shape. Both are empty outside a Git work tree. `files` is the text of the repository files that pages cite in `sources` or link to, keyed by repository-relative path, each `{"text", "truncated"}`. A file is included only when it is inside the repository and outside the vault, is not a credential path, and is UTF-8 text; one file is cut at 300,000 characters and all files together at 4,000,000, after which the rest stay ordinary links. The viewer opens a link to an included file in place: Markdown rendered, anything else as numbered lines, with the lines of a `#L10` or `#L10-L20` fragment marked.
|
|
206
211
|
|
|
207
|
-
`build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
|
|
212
|
+
`build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. `--allow-missing-sources` is for a build that sees only part of the repository (a Docker build context): a cited path where nothing exists is not an error and does not mark its page as changed, and the command lists those files; `check` and `snapshot` never accept it. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
|
|
208
213
|
|
|
209
214
|
`assets/viewer.html` has exactly one `__KNOWLEDGE_DATA__` placeholder for script-safe JSON. Treat contents as untrusted text: no raw Markdown HTML execution, unsafe URL schemes, external scripts, fonts, analytics or fetches. Render readable basic Markdown, pipe tables and wikilinks; leave unsupported syntax as text. The viewer has a tree of areas with their notes (a note is listed under its first area; superseded notes are not listed), a search over pages, gaps and the cited files, and five places: the overview, a page, the gap queue, the map and recent changes. A note shows its title, `summary`, the page text and the gaps about it that are not closed, then its source files folded; an area shows its notes with their summaries and folds its own text. The pages linked to or from the page are a short list beside it. Navigation keeps a trail for Back and Forward and writes the place into the address (`#/page/notes/example`, `#/gaps`), so a reload or a copied link returns to it. The map draws one frame per primary area (the area page, or the first entry of `areas`) with its pages inside; an edge between a page and its primary area is not drawn because the frame says it, links inside one area are solid and links across areas dashed; `nav` pages are not drawn. Recent changes reads `history`, `pending` and the "changed source" lines of `warnings`. "Copy for AI" only composes text from the page, a choice of what the agent should do and the reader's own words, and copies it to the clipboard. The reader's name, the recently viewed pages and the last commit seen are kept in the browser's `localStorage`, and the viewer works without it.
|
|
210
215
|
|
|
@@ -27,7 +27,7 @@ A gap must not have `status`; its progress is carried by `recheck` and `decision
|
|
|
27
27
|
| `decided_by` | when `decision` is `accepted`, `rejected` or `deferred` | a person's name; the value `agent` is an error |
|
|
28
28
|
| `decided_on` | when `decision` is `accepted`, `rejected` or `deferred` | `YYYY-MM-DD` |
|
|
29
29
|
| `duplicate_of` | when `decision` is `duplicate` | id of another existing gap (not itself) |
|
|
30
|
-
| `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"` |
|
|
30
|
+
| `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"`. Use `high`, `medium` or `low` for `priority` (or `P0` to `P4`): the viewer lists the most urgent gap of each state first and can show one priority only. |
|
|
31
31
|
|
|
32
32
|
`decided_by` and `decided_on` are also allowed on `done` and `duplicate` but not required. With `outdated`, `rechecked_by` and `rechecked_on` stay in place as the record of the last recheck actually done. A fresh recheck replaces all three fields and adds a new dated entry to the `Recheck` section; keep the older entries.
|
|
33
33
|
|