@forwardimpact/libwiki 0.1.3 → 0.2.0

package/src/marker-scanner.js

@@ -1,43 +1,90 @@
-const OPEN_RE = /^<!--\s*xmr:([^:\s]+):([^\s]+)\s*-->\s*$/;
-const CLOSE_RE = /^<!--\s*\/xmr\s*-->\s*$/;
+const XMR_OPEN_RE = /^<!--\s*xmr:([^:\s]+):([^\s]+)\s*-->\s*$/;
+const ISSUE_OPEN_RE =
+  /^<!--\s*(obstacles|experiments):(open|closed)(?::(\d+d))?\s*-->\s*$/;
+const XMR_CLOSE_RE = /^<!--\s*\/xmr\s*-->\s*$/;
+const ISSUE_CLOSE_RE = /^<!--\s*\/(obstacles|experiments)\s*-->\s*$/;
 
-/** Scan text for paired xmr open/close HTML comment markers and return their line positions and metadata. */
+function openLabel(open) {
+  return open.kind === "xmr" ? open.metric : open.topic;
+}
+
+function warnDangling(open) {
+  process.stderr.write(
+    `dangling-marker ${openLabel(open)} at line ${open.openLine + 1}\n`,
+  );
+}
+
+function tryOpen(line, i) {
+  const xmrMatch = line.match(XMR_OPEN_RE);
+  if (xmrMatch) {
+    return {
+      kind: "xmr",
+      metric: xmrMatch[1],
+      csvPath: xmrMatch[2],
+      openLine: i,
+    };
+  }
+  const issueMatch = line.match(ISSUE_OPEN_RE);
+  if (issueMatch) {
+    return {
+      kind: "issue-list",
+      topic: issueMatch[1],
+      state: issueMatch[2],
+      window: issueMatch[3] || null,
+      openLine: i,
+    };
+  }
+  return null;
+}
+
+function closePair(open, i) {
+  if (open.kind === "xmr") {
+    return {
+      kind: "xmr",
+      metric: open.metric,
+      csvPath: open.csvPath,
+      openLine: open.openLine,
+      closeLine: i,
+    };
+  }
+  return {
+    kind: "issue-list",
+    topic: open.topic,
+    state: open.state,
+    window: open.window,
+    openLine: open.openLine,
+    closeLine: i,
+  };
+}
+
+function matchClose(line, open) {
+  if (!open) return false;
+  if (open.kind === "xmr") return XMR_CLOSE_RE.test(line);
+  const m = line.match(ISSUE_CLOSE_RE);
+  return Boolean(m && open.kind === "issue-list" && open.topic === m[1]);
+}
+
+/** Scan text for paired marker blocks (xmr or issue-list). Returns positions and metadata. */
 export function scanMarkers(text) {
   const lines = text.split("\n");
   const pairs = [];
   let open = null;
 
   for (let i = 0; i < lines.length; i++) {
-    const openMatch = lines[i].match(OPEN_RE);
-    if (openMatch) {
-      if (open) {
-        process.stderr.write(
-          `dangling-marker ${open.metric} at line ${open.openLine + 1}\n`,
-        );
-      }
-      open = { metric: openMatch[1], csvPath: openMatch[2], openLine: i };
+    const line = lines[i];
+    const newOpen = tryOpen(line, i);
+    if (newOpen) {
+      if (open) warnDangling(open);
+      open = newOpen;
       continue;
     }
-
-    if (CLOSE_RE.test(lines[i])) {
-      if (open) {
-        pairs.push({
-          metric: open.metric,
-          csvPath: open.csvPath,
-          openLine: open.openLine,
-          closeLine: i,
-        });
-        open = null;
-      }
-      continue;
+    if (matchClose(line, open)) {
+      pairs.push(closePair(open, i));
+      open = null;
     }
   }
 
-  if (open) {
-    process.stderr.write(
-      `dangling-marker ${open.metric} at line ${open.openLine + 1}\n`,
-    );
-  }
+  if (open) warnDangling(open);
 
   return pairs;
 }

package/src/weekly-log.js

@@ -0,0 +1,91 @@
+import { readFileSync, writeFileSync, existsSync, renameSync } from "node:fs";
+import path from "node:path";
+import { WEEKLY_LOG_LINE_BUDGET } from "./constants.js";
+
+/** Compute ISO 8601 year-week for a Date. Returns { year, week } where year is the ISO week-year (not necessarily the calendar year for edge weeks). */
+export function isoWeek(date) {
+  const d = new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+  );
+  // Thursday of week: ISO weeks are anchored on Thursday.
+  const day = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - day);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((d - yearStart) / 86400000 + 1) / 7);
+  return { year: d.getUTCFullYear(), week };
+}
+
+function formatIsoWeek(date) {
+  const { year, week } = isoWeek(date);
+  return `${year}-W${String(week).padStart(2, "0")}`;
+}
+
+/** Return the path of the current weekly log file for an agent. */
+export function weeklyLogPath(wikiRoot, agent, today) {
+  const date = today instanceof Date ? today : new Date(today);
+  return path.join(wikiRoot, `${agent}-${formatIsoWeek(date)}.md`);
+}
+
+function countLines(text) {
+  if (text.length === 0) return 0;
+  let n = 0;
+  for (const ch of text) if (ch === "\n") n++;
+  if (!text.endsWith("\n")) n++;
+  return n;
+}
+
+function nextPartPath(filePath) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath, ".md");
+  let n = 1;
+  while (existsSync(path.join(dir, `${base}-part${n}.md`))) n++;
+  return path.join(dir, `${base}-part${n}.md`);
+}
+
+function agentTitle(agent) {
+  return agent
+    .split("-")
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join(" ");
+}
+
+function defaultH1(filePath, agent, isoWeekStr) {
+  return `# ${agentTitle(agent)} — ${isoWeekStr}\n`;
+}
+
+/** Rotate the current weekly log if next append would exceed the budget. Returns { rotated, fromPath, toPath }. */
+export function rotateIfOverBudget(
+  wikiRoot,
+  agent,
+  today,
+  appendLines = 0,
+  options = {},
+) {
+  const filePath = weeklyLogPath(wikiRoot, agent, today);
+  const { force = false } = options;
+  if (!existsSync(filePath)) return { rotated: false, fromPath: filePath };
+  const text = readFileSync(filePath, "utf-8");
+  const current = countLines(text);
+  if (!force && current + appendLines <= WEEKLY_LOG_LINE_BUDGET) {
+    return { rotated: false, fromPath: filePath };
+  }
+  const toPath = nextPartPath(filePath);
+  renameSync(filePath, toPath);
+  const date = today instanceof Date ? today : new Date(today);
+  writeFileSync(filePath, defaultH1(filePath, agent, formatIsoWeek(date)));
+  return { rotated: true, fromPath: filePath, toPath };
+}
+
+/** Append a body to a weekly log file. Creates it with an H1 if missing. */
+export function appendEntry(filePath, body, agent, today) {
+  const date = today instanceof Date ? today : new Date(today);
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, defaultH1(filePath, agent, formatIsoWeek(date)));
+  }
+  const text = readFileSync(filePath, "utf-8");
+  const separator = text.endsWith("\n") ? "\n" : "\n\n";
+  writeFileSync(
+    filePath,
+    text + separator + body + (body.endsWith("\n") ? "" : "\n"),
+  );
+}

