@skitterbyte/skitterspec-linear 18.0.0 → 18.1.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/MIGRATION.md +81 -0
- package/assets/core/env.config.md +33 -9
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-planning.md +4 -2
- package/assets/skills/no-spec/SKILL.md +3 -2
- package/assets/skills/spec-complete/SKILL.md +67 -25
- package/assets/skills/spec-hotfix/SKILL.md +21 -11
- package/assets/skills/spec-sync/SKILL.md +10 -1
- package/package.json +1 -1
- package/src/cli.js +295 -37
- package/src/env/config.js +14 -2
- package/src/env/hotfix.js +261 -15
- package/src/env/hotfixland.js +302 -0
- package/src/env/resolve.js +22 -8
- package/src/init.js +36 -4
- package/src/vendor/linear/api.js +43 -56
- package/src/vendor/linear/cli-sanitise.js +2 -2
- package/src/vendor/linear/cli-sync.js +87 -390
- package/src/vendor/linear/config.js +46 -171
- package/src/vendor/linear/credentials.js +40 -370
- package/src/vendor/linear/dialect.js +177 -0
- package/src/vendor/linear/doctor.js +7 -15
- package/src/vendor/linear/identity.js +20 -70
- package/src/vendor/linear/released.js +4 -222
- package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
- package/src/vendor/provider-kit/index.js +41 -0
- package/src/vendor/provider-kit/src/adapter.js +23 -0
- package/src/vendor/provider-kit/src/apply.js +197 -0
- package/src/vendor/provider-kit/src/args.js +68 -0
- package/src/vendor/provider-kit/src/config.js +198 -0
- package/src/vendor/provider-kit/src/credentials.js +404 -0
- package/src/vendor/provider-kit/src/doctor.js +35 -0
- package/src/vendor/provider-kit/src/http.js +44 -0
- package/src/vendor/provider-kit/src/identity.js +93 -0
- package/src/vendor/provider-kit/src/md-compare.js +39 -0
- package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
- package/src/vendor/provider-kit/src/prompt.js +50 -0
- package/src/vendor/provider-kit/src/released.js +226 -0
- package/src/vendor/provider-kit/src/specs.js +166 -0
- package/src/vendor/provider-kit/src/transport.js +22 -0
- package/src/vendor/sync-core/index.js +22 -5
- package/src/vendor/sync-core/src/compare.js +14 -12
- package/src/vendor/sync-core/src/dialect.js +51 -0
- package/src/vendor/sync-core/src/fields.js +36 -0
- package/src/vendor/sync-core/src/legacy.js +19 -9
- package/src/vendor/sync-core/src/normalize.js +30 -158
- package/src/vendor/sync-core/src/push.js +1 -1
- package/src/vendor/sync-core/src/retarget.js +21 -17
- package/src/vendor/sync-core/src/verify.js +24 -45
- package/src/vendor/sync-core/src/write.js +7 -5
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Spec resolution and listing for a provider CLI — how a spec argument becomes
|
|
5
|
+
* a snapshot directory, how a spec names its snapshot sidecar, and which specs
|
|
6
|
+
* a repo holds with which tracker links.
|
|
7
|
+
*
|
|
8
|
+
* The frontmatter key that links a spec is the provider's
|
|
9
|
+
* (`config.fields.identifier` — sync-core `src/fields.js`); everything else
|
|
10
|
+
* here is filesystem shape shared by every provider. `program` prefixes the
|
|
11
|
+
* user-facing refusals (`spec-sync: spec not found: …`).
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
const fs = require('node:fs')
|
|
15
|
+
const path = require('node:path')
|
|
16
|
+
|
|
17
|
+
const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
|
|
18
|
+
const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
|
|
19
|
+
|
|
20
|
+
function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
21
|
+
// Resolve a spec argument to its snapshot dir. Accepts a spec name/folder
|
|
22
|
+
// found under specs/** (preferred) or a literal path to a snapshot directory.
|
|
23
|
+
function resolveSnapshotDir(specArg, dir) {
|
|
24
|
+
const found = findSpecFolder(specArg, dir)
|
|
25
|
+
if (found) return found.path
|
|
26
|
+
const literal = path.resolve(dir, specArg)
|
|
27
|
+
if (fs.existsSync(literal) && fs.statSync(literal).isDirectory()) return literal
|
|
28
|
+
return null
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// The identifier keying the snapshot sidecar: the spec's stamped identifier
|
|
32
|
+
// if set, else its folder name (so the engine is usable before a spec is
|
|
33
|
+
// linked).
|
|
34
|
+
function specIdentifier(snapshotDir, config) {
|
|
35
|
+
const field = fieldsOf(config).identifier
|
|
36
|
+
try {
|
|
37
|
+
const { frontmatter } = readSnapshot(snapshotDir, config)
|
|
38
|
+
if (frontmatter[field]) return String(frontmatter[field])
|
|
39
|
+
} catch {
|
|
40
|
+
/* fall through to folder name */
|
|
41
|
+
}
|
|
42
|
+
return path.basename(snapshotDir)
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
// Read a spec's stamped identifier without throwing: an unlinked spec, an
|
|
46
|
+
// unreadable file and a spec with no frontmatter all read as `null`.
|
|
47
|
+
function linkedIdentifier(overviewPath, config) {
|
|
48
|
+
const field = fieldsOf(config).identifier
|
|
49
|
+
let raw
|
|
50
|
+
try {
|
|
51
|
+
raw = fs.readFileSync(overviewPath, 'utf-8')
|
|
52
|
+
} catch {
|
|
53
|
+
return null
|
|
54
|
+
}
|
|
55
|
+
const { data } = parseFrontmatter(raw)
|
|
56
|
+
return data[field] ? String(data[field]) : null
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// Every spec under specs/<bucket>/, paired with the tracker issue it is
|
|
60
|
+
// linked to (`null` when it has never been pushed). Folder specs read
|
|
61
|
+
// `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
|
|
62
|
+
// itself. Sorted for stable output.
|
|
63
|
+
function listSpecs(dir, config) {
|
|
64
|
+
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
65
|
+
const specs = []
|
|
66
|
+
for (const bucket of BUCKETS) {
|
|
67
|
+
const root = path.join(dir, 'specs', bucket)
|
|
68
|
+
let entries
|
|
69
|
+
try {
|
|
70
|
+
entries = fs.readdirSync(root, { withFileTypes: true })
|
|
71
|
+
} catch {
|
|
72
|
+
continue
|
|
73
|
+
}
|
|
74
|
+
for (const entry of entries) {
|
|
75
|
+
let name
|
|
76
|
+
let overviewPath
|
|
77
|
+
if (entry.isDirectory()) {
|
|
78
|
+
name = entry.name
|
|
79
|
+
overviewPath = path.join(root, name, overviewFile)
|
|
80
|
+
} else if (entry.isFile() && entry.name.endsWith('.md')) {
|
|
81
|
+
name = entry.name.slice(0, -3)
|
|
82
|
+
overviewPath = path.join(root, entry.name)
|
|
83
|
+
} else {
|
|
84
|
+
continue
|
|
85
|
+
}
|
|
86
|
+
specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return specs.sort((a, b) => a.spec.localeCompare(b.spec))
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// Resolve a spec argument to its folder, or null with a message on stdout.
|
|
93
|
+
// EVERY failure path here must print and EVERY caller must return a non-zero
|
|
94
|
+
// code: a push skill checks $? before it applies a plan, so a resolve failure
|
|
95
|
+
// that exits 0 reads as "nothing to do" rather than "I could not find the
|
|
96
|
+
// spec".
|
|
97
|
+
function resolveOrExit(specArg, dir, out) {
|
|
98
|
+
if (!specArg) {
|
|
99
|
+
out.write(`${program}: no spec given\n`)
|
|
100
|
+
return null
|
|
101
|
+
}
|
|
102
|
+
const snapshotDir = resolveSnapshotDir(specArg, dir)
|
|
103
|
+
if (!snapshotDir) {
|
|
104
|
+
out.write(`${program}: spec not found: ${specArg}\n`)
|
|
105
|
+
return null
|
|
106
|
+
}
|
|
107
|
+
return snapshotDir
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
// Phase-status warnings for a spec, one formatted line each. A spec states
|
|
111
|
+
// each phase's status three times and only the h1 emoji is read — get it
|
|
112
|
+
// wrong and the phase projects as `backlog`, pushes cleanly, and is recorded
|
|
113
|
+
// as intended: invisible. Reported by every subcommand that reads a
|
|
114
|
+
// projection, fatal in none — a legacy spec must still push.
|
|
115
|
+
function warningLines(snapshotDir, config) {
|
|
116
|
+
return lintPhases(snapshotDir, config).map((w) => ` warning ${w.file}: ${w.message}`)
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
|
|
120
|
+
function warnToErr(snapshotDir, config, err) {
|
|
121
|
+
const lines = warningLines(snapshotDir, config)
|
|
122
|
+
if (lines.length) err.write(lines.join('\n') + '\n')
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// Render the read-back comparison — the same check `verify` and `apply`
|
|
126
|
+
// both report through, so the two cannot disagree about what "intact" means.
|
|
127
|
+
function verifyLines(snapshotDir, config, stored, identifier) {
|
|
128
|
+
const projection = projectionOf(snapshotDir, config)
|
|
129
|
+
const checks = []
|
|
130
|
+
if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
|
|
131
|
+
for (const [ref, text] of Object.entries(stored.subIssues || {})) {
|
|
132
|
+
const sub = projection.subIssues.find((s) => s.ref === ref)
|
|
133
|
+
if (!sub) {
|
|
134
|
+
checks.push([`sub-issue ${ref}`, null, text])
|
|
135
|
+
continue
|
|
136
|
+
}
|
|
137
|
+
checks.push([`sub-issue ${ref}`, sub.goal, text])
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const lines = [`${program} verify: ${identifier}`]
|
|
141
|
+
let bad = 0
|
|
142
|
+
for (const [label, sent, got] of checks) {
|
|
143
|
+
if (sent == null) {
|
|
144
|
+
lines.push(` ?? ${label}: read back, but the projection has no such phase — stale ref?`)
|
|
145
|
+
bad++
|
|
146
|
+
continue
|
|
147
|
+
}
|
|
148
|
+
const r = compareStored(sent, got, config)
|
|
149
|
+
if (r.ok) continue
|
|
150
|
+
bad++
|
|
151
|
+
lines.push(
|
|
152
|
+
` !! ${label}: the tracker stored different text — ${Math.abs(r.lost)} character(s) ` +
|
|
153
|
+
`${r.lost > 0 ? 'lost' : 'added'}, first difference at ${r.at}`,
|
|
154
|
+
` sent: …${r.sentContext}…`,
|
|
155
|
+
` stored: …${r.storedContext}…`,
|
|
156
|
+
)
|
|
157
|
+
}
|
|
158
|
+
if (!bad) lines.push(` ${checks.length} description(s) round-tripped intact`)
|
|
159
|
+
else lines.push(' the repo is unchanged and still correct; re-push to overwrite the mirror')
|
|
160
|
+
return lines
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
module.exports = { makeSpecHelpers }
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Which transport a command runs over: `--via` wins, else the config's
|
|
5
|
+
* declared default, else "api when a credential resolved, mcp when it didn't".
|
|
6
|
+
*
|
|
7
|
+
* This expression was repeated verbatim nine times in the first provider —
|
|
8
|
+
* hoisted so the precedence is decided once. Per-command DEGRADATION stays with
|
|
9
|
+
* the command: which operations are impossible over mcp (exit 1, say so) and
|
|
10
|
+
* which hand the skill instructions (exit 0) is a per-command judgment, not a
|
|
11
|
+
* transport fact.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
function resolveTransport(flags, config, credentialOk) {
|
|
15
|
+
return (
|
|
16
|
+
(flags && flags.via) ||
|
|
17
|
+
(config && config.apply && config.apply.transport) ||
|
|
18
|
+
(credentialOk ? 'api' : 'mcp')
|
|
19
|
+
)
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
module.exports = { resolveTransport }
|
|
@@ -13,15 +13,16 @@
|
|
|
13
13
|
* stored matches what was sent — it merges nothing (see `src/verify.js`).
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
-
const { ownsField, normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
|
|
16
|
+
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
|
|
17
17
|
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
|
|
18
18
|
const { readBase, writeBase } = require('./src/base.js')
|
|
19
19
|
const { push, recordPush, projectionOf } = require('./src/push.js')
|
|
20
20
|
const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
|
|
21
|
-
const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
|
|
22
21
|
const { detectLegacyMirror } = require('./src/legacy.js')
|
|
23
22
|
const { compareStored, stream } = require('./src/verify.js')
|
|
24
|
-
const {
|
|
23
|
+
const { identityDialect, dialectOf } = require('./src/dialect.js')
|
|
24
|
+
const { fieldsOf } = require('./src/fields.js')
|
|
25
|
+
const { renderTaskBlock, findTaskBlocks, wrapEmphasisAware, collapseHyphenAware, inferWidth, fenceMask, DEFAULT_WIDTH } = require('./src/task-block.js')
|
|
25
26
|
const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
|
|
26
27
|
|
|
27
28
|
module.exports = {
|
|
@@ -56,7 +57,6 @@ module.exports = {
|
|
|
56
57
|
stampIssueId,
|
|
57
58
|
findPhaseFileByTitle,
|
|
58
59
|
listPhaseFiles,
|
|
59
|
-
sanitizeSpecMarkdown,
|
|
60
60
|
detectLegacyMirror,
|
|
61
61
|
compareStored,
|
|
62
62
|
// The tolerant reduction behind both `compareStored` and the snapshot's
|
|
@@ -66,7 +66,24 @@ module.exports = {
|
|
|
66
66
|
// Did someone else edit the tracker's description since the last push?
|
|
67
67
|
// Three-valued; `null` is cannot-tell and must never be reported as drift.
|
|
68
68
|
remoteDescriptionEdited,
|
|
69
|
-
|
|
69
|
+
// Provider seams: the frontmatter field vocabulary and the markdown dialect
|
|
70
|
+
// a provider's config supplies (`config.fields` / `config.dialect`).
|
|
71
|
+
fieldsOf,
|
|
72
|
+
identityDialect,
|
|
73
|
+
dialectOf,
|
|
74
|
+
// The lifecycle buckets, exported once so providers and tests stop growing
|
|
75
|
+
// private copies (the tracker-free common package keeps its own — it cannot
|
|
76
|
+
// depend on this package).
|
|
77
|
+
LIFECYCLE_BUCKETS,
|
|
78
|
+
// Task-block helpers a provider's own text tooling builds on (the Linear
|
|
79
|
+
// sanitiser reflows emphasis-aware with these).
|
|
80
|
+
renderTaskBlock,
|
|
81
|
+
findTaskBlocks,
|
|
82
|
+
wrapEmphasisAware,
|
|
83
|
+
collapseHyphenAware,
|
|
84
|
+
inferWidth,
|
|
85
|
+
fenceMask,
|
|
86
|
+
DEFAULT_WIDTH,
|
|
70
87
|
planRetarget,
|
|
71
88
|
applyRetarget,
|
|
72
89
|
deriveRecordedKey,
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
'use strict'
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* One-sided change detection for one-way sync (repo →
|
|
4
|
+
* One-sided change detection for one-way sync (repo → tracker).
|
|
5
5
|
*
|
|
6
6
|
* The repo is the source of truth; Linear is a generated mirror. We never read
|
|
7
7
|
* remote content. Instead we record a **last-pushed snapshot** — a content hash
|
|
@@ -19,9 +19,10 @@
|
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
21
|
const { createHash } = require('node:crypto')
|
|
22
|
-
// The tolerant reduction `verify.js` already uses to tell
|
|
22
|
+
// The tolerant reduction `verify.js` already uses to tell the tracker's own
|
|
23
23
|
// reserialisation apart from a real edit. Imported rather than reimplemented:
|
|
24
24
|
// two reductions that disagree would be two different answers to one question.
|
|
25
|
+
// Dialect-parameterised: the provider's `config.dialect` names the transforms.
|
|
25
26
|
const { stream } = require('./verify.js')
|
|
26
27
|
|
|
27
28
|
// Deterministic JSON: object keys sorted recursively; array order preserved.
|
|
@@ -63,7 +64,7 @@ function specIssueHash(p) {
|
|
|
63
64
|
// `complete`, and welding the two meant any prose edit re-emitted the state and
|
|
64
65
|
// dragged the issue back. Diffing them apart is what lets a push touch the
|
|
65
66
|
// description without re-asserting a state someone else now owns.
|
|
66
|
-
function specIssueFieldHashes(p) {
|
|
67
|
+
function specIssueFieldHashes(p, config) {
|
|
67
68
|
const hashes = {
|
|
68
69
|
description: hashField(p.description ?? null),
|
|
69
70
|
state: hashField(p.status ?? null),
|
|
@@ -79,7 +80,7 @@ function specIssueFieldHashes(p) {
|
|
|
79
80
|
// `description` above decides what to PUSH: it is exact, because any
|
|
80
81
|
// difference between the repo and what the repo last sent is a difference the
|
|
81
82
|
// repo should send again. This one decides whether SOMEBODY ELSE has been
|
|
82
|
-
// here, and for that exactness is precisely wrong —
|
|
83
|
+
// here, and for that exactness is precisely wrong — the tracker reserialises
|
|
83
84
|
// markdown on save (bullets rewritten, ordered lists renumbered, table
|
|
84
85
|
// separators collapsed), so comparing the exact hash against a read-back would
|
|
85
86
|
// report a human edit on every intact mirror in the workspace.
|
|
@@ -94,7 +95,7 @@ function specIssueFieldHashes(p) {
|
|
|
94
95
|
// It is recorded and never planned on. `issueChanges` reads `description`,
|
|
95
96
|
// `state` and `assignee` by name and never iterates this object, so adding a
|
|
96
97
|
// key here cannot make a push pending — there is a test for exactly that.
|
|
97
|
-
hashes.descriptionStream = hashField(stream(p.description ?? ''))
|
|
98
|
+
hashes.descriptionStream = hashField(stream(p.description ?? '', config))
|
|
98
99
|
return hashes
|
|
99
100
|
}
|
|
100
101
|
|
|
@@ -122,18 +123,19 @@ function specIssueFieldHashes(p) {
|
|
|
122
123
|
* @param {object|null} remote what the tracker currently holds for the issue
|
|
123
124
|
* @returns {boolean|null}
|
|
124
125
|
*/
|
|
125
|
-
function remoteDescriptionEdited(snapshot, remote) {
|
|
126
|
+
function remoteDescriptionEdited(snapshot, remote, config) {
|
|
126
127
|
const fields = snapshot && snapshot.issueFields
|
|
127
128
|
if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return null
|
|
128
129
|
const recorded = fields.descriptionStream
|
|
129
130
|
if (typeof recorded !== 'string' || !recorded) return null
|
|
130
131
|
|
|
131
132
|
if (!remote || typeof remote !== 'object') return null
|
|
132
|
-
|
|
133
|
-
const
|
|
133
|
+
// A provider whose remote shape differs supplies `config.remote.description`.
|
|
134
|
+
const hook = config && config.remote && config.remote.description
|
|
135
|
+
const text = typeof hook === 'function' ? hook(remote) : 'description' in remote ? remote.description : undefined
|
|
134
136
|
if (typeof text !== 'string') return null
|
|
135
137
|
|
|
136
|
-
return hashField(stream(text)) !== recorded
|
|
138
|
+
return hashField(stream(text, config)) !== recorded
|
|
137
139
|
}
|
|
138
140
|
// A phase SUB-ISSUE: its name, goal and state (all repo-owned).
|
|
139
141
|
const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
|
|
@@ -144,7 +146,7 @@ const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? nu
|
|
|
144
146
|
* aren't recorded until the skill stamps their returned id and the next
|
|
145
147
|
* projection includes it.
|
|
146
148
|
*/
|
|
147
|
-
function snapshotOf(projection) {
|
|
149
|
+
function snapshotOf(projection, config) {
|
|
148
150
|
const p = projection || {}
|
|
149
151
|
const byId = (arr, hash) => {
|
|
150
152
|
const out = {}
|
|
@@ -156,7 +158,7 @@ function snapshotOf(projection) {
|
|
|
156
158
|
// `issue` keeps a snapshot readable by anything still expecting the combined
|
|
157
159
|
// hash. Cheap insurance — two SHA-1s of text already in hand.
|
|
158
160
|
issue: specIssueHash(p),
|
|
159
|
-
issueFields: specIssueFieldHashes(p),
|
|
161
|
+
issueFields: specIssueFieldHashes(p, config),
|
|
160
162
|
subIssues: byId(p.subIssues, subIssueHash),
|
|
161
163
|
}
|
|
162
164
|
}
|
|
@@ -170,7 +172,7 @@ function snapshotOf(projection) {
|
|
|
170
172
|
* — the `ref` because the read-back check matches sub-issues to phases BY ref,
|
|
171
173
|
* and an update with only an id makes every one of them look unmatched.
|
|
172
174
|
* `plan.issue` (when present) is the spec issue's description + state; the push
|
|
173
|
-
* skill applies
|
|
175
|
+
* skill applies its provider's project/grouping choice on top of it.
|
|
174
176
|
*/
|
|
175
177
|
function planChanges(projection, snapshot) {
|
|
176
178
|
const p = projection || {}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The tracker's markdown DIALECT — how a provider shapes outbound text and
|
|
5
|
+
* reduces read-backs for comparison. The engine is provider-neutral, but every
|
|
6
|
+
* tracker reserialises text its own way (one rewrites bullets and mangles
|
|
7
|
+
* emphasis, another stores a different format entirely), so the transforms live
|
|
8
|
+
* with the provider and arrive here on `config.dialect`.
|
|
9
|
+
*
|
|
10
|
+
* Three hooks, each `string → string` and pure:
|
|
11
|
+
*
|
|
12
|
+
* - `canonicalize(text)` — canonicalise a projected description so
|
|
13
|
+
* semantically-equal content hashes equal
|
|
14
|
+
* across the boundary.
|
|
15
|
+
* - `flattenTables(text)` — rewrite constructs the tracker's renderer is
|
|
16
|
+
* known to corrupt (applied to every projected
|
|
17
|
+
* body).
|
|
18
|
+
* - `canonicalForCompare(text)`— reduce a read-back so the tracker's own
|
|
19
|
+
* benign reserialisation does not read as data
|
|
20
|
+
* loss (see `verify.js`).
|
|
21
|
+
*
|
|
22
|
+
* The identity dialect is the default: no provider transforms, plus the one
|
|
23
|
+
* reduction that is universal (line endings, trailing whitespace, blank-run
|
|
24
|
+
* collapse) so `canonicalForCompare` is never a bare string equality.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
function baseCanonicalForCompare(text) {
|
|
28
|
+
return String(text == null ? '' : text)
|
|
29
|
+
.replace(/\r\n/g, '\n')
|
|
30
|
+
.split('\n')
|
|
31
|
+
.map((line) => line.replace(/[ \t]+$/, ''))
|
|
32
|
+
.join('\n')
|
|
33
|
+
.replace(/\n{3,}/g, '\n\n')
|
|
34
|
+
.trim()
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const identityDialect = Object.freeze({
|
|
38
|
+
canonicalize: (text) => text,
|
|
39
|
+
flattenTables: (text) => text,
|
|
40
|
+
canonicalForCompare: baseCanonicalForCompare,
|
|
41
|
+
})
|
|
42
|
+
|
|
43
|
+
// The dialect in play for a config: the provider's hooks over the identity
|
|
44
|
+
// defaults, so a provider may supply any subset.
|
|
45
|
+
function dialectOf(config) {
|
|
46
|
+
const d = config && config.dialect
|
|
47
|
+
if (!d || typeof d !== 'object') return identityDialect
|
|
48
|
+
return { ...identityDialect, ...d }
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
module.exports = { identityDialect, dialectOf, baseCanonicalForCompare }
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The frontmatter FIELD VOCABULARY — which keys a provider stamps into spec
|
|
5
|
+
* files. The engine reads and writes stamps by these names and hardcodes none
|
|
6
|
+
* of them: each provider's config loader supplies its own set (the Linear
|
|
7
|
+
* provider defaults to `linear_identifier` / `linear_issue_id` / …), so a
|
|
8
|
+
* second provider stamps its own keys without touching the engine.
|
|
9
|
+
*
|
|
10
|
+
* Required keys: `identifier`, `url`, `issueId`, `assigneeId`.
|
|
11
|
+
* Optional: `assigneeName`, and `legacyIdentifier` / `legacyIssueId` — the keys
|
|
12
|
+
* a pre-9.0 mirror stamped. A provider with no legacy era simply omits them,
|
|
13
|
+
* and legacy detection then reports nothing (`legacy.js`).
|
|
14
|
+
*
|
|
15
|
+
* A missing `config.fields` THROWS rather than defaulting: a silent default
|
|
16
|
+
* would let the engine read stamps under names the provider never wrote, and
|
|
17
|
+
* the failure that produces is an all-creates plan that duplicates a live
|
|
18
|
+
* mirror — far worse than a loud error at the first call.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
function fieldsOf(config) {
|
|
22
|
+
const f = config && config.fields
|
|
23
|
+
if (!f || typeof f !== 'object' || Array.isArray(f)) {
|
|
24
|
+
throw new Error(
|
|
25
|
+
'config.fields missing — the provider config must name its frontmatter fields (identifier, url, issueId, assigneeId)',
|
|
26
|
+
)
|
|
27
|
+
}
|
|
28
|
+
for (const key of ['identifier', 'url', 'issueId', 'assigneeId']) {
|
|
29
|
+
if (typeof f[key] !== 'string' || !f[key]) {
|
|
30
|
+
throw new Error(`config.fields.${key} missing — the provider config must name this frontmatter field`)
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return f
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
module.exports = { fieldsOf }
|
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
*
|
|
6
6
|
* v9 remapped the mirror: a spec is an issue (was a Project), a phase is a
|
|
7
7
|
* sub-issue (was a Milestone), and tasks are no longer objects at all. The
|
|
8
|
-
* frontmatter keys moved with it
|
|
9
|
-
* `
|
|
8
|
+
* frontmatter keys moved with it (in the Linear provider's vocabulary,
|
|
9
|
+
* `linear_project_id` -> `linear_identifier`, `linear_milestone_id` ->
|
|
10
|
+
* `linear_issue_id` — see `config.fields`).
|
|
10
11
|
*
|
|
11
12
|
* The failure this guards is silent and destructive: v9 looks for the new keys,
|
|
12
13
|
* finds nothing, and produces a perfectly ordinary **all-creates** plan. Applying
|
|
@@ -27,9 +28,10 @@ const { parseFrontmatter } = require('./normalize.js')
|
|
|
27
28
|
const { readBase } = require('./base.js')
|
|
28
29
|
const { listPhaseFiles } = require('./write.js')
|
|
29
30
|
|
|
30
|
-
//
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
// The pre-9.0 keys come from the provider's field vocabulary
|
|
32
|
+
// (`config.fields.legacyIdentifier` / `.legacyIssueId`). A provider with no
|
|
33
|
+
// pre-9.0 era omits them, and detection then reports nothing: there is no old
|
|
34
|
+
// model its repos could be stranded on, so an absence is not evidence.
|
|
33
35
|
|
|
34
36
|
function frontmatterOf(file) {
|
|
35
37
|
try {
|
|
@@ -56,19 +58,27 @@ function countOrphans(snapshot) {
|
|
|
56
58
|
* @returns {null|{keys:string[], files:string[], orphans:object|null, orphanCount:number}}
|
|
57
59
|
*/
|
|
58
60
|
function detectLegacyMirror({ dir, snapshotDir, identifier, config }) {
|
|
61
|
+
const fields = (config && config.fields) || {}
|
|
62
|
+
const legacyOverviewKey = fields.legacyIdentifier
|
|
63
|
+
const legacyPhaseKey = fields.legacyIssueId
|
|
64
|
+
// No legacy vocabulary declared -> this provider has no pre-9.0 era, so there
|
|
65
|
+
// is no old model its repos could be stranded on, and an absence of the keys
|
|
66
|
+
// proves nothing (`.claude/rules/negative-checks.md`).
|
|
67
|
+
if (!legacyOverviewKey && !legacyPhaseKey) return null
|
|
68
|
+
|
|
59
69
|
const keys = []
|
|
60
70
|
const files = []
|
|
61
71
|
|
|
62
72
|
const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
63
73
|
const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
|
|
64
|
-
if (overview[
|
|
65
|
-
keys.push(
|
|
74
|
+
if (legacyOverviewKey && overview[legacyOverviewKey] != null) {
|
|
75
|
+
keys.push(legacyOverviewKey)
|
|
66
76
|
files.push(overviewFile)
|
|
67
77
|
}
|
|
68
78
|
|
|
69
79
|
for (const file of listPhaseFiles(snapshotDir)) {
|
|
70
|
-
if (frontmatterOf(path.join(snapshotDir, file))[
|
|
71
|
-
if (!keys.includes(
|
|
80
|
+
if (legacyPhaseKey && frontmatterOf(path.join(snapshotDir, file))[legacyPhaseKey] != null) {
|
|
81
|
+
if (!keys.includes(legacyPhaseKey)) keys.push(legacyPhaseKey)
|
|
72
82
|
files.push(file)
|
|
73
83
|
}
|
|
74
84
|
}
|