Merge pull request #66 from arnabnandy7/feature/maintainerResponsiveness

feat: add maintainer responsiveness analytics

Author: arnabnandy7

README.md

@@ -8,6 +8,7 @@
 - Filters by contributor-friendly label, linked pull requests, and Hacktoberfest readiness
 - Filters by explicit experience, contribution-type, and small-scope signals
 - Scores repository health from maintenance and contributor-activity signals
+- Summarizes maintainer responsiveness from bounded recent contribution samples
 - Sorts and ranks results using issue quality and repository health
 - Keeps successful searches in shareable, browser-navigable URLs
 - Identifies when optional GitHub enrichment is incomplete

db/migrations/0010_maintainer_responsiveness.sql

@@ -0,0 +1 @@
+ALTER TABLE "saved_search" ADD COLUMN "responsiveness" text DEFAULT 'any' NOT NULL;

doc/architecture.md

@@ -70,6 +70,20 @@ flowchart LR
 
 Candidate issues are enriched where possible with repository metadata, recent discussion, assignment state, linked pull requests, and Hacktoberfest signals. Repository health uses recent pushes, open issue and pull-request activity, stars, forks, and issue-tracker availability to distinguish active, moderate, and stale projects. The health score contributes a small optional boost to issue quality ranking and is shown directly on issue cards. The application ranks the enriched results for contributor relevance and returns paginated results to the browser.
 
+Maintainer responsiveness remains separate from repository health. For at most 12
+candidate repositories per search, a cached six-hour GitHub GraphQL request samples
+up to 20 recently updated issues and pull requests from the previous 90 days. The
+summary considers the first response from an owner, member, or collaborator (while
+excluding comments from the issue author), unanswered contributor-friendly issues,
+recent closures, and the external pull-request merge ratio. A responsive status
+requires at least half of sampled external pull requests to be merged when any are
+present; multiple external pull requests with a merge ratio below 25% indicate a
+slow repository. Fewer than four contribution
+samples, missing authentication, repositories outside the bounded batch, and partial
+GitHub failures produce `Unknown`. Responsive repositories receive a five-point
+quality boost and variable repositories receive two points; repository health is
+calculated and displayed independently.
+
 Search responses report repository-metadata, discussion-analysis, and linked-PR
 availability separately. Optional enrichment failures do not discard usable issue
 results; the interface identifies partial data and score explanations omit signals
@@ -85,6 +99,7 @@ Search filters currently include:
 - Any experience, first contribution, beginner, or intermediate
 - Documentation, tests, bug fix, or feature contribution type
 - All scopes or small scope
+- Any, responsive, variable, slow, or unknown maintainer responsiveness
 
 Experience, contribution type, and scope classifications use explicit issue
 labels and structured issue-template fields. Results show the signals that
@@ -185,7 +200,12 @@ observation is explicitly presented as a baseline.
 
 Digest issue links open GitHub directly. Saved-search links include the existing
 filter query parameters; the issue finder reads those parameters and runs the
-linked search on load.
+linked search on load. Weekly recommendations honor the saved responsiveness
+filter and show each repository's status and sample size. Repository-alert
+emails also show the cached responsiveness status, sample period, and
+contributing signals beside each repository. Weekly recommendations display the
+same quality score used to rank results in the portal. Repository alerts remain
+newest-issue notifications and do not assign portal search-quality scores.
 
 Authenticated users can also request their own digest immediately from the
 saved-search card. The manual route uses the same delivery pipeline and six-day

doc/setup.md

@@ -49,6 +49,7 @@ Run the SQL migrations in filename order against the Turso database:
 7. `db/migrations/0007_admin.sql`
 8. `db/migrations/0008_opportunity.sql`
 9. `db/migrations/0009_experience_scope_filters.sql`
+10. `db/migrations/0010_maintainer_responsiveness.sql`
 
 The first migration creates Better Auth's user, session, account, and verification tables. The second creates user-owned saved searches. Migration files intentionally contain structure only—never credentials or production data.
 
