feat: bring back last-updated metadata and add filtered git history

config.js

@@ -1,5 +1,6 @@
 export default {
   url: 'https://www.accessibility-developer-guide.com',
+  repoUrl: 'https://github.com/Access4all/adg',
   title: 'Accessibility Developer Guide',
   description: '', // TODO: Add
   twitter: '', // TODO: Add

config/recent-pages.js

@@ -0,0 +1,37 @@
+export default [
+  {
+    commit: '23924f765de3b11b4c09bdc6ea6459a166b75317',
+    pages: [
+      'examples/hiding-elements/skip-navigation-links',
+      'knowledge/keyboard-only/skip-navigation-links'
+    ]
+  },
+  {
+    commit: '92cf70a701b23d2dcedb74a8521de7e8cac761b0',
+    pages: ['introduction/about']
+  },
+  {
+    commit: '703b03c2ef4581b27f743e3136d626a3e36edd58',
+    pages: ['examples/widgets/accordion']
+  },
+  {
+    commit: '517667bf917d002ea45092af00df472130d23f90',
+    pages: ['setup/windows/vmware-on-macos']
+  },
+  {
+    commit: '27b9f04175342243fb7a0d557a1867aa4038be09',
+    pages: ['examples/widgets/tablists']
+  },
+  {
+    commit: '9bd1f018edeb81e9d9e49e87863a3f161e92f0ff',
+    pages: ['knowledge/legal/eaa']
+  },
+  {
+    commit: '3ffb178c4c4388af0082249d4e0c8cf5bbdbea0a',
+    pages: ['examples/tables/spanning-rows-cols']
+  },
+  {
+    commit: '62db125e30d39aa7248c141561699b979738ffc9',
+    pages: ['knowledge/screen-readers/mobile/reading-websites']
+  }
+]

gulp/helpers/datetime.js

@@ -3,29 +3,53 @@
  * @param {string} date in form of '2018-07-01'
  * @returns {string} '1. July, 2018'
  */
-const formatDate = date => {
-  var monthNames = [
-    'January',
-    'February',
-    'March',
-    'April',
-    'May',
-    'June',
-    'July',
-    'August',
-    'September',
-    'October',
-    'November',
-    'December'
-  ]
+const monthNames = [
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December'
+]
 
+const formatDate = date => {
   const dateTime = new Date(date)
 
+  if (Number.isNaN(dateTime.getTime())) {
+    return ''
+  }
+
   const day = dateTime.getDate()
   const monthIndex = dateTime.getMonth()
   const year = dateTime.getFullYear()
 
   return `${monthNames[monthIndex]} ${day}, ${year}`
 }
 
-export { formatDate }
+const formatDateTime = timestamp => {
+  const dateTime = new Date(
+    typeof timestamp === 'number' && timestamp < 1_000_000_000_000
+      ? timestamp * 1000
+      : timestamp
+  )
+
+  if (Number.isNaN(dateTime.getTime())) {
+    return ''
+  }
+
+  const day = dateTime.getDate()
+  const monthIndex = dateTime.getMonth()
+  const year = dateTime.getFullYear()
+  const hours = String(dateTime.getHours()).padStart(2, '0')
+  const minutes = String(dateTime.getMinutes()).padStart(2, '0')
+
+  return `${monthNames[monthIndex]} ${day}, ${year}, ${hours}:${minutes}`
+}
+
+export { formatDate, formatDateTime }

gulp/helpers/git-metadata.js

@@ -0,0 +1,159 @@
+import childProcess from 'node:child_process'
+import crypto from 'node:crypto'
+
+const gitHistoryRef = (() => {
+  for (const ref of ['main', 'master', 'HEAD']) {
+    const result = childProcess.spawnSync(
+      'git',
+      ['rev-parse', '--verify', ref],
+      {
+        encoding: 'utf8'
+      }
+    )
+
+    if (result.status === 0) {
+      return result.stdout.trim()
+    }
+  }
+
+  return 'HEAD'
+})()
+const gravatarImageSize = 48
+
+const getGravatarUrl = email => {
+  if (!email) {
+    return ''
+  }
+
+  const normalizedEmail = String(email).trim().toLowerCase()
+
+  if (!normalizedEmail) {
+    return ''
+  }
+
+  const hash = crypto.createHash('sha256').update(normalizedEmail).digest('hex')
+
+  return `https://gravatar.com/avatar/${hash}?s=${gravatarImageSize}&d=mp`
+}
+
+// Persist across watch rebuilds; git history does not change on every markdown save.
+const changedMetadata = {}
+const fileMergeHistoryCache = {}
+const fileChangeStatsCache = new Map()
+
+export default () => {
+  const parseGitHistory = historyStdout =>
+    historyStdout
+      .split('\x1e')
+      .map(item => item.trim())
+      .filter(Boolean)
+      .map(item => {
+        const [
+          commitId = '',
+          changed = '',
+          changedTimestamp = '',
+          changedBy = '',
+          changedByEmail = '',
+          commitMessage = ''
+        ] = item.split('\x1f')
+
+        return {
+          commitId,
+          changed,
+          changedTimestamp: Number(changedTimestamp),
+          changedBy,
+          changedByEmail,
+          commitMessage,
+          gravatarUrl: getGravatarUrl(changedByEmail)
+        }
+      })
+      .filter(entry => entry.commitId)
+
+  const getFileMergeHistory = filePath => {
+    if (fileMergeHistoryCache[filePath]) {
+      return fileMergeHistoryCache[filePath]
+    }
+
+    const historyStdout = childProcess.spawnSync(
+      'git',
+      [
+        'log',
+        gitHistoryRef,
+        '--pretty=format:%H%x1f%ci%x1f%ct%x1f%an%x1f%ae%x1f%s%x1e',
+        '-m',
+        '--merges',
+        '--first-parent',
+        '--',
+        filePath
+      ],
+      { encoding: 'utf8' }
+    ).stdout
+
+    const history = parseGitHistory(historyStdout)
+
+    fileMergeHistoryCache[filePath] = history
+    return history
+  }
+
+  const getFileChangeStats = (commitId, filePath) => {
+    if (!commitId || !filePath) {
+      return { linesAdded: 0, linesDeleted: 0 }
+    }
+
+    const cacheKey = `${commitId}\x1f${filePath}`
+
+    if (fileChangeStatsCache.has(cacheKey)) {
+      return fileChangeStatsCache.get(cacheKey)
+    }
+
+    const numstatStdout = childProcess.spawnSync(
+      'git',
+      [
+        'show',
+        '-m',
+        '--first-parent',
+        '--numstat',
+        '--format=tformat:',
+        commitId,
+        '--',
+        filePath
+      ],
+      { encoding: 'utf8' }
+    ).stdout
+
+    const [numstatLine = ''] = numstatStdout
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+    const [added = '0', deleted = '0'] = numstatLine.split('\t')
+    const stats = {
+      linesAdded: added === '-' ? 0 : Number(added) || 0,
+      linesDeleted: deleted === '-' ? 0 : Number(deleted) || 0
+    }
+
+    fileChangeStatsCache.set(cacheKey, stats)
+    return stats
+  }
+
+  const getGitMetadata = filePath => {
+    if (changedMetadata[filePath]) {
+      return changedMetadata[filePath]
+    }
+
+    const latestEntry = getFileMergeHistory(filePath)[0]
+
+    const metadata = {
+      changed: latestEntry ? latestEntry.changed : '',
+      changedTimestamp: latestEntry ? latestEntry.changedTimestamp : 0,
+      changedBy: latestEntry ? latestEntry.changedBy : '',
+      gravatarUrl: latestEntry ? latestEntry.gravatarUrl : '',
+      commitId: latestEntry ? latestEntry.commitId : '',
+      commitMessage: latestEntry ? latestEntry.commitMessage : ''
+    }
+
+    changedMetadata[filePath] = metadata
+    return metadata
+  }
+
+  return { getGitMetadata, getFileChangeStats, getFileMergeHistory }
+}

gulp/helpers/page-frontmatter.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import frontMatter from 'front-matter'
+
+const pagesDirectory = './pages'
+
+const collectPageMarkdownFiles = (directory, markdownFiles = []) => {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      if (entry.name === '_examples') {
+        continue
+      }
+
+      collectPageMarkdownFiles(entryPath, markdownFiles)
+      continue
+    }
+
+    if (entry.name.endsWith('.md')) {
+      markdownFiles.push(entryPath)
+    }
+  }
+
+  return markdownFiles
+}
+
+const getPageDirectory = (filePath, pagesRoot) => {
+  const relativePath = path.relative(pagesRoot, filePath)
+  const relativeDirectory = path.dirname(relativePath)
+
+  return relativeDirectory === '.' ? '' : relativeDirectory.replace(/\\/g, '/')
+}
+
+const getPagesWithFrontMatterFlag = (rootDir, flag) => {
+  const pagesRoot = path.join(rootDir, pagesDirectory)
+
+  return collectPageMarkdownFiles(pagesRoot)
+    .map(filePath => {
+      const { attributes } = frontMatter(fs.readFileSync(filePath, 'utf8'))
+
+      if (!attributes[flag]) {
+        return null
+      }
+
+      return {
+        filePath,
+        directory: getPageDirectory(filePath, pagesRoot)
+      }
+    })
+    .filter(Boolean)
+}
+
+const getDevOnlyPageGlobs = rootDir =>
+  getPagesWithFrontMatterFlag(rootDir, 'dev_only').map(
+    ({ filePath, directory }) =>
+      `!./pages/${directory || path.basename(filePath, path.extname(filePath))}/**/*.md`
+  )
+
+const getDevOnlyDistPaths = rootDir =>
+  getPagesWithFrontMatterFlag(rootDir, 'dev_only').map(
+    ({ directory }) => `./dist/${directory}`
+  )
+
+export { getDevOnlyDistPaths, getDevOnlyPageGlobs }