@forwardimpact/libwiki 0.3.0 → 0.3.1

package/src/sanitize.js

@@ -3,9 +3,10 @@ const ELLIPSIS = "…";
 const ZERO_WIDTH_SPACE = "\u200b";
 
 // Replace every newline, control character, or whitespace code point with a
-// single space, then collapse runs. Done by code-point inspection rather than a
-// character-class range so no literal hyphen is ever folded into a range and
-// hyphenated identifiers ("staff-engineer", "dick-olsson") survive intact.
+// single space. Then collapse runs. This function inspects each code point and
+// does not use a character-class range. So it never folds a literal hyphen
+// into a range, and hyphenated identifiers ("staff-engineer", "dick-olsson")
+// survive intact.
 function flattenWhitespace(input) {
   let out = "";
   for (const ch of input) {
@@ -19,11 +20,11 @@ function flattenWhitespace(input) {
 
 /**
  * Neutralize an anyone-editable issue-tracker field before it crosses into a
- * boot-readable wiki surface. Flattens newlines / control characters /
- * whitespace to single spaces (a multi-line value is what would let a field
- * inject a heading or block marker and move section boundaries), escapes a
- * leading protocol sigil ("[" or "<") so "[ask#N]" / "<tag>" / HTML-comment
- * lookalikes render inert, and length-caps the result.
+ * boot-readable wiki surface. Flattens newlines, control characters, and
+ * whitespace to single spaces. A multi-line value would let a field inject a
+ * heading or block marker and move section boundaries. Escapes a leading
+ * protocol sigil ("[" or "<") so "[ask#N]", "<tag>", and HTML-comment
+ * lookalikes render inert. Length-caps the result.
  * @param {string|null|undefined} value
  * @param {number} [maxLen]
  * @returns {string}
@@ -38,9 +39,9 @@ export function sanitizeCrossingField(value, maxLen = FIELD_CAP) {
 
 /**
  * Sanitize a materialized item title. Beyond {@link sanitizeCrossingField}, it
- * defuses the literal author-suffix token " (by " by inserting a zero-width
- * space after "(by", so a title can never be mistaken for the trailing
- * "(by <author>)" provenance suffix when the line is parsed back at boot.
+ * defuses the literal author-suffix token " (by ". It inserts a zero-width
+ * space after "(by". A title then never looks like the trailing
+ * "(by <author>)" provenance suffix when the boot parse reads the line back.
  * @param {string|null|undefined} value
  * @param {number} [maxLen]
  * @returns {string}

package/src/secret-gate.js

@@ -1,32 +1,33 @@
 /**
- * Fail-closed secret gate for the wiki push path. Runs gitleaks over the
- * commit range a push introduces and reports a clean / finding /
- * scanner-absent verdict. The wiki has no destination-side secret control (a
- * GitHub Wiki repo runs no Actions and is excluded from GitHub
- * secret-scanning), so this is the only place a content backstop can live.
+ * Fail-closed secret gate for the wiki push path. The gate runs gitleaks over
+ * the commit range a push introduces. It reports a clean, finding, or
+ * scanner-absent verdict. The wiki has no destination-side secret control. A
+ * GitHub Wiki repo runs no Actions, and GitHub secret-scanning excludes it. So
+ * this is the only place a content backstop can live.
  *
- * The module never throws on a scanner result: a missing or erroring scanner
- * resolves to `scanner-absent` so the caller fails closed rather than treating
- * an error as clean. Findings carry only a location (`file:line:rule`) — never
- * the matched secret value, so an audit record built from them cannot itself
- * leak.
+ * The module never throws on a scanner result. A missing scanner resolves to
+ * `scanner-absent`. A scanner that errors resolves the same way. The caller
+ * then fails closed and never reports an error as clean. Findings carry only a
+ * location (`file:line:rule`). They never carry the matched secret value, so an
+ * audit record built from them cannot itself leak.
  */
 
 import { isoTimestamp } from "@forwardimpact/libutil";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
-/** The gitleaks binary name resolved on PATH; provisioning is an operator concern (see wiki-operations guide). */
+/** The gitleaks binary name resolved on PATH. An operator provisions it (see the wiki-operations guide). */
 const GITLEAKS = "gitleaks";
 
 /**
- * Scan the commit range a push introduces for secrets, fail closed.
+ * Scan the commit range a push introduces for secrets. Fail closed.
  *
- * Probes `gitleaks version` first; an unresolvable binary short-circuits to
- * `scanner-absent`. Then runs `gitleaks detect` over `range` expressed as
- * `git log` options, reading the JSON report from stdout. Exit codes follow
- * gitleaks' documented contract: `0` clean, `1` leaks found, any other
- * non-zero an invocation error (treated as `scanner-absent` — fail closed, an
- * error is never reported as clean).
+ * The scan probes `gitleaks version` first. An unresolvable binary
+ * short-circuits to `scanner-absent`. The scan then runs `gitleaks detect` over
+ * `range` expressed as `git log` options, and reads the JSON report from
+ * stdout. Exit codes follow gitleaks' documented contract: `0` clean, `1` leaks
+ * found, any other non-zero an invocation error. The scan treats an invocation
+ * error as `scanner-absent` and fails closed. It never reports an error as
+ * clean.
  *
  * @param {object} args
  * @param {import('@forwardimpact/libutil/runtime').Runtime} args.runtime - Provides `subprocess.run`.
@@ -60,16 +61,16 @@ export async function scanPushWindow({ runtime, wikiDir, range }) {
   if (scan.exitCode === 1) {
     return { status: "finding", findings: parseFindings(scan.stdout) };
   }
-  // Any other non-zero is an invocation/usage error, not a leak verdict:
-  // fail closed rather than risk reporting a broken scan as clean.
+  // Any other non-zero is an invocation or usage error. It is not a leak
+  // verdict. Fail closed. Do not report a broken scan as clean.
   return { status: "scanner-absent" };
 }
 
 /**
- * Parse a gitleaks JSON report into location-only findings. Reads only the
- * file, line, and rule of each entry — never the matched secret value — so a
- * record built from the result is secret-free by construction. A malformed or
- * empty report yields an empty list.
+ * Parse a gitleaks JSON report into location-only findings. The parser reads
+ * only the file, line, and rule of each entry. It never reads the matched
+ * secret value, so a record built from the result is secret-free by
+ * construction. A malformed or empty report yields an empty list.
  *
  * @param {string} stdout - The gitleaks JSON report.
  * @returns {Array<{file: string, line: number, rule: string}>}
@@ -93,10 +94,10 @@ function parseFindings(stdout) {
  * Append one secret-free line to the wiki tree's `secret-overrides.log` and
  * stage it (path-scoped) so it lands in the same push as the overridden
  * content. The line records the override as a durable, inspectable audit
- * trail: an ISO timestamp, the asserted operator identity (`git config
- * user.email` — attribution of intent, NOT an authenticated identity), the
- * override class, the reason, and for a finding its location. It never carries
- * a matched secret value.
+ * trail. It holds an ISO timestamp, the asserted operator identity (`git
+ * config user.email`), the override class, the reason, and for a finding its
+ * location. That identity asserts intent. It is NOT an authenticated identity.
+ * The line never carries a matched secret value.
  *
  * @param {object} args
  * @param {import('@forwardimpact/libutil/runtime').Runtime} args.runtime - Provides `fs` and `clock`.
@@ -123,8 +124,8 @@ export async function appendOverrideRecord({
         "unspecified"
       : "scanner-absent";
   const ts = isoTimestamp(runtime.clock.now());
-  // Tab-separated, single line; the reason is collapsed so the record stays
-  // one inspectable row per override.
+  // Tab-separated, single line. The replace call collapses the reason so the
+  // record stays one inspectable row per override.
   const line = `${ts}\t${email}\t${klass}\t${reason.replace(/\s+/g, " ").trim()}\t${where}\n`;
   const logPath = `${wikiDir}/${OVERRIDE_LOG}`;
   await runtime.fs.appendFile(logPath, line);
@@ -140,12 +141,12 @@ export async function appendOverrideRecord({
 export const OVERRIDE_LOG = "secret-overrides.log";
 
 /**
- * Translate a `commitAndPush` security refusal into a command envelope,
- * logging the cause and its break-glass procedure at error level (always
- * surfaced, regardless of LOG_LEVEL). Returns `null` for any non-refusal
- * result (clean / pushed / network "saved locally"), so a caller can fall
- * through to its normal success handling. Shared by every command surface so
- * the refusal message and exit code live in one place.
+ * Translate a `commitAndPush` security refusal into a command envelope. Log the
+ * cause and its break-glass procedure at error level. The logger always
+ * surfaces them, regardless of LOG_LEVEL. Returns `null` for any
+ * non-refusal result (clean, pushed, or network "saved locally"), so a caller
+ * can fall through to its normal success path. Every command surface shares
+ * this function, so the refusal message and exit code live in one place.
  *
  * @param {object} runtime - The runtime bag (the logger writes to `proc.stderr`).
  * @param {{reason?: string, findings?: Array<{file: string, line: number, rule: string}>}} result - A `commitAndPush` result.
@@ -158,8 +159,8 @@ export function refusalEnvelope(runtime, result) {
       .join(", ");
     createLogger("wiki", runtime).error(
       "push",
-      `push blocked: secret detected in wiki content${where ? ` (${where})` : ""}; ` +
-        "the push was not attempted. After confirming a false positive, set " +
+      `push blocked: secret detected in wiki content${where ? ` (${where})` : ""}. ` +
+        "The push did not run. Confirm a false positive first. Then set " +
         "FIT_WIKI_SECRET_OVERRIDE to a reason to override (audited).",
     );
     return { ok: false, code: 1 };
@@ -167,8 +168,8 @@ export function refusalEnvelope(runtime, result) {
   if (result.reason === "scanner-unavailable") {
     createLogger("wiki", runtime).error(
       "push",
-      "push blocked: the secret scanner (gitleaks) is unavailable; the push " +
-        "was not attempted. Install gitleaks, or set FIT_WIKI_SCANNER_ABSENT_OK " +
+      "push blocked: the secret scanner (gitleaks) is unavailable. The push " +
+        "did not run. Install gitleaks, or set FIT_WIKI_SCANNER_ABSENT_OK " +
         "to a reason to override (audited).",
     );
     return { ok: false, code: 1 };

package/src/status.js

@@ -1,20 +1,21 @@
 // STATUS.md rows come in two kinds. A spec row's id is four digits with an
-// optional `/<unit>` suffix denoting a per-migration-unit sub-row of a master
-// spec (`1370/libutil`, …); the master `NNNN` row advances only when every
-// sub-row reads `plan implemented`. An experiment row's id is `exp:<issue>`
-// and the row carries four tab cells — `exp:<issue><TAB><state><TAB><pin>
-// <TAB><plan-ref>` — keying the merge-gate approval path for a spec-less
-// experiment PR. The `exp:` namespace cannot match the spec id's `^\d{4}`
-// anchor, so the two kinds never collide for any issue-number width.
+// optional `/<unit>` suffix. The suffix denotes a per-migration-unit sub-row
+// of a master spec (`1370/libutil`, …). The master `NNNN` row advances only
+// when every sub-row reads `plan implemented`. An experiment row's id is
+// `exp:<issue>`. That row carries four tab cells:
+// `exp:<issue><TAB><state><TAB><pin><TAB><plan-ref>`. The cells key the
+// merge-gate approval path for a spec-less experiment PR. The `exp:` namespace
+// cannot match the spec id's `^\d{4}` anchor, so the two kinds never collide
+// for any issue-number width.
 
 /** Matches a status-row id: a four-digit spec id (optional `/<unit>`) or `exp:<issue>`. */
 export const STATUS_ID_REGEX = /^(\d{4}(\/[a-z0-9-]+)?|exp:\d+)$/;
 
 /**
- * Classify a status-row id into its kind and parts. Experiment rows are
- * identified by an `exp:` id together with a four-cell row; the optional
- * `cells` array supplies that count (a bare `exp:` id without four cells is
- * not a valid row and yields null).
+ * Classify a status-row id into its kind and parts. An `exp:` id together with
+ * a four-cell row identifies an experiment row. The optional `cells` array
+ * supplies that count. A bare `exp:` id without four cells is not a valid row
+ * and yields null.
  * @param {string} id - The id field (cell 0) of a STATUS.md row.
  * @param {string[]} [cells] - The full tab-separated cells of the row, when
  *   available. Required to classify an experiment row.

package/src/storyboard-skeleton.js

@@ -1,16 +1,17 @@
 /**
- * Storyboard skeleton — the minimal, valid storyboard file `gemba-wiki refresh`
- * writes when the current-month board does not yet exist. It carries only the
- * structural surface libwiki owns: the five Toyota Kata sections and the
- * generic `obstacles`/`experiments` issue-list marker blocks that refresh
- * renders from tracker state.
+ * The storyboard skeleton is the minimal, valid storyboard file that
+ * `gemba-wiki refresh` writes when the current-month board does not yet exist.
+ * It carries only the structural surface libwiki owns: the five Toyota Kata
+ * sections and the generic `obstacles`/`experiments` issue-list marker blocks.
+ * Refresh renders those blocks from tracker state.
  *
- * Deliberately *not* here: the per-agent `#### {metric}` XmR blocks. Their
- * agent→metric grouping is per-installation curation libwiki cannot infer, so a
- * participant seeds each missing marker pair (see the kata-session skill) and a
- * later refresh renders it. Section budgets and authoring prose ("write the
- * challenge here") stay in the skill's `storyboard-template.md`, the L4
- * authoring layer — this skeleton is content-free scaffolding.
+ * This skeleton deliberately omits the per-agent `#### {metric}` XmR blocks.
+ * Each installation curates which metric belongs to which agent, so libwiki
+ * cannot infer the pairs. A participant seeds each missing marker pair (see the
+ * kata-session skill). A later refresh renders it. Section budgets and prose
+ * for authors ("write the challenge here") stay in the skill's
+ * `storyboard-template.md`, the L4 authoring layer. The skeleton itself carries
+ * no content.
  */
 
 const MONTH_NAMES = [
@@ -36,9 +37,9 @@ function isLeapYear(year) {
 }
 
 /**
- * Last calendar day of the month containing `todayIso` (ISO `YYYY-MM-DD`).
- * Pure integer/calendar math — no `Date`, so the module stays free of ambient
- * time deps.
+ * Return the last calendar day of the month that holds `todayIso` (ISO
+ * `YYYY-MM-DD`). The function uses pure integer and calendar math. It uses no
+ * `Date`, so the module stays free of ambient time deps.
  */
 function endOfMonthIso(todayIso) {
   const [year, month] = todayIso.split("-").map(Number);
@@ -48,10 +49,11 @@ function endOfMonthIso(todayIso) {
 }
 
 /**
- * Render the minimal storyboard skeleton for the month containing `todayIso`.
- * Pure — takes the day as an ISO string and returns markdown. The heading reads
- * `# Storyboard — {YYYY} {Month}`; the marker blocks match the syntax the
- * scanner (`marker-scanner.js`) and renderer (`commands/refresh.js`) expect.
+ * Render the minimal storyboard skeleton for the month that holds `todayIso`.
+ * The function is pure. It takes the day as an ISO string and returns
+ * markdown. The heading reads `# Storyboard — {YYYY} {Month}`. The marker
+ * blocks match the syntax the scanner (`marker-scanner.js`) and renderer
+ * (`commands/refresh.js`) expect.
  *
  * @param {string} todayIso - ISO date string (`YYYY-MM-DD`).
  * @returns {string} The skeleton markdown, newline-terminated.

package/src/util/agent-flag.js

@@ -1,16 +1,16 @@
 /**
- * Resolve the required agent flag from frozen CLI options. Pure — reads no
- * filesystem and no environment, so it runs before any state change. Returns
- * `{ ok: true, agent }` when the flag is present, or
- * `{ ok: false, code: 2, error }` when it is missing, where `error` names the
- * missing flag and shows a corrected example invocation. The error never
- * mentions an environment variable: `libwiki` carries no ambient agent
+ * Resolve the required agent flag from frozen CLI options. The function is
+ * pure. It reads no filesystem and no environment, so it runs before any state
+ * change. It returns `{ ok: true, agent }` when the flag is present. It returns
+ * `{ ok: false, code: 2, error }` when the flag is missing. The `error` names
+ * the missing flag and shows a corrected example invocation. The error never
+ * mentions an environment variable. `libwiki` carries no ambient agent
  * identity, so there is no fallback to offer.
  *
  * @param {Record<string, unknown>} options - The frozen `ctx.options`.
  * @param {{ command: string, flag?: string, example: string }} spec
- *   `command` names the failing subcommand; `flag` is the option key prefix
- *   (`--agent` by default, `--from` for `memo`); `example` is a correct
+ *   `command` names the subcommand that failed. `flag` is the option key prefix
+ *   (`--agent` by default, `--from` for `memo`). `example` is a correct
  *   invocation shown verbatim in the error.
  * @returns {{ ok: true, agent: string } | { ok: false, code: 2, error: string }}
  */

package/src/util/clock.js

@@ -1,7 +1,7 @@
 import { isoDate } from "@forwardimpact/libutil";
 
 /**
- * Today's ISO calendar date (`YYYY-MM-DD`) read from the injected clock.
+ * Return today's ISO calendar date (`YYYY-MM-DD`) from the injected clock.
  * Commands that previously inlined `new Date().toISOString().slice(0, 10)` (or
  * libwiki's `io.today()`) call this instead so the wall-clock read flows
  * through `runtime.clock`.

package/src/util/wiki-dir.js

@@ -1,9 +1,9 @@
 import path from "node:path";
 
 /**
- * Find the project root by upward `package.json` discovery from the current
- * working directory, using the injected `runtime.finder` (the one canonical
- * Finder, constructed only inside libutil).
+ * Find the project root. The search looks upward for a `package.json` from the
+ * current working directory. It uses the injected `runtime.finder` (the one
+ * canonical Finder, which libutil alone constructs).
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @returns {string}
  */
@@ -12,9 +12,9 @@ export function resolveProjectRoot(runtime) {
 }
 
 /**
- * Resolve the wiki root, preserving the pre-1370 order: the `--wiki-root`
- * option when given, else `<projectRoot>/wiki`. The finder is consulted only
- * when no explicit `--wiki-root` is supplied.
+ * Resolve the wiki root and keep the pre-1370 order: the `--wiki-root` option
+ * when the caller gives one, else `<projectRoot>/wiki`. The function consults
+ * the finder only when the caller supplies no explicit `--wiki-root`.
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @param {Record<string, unknown>} [options] - Parsed CLI options (`ctx.options`).
  * @returns {string}
@@ -26,7 +26,7 @@ export function resolveWikiRoot(runtime, options = {}) {
 /**
  * Report whether the resolved wiki root exists on disk. Commands that read or
  * sync an existing wiki use this to degrade gracefully (warn and exit 0) when
- * the tree was never bootstrapped — e.g. a fresh worktree where
+ * nobody bootstrapped the tree. One example is a fresh worktree where
  * `scripts/bootstrap.sh` did not run.
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @param {string} wikiDir - The resolved wiki root.