Content Registry

Generated Provenance for Chapters, Units & Figures

Content Registry

Chapter and figure provenance – entirely derived from git history, the filesystem, chapter frontmatter, and existing quality-gate reports by scripts/generate-content-registry.py, regenerated on every build. Nothing on this page is hand-maintained; if a fact can’t be derived this way it isn’t shown. See docs-internal/ops/content-registry.md for the full derivation notes and the first real-run findings.

Auth = {
  const deadline = Date.now() + 4000;
  while (!(window.Auth && typeof window.Auth.getCurrentUser === "function") && Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 30));
  }
  return window.Auth || {};
}

colors = ({
  navy: '#2C3E50',
  teal: '#16A085',
  orange: '#E67E22',
  red: '#C0392B',
  gray: '#7F8C8D'
})

currentUser = {
  const user = Auth.getCurrentUser();
  if (!user) return null;
  // B8: the admin role is a database fact -- public.is_admin(), backed by the
  // user_roles table and evaluated by the same RLS policies that guard every
  // query below. Auth.isUserAdmin() only string-matches the adminUsers list
  // that ships in public JavaScript, so it is not a control.
  const isAdmin = window.IoTClassSupabase?.isAdminServerSide
    ? await window.IoTClassSupabase.isAdminServerSide()
    : false;
  return { ...user, isAdmin };
}

registry = {
  if (!currentUser || !currentUser.isAdmin) return null;
  try {
    const res = await fetch('/assets/data/content-registry.json');
    if (!res.ok) return null;
    return await res.json();
  } catch (error) {
    console.error('Error loading content registry:', error);
    return null;
  }
}

mutable viewState = ({
  tab: 'chapters',
  search: '',
  module: 'all',
  sortBy: 'path',
  sortDir: 'asc',
  figureFilter: 'all'
})

chaptersArr = registry ? Object.values(registry.chapters) : []
figuresArr = registry ? Object.values(registry.figures) : []

moduleOptions = {
  if (!registry) return [];
  const mods = new Set();
  chaptersArr.forEach(c => mods.add(c.module));
  figuresArr.forEach(f => mods.add(f.scope.startsWith('module:') ? f.scope.slice(7) : null));
  mods.delete(null);
  return Array.from(mods).sort();
}

gateFindingCount = (rec) => rec.gate_findings ? Object.values(rec.gate_findings).reduce((a,b) => a+b, 0) : 0

sortRows = (rows, sortBy, sortDir) => {
  const dir = sortDir === 'desc' ? -1 : 1;
  return [...rows].sort((a, b) => {
    const av = a[sortBy], bv = b[sortBy];
    if (av == null && bv == null) return 0;
    if (av == null) return 1;
    if (bv == null) return -1;
    if (typeof av === 'number' && typeof bv === 'number') return (av - bv) * dir;
    return String(av).localeCompare(String(bv)) * dir;
  });
}

filteredChapters = {
  if (!registry) return [];
  const vs = viewState;
  let rows = chaptersArr;
  if (vs.module !== 'all') rows = rows.filter(c => c.module === vs.module);
  if (vs.search) {
    const q = vs.search.toLowerCase();
    rows = rows.filter(c =>
      c.path.toLowerCase().includes(q) ||
      (c.title || '').toLowerCase().includes(q) ||
      (c.nav_title || '').toLowerCase().includes(q)
    );
  }
  return sortRows(rows, vs.sortBy, vs.sortDir);
}

filteredFigures = {
  if (!registry) return [];
  const vs = viewState;
  let rows = figuresArr;
  if (vs.module !== 'all') rows = rows.filter(f => f.scope === `module:${vs.module}`);
  if (vs.figureFilter === 'orphan') rows = rows.filter(f => f.orphan);
  if (vs.figureFilter === 'gate-flagged') rows = rows.filter(f => gateFindingCount(f) > 0);
  if (vs.search) {
    const q = vs.search.toLowerCase();
    rows = rows.filter(f => f.path.toLowerCase().includes(q));
  }
  return sortRows(rows, vs.sortBy, vs.sortDir);
}

