@oss-autopilot/core 3.1.0 → 3.2.0

package/dist/core/pr-comments-fetcher.js

@@ -0,0 +1,125 @@
+import { paginateAll } from './pagination.js';
+import { isBotAuthor } from './comment-utils.js';
+import { parseGitHubUrl } from './urls.js';
+import { ValidationError, errorMessage } from './errors.js';
+import { debug, warn } from './logger.js';
+const MODULE = 'pr-comments-fetcher';
+/** Default concurrency for {@link fetchPRCommentBundlesBatch}. */
+const DEFAULT_BATCH_CONCURRENCY = 3;
+/**
+ * Fetch a single PR's comment bundle. Filters out the authenticated user's
+ * own comments and bots. Throws {@link ValidationError} on a non-PR URL.
+ */
+export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
+    const parsed = parseGitHubUrl(prUrl);
+    if (!parsed || parsed.type !== 'pull') {
+        throw new ValidationError(`Invalid PR URL: ${prUrl}`);
+    }
+    const { owner, repo, number: pull_number } = parsed;
+    const repoFull = `${owner}/${repo}`;
+    // Fetch the PR + all three comment streams in parallel. We always fetch
+    // every page — corpus quality depends on having every reviewer voice, not
+    // just the first 100 comments.
+    const [{ data: pr }, reviews, reviewComments, issueComments] = await Promise.all([
+        octokit.pulls.get({ owner, repo, pull_number }),
+        paginateAll((page) => octokit.pulls.listReviews({
+            owner,
+            repo,
+            pull_number,
+            per_page: 100,
+            page,
+        })),
+        paginateAll((page) => octokit.pulls.listReviewComments({
+            owner,
+            repo,
+            pull_number,
+            per_page: 100,
+            page,
+        })),
+        paginateAll((page) => octokit.issues.listComments({
+            owner,
+            repo,
+            issue_number: pull_number,
+            per_page: 100,
+            page,
+        })),
+    ]);
+    const ownLogin = githubUsername.toLowerCase();
+    /**
+     * Drop entries that aren't useful corpus: the user's own comments, bots,
+     * and entries with no author at all (deleted accounts surface as null
+     * user from GitHub's REST API).
+     */
+    const isWorthKeeping = (login) => {
+        if (!login)
+            return false;
+        if (login.toLowerCase() === ownLogin)
+            return false;
+        if (isBotAuthor(login))
+            return false;
+        return true;
+    };
+    const mergedAt = pr.merged_at ?? pr.closed_at ?? '';
+    return {
+        prUrl,
+        prTitle: pr.title,
+        repo: repoFull,
+        mergedAt,
+        reviews: reviews
+            .filter((r) => isWorthKeeping(r.user?.login))
+            .map((r) => ({
+            author: r.user?.login ?? '',
+            authorAssociation: r.author_association ?? 'NONE',
+            body: r.body ?? '',
+            submittedAt: r.submitted_at ?? '',
+        })),
+        reviewComments: reviewComments
+            .filter((c) => isWorthKeeping(c.user?.login))
+            .map((c) => ({
+            author: c.user?.login ?? '',
+            authorAssociation: c.author_association ?? 'NONE',
+            body: c.body ?? '',
+            path: c.path ?? '',
+            createdAt: c.created_at ?? '',
+        })),
+        issueComments: issueComments
+            .filter((c) => isWorthKeeping(c.user?.login))
+            .map((c) => ({
+            author: c.user?.login ?? '',
+            authorAssociation: c.author_association ?? 'NONE',
+            body: c.body ?? '',
+            createdAt: c.created_at ?? '',
+        })),
+    };
+}
+/**
+ * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
+ *
+ * Failures on individual PRs are logged and skipped — the batch returns a
+ * shorter array rather than aborting. Rationale: extraction quality is
+ * already a partial-information problem (users contribute to many repos and
+ * many PRs), so a single 404 / rate limit on one PR should not deny the
+ * host the corpus from the other 4.
+ */
+export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername, concurrency = DEFAULT_BATCH_CONCURRENCY) {
+    const results = [];
+    const queue = [...prUrls];
+    async function worker() {
+        while (queue.length > 0) {
+            const url = queue.shift();
+            if (!url)
+                return;
+            try {
+                const bundle = await fetchPRCommentBundle(octokit, url, githubUsername);
+                results.push(bundle);
+            }
+            catch (err) {
+                warn(MODULE, `Skipping ${url}: ${errorMessage(err)}`);
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, prUrls.length) }, worker);
+    await Promise.all(workers);
+    debug(MODULE, `Fetched ${results.length}/${prUrls.length} comment bundles`);
+    return results;
+}

package/dist/core/state-persistence.d.ts