package/src/wiki-repo.js

@@ -31,11 +31,31 @@ export function buildAuthArgs(args, token) {
 export class WikiRepo {
   #wikiDir;
   #parentDir;
+  #resolveToken;
 
-  /** Create a WikiRepo targeting the given wiki directory and its parent project directory. */
-  constructor({ wikiDir, parentDir }) {
+  /**
+   * Create a WikiRepo targeting the given wiki directory and its parent project directory.
+   * @param {{ wikiDir: string, parentDir: string, resolveToken: () => string | null }} opts
+   *   `resolveToken` is called lazily before each network operation. Return a
+   *   GitHub token string to authenticate, or `null` to run anonymously. The
+   *   callback owns the entire resolution policy — libwiki does not read
+   *   `process.env` directly. Throws propagate to the caller so credential
+   *   misconfiguration surfaces loudly. Commands typically pass
+   *   `() => config.ghToken()` from `@forwardimpact/libconfig`.
+   */
+  constructor({ wikiDir, parentDir, resolveToken }) {
+    if (typeof wikiDir !== "string" || wikiDir === "") {
+      throw new TypeError("WikiRepo: wikiDir must be a non-empty string");
+    }
+    if (typeof parentDir !== "string" || parentDir === "") {
+      throw new TypeError("WikiRepo: parentDir must be a non-empty string");
+    }
+    if (typeof resolveToken !== "function") {
+      throw new TypeError("WikiRepo: resolveToken callback is required");
+    }
     this.#wikiDir = wikiDir;
     this.#parentDir = parentDir;
+    this.#resolveToken = resolveToken;
   }
 
   /** Check whether the wiki directory is an initialized git repository. */
@@ -92,11 +112,16 @@ export class WikiRepo {
     }
   }
 
-  /** Stage all changes, commit with the given message, fetch, rebase on origin/master (falling back to a merge with -X ours if rebase fails), and push. */
+  /** Stage and commit any working-tree changes, then fetch, rebase on origin/master (falling back to a merge with -X ours if rebase fails), and push if HEAD is ahead of origin/master. The commit gate and the push gate are independent so a clean tree with local commits still pushes. */
   commitAndPush(message) {
-    if (this.isClean()) return { pushed: false, reason: "clean" };
-    this.#git(["add", "-A"]);
-    this.#git(["commit", "-m", message]);
+    const hasWorkingTreeChanges = !this.isClean();
+    if (hasWorkingTreeChanges) {
+      this.#git(["add", "-A"]);
+      this.#git(["commit", "-m", message]);
+    }
+    if (!this.#hasCommitsAhead()) {
+      return { pushed: false, reason: "clean" };
+    }
     this.fetch();
     const rebase = this.#git(["rebase", "origin/master"]);
     if (rebase.status !== 0) {
@@ -107,6 +132,12 @@ export class WikiRepo {
     return { pushed: true, reason: "pushed" };
   }
 
+  #hasCommitsAhead() {
+    const r = this.#git(["rev-list", "--count", "origin/master..HEAD"]);
+    const count = parseInt(r.stdout?.toString().trim() || "0", 10);
+    return count > 0;
+  }
+
   #parentConfig(key) {
     const r = spawnSync(
       "git",
@@ -123,11 +154,14 @@ export class WikiRepo {
   }
 
   #authGit(args) {
-    const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    const token = this.#resolveToken();
     const fullArgs = buildAuthArgs(args, token);
-    return spawnSync("git", fullArgs, {
-      stdio: "pipe",
-      env: token ? process.env : undefined,
-    });
+    // The credential helper body keeps `${GH_TOKEN:-$GITHUB_TOKEN}` literal so
+    // git's child shell expands it at auth time — the token never sits in argv.
+    // Inject the resolved token into the spawn env so the helper's lazy
+    // expansion finds it even when the resolver pulled from `.env` or
+    // `gh auth token` rather than the ambient process env.
+    const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+    return spawnSync("git", fullArgs, { stdio: "pipe", env });
   }
 }