@skitterbyte/skitterspec-jira 1.2.2 → 2.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.
@@ -405,15 +405,39 @@ function readSnapshot(snapshotDir, config) {
405
405
  return { frontmatter: data, title, sections, phases, body }
406
406
  }
407
407
 
408
+ // The headings a bug-shaped spec's ticket leads with, in this order, when the
409
+ // spec has them. A Bug ticket is read for its repro before anything else, and
410
+ // the feature overview order buries it. Sections a spec does not have are
411
+ // skipped, never invented — a legacy bug spec with feature-shaped sections
412
+ // renders exactly as it always did.
413
+ const BUG_LEAD_SECTIONS = ['Symptom', 'Repro', 'Expected', 'Actual', 'Root cause', 'Failing test (red)', 'Fix']
414
+
415
+ // A spec's kind off its folder prefix — the same convention the providers'
416
+ // `specKindOf` reads, kept local because sync-core depends on no other package.
417
+ function bugShaped(snapshotDir) {
418
+ const name = path.basename(String(snapshotDir || ''))
419
+ return name.startsWith('bug-') || name.startsWith('hotfix-')
420
+ }
421
+
408
422
  // Build the pushed description: the overview prose with local-only sections
409
423
  // removed. Keeps the title line for context. `extraSkip` drops additional
410
424
  // sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
411
425
  // the phase list isn't duplicated in the description — Decision 5).
