@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.
@@ -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
- function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
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
- for (const [heading, content] of Object.entries(sections)) {
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: withInlinePhases(
703
- buildDescription(
704
- title,
705
- sections,
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
- return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
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
- // Every state NAME the config points at: the lifecycle bucket map.
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
- return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
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
  }