delivery-friction-analyzer 0.18.0 → 0.19.0

package/README.md

@@ -9,25 +9,44 @@ Use it when you want to answer questions like:
 - Which files, surfaces, or PR classes create the most back-and-forth?
 - Which issues look preventable with better local checks, repo-specific AI instructions, skills, hooks, or smaller delivery slices?
 
-The analyzer runs locally with your GitHub credentials. Generated artifacts preserve source evidence, coverage caveats, and interpretation limits so reports can be inspected before they are shared.
+For live GitHub analysis, the analyzer runs locally with your GitHub credentials. Generated artifacts preserve source evidence, coverage caveats, and interpretation limits so reports can be inspected before they are shared.
 
 ## Requirements
 
 - Node.js 20 or newer.
-- GitHub CLI (`gh`) installed and authenticated with access to the target repository.
-- A repository profile JSON for the repository you want to analyze. Interactive setup can create a starter profile for you.
+- GitHub CLI (`gh`) installed and authenticated with access to the target repository for live GitHub analysis.
+- A repository profile JSON for the repository you want to analyze in live GitHub mode. Interactive setup can create a starter profile for you.
 
 For public repositories, ordinary read access is usually enough. Private repositories need a `gh` token with enough read access for the requested source families. With a classic PAT, that usually means the `repo` scope. With a fine-grained token or GitHub App, grant read permissions for repository metadata and contents, pull requests, Actions, and checks where available. Missing or partial source coverage is recorded in the generated methodology and coverage artifacts instead of being treated as complete data.
 
 ## Quickstart
 
+### Run the bundled sample
+
+Start with the synthetic tutorial sample. It runs locally without GitHub credentials and writes the same artifact family as live analysis:
+
+```sh
+npx delivery-friction-analyzer --source sample --out reports/tutorial
+```
+
+Open `reports/tutorial/friction-report.md` first. The sample output is labeled `Bundled synthetic sample, not live GitHub data` in the CLI completion, report, methodology, and source bundle.
+
+Short excerpt from the generated sample report context:
+
+> Source: Bundled synthetic sample, not live GitHub data.
+>
+> The generated sample report opens by pointing readers to Change scope, Review churn, and Repo guidance gap. It also shows why the first findings should not be overgeneralized: PR #104 is intentionally broad and outlier-sensitive, PR-open diff coverage is partial, and one PR has unavailable workflow-run history.
+
+Screenshots are intentionally deferred until the project has a visual report surface worth capturing.
+
 ### Guided setup
 
-From this repository, install dependencies and let interactive setup create or confirm the repository profile for a GitHub repository you want to measure:
+After reading the sample report, analyze a repository you own or can read. From this repository, install dependencies and let interactive setup create or confirm the repository profile for a GitHub repository you want to measure:
 
 ```sh
 npm install
 npm run analyze:github -- \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
@@ -44,6 +63,7 @@ After you have a repository profile, run the analyzer against the target reposit
 
 ```sh
 npm run analyze:github -- \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
