@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/cli/import-files.mjs

@@ -0,0 +1,15 @@
+// Optional project import probes.
+import fs from "node:fs";
+
+// A denied read or a loop of links is not absence: hiding it could report less than the host loads.
+const ABSENT = new Set(["ENOENT", "ENOTDIR", "ENAMETOOLONG", "ERR_INVALID_ARG_VALUE"]);
+export const isAbsentImportError = (error) => ABSENT.has(error?.code);
+
+export function importTargetIsFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    } catch (error) {
+        if (isAbsentImportError(error)) return false;
+        throw error;
+    }
+}

package/cli/index.mjs

@@ -14,6 +14,7 @@ import { pathToFileURL } from "node:url";
 
 import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
+import { HandoffError, handoffPolicy, handoffOverages, handoffTokens } from "./handoff-policy.mjs";
 
 /** Raised when `index` cannot run, or cannot judge honestly. Always exit 2, never 1. */
 export class IndexError extends Error {
@@ -23,7 +24,7 @@ export class IndexError extends Error {
     }
 }
 
-const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13"]);
+const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "2.15", "2.16"]);
 
 // `doctor` skips the same name, so the two count the same records.
 const NOT_A_RECORD = new Set(["README.md"]);
@@ -51,12 +52,17 @@ export function headingOf(source) {
     return first?.match(/^#[ \t]+(.+?)[ \t]*$/)?.[1] ?? null;
 }
 
-/** A handoff's date, the leading `YYYY-MM-DD` of its filename where that names a real day, else null. */
+/** Valid leading filename date, or null. */
 export function dateOf(filename) {
     const m = filename.match(/^(\d{4})-(\d{2})-(\d{2})-/);
     return m ? realDay(m[1], m[2], m[3]) : null;
 }
 
+export function eligibleHandoffDate(filename, today) {
+    const date = dateOf(filename);
+    return date !== null && date <= nextDay(today) ? date : null;
+}
+
 function realDay(y, mo, d) {
     const at = new Date(0);
     // Not `Date.UTC`, which reads a year from 0 to 99 as 1900 to 1999.
@@ -127,8 +133,20 @@ export function readStore(dir, workspace) {
     return { records, bytes };
 }
 
-/** A workspace's handoff series, `{ records, bytes }`, newest first; a record's `date` or `heading` is null where it has none. */
-export function readHandoffs(dir, workspace) {
+function regularHandoff(seriesDir, slot, file) {
+    try {
+        const stat = fs.lstatSync(path.join(seriesDir, file));
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new IndexError(`${path.join(slot, file)} is not a regular file: a handoff is a file of its own, never a link or a directory`);
+        }
+    } catch (cause) {
+        if (cause instanceof IndexError) throw cause;
+        throw new IndexError(`cannot read the handoff ${path.join(slot, file)} — ${cause.code ?? cause.message}`);
+    }
+}
+
+/** The series' metadata, newest first; bodies stay with the reader that needs them. */
+export function handoffEntries(dir, workspace) {
     const slot = workspace?.slots?.handoffs;
     if (!slot) {
         throw new IndexError(
@@ -141,23 +159,31 @@ export function readHandoffs(dir, workspace) {
     // `readdirSync` follows a link, so a link on the series path is refused before it is listed.
     refuseLinks(dir, slot, seriesDir, "a handoff series is read where its path says");
     const files = listSeries(seriesDir, slot, "handoff series").reverse();
+    return files.map(file => {
+        regularHandoff(seriesDir, slot, file);
+        return { file, date: dateOf(file) };
+    });
+}
+
+/** A workspace's handoff series, `{ records, bytes }`, newest first; a record's `date` or `heading` is null where it has none. */
+export function readHandoffs(dir, workspace) {
+    const entries = handoffEntries(dir, workspace), slot = workspace.slots.handoffs;
+    const seriesDir = path.resolve(dir, slot);
     const records = [];
     let bytes = 0;
 
-    for (const file of files) {
+    for (const { file, date } of entries) {
         let source;
         try {
-            const stat = fs.lstatSync(path.join(seriesDir, file));
-            if (stat.isSymbolicLink() || !stat.isFile()) {
-                throw new IndexError(`${path.join(slot, file)} is not a regular file: a handoff is a file of its own, never a link or a directory`);
-            }
+            regularHandoff(seriesDir, slot, file);
             source = fs.readFileSync(path.join(seriesDir, file), "utf8");
         } catch (cause) {
             if (cause instanceof IndexError) throw cause;
             throw new IndexError(`cannot read the handoff ${path.join(slot, file)} — ${cause.code ?? cause.message}`);
         }
-        bytes += Buffer.byteLength(source);
-        records.push({ file, date: dateOf(file), heading: headingOf(source) });
+        const recordBytes = Buffer.byteLength(source);
+        bytes += recordBytes;
+        records.push({ file, date, heading: headingOf(source), bytes: recordBytes });
     }
 
     return { records, bytes };
@@ -358,13 +384,17 @@ export function renderHandoffIndex(workspace, series) {
     const posix = (p) => p.split(path.sep).join(path.posix.sep);
     const from = path.posix.dirname(posix(indexPath));
 
+    let policy;
+    try { policy = handoffPolicy(workspace); }
+    catch (error) { throw new IndexError(error.message); }
     const header = [
         `# Handoff index — ${workspace.name}`,
         "",
         `> Generated from \`${slot}\` by \`node cli/index.mjs\`. Do not edit by hand: it is regenerated`,
         `> and byte-compared, so a hand-edit survives exactly until the next run.`,
-        `> ${series.records.length} handoff(s), newest first. No budget: the series is append-only, so`,
-        `> the only remedy a budget could ask for is one this project rules out.`,
+        ...(policy.window === null ? [
+            `> ${series.records.length} handoff(s), newest first. No index budget declared; the full series is listed.`,
+        ] : [`> ${series.records.length} handoff(s), newest first. Index budget: ${policy.window} tokens at ${policy.ratio} bytes per token.`]),
         "",
     ];
 
@@ -373,7 +403,17 @@ export function renderHandoffIndex(workspace, series) {
         return `- ${r.date} · [${r.heading}](${href})`;
     });
 
-    return [...header, ...entries].join("\n") + "\n";
+    if (policy.window === null) return [...header, ...entries].join("\n") + "\n";
+    const text = (count, budget = policy.window) => [...header.map(line => line.replace(`Index budget: ${policy.window} tokens`, `Index budget: ${budget} tokens`)), ...entries.slice(0, count), "", `> ${entries.length - count} handoff(s) omitted; all remain in \`${slot}\`, filenames ordered by date.`].join("\n") + "\n";
+    const overhead = text(0);
+    if (handoffTokens(Buffer.byteLength(overhead), policy.ratio) > policy.window) {
+        let minimum = 1;
+        while (handoffTokens(Buffer.byteLength(text(0, minimum)), policy.ratio) > minimum) minimum = handoffTokens(Buffer.byteLength(text(0, minimum)), policy.ratio);
+        throw new IndexError(`handoffs.index.budget.tokens is too small: at least ${minimum} tokens hold the complete header and omission notice`);
+    }
+    let count = 0;
+    while (count < entries.length && handoffTokens(Buffer.byteLength(text(count + 1)), policy.ratio) <= policy.window) count++;
+    return text(count);
 }
 
 export function renderScopeIndex(workspace, series) {
@@ -430,7 +470,7 @@ export function inspect(dir, { write = false, packRoots: extraRoots, discoverPac
     ].join("");
 
     const memory = judgeMemory(dir, workspace, { write, fail, note, today, remedyFlags });
-    const handoffs = judgeHandoffs(dir, workspace, { write, fail, remedyFlags });
+    const handoffs = judgeHandoffs(dir, workspace, { write, fail, note, today, remedyFlags });
     const scopes = judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks, remedyFlags });
 
     return {
@@ -558,26 +598,32 @@ function judgeMemory(dir, workspace, { write, fail, note, today, remedyFlags = "
     return { declared: true, path: indexPath, expected, budgets };
 }
 
-function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
+function judgeHandoffs(dir, workspace, { write, fail, note, today, remedyFlags = "" }) {
     const declaredPath = workspace.handoffs?.index?.path;
-    if (!declaredPath) return { declared: false, path: null, expected: null };
+    let policy;
+    try { policy = handoffPolicy(workspace); }
+    catch (error) {
+        if (!(error instanceof HandoffError)) throw error;
+        throw new IndexError(error.message);
+    }
+    if (!workspace.slots?.handoffs && !workspace.handoffs) return { declared: false, path: null, expected: null };
 
-    const indexPath = siteOutside(dir, declaredPath, workspace.slots?.handoffs, "series");
+    const indexPath = declaredPath ? siteOutside(dir, declaredPath, workspace.slots?.handoffs, "series") : null;
     const series = readHandoffs(dir, workspace);
 
     let broken = 0;
     for (const r of series.records) {
         const where = path.join(workspace.slots.handoffs, r.file);
-        if (r.date === null) {
+        if (eligibleHandoffDate(r.file, today) === null) {
             broken += 1;
             fail(
                 "handoffs",
                 "date",
-                `${where} does not lead with a valid YYYY-MM-DD date, so the index has no date to put on its line. ` +
+                `${where} must lead with a valid YYYY-MM-DD date no more than a day after ${today} (UTC). ` +
                     "core/operating/loop.md fixes the form as `YYYY-MM-DD-{slug}.md` — rename the file",
             );
         }
-        if (r.heading === null) {
+        if (declaredPath && r.heading === null) {
             broken += 1;
             fail(
                 "handoffs",
@@ -587,6 +633,12 @@ function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
             );
         }
     }
+    const overages = handoffOverages(series, policy);
+    for (const record of overages.bound) fail("handoffs", "budget",
+        `${path.join(workspace.slots.handoffs, record.file)} is ${record.tokens} tokens at ${policy.ratio} bytes per token, against a cap of ${policy.cap} — over by ${record.tokens - policy.cap}. ` +
+        "Compress it or move facts to their owning records and link them; keep each decision and its why. Never split, retire, raise the cap or move the cutoff to repair this breach");
+    if (overages.historical.length) note("handoffs", `${overages.historical.length} handoff(s) on or before cutoff ${policy.cutoff} exceed ${policy.cap} tokens: reported, never railed`);
+    if (!declaredPath) return { declared: true, path: null, expected: null, count: series.records.length, kept: false };
     if (broken) return { declared: true, path: indexPath, expected: null, count: series.records.length };
 
     const expected = renderHandoffIndex(workspace, series);
@@ -1052,7 +1104,8 @@ export function run(argv, say = console.log) {
             for (const f of broken) say(`  ✗ ${dir}: ${f.message}`);
             if (broken.length && worst < 1) worst = 1;
             else if (!result.series.handoffs.declared) say(`  · ${dir}: declares no handoff index`);
-            else if (!broken.length) say(result.series.handoffs.expected.trimEnd());
+            else if (!broken.length && result.series.handoffs.expected !== null) say(result.series.handoffs.expected.trimEnd());
+            else say(`  · ${dir}: declares no handoff index`);
             continue;
         }
         if (!result.declared) {
@@ -1074,8 +1127,8 @@ export function run(argv, say = console.log) {
                 }
             }
             if (result.series.handoffs.declared) {
-                const { kept, count } = result.series.handoffs;
-                parts.push(kept ? `handoff index ${state}` : `handoff index renders, ${count} handoff(s), none kept on disk`);
+                const { kept, count, path: indexPath } = result.series.handoffs;
+                parts.push(indexPath === null ? `handoff dates checked, ${count} handoff(s); no index declared` : kept ? `handoff index ${state}` : `handoff index renders, ${count} handoff(s), none kept on disk`);
             }
             if (result.series.scopes.declared) parts.push(`scope index ${state}`);
             say(`  ok ${dir}: ${parts.join("; ")}`);