html`${(!Auth.isUserAuthenticated || !Auth.isUserAuthenticated() || !currentUser?.isAdmin) ? `
  <div class="access-denied">
    <div style="font-size: 72px; margin-bottom: 20px;">🔒</div>
    <h2 style="color: ${colors.navy}; margin-bottom: 16px;">Access Denied</h2>
    <p style="color: ${colors.gray}; margin-bottom: 24px;">
      You must be an administrator to access this page.
    </p>
  </div>
` : ''}`

html`${currentUser?.isAdmin && !registry ? `
  <div class="access-denied">
    <div style="font-size: 48px; margin-bottom: 12px;">⚠️</div>
    <p style="color: ${colors.gray};">
      Could not load <code>/assets/data/content-registry.json</code>. Run
      <code>python3 scripts/generate-content-registry.py</code> to generate it.
    </p>
  </div>
` : ''}`

pct = (num, den) => den ? Math.round((num / den) * 1000) / 10 : 0

html`${currentUser?.isAdmin && registry ? `
  <!-- Summary Cards -->
  <div class="summary-cards">
    <div class="summary-card">
      <div class="summary-value">${registry.summary.chapters.toLocaleString()}</div>
      <div class="summary-label">Chapters</div>
    </div>
    <div class="summary-card">
      <div class="summary-value">${registry.summary.chapters_with_unit_metadata.toLocaleString()}</div>
      <div class="summary-label">Units Covered (${pct(registry.summary.chapters_with_unit_metadata, registry.summary.chapters)}%)</div>
    </div>
    <div class="summary-card">
      <div class="summary-value">${registry.summary.figures.toLocaleString()}</div>
      <div class="summary-label">Figures</div>
    </div>
    <div class="summary-card ${registry.summary.orphan_figures ? 'has-issues' : 'is-clean'}">
      <div class="summary-value">${registry.summary.orphan_figures.toLocaleString()}</div>
      <div class="summary-label">Orphan Figures (${pct(registry.summary.orphan_figures, registry.summary.figures)}%)</div>
    </div>
    <div class="summary-card ${registry.summary.dangling_figure_refs ? 'has-issues' : 'is-clean'}">
      <div class="summary-value">${registry.summary.dangling_figure_refs.toLocaleString()}</div>
      <div class="summary-label">Dangling Refs</div>
    </div>
    <div class="summary-card ${(registry.summary.broken_prereqs + registry.summary.broken_registry_sources + registry.summary.path_escapes_repo) ? 'has-issues' : 'is-clean'}">
      <div class="summary-value">${(registry.summary.broken_prereqs + registry.summary.broken_registry_sources + registry.summary.path_escapes_repo).toLocaleString()}</div>
      <div class="summary-label">Other Integrity Issues</div>
    </div>
  </div>

  <div style="font-size: 12px; color: ${colors.gray}; margin: -18px 0 20px 0;">
    Generated ${registry.generated_at} by <code>${registry.generator}</code> &middot;
    ${registry.summary.total_kc.toLocaleString()} knowledge checks &middot;
    ${registry.summary.total_quiz.toLocaleString()} quizzes &middot;
    ${registry.summary.total_interactive.toLocaleString()} interactives
  </div>
` : ''}`

renderIssueList = (items, formatter, emptyLabel) => items.length
  ? items.slice(0, 100).map(formatter).map(s => `<div>${s}</div>`).join('') +
    (items.length > 100 ? `<div style="opacity:.7">&hellip; ${items.length - 100} more (see docs-internal/reports/content-registry-check.tsv)</div>` : '')
  : `<div style="opacity:.7">${emptyLabel}</div>`

