app/kb/admin.mjs

Functions

Imports

It imports app/kb/bases.mjs, app/kb/gap-labels.mjs, app/kb/registry/catalog.mjs, app/kb/registry/compile.mjs, app/kb/registry/kinds.mjs, app/lib/cv/view.mjs. Imported by app/kb/editor.server.ts, app/routes/admin.kb.tsx.

Source

1// The admin's Knowledge Base page (docs/KNOWLEDGE-BASE.md, step 2), the part that needs no runtime: its tabs and their
2// counts, the search over a base's entries, and the Needs info list, every recorded gap of every entry and registry item
3// on one screen. Pure, so node:test holds it; the route passes in the rows it read from D1. Read-only: nothing here writes.
4
5import { foldText } from "../lib/cv/view.mjs";
6import { BASES } from "./bases.mjs";
7import { labelGaps } from "./gap-labels.mjs";
8import { hasItemPage, itemPath, kindPath } from "./registry/catalog.mjs";
9import { isGap } from "./registry/compile.mjs";
10import { KINDS } from "./registry/kinds.mjs";
11
12export const KB_ADMIN_PATH = "/admin/kb";
13
14/** Where an entry's file is edited (step 3). @param {string} slug */
15export const entryEditHref = (slug) => `${KB_ADMIN_PATH}/entry/${slug}`;
16
17/** Where a registry item's file is edited (step 3). @param {string} kind @param {string} id */
18const itemEditHref = (kind, id) => `${KB_ADMIN_PATH}/item/${kind}/${id}`;
19
20/** The tab that lists every gap, beside one tab per base. */
21export const NEEDS_INFO = "needs-info";
22
23/**
24 * @typedef {{
25 *   slug: string,
26 *   path: string,
27 *   profile: string,
28 *   title: string,
29 *   description: string,
30 *   draft: boolean,
31 *   version: string | null,
32 *   updated: string | null,
33 *   gaps: Array<{ field: string, reason: string, where?: string[], section?: string }>,
34 * }} KbEntry
35 *
36 * @typedef {{ kind: string, id: string, name: string, status: string, fields: Record<string, unknown> }} KbItem
37 *
38 * @typedef {{ what: string, kindLabel: string, href: string, editHref: string, field: string, label: string, reason: string }} KbGap
39 */
40
41/** The tab a `?tab=` value names, else the first base. @param {string | null} value */
42export function resolveTab(value) {
43  if (value === NEEDS_INFO || BASES.some((base) => base.id === value)) return /** @type {string} */ (value);
44  return /** @type {string} */ (BASES[0]?.id);
45}
46
47/** A tab's address, keeping the search only where it still applies (a base's list). @param {string} tab @param {string} [q] */
48export function tabHref(tab, q = "") {
49  const params = new URLSearchParams({ tab });
50  if (q && tab !== NEEDS_INFO) params.set("q", q);
51  return `${KB_ADMIN_PATH}?${params}`;
52}
53
54/**
55 * Every tab with its count, read from the same rows the lists are drawn from: one per base, then Needs info.
56 *
57 * @param {KbEntry[]} entries
58 * @param {KbGap[]} gaps
59 */
60export function kbTabs(entries, gaps) {
61  return [
62    ...BASES.map((base) => ({ id: base.id, label: base.name, count: entries.filter((e) => e.profile === base.profile).length })),
63    { id: NEEDS_INFO, label: "Needs info", count: gaps.length },
64  ];
65}
66
67/**
68 * A base's entries, narrowed by a search over the title, description and slug (case and accents folded), in title order.
69 *
70 * @param {KbEntry[]} entries
71 * @param {string} tab
72 * @param {string} [q]
73 */
74export function baseEntries(entries, tab, q = "") {
75  const base = BASES.find((b) => b.id === tab);
76  if (!base) return [];
77  const needle = foldText(q);
78  return entries
79    .filter((e) => e.profile === base.profile)
80    .filter((e) => needle === "" || foldText(`${e.title} ${e.description} ${e.slug}`).includes(needle))
81    .sort((a, b) => foldText(a.title).localeCompare(foldText(b.title), "en", { numeric: true }));
82}
83
84/** Where an item is read: its own page, or its kind's table where the kind has no item pages. @param {KbItem} item */
85function itemHref(item) {
86  return hasItemPage(item.kind) ? itemPath(item.kind, item.id) : kindPath(item.kind);
87}
88
89/**
90 * Every recorded gap (`MISSING: <why>`), entries first in title order, then registry items in the registry's order, each
91 * with the field and the reason as written.
92 *
93 * @param {KbEntry[]} entries
94 * @param {KbItem[]} items
95 * @returns {KbGap[]}
96 */
97export function needsInfo(entries, items) {
98  const profileName = Object.fromEntries(BASES.map((base) => [base.profile, base.singular]));
99  const fromEntries = [...entries]
100    .sort((a, b) => foldText(a.title).localeCompare(foldText(b.title), "en", { numeric: true }))
101    .flatMap((e) =>
102      labelGaps(e.gaps, e.profile).map((gap) => ({
103        what: e.title,
104        kindLabel: profileName[e.profile] ?? e.profile,
105        href: e.path,
106        editHref: `${entryEditHref(e.slug)}#${gap.anchor}`,
107        field: gap.field,
108        label: gap.label,
109        reason: gap.reason,
110      })),
111    );
112  const fromItems = items.flatMap((item) =>
113    labelGaps(
114      Object.entries(item.fields)
115        .filter(([, value]) => isGap(value))
116        .map(([field, value]) => ({ field, reason: String(value).replace(/^MISSING:\s*/, "") })),
117      null,
118    ).map((gap) => ({
119      what: item.name,
120      kindLabel: capitalise(KINDS[item.kind]?.singular ?? item.kind),
121      href: itemHref(item),
122      editHref: `${itemEditHref(item.kind, item.id)}#${gap.anchor}`,
123      field: gap.field,
124      label: gap.label,
125      reason: gap.reason,
126    })),
127  );
128  return [...fromEntries, ...fromItems];
129}
130
131/** @param {string} word */
132function capitalise(word) {
133  return word.charAt(0).toUpperCase() + word.slice(1);
134}