412
- function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
426
+ // `leadSections` names headings to emit FIRST, in its order, matched
427
+ // case-insensitively; the rest follow in document order. Empty means document
428
+ // order throughout — byte-identical to before the parameter existed.
429
+ function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect, leadSections = []) {
413
430
  const skip = new Set([...(localOnlySections || []), ...extraSkip])
414
431
  const parts = []
415
432
  if (title) parts.push(`# ${title}`)
416
- for (const [heading, content] of Object.entries(sections)) {
433
+ const entries = Object.entries(sections)
434
+ const lead = []
435
+ for (const want of leadSections) {
436
+ const hit = entries.find(([heading]) => heading.toLowerCase() === want.toLowerCase())
437
+ if (hit) lead.push(hit)
438
+ }
439
+ const ordered = [...lead, ...entries.filter((e) => !lead.includes(e))]
440
+ for (const [heading, content] of ordered) {
417
441
  if (skip.has(heading)) continue
418
442
  parts.push(`## ${heading}\n\n${content}`.trim())
419
443
  }
@@ -706,6 +730,10 @@ function normalizeLocal(snapshotDir, config) {
706
730
  config.sync.localOnlySections,
707
731
  phasesCarriedBySubIssues ? ['Phases'] : [],
708
732
  dialect,
733
+ // A bug or hotfix spec's ticket leads with the bug sections — a
734
+ // different render of the same overview, so the Bug form opens on the
735
+ // repro rather than the feature-shaped prose.
736
+ bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
709
737
  ),
710
738
  inlined,
711
739
  tasksMode,
@@ -751,39 +779,27 @@ function phasesWithheld(snapshotDir, config) {
751
779
 
752
780
  // --- remote projection ------------------------------------------------------
753
781
 
754
- // The lifecycle bucket a deployment ladder descends FROM. A spec is handed over
755
- // to the deploy pipeline once it is finished, so every rung sits downstream of
756
- // `complete` — a ticket on "On Test" is a completed spec that has been deployed,
757
- // not a spec that moved somewhere else.
758
- const LADDER_ORIGIN_BUCKET = 'complete'
759
-
760
- // The declared ladder rung with this state name, or null.
761
- function stageForState(state, config) {
762
- if (state == null) return null
763
- const want = String(state).toLowerCase().trim()
764
- const stages = (config && config.release && config.release.stages) || []
765
- if (!Array.isArray(stages)) return null
766
- return stages.find((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want) || null
782
+ // Every tracker state NAME that means this bucket: the one push writes
783
+ // (`states[bucket]`) first, then its read-only aliases (`stateAliases[bucket]`,
784
+ // from the array form of `states`). Readers use the whole list; writers only
785
+ // ever use `states[bucket]`, so an alias can never be written.
786
+ function stateNamesFor(bucket, config) {
787
+ const primary = config && config.states && config.states[bucket]
788
+ const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
789
+ return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
767
790
  }
768
791
 
769
792
  // Map a remote workflow-state name back to the local lifecycle bucket (the
770
793
  // vocabulary `spec_status` uses) via config.states, so local and remote
771
794
  // workflowState hash equal when semantically equal. Falls back to a lowercased
772
795
  // raw value when the state isn't one of the configured names.
773
- //
774
- // A DECLARED DEPLOYMENT STAGE reads as `complete`, deliberately. Without this
775
- // the fallback lowercases it — "On Test" becomes "on test", which equals no
776
- // bucket — and every deployed spec reports as drifted forever, for the whole
777
- // time it sits in the pipeline. The project told us these states are downstream
778
- // of a finished spec, so they are not a disagreement about where the spec is.
779
796
  function bucketForState(state, config) {
780
797
  if (state == null) return null
781
798
  const states = (config && config.states) || {}
782
799
  const want = String(state).toLowerCase().trim()
783
- for (const [bucket, name] of Object.entries(states)) {
784
- if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
800
+ for (const bucket of Object.keys(states)) {
801
+ if (stateNamesFor(bucket, config).some((name) => name.toLowerCase().trim() === want)) return bucket
785
802
  }
786
- if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
787
803
  return want
788
804
  }
789
805
 
@@ -818,11 +834,20 @@ function remoteWorkflowState(issue, config) {
818
834
  return name != null ? bucketForState(name, config) : null
819
835
  }
820
836
 
821
- // The declared ladder rung a remote issue is currently sitting on, or null.
822
- // Pairs with `remoteWorkflowState`: that says which bucket the issue maps to,
823
- // this says whether it got there by being deployed. Read-only.
824
- function remoteStage(issue, config) {
825
- return stageForState(remoteStateName(issue || {}, config), config)
837
+ // What the drift report needs to know about a remote issue's state: its name,
838
+ // the bucket it maps to, and whether it maps to one at all. Null when the
839
+ // payload carried no state — a cannot-tell, never an answer.
840
+ //
841
+ // AN UNMAPPED STATE IS NOT A DISAGREEMENT. A tracker grows states skitterspec
842
+ // never names ("Blocked", "Next Sprint"), and a ticket a person moved into one
843
+ // is not wrong about the spec — it is somewhere push does not manage, and push
844
+ // will not move it until the spec itself moves. `mapped` is what lets a report
845
+ // say that rather than accuse it.
846
+ function remoteStateReading(issue, config) {
847
+ const name = remoteStateName(issue || {}, config)
848
+ if (name == null) return null
849
+ const bucket = bucketForState(name, config)
850
+ return { name: String(name), bucket, mapped: LIFECYCLE_BUCKETS.includes(bucket) }
826
851
  }
827
852
 
828
853
  // A Linear issue title is plain text, so markdown emphasis is noise there — and
@@ -897,24 +922,16 @@ function titleFromText(text, max = 100) {
897
922
  return stripTitleMarkup(title)
898
923
  }
899
924
 
900
- // Every state NAME the config points at: the lifecycle bucket map, plus the
901
- // project's deployment ladder when it declares one. Both reach Linear the same
902
- // way and fail the same way, so both are checked by the same lookup.
925
+ // Every state NAME the config points at: the lifecycle bucket map.
903
926
  function configuredStateNames(config) {
904
- const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
905
- const stages = (config && config.release && config.release.stages) || []
906
- for (const stage of Array.isArray(stages) ? stages : []) {
907
- if (stage && typeof stage.state === 'string') names.push(stage.state)
908
- }
909
- return names
927
+ // The WRITTEN names only. An alias is never written, so one the workspace
928
+ // lacks cannot strand a push; `stateSuggestions` still names it in reports.
929
+ return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
910
930
  }
911
931
 
912
932
  // Which configured state NAMES are absent from the live workspace. The skill
913
933
  // fetches the workspace's project-status names over MCP and passes them here;
914
934
  // a non-empty result means a typo/rename that Linear would silently no-op.
915
- //
916
- // A project with no `release.stages` contributes nothing here, so the ladder
917
- // cannot make this accuse a config that was fine before it existed.
918
935
  function validateStates(config, workspaceStates) {
919
936
  const configured = configuredStateNames(config)
920
937
  const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
@@ -953,21 +970,6 @@ function stateSuggestions(config, workspaceStates) {
953
970
  const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
954
971
  out.push({ bucket, configured, suggestion, label: `states.${bucket}` })
955
972
  }
956
- // Deployment-ladder rungs, reported the same way. No suggestion is offered:
957
- // BUCKET_WORDS describes lifecycle vocabulary, and a stage name is the
958
- // project's own — guessing "On Test" meant "In Progress" would be worse than
959
- // saying nothing.
960
- const stages = (config && config.release && config.release.stages) || []
961
- for (const stage of Array.isArray(stages) ? stages : []) {
962
- if (!stage || typeof stage.state !== 'string') continue
963
- if (have.has(stage.state.toLowerCase().trim())) continue
964
- out.push({
965
- bucket: null,
966
- configured: stage.state,
967
- suggestion: null,
968
- label: `release.stages[${stage.key}]`,
969
- })
970
- }
971
973
  return out
972
974
  }
973
975
 
@@ -991,8 +993,7 @@ module.exports = {
991
993
  canonicalRemoteStatus,
992
994
  bucketForState,
993
995
  LIFECYCLE_BUCKETS,
994
- stageForState,
995
- remoteStage,
996
996
  remoteWorkflowState,
997
- LADDER_ORIGIN_BUCKET,
997
+ remoteStateReading,
998
+ stateNamesFor,
998
999
  }