html`${currentUser?.isAdmin && registry ? `
  <div class="integrity-panel">
    <div class="integrity-card ${registry.integrity.dangling_figure_refs.length ? 'dirty' : 'clean'}">
      <h4>Dangling Figure References <span class="integrity-count">${registry.integrity.dangling_figure_refs.length}</span></h4>
      <div style="font-size:12px; color:${colors.gray};">Chapter references a figure file that does not exist -- the live-404 bug class.</div>
      <div class="integrity-list">${renderIssueList(
        registry.integrity.dangling_figure_refs,
        d => `${d.chapter}:${d.line} &rarr; ${d.src}`,
        'None found.'
      )}</div>
    </div>

    <div class="integrity-card ${registry.integrity.path_escapes_repo.length ? 'dirty' : 'clean'}">
      <h4>Figure Paths Escaping the Repo <span class="integrity-count">${registry.integrity.path_escapes_repo.length}</span></h4>
      <div style="font-size:12px; color:${colors.gray};">A relative figure path resolves outside the repository root.</div>
      <div class="integrity-list">${renderIssueList(
        registry.integrity.path_escapes_repo,
        d => `${d.chapter}:${d.line} &rarr; ${d.src}`,
        'None found.'
      )}</div>
    </div>

    <div class="integrity-card ${registry.integrity.broken_prereqs.length ? 'dirty' : 'clean'}">
      <h4>Unit Prereqs Naming a Non-Chapter <span class="integrity-count">${registry.integrity.broken_prereqs.length}</span></h4>
      <div style="font-size:12px; color:${colors.gray};">Prereq resolves to a redirect stub or nothing -- a stale prerequisite graph.</div>
      <div class="integrity-list">${renderIssueList(
        registry.integrity.broken_prereqs,
        d => `${d.chapter} &rarr; '${d.prereq}'`,
        'None found.'
      )}</div>
    </div>

    <div class="integrity-card ${registry.integrity.broken_registry_sources.length ? 'dirty' : 'clean'}">
      <h4>assets/data/*.json With a Missing Source <span class="integrity-count">${registry.integrity.broken_registry_sources.length}</span></h4>
      <div style="font-size:12px; color:${colors.gray};">A registry's declared generation-source file no longer exists.</div>
      <div class="integrity-list">${renderIssueList(
        registry.integrity.broken_registry_sources,
        d => `${d.registry} (${d.field}) &rarr; ${d.declared_source}`,
        'None found.'
      )}</div>
    </div>
  </div>
` : ''}`

// NOTE ON EVENT HANDLING: this deliberately builds a real DOM node and
// wires real addEventListener calls rather than inline on-star HTML
// attributes. htl's `html` tag only wires an interpolated FUNCTION value up
// as a real listener when that function is interpolated directly at the
// tag's own top level; here the markup is composed as an ordinary (nested)
// template string first, so by the time it reaches `html` any interpolated
// function has already been coerced to its source-code TEXT via
// .toString() -- inert as an attribute value, never invoked. Delegated
// listeners on a stable container sidestep that entirely and are the
// standard, reliable pattern for a dynamic list of controls like this.
filterBarNode = {
  if (!(currentUser?.isAdmin && registry)) return html`<div></div>`;

  // Preserve focus/cursor across the re-render this cell does on every
  // keystroke in the search box (it re-runs whenever `viewState` mutates,
  // including `.search`, since OJS mutable-cell reactivity is whole-object,
  // not per-property) -- without this, typing a second character would
  // find the input already replaced and focus lost.
  const prevActive = document.activeElement;
  const wasSearchFocused = Boolean(prevActive && prevActive.matches && prevActive.matches('[data-action="search"]'));
  const prevSelStart = wasSearchFocused ? prevActive.selectionStart : null;
  const prevSelEnd = wasSearchFocused ? prevActive.selectionEnd : null;

  const container = html`<div class="filter-bar"></div>`;
  container.innerHTML = `
    <div class="tab-row">
      <button class="tab-btn ${viewState.tab === 'chapters' ? 'active' : ''}" data-action="tab" data-value="chapters">
        📖 Chapters (${chaptersArr.length})
      </button>
      <button class="tab-btn ${viewState.tab === 'figures' ? 'active' : ''}" data-action="tab" data-value="figures">
        🖼️ Figures (${figuresArr.length})
      </button>
    </div>

    <input
      type="text"
      class="filter-input"
      data-action="search"
      placeholder="${viewState.tab === 'chapters' ? 'Search chapter path or title...' : 'Search figure path...'}"
      value="${viewState.search}"
    />

    <select class="filter-select" data-action="module">
      <option value="all" ${viewState.module === 'all' ? 'selected' : ''}>All Modules</option>
      ${moduleOptions.map(m => `<option value="${m}" ${viewState.module === m ? 'selected' : ''}>${m}</option>`).join('')}
    </select>

    ${viewState.tab === 'figures' ? `
      <select class="filter-select" data-action="figureFilter">
        <option value="all" ${viewState.figureFilter === 'all' ? 'selected' : ''}>All Figures</option>
        <option value="orphan" ${viewState.figureFilter === 'orphan' ? 'selected' : ''}>Orphans Only</option>
        <option value="gate-flagged" ${viewState.figureFilter === 'gate-flagged' ? 'selected' : ''}>Gate-Flagged Only</option>
      </select>
    ` : ''}
  `;

  container.addEventListener('click', (event) => {
    const btn = event.target.closest('[data-action="tab"]');
    if (!btn) return;
    mutable viewState = { ...mutable viewState, tab: btn.dataset.value, sortBy: 'path', sortDir: 'asc' };
  });
  container.addEventListener('input', (event) => {
    if (event.target.matches('[data-action="search"]')) {
      mutable viewState = { ...mutable viewState, search: event.target.value };
    }
  });
  container.addEventListener('change', (event) => {
    if (event.target.matches('[data-action="module"]')) {
      mutable viewState = { ...mutable viewState, module: event.target.value };
    }
    if (event.target.matches('[data-action="figureFilter"]')) {
      mutable viewState = { ...mutable viewState, figureFilter: event.target.value };
    }
  });

  if (wasSearchFocused) {
    requestAnimationFrame(() => {
      const input = container.querySelector('[data-action="search"]');
      if (!input) return;
      input.focus();
      if (prevSelStart != null) input.setSelectionRange(prevSelStart, prevSelEnd);
    });
  }

  return container;
}

MAX_ROWS = 300

// data-sort-key drives a delegated click listener on the table container
// below (see the note on the filter bar cell above for why this can't be
// an inline onclick attribute).
sortHeader = (label, key) => `
  <th class="${viewState.sortBy === key ? 'active-sort' : ''}" data-sort-key="${key}">${label}</th>
`

chapterRow = (c) => `
  <tr>
    <td class="wrap"><div style="font-weight:500;">${c.title || c.path}</div><div style="font-size:11px; color:${colors.gray};">${c.path}</div></td>
    <td>${c.module}</td>
    <td>${c.difficulty || '&mdash;'}</td>
    <td>${c.has_unit ? `<span class="pill pill-count">${c.est_minutes ?? '?'} min</span>` : `<span class="pill pill-zero">no unit</span>`}</td>
    <td>${c.word_count.toLocaleString()}</td>
    <td>${c.kc_count}</td>
    <td>${c.quiz_count}</td>
    <td>${c.figure_count}</td>
    <td>${c.interactive_count}</td>
    <td>${c.created || '&mdash;'}</td>
    <td>${c.updated || '&mdash;'}</td>
    <td>${c.commits}</td>
    <td>${c.last_author || '&mdash;'}</td>
    <td>${gateFindingCount(c) ? `<span class="pill pill-gate">${gateFindingCount(c)}</span>` : `<span class="pill pill-zero">0</span>`}</td>
  </tr>
`

figureRow = (f) => `
  <tr>
    <td class="wrap">${f.path}</td>
    <td>${f.scope}</td>
    <td>${(f.bytes / 1024).toFixed(1)} KB</td>
    <td>${f.width && f.height ? `${Math.round(f.width)}&times;${Math.round(f.height)}` : '&mdash;'}</td>
    <td>${f.created || '&mdash;'}</td>
    <td>${f.updated || '&mdash;'}</td>
    <td>${f.commits}</td>
    <td>${f.last_author || '&mdash;'}</td>
    <td>${f.referenced_by.length}</td>
    <td>${f.orphan ? `<span class="pill pill-orphan">orphan</span>` : `<span class="pill pill-count">used</span>`}</td>
    <td>${gateFindingCount(f) ? `<span class="pill pill-gate">${gateFindingCount(f)}</span>` : `<span class="pill pill-zero">0</span>`}</td>
  </tr>
`

tableNode = {
  if (!(currentUser?.isAdmin && registry)) return html`<div></div>`;

  const container = html`<div></div>`;
  const isChapters = viewState.tab === 'chapters';
  const colspan = isChapters ? 14 : 11;
  const rows = isChapters ? filteredChapters : filteredFigures;
  const noun = isChapters ? 'chapters' : 'figures';
  const headHtml = isChapters ? `
          ${sortHeader('Chapter', 'path')}
          ${sortHeader('Module', 'module')}
          ${sortHeader('Difficulty', 'difficulty')}
          ${sortHeader('Unit', 'est_minutes')}
          ${sortHeader('Words', 'word_count')}
          ${sortHeader('KCs', 'kc_count')}
          ${sortHeader('Quizzes', 'quiz_count')}
          ${sortHeader('Figures', 'figure_count')}
          ${sortHeader('Interactives', 'interactive_count')}
          ${sortHeader('Created', 'created')}
          ${sortHeader('Updated', 'updated')}
          ${sortHeader('Commits', 'commits')}
          ${sortHeader('Last Author', 'last_author')}
          <th>Gate Findings</th>
  ` : `
          ${sortHeader('Figure', 'path')}
          ${sortHeader('Scope', 'scope')}
          ${sortHeader('Size', 'bytes')}
          <th>Dimensions</th>
          ${sortHeader('Created', 'created')}
          ${sortHeader('Updated', 'updated')}
          ${sortHeader('Commits', 'commits')}
          ${sortHeader('Last Author', 'last_author')}
          <th>Referenced By</th>
          <th>Status</th>
          <th>Gate Findings</th>
  `;
  const bodyHtml = rows.length === 0
    ? `<tr><td colspan="${colspan}" style="text-align:center; padding:40px; color:${colors.gray};">No ${noun} match the current filter.</td></tr>`
    : rows.slice(0, MAX_ROWS).map(isChapters ? chapterRow : figureRow).join('');

  container.innerHTML = `
    <div class="scroll-hint" aria-hidden="true">Scroll right to see all columns &rarr;</div>
    <div class="table-wrap iot-no-stack-table">
      <table class="registry-table">
        <thead><tr>${headHtml}</tr></thead>
        <tbody>${bodyHtml}</tbody>
      </table>
    </div>
    <div class="results-note">
      Showing ${Math.min(rows.length, MAX_ROWS).toLocaleString()} of ${rows.length.toLocaleString()} ${noun}
      ${rows.length > MAX_ROWS ? ' &mdash; refine search/module filter to narrow further' : ''}
    </div>
  `;

  container.addEventListener('click', (event) => {
    const th = event.target.closest('[data-sort-key]');
    if (!th) return;
    const key = th.dataset.sortKey;
    const nextDir = (viewState.sortBy === key && viewState.sortDir === 'asc') ? 'desc' : 'asc';
    mutable viewState = { ...mutable viewState, sortBy: key, sortDir: nextDir };
  });

  return container;
}

About This Registry

What is (and isn’t) in this registry

Derived, and shown: chapter/unit frontmatter (title, difficulty, est_minutes, prereqs), word counts, per-chapter counts of knowledge checks (<iot-knowledge-check>), quizzes (<iot-matching/ordering/label/code-quiz>) and interactives (<iot-embed>/<iot-simulator>), figure dimensions/bytes, and for every chapter and figure: created date, last-updated date, commit count, and last author, all read from a single git log --name-only pass over content/ and images/ history.

Deliberately NOT included: anything that would require a human to keep a fact updated by hand. There is no “status” or “priority” field anyone has to set – see docs-internal/ops/content-registry.md for the full list of scope decisions (why renamed files show a fresh “created” date, why pages outside content/<module>/*.qmd aren’t scanned for figure references, and which existing CI gates could not be attached because their reports aren’t keyed to a source path).

Regenerate with python3 scripts/generate-content-registry.py; runs automatically in scripts/post-render.sh and is checked in scripts/ci-quality-gates.sh.