delivery-friction-analyzer 0.19.0 → 0.20.0

package/docs/contracts/target-repository.md

@@ -19,7 +19,13 @@ Schema: `schemas/target-repository.schema.json`. Live analysis selection is late
 
 The validator rejects a target repository that exactly matches the configured product repository. For this repository, the product repository is `hannasdev/delivery-friction-analyzer`; `hannasdev/mcp-writing` is an internal validation target and fixture source.
 
-Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, explains that the guard prevents accidental self-analysis during normal live runs rather than protecting already readable GitHub data, tells you to choose the repository you want to measure with `--repo owner/name`, and confirms that no GitHub data was collected. `--validation-target` only marks output metadata and does not bypass this guard. The product repository identity is repo-local implementation configuration, not a public CLI option.
+Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, explains that the guard prevents accidental self-analysis during normal live runs rather than protecting already readable GitHub data, recommends the bundled sample or another repository first, and confirms that no GitHub data was collected.
+
+`--validation-target` only marks output metadata for internal validation or fixture-source runs. It does not bypass product-repository validation and does not change which repository may be analyzed.
+
+`--allow-product-repository` is an explicit live-analysis override for intentional self-analysis of this product repository. It is not the tutorial path and is rejected in sample mode. When the override is present for the product repository, the CLI must prove required GitHub data is readable before collection or artifact writes. Required preflight reads are repository metadata, pull request inventory, and pull request details for at least one selected merged pull request. Review threads, workflow runs, languages, contributor source, and PR-open diff remain normal coverage families; partial or unavailable optional coverage should be reported as caveats after the required assertion succeeds rather than failing the preflight.
+
+The product repository identity is repo-local implementation configuration, not a general public CLI setting.
 
 ## Degraded Behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.19.0",
+  "version": "0.20.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-06-27 — Product Repository Override
+
+- What changed: Added the explicit `--allow-product-repository` live-analysis override for intentional analysis of this tool's own repository, with required read-access checks before collection or artifact writes.
+- Why it matters: Maintainers can deliberately validate the analyzer against its public product repository without weakening the normal guardrail that steers first-time users toward the bundled sample or another target repository.
+- Who is affected: Maintainers intentionally running self-analysis, and users who hit the product-repository guard during live GitHub setup.
+- Action needed: Use the bundled sample or another repository for normal first-run analysis; add `--allow-product-repository` only for intentional self-analysis after confirming GitHub access.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/63
+
 ### 2026-06-27 — Explicit Sample CLI Source
 
 - What changed: Added explicit `--source sample` CLI routing for the bundled tutorial sample, with sample-first README guidance and live-only option rejection before GitHub collection.

package/src/cli/analyze-github.js

@@ -4,8 +4,16 @@ import { access, lstat, mkdir, open, readFile, rename, rm, stat, writeFile } fro
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { collectGitHubSourceBundle } from "../collect/github-source-bundle.js";
+import {
+  assertProductRepositoryReadableData,
+  collectGitHubSourceBundle,
+} from "../collect/github-source-bundle.js";
 import { createGhCliProvider } from "../collect/gh-provider.js";
