@skitterbyte/skitterspec-linear 19.7.0 → 19.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 +3 -1
- package/assets/claude-md-section.md +6 -0
- package/assets/core/env.config.json.example +5 -0
- package/assets/core/env.config.md +26 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +65 -12
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +31 -14
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-complete/SKILL.md +6 -0
- package/assets/skills/spec-epic-next/SKILL.md +83 -0
- package/assets/skills/spec-init/SKILL.md +35 -3
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +2 -2
- package/assets/skills/spec-tada/SKILL.md +153 -0
- package/bin/skitterspec-linear.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +473 -25
- package/src/env/config.js +57 -6
- package/src/env/epic.js +69 -19
- package/src/env/epicpage.js +87 -39
- package/src/env/epicread.js +41 -3
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +78 -1
- package/src/env/project.js +54 -3
- package/src/env/projectedit.js +148 -0
- package/src/env/resolve.js +1 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +44 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/init.js +11 -3
- package/src/tada/commits.js +145 -0
- package/src/tada/digest.js +260 -0
- package/src/tada/format.js +37 -0
- package/src/tada/page.js +213 -0
- package/src/tada/repo.js +102 -0
- package/src/tada/serve.js +127 -0
- package/src/tada/specs.js +146 -0
- package/src/tada/transcripts.js +258 -0
- package/src/tada/window.js +156 -0
- 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/assets/commands/{epic.md → spec-epic.md} +0 -0
package/src/tada/page.js
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The ta-da list as a page: the model's recap on top, the digest it was
|
|
5
|
+
* written from underneath. PURE — digest and recap in, HTML out.
|
|
6
|
+
*
|
|
7
|
+
* READ-ONLY AND UNSERVED. No form, no buttons, no script beyond nothing: a
|
|
8
|
+
* recap asks no verdict, so it has nothing to send back and no server to send
|
|
9
|
+
* it to. It is a file on this machine; publishing it is a separate act.
|
|
10
|
+
*
|
|
11
|
+
* EVERYTHING IS ESCAPED BEFORE IT IS FORMATTED. The digest quotes the reader's
|
|
12
|
+
* own prompts and commit subjects, and the recap is model-written markdown —
|
|
13
|
+
* neither is trusted to be HTML. The markdown subset below works on escaped
|
|
14
|
+
* text, so a `<script>` in a prompt arrives as text, never as a tag.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
function escapeHtml(s) {
|
|
18
|
+
return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c])
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
// Inline markdown on ALREADY-ESCAPED text: code first, so `**` inside a code
|
|
22
|
+
// span stays literal; then bold, then italic.
|
|
23
|
+
function inline(escaped) {
|
|
24
|
+
return escaped
|
|
25
|
+
.replace(/`([^`]+)`/g, '<code>$1</code>')
|
|
26
|
+
.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
|
|
27
|
+
.replace(/(^|[^*\w])\*([^*\s][^*]*)\*(?!\w)/g, '$1<em>$2</em>')
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The markdown a recap uses and nothing more: `#`–`###` headings, `-`/`*`
|
|
32
|
+
* bullets (one level), paragraphs, and inline code, bold and italic. Anything
|
|
33
|
+
* else reads as a paragraph of text — the safe failure for a recap.
|
|
34
|
+
*/
|
|
35
|
+
function renderMarkdown(md) {
|
|
36
|
+
const out = []
|
|
37
|
+
let list = false
|
|
38
|
+
let para = []
|
|
39
|
+
const flushPara = () => {
|
|
40
|
+
if (para.length) out.push(`<p>${inline(escapeHtml(para.join(' ')))}</p>`)
|
|
41
|
+
para = []
|
|
42
|
+
}
|
|
43
|
+
const closeList = () => {
|
|
44
|
+
if (list) out.push('</ul>')
|
|
45
|
+
list = false
|
|
46
|
+
}
|
|
47
|
+
for (const raw of String(md || '').split('\n')) {
|
|
48
|
+
const line = raw.trimEnd()
|
|
49
|
+
const heading = /^(#{1,3})\s+(.*)$/.exec(line)
|
|
50
|
+
const bullet = /^\s*[-*]\s+(.*)$/.exec(line)
|
|
51
|
+
if (!line.trim()) {
|
|
52
|
+
flushPara()
|
|
53
|
+
closeList()
|
|
54
|
+
} else if (heading) {
|
|
55
|
+
flushPara()
|
|
56
|
+
closeList()
|
|
57
|
+
const level = heading[1].length + 1 // the page's own title is the h1
|
|
58
|
+
out.push(`<h${level}>${inline(escapeHtml(heading[2]))}</h${level}>`)
|
|
59
|
+
} else if (bullet) {
|
|
60
|
+
flushPara()
|
|
61
|
+
if (!list) out.push('<ul>')
|
|
62
|
+
list = true
|
|
63
|
+
out.push(`<li>${inline(escapeHtml(bullet[1]))}</li>`)
|
|
64
|
+
} else {
|
|
65
|
+
closeList()
|
|
66
|
+
para.push(line.trim())
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
flushPara()
|
|
70
|
+
closeList()
|
|
71
|
+
return out.join('\n')
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
// `14:05 on Thursday 12 November`, in the reader's local time.
|
|
75
|
+
function timeText(d) {
|
|
76
|
+
const t = new Date(d)
|
|
77
|
+
const pad = (n) => String(n).padStart(2, '0')
|
|
78
|
+
const day = t.toLocaleDateString('en-GB', { weekday: 'long', day: 'numeric', month: 'long' })
|
|
79
|
+
return `${pad(t.getHours())}:${pad(t.getMinutes())} on ${day}`
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
const EVENT = { written: 'spec written', started: 'started', completed: 'completed', cancelled: 'cancelled' }
|
|
83
|
+
const eventText = (e) => (e.kind === 'phase-done' ? `phase ${e.phase} done` : EVENT[e.kind] || e.kind)
|
|
84
|
+
|
|
85
|
+
function ticketHtml(t) {
|
|
86
|
+
if (!t) return ''
|
|
87
|
+
const id = escapeHtml(t.id)
|
|
88
|
+
return t.url ? ` <a class="ticket" href="${escapeHtml(t.url)}">${id}</a>` : ` <span class="ticket">${id}</span>`
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function groupHtml(g) {
|
|
92
|
+
const head = g.spec
|
|
93
|
+
? `<span class="spec">${escapeHtml(g.spec)}</span>${ticketHtml(g.ticket)}`
|
|
94
|
+
: `<span class="branch">${escapeHtml(g.branch || '(no branch)')}</span> <span class="muted">no spec</span>`
|
|
95
|
+
const parts = [`<h4>${head}</h4>`]
|
|
96
|
+
if (g.events.length) {
|
|
97
|
+
parts.push(`<div class="chips">${g.events.map((e) => `<span class="chip">${escapeHtml(eventText(e))}</span>`).join('')}</div>`)
|
|
98
|
+
}
|
|
99
|
+
if (g.commits.length) {
|
|
100
|
+
parts.push(
|
|
101
|
+
`<ul class="commits">${g.commits
|
|
102
|
+
.map((c) => `<li><code>${escapeHtml(c.sha)}</code> ${escapeHtml(c.subject)}</li>`)
|
|
103
|
+
.join('')}</ul>`,
|
|
104
|
+
)
|
|
105
|
+
}
|
|
106
|
+
if (g.sessions.length) {
|
|
107
|
+
const prompts = g.sessions
|
|
108
|
+
.map(
|
|
109
|
+
(s) =>
|
|
110
|
+
s.prompts.map((p) => `<li>${p.command ? `<code>${escapeHtml(p.command)}</code> ` : ''}${escapeHtml(p.text)}</li>`).join('') +
|
|
111
|
+
(s.omitted ? `<li class="muted">… ${s.omitted} more</li>` : ''),
|
|
112
|
+
)
|
|
113
|
+
.join('')
|
|
114
|
+
const n = g.sessions.length
|
|
115
|
+
parts.push(`<details><summary>${n} session${n === 1 ? '' : 's'}</summary><ul class="prompts">${prompts}</ul></details>`)
|
|
116
|
+
}
|
|
117
|
+
if (g.inFlight) {
|
|
118
|
+
const next = g.inFlight.next ? ` · next: <code>${escapeHtml(g.inFlight.next)}</code>` : ''
|
|
119
|
+
parts.push(`<p class="inflight">in flight: ${escapeHtml(g.inFlight.detail)}${next}</p>`)
|
|
120
|
+
}
|
|
121
|
+
return `<section class="group">${parts.join('\n')}</section>`
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* @param {object} digest `buildDigest`'s answer
|
|
126
|
+
* @param {object} opts
|
|
127
|
+
* - `recap` the model's markdown recap, or null for the digest alone
|
|
128
|
+
* - `title` the page title — the caller's, in the reader's own dates
|
|
129
|
+
* (`humanLabel`); the digest only knows UTC instants
|
|
130
|
+
* - `project` the name of the project the report was run from, set in
|
|
131
|
+
* small type above the heading as on every generated page
|
|
132
|
+
* - `category` the scope the report was cut to, beside it
|
|
133
|
+
* - `writtenAt` when the recap was written — a served page is drawn now,
|
|
134
|
+
* and the recap above it may be hours older than the facts
|
|
135
|
+
*/
|
|
136
|
+
function renderTadaPage(digest, { recap = null, title = 'Ta-da', project = null, category = null, writtenAt = null } = {}) {
|
|
137
|
+
const name = title
|
|
138
|
+
const eyebrow = [project, category].filter(Boolean).map(escapeHtml).join(' · ')
|
|
139
|
+
const written = recap && writtenAt ? `<p class="muted">Recap written ${escapeHtml(timeText(writtenAt))}</p>` : ''
|
|
140
|
+
const projects = digest.projects
|
|
141
|
+
.map(
|
|
142
|
+
(p) =>
|
|
143
|
+
`<article class="project"><h3>${escapeHtml(p.name)} <span class="muted">${escapeHtml(p.repo || 'not a git repo')}</span></h3>\n` +
|
|
144
|
+
`${p.groups.map(groupHtml).join('\n') || '<p class="muted">nothing here</p>'}</article>`,
|
|
145
|
+
)
|
|
146
|
+
.join('\n')
|
|
147
|
+
const notes = digest.notes.length ? `<ul class="notes">${digest.notes.map((n) => `<li>${escapeHtml(n)}</li>`).join('')}</ul>` : ''
|
|
148
|
+
|
|
149
|
+
return `<!doctype html>
|
|
150
|
+
<html lang="en">
|
|
151
|
+
<head>
|
|
152
|
+
<meta charset="utf-8">
|
|
153
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
154
|
+
<title>${escapeHtml(project ? `${project} · ${name}` : name)}</title>
|
|
155
|
+
<style>
|
|
156
|
+
/* The light palette is complete on bare :root; the dark blocks only redefine. */
|
|
157
|
+
:root {
|
|
158
|
+
--bg: #ffffff; --fg: #1b1b1f; --muted: #5c6070; --line: #e1e3e8;
|
|
159
|
+
--panel: #f6f7f9; --accent: #0b5fd0; --chip-bg: #eceef2; --chip-fg: #46506a;
|
|
160
|
+
--good-fg: #1a7f37; --good-bg: #eaf8ee;
|
|
161
|
+
}
|
|
162
|
+
:root:not([data-theme="light"]) {
|
|
163
|
+
@media (prefers-color-scheme: dark) {
|
|
164
|
+
--bg: #121316; --fg: #e4e6ea; --muted: #969bab; --line: #2a2c34;
|
|
165
|
+
--panel: #1a1c21; --accent: #7fb0ff; --chip-bg: #23262d; --chip-fg: #a3aabd;
|
|
166
|
+
--good-fg: #7ee08a; --good-bg: #12261a;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
:root[data-theme="dark"] {
|
|
170
|
+
--bg: #121316; --fg: #e4e6ea; --muted: #969bab; --line: #2a2c34;
|
|
171
|
+
--panel: #1a1c21; --accent: #7fb0ff; --chip-bg: #23262d; --chip-fg: #a3aabd;
|
|
172
|
+
--good-fg: #7ee08a; --good-bg: #12261a;
|
|
173
|
+
}
|
|
174
|
+
* { box-sizing: border-box; }
|
|
175
|
+
body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
|
|
176
|
+
main { max-width: 820px; margin: 0 auto; padding: 24px 16px 64px; }
|
|
177
|
+
h1 { font-size: 1.6rem; margin: 0 0 16px; }
|
|
178
|
+
h2 { font-size: 1.25rem; margin: 28px 0 8px; }
|
|
179
|
+
h3 { font-size: 1.1rem; margin: 0 0 12px; overflow-wrap: anywhere; }
|
|
180
|
+
h4 { font-size: 1rem; margin: 0 0 6px; overflow-wrap: anywhere; }
|
|
181
|
+
a { color: var(--accent); }
|
|
182
|
+
code { font: 0.88em ui-monospace, "SF Mono", Menlo, monospace; overflow-wrap: anywhere; }
|
|
183
|
+
.muted { color: var(--muted); font-weight: normal; font-size: 0.9em; }
|
|
184
|
+
.eyebrow { color: var(--muted); font-size: 0.85em; margin: 0 0 2px; }
|
|
185
|
+
.recap { border: 1px solid var(--line); border-radius: 10px; padding: 4px 18px 12px; background: var(--good-bg); }
|
|
186
|
+
.project { border-top: 1px solid var(--line); padding-top: 18px; margin-top: 24px; }
|
|
187
|
+
.group { background: var(--panel); border-radius: 8px; padding: 12px 14px; margin: 10px 0; }
|
|
188
|
+
.chips { display: flex; flex-wrap: wrap; gap: 6px; margin: 4px 0 8px; }
|
|
189
|
+
.chip { background: var(--chip-bg); color: var(--chip-fg); border-radius: 999px; padding: 1px 10px; font-size: 0.85em; }
|
|
190
|
+
.ticket { font-weight: normal; font-size: 0.9em; }
|
|
191
|
+
ul { padding-left: 1.2em; margin: 6px 0; }
|
|
192
|
+
.commits, .prompts { list-style: none; padding-left: 0; }
|
|
193
|
+
.commits li, .prompts li { overflow-wrap: anywhere; }
|
|
194
|
+
.inflight { margin: 8px 0 0; color: var(--good-fg); }
|
|
195
|
+
.notes { color: var(--muted); font-size: 0.9em; }
|
|
196
|
+
details summary { cursor: pointer; color: var(--muted); }
|
|
197
|
+
</style>
|
|
198
|
+
</head>
|
|
199
|
+
<body>
|
|
200
|
+
<main>
|
|
201
|
+
${eyebrow ? `<p class="eyebrow">${eyebrow}</p>` : ''}
|
|
202
|
+
<h1>${escapeHtml(name)}</h1>
|
|
203
|
+
${recap ? `<section class="recap">${renderMarkdown(recap)}${written}</section>` : ''}
|
|
204
|
+
<h2>What it was written from</h2>
|
|
205
|
+
${projects || '<p class="muted">Nothing in this window.</p>'}
|
|
206
|
+
${notes}
|
|
207
|
+
</main>
|
|
208
|
+
</body>
|
|
209
|
+
</html>
|
|
210
|
+
`
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
module.exports = { renderTadaPage, renderMarkdown, escapeHtml }
|
package/src/tada/repo.js
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Everything a ta-da list knows about one repo beyond its sessions: the
|
|
5
|
+
* author's commits in the window attributed to specs, the lifecycle moves
|
|
6
|
+
* those commits made, and how to read a branch or a ticket back to a spec.
|
|
7
|
+
*
|
|
8
|
+
* `git` is the injected reader (`(args) => stdout | null`) and `config` the
|
|
9
|
+
* repo's loaded env config, so this runs against a throwaway repo in tests.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
const fs = require('node:fs')
|
|
13
|
+
const path = require('node:path')
|
|
14
|
+
|
|
15
|
+
const { describeBaseBranch } = require('../env/resolve.js')
|
|
16
|
+
const { projectName, projectCategory } = require('../env/project.js')
|
|
17
|
+
const { CONTAINS_CAP, authorOf, branchesContaining, knownSpecs, onBaseIn, readCommits, specForTicket, ticketFor } = require('./commits.js')
|
|
18
|
+
const { attributeCommit, branchToSpec, lifecycleEvents } = require('./specs.js')
|
|
19
|
+
|
|
20
|
+
// Enough to tell commits apart in a recap, as `git log --oneline` does.
|
|
21
|
+
const SHORT = 9
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* @param {object} a
|
|
25
|
+
* - `repo` the repo root
|
|
26
|
+
* - `git` reader bound to it
|
|
27
|
+
* - `config` its env config (`loadEnvConfig(repo).config`)
|
|
28
|
+
* - `window` `{ since, until }`
|
|
29
|
+
* @returns {{ name, category, skitterspec, base, toSpec, ticket, commits, events, notes }}
|
|
30
|
+
*/
|
|
31
|
+
function readRepoFacts({ repo, git, config, window }) {
|
|
32
|
+
const notes = []
|
|
33
|
+
// The positive signal for a skitterspec project: the config folder `init`
|
|
34
|
+
// always writes. A lifecycle folder is not checked — git drops an empty one.
|
|
35
|
+
const skitterspec = fs.existsSync(path.join(repo, 'specs', '.core'))
|
|
36
|
+
|
|
37
|
+
let base = null
|
|
38
|
+
try {
|
|
39
|
+
base = describeBaseBranch(config, git).base
|
|
40
|
+
} catch {
|
|
41
|
+
base = null
|
|
42
|
+
}
|
|
43
|
+
const heads = (git(['for-each-ref', '--format=%(refname:short)', 'refs/heads']) || '').split('\n').filter(Boolean)
|
|
44
|
+
// The base first, so its copy of a spec is the one read unless only a
|
|
45
|
+
// spec branch has it.
|
|
46
|
+
const refs = [...new Set([base, ...heads].filter(Boolean))]
|
|
47
|
+
const known = skitterspec ? knownSpecs(git, refs) : []
|
|
48
|
+
const toSpec = skitterspec ? branchToSpec(config.branch && config.branch.pattern, known) : () => null
|
|
49
|
+
const identifierField = (config.branch && config.branch.identifierField) || null
|
|
50
|
+
|
|
51
|
+
const ticketCache = new Map()
|
|
52
|
+
const ticket = (spec) => {
|
|
53
|
+
if (!ticketCache.has(spec)) ticketCache.set(spec, skitterspec ? ticketFor(git, refs, spec, identifierField) : null)
|
|
54
|
+
return ticketCache.get(spec)
|
|
55
|
+
}
|
|
56
|
+
const specOfTicket = (id) => (skitterspec ? specForTicket(git, refs, id) : null)
|
|
57
|
+
|
|
58
|
+
const span = { since: window.since.toISOString(), until: window.until.toISOString() }
|
|
59
|
+
const author = authorOf(git)
|
|
60
|
+
let raw = []
|
|
61
|
+
if (!author) {
|
|
62
|
+
notes.push(`cannot tell: ${path.basename(repo)} has no user.email or user.name, so its commits were not read`)
|
|
63
|
+
} else {
|
|
64
|
+
raw = readCommits(git, { ...span, author: author.match })
|
|
65
|
+
if (raw === null) {
|
|
66
|
+
notes.push(`cannot tell: git log failed in ${repo}`)
|
|
67
|
+
raw = []
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const show = (ref, p) => git(['show', `${ref}:${p}`])
|
|
72
|
+
const onBase = onBaseIn(git, base, span)
|
|
73
|
+
const commits = []
|
|
74
|
+
const events = []
|
|
75
|
+
let asked = 0
|
|
76
|
+
// `git log` is newest first, and a rebase stamps a run of commits with one
|
|
77
|
+
// committer second — so walk oldest first, and equal times keep that order.
|
|
78
|
+
raw.slice().reverse().forEach((c) => {
|
|
79
|
+
const landed = onBase.has(c.sha)
|
|
80
|
+
// Only an unlanded commit's branches say anything (`attributeCommit`), so
|
|
81
|
+
// only those are asked — and only up to the cap.
|
|
82
|
+
const branches = !landed && asked++ < CONTAINS_CAP ? branchesContaining(git, c.sha) : []
|
|
83
|
+
const spec = skitterspec ? attributeCommit({ ...c, onBase: landed, branches }, toSpec, specOfTicket) : null
|
|
84
|
+
// Where a commit with no spec is reported: the base branch when it is
|
|
85
|
+
// there, else the first branch holding it.
|
|
86
|
+
const branch = landed ? base : branches[0] || null
|
|
87
|
+
commits.push({ sha: c.sha.slice(0, SHORT), at: c.at, subject: c.subject, spec, branch, refs: c.refs })
|
|
88
|
+
if (skitterspec) {
|
|
89
|
+
for (const e of lifecycleEvents(c, show)) events.push({ ...e, sha: c.sha.slice(0, SHORT), at: c.at })
|
|
90
|
+
}
|
|
91
|
+
})
|
|
92
|
+
if (asked > CONTAINS_CAP) {
|
|
93
|
+
notes.push(`${asked} unlanded commits in ${path.basename(repo)} — past ${CONTAINS_CAP}, the rest are attributed by their files alone`)
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// The config's own name, else the repo's folder — the config is read without
|
|
97
|
+
// a checkout anchor, so `projectName` cannot fall back to the folder itself.
|
|
98
|
+
const name = projectName(config) || path.basename(repo)
|
|
99
|
+
return { name, category: projectCategory(config), skitterspec, base, toSpec, ticket, commits, events, notes }
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
module.exports = { readRepoFacts }
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The ta-da page as the review server serves it: `/<token>/_tada?on=…`,
|
|
5
|
+
* rendered per request like every other page there. Nothing is stored but the
|
|
6
|
+
* model's recap, a sidecar beside the review notes — the HTML never is, for
|
|
7
|
+
* the reason `env/serve.js` gives: a stored page is a photograph, and a
|
|
8
|
+
* served one cannot be out of date.
|
|
9
|
+
*
|
|
10
|
+
* The digest is the CLI's own answer (`skitterspec tada --json`), run in the
|
|
11
|
+
* server's project so its category scopes the report exactly as it would in a
|
|
12
|
+
* terminal there. One implementation, so the page and the terminal cannot
|
|
13
|
+
* disagree about what the day held.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const fs = require('node:fs')
|
|
17
|
+
const path = require('node:path')
|
|
18
|
+
const { execFile } = require('node:child_process')
|
|
19
|
+
|
|
20
|
+
const { windowFor, humanLabel, localDay } = require('./window.js')
|
|
21
|
+
const { renderTadaPage } = require('./page.js')
|
|
22
|
+
|
|
23
|
+
// `_tada`, not `tada`: the route shares a namespace with spec names, and a
|
|
24
|
+
// `/no-spec` branch may be called anything kebab-case — never with a leading
|
|
25
|
+
// underscore.
|
|
26
|
+
const ROUTE = '_tada'
|
|
27
|
+
|
|
28
|
+
const BIN = path.join(__dirname, '..', '..', 'bin', 'skitterspec.js')
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* What a request (or a CLI run) asks for, in one shape: the window as an
|
|
32
|
+
* absolute day so a link keeps meaning the same thing tomorrow, and the
|
|
33
|
+
* scope flags. `since` and `on` are both day strings (`YYYY-MM-DD`) or absent.
|
|
34
|
+
*/
|
|
35
|
+
function tadaQuery({ on = null, since = null, all = false, chat = false, here = false } = {}) {
|
|
36
|
+
const q = new URLSearchParams()
|
|
37
|
+
if (on) q.set('on', on)
|
|
38
|
+
else if (since) q.set('since', since)
|
|
39
|
+
if (all) q.set('all', '1')
|
|
40
|
+
if (chat) q.set('chat', '1')
|
|
41
|
+
if (here) q.set('here', '1')
|
|
42
|
+
const s = q.toString()
|
|
43
|
+
return s ? `?${s}` : ''
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The query back into a request — refusing a window it cannot read. */
|
|
47
|
+
function readTadaQuery(search, now = new Date()) {
|
|
48
|
+
const q = new URLSearchParams(search || '')
|
|
49
|
+
const on = q.get('on')
|
|
50
|
+
const since = q.get('since')
|
|
51
|
+
const window = windowFor({ on: on || undefined, since: since || undefined }, now)
|
|
52
|
+
const flag = (k) => ['1', 'true', ''].includes(q.get(k)) && q.has(k)
|
|
53
|
+
return { on, since, all: flag('all'), chat: flag('chat'), here: flag('here'), window }
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* The recap sidecar's name. Keyed by the window's START and kind, never its
|
|
58
|
+
* end: `--since friday` runs to now, so an end-keyed recap would be lost the
|
|
59
|
+
* next morning while the link that names it still works.
|
|
60
|
+
*/
|
|
61
|
+
function recapKey({ on, since, window, all, chat }) {
|
|
62
|
+
const kind = on ? 'on' : since ? 'since' : 'on'
|
|
63
|
+
return `${kind}-${localDay(window.since)}${all ? '-all' : ''}${chat ? '-chat' : ''}`
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function recapPath(stateDir, key) {
|
|
67
|
+
return path.join(stateDir, 'tada', `${key}.md`)
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The CLI's digest for one window, run where the server's project lives. */
|
|
71
|
+
function runDigest({ dir, ask, exec = execFile, bin = BIN }) {
|
|
72
|
+
const args = [bin, 'tada', '--json']
|
|
73
|
+
const day = localDay(ask.window.since)
|
|
74
|
+
if (ask.on) args.push('--on', day)
|
|
75
|
+
else if (ask.since) args.push('--since', day)
|
|
76
|
+
if (ask.all) args.push('--all-projects')
|
|
77
|
+
if (ask.chat) args.push('--chat')
|
|
78
|
+
// `--here` in the server's own project: the repo the page was asked for.
|
|
79
|
+
if (ask.here) args.push('--here')
|
|
80
|
+
return new Promise((resolve) => {
|
|
81
|
+
exec(process.execPath, args, { cwd: dir, timeout: 120_000, maxBuffer: 64 * 1024 * 1024 }, (err, stdout) => {
|
|
82
|
+
if (err) return resolve({ error: `cannot tell — the digest could not be built (${err.message.split('\n')[0]})` })
|
|
83
|
+
try {
|
|
84
|
+
resolve({ digest: JSON.parse(stdout) })
|
|
85
|
+
} catch {
|
|
86
|
+
resolve({ error: 'cannot tell — the digest was not readable' })
|
|
87
|
+
}
|
|
88
|
+
})
|
|
89
|
+
})
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* The route's whole answer: `{ html }`, or `{ status, error }` for the server
|
|
94
|
+
* to send as text. A window it cannot read is a 400 naming the fix — the
|
|
95
|
+
* server never guesses a day.
|
|
96
|
+
*/
|
|
97
|
+
async function renderServedTada({ dir, stateDir, search, project = null, now = new Date(), run = runDigest }) {
|
|
98
|
+
let ask
|
|
99
|
+
try {
|
|
100
|
+
ask = readTadaQuery(search, now)
|
|
101
|
+
} catch (e) {
|
|
102
|
+
return { status: 400, error: e.message }
|
|
103
|
+
}
|
|
104
|
+
const out = await run({ dir, ask })
|
|
105
|
+
if (out.error) return { status: 500, error: out.error }
|
|
106
|
+
let recap = null
|
|
107
|
+
let writtenAt = null
|
|
108
|
+
try {
|
|
109
|
+
const file = recapPath(stateDir, recapKey(ask))
|
|
110
|
+
recap = fs.readFileSync(file, 'utf8')
|
|
111
|
+
writtenAt = fs.statSync(file).mtime
|
|
112
|
+
} catch {
|
|
113
|
+
// No recap saved for this window is an ordinary state: the page is the
|
|
114
|
+
// digest alone, which is still the day's facts.
|
|
115
|
+
}
|
|
116
|
+
return {
|
|
117
|
+
html: renderTadaPage(out.digest, {
|
|
118
|
+
recap,
|
|
119
|
+
writtenAt,
|
|
120
|
+
title: `Ta-da · ${humanLabel(ask.window)}`,
|
|
121
|
+
project,
|
|
122
|
+
category: out.digest.category || null,
|
|
123
|
+
}),
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
module.exports = { ROUTE, tadaQuery, readTadaQuery, recapKey, recapPath, renderServedTada, runDigest }
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Turning git facts into spec facts for a ta-da list: which spec a branch
|
|
5
|
+
* belongs to, which lifecycle moves a commit made, and which spec a commit on
|
|
6
|
+
* the base branch was about. Pure — every input arrives already read.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { splitPrefix, phaseIsDone } = require('../env/resolve.js')
|
|
10
|
+
|
|
11
|
+
const TYPES = 'feat|bug|hotfix|chore|issue|incident|epic'
|
|
12
|
+
const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
13
|
+
|
|
14
|
+
// A spec document's path, anywhere in the repo — a project may sit in a
|
|
15
|
+
// subfolder, so the `specs/` segment is matched rather than anchored.
|
|
16
|
+
const SPEC_PATH = new RegExp(`(?:^|/)specs/(${BUCKETS.join('|')})/([^/]+)/([^/]+)$`)
|
|
17
|
+
|
|
18
|
+
function specPath(p) {
|
|
19
|
+
const m = SPEC_PATH.exec(p)
|
|
20
|
+
return m ? { bucket: m[1], name: m[2], file: m[3] } : null
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* A branch name → the spec it was provisioned for, read back through the
|
|
27
|
+
* project's `branch.pattern`. `{type}` and `{slug}` give the name outright;
|
|
28
|
+
* a pattern without `{type}` names a slug, which only counts when exactly one
|
|
29
|
+
* known spec carries it — two would make the answer a guess.
|
|
30
|
+
*
|
|
31
|
+
* @param {string} pattern `branch.pattern`, e.g. `{type}/{slug}`
|
|
32
|
+
* @param {string[]} known spec folder names this repo can see
|
|
33
|
+
* @returns {(branch: string) => string|null}
|
|
34
|
+
*/
|
|
35
|
+
function branchToSpec(pattern, known = []) {
|
|
36
|
+
const p = pattern || '{type}/{slug}'
|
|
37
|
+
if (!p.includes('{slug}')) return () => null
|
|
38
|
+
const shape = (slug) =>
|
|
39
|
+
new RegExp(
|
|
40
|
+
`^${escape(p).replace(/\\\{(type|slug|identifier)\\\}/g, (_, token) => {
|
|
41
|
+
if (token === 'type') return `(?<type>${TYPES})`
|
|
42
|
+
if (token === 'identifier') return '[^/]+'
|
|
43
|
+
return slug === null ? '(?<slug>.+)' : escape(slug)
|
|
44
|
+
})}$`,
|
|
45
|
+
)
|
|
46
|
+
if (p.includes('{type}')) {
|
|
47
|
+
const re = shape(null)
|
|
48
|
+
return (branch) => {
|
|
49
|
+
const m = branch && re.exec(branch)
|
|
50
|
+
return m ? `${m.groups.type}-${m.groups.slug}` : null
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
// No `{type}`: where `{slug}` ends is ambiguous beside an `{identifier}`
|
|
54
|
+
// (`ABC-12-orders`), so each known spec's slug is tried as a literal.
|
|
55
|
+
const shapes = known.map((k) => [k, shape(splitPrefix(k).slug)])
|
|
56
|
+
return (branch) => {
|
|
57
|
+
if (!branch) return null
|
|
58
|
+
const hits = shapes.filter(([, re]) => re.test(branch)).map(([k]) => k)
|
|
59
|
+
return hits.length === 1 ? hits[0] : null
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The lifecycle moves one commit made, from its `--name-status` lines and,
|
|
65
|
+
* for a phase, the file's text either side of it.
|
|
66
|
+
*
|
|
67
|
+
* @param {object} commit `{ sha, files: [{ status, path, from? }] }`
|
|
68
|
+
* @param {(ref: string, path: string) => string|null} show `git show ref:path`
|
|
69
|
+
* @returns {Array<{ spec, kind, phase? }>}
|
|
70
|
+
* kind: written · started · completed · cancelled · phase-done
|
|
71
|
+
*/
|
|
72
|
+
function lifecycleEvents(commit, show) {
|
|
73
|
+
const events = []
|
|
74
|
+
const seen = new Set()
|
|
75
|
+
const add = (spec, kind, extra = {}) => {
|
|
76
|
+
const key = `${spec}\0${kind}\0${extra.phase || ''}`
|
|
77
|
+
if (seen.has(key)) return
|
|
78
|
+
seen.add(key)
|
|
79
|
+
events.push({ spec, kind, ...extra })
|
|
80
|
+
}
|
|
81
|
+
for (const f of commit.files) {
|
|
82
|
+
const to = specPath(f.path)
|
|
83
|
+
if (!to) continue
|
|
84
|
+
if (f.status === 'R' && f.from) {
|
|
85
|
+
const from = specPath(f.from)
|
|
86
|
+
if (from && from.name === to.name && from.bucket !== to.bucket) {
|
|
87
|
+
if (to.bucket === 'in-progress') add(to.name, 'started')
|
|
88
|
+
else if (to.bucket === 'complete') add(to.name, 'completed')
|
|
89
|
+
else if (to.bucket === 'cancelled') add(to.name, 'cancelled')
|
|
90
|
+
}
|
|
91
|
+
continue
|
|
92
|
+
}
|
|
93
|
+
// `/spec` writes into backlog; `/spec-bug` and its kin write straight into
|
|
94
|
+
// in-progress, so a new overview in either is a spec being written.
|
|
95
|
+
if (f.status === 'A' && to.file === '00-overview.md' && (to.bucket === 'backlog' || to.bucket === 'in-progress')) {
|
|
96
|
+
add(to.name, 'written')
|
|
97
|
+
continue
|
|
98
|
+
}
|
|
99
|
+
const phase = /^(\d+)-.+\.md$/.exec(to.file)
|
|
100
|
+
if (f.status === 'M' && phase && Number(phase[1]) > 0) {
|
|
101
|
+
const after = show(commit.sha, f.path)
|
|
102
|
+
const before = show(`${commit.sha}^`, f.path)
|
|
103
|
+
// Both sides must be read: a phase file git could not show either side
|
|
104
|
+
// of is cannot-tell, never a phase someone finished.
|
|
105
|
+
if (after !== null && before !== null && phaseIsDone(after) && !phaseIsDone(before)) {
|
|
106
|
+
add(to.name, 'phase-done', { phase: Number(phase[1]) })
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return events
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** The one spec a commit's documents belong to, or null when none or several. */
|
|
114
|
+
function specTouched(commit) {
|
|
115
|
+
const names = new Set(commit.files.map((f) => specPath(f.path)).filter(Boolean).map((s) => s.name))
|
|
116
|
+
return names.size === 1 ? [...names][0] : null
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Which spec a commit belongs to: a branch that maps to a spec, then the one
|
|
121
|
+
* spec folder it touched, then its `Refs:` ticket. Anything else is `null` —
|
|
122
|
+
* reported under its branch as no spec.
|
|
123
|
+
*
|
|
124
|
+
* THE BRANCH IS ASKED ONLY OF A COMMIT NOT YET ON THE BASE. Containment is
|
|
125
|
+
* not authorship: a spec branch forked this afternoon contains every commit
|
|
126
|
+
* the base had this morning, so asking it about a landed commit attributes the
|
|
127
|
+
* whole day to whichever spec was started last. A landed commit is answered by
|
|
128
|
+
* what it carries — its files and its trailer — which do not move.
|
|
129
|
+
*
|
|
130
|
+
* @param {object} commit `{ onBase, branches, files, refs }`
|
|
131
|
+
* @param {(b: string) => string|null} toSpec
|
|
132
|
+
* @param {(id: string) => string|null} specOfTicket ticket id → spec, asked
|
|
133
|
+
* only when nothing else answered, since it is the one lookup that searches
|
|
134
|
+
*/
|
|
135
|
+
function attributeCommit(commit, toSpec, specOfTicket) {
|
|
136
|
+
const touched = specTouched(commit)
|
|
137
|
+
if (!commit.onBase) {
|
|
138
|
+
const fromBranch = commit.branches.map(toSpec).filter(Boolean)
|
|
139
|
+
if (fromBranch.length) return touched && fromBranch.includes(touched) ? touched : fromBranch[0]
|
|
140
|
+
}
|
|
141
|
+
if (touched) return touched
|
|
142
|
+
const tickets = [...new Set(commit.refs.map(specOfTicket).filter(Boolean))]
|
|
143
|
+
return tickets.length === 1 ? tickets[0] : null
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
module.exports = { BUCKETS, attributeCommit, branchToSpec, lifecycleEvents, specPath, specTouched }
|