@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.
Files changed (46) hide show
  1. package/README.md +3 -1
  2. package/assets/claude-md-section.md +6 -0
  3. package/assets/core/env.config.json.example +5 -0
  4. package/assets/core/env.config.md +26 -5
  5. package/assets/review/page.html +9 -0
  6. package/assets/rules/spec-planning.md +65 -12
  7. package/assets/rules/spec-reports.md +8 -1
  8. package/assets/skills/spec/SKILL.md +31 -14
  9. package/assets/skills/spec-cancel/SKILL.md +7 -0
  10. package/assets/skills/spec-complete/SKILL.md +6 -0
  11. package/assets/skills/spec-epic-next/SKILL.md +83 -0
  12. package/assets/skills/spec-init/SKILL.md +35 -3
  13. package/assets/skills/spec-next/SKILL.md +38 -1
  14. package/assets/skills/spec-start/SKILL.md +2 -2
  15. package/assets/skills/spec-tada/SKILL.md +153 -0
  16. package/bin/skitterspec-linear.js +5 -0
  17. package/package.json +1 -1
  18. package/src/cli.js +473 -25
  19. package/src/env/config.js +57 -6
  20. package/src/env/epic.js +69 -19
  21. package/src/env/epicpage.js +87 -39
  22. package/src/env/epicread.js +41 -3
  23. package/src/env/integrate.js +48 -1
  24. package/src/env/nextaction.js +78 -1
  25. package/src/env/project.js +54 -3
  26. package/src/env/projectedit.js +148 -0
  27. package/src/env/resolve.js +1 -0
  28. package/src/env/review.js +21 -3
  29. package/src/env/serve.js +44 -8
  30. package/src/env/specbranches.js +120 -0
  31. package/src/env/teardown.js +18 -3
  32. package/src/gating.js +16 -4
  33. package/src/init.js +11 -3
  34. package/src/tada/commits.js +145 -0
  35. package/src/tada/digest.js +260 -0
  36. package/src/tada/format.js +37 -0
  37. package/src/tada/page.js +213 -0
  38. package/src/tada/repo.js +102 -0
  39. package/src/tada/serve.js +127 -0
  40. package/src/tada/specs.js +146 -0
  41. package/src/tada/transcripts.js +258 -0
  42. package/src/tada/window.js +156 -0
  43. package/src/vendor/provider-kit/src/apply.js +25 -1
  44. package/src/vendor/sync-core/src/compare.js +10 -2
  45. package/src/vendor/sync-core/src/push.js +14 -3
  46. /package/assets/commands/{epic.md → spec-epic.md} +0 -0