+import {
+  DEFAULT_PRODUCT_REPOSITORY,
+  isProductRepositoryTarget,
+  productRepositoryTargetError,
+} from "../contracts/target-repository.js";
 import { computeRepositoryMetrics } from "../metrics/friction.js";
 import { normalizeFixtureBundle } from "../normalize/github-fixture.js";
 import {
@@ -48,6 +56,7 @@ const ALLOWED_OPTIONS = new Set([
   "interactive",
   "preset",
   "save-preset",
+  "allow-product-repository",
 ]);
 
 const BOOLEAN_OPTIONS = new Set([
@@ -61,6 +70,7 @@ const BOOLEAN_OPTIONS = new Set([
   "json",
   "no-json",
   "interactive",
+  "allow-product-repository",
 ]);
 
 const CLI_OPTION_KEYS = Object.freeze({
@@ -82,6 +92,7 @@ const CLI_OPTION_KEYS = Object.freeze({
   interactive: "interactive",
   preset: "presetPath",
   "save-preset": "savePresetPath",
+  "allow-product-repository": "allowProductRepository",
 });
 
 const RUN_PRESET_OPTION_KEYS = Object.freeze([
@@ -135,6 +146,8 @@ Options:
   --metadata-only           Alias for --dry-run.
   --validation-target       Mark output metadata as an internal validation run; does not bypass target validation.
   --no-validation-target    Disable validation-target mode when a preset enabled it.
+  --allow-product-repository
+                            Explicit live-analysis override for intentional self-analysis of this product repository.
   --exclude-pr-class <cls>  Exclude a PR class from normalized, metrics, report, methodology, and CSV artifacts. Repeat or comma-separate values.
   --csv                     Enable curated CSV evidence exports when a preset disabled them.
   --no-csv                  Suppress curated CSV evidence exports.
@@ -215,6 +228,7 @@ export function parseAnalyzeGithubArgs(argv) {
       if (key === "json") options.json = true;
       if (key === "no-json") options.json = false;
       if (key === "interactive") options.interactive = true;
+      if (key === "allow-product-repository") options.allowProductRepository = true;
       continue;
     }
 
@@ -243,6 +257,7 @@ export function parseAnalyzeGithubArgs(argv) {
     json: options.json,
     interactive: options.interactive,
   };
+  if (options.allowProductRepository) parsed.allowProductRepository = true;
   if (options.preset !== undefined) parsed.presetPath = options.preset;
   if (options["save-preset"] !== undefined) parsed.savePresetPath = options["save-preset"];
   if (parsed.source === undefined) delete parsed.source;
@@ -472,12 +487,14 @@ function hasLiveSourceIndicator(options) {
       || options.interactive
       || options.presetPath
       || options.savePresetPath
+      || options.allowProductRepository
       || options.excludedPrClasses?.length
       || providedOptions.has("dryRun")
       || providedOptions.has("isValidationTarget")
       || providedOptions.has("interactive")
       || providedOptions.has("presetPath")
       || providedOptions.has("savePresetPath")
+      || providedOptions.has("allowProductRepository")
       || providedOptions.has("excludedPrClasses"),
   );
 }
@@ -510,6 +527,9 @@ function rejectSampleLiveOptions(options) {
   if (options.interactive) incompatible.push("--interactive");
   if (options.presetPath) incompatible.push("--preset");
   if (options.savePresetPath) incompatible.push("--save-preset");
+  if (options.allowProductRepository || providedOptions.has("allowProductRepository")) {
+    incompatible.push("--allow-product-repository");
+  }
   if (options.excludedPrClasses?.length || providedOptions.has("excludedPrClasses")) {
     incompatible.push("--exclude-pr-class");
   }
@@ -517,6 +537,14 @@ function rejectSampleLiveOptions(options) {
   throw new Error(`--source sample cannot be combined with live GitHub option(s): ${incompatible.join(", ")}. Use only output options such as --out, --json, --csv, or --no-csv.`);
 }
 
+function targetInputFromRepositorySlug(repository) {
+  const match = REPOSITORY_SLUG.exec(repository);
+  if (!match) {
+    throw new Error("repo must use owner/name with GitHub-safe owner and name segments.");
+  }
+  return { owner: match[1], name: match[2] };
+}
+
 function configuredPrClasses(repositoryProfile) {
   const rules = Array.isArray(repositoryProfile?.prClasses) ? repositoryProfile.prClasses : [];
   return new Set(rules.map(rule => rule.class));
@@ -1628,12 +1656,26 @@ export async function runAnalyzeGithub(options, {
   validateLimit(options.limit);
   validateExcludedPrClasses(options.excludedPrClasses);
   const csvEnabled = options.csv !== false;
+  const effectiveProductRepository = productRepository ?? DEFAULT_PRODUCT_REPOSITORY;
+  const targetInput = targetInputFromRepositorySlug(options.repository);
+  const targetsProductRepository = isProductRepositoryTarget(targetInput, effectiveProductRepository);
+  if (targetsProductRepository && !options.allowProductRepository) {
+    throw new Error(productRepositoryTargetError(targetInput));
+  }
+  onProgress?.("Validating profile.");
+  const repositoryProfile = await readProfile(options.profilePath);
+  if (targetsProductRepository) {
+    onProgress?.("Checking required GitHub read access for product-repository analysis.");
+    await assertProductRepositoryReadableData({
+      repository: options.repository,
+      limit: options.dryRun ? Math.min(options.limit, 1) : options.limit,
+      provider,
+      productRepository: effectiveProductRepository,
+    });
+  }
 
-  onProgress?.("Validating profile and output directory.");
-  const [repositoryProfile, outDir] = await Promise.all([
-    readProfile(options.profilePath),
-    validateOutputDirectory(options.outDir),
-  ]);
+  onProgress?.("Validating output directory.");
+  const outDir = await validateOutputDirectory(options.outDir);
   validateExcludedPrClassesAreConfigured(options.excludedPrClasses ?? [], repositoryProfile);
   const generatedPaths = artifactPaths(outDir, { includeCsv: csvEnabled });
   const disabledPaths = csvEnabled ? {} : Object.fromEntries(
@@ -1654,7 +1696,8 @@ export async function runAnalyzeGithub(options, {
     collectedAt: now(),
     isValidationTarget: options.isValidationTarget,
     contributors: repositoryProfile.contributors,
-    productRepository,
+    productRepository: effectiveProductRepository,
+    allowProductRepository: Boolean(options.allowProductRepository),
   });
 
   if (options.dryRun) {

package/src/collect/github-source-bundle.js

@@ -49,7 +49,7 @@ function visibilityOf(repository) {
   return "unknown";
 }
 
-function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequestLimit, isValidationTarget, productRepository }) {
+function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequestLimit, isValidationTarget, productRepository, allowProductRepository }) {
   const targetRepository = {
     owner,
     name,
@@ -58,13 +58,90 @@ function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequ
     analysisPullRequestLimit,
     isValidationTarget,
   };
-  const errors = validateTargetRepository(targetRepository, { productRepository });
+  const errors = validateTargetRepository(targetRepository, { productRepository, allowProductRepository });
   if (errors.length > 0) {
     throw new Error(`collected target repository metadata is invalid: ${errors.join(" ")}`);
   }
   return targetRepository;
 }
 
+function formatReadableDataFailure({ repository, family, action, error }) {
+  const diagnostic = redactDiagnostic(error?.message ?? error);
+  return `Cannot analyze ${repository} with --allow-product-repository because required GitHub read access could not be proven for ${family}. ${action}. Required preflight must read repository metadata, pull request inventory, and pull request details before collection or artifact writes.${diagnostic ? ` GitHub response: ${diagnostic}` : ""}`;
+}
+
+async function requireReadableProbe({ repository, family, action, run }) {
+  try {
+    return await run();
+  } catch (error) {
+    throw new Error(formatReadableDataFailure({
+      repository,
+      family,
+      action,
+      error,
+    }));
+  }
+}
+
+export async function assertProductRepositoryReadableData({
+  repository,
+  owner,
+  name,
+  limit,
+  provider,
+  productRepository = DEFAULT_PRODUCT_REPOSITORY,
+} = {}) {
+  if (!provider) {
+    throw new Error("provider is required.");
+  }
+  requirePullRequestLimit(limit);
+  const targetInput = repository ? parseRepositoryInput(repository) : { owner, name };
+  if (!isProductRepositoryTarget(targetInput, productRepository)) {
+    return { requiredFamilies: [] };
+  }
+
+  const repositoryLabel = `${targetInput.owner}/${targetInput.name}`;
+  await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "repository metadata",
+    action: "Authenticate with GitHub CLI or choose a repository your token can read",
+    run: () => provider.getRepository(targetInput),
+  });
+
+  const inventory = await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "pull request inventory",
+    action: "Ensure `gh pr list --repo owner/name` can list merged pull requests",
+    run: () => provider.listMergedPullRequests({ ...targetInput, limit }),
+  });
+  if (!Array.isArray(inventory)) {
+    throw new Error(`Cannot analyze ${repositoryLabel} with --allow-product-repository because required GitHub read access could not be proven for pull request inventory. GitHub returned an unreadable pull request inventory shape. Required preflight must read repository metadata, pull request inventory, and pull request details before collection or artifact writes.`);
+  }
+  const selectedInventory = [...inventory]
+    .sort((left, right) => String(right.mergedAt ?? "").localeCompare(String(left.mergedAt ?? "")))
+    .slice(0, limit);
+  const firstPullRequest = selectedInventory[0];
+  if (!firstPullRequest?.number) {
+    throw new Error(`Cannot analyze ${repositoryLabel} with --allow-product-repository because required GitHub read access could not be proven for pull request details. The pull request inventory returned no merged pull requests to inspect. Choose another repository or rerun after merged pull requests are readable.`);
+  }
+
+  await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "pull request details",
+    action: "Ensure `gh pr view --repo owner/name <number> --json ...` can read merged pull request details",
+    run: () => provider.getPullRequest({ ...targetInput, number: firstPullRequest.number }),
+  });
+
+  return {
+    requiredFamilies: [
+      "repository_metadata",
+      "pull_request_inventory",
+      "pull_request_details",
+    ],
+    probedPullRequestNumber: firstPullRequest.number,
+  };
+}
+
 function mapRepositoryMetadata(repository) {
   return {
     id: repository.id ?? null,
@@ -378,6 +455,7 @@ export async function collectGitHubSourceBundle({
   isValidationTarget = false,
   contributors = null,
   productRepository = DEFAULT_PRODUCT_REPOSITORY,
+  allowProductRepository = false,
 } = {}) {
   if (!provider) {
     throw new Error("provider is required.");
@@ -385,7 +463,7 @@ export async function collectGitHubSourceBundle({
   const targetPullRequestLimit = analysisPullRequestLimit ?? limit;
   requirePullRequestLimit(targetPullRequestLimit);
   const targetInput = repository ? parseRepositoryInput(repository) : { owner, name };
-  if (isProductRepositoryTarget(targetInput, productRepository)) {
+  if (isProductRepositoryTarget(targetInput, productRepository) && !allowProductRepository) {
     throw new Error(productRepositoryTargetError(targetInput));
   }
   const targetNameErrors = validateTargetRepository({
@@ -394,7 +472,7 @@ export async function collectGitHubSourceBundle({
     visibility: "unknown",
     analysisPullRequestLimit: targetPullRequestLimit,
     isValidationTarget,
-  }, { productRepository }).filter(error => !error.includes("defaultBranch") && !error.includes("visibility"));
+  }, { productRepository, allowProductRepository }).filter(error => !error.includes("defaultBranch") && !error.includes("visibility"));
   if (targetNameErrors.length > 0) {
     throw new Error(targetNameErrors.join(" "));
   }
@@ -406,6 +484,7 @@ export async function collectGitHubSourceBundle({
     analysisPullRequestLimit: targetPullRequestLimit,
     isValidationTarget,
     productRepository,
+    allowProductRepository,
   });
   const repositoryCoverage = coverageEntry({
     family: "repository_metadata",

package/src/contracts/target-repository.js

@@ -13,7 +13,7 @@ function validateRepoPart(value, label) {
   return null;
 }
 
-export function validateTargetRepository(input, { productRepository } = {}) {
+export function validateTargetRepository(input, { productRepository, allowProductRepository = false } = {}) {
   const errors = [];
   if (!input || typeof input !== "object") {
     return ["target repository input must be an object."];
@@ -46,6 +46,8 @@ export function validateTargetRepository(input, { productRepository } = {}) {
   const normalizedProductName = typeof productRepository?.name === "string" ? productRepository.name.toLowerCase() : null;
 
   if (
+    !allowProductRepository
+    &&
     normalizedInputOwner
     && normalizedInputName
     && normalizedProductOwner
@@ -99,5 +101,12 @@ export function productRepositoryTargetError(input) {
   const repository = typeof input?.owner === "string" && typeof input?.name === "string"
     ? `${input.owner}/${input.name}`
     : "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. Choose a different repository with --repo owner/name. No GitHub data was collected.`;
+  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.
+
+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.`;
 }