@erclx/canon 5.19.0 → 5.21.0

package/src/sandbox/stub-remote.ts

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+const STUB_ORG = 'stub-org'
+const ANCHOR_REPO = 'canon-sandbox'
+
+/** The URL `sandbox_anchor_url` builds once `GITHUB_ORG` names the stub organization. */
+export const STUB_ANCHOR_URL = `https://github.com/${STUB_ORG}/${ANCHOR_REPO}.git`
+
+/** Port 9 is the discard service, which nothing listens on, so a real HTTPS attempt fails. */
+const DEAD_PROXY = 'http://127.0.0.1:9'
+
+/** Pinned so a commit id depends on its tree alone and two provisions of one tree agree. */
+const PINNED_DATE = '2026-01-01T00:00:00Z'
+
+/**
+ * Answers the `gh` calls the git scenarios make and fails on any other, so a new
+ * call reaches a reader as a red arm rather than a silent pass. Every call is
+ * logged as one line, quoted so an argument holding a space stays one argument.
+ */
+const STUB_GH = `#!/usr/bin/env bash
+# stub gh
+dir="$STUB_GH_DIR"
+line="$(printf '%q ' "$@")"
+line="\${line% }"
+printf '%s\\n' "$line" >>"$dir/gh.log"
+
+case "$1" in
+api) exit 0 ;;
+pr)
+  case "$2" in
+  create)
+    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
+    count=$((count + 1))
+    echo "$count" >"$dir/pr-count"
+    echo "https://github.com/${STUB_ORG}/${ANCHOR_REPO}/pull/$count"
+    exit 0
+    ;;
+  close | list) exit 0 ;;
+  esac
+  ;;
+esac
+
+printf '%s\\n' "$line" >>"$dir/gh-unknown.log"
+echo "stub gh: unknown call: $line" >&2
+exit 1
+`
+
+/**
+ * Builds a local bare repository and a stub `gh` under `stubDir` and returns the
+ * environment that sends a provision's pushes and `gh` calls there. Nothing in
+ * it reaches the shared anchor: the URL rewrite turns every push into a file
+ * path, and the stub heads `PATH` ahead of any real `gh`.
+ */
+export function createStubRemote(stubDir: string): Record<string, string> {
+  rmSync(stubDir, { recursive: true, force: true })
+  const bin = join(stubDir, 'bin')
+  const remotes = join(stubDir, 'remotes')
+  mkdirSync(bin, { recursive: true })
+  mkdirSync(remotes, { recursive: true })
+
+  execFileSync(
+    'git',
+    ['init', '-q', '--bare', '-b', 'main', join(remotes, `${ANCHOR_REPO}.git`)],
+    { stdio: 'ignore' },
+  )
+
+  const gh = join(bin, 'gh')
+  writeFileSync(gh, STUB_GH)
+  chmodSync(gh, 0o755)
+
+  return {
+    PATH: `${bin}:${process.env.PATH ?? ''}`,
+    STUB_GH_DIR: stubDir,
+    GITHUB_ORG: STUB_ORG,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: `url.${remotes}/.insteadOf`,
+    GIT_CONFIG_VALUE_0: `https://github.com/${STUB_ORG}/`,
+    GIT_AUTHOR_DATE: PINNED_DATE,
+    GIT_COMMITTER_DATE: PINNED_DATE,
+    HTTPS_PROXY: DEAD_PROXY,
+    https_proxy: DEAD_PROXY,
+    ALL_PROXY: DEAD_PROXY,
+  }
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trimEnd()
+}
+
+function readLog(path: string): string {
+  return existsSync(path) ? readFileSync(path, 'utf8').trimEnd() : ''
+}
+
+/**
+ * Reads what a provision left in the stub: the `gh` calls, the calls it did not
+ * recognize, and for each bare repository every ref with its tip tree and the
+ * commit subjects beneath it. A tree id carries no timestamp, so it compares
+ * across two runs where a commit id would not.
+ */
+export function readStubManifest(stubDir: string): Map<string, string> {
+  const manifest = new Map<string, string>()
+  manifest.set('stub:gh', readLog(join(stubDir, 'gh.log')))
+  manifest.set('stub:gh-unknown', readLog(join(stubDir, 'gh-unknown.log')))
+
+  const remotes = join(stubDir, 'remotes')
+  if (!existsSync(remotes)) return manifest
+
+  for (const entry of readdirSync(remotes).sort()) {
+    if (!entry.endsWith('.git')) continue
+    const repo = join(remotes, entry)
+    const name = entry.slice(0, -'.git'.length)
+
+    const refs = git(repo, ['for-each-ref', '--format=%(refname) %(tree)'])
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => {
+        const ref = line.split(' ')[0] ?? ''
+        const subjects = git(repo, ['log', '--format=  %s', '--reverse', ref])
+
+        return `${line}\n${subjects}`
+      })
+    manifest.set(`stub:${name}:refs`, refs.join('\n'))
+  }
+
+  return manifest
+}

package/src/slides/convert/chart.ts

