@skitterbyte/skitterspec-jira 2.3.0 → 2.5.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/claude-md-section.md +20 -1
- package/assets/core/SETUP.md +5 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +143 -8
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +40 -6
- package/assets/hooks/review-gate.cjs +42 -7
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +25 -1
- package/assets/skills/spec-cancel/SKILL.md +35 -0
- package/assets/skills/spec-complete/SKILL.md +113 -0
- package/assets/skills/spec-hotfix/SKILL.md +40 -2
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-jira-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +9 -4
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +32 -0
- package/assets/skills/spec-start/SKILL.md +39 -1
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1188 -79
- package/src/env/base.js +104 -0
- package/src/env/bootstrap.js +22 -3
- package/src/env/classify.js +12 -4
- package/src/env/config.js +77 -5
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +81 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +237 -9
- package/src/env/hotfixland.js +105 -10
- package/src/env/inflight.js +98 -0
- package/src/env/integrate.js +136 -9
- package/src/env/live.js +8 -7
- package/src/env/mainguard.js +20 -5
- package/src/env/phases.js +28 -0
- package/src/env/project.js +223 -0
- package/src/env/provision.js +30 -8
- package/src/env/resolve.js +147 -25
- package/src/env/review.js +21 -7
- package/src/env/reviewers.js +7 -10
- package/src/env/serve.js +27 -11
- package/src/env/specstate.js +101 -0
- package/src/env/supervise.js +15 -2
- package/src/env/teardown.js +46 -3
- package/src/init.js +49 -9
- package/src/vendor/jira/cli-sync.js +48 -4
- package/src/vendor/jira/config.js +17 -5
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +58 -6
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/credentials.js +7 -2
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +48 -4
- package/src/vendor/provider-kit/src/specs.js +18 -7
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +81 -6
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +65 -5
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The SUMMARY BLOCK — what a ticket carries under `mapping.description:
|
|
5
|
+
* "summary"`. The spec stays in git; the ticket gets a short, delimited block
|
|
6
|
+
* (what the work is, what done looks like, what it touches) and the repo owns
|
|
7
|
+
* that block and nothing else in the description. Text a team writes around it
|
|
8
|
+
* survives every push.
|
|
9
|
+
*
|
|
10
|
+
* Writing it is a SPLICE, not a pull: the live description is read so the
|
|
11
|
+
* block can be replaced in place, and nothing outside the block is parsed,
|
|
12
|
+
* merged, hashed or written back to the spec.
|
|
13
|
+
*
|
|
14
|
+
* Pure: no I/O, no clock, no randomness.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
const path = require('node:path')
|
|
18
|
+
|
|
19
|
+
// The two delimiter styles. `comment` is invisible where the tracker keeps
|
|
20
|
+
// HTML comments verbatim (GitHub, measured 2026-11-08); `heading` is the
|
|
21
|
+
// fallback where it may not. Which a provider uses is its config's call
|
|
22
|
+
// (`summary.delimiter`), never guessed from the text.
|
|
23
|
+
const DELIMITERS = Object.freeze({
|
|
24
|
+
comment: Object.freeze({ begin: '<!-- skitterspec:begin -->', end: '<!-- skitterspec:end -->' }),
|
|
25
|
+
heading: Object.freeze({ begin: '## Skitterspec summary', end: '_— end of skitterspec summary —_' }),
|
|
26
|
+
})
|
|
27
|
+
|
|
28
|
+
// `spec` (the whole overview, as before) unless the config says `summary`.
|
|
29
|
+
// ABSENT MEANS `spec`, deliberately: a config written before this key existed
|
|
30
|
+
// must push exactly what it always pushed, so an upgrade rewrites no ticket.
|
|
31
|
+
function descriptionMode(config) {
|
|
32
|
+
const mode = config && config.mapping && config.mapping.description
|
|
33
|
+
return mode === 'summary' ? 'summary' : 'spec'
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function delimitersFor(config) {
|
|
37
|
+
const style = config && config.summary && config.summary.delimiter
|
|
38
|
+
return DELIMITERS[style] || DELIMITERS.heading
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const countOf = (text, needle) => text.split(needle).length - 1
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Where the block sits in a description.
|
|
45
|
+
*
|
|
46
|
+
* THREE STATES, and the third is why this returns more than a boolean:
|
|
47
|
+
*
|
|
48
|
+
* - `present` — exactly one begin, then exactly one end after it;
|
|
49
|
+
* - `absent` — neither delimiter appears;
|
|
50
|
+
* - `damaged` — anything else: a begin with no end, an end with no begin,
|
|
51
|
+
* two of either. Someone has edited a delimiter line, and the edges of the
|
|
52
|
+
* block cannot be told apart from the team's text around it.
|
|
53
|
+
*
|
|
54
|
+
* `damaged` is cannot-tell and every caller routes it to the harmless branch:
|
|
55
|
+
* the description is not written, and no edit is reported. Splicing into it
|
|
56
|
+
* could eat a paragraph that was never the repo's; prepending a second block
|
|
57
|
+
* would leave two (`.claude/rules/negative-checks.md` rule 4).
|
|
58
|
+
*/
|
|
59
|
+
function blockOf(text, config) {
|
|
60
|
+
const t = typeof text === 'string' ? text : ''
|
|
61
|
+
const { begin, end } = delimitersFor(config)
|
|
62
|
+
const begins = countOf(t, begin)
|
|
63
|
+
const ends = countOf(t, end)
|
|
64
|
+
if (begins === 0 && ends === 0) return { state: 'absent' }
|
|
65
|
+
if (begins !== 1 || ends !== 1) return { state: 'damaged' }
|
|
66
|
+
const start = t.indexOf(begin)
|
|
67
|
+
const close = t.indexOf(end)
|
|
68
|
+
if (close < start) return { state: 'damaged' }
|
|
69
|
+
const stop = close + end.length
|
|
70
|
+
return { state: 'present', start, end: stop, block: t.slice(start, stop) }
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function wrapBlock(inner, config) {
|
|
74
|
+
const { begin, end } = delimitersFor(config)
|
|
75
|
+
return `${begin}\n${String(inner || '').trim()}\n${end}`
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Put `block` (a whole wrapped block) into `live`, leaving every other byte of
|
|
80
|
+
* `live` as it was. An absent block goes first, above the team's text. Returns
|
|
81
|
+
* null when the existing block is damaged — the caller must not write.
|
|
82
|
+
*/
|
|
83
|
+
function spliceBlock(live, block, config) {
|
|
84
|
+
const text = typeof live === 'string' ? live : ''
|
|
85
|
+
const at = blockOf(text, config)
|
|
86
|
+
if (at.state === 'damaged') return null
|
|
87
|
+
if (at.state === 'present') return text.slice(0, at.start) + block + text.slice(at.end)
|
|
88
|
+
return text.trim() ? `${block}\n\n${text}` : block
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* The part of a tracker description that is the repo's to compare: the whole
|
|
93
|
+
* text in `spec` mode, the block alone in `summary` mode. Null when summary mode
|
|
94
|
+
* finds no intact block — cannot-tell for drift, and the caller decides whether
|
|
95
|
+
* an absent block is a loss (right after a write it is).
|
|
96
|
+
*/
|
|
97
|
+
function comparableDescription(text, config) {
|
|
98
|
+
if (typeof text !== 'string') return null
|
|
99
|
+
if (descriptionMode(config) !== 'summary') return text
|
|
100
|
+
const at = blockOf(text, config)
|
|
101
|
+
return at.state === 'present' ? at.block : null
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// --- the block's parts ------------------------------------------------------
|
|
105
|
+
|
|
106
|
+
function firstParagraph(text) {
|
|
107
|
+
const t = String(text || '').trim()
|
|
108
|
+
if (!t) return ''
|
|
109
|
+
return t.split(/\n\s*\n/)[0].trim()
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// A markdown table's rows as `{ header: cell }` objects. Header and separator
|
|
113
|
+
// rows are consumed; a line that is not a table row ends the table.
|
|
114
|
+
function tableRows(text) {
|
|
115
|
+
const lines = String(text || '')
|
|
116
|
+
.split('\n')
|
|
117
|
+
.map((l) => l.trim())
|
|
118
|
+
.filter((l) => l.startsWith('|'))
|
|
119
|
+
if (lines.length < 2) return []
|
|
120
|
+
const cells = (l) =>
|
|
121
|
+
l
|
|
122
|
+
.replace(/^\|/, '')
|
|
123
|
+
.replace(/\|$/, '')
|
|
124
|
+
.split('|')
|
|
125
|
+
.map((c) => c.trim())
|
|
126
|
+
const header = cells(lines[0]).map((h) => h.toLowerCase())
|
|
127
|
+
return lines
|
|
128
|
+
.slice(2)
|
|
129
|
+
.map(cells)
|
|
130
|
+
.map((row) => Object.fromEntries(header.map((h, i) => [h, row[i] || ''])))
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
// The Impact table as one line: each row's Detail, else its Surface. Detail is
|
|
134
|
+
// what names the thing (`POST /orders`); Surface alone is its category
|
|
135
|
+
// (`Endpoint`), which tells a ticket reader nothing.
|
|
136
|
+
function touches(sections) {
|
|
137
|
+
const impact = sections.Impact
|
|
138
|
+
if (!impact) return ''
|
|
139
|
+
const named = tableRows(impact)
|
|
140
|
+
.map((r) => r.detail || r.surface || '')
|
|
141
|
+
.map((s) => s.trim())
|
|
142
|
+
.filter(Boolean)
|
|
143
|
+
return [...new Set(named)].join(' · ')
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// The value of a `> **Field:** value` header line, or ''.
|
|
147
|
+
function headerValue(body, field) {
|
|
148
|
+
const m = String(body || '').match(new RegExp(`^>\\s*\\*\\*${field}:\\*\\*\\s*(.+)$`, 'm'))
|
|
149
|
+
return m ? m[1].trim() : ''
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
// The acceptance criteria as a checklist: every list item becomes `- [ ]`,
|
|
153
|
+
// keeping a `[x]` the author ticked. Prose between items is kept as written.
|
|
154
|
+
function criteria(sections) {
|
|
155
|
+
const text = sections['Acceptance criteria']
|
|
156
|
+
if (!text) return ''
|
|
157
|
+
return String(text)
|
|
158
|
+
.trim()
|
|
159
|
+
.split('\n')
|
|
160
|
+
.map((line) => {
|
|
161
|
+
const m = line.match(/^(\s*)[-*+]\s+(\[[ xX]\]\s+)?(.*)$/)
|
|
162
|
+
if (!m) return line
|
|
163
|
+
const box = m[2] && /x/i.test(m[2]) ? '[x]' : '[ ]'
|
|
164
|
+
return `${m[1]}- ${box} ${m[3]}`
|
|
165
|
+
})
|
|
166
|
+
.join('\n')
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// `specs/<bucket>/<name>` — where the spec lives, for a reader who wants more.
|
|
170
|
+
function specPath(snapshotDir) {
|
|
171
|
+
const dir = String(snapshotDir || '')
|
|
172
|
+
return ['specs', path.basename(path.dirname(dir)), path.basename(dir)].join('/')
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* The spec ticket's block content (unwrapped). Every part is skipped, never
|
|
177
|
+
* invented, when its source is absent — a spec with no Summary, criteria,
|
|
178
|
+
* Impact table or Gating header still gets a block: its Problem and its path.
|
|
179
|
+
*/
|
|
180
|
+
function specBlockInner({ snapshotDir, sections, body, phases }) {
|
|
181
|
+
const summary =
|
|
182
|
+
String(sections.Summary || '').trim() || firstParagraph(sections.Problem) || firstParagraph(sections.Symptom)
|
|
183
|
+
const parts = []
|
|
184
|
+
if (summary) parts.push(summary)
|
|
185
|
+
const ac = criteria(sections)
|
|
186
|
+
if (ac) parts.push(`**Acceptance criteria**\n\n${ac}`)
|
|
187
|
+
const t = touches(sections)
|
|
188
|
+
if (t) parts.push(`**Touches** ${t}`)
|
|
189
|
+
const gating = headerValue(body, 'Gating')
|
|
190
|
+
if (gating) parts.push(`**Gating** ${gating}`)
|
|
191
|
+
const progress = progressLine(phases)
|
|
192
|
+
if (progress) parts.push(progress)
|
|
193
|
+
parts.push(`**Spec** \`${specPath(snapshotDir)}\``)
|
|
194
|
+
return parts.join('\n\n')
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// --- progress -----------------------------------------------------------------
|
|
198
|
+
|
|
199
|
+
// A phase's checkboxes: every task bullet, nested ones included, each counted
|
|
200
|
+
// once. Only `x` is done — `[~]`, `[>]`, `[-]` are not (task-block.js).
|
|
201
|
+
function taskCounts(phase) {
|
|
202
|
+
const boxes = ((phase && phase.blocks) || []).filter((b) => b && b.checkbox)
|
|
203
|
+
return { ticked: boxes.filter((b) => b.mark === 'x').length, total: boxes.length }
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* How far along a spec is, from its phase files' own checkboxes.
|
|
208
|
+
*
|
|
209
|
+
* `null` when there is not a single checkbox anywhere: that is cannot-tell, not
|
|
210
|
+
* 0%. A spec written without task lists has not "made no progress", and a
|
|
211
|
+
* ticket reading 0% for its whole life would say exactly that.
|
|
212
|
+
*
|
|
213
|
+
* `phase` is the one being worked: the first in progress, else the first not
|
|
214
|
+
* done, else the last (everything is done).
|
|
215
|
+
*/
|
|
216
|
+
function progressOf(phases) {
|
|
217
|
+
const list = (phases || []).filter((p) => p && p.name)
|
|
218
|
+
let ticked = 0
|
|
219
|
+
let total = 0
|
|
220
|
+
for (const p of list) {
|
|
221
|
+
const c = taskCounts(p)
|
|
222
|
+
ticked += c.ticked
|
|
223
|
+
total += c.total
|
|
224
|
+
}
|
|
225
|
+
if (!total) return null
|
|
226
|
+
let at = list.findIndex((p) => p.state === 'in-progress')
|
|
227
|
+
if (at === -1) at = list.findIndex((p) => p.state !== 'complete')
|
|
228
|
+
if (at === -1) at = list.length - 1
|
|
229
|
+
return { ticked, total, percent: Math.floor((ticked / total) * 100), phase: at + 1, phases: list.length }
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function progressLine(phases) {
|
|
233
|
+
const p = progressOf(phases)
|
|
234
|
+
return p ? `**Progress** ${p.percent}% · phase ${p.phase} of ${p.phases}` : ''
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
// A phase sub-issue's block content: its goal, and its task count when it has
|
|
238
|
+
// any checkboxes (a phase with none says nothing rather than `0 of 0`).
|
|
239
|
+
function phaseBlockInner(phase) {
|
|
240
|
+
const goal = String((phase && phase.goal) || '').trim() || String((phase && phase.name) || '').trim()
|
|
241
|
+
const { ticked, total } = taskCounts(phase)
|
|
242
|
+
return total ? `${goal}\n\n**Progress** ${ticked} of ${total} tasks` : goal
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
module.exports = {
|
|
246
|
+
DELIMITERS,
|
|
247
|
+
descriptionMode,
|
|
248
|
+
delimitersFor,
|
|
249
|
+
blockOf,
|
|
250
|
+
wrapBlock,
|
|
251
|
+
spliceBlock,
|
|
252
|
+
comparableDescription,
|
|
253
|
+
specBlockInner,
|
|
254
|
+
phaseBlockInner,
|
|
255
|
+
progressOf,
|
|
256
|
+
tableRows,
|
|
257
|
+
}
|