delivery-friction-analyzer 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.26.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,22 @@
 
 ## 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.
+- Why it matters: First-time users and maintainers get the blocking self-analysis decision before answering unrelated setup questions, while PR class setup stays easier to answer without losing the guidance needed to avoid misleading classifications.
+- Who is affected: Users running `--interactive` live GitHub setup, especially when they enter the analyzer's own repository or review the optional Conventional Commit PR class preset.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/74
+
 ### 2026-07-04 — Local Sample Checkout Command
 
 - What changed: Local checkouts now expose `npm run sample` for the bundled tutorial sample, while README guidance keeps the public `npx` package path first and shows checkout usage separately.

package/src/cli/analyze-github.js

@@ -38,7 +38,8 @@ const PACKAGE_JSON_URL = new URL("../../package.json", import.meta.url);
 const SAMPLE_SOURCE_BUNDLE_URL = new URL("../../examples/tutorial/source-bundle.json", import.meta.url);
 const SAMPLE_PROFILE_URL = new URL("../../examples/tutorial/profile.json", import.meta.url);
 const STARTER_PROFILE_PROMPT_COPY = "Starter profiles are valid, but until you add rules the report may classify PR classes, file roles, and functional surfaces as unknown.";
-const CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY = "Add Conventional Commit PR class rules?\nUse this when PR titles usually start with feat:, fix:, docs:, test:, chore(deps):, or similar prefixes.\nIt writes title-based dependency, feature, fix, docs, test, and maintenance classes so fewer PRs are classified as unknown.\nSkip it for release titles, ticket prefixes, free-form titles, or another custom PR taxonomy.\nIt does not change scoring, rankings, GitHub collection, or CSV export shape.";
+const CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY = "Add Conventional Commit PR class rules? Use this only when PR titles usually start with prefixes like feat:, fix:, docs:, test:, or chore(deps):.";
+const CONVENTIONAL_COMMIT_PRESET_HELP_COPY = "Writes title-based dependency, feature, fix, docs, test, and maintenance PR class rules to the repository profile. Accept only when most PR titles use Conventional Commit prefixes such as feat:, fix:, docs:, test:, or chore(deps):. Skip for release titles, ticket prefixes, free-form titles, or another custom PR taxonomy. Existing PR class rules are kept. This changes profile interpretation only; it does not change scoring, rankings, GitHub collection, or CSV export shape.";
 const STARTER_PROFILE_COMPLETION_COPY = "Created a starter profile. Review or refine it before relying on report labels for PR classes, file roles, or functional surfaces.";
 const MISSING_PROFILE_GUIDANCE = `Live GitHub analysis needs a repository-profile.v1 JSON file.
 Run with --interactive to create a starter profile, or pass --profile path/to/profile.json.
@@ -1058,15 +1059,11 @@ function withAvailablePrClassRuleIds(profile, rules) {
 }
 
 async function promptConventionalCommitPrClassPreset(promptAdapter, output, profile) {
-  const hasExistingPrClasses = Array.isArray(profile.prClasses) && profile.prClasses.length > 0;
-  const message = hasExistingPrClasses
-    ? `${CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY} Existing PR class rules will be kept.`
-    : CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY;
   const shouldAddPreset = await askUntilValid(promptAdapter, {
     id: "addConventionalCommitPrClasses",
     type: "confirm",
-    message,
-    help: "Optional profile setup: add reusable title rules when Conventional Commit prefixes match this repository. This changes profile classification only, not scoring or GitHub collection.",
+    message: CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY,
+    help: CONVENTIONAL_COMMIT_PRESET_HELP_COPY,
     defaultValue: false,
   }, {
     output,
@@ -1318,6 +1315,13 @@ function shouldPromptInteractiveOption(options, key) {
   return !hasOwnOption(options, key);
 }
 
+function rejectInteractiveProductRepository(repository, { productRepository, allowProductRepository = false } = {}) {
+  const targetInput = targetInputFromRepositorySlug(repository);
+  if (!allowProductRepository && isProductRepositoryTarget(targetInput, productRepository ?? DEFAULT_PRODUCT_REPOSITORY)) {
+    throw new Error(productRepositoryTargetError(targetInput));
+  }
+}
+
 export async function collectInteractiveAnalyzeGithubOptions(options, {
   promptAdapter = null,
   input = process.stdin,
@@ -1350,6 +1354,10 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
         validate: validateRepositorySlug,
       });
     }
+    rejectInteractiveProductRepository(resolved.repository, {
+      productRepository: options.productRepository,
+      allowProductRepository: options.allowProductRepository,
+    });
 
     if (resolved.limit === undefined) {
       resolved.limit = await askUntilValid(adapter, {
@@ -1860,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,
@@ -1988,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}`
@@ -1997,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(

package/src/contracts/target-repository.js

@@ -103,10 +103,12 @@ export function productRepositoryTargetError(input) {
     : "the requested repository";
   return `Cannot analyze ${repository} because it is this tool's product repository. The guard prevents accidental self-analysis during normal live runs; it is not a data-security boundary.
 
+No GitHub data was collected, and no files were written.
+
 To learn the tool, run the bundled sample:
   delivery-friction-analyzer --source sample --out reports/tutorial
 
 To analyze a different repository, pass --repo owner/name.
 
-If you intentionally want to analyze this product repository, rerun with --allow-product-repository. The CLI will check that required data is readable before writing artifacts. No GitHub data was collected.`;
+If you intentionally want to analyze this product repository, rerun with --allow-product-repository. The CLI will check that required data is readable before writing artifacts.`;
 }