delivery-friction-analyzer 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### 2026-07-05 — Dry-Run Short-Sample Explanations
+
+- What changed: Live dry-run completion now explains why fewer pull requests were sampled than requested when the analyzer has enough evidence, or says the reason is unknown when it cannot prove the cause.
+- Why it matters: First-time users and maintainers can interpret short coverage probes without assuming the repository has too few eligible PRs, filters were applied, or GitHub data was complete.
+- Who is affected: Users running live GitHub `--dry-run` or `--metadata-only` checks, especially with requested limits larger than the collected sample.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/75
+
 ### 2026-07-04 — Guided Setup Guard Clarity
 
 - What changed: Interactive setup now stops as soon as users enter this tool's product repository, explains that no GitHub data was collected and no files were written, and keeps Conventional Commit PR class setup as a short prompt with detailed `?` help.

package/src/cli/analyze-github.js

@@ -1868,7 +1868,7 @@ export async function runAnalyzeGithub(options, {
       paths: generatedPaths,
       sourceBundle,
       requestedLimit: options.limit,
-      sampledLimit: collectionLimit,
+      sampledLimit: sourceBundle.selection?.collectedCount ?? collectionLimit,
       csv: false,
       analysisFilter: requestedAnalysisFilter(options.excludedPrClasses ?? []),
       savedProfilePath: options.savedProfilePath,
@@ -1996,6 +1996,81 @@ function coverageCaveats(coverage) {
   });
 }
 
+function dryRunCollectedCount(result) {
+  const count = result.selection?.collectedCount;
+  return Number.isInteger(count) ? count : result.sampledLimit;
+}
+
+function relevantShortSampleCoverageStatus(coverage) {
+  const relevantFamilies = new Set([
+    "pull_request_inventory",
+    "pull_request_details",
+    "review_threads",
+    "workflow_runs",
+  ]);
+  const statuses = (coverage?.sourceFamilies ?? []).filter(family => (
+    relevantFamilies.has(family.family)
+    && family.status
+    && family.status !== "available"
+  )).map(family => family.status);
+
+  if (!statuses.length) return null;
+  if (statuses.includes("partial") && statuses.includes("unavailable")) return "incomplete";
+  if (statuses.includes("partial")) return "partial";
+  if (statuses.includes("unavailable")) return "unavailable";
+  return "incomplete";
+}
+
+function pullRequestCountLabel(count) {
+  return count === 1 ? "one pull request" : `${count} pull requests`;
+}
+
+function dryRunShortSampleExplanation(result) {
+  if (!result.dryRun) return null;
+  const requestedCount = result.requestedLimit;
+  const collectedCount = dryRunCollectedCount(result);
+  if (!Number.isInteger(requestedCount)
+    || !Number.isInteger(collectedCount)
+    || collectedCount >= requestedCount) {
+    return null;
+  }
+
+  if (Number.isInteger(result.analysisFilter?.originalPullRequests)
+    && Number.isInteger(result.analysisFilter?.filteredPullRequests)
+    && result.analysisFilter.originalPullRequests >= requestedCount
+    && result.analysisFilter.filteredPullRequests < requestedCount) {
+    return `Sampled ${collectedCount} of ${requestedCount} requested after applying the requested PR class filter.`;
+  }
+
+  if (Number.isInteger(result.selection?.requestedLimit)
+    && Number.isInteger(result.selection?.collectedCount)
+    && result.selection.collectedCount < result.selection.requestedLimit) {
+    return `Sampled ${collectedCount} of ${requestedCount} requested because GitHub returned ${result.selection.collectedCount} merged pull request(s) for this query.`;
+  }
+
+  if (Number.isInteger(result.selection?.requestedLimit)
+    && result.selection.requestedLimit < requestedCount
+    && collectedCount >= result.selection.requestedLimit) {
+    return `Sampled ${collectedCount} of ${requestedCount} requested because dry-run mode intentionally checks ${pullRequestCountLabel(result.selection.requestedLimit)} to verify GitHub access and coverage without writing artifacts.`;
+  }
+
+  const relevantCoverageStatus = relevantShortSampleCoverageStatus(result.collectionCoverage);
+  if (relevantCoverageStatus === "partial") {
+    return `Sampled ${collectedCount} of ${requestedCount} requested. Collection coverage was partial; check the coverage details before treating the sample as complete.`;
+  }
+  if (relevantCoverageStatus === "unavailable") {
+    return `Sampled ${collectedCount} of ${requestedCount} requested. Collection coverage was unavailable for one or more relevant sources; check the coverage details before treating the sample as complete.`;
+  }
+  if (relevantCoverageStatus === "incomplete") {
+    return `Sampled ${collectedCount} of ${requestedCount} requested. Collection coverage was incomplete; check the coverage details before treating the sample as complete.`;
+  }
+
+  const eligiblePullRequests = collectedCount === 1
+    ? "one eligible pull request"
+    : `${collectedCount} eligible pull requests`;
+  return `Sampled ${collectedCount} of ${requestedCount} requested. The analyzer could not determine the reason from available dry-run evidence; check coverage details before assuming the repository has only ${eligiblePullRequests}.`;
+}
+
 export function formatAnalyzeGithubCompletion(result) {
   const target = result.targetRepository?.owner && result.targetRepository?.name
     ? `${result.targetRepository.owner}/${result.targetRepository.name}`
@@ -2005,9 +2080,13 @@ export function formatAnalyzeGithubCompletion(result) {
   if (result.dryRun) {
     lines.push(
       `Dry run complete for ${target}.`,
-      `Sampled pull requests: ${result.sampledLimit} of ${result.requestedLimit} requested.`,
+      `Sampled pull requests: ${dryRunCollectedCount(result)} of ${result.requestedLimit} requested.`,
       "Artifacts: not written.",
     );
+    const shortSampleExplanation = dryRunShortSampleExplanation(result);
+    if (shortSampleExplanation) {
+      lines.push(shortSampleExplanation);
+    }
   } else {
     const paths = result.artifactPaths ?? {};
     lines.push(