co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/github/client.js

@@ -2,6 +2,7 @@
  * (pat.ts, and app.ts). `GhClient` shells out to the `gh` binary and does
  * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
 import { log } from "../util/log.js";
+import { networkFailure } from "../cli/error.js";
 export class GitHubHttpError extends Error {
     status;
     constructor(status, body) {
@@ -85,7 +86,12 @@ export async function githubFetch(url, init) {
         let response;
         let exhausted;
         for (let attempt = 1; attempt <= 3; attempt++) {
-            response = await fetch(url, init);
+            try {
+                response = await fetch(url, init);
+            }
+            catch (error) {
+                throw networkFailure(url, error);
+            }
             if (response.status !== 403 && response.status !== 429)
                 return response;
             const retryAfterHeader = response.headers.get("retry-after");

package/dist/src/github/collect.js

@@ -286,7 +286,7 @@ async function pullRequests(client, options, previous, phase, progress) {
                 detail = await client.request(`repos/${options.repo}/pulls/${number}`);
             }
             catch (error) {
-                log("fetch", `PR #${number} detail unavailable; diff skipped: ${String(error)}`);
+                log("fetch", `PR #${number} detail unavailable. Diff skipped: ${String(error)}`);
             }
         }
         const current = {

package/dist/src/github/gh.js

@@ -1,7 +1,44 @@
 import { paginate, probeDelay, RATE_LIMIT_PROBE_MS, rateLimitError, waitForRateLimit, } from "./client.js";
 import { log } from "../util/log.js";
-import { commandOutput, commandWithInput, } from "../util/runtime.js";
+import { CliError, EXIT_RUNTIME, EXIT_USAGE } from "../cli/error.js";
+import { commandOutput, commandWithInput, getEnv, } from "../util/runtime.js";
 const PULSE_MS = 120_000;
+/** Test seam: `CM_GH_BIN` replaces the `gh` command and `CM_GH_SCRIPT` (if
+ * set) is prepended as its first argument, so a fake can be run as
+ * `<bin> <script> api …` with no shell. Unset means the real `gh` on PATH, so
+ * production behaviour is unchanged. Spawning without a shell matters: a shell
+ * concatenates arguments unescaped, so an endpoint's `?`, `&` and `=` would be
+ * reinterpreted by cmd.exe on Windows. */
+function ghSpawn() {
+    const bin = getEnv("CM_GH_BIN");
+    if (!bin)
+        return { command: "gh", prefix: [] };
+    const script = getEnv("CM_GH_SCRIPT");
+    return { command: bin, prefix: script ? [script] : [] };
+}
+/** Turns a failed `gh api` call into a message that says what broke, why, and
+ * what to do next (CORE-12, F09/F24/F28). The four shapes the DX research hit:
+ * `gh` missing from PATH, the repo missing or unreadable, an empty stderr, and
+ * everything else. The first line is the only part a human reads, so it always
+ * names the situation; the raw gh text moves to the hint so it stays available
+ * without drowning the message. */
+function ghFailure(endpoint, stderr) {
+    if (/ENOENT|command not found|not recognized/i.test(stderr)) {
+        return new CliError("gh_not_installed", "GitHub CLI (gh) was not found.", "Install it from https://cli.github.com or use --auth=pat.", EXIT_USAGE);
+    }
+    if (/HTTP 404|Not Found/i.test(stderr)) {
+        // The endpoint is `repos/owner/repo/...`; the user thinks in `owner/repo`.
+        const match = endpoint.match(/^repos\/([^/]+)\/([^/]+)/);
+        const subject = match ? `${match[1]}/${match[2]}` : endpoint;
+        return new CliError("repo_not_found", `${subject} was not found, or your GitHub account cannot read it.`, "Check the name and run gh auth status.", EXIT_USAGE);
+    }
+    // An empty stderr used to collapse to just the endpoint, which told the user
+    // nothing about what happened.
+    if (stderr.length === 0) {
+        return new CliError("gh_failed", `gh exited without an error message while reading ${endpoint}.`, "Run gh auth status and try again with --debug.", EXIT_RUNTIME);
+    }
+    return new CliError("gh_failed", `gh could not read ${endpoint}.`, `gh said: ${stderr}`, EXIT_RUNTIME);
+}
 let lastCallAt = 0;
 let pulse;
 function count(value) {
@@ -23,8 +60,9 @@ export function quotaLine(body) {
 }
 async function printQuota() {
     try {
-        const result = await commandOutput("gh", {
-            args: ["api", "rate_limit"],
+        const { command, prefix } = ghSpawn();
+        const result = await commandOutput(command, {
+            args: [...prefix, "api", "rate_limit"],
             stdout: "piped",
             stderr: "piped",
         });
@@ -62,8 +100,9 @@ function noteGhCall(debug) {
 }
 async function readLimit(endpoint) {
     try {
-        const result = await commandOutput("gh", {
-            args: ["api", "rate_limit"],
+        const { command, prefix } = ghSpawn();
+        const result = await commandOutput(command, {
+            args: [...prefix, "api", "rate_limit"],
             stdout: "piped",
             stderr: "piped",
         });
@@ -90,11 +129,14 @@ export class GhClient {
         this.debug = debug;
     }
     request(endpoint) {
-        return this.call(endpoint, () => commandOutput("gh", {
-            args: ["api", endpoint],
-            stdout: "piped",
-            stderr: "piped",
-        }));
+        return this.call(endpoint, () => {
+            const { command, prefix } = ghSpawn();
+            return commandOutput(command, {
+                args: [...prefix, "api", endpoint],
+                stdout: "piped",
+                stderr: "piped",
+            });
+        });
     }
     write(endpoint, body) {
         return this.send(endpoint, "POST", body);
@@ -109,19 +151,34 @@ export class GhClient {
         return paginate((e) => this.request(e), endpoint, limit, progress);
     }
     send(endpoint, method, body) {
-        return this.call(endpoint, () => commandWithInput("gh", {
-            args: ["api", "-X", method, endpoint, "--input", "-"],
-            stdin: "piped",
-            stdout: "piped",
-            stderr: "piped",
-        }, JSON.stringify(body)));
+        return this.call(endpoint, () => {
+            const { command, prefix } = ghSpawn();
+            return commandWithInput(command, {
+                args: [...prefix, "api", "-X", method, endpoint, "--input", "-"],
+                stdin: "piped",
+                stdout: "piped",
+                stderr: "piped",
+            }, JSON.stringify(body));
+        });
     }
     async call(endpoint, run) {
         noteGhCall(this.debug);
         const started = Date.now();
         let spun = false;
         for (;;) {
-            const result = await run();
+            // A missing `gh` binary rejects the spawn instead of returning a failed
+            // result, so the ENOENT case has to be caught here too (CORE-12).
+            let result;
+            try {
+                result = await run();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/ENOENT/i.test(message)) {
+                    throw new CliError("gh_not_installed", "GitHub CLI (gh) was not found.", "Install it from https://cli.github.com or use --auth=pat.", EXIT_USAGE);
+                }
+                throw error;
+            }
             if (result.success) {
                 try {
                     return JSON.parse(new TextDecoder().decode(result.stdout));
@@ -136,7 +193,7 @@ export class GhClient {
                 ? bucket.remaining === 0
                 : /rate limit/i.test(error);
             if (!limited)
-                throw new Error(`gh api failed: ${error || endpoint}`);
+                throw ghFailure(endpoint, error);
             const resetAt = bucket?.resetAt ?? new Date(Date.now() + RATE_LIMIT_PROBE_MS);
             const delay = probeDelay(resetAt, Date.now());
             if (delay === 0) {

package/dist/src/knowledge/facts.js

@@ -266,7 +266,7 @@ export function extractFacts(source, options) {
     }
     if (source.pullRequests.length) {
         const merged = source.pullRequests.filter((pr) => pr.merged).length;
-        add(facts, fact("process", `${merged}/${source.pullRequests.length} selected pull requests are merged; keep work mergeable before requesting review.`, "pull request metadata", 2));
+        add(facts, fact("process", `${merged}/${source.pullRequests.length} selected pull requests are merged. Keep work mergeable before requesting review.`, "pull request metadata", 2));
         const labels = counts(source.pullRequests.flatMap((pr) => pr.labels))
             .slice(0, 12)
             .map(([label, count]) => `\`${label}\` (${count})`);
@@ -275,7 +275,7 @@ export function extractFacts(source, options) {
         }
         const described = source.pullRequests.filter((pr) => pr.body.trim().length > 80).length;
         if (described / source.pullRequests.length >= 0.7) {
-            add(facts, fact("title-body", "Most selected pull requests contain a substantive description; explain purpose, scope, and verification before requesting review.", "pull request descriptions", 3));
+            add(facts, fact("title-body", "Most selected pull requests contain a substantive description. Explain purpose, scope, and verification before requesting review.", "pull request descriptions", 3));
         }
         const reviewText = source.pullRequests
             .flatMap((pr) => [...pr.comments, ...pr.reviews])
@@ -292,7 +292,12 @@ export function extractFacts(source, options) {
         ]) {
             const count = (reviewText.match(new RegExp(`\\b${term}\\w*\\b`, "g")) ?? []).length;
             if (count >= 2) {
-                add(facts, fact("review-bar", instruction, `review discussion (${count} mentions)`, count));
+                add(facts, {
+                    ...fact("review-bar", instruction, `review discussion (${count} mentions)`, count),
+                    // A rule mined from discussion across several pull requests is
+                    // repository policy, not one request's narrative (CORE-32).
+                    origin: "repository",
+                });
             }
         }
         if (source.pullRequests.some((pr) => pr.additions + pr.deletions > 1000)) {

package/dist/src/knowledge/guide.d.ts

@@ -3,4 +3,12 @@ export type ReviewDocuments = {
     guide: string;
     detailed?: string;
 };
+/** A fact read out of a single pull request describes that request, not the
+ * repository. `origin` is absent on facts written before the field existed, so
+ * those count as repository policy (CORE-32 / F26b). */
+export declare function isPullRequestFact(item: Fact): boolean;
+/** The selected review signals, before the `>2` threshold is applied. Exported
+ * so `init` can tell the user how far short of the threshold a repository is
+ * (CORE-31), rather than silently skipping the two guide files. */
+export declare function reviewSignalCount(facts: Fact[]): number;
 export declare function buildReviewDocuments(facts: Fact[]): ReviewDocuments | undefined;

package/dist/src/knowledge/guide.js

@@ -1,11 +1,12 @@
-function reviewFacts(facts) {
+/** A fact read out of a single pull request describes that request, not the
+ * repository. `origin` is absent on facts written before the field existed, so
+ * those count as repository policy (CORE-32 / F26b). */
+export function isPullRequestFact(item) {
+    return item.origin === "pull-request";
+}
+function dedupe(items) {
     const seen = new Set();
-    return facts
-        .filter((item) => item.sectionKey === "review-bar" &&
-        item.evidence.some((evidence) => evidence.startsWith("PR #") ||
-            evidence.startsWith("review discussion")))
-        .sort((a, b) => b.weight - a.weight || a.claim.localeCompare(b.claim))
-        .filter((item) => {
+    return items.filter((item) => {
         const key = item.claim.toLowerCase().replace(/\W+/g, " ").trim();
         if (seen.has(key))
             return false;
@@ -13,6 +14,23 @@ function reviewFacts(facts) {
         return true;
     });
 }
+function reviewBarFacts(facts) {
+    return facts
+        .filter((item) => item.sectionKey === "review-bar" &&
+        item.evidence.some((evidence) => evidence.startsWith("PR #") ||
+            evidence.startsWith("review discussion")))
+        .sort((a, b) => b.weight - a.weight || a.claim.localeCompare(b.claim));
+}
+/** The short guide's checklist: every recurring review signal, including the
+ * ones mined from pull requests (CORE-32 keeps this file's PR source). */
+function reviewFacts(facts) {
+    return dedupe(reviewBarFacts(facts));
+}
+/** The detailed guide's checklist: only expectations backed by repository-wide
+ * evidence, never a single pull request's narrative (CORE-32). */
+function detailedFacts(facts) {
+    return dedupe(reviewBarFacts(facts).filter((item) => !isPullRequestFact(item)));
+}
 function detailedDocument(facts) {
     const bullets = facts.flatMap((fact) => {
         const claim = fact.claim.replace(/\bPR\s*#?\s*\d+\b/gi, "the change");
@@ -46,11 +64,17 @@ It describes failure patterns to look for, not historical pull requests.
 ${bullets.join("\n")}
 `;
 }
+/** The selected review signals, before the `>2` threshold is applied. Exported
+ * so `init` can tell the user how far short of the threshold a repository is
+ * (CORE-31), rather than silently skipping the two guide files. */
+export function reviewSignalCount(facts) {
+    return reviewFacts(facts).length;
+}
 export function buildReviewDocuments(facts) {
     const selected = reviewFacts(facts);
     if (selected.length <= 2)
         return undefined;
-    const detailed = detailedDocument(selected.slice(0, 120));
+    const detailed = detailedDocument(detailedFacts(facts).slice(0, 120));
     const detailedLines = detailed.trimEnd().split("\n").length;
     if (detailedLines <= 100) {
         return {

package/dist/src/knowledge/probe.js

@@ -103,7 +103,7 @@ export function analyzeProbe(meta, pulls, detailSamples, commits) {
             : Infinity;
         reasons.push(releaseAgeMonths <= 18
             ? `A release from ${latestReleaseAt.slice(0, 10)} is recent; use the last ${maxPrMonths} months to prioritize the current contribution and release process.`
-            : `The last ${maxPrMonths} months cover at least 85% of pull requests; older history is a minority.`);
+            : `The last ${maxPrMonths} months cover at least 85% of pull requests. Older history is a minority.`);
     }
     else if (pulls.length) {
         reasons.push("Pull request volume or history span is small enough to keep all PR months.");
@@ -112,10 +112,20 @@ export function analyzeProbe(meta, pulls, detailSamples, commits) {
         reasons.push(`${usefulCommits} non-merge commits contain enough signal to analyze commit conventions.`);
     }
     else if (commits.length) {
-        reasons.push("Commit history is mostly merge/noise commits, so it is not recommended as a source.");
+        // Only claim the history is noise when the useful-commit ratio actually
+        // supports it. With `commits: 8 · useful: 5` the ratio is above a half,
+        // and the old unconditional sentence contradicted the numbers beside it
+        // (CORE-24).
+        const usefulRatio = usefulCommits / commits.length;
+        if (usefulRatio < 0.5) {
+            reasons.push("Commit history is mostly merge/noise commits, so it is not recommended as a source.");
+        }
+        else {
+            reasons.push(`Commit history is short (${commits.length} ${commits.length === 1 ? "commit" : "commits"}), so it is not recommended as a source yet.`);
+        }
     }
     if (maxChangeLines) {
-        reasons.push(`The sampled diff p90 is ${p90Diff} lines; the cap keeps the largest outliers out while retaining about 90% of sampled diffs.`);
+        reasons.push(`The sampled diff p90 is ${p90Diff} lines. The cap keeps the largest outliers out while retaining about 90% of sampled diffs.`);
     }
     return {
         includePullRequests: pulls.length > 0,

package/dist/src/knowledge/sections.d.ts

@@ -1,2 +1,11 @@
 export declare const sectionTitles: Record<string, string>;
 export declare const sectionKeys: string[];
+/** Sections whose content also lives in `CODEBASE.md`. The skill links to that
+ * file instead of keeping a second copy (CORE-32 / F26c). */
+export declare const codebaseSectionKeys: Set<string>;
+/** A fact read out of a single pull request describes that request, not the
+ * repository, so it may only feed the `review-bar` checklist. Every other
+ * section states repository policy and must not learn from one PR's narrative
+ * (CORE-32 / F26b). Keep this in sync with `guide.ts`, which applies the same
+ * rule to the review guides. */
+export declare function sectionAllowsPrFacts(key: string): boolean;

package/dist/src/knowledge/sections.js

@@ -11,3 +11,19 @@ export const sectionTitles = {
     process: "Pull request process",
 };
 export const sectionKeys = Object.keys(sectionTitles);
+/** Sections whose content also lives in `CODEBASE.md`. The skill links to that
+ * file instead of keeping a second copy (CORE-32 / F26c). */
+export const codebaseSectionKeys = new Set([
+    "layout",
+    "style",
+    "tests",
+    "devloop",
+]);
+/** A fact read out of a single pull request describes that request, not the
+ * repository, so it may only feed the `review-bar` checklist. Every other
+ * section states repository policy and must not learn from one PR's narrative
+ * (CORE-32 / F26b). Keep this in sync with `guide.ts`, which applies the same
+ * rule to the review guides. */
+export function sectionAllowsPrFacts(key) {
+    return key === "review-bar";
+}

package/dist/src/knowledge/skill.d.ts

@@ -1,4 +1,9 @@
 import type { Fact } from "./types.ts";
+/** The full text of the sections that live in `CODEBASE.md`. The skill itself
+ * only links to that file, so this is the single place the codebase guidance is
+ * written out: the synthesized override when there is one, otherwise the
+ * rendered facts (CORE-32 / F26c). */
+export declare function codebaseBody(facts: Fact[], overrides?: Record<string, string>): string;
 /** Slices an assembled skill's `## Heading` sections back out by section key,
  * from `<!-- section:key -->` markers or (fallback) canonical heading text. */
 export declare function extractSections(markdown: string): Record<string, string>;

package/dist/src/knowledge/skill.js

@@ -1,15 +1,54 @@
-import { sectionKeys, sectionTitles } from "./sections.js";
+import { isPullRequestFact } from "./guide.js";
+import { codebaseSectionKeys, sectionAllowsPrFacts, sectionKeys, sectionTitles, } from "./sections.js";
 function sectionFacts(facts, key) {
     return facts
         .filter((item) => item.sectionKey === key)
         .sort((a, b) => b.weight - a.weight);
 }
+/** Facts a section may state. A fact read out of a single pull request is that
+ * request's narrative, not a rule, so only `review-bar` may use it (CORE-32 /
+ * F26b). Facts written before `origin` existed count as repository policy. */
+function usableFacts(facts, key) {
+    const items = sectionFacts(facts, key);
+    return sectionAllowsPrFacts(key)
+        ? items
+        : items.filter((item) => !isPullRequestFact(item));
+}
+/** The link that stands in for a codebase section's text. */
+function isCodebaseLink(section) {
+    return section.includes("[CODEBASE.md](CODEBASE.md)");
+}
 function render(key, facts) {
-    const items = sectionFacts(facts, key).slice(0, 6);
+    if (codebaseSectionKeys.has(key)) {
+        return `## ${sectionTitles[key] ?? key}\n\nSee [CODEBASE.md](CODEBASE.md).`;
+    }
+    const items = usableFacts(facts, key).slice(0, 6);
     if (!items.length)
         return "";
     return `## ${sectionTitles[key] ?? key}\n\n${items.map((item) => `- ${item.claim}`).join("\n")}`;
 }
+function codebaseSectionText(key, facts, overrides) {
+    const override = overrides[key]?.trim();
+    if (override && hasBullets(override) && !isCodebaseLink(override)) {
+        return cleanSection(override);
+    }
+    const items = usableFacts(facts, key).slice(0, 6);
+    if (!items.length)
+        return "";
+    return `## ${sectionTitles[key] ?? key}\n\n${items
+        .map((item) => `- ${item.claim}`)
+        .join("\n")}`;
+}
+/** The full text of the sections that live in `CODEBASE.md`. The skill itself
+ * only links to that file, so this is the single place the codebase guidance is
+ * written out: the synthesized override when there is one, otherwise the
+ * rendered facts (CORE-32 / F26c). */
+export function codebaseBody(facts, overrides = {}) {
+    return [...codebaseSectionKeys]
+        .map((key) => codebaseSectionText(key, facts, overrides))
+        .filter(Boolean)
+        .join("\n\n");
+}
 function cleanSection(value) {
     return value.replace(/^\s*```[a-zA-Z0-9_-]*\s*$/gm, "").trim();
 }
@@ -42,18 +81,25 @@ async function hash(value) {
         .map((byte) => byte.toString(16).padStart(2, "0"))
         .join("");
 }
+/** The fields that decide a section's text. `origin` is included so a fact
+ * moving from PR narrative to repository policy (or the reverse) counts as a
+ * change rather than reusing a section built under the old rule (CORE-32). */
+function hashInput(item) {
+    return [
+        item.id,
+        item.claim,
+        item.weight,
+        item.scope,
+        item.confidence,
+        item.status,
+        item.origin ?? "repository",
+    ];
+}
 export async function factSectionHashes(facts) {
     const hashes = {};
     for (const key of new Set(facts.map((item) => item.sectionKey))) {
         const relevant = sectionFacts(facts, key);
-        hashes[key] = await hash(JSON.stringify(relevant.map((item) => [
-            item.id,
-            item.claim,
-            item.weight,
-            item.scope,
-            item.confidence,
-            item.status,
-        ])));
+        hashes[key] = await hash(JSON.stringify(relevant.map(hashInput)));
     }
     return hashes;
 }
@@ -68,26 +114,27 @@ export async function assembleSkill(repo, facts, previousMarkdown, previousHashe
         if (!content)
             continue;
         const relevant = sectionFacts(facts, key);
-        const sectionHash = await hash(JSON.stringify(relevant.map((item) => [
-            item.id,
-            item.claim,
-            item.weight,
-            item.scope,
-            item.confidence,
-            item.status,
-        ])));
+        const sectionHash = await hash(JSON.stringify(relevant.map(hashInput)));
         hashes[key] = sectionHash;
         const canonicalHeading = `## ${sectionTitles[key] ?? key}`;
-        const hasOverride = Object.hasOwn(overrides, key);
+        // The codebase sections hold a link, not text, so the skill never takes a
+        // synthesized override for them; the override goes to CODEBASE.md instead.
+        const hasOverride = Object.hasOwn(overrides, key) && !codebaseSectionKeys.has(key);
         if (!hasOverride &&
             previousMarkdown &&
             previousHashes[key] === sectionHash &&
-            previous[key]?.startsWith(canonicalHeading)) {
+            previous[key]?.startsWith(canonicalHeading) &&
+            // A section whose shape changed (the codebase sections now carry a link
+            // instead of the text) is rewritten rather than kept because its facts
+            // happen to be unchanged.
+            isCodebaseLink(content) === isCodebaseLink(previous[key])) {
             sections[key] = cleanSection(previous[key]);
             continue;
         }
         const section = hasOverride ? overrides[key] : content;
-        if (!hasBullets(section))
+        // A codebase section is a link, not a bullet list, so it is kept even
+        // though it has no bullets; a text section without bullets is dropped.
+        if (!isCodebaseLink(section) && !hasBullets(section))
             continue;
         sections[key] = section;
         changed.push(key);

package/dist/src/knowledge/synthesis.d.ts

@@ -1,7 +1,23 @@
+import type { SkippedUnit } from "../ai/batch.ts";
 import type { AiProvider, AiResponse, Options } from "../types.ts";
 import type { Fact, Source } from "./types.ts";
 type UsageSink = (job: string, response: AiResponse) => Promise<void>;
+export type SkippedUnits = SkippedUnit[];
+export type SynthesisResult = Record<string, string>;
 export declare function extractAiFacts(provider: AiProvider, repo: string, source: Source, options: Options, usage?: UsageSink): Promise<Fact[]>;
+export declare function extractAiFactsWithReport(provider: AiProvider, repo: string, source: Source, options: Options, usage?: UsageSink): Promise<{
+    facts: Fact[];
+    skipped: SkippedUnit[];
+}>;
+/** Same as {@link extractAiFacts}, but also reports what the batch skipped so
+ * the caller can put it in the final `[done]` line (CORE-30). */
+export declare function enrichFactsWithReport(provider: AiProvider, repo: string, base: Fact[], source: Source, options: Options, usage?: UsageSink): Promise<{
+    facts: Fact[];
+    skipped: SkippedUnit[];
+}>;
 export declare function enrichFacts(provider: AiProvider, repo: string, base: Fact[], source: Source, options: Options, usage?: UsageSink): Promise<Fact[]>;
-export declare function synthesizeSections(provider: AiProvider, repo: string, facts: Fact[], _previousMarkdown: string | undefined, ai: Options["ai"], model: string, concurrency: number, usage?: UsageSink, onlySections?: Set<string>): Promise<Record<string, string>>;
+export declare function synthesizeSections(provider: AiProvider, repo: string, facts: Fact[], _previousMarkdown: string | undefined, ai: Options["ai"], model: string, concurrency: number, usage?: UsageSink, onlySections?: Set<string>): Promise<{
+    overrides: Record<string, string>;
+    skipped: SkippedUnit[];
+}>;
 export {};