@@ -34,6 +34,12 @@ export declare function migrateV1ToV2(rawState: Record<string, unknown>): Record
  * New optional fields are handled by Zod defaults (undefined/optional).
  */
 export declare function migrateV2ToV3(rawState: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Migrate state from v3 to v4 (#867).
+ * Adds: commentsFetchedAt on StoredMergedPR / StoredClosedPR. The new field is
+ * optional, so no data transformation is needed — only the version bump.
+ */
+export declare function migrateV3ToV4(rawState: Record<string, unknown>): Record<string, unknown>;
 /**
  * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.

package/dist/core/state-persistence.js

@@ -158,12 +158,23 @@ export function migrateV2ToV3(rawState) {
     debug(MODULE, 'v2 to v3 migration complete.');
     return rawState;
 }
+/**
+ * Migrate state from v3 to v4 (#867).
+ * Adds: commentsFetchedAt on StoredMergedPR / StoredClosedPR. The new field is
+ * optional, so no data transformation is needed — only the version bump.
+ */
+export function migrateV3ToV4(rawState) {
+    debug(MODULE, 'Migrating state from v3 to v4 (add commentsFetchedAt to stored PR records)...');
+    rawState.version = 4;
+    debug(MODULE, 'v3 to v4 migration complete (no data transformation required).');
+    return rawState;
+}
 /**
  * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export function createFreshState() {
-    return AgentStateSchema.parse({ version: 3 });
+    return AgentStateSchema.parse({ version: 4 });
 }
 /**
  * Migrate state from legacy ./data/ location to ~/.oss-autopilot/.
@@ -273,6 +284,9 @@ function tryRestoreFromBackup() {
                 if (raw.version === 2) {
                     raw = migrateV2ToV3(raw);
                 }
+                if (raw.version === 3) {
+                    raw = migrateV3ToV4(raw);
+                }
             }
             const parsed = AgentStateSchema.safeParse(raw);
             if (parsed.success) {
@@ -313,7 +327,7 @@ export function loadState() {
         if (fs.existsSync(statePath)) {
             const data = fs.readFileSync(statePath, 'utf-8');
             let raw = JSON.parse(data);
-            // Chain migrations: v1 → v2 → v3
+            // Chain migrations: v1 → v2 → v3 → v4
             let wasMigrated = false;
             if (typeof raw === 'object' && raw !== null) {
                 const rawObj = raw;
@@ -325,6 +339,10 @@ export function loadState() {
                     raw = migrateV2ToV3(raw);
                     wasMigrated = true;
                 }
+                if (raw.version === 3) {
+                    raw = migrateV3ToV4(raw);
+                    wasMigrated = true;
+                }
             }
             // Validate through Zod schema (strips unknown keys in memory; stale keys persist on disk until next save)
             const parsed = AgentStateSchema.safeParse(raw);

package/dist/core/state-schema.d.ts

@@ -63,12 +63,14 @@ export declare const StoredMergedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     mergedAt: z.ZodString;
+    commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const StoredClosedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     closedAt: z.ZodString;
+    commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const AnalyzedIssueConversationSchema: z.ZodObject<{
@@ -324,7 +326,7 @@ export declare const DailyDigestSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const AgentStateSchema: z.ZodObject<{
-    version: z.ZodLiteral<3>;
+    version: z.ZodLiteral<4>;
     gistId: z.ZodOptional<z.ZodString>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
@@ -471,12 +473,14 @@ export declare const AgentStateSchema: z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         mergedAt: z.ZodString;
+        commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     closedPRs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         closedAt: z.ZodString;
+        commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     analyzedIssueConversations: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/core/state-schema.js

@@ -44,12 +44,18 @@ export const StoredMergedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     mergedAt: z.string(),
+    /** When the raw review-comment bundle for this PR was last fetched (#867). */
+    commentsFetchedAt: z.string().optional(),
+    /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
     learningsExtractedAt: z.string().optional(),
 });
 export const StoredClosedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