@@ -70,6 +71,8 @@ deduplicated opportunity record for each issue a signed-in user saves or opens;
 it does not store the user's GitHub contribution history.
 The ninth adds experience, contribution-type, and scope preferences to cloud
 saved searches. Existing records default to unrestricted filters.
+The tenth adds the optional maintainer-responsiveness preference to cloud saved
+searches. Existing records default to unrestricted responsiveness.
 
 ## GitHub OAuth
 

src/app/api/saved-searches/route.ts

@@ -42,6 +42,7 @@ async function listSavedSearches(userId: string): Promise<SavedSearch[]> {
     experience: row.experience,
     contributionType: row.contributionType,
     scope: row.scope,
+    responsiveness: row.responsiveness,
     createdAt: row.createdAt.toISOString(),
   }));
 }

src/app/api/search/route.ts

@@ -37,6 +37,7 @@ export async function GET(request: Request) {
       experience: searchParams.get("experience"),
       contributionType: searchParams.get("contributionType"),
       scope: searchParams.get("scope"),
+      responsiveness: searchParams.get("responsiveness"),
       page,
     });
 

src/features/issues/components/issue-card.tsx

@@ -22,9 +22,11 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { compactNumber, relativeDate } from "@/features/issues/lib/format";
+import { getResponsivenessBoost } from "@/features/issues/lib/repository-responsiveness";
 import type {
   Issue,
   RepositoryHealth,
+  RepositoryResponsiveness,
 } from "@/features/issues/types/search";
 
 function getQualityBadgeClassName(qualityScore: number) {
@@ -39,6 +41,19 @@ function getQualityBadgeClassName(qualityScore: number) {
   return "bg-rose-500/10 text-rose-700 dark:text-rose-400 border-rose-500/20";
 }
 
+function getResponsivenessClassName(status: RepositoryResponsiveness["status"]) {
+  switch (status) {
+    case "responsive":
+      return "border-emerald-500/20 bg-emerald-500/10 text-emerald-700 dark:text-emerald-400";
+    case "variable":
+      return "border-amber-500/20 bg-amber-500/10 text-amber-700 dark:text-amber-400";
+    case "slow":
+      return "border-rose-500/20 bg-rose-500/10 text-rose-700 dark:text-rose-400";
+    default:
+      return "";
+  }
+}
+
 function getRepositoryHealthClassName(label: RepositoryHealth["label"]) {
   switch (label) {
     case "active":
@@ -87,8 +102,50 @@ function RepositoryHealthTooltip({ issue }: Readonly<{ issue: Issue }>) {
   );
 }
 
+function ResponsivenessTooltip({ issue }: Readonly<{ issue: Issue }>) {
+  const responsiveness = issue.repositoryResponsiveness ?? {
+    status: "unknown" as const,
+    sampleDays: 90,
+    sampleSize: 0,
+    signals: ["Responsiveness sample unavailable"],
+  };
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Badge
+          variant="outline"
+          className={getResponsivenessClassName(responsiveness.status)}
+          tabIndex={0}
+          title={responsiveness.signals.join(" · ")}
+        >
+          <MessageCircle className="h-3 w-3" />
+          {responsiveness.status === "unknown"
+            ? "Response unknown"
+            : `${responsiveness.status} maintainers`}
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="block max-w-sm space-y-2">
+        <p className="font-medium">Maintainer responsiveness</p>
+        <p>
+          Based on {responsiveness.sampleSize} recent contribution samples from
+          the last {responsiveness.sampleDays} days.
+        </p>
+        <ul className="list-disc space-y-1 pl-4">
+          {responsiveness.signals.map((signal) => (
+            <li key={signal}>{signal}</li>
+          ))}
+        </ul>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
 function QualityTooltip({ issue }: Readonly<{ issue: Issue }>) {
   const healthBoost = Math.round((issue.repositoryHealth.score ?? 0) / 10);
+  const responsivenessBoost = getResponsivenessBoost(
+    issue.repositoryResponsiveness?.status ?? "unknown",
+  );
 
   return (
     <Tooltip>
@@ -113,7 +170,8 @@ function QualityTooltip({ issue }: Readonly<{ issue: Issue }>) {
         </p>
         <p>
           Repository health contributes {healthBoost} points. Scores are not
-          percentages.
+          percentages. Maintainer responsiveness contributes {responsivenessBoost}
+          points.
         </p>
         {issue.enrichment?.repositoryMetadata === false ? (
           <p>Repository metadata was unavailable, so its ranking signals were omitted.</p>
@@ -157,6 +215,7 @@ function IssueBadges({ issue }: Readonly<{ issue: Issue }>) {
   return (
     <div className="flex flex-wrap items-center gap-2">
       <RepositoryHealthTooltip issue={issue} />
+      <ResponsivenessTooltip issue={issue} />
       {issue.hacktoberfest ? (
         <Badge className="border-sky-500/20 bg-sky-500/10 text-sky-700 dark:text-sky-400">
           {issue.hacktoberfestSource === "repo-topic"

src/features/issues/components/issue-finder.tsx

@@ -59,6 +59,7 @@ import {
   HACKTOBERFEST_OPTIONS,
   LABEL_OPTIONS,
   LINKED_PR_OPTIONS,
+  RESPONSIVENESS_OPTIONS,
   SORT_OPTIONS,
   SCOPE_OPTIONS,
   TECH_EXAMPLES,
@@ -88,6 +89,7 @@ type SearchFilters = {
   experience: string;
   contributionType: string;
   scope: string;
+  responsiveness: string;
 };
 
 const DEFAULT_SEARCH_FILTERS: SearchFilters = {
@@ -99,6 +101,7 @@ const DEFAULT_SEARCH_FILTERS: SearchFilters = {
   experience: "any",
   contributionType: "any",
   scope: "any",
+  responsiveness: "any",
 };
 
 function getSupportedValue(
@@ -136,6 +139,11 @@ function getSearchFilters(search: string): SearchFilters | null {
       "any",
     ),
     scope: getSupportedValue(params.get("scope"), SCOPE_OPTIONS, "any"),
+    responsiveness: getSupportedValue(
+      params.get("responsiveness"),
+      RESPONSIVENESS_OPTIONS,
+      "any",
+    ),
   };
 }
 
@@ -149,6 +157,7 @@ function createSearchParams(filters: SearchFilters, page?: number) {
     experience: filters.experience,
     contributionType: filters.contributionType,
     scope: filters.scope,
+    responsiveness: filters.responsiveness,
     ...(page ? { page: String(page) } : {}),
   });
 }
@@ -642,6 +651,9 @@ export function IssueFinder() {
     DEFAULT_SEARCH_FILTERS.contributionType,
   );
   const [scope, setScope] = useState(DEFAULT_SEARCH_FILTERS.scope);
+  const [responsiveness, setResponsiveness] = useState(
+    DEFAULT_SEARCH_FILTERS.responsiveness,
+  );
   const [data, setData] = useState<SearchResponse | null>(null);
   const [issues, setIssues] = useState<Issue[]>([]);
   const [page, setPage] = useState(1);
@@ -684,6 +696,7 @@ export function IssueFinder() {
         setExperience(DEFAULT_SEARCH_FILTERS.experience);
         setContributionType(DEFAULT_SEARCH_FILTERS.contributionType);
         setScope(DEFAULT_SEARCH_FILTERS.scope);
+        setResponsiveness(DEFAULT_SEARCH_FILTERS.responsiveness);
         setData(null);
         setIssues([]);
         setError(null);
@@ -700,6 +713,7 @@ export function IssueFinder() {
       setExperience(linkedSearch.experience);
       setContributionType(linkedSearch.contributionType);
       setScope(linkedSearch.scope);
+      setResponsiveness(linkedSearch.responsiveness);
       void searchIssues(undefined, linkedSearch, false);
     }
 
@@ -847,6 +861,12 @@ export function IssueFinder() {
     () => SCOPE_OPTIONS.find((item) => item.value === scope) ?? SCOPE_OPTIONS[0],
     [scope],
   );
+  const selectedResponsiveness = useMemo(
+    () =>
+      RESPONSIVENESS_OPTIONS.find((item) => item.value === responsiveness) ??
+      RESPONSIVENESS_OPTIONS[0],
+    [responsiveness],
+  );
 
   const hasMore = useMemo(() => {
     if (!data) return false;
@@ -876,6 +896,7 @@ export function IssueFinder() {
         experience,
         contributionType,
         scope,
+        responsiveness,
       });
 
       setSavedSearches((current) => [...current, savedSearch]);
@@ -929,6 +950,7 @@ export function IssueFinder() {
     setExperience(savedSearch.experience ?? "any");
     setContributionType(savedSearch.contributionType ?? "any");
     setScope(savedSearch.scope ?? "any");
+    setResponsiveness(savedSearch.responsiveness ?? "any");
 
     void searchIssues(undefined, {
       tech: savedSearch.tech,
@@ -939,6 +961,7 @@ export function IssueFinder() {
       experience: savedSearch.experience ?? "any",
       contributionType: savedSearch.contributionType ?? "any",
       scope: savedSearch.scope ?? "any",
+      responsiveness: savedSearch.responsiveness ?? "any",
     });
   }
 
@@ -1019,6 +1042,8 @@ export function IssueFinder() {
     const searchContributionType =
       searchOverride?.contributionType ?? contributionType;
     const searchScope = searchOverride?.scope ?? scope;
+    const searchResponsiveness =
+      searchOverride?.responsiveness ?? responsiveness;
 
     if (!searchTech.trim()) {
       setError("Enter a technology to search.");
@@ -1041,6 +1066,7 @@ export function IssueFinder() {
       experience: searchExperience,
       contributionType: searchContributionType,
       scope: searchScope,
+      responsiveness: searchResponsiveness,
     });
     const requestId = ++searchRequestId.current;
 
@@ -1099,6 +1125,7 @@ export function IssueFinder() {
         experience,
         contributionType,
         scope,
+        responsiveness,
       },
       nextPage,
     );
@@ -1307,6 +1334,23 @@ export function IssueFinder() {
                 </SelectContent>
               </Select>
 
+              <Select value={responsiveness} onValueChange={setResponsiveness}>
+                <SelectTrigger
+                  className="h-11 w-full"
+                  size="lg"
+                  aria-label="Maintainer responsiveness filter"
+                >
+                  <SelectValue>{selectedResponsiveness.label}</SelectValue>
+                </SelectTrigger>
+                <SelectContent>
+                  {RESPONSIVENESS_OPTIONS.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+
               <Button
                 type="submit"
                 className="h-11 w-full gap-2 sm:col-span-2 lg:col-span-1"
@@ -1342,6 +1386,10 @@ export function IssueFinder() {
               <Metric label="Experience" value={selectedExperience.label} />
               <Metric label="Type" value={selectedContributionType.label} />
               <Metric label="Scope" value={selectedScope.label} />
+              <Metric
+                label="Responsiveness"
+                value={selectedResponsiveness.label}
+              />
               <Metric
                 label="Ranked"
                 value={data ? compactNumber(data.candidateCount) : "-"}

src/features/issues/data/search-options.ts

@@ -119,3 +119,15 @@ export const SCOPE_OPTIONS = [
 export const SCOPE_FILTERS = new Set(
   SCOPE_OPTIONS.map((option) => option.value),
 );
+
+export const RESPONSIVENESS_OPTIONS = [
+  { value: "any", label: "Any responsiveness" },
+  { value: "responsive", label: "Responsive maintainers" },
+  { value: "variable", label: "Variable responsiveness" },
+  { value: "slow", label: "Slow responsiveness" },
+  { value: "unknown", label: "Unknown responsiveness" },
+];
+
+export const RESPONSIVENESS_FILTERS = new Set(
+  RESPONSIVENESS_OPTIONS.map((option) => option.value),
+);