@@ -56,6 +76,7 @@ To run the CLI from another project with the npm package, pass the same choices
 
 ```sh
 npx delivery-friction-analyzer \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile path/to/repository-profile.json \
@@ -108,6 +129,8 @@ Each ranked bottleneck example includes source references, workflow-run conclusi
 
 ## Common Options
 
+Use `--source sample` for the bundled synthetic tutorial data. Use `--source github` for live repository analysis. Existing live commands that pass `--repo`, `--profile`, or `--limit` without `--source` still run as GitHub analysis, but new users should prefer the explicit source flag.
+
 Use `--dry-run` or `--metadata-only` to validate repository access, profile JSON, output directory writability, and sampled API coverage without writing full report artifacts. The output directory may be created during this check, and a temporary probe file may be written and removed.
 
 Use `--no-csv` when you want the Markdown, JSON, source, normalized, metrics, and methodology artifacts without spreadsheet-friendly CSV exports.

package/docs/reference/release-automation.md

@@ -7,6 +7,7 @@ Delivery Friction Analyzer publishes the unbundled source package to npm. This r
 The npm package allowlist includes:
 
 - runtime source in `src`;
+- bundled tutorial sample runtime data in `examples/tutorial`;
 - JSON schemas in `schemas`;
 - public contract and reference docs in `docs/contracts` and `docs/reference`;
 - the internal validation repository profile at `fixtures/github/mcp-writing/profile.json`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.18.0",
+  "version": "0.19.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 — 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.
+- Why it matters: New users can generate a deterministic local report without GitHub credentials, while existing live GitHub runs keep their source boundary and required target-option validation.
+- Who is affected: First-time users trying the tutorial sample, maintainers reviewing CLI source routing, and users passing live-only flags such as repository targets, dry-run checks, or PR class exclusions.
+- Action needed: Use `delivery-friction-analyzer --source sample --out reports/tutorial` for the bundled sample, or `delivery-friction-analyzer --source github --repo owner/name --limit 30 --profile path/to/profile.json --out reports/owner-name` for live analysis.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/62
+
 ### 2026-06-27 — Tutorial Sample Bundle
 
 - What changed: Added the packaged tutorial sample source bundle, educational sample profile, and generated-aligned report excerpt for a fully synthetic repository.

package/src/cli/analyze-github.js

@@ -25,8 +25,12 @@ import {
 } from "../profile/workflow.js";
 
 const RUN_PRESET_SCHEMA_VERSION = "analyze-github-run-preset.v1";
+const SAMPLE_SOURCE_LABEL = "Bundled synthetic sample, not live GitHub data";
+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 ALLOWED_OPTIONS = new Set([
+  "source",
   "repo",
   "limit",
   "profile",
@@ -60,6 +64,7 @@ const BOOLEAN_OPTIONS = new Set([
 ]);
 
 const CLI_OPTION_KEYS = Object.freeze({
+  source: "source",
   repo: "repository",
   limit: "limit",
   profile: "profilePath",
@@ -114,10 +119,13 @@ const CSV_ARTIFACT_KEYS = new Set([
 ]);
 
 export const USAGE = `Usage:
+  delivery-friction-analyzer --source sample --out <directory>
+  delivery-friction-analyzer --source github --repo <owner/name> --limit <1-100> --profile <path> --out <directory>
   delivery-friction-analyzer --repo <owner/name> --limit <1-100> --profile <path> --out <directory>
   delivery-friction-analyzer --repo <owner/name> --limit <1-100> --profile <path> --out <directory> --dry-run
 
 Options:
+  --source <sample|github> Choose the bundled synthetic sample or live GitHub analysis.
   --repo <owner/name>       Target GitHub repository to analyze.
   --limit <1-100>           Latest merged pull request count.
   --profile <path>          Repository profile JSON used for file role classification.
