add changelog extraction and signature computation for provenance

Author: LadyBluenotes

packages/skillc/src/buildLib.ts

@@ -1,14 +1,19 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { fetchDocsFromRepo } from './fetchDocs.js'
+import { ensureRepoCheckout, fetchDocsFromRepo } from './fetchDocs.js'
 import { indexDocsSnapshot } from './indexDocs.js'
 import { buildTopicsIndex } from './buildTopics.js'
 import { renderSkillMd } from './renderSkill.js'
 import { renderLibraryAgent } from './renderLibraryAgent.js'
 import { renderTanstackAgent } from './renderTanstackAgent.js'
-import { computeTemplatesHash, writeProvenance } from './provenance.js'
+import {
+  computeSignature,
+  computeTemplatesHash,
+  writeProvenance,
+} from './provenance.js'
 import { readCatalog } from './catalog.js'
 import { git } from './git.js'
+import { extractRecentChanges } from './changelog.js'
 
 type CatalogRepo = {
   repo: string
@@ -103,10 +108,18 @@ function writeProvenanceFromExisting(args: {
   commitSha: string
   templatesHash: string
   compilerVersion: string
+  changelogHash: string
 }) {
   const provenancePath = path.join(args.outDir, 'provenance.json')
   const prev = readJsonIfExists<any>(provenancePath) ?? {}
 
+  const signature = computeSignature({
+    docsHash: prev.docs_hash ?? 'sha256:0',
+    templatesHash: args.templatesHash,
+    changelogHash: args.changelogHash,
+    compilerVersion: args.compilerVersion,
+  })
+
   const provenance = {
     schema: 1,
     lib: prev.lib,
@@ -116,8 +129,9 @@ function writeProvenanceFromExisting(args: {
     commitSha: args.commitSha,
     docs_hash: prev.docs_hash,
     templates_hash: args.templatesHash,
+    changelog_hash: args.changelogHash,
     compiler_version: args.compilerVersion,
-    signature: prev.signature,
+    signature,
     generated_at: new Date().toISOString(),
   }
 
@@ -221,21 +235,33 @@ export async function buildLib(args: {
         throw err
       }
 
+      const { worktree } = ensureRepoCheckout({ repoUrl, ref })
+      const { lines: recentChanges, hash: changelogHash } =
+        extractRecentChanges({
+          worktree,
+          version: args.version,
+          tagPattern: pattern,
+        })
+
       const existingBuild = readJsonIfExists<any>(
         path.join(outAbs, 'build.json'),
       )
       const existingProv = readJsonIfExists<any>(
         path.join(outAbs, 'provenance.json'),
       )
 
-      if (
+      const matchesExistingCore =
         existingBuild &&
         existingProv &&
         existingBuild.repo === repoUrl &&
         existingBuild.ref === ref &&
         existingBuild.commitSha === commitSha &&
         existingProv.templates_hash === templatesHash &&
         existingProv.compiler_version === compilerVersion
+
+      if (
+        matchesExistingCore &&
+        existingProv.changelog_hash === changelogHash
       ) {
         console.log(`Skill build result: skipped (${args.lib}@${args.version})`)
         console.log(
@@ -244,9 +270,53 @@ export async function buildLib(args: {
         return
       }
 
+      if (matchesExistingCore) {
+        console.log(
+          `Skill build result: updated-changelog (${args.lib}@${args.version})`,
+        )
+        console.log(
+          `Updating changelog for ${args.lib}@${args.version} from ${repoUrl}@${ref} (${commitSha}).`,
+        )
+
+        renderSkillMd({
+          library: args.lib,
+          version: args.version,
+          outDir: outAbs,
+          recentChanges,
+        })
+
+        writeProvenanceFromExisting({
+          outDir: outAbs,
+          version: args.version,
+          repoUrl,
+          ref,
+          commitSha,
+          templatesHash,
+          compilerVersion,
+          changelogHash,
+        })
+
+        const buildJson = {
+          lib: args.lib,
+          version: args.version,
+          repo: repoUrl,
+          ref,
+          commitSha,
+          generatedAt: new Date().toISOString(),
+        }
+
+        fs.writeFileSync(
+          path.join(outAbs, 'build.json'),
+          JSON.stringify(buildJson, null, 2) + '\n',
+        )
+
+        return
+      }
+
       const latest = findLatestBuild({ repoRoot: args.repoRoot, lib: args.lib })
       const canReuseLatest =
         latest &&
+        latest.dir !== outAbs &&
         latest.build?.repo === repoUrl &&
         latest.build?.commitSha === commitSha &&
         latest.provenance?.templates_hash === templatesHash &&
@@ -263,6 +333,12 @@ export async function buildLib(args: {
         cloneDirWithHardlinks(latest.dir, outAbs)
 
         updateSkillVersion(outAbs, args.version)
+        renderSkillMd({
+          library: args.lib,
+          version: args.version,
+          outDir: outAbs,
+          recentChanges,
+        })
         writeProvenanceFromExisting({
           outDir: outAbs,
           version: args.version,
@@ -271,6 +347,7 @@ export async function buildLib(args: {
           commitSha,
           templatesHash,
           compilerVersion,
+          changelogHash,
         })
 
         const buildJson = {
@@ -319,7 +396,12 @@ export async function buildLib(args: {
         version: args.version,
         outDir,
       })
-      renderSkillMd({ library: args.lib, version: args.version, outDir })
+      renderSkillMd({
+        library: args.lib,
+        version: args.version,
+        outDir,
+        recentChanges,
+      })
 
       writeProvenance({
         lib: args.lib,
@@ -329,6 +411,7 @@ export async function buildLib(args: {
         indexRoot,
         compiler: { name: '@tanstack/skillc', version: compilerVersion },
         templatesRoot,
+        changelogHash,
       })
 
       const revisionPath = path.join(sourceRoot, 'REVISION.json')

packages/skillc/src/changelog.ts

@@ -0,0 +1,182 @@
+import crypto from 'node:crypto'
+import path from 'node:path'
+import { git } from './git.js'
+
+const keywordRegex =
+  /\b(breaking|migration|migrations|deprecat|fix|bug|security)\b/i
+
+function sha256(input: string | Buffer) {
+  return 'sha256:' + crypto.createHash('sha256').update(input).digest('hex')
+}
+
+function parsePackageNameFromTagPattern(pattern?: string) {
+  if (!pattern) return undefined
+  const cleaned = pattern
+    .replace('{version}', '')
+    .replace(/[@._-]+$/, '')
+    .trim()
+
+  if (/^@[^/]+\/[^@]+$/.test(cleaned)) return cleaned
+  if (/^[a-z0-9][\w.-]*$/i.test(cleaned)) return cleaned
+  return undefined
+}
+
+function listRepoFiles(worktree: string) {
+  const res = git(['ls-tree', '-r', '--name-only', 'HEAD'], worktree)
+  return res.stdout.split(/\r?\n/).filter(Boolean)
+}
+
+function readGitFile(worktree: string, filePath: string) {
+  const res = git(['show', `HEAD:${filePath}`], worktree)
+  return res.stdout
+}
+
+function findPackageDir(args: {
+  worktree: string
+  packageName: string
+  repoFiles: string[]
+}) {
+  const packageJsonPaths = args.repoFiles.filter(
+    (file) => file.startsWith('packages/') && file.endsWith('/package.json'),
+  )
+
+  for (const pkgPath of packageJsonPaths) {
+    try {
+      const pkgJson = JSON.parse(readGitFile(args.worktree, pkgPath))
+      if (pkgJson?.name === args.packageName) {
+        return path.posix.dirname(pkgPath)
+      }
+    } catch (error) {
+      continue
+    }
+  }
+
+  return undefined
+}
+
+function findChangelogPath(args: {
+  worktree: string
+  repoFiles: string[]
+  packageDir?: string
+}) {
+  const candidates: string[] = []
+
+  if (args.packageDir) {
+    candidates.push(
+      path.posix.join(args.packageDir, 'CHANGELOG.md'),
+      path.posix.join(args.packageDir, 'CHANGELOG.mdx'),
+    )
+  }
+
+  candidates.push('CHANGELOG.md', 'CHANGELOG.mdx')
+
+  for (const candidate of candidates) {
+    if (args.repoFiles.includes(candidate)) return candidate
+  }
+
+  return undefined
+}
+
+function extractVersionSection(args: {
+  markdown: string
+  version: string
+  packageName?: string
+}) {
+  const lines = args.markdown.split(/\r?\n/)
+  const patterns = [
+    args.packageName ? `${args.packageName}@${args.version}` : undefined,
+    `v${args.version}`,
+    args.version,
+  ].filter(Boolean) as string[]
+
+  let startIndex = -1
+  let headingLevel = 0
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]
+    const match = line.match(/^(#{2,4})\s+(.*)$/)
+    if (!match) continue
+    const title = match[2]
+    if (patterns.some((p) => title.includes(p))) {
+      startIndex = i + 1
+      headingLevel = match[1].length
+      break
+    }
+  }
+
+  if (startIndex === -1) return []
+
+  const section: string[] = []
+  for (let i = startIndex; i < lines.length; i += 1) {
+    const line = lines[i]
+    const match = line.match(/^(#{1,6})\s+/)
+    if (match && match[1].length <= headingLevel) break
+    section.push(line)
+  }
+
+  return section
+}
+
+function filterUserFacing(lines: string[]) {
+  const out: string[] = []
+  let pendingHeadings: string[] = []
+
+  for (const line of lines) {
+    if (/^#{2,6}\s+/.test(line)) {
+      pendingHeadings = [line]
+      if (keywordRegex.test(line)) {
+        out.push(...pendingHeadings)
+        pendingHeadings = []
+      }
+      continue
+    }
+
+    if (!keywordRegex.test(line)) continue
+
+    if (pendingHeadings.length) {
+      out.push(...pendingHeadings)
+      pendingHeadings = []
+    }
+
+    out.push(line)
+  }
+
+  return out
+}
+
+export function extractRecentChanges(args: {
+  worktree: string
+  version: string
+  tagPattern?: string
+}) {
+  const repoFiles = listRepoFiles(args.worktree)
+  const packageName = parsePackageNameFromTagPattern(args.tagPattern)
+  const packageDir = packageName
+    ? findPackageDir({
+        worktree: args.worktree,
+        packageName,
+        repoFiles,
+      })
+    : undefined
+
+  const changelogPath = findChangelogPath({
+    worktree: args.worktree,
+    repoFiles,
+    packageDir,
+  })
+
+  if (!changelogPath) {
+    return { lines: [], hash: sha256('') }
+  }
+
+  const markdown = readGitFile(args.worktree, changelogPath)
+  const section = extractVersionSection({
+    markdown,
+    version: args.version,
+    packageName,
+  })
+  const lines = filterUserFacing(section)
+  const hash = sha256(lines.join('\n'))
+
+  return { lines, hash }
+}