kaloko 0.5.1 → 0.6.0

package/src/lib/changelog-core.mjs

@@ -0,0 +1,323 @@
+// The visual changelog (docs/DOCS-CHANGELOG.md, phase 1), the parts the CLI and the service share: step references
+// in Markdown, Keep a Changelog parsing and editing, commit classification and the draft skeleton. No I/O here: the
+// worker imports this file too (worker/src/changelog.js), so it stays plain JavaScript without Node built-ins.
+
+// ---------- step references ----------
+
+/** Scenario and step ids as the service accepts them (design.js SCENARIO_ID). */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/
+const PARAMS = {
+  locale: /^[A-Za-z0-9_-]{1,20}$/,
+  viewport: /^[A-Za-z0-9._-]{1,80}$/,
+  version: /^[A-Za-z0-9._+-]{1,80}$/,
+  state: /^[A-Za-z0-9._-]{1,60}$/
+}
+export const REF_SCHEME = 'kaloko:'
+
+/**
+ * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=]`, or the short `kaloko:<step>` that
+ * means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev` (the
+ * release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
+ * dimension values in the capture key). Returns null for anything else.
+ */
+export function parseStepRef (ref) {
+  const s = String(ref || '').trim()
+  if (!s.startsWith(REF_SCHEME)) return null
+  const rest = s.slice(REF_SCHEME.length)
+  const qi = rest.indexOf('?')
+  const path = qi < 0 ? rest : rest.slice(0, qi)
+  let parts
+  try { parts = path.split('/').map((p) => decodeURIComponent(p)) } catch { return null }
+  if (!parts.length || parts.length > 2 || parts.some((p) => !ID.test(p))) return null
+  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null }
+  const q = new URLSearchParams(qi < 0 ? '' : rest.slice(qi + 1))
+  for (const [k, v] of q) {
+    if (!(k in PARAMS)) return null
+    if (!PARAMS[k].test(v)) return null
+    out[k] = v
+  }
+  if (out.version === 'latest') out.version = null
+  return out
+}
+
+/** The reference text of a parsed (or hand-built) reference; parameters in a fixed order. */
+export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null }) {
+  const path = `${scenario ? `${encodeURIComponent(scenario)}/` : ''}${encodeURIComponent(step)}`
+  const q = Object.entries({ locale, viewport, version, state }).filter(([, v]) => v != null && v !== '')
+  return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}`
+}
+
+/** Every image with a step reference in a Markdown text: { alt, ref, parsed, index }; broken ones have parsed null. */
+export function findStepRefs (markdown) {
+  const out = []
+  const re = /!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g
+  let m
+  while ((m = re.exec(String(markdown || '')))) out.push({ alt: m[1], ref: m[2], parsed: parseStepRef(m[2]), index: m.index })
+  return out
+}
+
+// ---------- versions ----------
+
+/** "v2.4.0" → "2.4.0"; anything else stays as it is (trimmed). */
+export const cleanVersion = (v) => String(v ?? '').trim().replace(/^v(?=\d)/, '')
+
+/** Semantic Versioning order (prereleases before their release); versions that are not semver sort by text. */
+export function compareVersions (a, b) {
+  const p = (v) => { const m = cleanVersion(v).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/); return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || null } : null }
+  const x = p(a); const y = p(b)
+  if (!x || !y) return String(a).localeCompare(String(b))
+  for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] - y.n[i]
+  if (x.pre === y.pre) return 0
+  if (!x.pre) return 1
+  if (!y.pre) return -1
+  return x.pre.localeCompare(y.pre, 'en', { numeric: true })
+}
+
+/** The git tag of a version for a tag pattern ("v*" → "v2.4.0", "shop-v*" → "shop-v2.4.0"). */
+export const tagFor = (pattern, version) => String(pattern || 'v*').replace('*', cleanVersion(version))
+/** The version a tag names under a pattern, or null when the tag does not match it. */
+export function versionOfTag (pattern, tag) {
+  const [pre, post = ''] = String(pattern || 'v*').split('*')
+  const t = String(tag || '')
+  if (!t.startsWith(pre) || !t.endsWith(post) || t.length <= pre.length + post.length) return null
+  return cleanVersion(t.slice(pre.length, t.length - post.length))
+}
+
+// ---------- Keep a Changelog ----------
+
+export const GROUPS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+const GROUP_ALIASES = { added: 'Added', new: 'Added', features: 'Added', 'minor changes': 'Added', changed: 'Changed', 'patch changes': 'Fixed', 'major changes': 'Changed', improvements: 'Changed', deprecated: 'Deprecated', removed: 'Removed', fixed: 'Fixed', 'bug fixes': 'Fixed', fixes: 'Fixed', security: 'Security', 'performance improvements': 'Changed' }
+/** A group heading as written by people or release tools ("Bug Fixes", "Minor Changes") in Keep a Changelog terms. */
+export const groupName = (h) => GROUP_ALIASES[String(h || '').trim().toLowerCase()] || String(h || '').trim()
+
+export const CHANGELOG_HEAD = `# Changelog
+
+All notable changes for the people who use this product. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow
+[Semantic Versioning](https://semver.org/). Pictures are step references
+(\`![](kaloko:<scenario>/<step>)\`) that Kaloko shows from the accepted runs.
+`
+export const CHANGELOG_SKELETON = `${CHANGELOG_HEAD}
+## [Unreleased]
+`
+
+const RELEASE_HEADING = /^##\s+(.+?)\s*$/
+const DATE = /(\d{4}-\d{2}-\d{2})/
+
+/** "## [2.4.0] - 2026-10-12", "## [1.2.0](https://…compare…) (2026-10-12)", "## 1.2.0", "## [Unreleased]". */
+export function parseHeading (line) {
+  const m = String(line).match(RELEASE_HEADING)
+  if (!m || /^#/.test(m[1])) return null
+  const text = m[1]
+  const bracket = text.match(/^\[([^\]]+)\]/)
+  const label = (bracket ? bracket[1] : text.split(/\s+/)[0]).trim()
+  if (/^unreleased$/i.test(label)) return { unreleased: true, version: null, date: null }
+  const version = cleanVersion(label)
+  if (!/^\d/.test(version)) return null
+  const rest = text.slice(bracket ? bracket[0].length : label.length)
+  return { unreleased: false, version, date: (rest.match(DATE) || [])[1] || null }
+}
+
+/** List items of a group body: each item keeps its continuation lines (pictures under it), without the "- ". */
+export function listItems (body) {
+  const items = []
+  let cur = null
+  for (const line of String(body || '').split('\n')) {
+    const m = line.match(/^[-*+]\s+(.*)$/)
+    if (m) { if (cur) items.push(cur.trimEnd()); cur = m[1]; continue }
+    if (cur != null && (/^\s+\S/.test(line) || line.trim() === '')) { cur += `\n${line.replace(/^ {1,4}/, '')}`; continue }
+    if (cur != null) { items.push(cur.trimEnd()); cur = null }
+  }
+  if (cur) items.push(cur.trimEnd())
+  return items.map((x) => x.replace(/\n+$/, '')).filter(Boolean)
+}
+
+/** Groups of a release body: [{ name, heading, items }] plus text before the first group (notes). */
+export function parseEntry (body) {
+  const groups = []; const notes = []
+  let cur = null
+  for (const line of String(body || '').replace(/\r/g, '').split('\n')) {
+    const h = line.match(/^###\s+(.+?)\s*$/)
+    if (h) { cur = { name: groupName(h[1]), heading: h[1].trim(), lines: [] }; groups.push(cur); continue }
+    if (cur) cur.lines.push(line); else notes.push(line)
+  }
+  return { notes: notes.join('\n').trim(), groups: groups.map((g) => ({ name: g.name, heading: g.heading, items: listItems(g.lines.join('\n')) })).filter((g) => g.items.length || g.name) }
+}
+
+/**
+ * A changelog file: { head (text before the first release heading), sections: [{ unreleased, version, date, heading,
+ * body, start, end }] (line numbers, end exclusive), links (the reference definitions at the bottom, by lower-case
+ * label), linksStart }.
+ */
+export function parseChangelog (text) {
+  const lines = String(text || '').replace(/\r/g, '').split('\n')
+  let linksStart = lines.length
+  while (linksStart > 0 && (/^\[[^\]]+\]:\s*\S+/.test(lines[linksStart - 1]) || lines[linksStart - 1].trim() === '')) linksStart--
+  if (!lines.slice(linksStart).some((l) => /^\[[^\]]+\]:/.test(l))) linksStart = lines.length
+  const links = {}
+  for (const l of lines.slice(linksStart)) { const m = l.match(/^\[([^\]]+)\]:\s*(\S+)/); if (m) links[m[1].toLowerCase()] = m[2] }
+  const sections = []
+  for (let i = 0; i < linksStart; i++) {
+    const h = /^##\s/.test(lines[i]) ? parseHeading(lines[i]) : null
+    if (!h) continue
+    if (sections.length) sections[sections.length - 1].end = i
+    sections.push({ ...h, heading: lines[i], start: i, end: linksStart })
+  }
+  for (const s of sections) s.body = lines.slice(s.start + 1, s.end).join('\n').trim()
+  const head = lines.slice(0, sections.length ? sections[0].start : linksStart).join('\n').trimEnd()
+  return { head, sections, links, linksStart, lines }
+}
+
+/** The section of a version (or the Unreleased one for null), or null. */
+export function sectionOf (text, version) {
+  const { sections } = parseChangelog(text)
+  const v = version == null ? null : cleanVersion(version)
+  return sections.find((s) => v == null ? s.unreleased : !s.unreleased && s.version === v) || null
+}
+
+/** The newest released version written in the file (null when none). */
+export function latestVersionIn (text) {
+  const v = parseChangelog(text).sections.filter((s) => !s.unreleased).map((s) => s.version)
+  return v.sort(compareVersions).pop() || null
+}
+
+const norm = (item) => String(item).split('\n')[0].replace(/<!--[\s\S]*?-->/g, '').replace(/\s+/g, ' ').trim().toLowerCase()
+
+/** Markdown of groups ({ Added: [items] } in Keep a Changelog order; other names after them). */
+export function groupsMarkdown (groups) {
+  const names = [...GROUPS.filter((g) => groups[g]?.length), ...Object.keys(groups).filter((g) => !GROUPS.includes(g) && groups[g]?.length)]
+  return names.map((g) => `### ${g}\n\n${groups[g].map((it) => `- ${String(it).split('\n').map((l, i) => i && l ? `  ${l}` : l).join('\n')}`).join('\n')}`).join('\n\n')
+}
+
+/**
+ * Puts draft items into the Unreleased section of a changelog: items whose first line is already there are left
+ * out, groups that exist get the new items at their end, missing groups are added in Keep a Changelog order. A file
+ * without an Unreleased section gets one above the newest release; an empty file gets the skeleton.
+ * Returns { text, added } (the number of new items).
+ */
+export function applyDraft (text, groups) {
+  let src = String(text || '')
+  if (!src.trim()) src = CHANGELOG_SKELETON
+  let parsed = parseChangelog(src)
+  let un = parsed.sections.find((s) => s.unreleased)
+  if (!un) {
+    const lines = parsed.lines
+    const at = parsed.sections.length ? parsed.sections[0].start : parsed.linksStart
+    const before = lines.slice(0, at); while (before.length && before[before.length - 1].trim() === '') before.pop()
+    src = [...before, '', '## [Unreleased]', '', ...lines.slice(at)].join('\n')
+    parsed = parseChangelog(src)
+    un = parsed.sections.find((s) => s.unreleased)
+  }
+  const existing = parseEntry(un.body)
+  const seen = new Set(parsed.sections.flatMap((s) => parseEntry(s.body).groups.flatMap((g) => g.items.map(norm))))
+  const merged = new Map(existing.groups.map((g) => [g.name, { heading: g.heading, items: [...g.items] }]))
+  let added = 0
+  for (const [name, items] of Object.entries(groups)) {
+    for (const it of items || []) {
+      if (seen.has(norm(it))) continue
+      seen.add(norm(it))
+      if (!merged.has(name)) merged.set(name, { heading: name, items: [] })
+      merged.get(name).items.push(it); added++
+    }
+  }
+  const order = [...GROUPS.filter((g) => merged.has(g)), ...[...merged.keys()].filter((g) => !GROUPS.includes(g))]
+  const body = [existing.notes, ...order.map((g) => { const x = merged.get(g); return groupsMarkdown({ [g]: x.items }).replace(/^### [^\n]+/, `### ${x.heading}`) })].filter(Boolean).join('\n\n')
+  const lines = parsed.lines
+  const out = [...lines.slice(0, un.start + 1), '', ...(body ? [body, ''] : []), ...lines.slice(un.end)]
+  return { text: out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n'), added }
+}
+
+/**
+ * Turns the Unreleased section into the release `version` of `date` and opens a new, empty Unreleased section above
+ * it. Compare links at the bottom ([unreleased]: …/compare/v1...HEAD) move along. Returns { text, changed, empty }.
+ */
+export function finalizeRelease (text, version, date, { tagPattern = 'v*' } = {}) {
+  const v = cleanVersion(version)
+  const parsed = parseChangelog(text)
+  if (parsed.sections.some((s) => !s.unreleased && s.version === v)) return { text, changed: false, empty: false }
+  const un = parsed.sections.find((s) => s.unreleased)
+  if (!un) return { text, changed: false, empty: true }
+  const lines = [...parsed.lines]
+  lines.splice(un.start, 1, '## [Unreleased]', '', `## [${v}] - ${date}`)
+  let out = lines.join('\n')
+  const link = parsed.links.unreleased
+  const m = link && link.match(/^(.*\/compare\/)(.+)\.\.\.HEAD$/)
+  if (m) {
+    const tag = tagFor(tagPattern, v)
+    out = out.replace(/^\[unreleased\]:\s*\S+$/im, `[unreleased]: ${m[1]}${tag}...HEAD\n[${v}]: ${m[1]}${m[2]}...${tag}`)
+  }
+  return { text: out, changed: true, empty: !un.body.trim() }
+}
+
+// ---------- commits and the draft ----------
+
+const CONVENTIONAL = /^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/
+const INTERNAL = new Set(['docs', 'test', 'tests', 'chore', 'ci', 'build', 'style', 'refactor', 'release', 'wip', 'deps'])
+const TYPE_GROUP = { feat: 'Added', feature: 'Added', add: 'Added', fix: 'Fixed', bugfix: 'Fixed', hotfix: 'Fixed', perf: 'Changed', revert: 'Changed', remove: 'Removed', deprecate: 'Deprecated', security: 'Security', sec: 'Security' }
+
+/**
+ * Where a commit or pull request title goes: { group, text, internal, breaking, pr }. Conventional Commits when the
+ * title uses them; otherwise the first verb decides (add → Added, fix → Fixed, remove → Removed, else Changed).
+ * Documentation, tests, chores, CI, refactors, merges and releases are internal.
+ */
+export function classifyCommit (subject, body = '') {
+  let s = String(subject || '').trim()
+  let pr = null
+  const sq = s.match(/\s*\(#(\d+)\)\s*$/)
+  if (sq) { pr = Number(sq[1]); s = s.slice(0, sq.index).trim() }
+  const breaking = /BREAKING[ -]CHANGE/.test(body)
+  if (/^Merge\b|^Revert "|^v?\d+\.\d+\.\d+$|\[skip changelog\]|\[no changelog\]/i.test(s)) return { group: null, text: s, internal: true, breaking, pr }
+  const m = s.match(CONVENTIONAL)
+  if (m) {
+    const type = m[1].toLowerCase()
+    const text = sentence(m[4])
+    if (INTERNAL.has(type) && !m[3] && !breaking) return { group: null, text, internal: true, breaking: false, pr, type, scope: m[2] || null }
+    const group = TYPE_GROUP[type] || (/^(remove|drop|delete)\b/i.test(m[4]) ? 'Removed' : 'Changed')
+    return { group: m[3] || breaking ? (group === 'Added' ? 'Added' : 'Changed') : group, text, internal: false, breaking: !!m[3] || breaking, pr, type, scope: m[2] || null }
+  }
+  const verb = s.toLowerCase()
+  const group = /^(add|adds|added|new|introduce|support|allow|enable)\b/.test(verb) ? 'Added'
+    : /^(fix|fixes|fixed|correct|repair|resolve|prevent)\b/.test(verb) ? 'Fixed'
+      : /^(remove|removes|removed|drop|delete)\b/.test(verb) ? 'Removed'
+        : /^(deprecate)\b/.test(verb) ? 'Deprecated' : 'Changed'
+  return { group, text: sentence(s), internal: false, breaking, pr }
+}
+const sentence = (t) => { const x = String(t || '').trim().replace(/\.$/, ''); return x ? x[0].toUpperCase() + x.slice(1) : x }
+
+/**
+ * The draft entry: items grouped Added / Changed / Fixed / Removed (Deprecated, Security when present).
+ *
+ * commits  [{ subject, body, pr: { number, url } | null }] — merged pull requests or commits since the last release
+ * changes  [{ scenario, title, steps: [{ step, title, reason: new|changed|removed, pr: number|null }] }] — what the
+ *          accepted runs since the last release show differently (from the service)
+ * Pictures are step references: a changed step gets before and after (`?version=prev` is the previous release), a
+ * new step one picture. A step whose run came from a pull request goes under that pull request's item.
+ * Returns { groups, internal (titles left out), markdown }.
+ */
+export function draftEntry ({ commits = [], changes = [], scenarioLabel = (s) => s.title || s.scenario } = {}) {
+  const groups = {}
+  const internal = []
+  const byPr = new Map()
+  const add = (g, item) => { (groups[g] ||= []).push(item); return groups[g].length - 1 }
+  for (const c of commits) {
+    const k = classifyCommit(c.subject, c.body)
+    if (k.internal) { internal.push(c.subject); continue }
+    const number = c.pr?.number || k.pr
+    const url = c.pr?.url || null
+    const text = `${k.text}${k.breaking ? ' (breaking: say what people have to do)' : ''}${number ? ` (${url ? `[#${number}](${url})` : `#${number}`})` : ''}`
+    const i = add(k.group, text)
+    if (number && !byPr.has(number)) byPr.set(number, { group: k.group, i })
+  }
+  for (const sc of changes) {
+    for (const st of sc.steps || []) {
+      const ref = (version) => formatStepRef({ scenario: sc.scenario, step: st.step, version })
+      const title = st.title || st.step
+      const pics = st.reason === 'new' ? `![${title}](${ref(null)})` : st.reason === 'removed' ? `![${title} before](${ref('prev')})` : `![${title} before](${ref('prev')}) ![${title} after](${ref(null)})`
+      const home = st.pr && byPr.get(st.pr)
+      if (home) { groups[home.group][home.i] += `\n${pics}`; continue }
+      const g = st.reason === 'new' ? 'Added' : st.reason === 'removed' ? 'Removed' : 'Changed'
+      add(g, `**${title}** in ${scenarioLabel(sc)} <!-- say what a person notices here -->\n${pics}`)
+    }
+  }
+  return { groups, internal, markdown: groupsMarkdown(groups) }
+}