co-maintainer 0.4.0-beta.1

package/dist/src/github/jwt.js

@@ -0,0 +1,84 @@
+/** GitHub hands out App private keys as PKCS#1 PEM ("BEGIN RSA PRIVATE
+ * KEY"). Web Crypto's `importKey("pkcs8", ...)` only takes PKCS#8. The two
+ * differ by a fixed 26-byte wrapper around the same PKCS#1 bytes: a version
+ * INTEGER, the rsaEncryption AlgorithmIdentifier, and an OCTET STRING tag
+ * around the PKCS#1 payload — this file builds that wrapper by hand rather
+ * than pulling in an ASN.1 library for one fixed structure. */
+const RSA_ALGORITHM_IDENTIFIER = Uint8Array.from([
+    0x30,
+    0x0d, // SEQUENCE, 13 bytes
+    0x06,
+    0x09,
+    0x2a,
+    0x86,
+    0x48,
+    0x86,
+    0xf7,
+    0x0d,
+    0x01,
+    0x01,
+    0x01, // OID 1.2.840.113549.1.1.1 rsaEncryption
+    0x05,
+    0x00, // NULL
+]);
+function derLength(length) {
+    if (length < 0x80)
+        return [length];
+    const bytes = [];
+    for (let n = length; n > 0; n >>= 8)
+        bytes.unshift(n & 0xff);
+    return [0x80 | bytes.length, ...bytes];
+}
+function derTlv(tag, content) {
+    return Uint8Array.from([tag, ...derLength(content.length), ...content]);
+}
+export function pkcs1ToPkcs8(pkcs1) {
+    const version = Uint8Array.from([0x02, 0x01, 0x00]);
+    const octetString = derTlv(0x04, pkcs1);
+    const inner = new Uint8Array(version.length + RSA_ALGORITHM_IDENTIFIER.length + octetString.length);
+    inner.set(version, 0);
+    inner.set(RSA_ALGORITHM_IDENTIFIER, version.length);
+    inner.set(octetString, version.length + RSA_ALGORITHM_IDENTIFIER.length);
+    return derTlv(0x30, inner);
+}
+function pemToDer(pem) {
+    const match = pem.match(/-----BEGIN ([^-]+)-----([\s\S]+?)-----END \1-----/);
+    if (!match)
+        throw new Error("not a PEM-encoded key");
+    const base64 = match[2].replace(/\s+/g, "");
+    const der = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+    return { der, label: match[1].trim() };
+}
+export async function importAppPrivateKey(pem) {
+    const { der, label } = pemToDer(pem);
+    let pkcs8;
+    if (label === "RSA PRIVATE KEY")
+        pkcs8 = pkcs1ToPkcs8(der);
+    else if (label === "PRIVATE KEY")
+        pkcs8 = der;
+    else
+        throw new Error(`unsupported private key PEM label: ${label}`);
+    return await crypto.subtle.importKey("pkcs8", pkcs8, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+}
+function base64url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function base64urlJson(value) {
+    return base64url(new TextEncoder().encode(JSON.stringify(value)));
+}
+/** GitHub requires `exp` no more than 10 minutes out and tolerates `iat` a
+ * little in the past to absorb clock drift between this machine and
+ * GitHub's. */
+export async function signAppJwt(appId, key) {
+    const now = Math.floor(Date.now() / 1000);
+    const signingInput = `${base64urlJson({ alg: "RS256", typ: "JWT" })}.${base64urlJson({
+        iat: now - 60,
+        exp: now + 600,
+        iss: appId,
+    })}`;
+    const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(signingInput));
+    return `${signingInput}.${base64url(new Uint8Array(signature))}`;
+}

package/dist/src/github/oauth.d.ts

@@ -0,0 +1,9 @@
+export declare function githubAuthorizeUrl(clientId: string, redirectUri: string, state: string): string;
+/** Exchanges an authorization `code` for the GitHub login it belongs to,
+ * or `undefined` if the exchange or the `/user` lookup fails. */
+export declare function githubLoginFromCode(opts: {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+}): Promise<string | undefined>;

package/dist/src/github/oauth.js

