@skitterbyte/skitterspec-jira 2.7.0 → 2.8.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/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +16 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +40 -11
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +30 -13
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +134 -17
- package/src/env/config.js +47 -6
- package/src/env/epic.js +23 -8
- package/src/env/epicpage.js +4 -3
- package/src/env/epicread.js +39 -1
- package/src/env/integrate.js +48 -1
- package/src/env/project.js +18 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +17 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
package/src/env/config.js
CHANGED
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
*/
|
|
61
61
|
|
|
62
62
|
const { createHash } = require('node:crypto')
|
|
63
|
-
const { readFileSync, realpathSync } = require('node:fs')
|
|
63
|
+
const { existsSync, readFileSync, realpathSync } = require('node:fs')
|
|
64
64
|
const { join, resolve, sep } = require('node:path')
|
|
65
65
|
|
|
66
66
|
const CONFIG_FILE = join('specs', '.core', 'env.config.json')
|
|
@@ -230,9 +230,11 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
230
230
|
// follows the merge. `remote` names where the branch is pushed. `draft`
|
|
231
231
|
// opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
|
|
232
232
|
// downstream can close a ticket early). `specDocs` decides where a spec
|
|
233
|
-
// DOCUMENT lands
|
|
234
|
-
//
|
|
235
|
-
//
|
|
233
|
+
// DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
|
|
234
|
+
// docs under "pr"), "branch" has the spec ride its feature branch and land
|
|
235
|
+
// with the work. The "trunk" here is only the base's default — with a
|
|
236
|
+
// ticketing provider configured and the key unset, `applyProviderSpecDocs`
|
|
237
|
+
// makes it "branch", whatever the strategy.
|
|
236
238
|
land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
|
|
237
239
|
// `mainIsLandingZone` defaults ON wherever isolation is configured, matching
|
|
238
240
|
// the review gate's precedent: the push toward not working on the base branch
|
|
@@ -307,6 +309,10 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
307
309
|
allowRemote: false,
|
|
308
310
|
commitWith: '/commit',
|
|
309
311
|
required: true,
|
|
312
|
+
// The name every generated page carries in its tab and above its heading.
|
|
313
|
+
// Empty means "the project folder's name" (`projectName` in project.js) —
|
|
314
|
+
// the override exists for a checkout named `app` or `repo`.
|
|
315
|
+
projectName: '',
|
|
310
316
|
// External code reviewers whose findings render as CHECKS on the page.
|
|
311
317
|
// Empty by default and never written by `init`: configuring one sends the
|
|
312
318
|
// worktree's diff to whatever the command talks to, which is a decision
|
|
@@ -772,6 +778,8 @@ function mergeConfig(base, parsed) {
|
|
|
772
778
|
// here. There is nothing it could mean instead: the hand-off has no off
|
|
773
779
|
// switch, so a blank value is a typo rather than an instruction.
|
|
774
780
|
assign(base.review, parsed.review, 'commitWith', 'string')
|
|
781
|
+
// A blank name falls back to the folder's, like `commitWith` above.
|
|
782
|
+
assign(base.review, parsed.review, 'projectName', 'string')
|
|
775
783
|
// Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
|
|
776
784
|
// leaves the gate ON. Turning off a check that refuses must be something
|
|
777
785
|
// someone WROTE, never something a typo achieved on their behalf.
|
|
@@ -873,6 +881,33 @@ function applyProviderEnvDefaults(config, parsed) {
|
|
|
873
881
|
return config
|
|
874
882
|
}
|
|
875
883
|
|
|
884
|
+
// The provider's own config file, relative to the project root — set once per
|
|
885
|
+
// process by a provider superset's bin, like the defaults above. A registered
|
|
886
|
+
// file that EXISTS is the positive signal that a ticketing provider is attached
|
|
887
|
+
// to this project, and only then does `land.specDocs` default to "branch": the
|
|
888
|
+
// tracker is the backlog, so landing a spec document on the base branch just to
|
|
889
|
+
// make it findable buys nothing (feat-tracker-spec-branches).
|
|
890
|
+
//
|
|
891
|
+
// WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
|
|
892
|
+
// has no config file, and reads as no provider — which is the safe reading,
|
|
893
|
+
// since "trunk" is today's behaviour. An unregistered base distribution never
|
|
894
|
+
// asks at all.
|
|
895
|
+
let providerConfigFile = null
|
|
896
|
+
function setProviderConfigFile(rel) {
|
|
897
|
+
providerConfigFile = rel || null
|
|
898
|
+
}
|
|
899
|
+
|
|
900
|
+
// An explicit `specDocs` in the file — any value, even one the merge rejected —
|
|
901
|
+
// is the project's decision; a rejected typo stays on the conservative "trunk"
|
|
902
|
+
// rather than being promoted to the provider default.
|
|
903
|
+
function applyProviderSpecDocs(config, parsed, dir) {
|
|
904
|
+
if (!providerConfigFile) return config
|
|
905
|
+
const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
|
|
906
|
+
if (pLand && 'specDocs' in pLand) return config
|
|
907
|
+
if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
|
|
908
|
+
return config
|
|
909
|
+
}
|
|
910
|
+
|
|
876
911
|
function loadEnvConfig(dir = process.cwd()) {
|
|
877
912
|
const base = defaults()
|
|
878
913
|
const file = join(dir, CONFIG_FILE)
|
|
@@ -882,7 +917,12 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
882
917
|
raw = readFileSync(file, 'utf-8')
|
|
883
918
|
} catch (error) {
|
|
884
919
|
if (error.code === 'ENOENT') {
|
|
885
|
-
return {
|
|
920
|
+
return {
|
|
921
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
|
|
922
|
+
present: false,
|
|
923
|
+
unknown: [],
|
|
924
|
+
badReviewers: [],
|
|
925
|
+
}
|
|
886
926
|
}
|
|
887
927
|
throw error
|
|
888
928
|
}
|
|
@@ -895,7 +935,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
895
935
|
}
|
|
896
936
|
|
|
897
937
|
return {
|
|
898
|
-
config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
|
|
938
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
|
|
899
939
|
present: true,
|
|
900
940
|
unknown: collectUnknownKeys(parsed),
|
|
901
941
|
badReviewers: collectBadReviewers(parsed),
|
|
@@ -905,6 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
905
945
|
module.exports = {
|
|
906
946
|
loadEnvConfig,
|
|
907
947
|
setProviderEnvDefaults,
|
|
948
|
+
setProviderConfigFile,
|
|
908
949
|
resolveServePort,
|
|
909
950
|
derivedServePort,
|
|
910
951
|
servePortRoot,
|
package/src/env/epic.js
CHANGED
|
@@ -292,12 +292,21 @@ function layer(members) {
|
|
|
292
292
|
* - `index` `indexSpecTree` of the base branch
|
|
293
293
|
* - `readFile` base-branch path → text, or null
|
|
294
294
|
* - `candidates` base-branch overview paths that may carry an `Epic:` header
|
|
295
|
+
* - `waitIndex`/`waitRead` where a wait is resolved, when that is not where
|
|
296
|
+
* members are read — `epic status --here` reads members off a
|
|
297
|
+
* working tree and still meets a wait only on the base branch
|
|
295
298
|
* - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
|
|
296
299
|
* each provisioned spec's own copy, which is where an
|
|
297
300
|
* in-flight spec's bucket and phase progress are true
|
|
301
|
+
* - `branches` the same shape, read off spec branches this machine has no
|
|
302
|
+
* worktree for (`env/specbranches.js`) — how a member that
|
|
303
|
+
* rides its own branch is seen at all. It can make a member
|
|
304
|
+
* VISIBLE and give it a bucket; it never meets a wait, which
|
|
305
|
+
* is still read only off the base branch.
|
|
298
306
|
*/
|
|
299
|
-
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
|
|
307
|
+
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
|
|
300
308
|
const own = new Map(worktrees.map((w) => [w.folder, w]))
|
|
309
|
+
const onBranch = new Map(branches.filter((b) => !own.has(b.folder)).map((b) => [b.folder, b]))
|
|
301
310
|
const members = new Map()
|
|
302
311
|
|
|
303
312
|
for (const file of candidates) {
|
|
@@ -312,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
312
321
|
members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
|
|
313
322
|
}
|
|
314
323
|
// A member authored on its own branch and not landed yet is invisible on the
|
|
315
|
-
// base branch; its worktree copy is what knows it belongs here
|
|
316
|
-
|
|
324
|
+
// base branch; its worktree copy is what knows it belongs here — or, with no
|
|
325
|
+
// worktree on this machine, its branch's copy. The worktree is read last, so
|
|
326
|
+
// it wins.
|
|
327
|
+
for (const w of [...onBranch.values(), ...worktrees]) {
|
|
317
328
|
const h = epicHeaders(w.overview)
|
|
318
329
|
// The worktree's copy is the newer word on a spec being built: it may have
|
|
319
330
|
// joined, changed its waits, or moved to another epic.
|
|
@@ -327,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
327
338
|
const base = index.get(m.spec)
|
|
328
339
|
// In flight is the positive signal of a worktree whose own copy has not
|
|
329
340
|
// finished; otherwise the base branch's bucket.
|
|
330
|
-
|
|
331
|
-
m.
|
|
341
|
+
const br = onBranch.get(m.spec)
|
|
342
|
+
m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : br ? br.bucket : base ? base.bucket : wt ? wt.bucket : null
|
|
343
|
+
m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, waitIndex, waitRead) }))
|
|
332
344
|
// A phase's own `Waits on:` holds that phase, not the spec's start: the
|
|
333
345
|
// sync point the field example turned on (#154 phase 2 on #159 phase 1).
|
|
334
346
|
// A phase already done has nothing left to wait for.
|
|
335
347
|
m.phaseWaits = m.phases
|
|
336
348
|
.filter((p) => p.text !== null && !phaseIsDone(p.text))
|
|
337
349
|
.flatMap((p) =>
|
|
338
|
-
epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w,
|
|
350
|
+
epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, waitIndex, waitRead) } })),
|
|
339
351
|
)
|
|
340
352
|
}
|
|
341
353
|
|
|
@@ -403,9 +415,12 @@ function aligned(lines, indent = ' ') {
|
|
|
403
415
|
* cannot tell rather than guessing.
|
|
404
416
|
*/
|
|
405
417
|
function formatEpicStatus(s) {
|
|
406
|
-
if (!s.found && !s.members.length)
|
|
418
|
+
if (!s.found && !s.members.length) {
|
|
419
|
+
return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
|
|
420
|
+
}
|
|
407
421
|
const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
|
|
408
|
-
const
|
|
422
|
+
const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
|
|
423
|
+
const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${where}`
|
|
409
424
|
const out = [head, '']
|
|
410
425
|
if (!s.members.length) {
|
|
411
426
|
out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
|
package/src/env/epicpage.js
CHANGED
|
@@ -51,7 +51,7 @@ function syncLine({ spec, phase, wait }) {
|
|
|
51
51
|
return `${who} after ${wait.raw} (${mark})`
|
|
52
52
|
}
|
|
53
53
|
|
|
54
|
-
function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
|
|
54
|
+
function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
|
|
55
55
|
const lanes = answer.lanes === null ? 'no lane cap' : `${answer.lanes} lanes, ${answer.freeLanes} free`
|
|
56
56
|
const count = `${answer.members.length} member${answer.members.length === 1 ? '' : 's'}`
|
|
57
57
|
const rows = (answer.rows || [])
|
|
@@ -83,7 +83,7 @@ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
|
|
|
83
83
|
<meta charset="utf-8">
|
|
84
84
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
85
85
|
<meta http-equiv="refresh" content="${Number(refreshSeconds)}">
|
|
86
|
-
<title>${escapeHtml(answer.epic)}</title>
|
|
86
|
+
<title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
|
|
87
87
|
<style>
|
|
88
88
|
:root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
|
|
89
89
|
@media (prefers-color-scheme: dark) {
|
|
@@ -94,6 +94,7 @@ body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
|
|
|
94
94
|
font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
|
|
95
95
|
main { max-width:60rem; margin:0 auto }
|
|
96
96
|
h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
|
|
97
|
+
.eyebrow { color:var(--dim); font-size:.8rem; margin:0 0 .1rem }
|
|
97
98
|
.sub { color:var(--dim); margin:0 0 1.25rem }
|
|
98
99
|
.wrap { overflow-x:auto }
|
|
99
100
|
table { border-collapse:collapse; width:100% }
|
|
@@ -113,7 +114,7 @@ dt { color:var(--dim) } dd { margin:0 }
|
|
|
113
114
|
</head>
|
|
114
115
|
<body>
|
|
115
116
|
<main>
|
|
116
|
-
<h1>${escapeHtml(answer.epic)}</h1>
|
|
117
|
+
${project ? `<p class="eyebrow">${escapeHtml(project)}</p>\n` : ''}<h1>${escapeHtml(answer.epic)}</h1>
|
|
117
118
|
<p class="sub">${count} · ${escapeHtml(lanes)}</p>
|
|
118
119
|
<div class="wrap">${table}</div>
|
|
119
120
|
${own}
|
package/src/env/epicread.js
CHANGED
|
@@ -36,6 +36,44 @@ function epicTree(git, base) {
|
|
|
36
36
|
return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
|
|
37
37
|
}
|
|
38
38
|
|
|
39
|
+
/**
|
|
40
|
+
* The same shape as `epicTree`, read off a WORKING TREE on disk — uncommitted
|
|
41
|
+
* edits included. It is what `epic status --here` reads members and headers
|
|
42
|
+
* from, so a conversion can be checked in the worktree it is made in before it
|
|
43
|
+
* lands. Waits are still met only on the base branch: that is the caller's
|
|
44
|
+
* `waitIndex`, never this.
|
|
45
|
+
*
|
|
46
|
+
* WHAT WOULD FOOL THIS: a file git would ignore is read like any other. Under
|
|
47
|
+
* `specs/` there is nothing ignored by design, so the cost is a stray editor
|
|
48
|
+
* backup named `*.md`, read as one more phase file.
|
|
49
|
+
*/
|
|
50
|
+
function workingTree(root) {
|
|
51
|
+
const files = []
|
|
52
|
+
const walk = (rel) => {
|
|
53
|
+
let entries
|
|
54
|
+
try {
|
|
55
|
+
entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true })
|
|
56
|
+
} catch {
|
|
57
|
+
return
|
|
58
|
+
}
|
|
59
|
+
for (const e of entries) {
|
|
60
|
+
const p = `${rel}/${e.name}`
|
|
61
|
+
if (e.isDirectory()) walk(p)
|
|
62
|
+
else if (e.isFile()) files.push(p)
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
walk('specs')
|
|
66
|
+
const readFile = (p) => {
|
|
67
|
+
try {
|
|
68
|
+
return fs.readFileSync(path.join(root, p), 'utf8')
|
|
69
|
+
} catch {
|
|
70
|
+
return null
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
const candidates = files.filter((p) => p.endsWith('/00-overview.md') && /^>\s*\*\*Epic:\*\*/m.test(readFile(p) || ''))
|
|
74
|
+
return { index: indexSpecTree(files.join('\n')), readFile, candidates }
|
|
75
|
+
}
|
|
76
|
+
|
|
39
77
|
// A provisioned spec's own overview and bucket, read in its worktree — the
|
|
40
78
|
// copy where an in-flight spec's bucket and headers are true. null when the
|
|
41
79
|
// worktree holds no readable copy.
|
|
@@ -106,4 +144,4 @@ function epicAnswer(epic, inputs, readers) {
|
|
|
106
144
|
return { ...status, rows, next }
|
|
107
145
|
}
|
|
108
146
|
|
|
109
|
-
module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
|
|
147
|
+
module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
|
package/src/env/integrate.js
CHANGED
|
@@ -243,6 +243,53 @@ function planIntegratePr(spec, config, ctx) {
|
|
|
243
243
|
}
|
|
244
244
|
}
|
|
245
245
|
|
|
246
|
+
/**
|
|
247
|
+
* Pure planner for the AUTHORING land of a spec document under
|
|
248
|
+
* `land.specDocs: "branch"` (`spec-env integrate --docs`).
|
|
249
|
+
*
|
|
250
|
+
* The document rides its own branch rather than landing on base, so the plan
|
|
251
|
+
* touches no base at all — no rebase, no fast-forward, no PR. What it does is
|
|
252
|
+
* publish the branch, because a spec on an unpushed branch is on one machine
|
|
253
|
+
* and nowhere else (the ticket's summary block cannot rebuild it). The push is
|
|
254
|
+
* consent-gated with `planIntegratePr`'s shape: already on the remote at HEAD
|
|
255
|
+
* is honoured (`via: "remote"`), `--push` is the recorded yes (`via: "push"`),
|
|
256
|
+
* otherwise it HOLDS (`via: "hold"`) with the push in `holdCommands`.
|
|
257
|
+
*
|
|
258
|
+
* NO REMOTE IS A HOLD, NEVER AN ERROR. A clone with no remote of that name
|
|
259
|
+
* cannot publish, and refusing would accuse a healthy local-only repo; the
|
|
260
|
+
* plan says so (`noRemote`) and the spec stays on its local branch.
|
|
261
|
+
*
|
|
262
|
+
* ctx: { worktreeState: { dirty }, remote, treePath, remoteConfigured,
|
|
263
|
+
* pushedAtHead, push }
|
|
264
|
+
*/
|
|
265
|
+
function planIntegrateDocs(spec, config, ctx) {
|
|
266
|
+
const { worktreeState = {}, treePath, remoteConfigured } = ctx || {}
|
|
267
|
+
const remote = (ctx && ctx.remote) || 'origin'
|
|
268
|
+
const branch = spec.branch
|
|
269
|
+
const result = {
|
|
270
|
+
blocked: false, noop: false, reason: null, commands: [],
|
|
271
|
+
push: null, holdCommands: [], noRemote: false,
|
|
272
|
+
afterLand: noAfterLand(), branch, remote,
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
// The verdict's commit ran first, so anything still uncommitted is not this
|
|
276
|
+
// spec's — and a push would publish a branch missing it.
|
|
277
|
+
if (worktreeState.dirty) {
|
|
278
|
+
return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the spec first' }
|
|
279
|
+
}
|
|
280
|
+
if (!remoteConfigured) {
|
|
281
|
+
return { ...result, noRemote: true, push: { kind: 'push', via: 'hold', remote, branch } }
|
|
282
|
+
}
|
|
283
|
+
if (ctx.pushedAtHead) {
|
|
284
|
+
return { ...result, noop: true, push: { kind: 'push', via: 'remote', remote, branch } }
|
|
285
|
+
}
|
|
286
|
+
const pushCommand = `git -C ${shellPath(treePath)} push -u ${remote} ${branch}`
|
|
287
|
+
if (ctx.push) {
|
|
288
|
+
return { ...result, commands: [pushCommand], push: { kind: 'push', via: 'push', remote, branch } }
|
|
289
|
+
}
|
|
290
|
+
return { ...result, push: { kind: 'push', via: 'hold', remote, branch }, holdCommands: [pushCommand] }
|
|
291
|
+
}
|
|
292
|
+
|
|
246
293
|
// The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
|
|
247
294
|
// primary checkout, standing on base) once the land commands have succeeded.
|
|
248
295
|
// A blocked plan carries the empty form — nothing landed, so nothing follows.
|
|
@@ -291,4 +338,4 @@ function noAfterLand() {
|
|
|
291
338
|
return { cwd: null, commands: [], entries: [], range: null }
|
|
292
339
|
}
|
|
293
340
|
|
|
294
|
-
module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }
|
|
341
|
+
module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs, afterLandFor, rangeOf }
|
package/src/env/project.js
CHANGED
|
@@ -162,6 +162,23 @@ function attachProject(config, anchor) {
|
|
|
162
162
|
return config
|
|
163
163
|
}
|
|
164
164
|
|
|
165
|
+
/**
|
|
166
|
+
* The name a generated page calls this project by: `review.projectName` when
|
|
167
|
+
* set, else the project folder's name in the PRIMARY checkout.
|
|
168
|
+
*
|
|
169
|
+
* NEVER THE CWD'S NAME. A worktree's folder is named after its spec, so a page
|
|
170
|
+
* rendered from one would repeat the spec name where the project's belongs —
|
|
171
|
+
* which is why this reads the anchor `attachProject` recorded. `null` when there
|
|
172
|
+
* is none: cannot tell, and the pages then render exactly as they did before.
|
|
173
|
+
*/
|
|
174
|
+
function projectName(config) {
|
|
175
|
+
const set = config && config.review && config.review.projectName
|
|
176
|
+
if (typeof set === 'string' && set.trim()) return set.trim()
|
|
177
|
+
const p = config && config.project
|
|
178
|
+
if (!p || !p.root) return null
|
|
179
|
+
return path.basename(projectIn(p.root, p.prefix || '')) || null
|
|
180
|
+
}
|
|
181
|
+
|
|
165
182
|
/**
|
|
166
183
|
* A path as one shell word, for the commands the engine PRINTS for a person or
|
|
167
184
|
* a skill to run. Quoted only when it has to be, so a path without spaces or
|
|
@@ -217,6 +234,7 @@ module.exports = {
|
|
|
217
234
|
toPosix,
|
|
218
235
|
shellPath,
|
|
219
236
|
attachProject,
|
|
237
|
+
projectName,
|
|
220
238
|
repoRootOf,
|
|
221
239
|
prefixOf,
|
|
222
240
|
projectLine,
|
package/src/env/review.js
CHANGED
|
@@ -269,7 +269,7 @@ function resolveReader(config, env = {}) {
|
|
|
269
269
|
* `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
|
|
270
270
|
* caller's declaration about the work, not a reading of the gate.
|
|
271
271
|
*/
|
|
272
|
-
function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null }) {
|
|
272
|
+
function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
|
|
273
273
|
// WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
|
|
274
274
|
// reads the spec's worktree, and for those the two are the same path — so
|
|
275
275
|
// `treePath` left null keeps the existing behaviour exactly. The `docs` mode
|
|
@@ -360,6 +360,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
360
360
|
return {
|
|
361
361
|
spec: spec.folder,
|
|
362
362
|
title: spec.folder,
|
|
363
|
+
// The project's name, for the tab and the line above the heading. Absent
|
|
364
|
+
// when the caller could not tell, and the page then renders as before.
|
|
365
|
+
...(project ? { project } : {}),
|
|
363
366
|
branch: spec.branch,
|
|
364
367
|
// The tree the diff was read from. Identical to the worktree for every
|
|
365
368
|
// mode but `docs`, where there is no worktree and this is the checkout the
|
|
@@ -603,6 +606,10 @@ const ACTIONS = ['live-on', 'allow-network', 'allow-remote']
|
|
|
603
606
|
*/
|
|
604
607
|
function tierAction(tier) {
|
|
605
608
|
if (!tier || !tier.off) return null
|
|
609
|
+
// A loopback bind is off for a reason no press can fix: widening it restarts
|
|
610
|
+
// the server, which mints a new token and kills every link already open. Its
|
|
611
|
+
// command is named on the line; the page offers nothing.
|
|
612
|
+
if (tier.bound === 'loopback') return null
|
|
606
613
|
if (tier.tier === 'network') return 'allow-network'
|
|
607
614
|
if (tier.tier === 'remote') return 'allow-remote'
|
|
608
615
|
return null
|
|
@@ -742,6 +749,11 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
|
|
|
742
749
|
return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
|
|
743
750
|
}),
|
|
744
751
|
})
|
|
752
|
+
} else if (served && served.loopback && served.widen) {
|
|
753
|
+
// Permitted, and the machine has addresses — but the running server is
|
|
754
|
+
// bound to loopback. "No network address" here sent readers looking for a
|
|
755
|
+
// network problem; the fix is one command, so the line names it.
|
|
756
|
+
tiers.push({ tier: 'network', off: true, bound: 'loopback', enable: served.widen })
|
|
745
757
|
} else {
|
|
746
758
|
// Permitted, but there is no address to offer — a machine with no network,
|
|
747
759
|
// or a server that could not take one. Not a problem to report as an error.
|
|
@@ -2309,16 +2321,22 @@ function fragmentTemplate(template = null) {
|
|
|
2309
2321
|
*/
|
|
2310
2322
|
function renderReviewFragment(data, { template = null, reviewHtml = '' } = {}) {
|
|
2311
2323
|
const values = {
|
|
2312
|
-
[TITLE_PLACEHOLDER]: escapeHtml(data
|
|
2324
|
+
[TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
|
|
2313
2325
|
[REVIEW_PLACEHOLDER]: reviewHtml,
|
|
2314
2326
|
[DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
|
|
2315
2327
|
}
|
|
2316
2328
|
return fragmentTemplate(template).replace(PLACEHOLDER_RE, (m) => values[m])
|
|
2317
2329
|
}
|
|
2318
2330
|
|
|
2331
|
+
// The tab name: `<project> · <spec>`, so pages from two projects open side by
|
|
2332
|
+
// side can be told apart from the tab alone — all a phone shows.
|
|
2333
|
+
function tabTitle(data) {
|
|
2334
|
+
return data.project ? `${data.project} · ${data.title}` : data.title
|
|
2335
|
+
}
|
|
2336
|
+
|
|
2319
2337
|
function renderReviewPage(data, { template = null, reviewHtml = '' } = {}) {
|
|
2320
2338
|
const values = {
|
|
2321
|
-
[TITLE_PLACEHOLDER]: escapeHtml(data
|
|
2339
|
+
[TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
|
|
2322
2340
|
[REVIEW_PLACEHOLDER]: reviewHtml,
|
|
2323
2341
|
[DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
|
|
2324
2342
|
}
|
package/src/env/serve.js
CHANGED
|
@@ -38,10 +38,11 @@ const {
|
|
|
38
38
|
isEpic,
|
|
39
39
|
} = require('./resolve.js')
|
|
40
40
|
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
|
|
41
|
+
const { specBranchDocs } = require('./specbranches.js')
|
|
41
42
|
const { renderEpicPage } = require('./epicpage.js')
|
|
42
43
|
const { readRegistry } = require('./registry.js')
|
|
43
44
|
const { loadEnvConfig } = require('./config.js')
|
|
44
|
-
const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
45
|
+
const { primaryAnchor, attachProject, projectName, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
45
46
|
const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
|
|
46
47
|
const { liveStateFor } = require('./live.js')
|
|
47
48
|
const { preferRemoteBase } = require('./host.js')
|
|
@@ -127,8 +128,11 @@ function escapeHtml(s) {
|
|
|
127
128
|
* palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
|
|
128
129
|
* do not disagree when opened side by side.
|
|
129
130
|
*/
|
|
130
|
-
function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
131
|
+
function renderIndex(entries, { token = null, epics = [], project = null } = {}) {
|
|
131
132
|
const prefix = token ? `/${token}` : ''
|
|
133
|
+
// The heading and tab name the project, so two servers' indexes open side by
|
|
134
|
+
// side can be told apart. No name — cannot tell — reads as it always did.
|
|
135
|
+
const heading = project ? `${escapeHtml(project)} · spec diffs` : 'spec diffs'
|
|
132
136
|
// Epics with a member in flight, each a doorway to its epic page. Listed
|
|
133
137
|
// above the diffs because an epic page is where a reader running several
|
|
134
138
|
// members starts; absent entirely on a repo with no epic in flight.
|
|
@@ -161,7 +165,7 @@ function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
|
161
165
|
<head>
|
|
162
166
|
<meta charset="utf-8">
|
|
163
167
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
164
|
-
<title
|
|
168
|
+
<title>${heading}</title>
|
|
165
169
|
<style>
|
|
166
170
|
:root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --add:#0a7b34; --del:#b3261e; --link:#0b5fbd }
|
|
167
171
|
@media (prefers-color-scheme: dark) {
|
|
@@ -188,7 +192,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
|
|
|
188
192
|
</head>
|
|
189
193
|
<body>
|
|
190
194
|
<main>
|
|
191
|
-
<h1
|
|
195
|
+
<h1>${heading}</h1>
|
|
192
196
|
${epicList}
|
|
193
197
|
${body}
|
|
194
198
|
</main>
|
|
@@ -561,6 +565,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
561
565
|
notes,
|
|
562
566
|
gate: gateRead.corrupt ? null : gateRead.gate,
|
|
563
567
|
buttons,
|
|
568
|
+
project: projectName(config),
|
|
564
569
|
only: view.owned,
|
|
565
570
|
treePath: view.tree,
|
|
566
571
|
})
|
|
@@ -638,6 +643,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
638
643
|
buttons,
|
|
639
644
|
live,
|
|
640
645
|
tiers,
|
|
646
|
+
project: projectName(config),
|
|
641
647
|
})
|
|
642
648
|
|
|
643
649
|
if (!branch && data.totals.files === 0) {
|
|
@@ -660,6 +666,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
660
666
|
buttons,
|
|
661
667
|
live,
|
|
662
668
|
tiers,
|
|
669
|
+
project: projectName(config),
|
|
663
670
|
fellBack: true,
|
|
664
671
|
})
|
|
665
672
|
if (wider.totals.files > 0) {
|
|
@@ -805,7 +812,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
|
|
|
805
812
|
})
|
|
806
813
|
}
|
|
807
814
|
|
|
808
|
-
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
|
|
815
|
+
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null, project = null }) {
|
|
809
816
|
return http.createServer((req, res) => {
|
|
810
817
|
const send = (code, body, type = 'text/html; charset=utf-8') => {
|
|
811
818
|
res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
|
|
@@ -859,7 +866,7 @@ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, r
|
|
|
859
866
|
}
|
|
860
867
|
|
|
861
868
|
try {
|
|
862
|
-
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
|
|
869
|
+
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics(), project }))
|
|
863
870
|
const out = render(route.spec, { branch: route.branch })
|
|
864
871
|
if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
|
|
865
872
|
if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
|
|
@@ -1027,14 +1034,16 @@ function serverHooks(dir, config) {
|
|
|
1027
1034
|
}
|
|
1028
1035
|
const tree = epicTree(trimmedGit, base)
|
|
1029
1036
|
if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
|
|
1030
|
-
const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
|
|
1037
|
+
const inputs = { dir, config, base, ...tree, worktrees: worktrees(), branches: specBranchDocs(trimmedGit, config, base) }
|
|
1031
1038
|
const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
|
|
1032
1039
|
if (!answer.found && !answer.members.length) return null
|
|
1033
|
-
return { html: renderEpicPage(answer) }
|
|
1040
|
+
return { html: renderEpicPage(answer, { project: projectName(config) }) }
|
|
1034
1041
|
}
|
|
1035
1042
|
|
|
1036
1043
|
return {
|
|
1037
1044
|
resolveEntries,
|
|
1045
|
+
// What the index calls this project. Read once: the server is per project.
|
|
1046
|
+
project: projectName(config),
|
|
1038
1047
|
resolveEpics: () => {
|
|
1039
1048
|
try {
|
|
1040
1049
|
return epicsInFlight(worktrees())
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Specs that live only on their own branch (feat-tracker-spec-branches).
|
|
5
|
+
*
|
|
6
|
+
* Under `land.specDocs: "branch"` — the default once a ticketing provider is
|
|
7
|
+
* configured — a spec document never lands on the base branch until its work
|
|
8
|
+
* does, so `ls specs/backlog/` on base cannot see it. The checks that read the
|
|
9
|
+
* backlog (`gating check`, `epic status`, `docs-freshness check`) ask this
|
|
10
|
+
* instead, so the specs that mode produces are not invisible to them.
|
|
11
|
+
*
|
|
12
|
+
* What a branch is FOR is read off what it changed: the spec folders its range
|
|
13
|
+
* (`<base>...<ref>`) touches. Every spec branch forks from base and so carries
|
|
14
|
+
* every base spec too; only the ones it changed are its own.
|
|
15
|
+
*
|
|
16
|
+
* Read with git and never fetched. An advisory check that can hang on the
|
|
17
|
+
* network is worse than one that is a fetch behind, so remote-tracking refs are
|
|
18
|
+
* read as they stand and a caller labels them "as of last fetch".
|
|
19
|
+
*
|
|
20
|
+
* WHAT WOULD FOOL THIS: a remote that was never fetched (its specs are simply
|
|
21
|
+
* absent — an extra miss, never an accusation), and a spec branch whose name
|
|
22
|
+
* does not match `branch.pattern` (renamed by hand; it is not found). Every
|
|
23
|
+
* unreadable git call reads as nothing found.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
const { BUCKETS } = require('./resolve.js')
|
|
27
|
+
|
|
28
|
+
const OVERVIEW_RE = /^specs\/([^/]+)\/([^/]+)\/00-overview\.md$/
|
|
29
|
+
const SPEC_PATH_RE = /^specs\/([^/]+)\/([^/]+)\//
|
|
30
|
+
|
|
31
|
+
// `branch.pattern` as a for-each-ref glob: every `{token}` becomes `*`.
|
|
32
|
+
function refGlob(config) {
|
|
33
|
+
const pattern = (config && config.branch && config.branch.pattern) || '{type}/{slug}'
|
|
34
|
+
return pattern.replace(/\{[^}]+\}/g, '*')
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function lines(out) {
|
|
38
|
+
return String(out || '').split('\n').map((l) => l.trim()).filter(Boolean)
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The spec branches this clone can see: local first, then remote-tracking, as
|
|
43
|
+
* `{ ref, name, local }`. The base branch itself is never a spec branch.
|
|
44
|
+
*/
|
|
45
|
+
function specRefs(git, config, base) {
|
|
46
|
+
const glob = refGlob(config)
|
|
47
|
+
const remote = (config && config.land && config.land.remote) || 'origin'
|
|
48
|
+
const local = lines(git(['for-each-ref', '--format=%(refname)', `refs/heads/${glob}`]))
|
|
49
|
+
.map((ref) => ({ ref, name: ref.slice('refs/heads/'.length), local: true }))
|
|
50
|
+
const prefix = `refs/remotes/${remote}/`
|
|
51
|
+
const tracking = lines(git(['for-each-ref', '--format=%(refname)', `${prefix}${glob}`]))
|
|
52
|
+
.map((ref) => ({ ref, name: ref.slice(prefix.length), local: false }))
|
|
53
|
+
return [...local, ...tracking].filter((r) => r.name !== base && r.name !== 'HEAD')
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Every spec folder a spec branch changed, read off that branch:
|
|
58
|
+
* `[{ folder, bucket, ref, local, overview, phases: [{ n, text }] }]`.
|
|
59
|
+
*
|
|
60
|
+
* Precedence (Decision 7): a folder the base branch has FINISHED — in
|
|
61
|
+
* `complete/` or `cancelled/` — is dropped, since the work is done and a
|
|
62
|
+
* lingering branch is history; otherwise a local branch beats a
|
|
63
|
+
* remote-tracking one. Base's own `backlog/` copy losing to a branch copy is
|
|
64
|
+
* the caller's merge, via `preferBranches`.
|
|
65
|
+
*/
|
|
66
|
+
function specBranchDocs(git, config, base) {
|
|
67
|
+
if (!base) return []
|
|
68
|
+
const finished = new Set()
|
|
69
|
+
for (const p of lines(git(['ls-tree', '-r', '--name-only', base, '--', 'specs/complete', 'specs/cancelled']))) {
|
|
70
|
+
const m = OVERVIEW_RE.exec(p)
|
|
71
|
+
if (m) finished.add(m[2])
|
|
72
|
+
}
|
|
73
|
+
const found = new Map()
|
|
74
|
+
for (const { ref, local } of specRefs(git, config, base)) {
|
|
75
|
+
const changed = new Set()
|
|
76
|
+
for (const p of lines(git(['diff', '--name-only', `${base}...${ref}`, '--', 'specs']))) {
|
|
77
|
+
const m = SPEC_PATH_RE.exec(p)
|
|
78
|
+
if (m && BUCKETS.includes(m[1])) changed.add(m[2])
|
|
79
|
+
}
|
|
80
|
+
if (!changed.size) continue
|
|
81
|
+
const tree = lines(git(['ls-tree', '-r', '--name-only', ref, '--', 'specs']))
|
|
82
|
+
for (const folder of changed) {
|
|
83
|
+
if (finished.has(folder)) continue
|
|
84
|
+
if (found.has(folder) && (found.get(folder).local || !local)) continue
|
|
85
|
+
const overviewPath = tree.find((p) => {
|
|
86
|
+
const m = OVERVIEW_RE.exec(p)
|
|
87
|
+
return m && m[2] === folder
|
|
88
|
+
})
|
|
89
|
+
if (!overviewPath) continue // the branch deleted it, or moved it out of specs/
|
|
90
|
+
const overview = git(['show', `${ref}:${overviewPath}`])
|
|
91
|
+
if (overview === null) continue
|
|
92
|
+
const bucket = OVERVIEW_RE.exec(overviewPath)[1]
|
|
93
|
+
const dirPrefix = `specs/${bucket}/${folder}/`
|
|
94
|
+
const phases = tree
|
|
95
|
+
.filter((p) => p.startsWith(dirPrefix) && /^\d\d-.+\.md$/.test(p.slice(dirPrefix.length)) && !p.endsWith('/00-overview.md'))
|
|
96
|
+
.map((p) => ({ n: Number(p.slice(dirPrefix.length, dirPrefix.length + 2)), text: git(['show', `${ref}:${p}`]) }))
|
|
97
|
+
found.set(folder, { folder, bucket, ref, local, overview, phases })
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return [...found.values()].sort((a, b) => a.folder.localeCompare(b.folder))
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Merge a disk scan with branch copies: a branch copy replaces the disk entry
|
|
105
|
+
* for the same folder, and adds one where there is none. Both lists carry
|
|
106
|
+
* `folder`; the result keeps the disk entries' order, then the new ones.
|
|
107
|
+
*/
|
|
108
|
+
function preferBranches(disk, branches) {
|
|
109
|
+
const byFolder = new Map(branches.map((b) => [b.folder, b]))
|
|
110
|
+
const merged = disk.map((d) => byFolder.get(d.folder) || d)
|
|
111
|
+
const seen = new Set(disk.map((d) => d.folder))
|
|
112
|
+
return [...merged, ...branches.filter((b) => !seen.has(b.folder))]
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** The label a branch-sourced row carries. */
|
|
116
|
+
function branchLabel(entry) {
|
|
117
|
+
return entry.local ? `on ${entry.ref.replace(/^refs\/heads\//, '')}` : `on ${entry.ref.replace(/^refs\/remotes\//, '')}, as of last fetch`
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
module.exports = { specBranchDocs, specRefs, preferBranches, branchLabel, refGlob }
|