@@ -0,0 +1,165 @@
+import type PptxGenJS from 'pptxgenjs'
+import { position, type Rect } from '@/slides/convert/shapes'
+
+/**
+ * A `<figure data-chart="...">` holding a `<table>` lands as a native chart.
+ * The table stays the page's accessible source and is not also drawn. Its
+ * header row names the series and its first column names the categories.
+ */
+
+export const CHART_TYPES = ['bar', 'line', 'area', 'pie', 'doughnut'] as const
+export type ChartType = (typeof CHART_TYPES)[number]
+
+export interface ChartRecord {
+  readonly selector: string
+  readonly box: Rect
+  /** The raw `data-chart` value, checked against `CHART_TYPES` here. */
+  readonly type: string
+  readonly hasLabels: boolean
+  /** The figure's `<figcaption>`, when it has one. */
+  readonly title?: string
+  readonly rows: readonly (readonly string[])[]
+}
+
+export interface ChartTheme {
+  /** Series colors in order, repeated past the last. */
+  readonly colors: readonly string[]
+  readonly ink: string
+  readonly muted: string
+  readonly face: string
+}
+
+export interface ChartSeries {
+  readonly name: string
+  readonly labels: readonly string[]
+  /** `null` is an empty cell, which the chart draws as a gap. */
+  readonly values: readonly (number | null)[]
+}
+
+export type ChartPlan =
+  | {
+      readonly status: 'chart'
+      readonly type: ChartType
+      readonly data: readonly ChartSeries[]
+      readonly options: PptxGenJS.IChartOpts
+    }
+  | {
+      readonly status: 'refused'
+      readonly selector: string
+      readonly message: string
+    }
+
+export interface ColorRole {
+  readonly name: string
+  readonly hex: string
+}
+
+/** The grounds a series would vanish into. */
+const GROUND_ROLES = new Set(['--color-background', '--color-surface'])
+
+const NUMBER = /^-?(\d+\.?\d*|\.\d+)$/
+
+/**
+ * A comma counts as a thousands separator only where it groups in threes, so a
+ * comma-decimal `3,5` refuses rather than reading as 35.
+ */
+const GROUPED = /^-?\d{1,3}(,\d{3})+(\.\d+)?$/
+
+const isChartType = (value: string): value is ChartType =>
+  (CHART_TYPES as readonly string[]).includes(value)
+
+/**
+ * The accent, then every other declared color role in token order except the
+ * grounds, each color once. No project declares a chart palette, so the
+ * project's own roles stand in for one.
+ */
+export function seriesColors(
+  accent: string,
+  roles: readonly ColorRole[],
+): string[] {
+  const colors = [accent]
+  for (const role of roles) {
+    if (GROUND_ROLES.has(role.name) || colors.includes(role.hex)) continue
+    colors.push(role.hex)
+  }
+  return colors
+}
+
+function cycle(colors: readonly string[], count: number): string[] {
+  return Array.from(
+    { length: count },
+    (_, index) => colors[index % colors.length] ?? '',
+  )
+}
+
+export function planChart(record: ChartRecord, theme: ChartTheme): ChartPlan {
+  const refuse = (message: string): ChartPlan => ({
+    status: 'refused',
+    selector: record.selector,
+    message,
+  })
+  if (!isChartType(record.type)) {
+    return refuse(
+      `data-chart "${record.type}" is not one of ${CHART_TYPES.join(', ')}`,
+    )
+  }
+  const [header = [], ...body] = record.rows
+  if (header.length < 2 || body.length === 0) {
+    return refuse(
+      'the table needs a header row and at least one data row of two cells',
+    )
+  }
+
+  const labels = body.map((row) => row[0] ?? '')
+  const data: ChartSeries[] = []
+  for (let column = 1; column < header.length; column += 1) {
+    const values: (number | null)[] = []
+    for (const [index, row] of body.entries()) {
+      const text = (row[column] ?? '').trim()
+      if (text === '') {
+        values.push(null)
+        continue
+      }
+      const bare = GROUPED.test(text) ? text.replace(/,/g, '') : text
+      if (!NUMBER.test(bare)) {
+        return refuse(
+          `cell "${text}" at row ${index + 2}, column ${column + 1} is not a number`,
+        )
+      }
+      values.push(Number(bare))
+    }
+    data.push({ name: header[column] ?? '', labels, values })
+  }
+
+  const isRound = record.type === 'pie' || record.type === 'doughnut'
+  return {
+    status: 'chart',
+    type: record.type,
+    data,
+    options: {
+      ...position(record.box),
+      chartColors: cycle(theme.colors, isRound ? labels.length : data.length),
+      displayBlanksAs: 'gap',
+      showValue: record.hasLabels,
+      dataLabelColor: theme.ink,
+      dataLabelFontFace: theme.face,
+      showLegend: isRound || data.length > 1,
+      legendPos: 'b',
+      legendColor: theme.ink,
+      legendFontFace: theme.face,
+      catAxisLabelColor: theme.muted,
+      catAxisLabelFontFace: theme.face,
+      valAxisLabelColor: theme.muted,
+      valAxisLabelFontFace: theme.face,
+      ...(record.title
+        ? {
+            showTitle: true,
+            title: record.title,
+            titleColor: theme.ink,
+            titleFontFace: theme.face,
+            altText: record.title,
+          }
+        : {}),
+    },
+  }
+}