@@ -0,0 +1,51 @@
+/** The user-to-server side of a GitHub App's OAuth flow — "Sign in with
+ * GitHub" — reusing the App's own client ID/secret. No separate OAuth App
+ * is needed. */
+import { githubFetch } from "./client.js";
+export function githubAuthorizeUrl(clientId, redirectUri, state) {
+    const url = new URL("https://github.com/login/oauth/authorize");
+    url.searchParams.set("client_id", clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", state);
+    return url.toString();
+}
+async function exchangeGithubCode(opts) {
+    const response = await githubFetch("https://github.com/login/oauth/access_token", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: JSON.stringify({
+            client_id: opts.clientId,
+            client_secret: opts.clientSecret,
+            code: opts.code,
+            redirect_uri: opts.redirectUri,
+        }),
+    });
+    if (!response.ok)
+        return undefined;
+    const body = (await response.json());
+    return body.access_token;
+}
+async function githubLoginFor(accessToken) {
+    const response = await githubFetch("https://api.github.com/user", {
+        headers: {
+            Accept: "application/vnd.github+json",
+            Authorization: `Bearer ${accessToken}`,
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok)
+        return undefined;
+    const body = (await response.json());
+    return body.login;
+}
+/** Exchanges an authorization `code` for the GitHub login it belongs to,
+ * or `undefined` if the exchange or the `/user` lookup fails. */
+export async function githubLoginFromCode(opts) {
+    const accessToken = await exchangeGithubCode(opts);
+    if (!accessToken)
+        return undefined;
+    return await githubLoginFor(accessToken);
+}

package/dist/src/github/pat.d.ts

@@ -0,0 +1,10 @@
+import type { GitHubClient } from "../types.ts";
+export declare class PatClient implements GitHubClient {
+    private readonly token;
+    constructor(token: string);
+    request<T>(endpoint: string): Promise<T>;
+    write<T>(endpoint: string, body: unknown): Promise<T>;
+    createCheckRun<T>(endpoint: string, body: unknown): Promise<T>;
+    updateCheckRun<T>(endpoint: string, body: unknown): Promise<T>;
+    pages<T>(endpoint: string, limit?: number, progress?: (page: number, fetched: number) => void): Promise<T[]>;
+}

package/dist/src/github/pat.js

@@ -0,0 +1,60 @@
+import { githubFetch, GitHubHttpError, paginate } from "./client.js";
+export class PatClient {
+    token;
+    constructor(token) {
+        if (!token)
+            throw new Error("PAT mode requires GITHUB_TOKEN or GH_TOKEN");
+        this.token = token;
+    }
+    async request(endpoint) {
+        const response = await githubFetch(`https://api.github.com/${endpoint}`, {
+            headers: {
+                Accept: "application/vnd.github+json",
+                Authorization: `Bearer ${this.token}`,
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        });
+        if (!response.ok) {
+            throw new GitHubHttpError(response.status, await response.text());
+        }
+        return (await response.json());
+    }
+    async write(endpoint, body) {
+        const response = await githubFetch(`https://api.github.com/${endpoint}`, {
+            method: "POST",
+            headers: {
+                Accept: "application/vnd.github+json",
+                Authorization: `Bearer ${this.token}`,
+                "X-GitHub-Api-Version": "2022-11-28",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new GitHubHttpError(response.status, await response.text());
+        }
+        return (await response.json());
+    }
+    async createCheckRun(endpoint, body) {
+        return await this.write(endpoint, body);
+    }
+    async updateCheckRun(endpoint, body) {
+        const response = await githubFetch(`https://api.github.com/${endpoint}`, {
+            method: "PATCH",
+            headers: {
+                Accept: "application/vnd.github+json",
+                Authorization: `Bearer ${this.token}`,
+                "X-GitHub-Api-Version": "2022-11-28",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new GitHubHttpError(response.status, await response.text());
+        }
+        return (await response.json());
+    }
+    pages(endpoint, limit, progress) {
+        return paginate((e) => this.request(e), endpoint, limit, progress);
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Options } from "../types.ts";
+import type { Fact, Source } from "./types.ts";
+export declare function extractFacts(source: Source, options: Options): Fact[];

package/dist/src/knowledge/facts.js

@@ -0,0 +1,325 @@
+function fact(sectionKey, claim, evidence, weight = 1) {
+    return {
+        id: `${sectionKey}:${claim.toLowerCase().replaceAll(/\W+/g, "-")}`,
+        sectionKey,
+        claim,
+        evidence: [evidence],
+        weight,
+        scope: "current",
+        confidence: "high",
+        status: "active",
+    };
+}
+function add(facts, item) {
+    const existing = facts.get(item.id);
+    if (!existing)
+        facts.set(item.id, item);
+    else {
+        existing.weight += item.weight;
+        existing.evidence = [...new Set([...existing.evidence, ...item.evidence])];
+        if (existing.scope !== item.scope) {
+            existing.scope =
+                existing.scope === "current" || item.scope === "current"
+                    ? "current"
+                    : "repeated-history";
+        }
+        existing.confidence =
+            existing.confidence === "high" || item.confidence === "high"
+                ? "high"
+                : existing.confidence === "medium" || item.confidence === "medium"
+                    ? "medium"
+                    : "low";
+    }
+}
+function counts(values) {
+    const result = new Map();
+    for (const value of values.filter(Boolean)) {
+        result.set(value, (result.get(value) ?? 0) + 1);
+    }
+    return [...result.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+function packageScripts(content) {
+    try {
+        const scripts = JSON.parse(content).scripts;
+        return scripts
+            ? Object.entries(scripts).map(([name, command]) => [
+                name,
+                String(command),
+            ])
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function markdownSections(content) {
+    const sections = [];
+    let heading = "";
+    let lines = [];
+    const flush = () => {
+        const summary = lines
+            .join(" ")
+            .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+            .replace(/https?:\/\/\S+/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (heading && summary) {
+            sections.push([heading, summary]);
+        }
+    };
+    for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^#{1,3}\s+(.+)$/);
+        if (match) {
+            flush();
+            heading = match[1].trim();
+            lines = [];
+        }
+        else if (heading && line.trim() && !line.trim().startsWith("```")) {
+            lines.push(line.trim());
+        }
+    }
+    flush();
+    return sections;
+}
+function cargoPackage(content) {
+    return content.match(/^\s*name\s*=\s*"([^"]+)"/m)?.[1];
+}
+function sourceModuleClaim(path, content) {
+    const symbols = [
+        ...content.matchAll(/\b(?:pub\s+)?(?:struct|enum|trait|fn|function|class|interface|type|func|def|const)\s+([A-Za-z_]\w*)|\bexport\s+(?:default\s+)?(?:function|class|const|interface|type)\s+([A-Za-z_]\w*)/g),
+    ]
+        .map((match) => match[1] ?? match[2])
+        .filter(Boolean)
+        .slice(0, 8);
+    if (!symbols.length)
+        return undefined;
+    return `\`${path}\` contains ${symbols
+        .map((symbol) => `\`${symbol}\``)
+        .join(", ")}; keep related changes in this module.`;
+}
+function commandPrefix(source) {
+    if (source.tree.some((path) => /pnpm-lock\.yaml$/.test(path)))
+        return "pnpm";
+    if (source.tree.some((path) => /yarn\.lock$/.test(path)))
+        return "yarn";
+    if (source.tree.some((path) => /bun\.lockb?$/.test(path)))
+        return "bun";
+    if (source.tree.some((path) => /deno\.json(?:c)?$/.test(path))) {
+        return "deno task";
+    }
+    if (source.tree.some((path) => /Cargo\.toml$/.test(path)))
+        return "cargo";
+    if (source.tree.some((path) => /Makefile$|makefile$/i.test(path))) {
+        return "make";
+    }
+    return "npm run";
+}
+function sanitizeDocumentBody(body, source) {
+    const paths = new Set([...source.tree, ...Object.keys(source.files)]);
+    const repositoryName = String(source.repo.full_name ?? "");
+    const known = (reference) => {
+        if (reference.startsWith("@") || reference === repositoryName)
+            return true;
+        const normalized = reference.replace(/^\.\/+/, "").replace(/\/+$/, "");
+        const wildcard = normalized.includes("*")
+            ? new RegExp(`^${normalized
+                .split("*")
+                .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+                .join(".*")}$`)
+            : undefined;
+        return (paths.has(normalized) ||
+            [...paths].some((path) => wildcard ? wildcard.test(path) : path.startsWith(`${normalized}/`)));
+    };
+    return body
+        .replace(/`([^`\n]+\/[^`\n]+)`/g, (whole, reference) => known(reference) ? whole : "")
+        .replace(/(?:^|[\s("'`])((?!@)[A-Za-z0-9_.-]+\/[A-Za-z0-9_.*?{}<>:+-]+(?:\/[A-Za-z0-9_.*?{}<>:+-]+)*)/g, (whole, reference) => known(reference) ? whole : whole.replace(reference, ""));
+}
+export function extractFacts(source, options) {
+    const facts = new Map();
+    const fullName = String(source.repo.full_name ?? "");
+    const branch = String(source.repo.default_branch ?? "main");
+    add(facts, fact("identity", `Work in ${fullName} on the \`${branch}\` default branch.`, "repository metadata", 3));
+    const directories = [
+        ...new Set(source.tree
+            .map((path) => path.split("/")[0])
+            .filter((path) => path &&
+            !path.includes(".") &&
+            !/^(test|tests|spec|__tests__)$/i.test(path))),
+    ].sort();
+    if (directories.length) {
+        add(facts, fact("layout", `Top-level directories include ${directories
+            .slice(0, 12)
+            .map((dir) => `\`${dir}/\``)
+            .join(", ")}.`, "repository tree", 2));
+    }
+    const testRoots = [
+        ...new Set(source.tree
+            .map((path) => path.split("/")[0])
+            .filter((root) => /^(test|tests|spec|__tests__)$/i.test(root))),
+    ];
+    if (testRoots.length) {
+        add(facts, fact("tests", `Repository tests live under ${testRoots.map((root) => `\`${root}/\``).join(", ")}.`, "repository tree", 3));
+    }
+    const workflows = source.tree.filter((path) => /^\.github\/workflows\/.+\.(yml|yaml)$/i.test(path));
+    if (workflows.length) {
+        add(facts, fact("ship", `CI workflows are defined in ${workflows.map((path) => `\`${path}\``).join(", ")}.`, "repository tree", 3));
+    }
+    if (source.tree.some((path) => /^\.github\/workflows\/.+release.+\.(yml|yaml)$/i.test(path) ||
+        /(^|\/)(changesets|release-please|\.releaserc)/i.test(path))) {
+        add(facts, fact("ship", "The repository contains an explicit release workflow or release configuration.", "release files", 3));
+    }
+    const seenScripts = new Set();
+    for (const [path, content] of Object.entries(source.files)) {
+        // Anchored at any path segment, not just the repository root: a Cargo
+        // workspace nests each crate's source under `<crate>/src/...`, and this
+        // very repository's own `packages/<pkg>/src/...` layout is the same
+        // shape. A root-only anchor silently produced zero layout facts for both.
+        if (/(?:^|\/)(?:src|lib|app|cmd)\//i.test(path)) {
+            const claim = sourceModuleClaim(path, content);
+            if (claim)
+                add(facts, fact("layout", claim, path, 3));
+        }
+        if (/^README\.md$/i.test(path) || /CONTRIBUTING/i.test(path)) {
+            for (const [heading, body] of markdownSections(content)) {
+                const isReadme = /^README\.md$/i.test(path);
+                const relevant = isReadme
+                    ? /usage|run|develop|build|test|contribut|release/i.test(heading)
+                    : /install|setup|usage|run|develop|build|test|contribut|release/i.test(heading);
+                if (!relevant) {
+                    continue;
+                }
+                add(facts, fact("devloop", `README ${heading}: ${sanitizeDocumentBody(body, source).slice(0, 260)}${body.length > 260 ? "…" : ""}`, path, 3));
+            }
+        }
+        if (/^Cargo\.toml$/i.test(path)) {
+            const packageName = cargoPackage(content);
+            add(facts, fact("identity", `This is a Rust Cargo project${packageName ? ` named \`${packageName}\`` : ""}.`, path, 4));
+            add(facts, fact("tests", "Run the Rust test suite with `cargo test`.", path, 3));
+        }
+        if (/^CHANGELOG\.md$/i.test(path)) {
+            add(facts, fact("ship", "Release notes are maintained in `CHANGELOG.md`.", path, 3));
+        }
+        if (/PULL_REQUEST_TEMPLATE/i.test(path)) {
+            add(facts, fact("title-body", `Use the pull request template at \`${path}\`.`, path, 4));
+            const headings = [...content.matchAll(/^#{1,3}\s+(.+)$/gm)]
+                .map((match) => match[1].trim())
+                .slice(0, 12);
+            if (headings.length) {
+                add(facts, fact("title-body", `The pull request template asks for: ${headings
+                    .map((heading) => `**${heading}**`)
+                    .join(", ")}.`, path, 4));
+            }
+        }
+        for (const [name, command] of path.endsWith("package.json")
+            ? packageScripts(content)
+            : []) {
+            const rootScript = path === "package.json";
+            const usefulWorkspaceScript = /test|lint|check|type|build|load|compare/i.test(name);
+            if (!rootScript && !usefulWorkspaceScript)
+                continue;
+            const cleanCommand = sanitizeDocumentBody(command, source)
+                .replace(/\s+/g, " ")
+                .trim();
+            if (!cleanCommand)
+                continue;
+            const scriptKey = `${name}:${command}`;
+            if (seenScripts.has(scriptKey))
+                continue;
+            seenScripts.add(scriptKey);
+            const section = /test|lint|check|type/i.test(name)
+                ? "tests"
+                : /build|dev|start|format/i.test(name)
+                    ? "devloop"
+                    : "ship";
+            add(facts, fact(section, `Use \`${commandPrefix(source)} ${name}\` for ${cleanCommand}.`, path, 2));
+        }
+        if (/^\.github\/workflows\//.test(path)) {
+            const jobsBlock = content.match(/^jobs:\s*\n([\s\S]*?)(?=^[^\s]|\s*$)/m)?.[1] ?? "";
+            const jobs = [...jobsBlock.matchAll(/^\s{2}([A-Za-z0-9_-]+):\s*$/gm)]
+                .map((match) => match[1])
+                .slice(0, 20);
+            if (jobs.length) {
+                add(facts, fact("ship", `Workflow \`${path}\` defines jobs: ${jobs.map((job) => `\`${job}\``).join(", ")}.`, path, 2));
+            }
+            if (/\bon:\s*[\s\S]{0,200}\bpull_request\b/.test(content)) {
+                add(facts, fact("ship", `Changes targeting pull requests run \`${path}\`.`, path, 3));
+            }
+            if (/\bpush:\s*\n\s+branches:\s*\n\s+-\s*main\b/.test(content)) {
+                add(facts, fact("ship", `The release workflow runs when \`main\` receives a push.`, path, 4));
+            }
+            if (/runs-on:\s*windows-latest/i.test(content)) {
+                add(facts, fact("ship", `Release builds run on \`windows-latest\`.`, path, 3));
+            }
+            if (/cargo\s+build\s+--release/.test(content)) {
+                add(facts, fact("ship", "The release pipeline builds the Rust binary with `cargo build --release`.", path, 4));
+            }
+            if (/gh\s+release\s+create/.test(content)) {
+                add(facts, fact("ship", "Publishing uses `gh release create` with a generated version tag and `CHANGELOG.md` notes.", path, 4));
+            }
+            if (/Cargo\.toml/.test(content) && /version\s*=/i.test(content)) {
+                add(facts, fact("ship", "The release tag is derived from the version in `Cargo.toml`.", path, 4));
+            }
+        }
+        if (/CONTRIBUTING/i.test(path)) {
+            add(facts, fact("devloop", `Follow repository contribution guidance in \`${path}\`.`, path, 4));
+        }
+    }
+    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));
+        const labels = counts(source.pullRequests.flatMap((pr) => pr.labels))
+            .slice(0, 12)
+            .map(([label, count]) => `\`${label}\` (${count})`);
+        if (labels.length) {
+            add(facts, fact("labels", `Common pull request labels are ${labels.join(", ")}.`, "pull request labels", 2));
+        }
+        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));
+        }
+        const reviewText = source.pullRequests
+            .flatMap((pr) => [...pr.comments, ...pr.reviews])
+            .join("\n")
+            .toLowerCase();
+        for (const [term, instruction] of [
+            ["test", "Include or update tests when behavior changes."],
+            [
+                "changelog",
+                "Update the changelog when the repository process requires it.",
+            ],
+            ["documentation", "Update documentation when public behavior changes."],
+            ["type", "Keep types and type-checking valid before review."],
+        ]) {
+            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));
+            }
+        }
+        if (source.pullRequests.some((pr) => pr.additions + pr.deletions > 1000)) {
+            add(facts, fact("review-bar", "Keep large changes focused and explain their risk and verification in the pull request.", "pull request change sizes", 2));
+        }
+    }
+    if (source.commits.length) {
+        const conventional = source.commits.filter((commit) => /^(feat|fix|docs|refactor|test|build|ci|chore|perf|style)(\(.+\))?!?:\s/i.test(String(commit.commit?.message ?? ""))).length;
+        if (conventional / source.commits.length >= 0.6) {
+            add(facts, fact("style", "Use conventional commit prefixes when creating commits.", "commit history", 3));
+        }
+        const examples = source.commits
+            .slice(0, 8)
+            .map((commit) => String(commit.commit?.message ?? "").split("\n")[0])
+            .filter(Boolean);
+        if (examples.length) {
+            add(facts, fact("style", `Recent commit examples: ${examples
+                .map((message) => `\`${message.slice(0, 100)}\``)
+                .join("; ")}.`, "commit history", 2));
+        }
+    }
+    if (options.includePullRequestChanges &&
+        source.pullRequests.some((pr) => pr.changedFiles.length)) {
+        const files = counts(source.pullRequests.flatMap((pr) => pr.changedFiles)).slice(0, 10);
+        add(facts, fact("review-bar", `Frequently changed files include ${files
+            .map(([path]) => `\`${path}\``)
+            .join(", ")}; check nearby tests and workflows before editing.`, "pull request files", 2));
+    }
+    return [...facts.values()];
+}

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

@@ -0,0 +1,6 @@
+import type { Fact } from "./types.ts";
+export type ReviewDocuments = {
+    guide: string;
+    detailed?: string;
+};
+export declare function buildReviewDocuments(facts: Fact[]): ReviewDocuments | undefined;

package/dist/src/knowledge/guide.js

@@ -0,0 +1,82 @@
+function reviewFacts(facts) {
+    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) => {
+        const key = item.claim.toLowerCase().replace(/\W+/g, " ").trim();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function detailedDocument(facts) {
+    const bullets = facts.flatMap((fact) => {
+        const claim = fact.claim.replace(/\bPR\s*#?\s*\d+\b/gi, "the change");
+        const lower = claim.toLowerCase();
+        const category = lower.includes("test")
+            ? "Missing or insufficient tests"
+            : lower.includes("type")
+                ? "Type and static validation"
+                : lower.includes("documentation")
+                    ? "Missing documentation"
+                    : lower.includes("changelog")
+                        ? "Release-note completeness"
+                        : lower.includes("large") || lower.includes("focused")
+                            ? "Unfocused or risky scope"
+                            : "Repository-specific review expectation";
+        return [
+            `### ${category}`,
+            `- Violation to avoid: ${claim}`,
+            "- Inspect the affected implementation, nearby tests, and related workflow before requesting review.",
+            "- Apply this check whenever a change touches the same behavior or integration boundary.",
+        ];
+    });
+    return `# Detailed PR review guide
+
+This file is a code-review checklist derived from recurring change requests.
+Use it while inspecting the codebase and before opening a pull request.
+It describes failure patterns to look for, not historical pull requests.
+
+## Code-level checks
+
+${bullets.join("\n")}
+`;
+}
+export function buildReviewDocuments(facts) {
+    const selected = reviewFacts(facts);
+    if (selected.length <= 2)
+        return undefined;
+    const detailed = detailedDocument(selected.slice(0, 120));
+    const detailedLines = detailed.trimEnd().split("\n").length;
+    if (detailedLines <= 100) {
+        return {
+            guide: `# PR review guide
+
+Use this checklist before requesting review. These expectations occurred in
+more than two selected pull-request review signals.
+
+## Before requesting review
+
+${selected.map((fact) => `- ${fact.claim}`).join("\n")}
+`,
+        };
+    }
+    return {
+        guide: `# PR review guide
+
+Use this file as the short checklist before requesting review. The detailed
+code-level checks are in [PR_REVIEW_DETAILED_GUIDE.md](PR_REVIEW_DETAILED_GUIDE.md).
+
+## Workflow
+
+- Inspect the detailed checks that match the files and behavior being changed.
+- Run the applicable tests and validation before requesting review.
+- Treat the detailed checks as preventive guidance, not as a list of past PRs.
+`,
+        detailed,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { Json } from "../types.ts";
+export type ProbeResult = {
+    includePullRequests: boolean;
+    includePullRequestChanges: boolean;
+    includeCommitHistory: boolean;
+    maxPrMonths?: number;
+    maxCommits?: number;
+    maxPullRequestChangeLines?: number;
+    report: Json;
+    reasons: string[];
+};
+export declare function analyzeProbe(meta: Json, pulls: Json[], detailSamples: Json[], commits: Json[]): ProbeResult;