@skitterbyte/skitterspec-linear 19.0.0 → 19.2.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 +71 -0
- package/README.md +1 -0
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +16 -1
- package/assets/rules/spec-planning.md +52 -11
- package/assets/rules/spec-reports.md +28 -2
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +47 -8
- package/assets/skills/spec-bug/SKILL.md +6 -2
- package/assets/skills/spec-complete/SKILL.md +39 -0
- package/assets/skills/spec-hotfix/SKILL.md +4 -0
- package/assets/skills/spec-incident/SKILL.md +142 -0
- package/assets/skills/spec-init/SKILL.md +2 -1
- package/assets/skills/spec-next/SKILL.md +2 -2
- package/package.json +1 -1
- package/src/cli.js +108 -3
- package/src/env/resolve.js +12 -4
- package/src/env/review.js +79 -0
- package/src/vendor/linear/api.js +37 -2
- package/src/vendor/linear/cli-sync.js +119 -3
- package/src/vendor/linear/config.js +35 -3
- package/src/vendor/provider-kit/src/config.js +44 -0
- package/src/vendor/sync-core/index.js +4 -1
- package/src/vendor/sync-core/src/normalize.js +137 -16
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* stored matches what was sent — it merges nothing (see `src/verify.js`).
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
-
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
|
|
16
|
+
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, linkedIncident, phaseModeFor } = require('./src/normalize.js')
|
|
17
17
|
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
|
|
18
18
|
const { readBase, writeBase } = require('./src/base.js')
|
|
19
19
|
const { push, recordPush, projectionOf } = require('./src/push.js')
|
|
@@ -46,6 +46,9 @@ module.exports = {
|
|
|
46
46
|
titleFromText,
|
|
47
47
|
validateStates,
|
|
48
48
|
stateSuggestions,
|
|
49
|
+
effectiveStates,
|
|
50
|
+
specHeaders,
|
|
51
|
+
linkedIncident,
|
|
49
52
|
hashField,
|
|
50
53
|
stableStringify,
|
|
51
54
|
readBase,
|
|
@@ -405,15 +405,93 @@ function readSnapshot(snapshotDir, config) {
|
|
|
405
405
|
return { frontmatter: data, title, sections, phases, body }
|
|
406
406
|
}
|
|
407
407
|
|
|
408
|
+
// The spec's own `> **Severity:**` and `> **Incident:**` headers, off the
|
|
409
|
+
// overview's blockquote block. They are PUSH-TIME EXTRAS, deliberately not
|
|
410
|
+
// keys on `normalizeLocal`'s field set: severity lands in a provider-specific
|
|
411
|
+
// home (a field, a label) and the incident link as a typed relation, so
|
|
412
|
+
// neither belongs in the synced-field hashes a stored base compares.
|
|
413
|
+
function specHeaders(snapshotDir, config) {
|
|
414
|
+
const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
415
|
+
let raw
|
|
416
|
+
try {
|
|
417
|
+
raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
|
|
418
|
+
} catch {
|
|
419
|
+
return { severity: null, incident: null }
|
|
420
|
+
}
|
|
421
|
+
const read = (name) => {
|
|
422
|
+
const m = new RegExp(`^>\\s*\\*\\*${name}:\\*\\*\\s*(.+)$`, 'm').exec(raw)
|
|
423
|
+
return m ? m[1].trim() : null
|
|
424
|
+
}
|
|
425
|
+
return { severity: read('Severity'), incident: read('Incident') }
|
|
426
|
+
}
|
|
427
|
+
|
|
428
|
+
// Resolve a fix spec's `> **Incident:**` header to the incident spec it names:
|
|
429
|
+
// its folder in any lifecycle bucket, and the tracker identifier stamped on it
|
|
430
|
+
// (via the provider's own `fields.identifier`). `identifier: null` means the
|
|
431
|
+
// incident exists but is not linked yet — report and carry on, never fail the
|
|
432
|
+
// push over it. No header at all returns null.
|
|
433
|
+
function linkedIncident(snapshotDir, config) {
|
|
434
|
+
const { incident } = specHeaders(snapshotDir, config)
|
|
435
|
+
if (!incident) return null
|
|
436
|
+
const root = path.resolve(snapshotDir, '..', '..', '..')
|
|
437
|
+
const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
438
|
+
for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
|
|
439
|
+
const file = path.join(root, 'specs', bucket, incident, overviewFile)
|
|
440
|
+
if (!fs.existsSync(file)) continue
|
|
441
|
+
const { data } = parseFrontmatter(fs.readFileSync(file, 'utf-8'))
|
|
442
|
+
const idField = config && config.fields && config.fields.identifier
|
|
443
|
+
const identifier = idField && data[idField] != null ? String(data[idField]) : null
|
|
444
|
+
return { name: incident, identifier, found: true }
|
|
445
|
+
}
|
|
446
|
+
// A FOLDER NOT ON DISK IS NOT PROOF THE INCIDENT DOES NOT EXIST — buckets
|
|
447
|
+
// are branch-local truth, so an incident on its own unlanded branch is
|
|
448
|
+
// invisible here. The caller reports "not linked yet" and carries on.
|
|
449
|
+
return { name: incident, identifier: null, found: false }
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
// The one-line cross-reference a fix spec's body carries to its incident. Part
|
|
453
|
+
// of the PROJECTION (not appended at send time), so the stored base, the plan
|
|
454
|
+
// and what the tracker holds all hash the same bytes — and on GitHub the
|
|
455
|
+
// `#N` identifier backlinks on the incident's own timeline.
|
|
456
|
+
function relatedIncidentLine(snapshotDir, config) {
|
|
457
|
+
const incident = linkedIncident(snapshotDir, config)
|
|
458
|
+
if (!incident) return ''
|
|
459
|
+
return `\n\nRelated incident: ${incident.identifier || incident.name}`
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
// The headings a bug-shaped spec's ticket leads with, in this order, when the
|
|
463
|
+
// spec has them. A Bug ticket is read for its repro before anything else, and
|
|
464
|
+
// the feature overview order buries it. Sections a spec does not have are
|
|
465
|
+
// skipped, never invented — a legacy bug spec with feature-shaped sections
|
|
466
|
+
// renders exactly as it always did.
|
|
467
|
+
const BUG_LEAD_SECTIONS = ['Symptom', 'Repro', 'Expected', 'Actual', 'Root cause', 'Failing test (red)', 'Fix']
|
|
468
|
+
|
|
469
|
+
// A spec's kind off its folder prefix — the same convention the providers'
|
|
470
|
+
// `specKindOf` reads, kept local because sync-core depends on no other package.
|
|
471
|
+
function bugShaped(snapshotDir) {
|
|
472
|
+
const name = path.basename(String(snapshotDir || ''))
|
|
473
|
+
return name.startsWith('bug-') || name.startsWith('hotfix-')
|
|
474
|
+
}
|
|
475
|
+
|
|
408
476
|
// Build the pushed description: the overview prose with local-only sections
|
|
409
477
|
// removed. Keeps the title line for context. `extraSkip` drops additional
|
|
410
478
|
// sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
|
|
411
479
|
// the phase list isn't duplicated in the description — Decision 5).
|
|
412
|
-
|
|
480
|
+
// `leadSections` names headings to emit FIRST, in its order, matched
|
|
481
|
+
// case-insensitively; the rest follow in document order. Empty means document
|
|
482
|
+
// order throughout — byte-identical to before the parameter existed.
|
|
483
|
+
function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect, leadSections = []) {
|
|
413
484
|
const skip = new Set([...(localOnlySections || []), ...extraSkip])
|
|
414
485
|
const parts = []
|
|
415
486
|
if (title) parts.push(`# ${title}`)
|
|
416
|
-
|
|
487
|
+
const entries = Object.entries(sections)
|
|
488
|
+
const lead = []
|
|
489
|
+
for (const want of leadSections) {
|
|
490
|
+
const hit = entries.find(([heading]) => heading.toLowerCase() === want.toLowerCase())
|
|
491
|
+
if (hit) lead.push(hit)
|
|
492
|
+
}
|
|
493
|
+
const ordered = [...lead, ...entries.filter((e) => !lead.includes(e))]
|
|
494
|
+
for (const [heading, content] of ordered) {
|
|
417
495
|
if (skip.has(heading)) continue
|
|
418
496
|
parts.push(`## ${heading}\n\n${content}`.trim())
|
|
419
497
|
}
|
|
@@ -699,19 +777,24 @@ function normalizeLocal(snapshotDir, config) {
|
|
|
699
777
|
const phasesCarriedBySubIssues =
|
|
700
778
|
syncsSubIssues && phaseModeFor(workflowState, config) !== 'inline' && withheld === 0
|
|
701
779
|
const extracted = {
|
|
702
|
-
description:
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
780
|
+
description:
|
|
781
|
+
withInlinePhases(
|
|
782
|
+
buildDescription(
|
|
783
|
+
title,
|
|
784
|
+
sections,
|
|
785
|
+
config.sync.localOnlySections,
|
|
786
|
+
phasesCarriedBySubIssues ? ['Phases'] : [],
|
|
787
|
+
dialect,
|
|
788
|
+
// A bug or hotfix spec's ticket leads with the bug sections — a
|
|
789
|
+
// different render of the same overview, so the Bug form opens on the
|
|
790
|
+
// repro rather than the feature-shaped prose.
|
|
791
|
+
bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
|
|
792
|
+
),
|
|
793
|
+
inlined,
|
|
794
|
+
tasksMode,
|
|
706
795
|
config.sync.localOnlySections,
|
|
707
|
-
phasesCarriedBySubIssues ? ['Phases'] : [],
|
|
708
796
|
dialect,
|
|
709
|
-
),
|
|
710
|
-
inlined,
|
|
711
|
-
tasksMode,
|
|
712
|
-
config.sync.localOnlySections,
|
|
713
|
-
dialect,
|
|
714
|
-
),
|
|
797
|
+
) + relatedIncidentLine(snapshotDir, config),
|
|
715
798
|
// Sub-issue projection: one per phase. `ref` is the phase-file basename — the
|
|
716
799
|
// local handle the push skill stamps a newly-created sub-issue id back into.
|
|
717
800
|
// `state` is the phase's status bucket (from its heading emoji), mapped to a
|
|
@@ -758,7 +841,14 @@ function phasesWithheld(snapshotDir, config) {
|
|
|
758
841
|
function stateNamesFor(bucket, config) {
|
|
759
842
|
const primary = config && config.states && config.states[bucket]
|
|
760
843
|
const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
|
|
761
|
-
|
|
844
|
+
// Override values read as the bucket they override — so a `/spec-status`
|
|
845
|
+
// against a type completed to "Closed" still reads as `complete`.
|
|
846
|
+
const overrides = stateOverrideTables(config).flatMap((table) =>
|
|
847
|
+
Object.values(table).map((entry) => entry && entry[bucket]),
|
|
848
|
+
)
|
|
849
|
+
return [...new Set([primary, ...(Array.isArray(aliases) ? aliases : []), ...overrides])].filter(
|
|
850
|
+
(n) => typeof n === 'string' && n,
|
|
851
|
+
)
|
|
762
852
|
}
|
|
763
853
|
|
|
764
854
|
// Map a remote workflow-state name back to the local lifecycle bucket (the
|
|
@@ -894,11 +984,39 @@ function titleFromText(text, max = 100) {
|
|
|
894
984
|
return stripTitleMarkup(title)
|
|
895
985
|
}
|
|
896
986
|
|
|
897
|
-
//
|
|
987
|
+
// Per-type/kind state OVERRIDES: `table` maps a work item type (Azure, Jira)
|
|
988
|
+
// or a spec kind (GitHub, Linear) to a partial bucket map laid over
|
|
989
|
+
// `config.states`. A bucket mapped to null means "send no state for this
|
|
990
|
+
// bucket"; a bucket the entry lacks falls through to the base map. With no
|
|
991
|
+
// table, or no entry for `key`, this is exactly `config.states`.
|
|
992
|
+
function effectiveStates(config, table, key) {
|
|
993
|
+
const out = { ...((config && config.states) || {}) }
|
|
994
|
+
const over = (table && key && table[key]) || null
|
|
995
|
+
if (over) for (const [bucket, value] of Object.entries(over)) out[bucket] = value
|
|
996
|
+
return out
|
|
997
|
+
}
|
|
998
|
+
|
|
999
|
+
// The per-type/kind override tables a provider config may carry. Readers that
|
|
1000
|
+
// scan "every configured state name" scan these too, so an override value is
|
|
1001
|
+
// validated and recognised exactly like a base one.
|
|
1002
|
+
function stateOverrideTables(config) {
|
|
1003
|
+
return [config && config.statesByType, config && config.statesByKind].filter(Boolean)
|
|
1004
|
+
}
|
|
1005
|
+
|
|
1006
|
+
// Every state NAME the config points at: the lifecycle bucket map, plus any
|
|
1007
|
+
// per-type/kind override values (null entries carry no name).
|
|
898
1008
|
function configuredStateNames(config) {
|
|
899
1009
|
// The WRITTEN names only. An alias is never written, so one the workspace
|
|
900
1010
|
// lacks cannot strand a push; `stateSuggestions` still names it in reports.
|
|
901
|
-
|
|
1011
|
+
const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
|
|
1012
|
+
for (const table of stateOverrideTables(config)) {
|
|
1013
|
+
for (const entry of Object.values(table)) {
|
|
1014
|
+
for (const value of Object.values(entry || {})) {
|
|
1015
|
+
if (typeof value === 'string') names.push(value)
|
|
1016
|
+
}
|
|
1017
|
+
}
|
|
1018
|
+
}
|
|
1019
|
+
return [...new Set(names)]
|
|
902
1020
|
}
|
|
903
1021
|
|
|
904
1022
|
// Which configured state NAMES are absent from the live workspace. The skill
|
|
@@ -949,6 +1067,7 @@ module.exports = {
|
|
|
949
1067
|
ownsField,
|
|
950
1068
|
stateSuggestions,
|
|
951
1069
|
configuredStateNames,
|
|
1070
|
+
effectiveStates,
|
|
952
1071
|
normalizeLocal,
|
|
953
1072
|
assigneeFor,
|
|
954
1073
|
phaseProjection,
|
|
@@ -968,4 +1087,6 @@ module.exports = {
|
|
|
968
1087
|
remoteWorkflowState,
|
|
969
1088
|
remoteStateReading,
|
|
970
1089
|
stateNamesFor,
|
|
1090
|
+
specHeaders,
|
|
1091
|
+
linkedIncident,
|
|
971
1092
|
}
|