+    /** When the raw review-comment bundle for this PR was last fetched (#867). */
+    commentsFetchedAt: z.string().optional(),
+    /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
     learningsExtractedAt: z.string().optional(),
 });
 export const AnalyzedIssueConversationSchema = z.object({
@@ -211,7 +217,7 @@ export const DailyDigestSchema = z.object({
 });
 // ── 8. Root schema ───────────────────────────────────────────────────
 export const AgentStateSchema = z.object({
-    version: z.literal(3),
+    version: z.literal(4),
     gistId: z.string().optional(),
     repoScores: z.record(z.string(), RepoScoreSchema).default({}),
     config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),

package/dist/core/state.d.ts

@@ -105,6 +105,29 @@ export declare class StateManager {
     isGistMode(): boolean;
     /** Whether the Gist is in degraded mode (using local cache fallback). */
     isGistDegraded(): boolean;
+    /**
+     * Whether per-repo guidelines (#867) are available. True iff the Gist store
+     * is initialized — in local-only mode, guidelines are unavailable and
+     * write operations would throw {@link GuidelinesNotAvailableError}.
+     */
+    isGuidelinesAvailable(): boolean;
+    /**
+     * Read the per-repo guidelines for `repo` (#867). Returns null when in
+     * local mode, when no file exists, or when the file is empty (tombstoned).
+     */
+    getGuidelines(repo: string): string | null;
+    /**
+     * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+     * when content exceeds the byte budget.
+     */
+    setGuidelines(repo: string, content: string): void;
+    /**
+     * Tombstone the guidelines file for `repo` so subsequent reads return null.
+     * Throws when not in Gist mode.
+     */
+    deleteGuidelines(repo: string): void;
+    /** List repos with non-empty guidelines stored in the Gist. */
+    listGuidelinesRepos(): string[];
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -176,6 +199,16 @@ export declare class StateManager {
     };
     /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark(): string | undefined;
+    /**
+     * Stamp `commentsFetchedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRCommentsFetched(url: string, fetchedAt: string): void;
+    /**
+     * Stamp `learningsExtractedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRLearningsExtracted(url: string, extractedAt: string): void;
     /**
      * Merge partial config updates into the current configuration.
      * @param config - Partial config object to merge

package/dist/core/state.js

@@ -10,6 +10,7 @@ import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
 import { errorMessage, ConfigurationError, ConcurrencyError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
+import * as guidelinesStoreModule from './guidelines-store.js';
 import { getStatePath, getStateCachePath } from './paths.js';
 import { parseGitHubUrl } from './urls.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
@@ -274,6 +275,41 @@ export class StateManager {
     isGistDegraded() {
         return this.gistDegraded;
     }
+    /**
+     * Whether per-repo guidelines (#867) are available. True iff the Gist store
+     * is initialized — in local-only mode, guidelines are unavailable and
+     * write operations would throw {@link GuidelinesNotAvailableError}.
+     */
+    isGuidelinesAvailable() {
+        return this.gistStore !== null;
+    }
+    /**
+     * Read the per-repo guidelines for `repo` (#867). Returns null when in
+     * local mode, when no file exists, or when the file is empty (tombstoned).
+     */
+    getGuidelines(repo) {
+        return guidelinesStoreModule.getGuidelines(this.gistStore, repo);
+    }
+    /**
+     * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+     * when content exceeds the byte budget.
+     */
+    setGuidelines(repo, content) {
+        guidelinesStoreModule.setGuidelines(this.gistStore, repo, content);
+        this.autoSave();
+    }
+    /**
+     * Tombstone the guidelines file for `repo` so subsequent reads return null.
+     * Throws when not in Gist mode.
+     */
+    deleteGuidelines(repo) {
+        guidelinesStoreModule.deleteGuidelines(this.gistStore, repo);
+        this.autoSave();
+    }
+    /** List repos with non-empty guidelines stored in the Gist. */
+    listGuidelinesRepos() {
+        return guidelinesStoreModule.listGuidelinesRepos(this.gistStore);
+    }
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -434,6 +470,40 @@ export class StateManager {
     getClosedPRWatermark() {
         return this.state.closedPRs?.[0]?.closedAt || undefined;
     }
+    /**
+     * Stamp `commentsFetchedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRCommentsFetched(url, fetchedAt) {
+        const merged = this.state.mergedPRs?.find((pr) => pr.url === url);
+        if (merged) {
+            merged.commentsFetchedAt = fetchedAt;
+            this.autoSave();
+            return;
+        }
+        const closed = this.state.closedPRs?.find((pr) => pr.url === url);
+        if (closed) {
+            closed.commentsFetchedAt = fetchedAt;
+            this.autoSave();
+        }
+    }
+    /**
+     * Stamp `learningsExtractedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRLearningsExtracted(url, extractedAt) {
+        const merged = this.state.mergedPRs?.find((pr) => pr.url === url);
+        if (merged) {
+            merged.learningsExtractedAt = extractedAt;
+            this.autoSave();
+            return;
+        }
+        const closed = this.state.closedPRs?.find((pr) => pr.url === url);
+        if (closed) {
+            closed.learningsExtractedAt = extractedAt;
+            this.autoSave();
+        }
+    }
     // === Configuration ===
     /**
      * Merge partial config updates into the current configuration.

package/dist/core/types.d.ts

@@ -233,7 +233,7 @@ interface CommentedIssueWithoutResponse extends CommentedIssueBase {
 export type CommentedIssue = CommentedIssueWithResponse | CommentedIssueWithoutResponse;
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export declare const DEFAULT_CONFIG: AgentConfig;
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v4 architecture. */
 export declare const INITIAL_STATE: AgentState;
 export declare const PROJECT_CATEGORIES: ("nonprofit" | "devtools" | "infrastructure" | "web-frameworks" | "data-ml" | "education")[];
 export declare const ISSUE_SCOPES: ("advanced" | "beginner" | "intermediate")[];

package/dist/core/types.js

@@ -12,8 +12,8 @@ export function isBelowMinStars(stargazersCount, minStars) {
 // ── Schema-derived constants ─────────────────────────────────────────
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export const DEFAULT_CONFIG = AgentConfigSchema.parse({});
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
-export const INITIAL_STATE = AgentStateSchema.parse({ version: 3 });
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v4 architecture. */
+export const INITIAL_STATE = AgentStateSchema.parse({ version: 4 });
 // ── Const arrays (derived from Zod schemas for runtime iteration) ────
 export const PROJECT_CATEGORIES = ProjectCategorySchema.options;
 export const ISSUE_SCOPES = IssueScopeSchema.options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {