feat(web): show the build commit and time in the footer (#3788)

Author: abraham

packages/web/build/build-info.test.ts

@@ -0,0 +1,25 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { buildInfo } from './build-info';
+
+describe('buildInfo', () => {
+  const now = new Date('2027-10-15T09:00:00Z');
+
+  it('has the short commit and the time', () => {
+    expect(buildInfo(process.cwd(), now)).toEqual({
+      sha: expect.stringMatching(/^[0-9a-f]{7,}$/),
+      time: '2027-10-15T09:00:00.000Z',
+    });
+  });
+
+  it('leaves out the commit outside a git checkout', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'hoverboard-build-'));
+    try {
+      expect(buildInfo(dir, now)).toEqual({ time: '2027-10-15T09:00:00.000Z' });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

packages/web/build/build-info.ts

@@ -0,0 +1,27 @@
+import { execFileSync } from 'node:child_process';
+
+export interface BuildInfo {
+  /** The short commit SHA. Missing outside a git checkout. */
+  sha?: string;
+  /** When the build started, in ISO 8601. */
+  time: string;
+}
+
+const shortSha = (cwd: string): string | undefined => {
+  try {
+    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return sha || undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** The commit and time of this build, which the footer shows. */
+export const buildInfo = (cwd = process.cwd(), now = new Date()): BuildInfo => {
+  const sha = shortSha(cwd);
+  return { ...(sha ? { sha } : {}), time: now.toISOString() };
+};

packages/web/build/resolve-config.test.ts

@@ -609,7 +609,10 @@ describe('siteModule', () => {
     ...resolveConfig({ paths: repoPaths, nodeEnv: 'production' }),
     contentTranslations: { es: { title: 'DevFest en español' } },
   };
-  const plugin = siteModule(config, { siteDir: repoPaths.site });
+  const plugin = siteModule(config, {
+    siteDir: repoPaths.site,
+    build: { sha: 'abc1234', time: '2027-10-15T09:00:00.000Z' },
+  });
   const resolveId = plugin.resolveId as (id: string) => string | undefined;
   const load = plugin.load as (id: string) => Promise<string | undefined>;
 
@@ -621,6 +624,9 @@ describe('siteModule', () => {
       'export const contentTranslations = {"es": () => import("virtual:hoverboard/content/es")};',
     );
     expect(code).toContain('export const heroIllustration = undefined;');
+    expect(code).toContain(
+      'export const build = {"sha":"abc1234","time":"2027-10-15T09:00:00.000Z"};',
+    );
     expect(await load(resolveId('virtual:hoverboard/content/es')!)).toBe(
       'export default {"title":"DevFest en español"};\n',
     );

packages/web/build/site-module.d.ts

@@ -1,4 +1,5 @@
 // Types for `virtual:hoverboard/site`, which vite-plugin-site.ts serves. tsconfig.json maps it here.
+import type { BuildInfo } from './build-info';
 import type { SiteConfig } from './resolve-config';
 
 export declare const site: SiteConfig['site'];
@@ -7,3 +8,4 @@ export declare const resources: SiteConfig['resources'];
 export declare const contentTranslations: Record<string, () => Promise<{ default: object }>>;
 /** `heroSettings.home.illustration`, the SVG file's markup. */
 export declare const heroIllustration: string | undefined;
+export declare const build: BuildInfo;

packages/web/build/vite-plugin-site.ts

@@ -5,6 +5,7 @@ import n from 'nunjucks';
 import type { Plugin, PluginOption } from 'vite';
 import copy from 'rollup-plugin-copy';
 import { FEATURES, type Feature } from '../src/config/features';
+import { buildInfo } from './build-info';
 import { fontModuleCode, fontModuleParts } from './fonts';
 import {
   CONFIG_PATHS,
@@ -49,7 +50,12 @@ export const featureDefines = (features: Record<Feature, boolean>): Record<strin
  */
 export const siteModule = (
   config: SiteConfig,
-  { defineFeatures = true, siteDir = CONFIG_PATHS.site, publicDir = CONFIG_PATHS.public } = {},
+  {
+    defineFeatures = true,
+    siteDir = CONFIG_PATHS.site,
+    publicDir = CONFIG_PATHS.public,
+    build = buildInfo(),
+  } = {},
 ): Plugin => ({
   name: 'hoverboard-site-module',
   config: () => (defineFeatures ? { define: featureDefines(config.site.features) } : {}),
@@ -74,6 +80,7 @@ export const siteModule = (
         `export const resources = ${JSON.stringify(resources)};`,
         `export const contentTranslations = {${loaders.join(', ')}};`,
         `export const heroIllustration = ${JSON.stringify(heroIllustrationSvg(site, publicDir))};`,
+        `export const build = ${JSON.stringify(build)};`,
         '',
       ].join('\n');
     }

packages/web/src/components/footer/footer-nav.test.ts

@@ -3,14 +3,22 @@ import { screen, within } from '@testing-library/dom';
 import { html } from 'lit';
 import { fixture } from '../../../__tests__/helpers/fixtures';
 import { setFeatures } from '../../../__tests__/helpers/features';
-import { organizer } from '../../config/site';
+import { build, organizer } from '../../config/site';
 import './footer-nav';
 
 describe('footer-nav', () => {
   it('defines a component', () => {
     expect(customElements.get('footer-nav')).toBeDefined();
   });
 
+  it('shows the commit and time of the build, in UTC', async () => {
+    const { shadowRootForWithin } = await fixture(html`<footer-nav></footer-nav>`);
+    const time = within(shadowRootForWithin).getByText(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC$/);
+
+    expect(time).toHaveAttribute('datetime', build.time);
+    expect(within(shadowRootForWithin).getByText(build.sha ?? '', { exact: false })).toBeVisible();
+  });
+
   it('renders organizer logo and links', async () => {
     const { shadowRootForWithin } = await fixture(
       html`<footer-nav data-testid="footer"></footer-nav>`,

packages/web/src/components/footer/footer-nav.ts

@@ -2,7 +2,7 @@ import { msg } from '@lit/localize';
 import { css, html, nothing } from 'lit';
 import { customElement } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
-import { organizer } from '../../config/site';
+import { build, organizer } from '../../config/site';
 import { safeUrl } from '../../utils/safe-url';
 import { navigationLabel } from '../shell/navigation-label';
 import { ThemedElement } from '../themed-element';
@@ -70,6 +70,11 @@ export class FooterNav extends ThemedElement {
               ? html`· <a class="coc" href="/coc">${navigationLabel('codeOfConduct')}</a>`
               : nothing
           }
+          <span class="build"
+            >· ${build.sha ? html`${build.sha} · ` : nothing}<time datetime="${build.time}"
+              >${build.time.slice(0, 16).replace('T', ' ')} UTC</time
+            ></span
+          >
         </div>
       </div>
     `;

packages/web/src/config/site.ts

@@ -1,6 +1,7 @@
 // The only client entry point for site config. Read config from here, never from the data files.
 
 import {
+  build,
   contentTranslations,
   heroIllustration,
   resources,
@@ -13,6 +14,8 @@ import { deepMerge } from './merge';
 export const { basepath, heroSettings, image, organizer, url } = settings;
 /** The site's own hero illustration's markup, from `heroSettings.home.illustration`. */
 export { heroIllustration };
+/** The commit and time of the build. */
+export { build };
 export const shortName = settings.shortName;
 /** `system` lets visitors pick a scheme in the footer. `light` and `dark` lock the site to one. */
 export const colorScheme = settings.theme.colorScheme as 'system' | 'light' | 'dark';

packages/web/src/data/build.ts

@@ -2,13 +2,12 @@
 import { ClientRouter } from 'astro:transitions';
 import { fontCss, fontStylesheets } from 'virtual:hoverboard/fonts';
 import { theme, themeCss } from 'virtual:hoverboard/layout';
-import { resources, site } from 'virtual:hoverboard/site';
+import { resources, site, build } from 'virtual:hoverboard/site';
 import '../styles/base.css';
 import { FooterBlock } from '../components/footer/footer-block';
 import { AppHeader, demoBanner } from '../components/shell/app-header';
 import { AppOverlays } from '../components/shell/app-overlays';
 import { loadContent } from '../data/content';
-import { BUILD_ID } from '../data/build';
 import '../data/markdown';
 import { seedPage } from '../data/page';
 import { openGraphLocale } from '../data/structured-data';
@@ -79,7 +78,7 @@ await demoBanner;
     <meta content={resources.keywords} name="keywords" />
     <meta content={site.organizer.name} name="author" />
     <meta content="Project Hoverboard" name="generator" />
-    <meta content={BUILD_ID} name={BUILD_META} />
+    <meta content={build.time} name={BUILD_META} />
 
     <title>{title}</title>