@@ -137,6 +145,14 @@ Options:
   --save-preset <path>      Save local run settings for non-interactive reruns.
 `;
 
+export const SOURCE_SELECTION_GUIDANCE = `Choose what to analyze.
+
+Try the bundled sample:
+  delivery-friction-analyzer --source sample --out reports/tutorial
+
+Analyze a GitHub repository:
+  delivery-friction-analyzer --source github --repo owner/name --limit 30 --profile path/to/profile.json --out reports/owner-name`;
+
 function attachOptionSource(options, property, value) {
   Object.defineProperty(options, property, {
     value,
@@ -215,6 +231,7 @@ export function parseAnalyzeGithubArgs(argv) {
   }
 
   const parsed = {
+    source: options.source,
     repository: options.repo,
     limit: options.limit === undefined ? undefined : Number(options.limit),
     profilePath: options.profile,
@@ -228,6 +245,7 @@ export function parseAnalyzeGithubArgs(argv) {
   };
   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;
 
   return attachOptionSource(parsed, "explicitCliOptions", explicitOptions);
 }
@@ -408,6 +426,12 @@ function requireOptions(options) {
   }
 }
 
+function requireSampleOptions(options) {
+  if (!options.outDir) {
+    throw new Error("Missing required option(s): --out");
+  }
+}
+
 function validateRepositorySlug(repository) {
   if (typeof repository !== "string" || !REPOSITORY_SLUG.test(repository)) {
     throw new Error("repo must use owner/name with GitHub-safe owner and name segments.");
@@ -428,6 +452,71 @@ function validateExcludedPrClasses(excludedPrClasses = []) {
   }
 }
 
+function validateSource(source) {
+  if (source !== "sample" && source !== "github") {
+    throw new Error("source must be one of: sample, github");
+  }
+}
+
+function hasLiveSourceIndicator(options) {
+  const providedOptions = new Set([
+    ...optionSourceSet(options, "explicitCliOptions"),
+    ...optionSourceSet(options, "presetOptionKeys"),
+  ]);
+  return Boolean(
+    options.repository
+      || options.limit !== undefined
+      || options.profilePath
+      || options.dryRun
+      || options.isValidationTarget
+      || options.interactive
+      || options.presetPath
+      || options.savePresetPath
+      || options.excludedPrClasses?.length
+      || providedOptions.has("dryRun")
+      || providedOptions.has("isValidationTarget")
+      || providedOptions.has("interactive")
+      || providedOptions.has("presetPath")
+      || providedOptions.has("savePresetPath")
+      || providedOptions.has("excludedPrClasses"),
+  );
+}
+
+function resolveAnalysisSource(options) {
+  if (options.source !== undefined) {
+    validateSource(options.source);
+    return options.source;
+  }
+  if (hasLiveSourceIndicator(options)) {
+    return "github";
+  }
+  throw new Error(SOURCE_SELECTION_GUIDANCE);
+}
+
+function rejectSampleLiveOptions(options) {
+  const incompatible = [];
+  const providedOptions = new Set([
+    ...optionSourceSet(options, "explicitCliOptions"),
+    ...optionSourceSet(options, "presetOptionKeys"),
+  ]);
+  const dryRunOptionLabel = providedOptions.has("dryRun") && options.dryRun
+    ? "--dry-run/--metadata-only"
+    : "--dry-run";
+  if (options.repository) incompatible.push("--repo");
+  if (options.limit !== undefined) incompatible.push("--limit");
+  if (options.profilePath) incompatible.push("--profile");
+  if (options.dryRun || providedOptions.has("dryRun")) incompatible.push(dryRunOptionLabel);
+  if (options.isValidationTarget || providedOptions.has("isValidationTarget")) incompatible.push("--validation-target");
+  if (options.interactive) incompatible.push("--interactive");
+  if (options.presetPath) incompatible.push("--preset");
+  if (options.savePresetPath) incompatible.push("--save-preset");
+  if (options.excludedPrClasses?.length || providedOptions.has("excludedPrClasses")) {
+    incompatible.push("--exclude-pr-class");
+  }
+  if (!incompatible.length) return;
+  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 configuredPrClasses(repositoryProfile) {
   const rules = Array.isArray(repositoryProfile?.prClasses) ? repositoryProfile.prClasses : [];
   return new Set(rules.map(rule => rule.class));
@@ -1444,6 +1533,7 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
     sampledLimit,
     outputDirectory: outDir,
     artifactPaths: dryRun ? null : paths,
+    source: sourceBundle.source,
     targetRepository: sourceBundle.targetRepository,
     selection: sourceBundle.selection,
     collectionCoverage: sourceBundle.coverage,
@@ -1484,6 +1574,49 @@ function applyPrClassFilter(normalized, excludedPrClasses = []) {
   };
 }
 
+async function readBundledJson(url, label) {
+  try {
+    return JSON.parse(await readFile(url, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`${label} must be valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+async function buildAnalysisArtifacts({ sourceBundle, repositoryProfile, profilePath, csvEnabled, excludedPrClasses = [] }) {
+  validateExcludedPrClassesAreConfigured(excludedPrClasses, repositoryProfile);
+  const normalized = applyPrClassFilter(
+    normalizeFixtureBundle(sourceBundle, { repositoryProfile }),
+    excludedPrClasses,
+  );
+  const metrics = computeRepositoryMetrics(normalized);
+  const report = attachCollectionCoverage(
+    generateRepositoryFrictionReport(metrics, {
+      workflowContext: repositoryProfile.workflow,
+      contributorSource: normalized.contributorSource,
+    }),
+    sourceBundle,
+  );
+  const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
+  const methodology = renderRepositoryFrictionMethodology({
+    report,
+    sourceBundle,
+    profilePath,
+    artifactFileNames: ANALYZE_GITHUB_ARTIFACTS,
+    csvEnabled,
+  });
+  const csv = csvEnabled
+    ? generateEvidenceCsvArtifacts({
+      metricsSummary: metrics,
+      report,
+      collectionCoverage: sourceBundle.coverage,
+    })
+    : {};
+  return { normalized, metrics, report, markdown, methodology, csv };
+}
+
 export async function runAnalyzeGithub(options, {
   provider = createGhCliProvider(),
   now = () => new Date().toISOString(),
@@ -1541,43 +1674,23 @@ export async function runAnalyzeGithub(options, {
   }
 
   onProgress?.("Normalizing source bundle and computing metrics.");
-  const normalized = applyPrClassFilter(
-    normalizeFixtureBundle(sourceBundle, { repositoryProfile }),
-    options.excludedPrClasses ?? [],
-  );
-  const metrics = computeRepositoryMetrics(normalized);
-  const report = attachCollectionCoverage(
-    generateRepositoryFrictionReport(metrics, {
-      workflowContext: repositoryProfile.workflow,
-      contributorSource: normalized.contributorSource,
-    }),
-    sourceBundle,
-  );
-  const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
-  const methodology = renderRepositoryFrictionMethodology({
-    report,
+  const artifacts = await buildAnalysisArtifacts({
     sourceBundle,
     profilePath: options.profilePath,
-    artifactFileNames: ANALYZE_GITHUB_ARTIFACTS,
     csvEnabled,
+    repositoryProfile,
+    excludedPrClasses: options.excludedPrClasses ?? [],
   });
-  const csv = csvEnabled
-    ? generateEvidenceCsvArtifacts({
-      metricsSummary: metrics,
-      report,
-      collectionCoverage: sourceBundle.coverage,
-    })
-    : {};
 
   onProgress?.("Writing local artifacts.");
   await writeAnalysisArtifacts(outDir, generatedPaths, {
     sourceBundle,
-    normalized,
-    metricsSummary: metrics,
-    reportJson: report,
-    reportMarkdown: markdown,
-    methodology,
-    csv,
+    normalized: artifacts.normalized,
+    metricsSummary: artifacts.metrics,
+    reportJson: artifacts.report,
+    reportMarkdown: artifacts.markdown,
+    methodology: artifacts.methodology,
+    csv: artifacts.csv,
   }, { disabledPaths });
 
   return summarizeResult({
@@ -1585,18 +1698,75 @@ export async function runAnalyzeGithub(options, {
     outDir,
     paths: generatedPaths,
     sourceBundle,
-    metrics,
-    report,
+    metrics: artifacts.metrics,
+    report: artifacts.report,
     requestedLimit: options.limit,
     sampledLimit: collectionLimit,
     csv: csvEnabled,
-    analysisFilter: normalized.analysisFilter ?? null,
+    analysisFilter: artifacts.normalized.analysisFilter ?? null,
     savedProfilePath: options.savedProfilePath,
     savedRunPresetPath: options.savedRunPresetPath,
     prClassRulesWritten: options.prClassRulesWritten,
   });
 }
 
+export async function runAnalyzeSample(options, {
+  onProgress = null,
+} = {}) {
+  rejectSampleLiveOptions(options);
+  requireSampleOptions(options);
+  const csvEnabled = options.csv !== false;
+
+  onProgress?.("Loading bundled synthetic sample.");
+  const [sourceBundle, repositoryProfile, outDir] = await Promise.all([
+    readBundledJson(SAMPLE_SOURCE_BUNDLE_URL, "sample source bundle"),
+    readBundledJson(SAMPLE_PROFILE_URL, "sample repository profile"),
+    validateOutputDirectory(options.outDir),
+  ]);
+  if (sourceBundle.source?.kind !== "sample" || sourceBundle.source?.label !== SAMPLE_SOURCE_LABEL) {
+    throw new Error(`sample source bundle source.kind must be sample and source.label must be ${SAMPLE_SOURCE_LABEL}.`);
+  }
+  validateProfile(repositoryProfile);
+
+  const generatedPaths = artifactPaths(outDir, { includeCsv: csvEnabled });
+  const disabledPaths = csvEnabled ? {} : Object.fromEntries(
+    Object.entries(artifactPaths(outDir, { includeCsv: true })).filter(([key]) => CSV_ARTIFACT_KEYS.has(key)),
+  );
+  await assertWritableArtifactTargets({ ...generatedPaths, ...disabledPaths });
+
+  onProgress?.("Normalizing source bundle and computing metrics.");
+  const artifacts = await buildAnalysisArtifacts({
+    sourceBundle,
+    profilePath: "examples/tutorial/profile.json",
+    csvEnabled,
+    repositoryProfile,
+  });
+
+  onProgress?.("Writing local artifacts.");
+  await writeAnalysisArtifacts(outDir, generatedPaths, {
+    sourceBundle,
+    normalized: artifacts.normalized,
+    metricsSummary: artifacts.metrics,
+    reportJson: artifacts.report,
+    reportMarkdown: artifacts.markdown,
+    methodology: artifacts.methodology,
+    csv: artifacts.csv,
+  }, { disabledPaths });
+
+  return summarizeResult({
+    dryRun: false,
+    outDir,
+    paths: generatedPaths,
+    sourceBundle,
+    metrics: artifacts.metrics,
+    report: artifacts.report,
+    requestedLimit: sourceBundle.selection?.requestedLimit,
+    sampledLimit: sourceBundle.selection?.collectedCount,
+    csv: csvEnabled,
+    analysisFilter: null,
+  });
+}
+
 function writeProgress(message, stderr = process.stderr) {
   stderr.write(`${message}\n`);
 }
@@ -1637,6 +1807,7 @@ export function formatAnalyzeGithubCompletion(result) {
     lines.push(
       `Markdown report: ${paths.reportMarkdown}`,
       `Analysis complete for ${target}.`,
+      `Source: ${result.source?.label ?? "not recorded"}.`,
       `Methodology: ${paths.methodology}`,
       `JSON report: ${paths.reportJson}`,
       `Metrics summary: ${paths.metricsSummary}`,
@@ -1712,7 +1883,28 @@ export async function runAnalyzeGithubCli(argv, {
       stdout.write(USAGE);
       return null;
     }
+    if (parsedOptions.source !== undefined) {
+      validateSource(parsedOptions.source);
+      if (parsedOptions.source === "sample") {
+        const runOptions = {
+          onProgress: message => writeProgress(message, stderr),
+        };
+        const result = await runAnalyzeSample(parsedOptions, runOptions);
+        writeAnalyzeGithubCompletion(result, { json: parsedOptions.json, stdout });
+        return result;
+      }
+    }
     const options = await mergeRunPresetOptions(parsedOptions);
+    const source = resolveAnalysisSource(options);
+
+    if (source === "sample") {
+      const runOptions = {
+        onProgress: message => writeProgress(message, stderr),
+      };
+      const result = await runAnalyzeSample(options, runOptions);
+      writeAnalyzeGithubCompletion(result, { json: options.json, stdout });
+      return result;
+    }
 
     const providedOptionKeys = new Set([
       ...optionSourceSet(options, "explicitCliOptions"),