package/src/slides/convert/deck.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+/**
+ * What belongs to the deck rather than to one slide, read from `deck.json`
+ * beside the slides. A slide overrides a band through attributes on its own
+ * `<body>`, which `walk.ts` reads.
+ */
+
+export const DECK_FILE = 'deck.json'
+
+export const BAND_SLOTS = ['left', 'center', 'right'] as const
+export type BandSlot = (typeof BAND_SLOTS)[number]
+
+export interface Band {
+  readonly show: boolean
+  readonly left?: string
+  readonly center?: string
+  readonly right?: string
+}
+
+export interface DeckConfig {
+  readonly title: string
+  readonly header: Band
+  readonly footer: Band
+  /** Drawn at the right of the footer, so they show only where it does. */
+  readonly slideNumbers: boolean
+  /** Absolute, resolved against the deck folder. */
+  readonly mark?: string
+}
+
+export type DeckRead =
+  | { readonly status: 'read'; readonly deck: DeckConfig }
+  | {
+      readonly status: 'refused'
+      readonly field: string
+      readonly message: string
+    }
+
+const DECK_FIELDS = new Set([
+  'title',
+  'header',
+  'footer',
+  'slideNumbers',
+  'mark',
+])
+const BAND_FIELDS = new Set<string>(['show', ...BAND_SLOTS])
+
+class FieldError extends Error {
+  constructor(
+    readonly field: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function rejectUnknown(
+  record: Record<string, unknown>,
+  known: ReadonlySet<string>,
+  prefix: string,
+): void {
+  const unknown = Object.keys(record).find((key) => !known.has(key))
+  if (unknown !== undefined) {
+    throw new FieldError(
+      `${prefix}${unknown}`,
+      `unknown field ${prefix}${unknown}`,
+    )
+  }
+}
+
+function stringField(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') {
+    throw new FieldError(field, `${field} must be a string`)
+  }
+  return value
+}
+
+function booleanField(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') {
+    throw new FieldError(field, `${field} must be true or false`)
+  }
+  return value
+}
+
+/**
+ * A declared band merges over its default, so `{ "center": "x" }` keeps the
+ * footer's title on the left. Declaring any text turns a band on unless it
+ * also says `show: false`.
+ */
+function band(value: unknown, field: string, fallback: Band): Band {
+  if (value === undefined) return fallback
+  if (!isRecord(value)) {
+    throw new FieldError(field, `${field} must be an object`)
+  }
+  rejectUnknown(value, BAND_FIELDS, `${field}.`)
+  const slots: { -readonly [slot in BandSlot]?: string } = {}
+  for (const slot of BAND_SLOTS) {
+    const text = stringField(value[slot], `${field}.${slot}`)
+    if (text !== undefined) slots[slot] = text
+  }
+  const show =
+    booleanField(value.show, `${field}.show`) ??
+    (Object.keys(slots).length > 0 || fallback.show)
+  return { ...fallback, ...slots, show }
+}
+
+function parse(raw: unknown, folder: string): DeckConfig {
+  if (!isRecord(raw)) {
+    throw new FieldError(DECK_FILE, `${DECK_FILE} must hold an object`)
+  }
+  rejectUnknown(raw, DECK_FIELDS, '')
+  const title = stringField(raw.title, 'title') ?? basename(folder)
+  const header = band(raw.header, 'header', { show: false })
+  const footer = band(raw.footer, 'footer', { show: true, left: title })
+  const slideNumbers = booleanField(raw.slideNumbers, 'slideNumbers') ?? true
+  if (slideNumbers && footer.right !== undefined) {
+    throw new FieldError(
+      'footer.right',
+      'footer.right is where slide numbers sit. Set slideNumbers to false to use it',
+    )
+  }
+  const markPath = stringField(raw.mark, 'mark')
+  let mark: string | undefined
+  if (markPath !== undefined) {
+    mark = join(folder, markPath)
+    if (!existsSync(mark) || !statSync(mark).isFile()) {
+      throw new FieldError('mark', `mark ${mark} does not exist`)
+    }
+  }
+  return { title, header, footer, slideNumbers, mark }
+}
+
+export function readDeck(folder: string): DeckRead {
+  const path = join(folder, DECK_FILE)
+  let raw: unknown = {}
+  if (existsSync(path)) {
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf8'))
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      return {
+        status: 'refused',
+        field: DECK_FILE,
+        message: `${path}: not valid JSON (${reason})`,
+      }
+    }
+  }
+  try {
+    return { status: 'read', deck: parse(raw, folder) }
+  } catch (error) {
+    if (!(error instanceof FieldError)) throw error
+    return {
+      status: 'refused',
+      field: error.field,
+      message: `${path}: ${error.message}`,
+    }
+  }
+}