@@ -47,6 +47,15 @@ function planDown(spec, config, flags, ctx) {
47
47
  // can use `-D` — the same question ("are these commits recoverable?"), so the
48
48
  // two must never answer it differently.
49
49
  const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
50
+ // A spec-documents-only branch under `land.specDocs: "branch"` — authored,
51
+ // perhaps pushed, never started (feat-tracker-spec-branches). It holds no
52
+ // code to lose and was never meant to have a PR, and left on the remote it
53
+ // reads as backlog to every check that scans spec branches. `docsOnly` is a
54
+ // positive signal the caller computes from the branch's own range; anything
55
+ // it cannot read stays false, which keeps every guard below as it was.
56
+ const docsLane = Boolean(
57
+ worktreeState.docsOnly && config.land && config.land.specDocs === 'branch',
58
+ )
50
59
 
51
60
  // --- guards (overridable with --force) ---
52
61
  if (!force) {
@@ -69,7 +78,7 @@ function planDown(spec, config, flags, ctx) {
69
78
  // PR and the exit where git's cannot. `--force` bypasses, and still plans
70
79
  // `-d` below, so a genuinely unlanded branch fails loudly rather than
71
80
  // being -D'd.
72
- if (config.land && config.land.strategy === 'pr' && !landed) {
81
+ if (config.land && config.land.strategy === 'pr' && !landed && !docsLane) {
73
82
  const prState = worktreeState.prState
74
83
  const at = worktreeState.prUrl ? ` — see ${worktreeState.prUrl}` : ''
75
84
  if (prState === 'open' || prState === 'draft') {
@@ -188,9 +197,15 @@ function planDown(spec, config, flags, ctx) {
188
197
  // this delete a no-op: `git push --delete` errors with "remote ref does not
189
198
  // exist", which is loud and destroys nothing. The skills report that as
190
199
  // already-gone, never as a failed teardown.
200
+ //
201
+ // The docs lane is the one unlanded branch that may be offered: its remote
202
+ // copy backs up only the spec document being cancelled, and the ticket keeps
203
+ // the record. It is ALWAYS confirm-first — "always" folds the landed delete
204
+ // into the run-blind list, but deleting the last copy of a document is not
205
+ // what that policy was set for.
191
206
  const remoteCommands = []
192
207
  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
193
- if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
208
+ if (spec.branch && (landed || docsLane) && worktreeState.remoteBranch && policy !== 'never') {
194
209
  // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
195
210
  // itself contains slashes, so the remote is what remains once the exact
196
211
  // "/<branch>" suffix is stripped — not the text before the first slash.
@@ -206,7 +221,7 @@ function planDown(spec, config, flags, ctx) {
206
221
  const cmd = `git push ${remote} --delete ${spec.branch}`
207
222
  // "always" is the project saying it never wants to be asked, so the push
208
223
  // joins the run-blind list. Everything else keeps it quarantined.
209
- if (policy === 'always') commands.push(cmd)
224
+ if (policy === 'always' && landed) commands.push(cmd)
210
225
  else remoteCommands.push(cmd)
211
226
  }
212
227
  }
package/src/gating.js CHANGED
@@ -15,6 +15,7 @@
15
15
 
16
16
  const fs = require('node:fs')
17
17
  const path = require('node:path')
18
+ const { preferBranches, branchLabel } = require('./env/specbranches.js')
18
19
 
19
20
  const CONFIG_FILE = path.join('specs', '.core', 'gating.config.json')
20
21
 
@@ -87,6 +88,12 @@ function readGatingField(specPath) {
87
88
  } catch {
88
89
  return { raw: null, kind: 'missing' }
89
90
  }
91
+ return readGatingText(raw)
92
+ }
93
+
94
+ // The same reading over an overview's text — a spec read off its own branch
95
+ // (`env/specbranches.js`) has text and no path on disk.
96
+ function readGatingText(raw) {
90
97
  const m = /^>\s*\*\*Gating:\*\*\s*(.*)$/m.exec(raw)
91
98
  if (!m) return { raw: null, kind: 'missing' }
92
99
  const value = m[1].trim().replace(/^["'`]|["'`]$/g, '')
@@ -130,15 +137,19 @@ function activeSpecs(dir) {
130
137
  * @returns {{configured: boolean, findings: Array<{folder, bucket, kind, raw}>,
131
138
  * checked: number, guidance: string}}
132
139
  */
133
- function checkGating(dir, specs) {
140
+ function checkGating(dir, specs, { branches = [] } = {}) {
134
141
  const { config, present } = loadGatingConfig(dir)
135
142
  if (!present) return { configured: false, findings: [], checked: 0, guidance: '' }
136
- const targets = specs && specs.length ? specs : activeSpecs(dir)
143
+ // Branch copies (`env/specbranches.js`) win over the disk copy of the same
144
+ // spec and add the ones the base branch cannot see; finished buckets are not
145
+ // gating's business either way.
146
+ const active = branches.filter((b) => ACTIVE_BUCKETS.includes(b.bucket))
147
+ const targets = specs && specs.length ? specs : preferBranches(activeSpecs(dir), active)
137
148
  const findings = []
138
149
  for (const spec of targets) {
139
- const { kind, raw } = readGatingField(spec.path)
150
+ const { kind, raw } = spec.ref ? readGatingText(spec.overview) : readGatingField(spec.path)
140
151
  if (kind === 'missing' || kind === 'invalid') {
141
- findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw })
152
+ findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw, ...(spec.ref ? { from: branchLabel(spec) } : {}) })
142
153
  }
143
154
  }
144
155
  return { configured: true, findings, checked: targets.length, guidance: config.guidance }
@@ -150,6 +161,7 @@ module.exports = {
150
161
  ACTIVE_BUCKETS,
151
162
  loadGatingConfig,
152
163
  readGatingField,
164
+ readGatingText,
153
165
  activeSpecs,
154
166
  checkGating,
155
167
  }
package/src/init.js CHANGED
@@ -9,6 +9,7 @@ const { ensureWorktreeDirTrusted } = require('./env/trust.js')
9
9
  const { ensureHooks } = require('./env/hooks.js')
10
10
  const { repoInfo, expandTokens } = require('./env/resolve.js')
11
11
  const { primaryAnchor } = require('./env/project.js')
12
+ const { setProjectKeys } = require('./env/projectedit.js')
12
13
 
13
14
  const ASSETS = path.join(__dirname, '..', 'assets')
14
15
 
@@ -691,7 +692,7 @@ function installCore(dir, opts) {
691
692
  // Only called when the operator opts in, and never on `update` (adopting isolation
692
693
  // is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
693
694
  // never clobbers an existing env.config.json without --force.
694
- function installIsolation(dir, { enabled, workspaceMode }, opts) {
695
+ function installIsolation(dir, { enabled, workspaceMode, project = {} }, opts) {
695
696
  if (!enabled) return
696
697
  const target = path.join(dir, 'specs', '.core', 'env.config.json')
697
698
  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
@@ -705,6 +706,13 @@ function installIsolation(dir, { enabled, workspaceMode }, opts) {
705
706
  parsed.mode = 'checkout'
706
707
  fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
707
708
  }
709
+ // --name / --category, edited in rather than regenerated, so a config the
710
+ // operator already customized keeps everything but the two values asked for.
711
+ if ((typeof project.name === 'string' || typeof project.category === 'string') && fs.existsSync(target)) {
712
+ const text = fs.readFileSync(target, 'utf8')
713
+ const edited = setProjectKeys(text, project)
714
+ if (edited !== text) fs.writeFileSync(target, edited)
715
+ }
708
716
  trustWorktreeRoot(dir)
709
717
  }
710
718
 
@@ -1137,7 +1145,7 @@ function suggestReleaseWith(dir) {
1137
1145
  )
1138
1146
  }
1139
1147
 
1140
- async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating }) {
1148
+ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project }) {
1141
1149
  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
1142
1150
  resetReport()
1143
1151
 
@@ -1149,7 +1157,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
1149
1157
  removeRetiredFiles(dir)
1150
1158
  installCore(dir, { force })
1151
1159
  // Adopting isolation writes the live env.config.json — init only, never update.
1152
- if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
1160
+ if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode, project }, { force })
1153
1161
  if (mode !== 'update') installGating(dir, { enabled: gating }, { force })
1154
1162
  if (claudeMd) installClaudeMd(dir, { mode })
1155
1163
  suggestReleaseWith(dir)
@@ -0,0 +1,145 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * A repo's side of the ta-da list: the author's commits in the window, which
5
+ * branches hold each one, and the tickets its specs carry. Every git call
6
+ * goes through an injected reader — `(args) => stdout | null` — so this is
7
+ * testable against a throwaway repo and never shells out on its own.
8
+ */
9
+
10
+ const { readTicket } = require('../env/resolve.js')
11
+ const { BUCKETS } = require('./specs.js')
12
+
13
+ const RS = '\x1e'
14
+ const US = '\x1f'
15
+
16
+ // Past this many commits in one window the per-commit branch lookup is the
17
+ // slow half; the commits are still listed, attributed by their files alone.
18
+ const CONTAINS_CAP = 200
19
+
20
+ const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
21
+
22
+ /**
23
+ * Who "you" are in this repo: its own `user.email`, else `user.name`. Read per
24
+ * repo because a work repo and a personal one often carry different
25
+ * identities. Null is cannot-tell — the caller says so rather than reporting
26
+ * a day with no commits.
27
+ */
28
+ function authorOf(git) {
29
+ const email = git(['config', 'user.email'])
30
+ if (email) return { match: escapeRegex(email), who: email }
31
+ const name = git(['config', 'user.name'])
32
+ if (name) return { match: escapeRegex(name), who: name }
33
+ return null
34
+ }
35
+
36
+ /**
37
+ * The author's non-merge commits in the window, on any ref, each with the
38
+ * files it touched and its `Refs:` trailers.
39
+ *
40
+ * @returns {Array<{ sha, at, subject, refs: string[], files }>|null}
41
+ * null when git could not be read at all
42
+ */
43
+ function readCommits(git, { since, until, author }) {
44
+ const out = git([
45
+ 'log',
46
+ // Every ref but the stash: a stash entry is a commit too, and `--all`
47
+ // reports it as work ("index on feat/x: …") done twice.
48
+ '--exclude=refs/stash',
49
+ '--all',
50
+ '--no-merges',
51
+ `--since=${since}`,
52
+ `--until=${until}`,
53
+ `--author=${author}`,
54
+ '--name-status',
55
+ '-M',
56
+ `--format=${RS}%H${US}%cI${US}%s${US}%(trailers:key=Refs,valueonly,separator=%x2c)`,
57
+ ])
58
+ if (out === null) return null
59
+ const commits = []
60
+ for (const record of out.split(RS)) {
61
+ if (!record.trim()) continue
62
+ const [head, ...rest] = record.split('\n')
63
+ const [sha, at, subject, refs] = head.split(US)
64
+ const files = []
65
+ for (const line of rest) {
66
+ if (!line.trim()) continue
67
+ const [status, a, b] = line.split('\t')
68
+ // `R087` — a rename with its similarity score; the letter is the fact.
69
+ if (status[0] === 'R' && b) files.push({ status: 'R', from: a, path: b })
70
+ else if (a) files.push({ status: status[0], path: a })
71
+ }
72
+ commits.push({
73
+ sha,
74
+ at,
75
+ subject,
76
+ refs: (refs || '').split(',').map((r) => r.trim()).filter(Boolean),
77
+ files,
78
+ })
79
+ }
80
+ return commits
81
+ }
82
+
83
+ /** The shas the base branch holds in the window — one walk, not one per commit. */
84
+ function onBaseIn(git, base, { since, until }) {
85
+ if (!base) return new Set()
86
+ const out = git(['log', base, '--no-merges', `--since=${since}`, `--until=${until}`, '--format=%H'])
87
+ return new Set(out ? out.split('\n').filter(Boolean) : [])
88
+ }
89
+
90
+ /** The local branches that hold a commit — most recent first is not promised. */
91
+ function branchesContaining(git, sha) {
92
+ const out = git(['for-each-ref', '--contains', sha, '--format=%(refname:short)', 'refs/heads'])
93
+ return out ? out.split('\n').filter(Boolean) : []
94
+ }
95
+
96
+ /**
97
+ * Every spec folder this repo can see across `refs` — the base branch and the
98
+ * spec branches, since under `land.specDocs: "branch"` a spec exists only on
99
+ * its own. One `ls-tree` per ref; nothing is read until it is asked for.
100
+ */
101
+ function knownSpecs(git, refs) {
102
+ const known = new Set()
103
+ for (const ref of refs) {
104
+ const listing = git(['ls-tree', '-r', '--name-only', ref, '--', ...BUCKETS.map((b) => `specs/${b}`)])
105
+ if (!listing) continue
106
+ for (const p of listing.split('\n')) {
107
+ const m = /^specs\/[^/]+\/([^/]+)\/00-overview\.md$/.exec(p)
108
+ if (m) known.add(m[1])
109
+ }
110
+ }
111
+ return [...known]
112
+ }
113
+
114
+ /** A spec's ticket, read off the first of `refs` that holds its overview. */
115
+ function ticketFor(git, refs, spec, identifierField = null) {
116
+ for (const ref of refs) {
117
+ for (const bucket of BUCKETS) {
118
+ const text = git(['show', `${ref}:specs/${bucket}/${spec}/00-overview.md`])
119
+ if (text === null) continue
120
+ return readTicket(text, identifierField)
121
+ }
122
+ }
123
+ return null
124
+ }
125
+
126
+ /**
127
+ * The spec a `Refs:` ticket names, found by the identifier stamped in its
128
+ * overview. Exactly one match or null — two specs claiming one ticket is a
129
+ * question, not an answer.
130
+ */
131
+ function specForTicket(git, refs, id) {
132
+ const value = escapeRegex(id)
133
+ const names = new Set()
134
+ for (const ref of refs) {
135
+ const out = git(['grep', '-l', '-E', `^[A-Za-z][A-Za-z0-9]*_identifier:[[:space:]]*["']?${value}["']?[[:space:]]*$`, ref, '--', 'specs/*/*/00-overview.md'])
136
+ if (!out) continue
137
+ for (const line of out.split('\n')) {
138
+ const m = /specs\/[^/]+\/([^/]+)\/00-overview\.md$/.exec(line)
139
+ if (m) names.add(m[1])
140
+ }
141
+ }
142
+ return names.size === 1 ? [...names][0] : null
143
+ }
144
+
145
+ module.exports = { CONTAINS_CAP, authorOf, branchesContaining, knownSpecs, onBaseIn, readCommits, specForTicket, ticketFor }
@@ -0,0 +1,260 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The ta-da digest: the window's sessions, folded into the repo each one
5
+ * worked in and grouped by branch. This is what `skitterspec tada` prints and
6
+ * what the skill writes its recap from — never the transcripts themselves.
7
+ *
8
+ * The project is the REPO, not the cwd. A session that `cd`s into
9
+ * `../<repo>-wt/<slug>` is still working on `<repo>`, and grouping by cwd
10
+ * reported one repo as one project per worktree (Decision 3).
11
+ */
12
+
13
+ const fs = require('node:fs')
14
+ const path = require('node:path')
15
+ const { execFileSync } = require('node:child_process')
16
+
17
+ const { listTranscripts, readSession, trimPrompts } = require('./transcripts.js')
18
+
19
+ /**
20
+ * The repo a cwd belongs to, through the shared git dir — which every worktree
21
+ * of a repo points at, so they all fold into the primary checkout.
22
+ *
23
+ * @returns {{ repo: string } | { repo: null } | { missing: true }}
24
+ * `repo: null` is a directory that exists outside any repo; `missing` is one
25
+ * that no longer exists (a torn-down worktree), and is not the same fact.
26
+ */
27
+ function gitRepoOf(cwd) {
28
+ if (!fs.existsSync(cwd)) return { missing: true }
29
+ let common
30
+ try {
31
+ common = execFileSync('git', ['-C', cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
32
+ stdio: ['ignore', 'pipe', 'ignore'],
33
+ })
34
+ .toString()
35
+ .trim()
36
+ } catch {
37
+ return { repo: null }
38
+ }
39
+ return { repo: path.basename(common) === '.git' ? path.dirname(common) : common }
40
+ }
41
+
42
+ function memo(fn) {
43
+ const seen = new Map()
44
+ return (k) => {
45
+ if (!seen.has(k)) seen.set(k, fn(k))
46
+ return seen.get(k)
47
+ }
48
+ }
49
+
50
+ /**
51
+ * @param {object} a
52
+ * - `root` the transcripts root (`defaultRoot()`)
53
+ * - `window` `{ since, until }` from `windowFor`
54
+ * - `here` a cwd to narrow to its repo, or null for every project
55
+ * - `repoOf` `gitRepoOf`, injectable
56
+ * - `facts` `(repo) => readRepoFacts(…)` — commits, lifecycle moves and
57
+ * spec lookups for a repo; omitted, groups are sessions only
58
+ * - `openFor` `(repo) => [{ spec, detail, next }]` — what is in flight there
59
+ * - `chat` keep every prompt, no-spec ones included (`--chat`)
60
+ * - `category` the running project's category: only projects carrying the
61
+ * same one are reported. Null reports every project.
62
+ */
63
+ async function buildDigest({ root, window, here = null, repoOf = gitRepoOf, facts = null, openFor = null, category = null, chat = false }) {
64
+ const resolve = memo(repoOf)
65
+ const notes = []
66
+ const refolded = new Set()
67
+ const files = listTranscripts(root, window.since)
68
+ const projects = new Map()
69
+ let stamped = 0
70
+
71
+ for (const file of files) {
72
+ const session = await readSession(file, window)
73
+ stamped += session.stamped
74
+ // A cwd that is gone takes the repo of a place in the same session that
75
+ // still resolves, else of the directory the session was launched from —
76
+ // it started somewhere real before it moved.
77
+ const fallback =
78
+ session.places.map((p) => resolve(p.cwd)).find((r) => r.repo) ||
79
+ (session.launch && [resolve(session.launch)].find((r) => r.repo))
80
+
81
+ for (const place of session.places) {
82
+ let r = resolve(place.cwd)
83
+ if (r.missing) {
84
+ // The usual reason is a worktree torn down by /spec-complete — the
85
+ // normal end of a spec — so these are counted, not listed one by one.
86
+ if (fallback) {
87
+ refolded.add(place.cwd)
88
+ r = fallback
89
+ } else {
90
+ notes.push(`cannot tell: ${place.cwd} no longer exists, and nothing in its session does`)
91
+ r = { repo: null }
92
+ }
93
+ }
94
+ const key = r.repo || place.cwd
95
+ if (!projects.has(key)) {
96
+ projects.set(key, { key, repo: r.repo, name: path.basename(key), git: Boolean(r.repo), groups: new Map() })
97
+ }
98
+ const groups = projects.get(key).groups
99
+ const branch = place.branch || null
100
+ if (!groups.has(branch)) groups.set(branch, new Map())
101
+ const sessions = groups.get(branch)
102
+ if (!sessions.has(session.id)) sessions.set(session.id, { id: session.id, start: place.start, end: place.end, prompts: [] })
103
+ const s = sessions.get(session.id)
104
+ if (place.start < s.start) s.start = place.start
105
+ if (place.end > s.end) s.end = place.end
106
+ s.prompts.push(...place.prompts)
107
+ }
108
+ }
109
+
110
+ if (refolded.size > 0) {
111
+ notes.push(
112
+ `${refolded.size} working director${refolded.size === 1 ? 'y' : 'ies'} no longer exist ` +
113
+ "(torn-down worktrees, usually) — counted under the repo their session started in, on the branch it recorded",
114
+ )
115
+ }
116
+
117
+ // The positive signal behind an empty day: transcripts changed inside the
118
+ // window, yet not one entry in any of them carried a timestamp we could read.
119
+ // That is a format we no longer understand, not a day off.
120
+ if (files.length > 0 && stamped === 0) {
121
+ notes.push(
122
+ `cannot tell: ${files.length} transcript(s) changed in the window but none carried a readable ` +
123
+ 'timestamp — the transcript format may have changed',
124
+ )
125
+ }
126
+
127
+ let list = [...projects.values()]
128
+ if (here) {
129
+ const at = path.resolve(here)
130
+ const key = resolve(at).repo || at
131
+ list = list.filter((p) => p.key === key)
132
+ }
133
+
134
+ const want = category ? fold(category) : null
135
+ const reported = list
136
+ .map((p) => ({ p, f: p.repo && facts ? facts(p.repo) : null }))
137
+ // Scoped by category: a project counts only when its own config carries
138
+ // the same one. Uncategorised projects — and repos with no skitterspec
139
+ // config, which have nowhere to declare one — are left out entirely.
140
+ .filter(({ f }) => !want || (f && f.category && fold(f.category) === want))
141
+ .map(({ p, f }) => {
142
+ if (f) notes.push(...f.notes)
143
+ return {
144
+ repo: p.repo,
145
+ name: (f && f.name) || p.name,
146
+ ...(f && f.category ? { category: f.category } : {}),
147
+ git: p.git,
148
+ skitterspec: Boolean(f && f.skitterspec),
149
+ groups: groupsOf(p, f, f && openFor ? openFor(p.repo) : [], { chat }),
150
+ }
151
+ })
152
+ // A project whose only activity was chatter that led nowhere has nothing
153
+ // left to report once that is dropped.
154
+ .filter((p) => p.groups.length > 0)
155
+ .sort((a, b) => a.name.localeCompare(b.name))
156
+
157
+ return {
158
+ window: { since: window.since.toISOString(), until: window.until.toISOString() },
159
+ ...(category ? { category } : {}),
160
+ projects: reported,
161
+ notes: [...new Set(notes)],
162
+ }
163
+ }
164
+
165
+ const fold = (s) => s.trim().toLowerCase()
166
+
167
+ /**
168
+ * Changes over chatter (Decision 3): prompts typed where no spec was in play
169
+ * are dropped — unless the same session went on to stand on a spec's branch,
170
+ * in which case they were the conversation that led to that spec, and they
171
+ * move into it. The spec the session reached first afterwards takes them;
172
+ * failing that, the first it reached at all.
173
+ *
174
+ * Only prompts are dropped. A no-spec group's commits are changes, and stay.
175
+ */
176
+ function foldChatter(placed) {
177
+ const out = placed.filter((x) => x.spec)
178
+ for (const x of placed.filter((y) => !y.spec)) {
179
+ const onSpecs = out.filter((y) => y.s.id === x.s.id).sort((a, b) => (a.s.start < b.s.start ? -1 : 1))
180
+ const into = onSpecs.find((y) => y.s.start >= x.s.start) || onSpecs[0]
181
+ if (!into) continue
182
+ into.s.prompts.push(...x.s.prompts)
183
+ if (x.s.start < into.s.start) into.s.start = x.s.start
184
+ }
185
+ return out
186
+ }
187
+
188
+ /**
189
+ * One project's groups: a spec where the branch, a commit or an in-flight row
190
+ * names one, else the branch. Sessions, commits, lifecycle moves and open
191
+ * state for one spec land in one group, whichever of them found it.
192
+ */
193
+ function groupsOf(p, f, open, { chat = false } = {}) {
194
+ const groups = new Map()
195
+ const group = (spec, branch) => {
196
+ const key = spec ? `spec\0${spec}` : `branch\0${branch || ''}`
197
+ if (!groups.has(key)) {
198
+ groups.set(key, { spec: spec || null, branch: branch || null, sessions: [], commits: [], events: [], inFlight: null })
199
+ }
200
+ const g = groups.get(key)
201
+ if (!g.branch && branch) g.branch = branch
202
+ return g
203
+ }
204
+
205
+ const placed = []
206
+ for (const [branch, sessions] of p.groups) {
207
+ const spec = f ? f.toSpec(branch) : null
208
+ for (const s of sessions.values()) placed.push({ spec, branch, s })
209
+ }
210
+ for (const { spec, branch, s } of chat ? placed : foldChatter(placed)) {
211
+ s.prompts.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0))
212
+ group(spec, branch).sessions.push({ id: s.id, start: s.start, end: s.end, ...trimPrompts(s.prompts) })
213
+ }
214
+ if (f) {
215
+ for (const c of f.commits) group(c.spec, c.spec ? null : c.branch).commits.push(c)
216
+ for (const e of f.events) group(e.spec, null).events.push(e)
217
+ }
218
+ for (const row of open) group(row.spec, null).inFlight = row
219
+
220
+ return [...groups.values()]
221
+ .map((g) => {
222
+ g.sessions.sort((a, b) => (a.start < b.start ? -1 : 1))
223
+ g.commits.sort(byTime)
224
+ g.events.sort(byTime)
225
+ const ticket = g.spec && f ? f.ticket(g.spec) || refTicket(g.commits) : null
226
+ return { spec: g.spec, branch: g.branch, ...(ticket ? { ticket } : {}), sessions: g.sessions, commits: g.commits, events: g.events, inFlight: g.inFlight }
227
+ })
228
+ .sort((a, b) => {
229
+ // Activity first, in the order it happened; a spec that is only open —
230
+ // in flight, untouched in this window — goes last.
231
+ const ta = firstAt(a)
232
+ const tb = firstAt(b)
233
+ if (ta === tb) return 0
234
+ if (ta === null) return 1
235
+ if (tb === null) return -1
236
+ return ta < tb ? -1 : 1
237
+ })
238
+ }
239
+
240
+ // Stable on a tie — a rebased run shares one committer second, and its order
241
+ // is the walk's, which is oldest first.
242
+ function byTime(a, b) {
243
+ const ta = Date.parse(a.at)
244
+ const tb = Date.parse(b.at)
245
+ return ta < tb ? -1 : ta > tb ? 1 : 0
246
+ }
247
+
248
+ function firstAt(g) {
249
+ const times = [...g.sessions.map((s) => s.start), ...g.commits.map((c) => c.at)].map((t) => Date.parse(t))
250
+ return times.length ? Math.min(...times) : null
251
+ }
252
+
253
+ // A spec whose overview carries no ticket can still be named by the `Refs:`
254
+ // its commits carried — the id alone, since only the overview holds a url.
255
+ function refTicket(commits) {
256
+ const ids = [...new Set(commits.flatMap((c) => c.refs || []))]
257
+ return ids.length === 1 ? { id: ids[0], url: null } : null
258
+ }
259
+
260
+ module.exports = { buildDigest, gitRepoOf }
@@ -0,0 +1,37 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The digest as text — what `skitterspec tada` prints and what the skill
5
+ * reads. A fifth of the JSON's size, because every byte here is a token the
6
+ * recap costs. Pure.
7
+ *
8
+ * Line markers carry the kind, so the skill can tell them apart without
9
+ * labels: `*` a lifecycle move, `+` a commit, `-` a prompt.
10
+ */
11
+
12
+ function formatTada(digest) {
13
+ const w = digest.window
14
+ const scope = digest.category ? ` · ${digest.category}` : ''
15
+ const out = [`ta-da: ${w.label || `${w.since} → ${w.until}`}${scope}`]
16
+ if (digest.projects.length === 0) out.push(' nothing in this window.')
17
+ for (const p of digest.projects) {
18
+ out.push('', `${p.name}${p.repo ? ` (${p.repo})` : ' (not a git repo)'}`)
19
+ for (const g of p.groups) {
20
+ const head = g.spec ? `${g.spec}${g.ticket ? ` [${g.ticket.id}]` : ''}` : `${g.branch || '(no branch)'} — no spec`
21
+ out.push(` ${head}`)
22
+ for (const e of g.events) out.push(` * ${e.kind === 'phase-done' ? `phase ${e.phase} done` : e.kind}`)
23
+ for (const c of g.commits) out.push(` + ${c.sha} ${c.subject}`)
24
+ const sessions = g.sessions.length
25
+ if (sessions) out.push(` ${sessions} session${sessions === 1 ? '' : 's'}:`)
26
+ for (const s of g.sessions) {
27
+ for (const pr of s.prompts) out.push(` - ${pr.command ? `${pr.command} ` : ''}${pr.text}`.trimEnd())
28
+ if (s.omitted) out.push(` … ${s.omitted} more`)
29
+ }
30
+ if (g.inFlight) out.push(` in flight: ${g.inFlight.detail}${g.inFlight.next ? ` · next: ${g.inFlight.next}` : ''}`)
31
+ }
32
+ }
33
+ for (const n of digest.notes) out.push('', n)
34
+ return out.join('\n') + '\n'
35
+ }
36
+
37
+ module.exports = { formatTada }