feat(maintainers): add settings preview diagnostics

CHANGELOG.md

@@ -53,6 +53,8 @@
 
 - Add deterministic base-agent orchestrator (#14)
 
+- Add settings preview diagnostics
+
 
 
 ### Fixes

src/api/routes.ts

@@ -101,6 +101,7 @@ import {
 import { attachDataQuality, buildCoreSignalFidelity, buildRepoDataQuality, buildSignalFidelity } from "../signals/data-quality";
 import { buildPullRequestReviewability } from "../signals/reward-risk";
 import { buildLocalBranchAnalysis } from "../signals/local-branch";
+import { buildRepoSettingsPreview } from "../signals/settings-preview";
 import type { ContributorEvidenceRecord, JobMessage, JsonValue, RepoSyncSegmentRecord } from "../types";
 import { errorMessage, nowIso } from "../utils/json";
 
@@ -254,6 +255,21 @@ const repositorySettingsSchema = z.object({
   privateTrustEnabled: z.boolean().default(true),
 });
 
+const settingsPreviewSchema = z.object({
+  sample: z
+    .object({
+      authorLogin: z.string().trim().min(1).max(100).optional(),
+      authorType: z.enum(["User", "Bot"]).optional(),
+      authorAssociation: z.enum(["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIMER", "FIRST_TIME_CONTRIBUTOR", "MANNEQUIN", "NONE"]).optional(),
+      minerStatus: z.enum(["confirmed", "not_found", "unavailable"]).optional(),
+      title: z.string().max(300).optional(),
+      body: z.string().max(10000).nullable().optional(),
+      labels: z.array(z.string().max(100)).max(50).optional(),
+      linkedIssues: z.array(z.number().int().positive()).max(50).optional(),
+    })
+    .optional(),
+});
+
 export function createApp() {
   const app = new Hono<AppBindings>();
   app.use(
@@ -558,6 +574,42 @@ export function createApp() {
     return c.json(await getRepositorySettings(c.env, fullName));
   });
 
+  app.post("/v1/repos/:owner/:repo/settings-preview", async (c) => {
+    const fullName = `${c.req.param("owner")}/${c.req.param("repo")}`;
+    const body = (await c.req.json().catch(() => null)) ?? {};
+    const parsed = settingsPreviewSchema.safeParse(body);
+    if (!parsed.success) return c.json({ error: "invalid_settings_preview_request", issues: parsed.error.issues }, 400);
+    const [repo, settings, issues, pullRequests] = await Promise.all([
+      getRepository(c.env, fullName),
+      getRepositorySettings(c.env, fullName),
+      listIssues(c.env, fullName),
+      listPullRequests(c.env, fullName),
+    ]);
+    const installationId = repo?.installationId ?? null;
+    const healthRecord = installationId !== null ? await getInstallationHealth(c.env, installationId) : null;
+    const enriched = healthRecord ? enrichInstallationHealth(healthRecord) : null;
+    const installation = enriched
+      ? {
+          installationId: enriched.installationId,
+          status: enriched.status,
+          missingPermissions: enriched.missingPermissions,
+          missingEvents: enriched.missingEvents,
+          permissionRemediation: enriched.permissionRemediation,
+        }
+      : null;
+    return c.json(
+      buildRepoSettingsPreview({
+        repoFullName: fullName,
+        repo,
+        settings,
+        installation,
+        issues,
+        pullRequests,
+        sample: parsed.data.sample ?? {},
+      }),
+    );
+  });
+
   app.get("/v1/repos/:owner/:repo/pulls/:number/maintainer-packet", async (c) => {
     const fullName = `${c.req.param("owner")}/${c.req.param("repo")}`;
     const number = Number(c.req.param("number"));

src/openapi/schemas.ts

@@ -449,6 +449,71 @@ export const RepositorySettingsSchema = z
   })
   .openapi("RepositorySettings");
 
+export const RepoSettingsPreviewSchema = z
+  .object({
+    repoFullName: z.string(),
+    generatedAt: z.string(),
+    settings: z.object({
+      publicSurface: z.enum(["off", "comment_and_label", "comment_only", "label_only"]),
+      commentMode: z.enum(["off", "detected_contributors_only", "all_prs"]),
+      publicSignalLevel: z.enum(["minimal", "standard"]),
+      checkRunMode: z.enum(["off", "enabled"]),
+      checkRunDetailLevel: z.enum(["minimal", "standard", "deep"]),
+      autoLabelEnabled: z.boolean(),
+      gittensorLabel: z.string(),
+      createMissingLabel: z.boolean(),
+      includeMaintainerAuthors: z.boolean(),
+      requireLinkedIssue: z.boolean(),
+    }),
+    installation: z
+      .object({
+        installationId: z.number(),
+        status: z.enum(["healthy", "needs_attention", "broken"]),
+        missingPermissions: z.array(z.string()),
+        missingEvents: z.array(z.string()),
+        permissionRemediation: z.array(
+          z.object({
+            permission: z.string(),
+            requiredAccess: z.string(),
+            currentAccess: z.string(),
+            ok: z.boolean(),
+            action: z.string(),
+          }),
+        ),
+      })
+      .nullable(),
+    sample: z.object({
+      authorLogin: z.string(),
+      authorType: z.string(),
+      authorAssociation: z.string(),
+      minerStatus: z.enum(["confirmed", "not_found", "unavailable"]),
+      title: z.string(),
+      labels: z.array(z.string()),
+      linkedIssues: z.array(z.number()),
+    }),
+    decision: z.object({
+      willComment: z.boolean(),
+      willLabel: z.boolean(),
+      willCheckRun: z.boolean(),
+      skipped: z.boolean(),
+      skipReason: z.enum(["surface_off", "missing_author", "bot_author", "maintainer_author", "miner_detection_unavailable", "not_official_gittensor_miner"]).nullable(),
+      actions: z.array(z.enum(["skip", "comment", "label", "check_run", "none"])),
+      summary: z.string(),
+    }),
+    previewComment: z.string().nullable(),
+    appliedLabel: z.string().nullable(),
+    checkRun: z
+      .object({
+        willCreate: z.boolean(),
+        title: z.string(),
+        detailLevel: z.enum(["minimal", "standard", "deep"]),
+      })
+      .nullable(),
+    warnings: z.array(z.string()),
+    summary: z.string(),
+  })
+  .openapi("RepoSettingsPreview");
+
 export const RepoSyncStateSchema = z
   .object({
     repoFullName: z.string(),

src/openapi/spec.ts

@@ -51,6 +51,7 @@ import {
   GitHubRateLimitObservationSchema,
   RepoSyncSegmentSchema,
   RepoSyncStateSchema,
+  RepoSettingsPreviewSchema,
   RepositorySchema,
   RepositorySettingsSchema,
   RoleContextSchema,
@@ -99,6 +100,7 @@ export function buildOpenApiSpec() {
   registry.register("Bounty", BountySchema);
   registry.register("BountyAdvisory", BountyAdvisorySchema);
   registry.register("RepositorySettings", RepositorySettingsSchema);
+  registry.register("RepoSettingsPreview", RepoSettingsPreviewSchema);
   registry.register("AgentRun", AgentRunSchema);
   registry.register("AgentAction", AgentActionSchema);
   registry.register("AgentContextSnapshot", AgentContextSnapshotSchema);
@@ -242,6 +244,14 @@ export function buildOpenApiSpec() {
       200: { description: "Gittensory repository automation settings", content: { "application/json": { schema: RepositorySettingsSchema } } },
     },
   });
+  registry.registerPath({
+    method: "post",
+    path: "/v1/repos/{owner}/{repo}/settings-preview",
+    responses: {
+      200: { description: "Maintainer dry-run preview of the public surface decision for a sample PR (no GitHub mutation)", content: { "application/json": { schema: RepoSettingsPreviewSchema } } },
+      400: { description: "Invalid settings preview request" },
+    },
+  });
   registry.registerPath({
     method: "get",
     path: "/v1/repos/{owner}/{repo}/pulls/{number}/maintainer-packet",

src/queue/processors.ts

@@ -76,6 +76,7 @@ import {
   buildQueueHealth,
   detectGittensorContributor,
 } from "../signals/engine";
+import { decidePublicSurface } from "../signals/settings-preview";
 import type { ContributorEvidenceRecord, GitHubWebhookPayload, JobMessage, JsonValue } from "../types";
 import { errorMessage } from "../utils/json";
 
@@ -520,20 +521,21 @@ async function maybePublishPrPublicSurface(
   advisory: Awaited<ReturnType<typeof buildPullRequestAdvisory>>,
   webhook: { deliveryId: string; authorType?: string | undefined },
 ): Promise<void> {
-  if (!hasVisiblePrSurface(settings)) return;
-  const author = pr.authorLogin;
-  if (!author) {
-    await auditPrVisibilitySkip(env, repoFullName, pr.number, null, "missing_author", webhook.deliveryId);
-    return;
-  }
-  if (webhook.authorType === "Bot" || /\[bot\]$/i.test(author)) {
-    await auditPrVisibilitySkip(env, repoFullName, pr.number, author, "bot_author", webhook.deliveryId);
-    return;
-  }
-  if (!settings.includeMaintainerAuthors && pr.authorAssociation && ["OWNER", "MEMBER", "COLLABORATOR"].includes(pr.authorAssociation)) {
-    await auditPrVisibilitySkip(env, repoFullName, pr.number, author, "maintainer_author", webhook.deliveryId);
+  const author = pr.authorLogin ?? null;
+  // Cheap, network-free skip checks (also avoids the miner lookup when it would be wasted).
+  const prelim = decidePublicSurface({
+    settings,
+    authorLogin: author,
+    authorType: webhook.authorType ?? null,
+    authorAssociation: pr.authorAssociation ?? null,
+    minerStatus: "not_checked",
+  });
+  if (prelim.skipped) {
+    if (prelim.skipReason === "surface_off") return;
+    await auditPrVisibilitySkip(env, repoFullName, pr.number, author, prelim.skipReason ?? "skipped", webhook.deliveryId);
     return;
   }
+  if (!author) return;
 
   const official = await fetchOfficialGittensorMiner(author);
   if (official.status === "unavailable") {
@@ -547,10 +549,17 @@ async function maybePublishPrPublicSurface(
     });
     return;
   }
-  if (official.status === "not_found") {
+  if (official.status !== "confirmed") {
     await auditPrVisibilitySkip(env, repoFullName, pr.number, author, "not_official_gittensor_miner", webhook.deliveryId);
     return;
   }
+  const decision = decidePublicSurface({
+    settings,
+    authorLogin: author,
+    authorType: webhook.authorType ?? null,
+    authorAssociation: pr.authorAssociation ?? null,
+    minerStatus: "confirmed",
+  });
 
   const [contributorPullRequests, contributorIssues, repoIssues, repoPullRequests, github, cachedRepoStats] = await Promise.all([
     listContributorPullRequests(env, author),
@@ -580,7 +589,7 @@ async function maybePublishPrPublicSurface(
     repoIssues,
     repoPullRequests,
   );
-  if (shouldPublishPrComment(settings)) {
+  if (decision.willComment) {
     const body = buildPublicPrIntelligenceComment({
       repo,
       pr,
@@ -593,12 +602,12 @@ async function maybePublishPrPublicSurface(
     });
     await createOrUpdatePrIntelligenceComment(env, installationId, repoFullName, pr.number, body);
   }
-  if (shouldApplyPrLabel(settings)) {
+  if (decision.willLabel) {
     await ensurePullRequestLabel(env, installationId, repoFullName, pr.number, settings.gittensorLabel, {
       createMissingLabel: settings.createMissingLabel,
     });
   }
-  if (settings.checkRunMode === "enabled" && advisory.headSha) {
+  if (decision.willCheckRun && advisory.headSha) {
     await createOrUpdateCheckRun(env, installationId, repoFullName, {
       ...advisory,
       conclusion: "success",
@@ -616,7 +625,7 @@ async function maybePublishPrPublicSurface(
     metadata: {
       deliveryId: webhook.deliveryId,
       publicSurface: settings.publicSurface,
-      label: shouldApplyPrLabel(settings) ? settings.gittensorLabel : null,
+      label: decision.willLabel ? settings.gittensorLabel : null,
       checkRunMode: settings.checkRunMode,
     },
   });
@@ -716,19 +725,6 @@ async function maybeProcessGittensoryMentionCommand(env: Env, deliveryId: string
   return true;
 }
 
-function hasVisiblePrSurface(settings: Awaited<ReturnType<typeof getRepositorySettings>>): boolean {
-  return settings.publicSurface !== "off" || settings.checkRunMode === "enabled";
-}
-
-function shouldPublishPrComment(settings: Awaited<ReturnType<typeof getRepositorySettings>>): boolean {
-  if (settings.commentMode === "off") return false;
-  return settings.publicSurface === "comment_and_label" || settings.publicSurface === "comment_only";
-}
-
-function shouldApplyPrLabel(settings: Awaited<ReturnType<typeof getRepositorySettings>>): boolean {
-  return settings.autoLabelEnabled && (settings.publicSurface === "comment_and_label" || settings.publicSurface === "label_only");
-}
-
 async function auditPrVisibilitySkip(
   env: Env,
   repoFullName: string,