delivery-friction-analyzer 0.6.2 → 0.7.1

package/README.md

@@ -15,12 +15,14 @@ The analyzer runs locally with your GitHub credentials. Generated artifacts pres
 
 - 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.
+- A repository profile JSON for the repository you want to analyze. 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 API 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 API coverage is recorded in the generated methodology and coverage artifacts instead of being treated as complete data.
 
 ## Quickstart
 
+### Try the sample target
+
 From this repository, install dependencies and run the analyzer against the sample validation target:
 
 ```sh
@@ -32,25 +34,35 @@ npm run analyze:github -- \
   --out reports/mcp-writing
 ```
 
-From another project or script, run the published CLI with `npx`:
+Open `reports/mcp-writing/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
+
+### Analyze your own repository
+
+For a guided first run in a local terminal, let interactive setup create or confirm the repository profile:
 
 ```sh
-npx delivery-friction-analyzer \
-  --repo hannasdev/mcp-writing \
+npm run analyze:github -- \
+  --interactive \
+  --repo owner/name \
   --limit 30 \
-  --profile path/to/repository-profile.json \
-  --out reports/mcp-writing
+  --profile profiles/owner-name.json \
+  --out reports/owner-name \
+  --dry-run
 ```
 
-Open `reports/mcp-writing/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
+If the profile path does not exist, interactive setup can create a minimal `repository-profile.v1` profile. `--dry-run` validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage without writing the full report bundle. When the profile looks right, rerun the command without `--dry-run`.
 
-For a guided first run in a local terminal, use the opt-in interactive flow:
+To run the CLI from another project with the npm package, pass the same choices as explicit flags:
 
 ```sh
-npm run analyze:github -- --interactive
+npx delivery-friction-analyzer \
+  --repo owner/name \
+  --limit 30 \
+  --profile path/to/repository-profile.json \
+  --out reports/owner-name
 ```
 
-Interactive mode asks for the same run choices supported by flags, including repository, PR limit, profile path, output directory, dry-run mode, CSV exports, JSON completion output, and configured PR class exclusions. It can also create a missing repository profile path or write a generated profile copy with confirmed workflow context and release PR title rules. Scripted and CI usage should keep passing explicit flags; missing required flags without `--interactive` fail deterministically instead of waiting for input.
+Interactive mode walks through missing run choices such as repository, PR limit, profile path, output directory, dry-run mode, and JSON completion output. Depending on the run and profile, it can also prompt for profile creation or updates, CSV exports, and configured PR class exclusions. Use it for guided local setup; keep explicit flags for scripts and CI.
 
 ## Repository Profiles
 
@@ -64,32 +76,26 @@ Profiles can define:
 - PR classes such as release, dependency, feature, or other repository-specific groups;
 - workflow context such as merge method, release strategy, and branch strategy.
 
-For a new repository, the easiest path is to let interactive setup create the profile file you plan to use:
-
-```sh
-npm run analyze:github -- \
-  --interactive \
-  --repo owner/name \
-  --limit 30 \
-  --profile profiles/owner-name.json \
-  --out reports/owner-name \
-  --dry-run
-```
-
-If `profiles/owner-name.json` does not exist, interactive setup asks whether to create it, then writes a minimal `repository-profile.v1` profile with confirmed workflow context and optional release PR title rules. `--dry-run` still validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage. It may create the output directory and briefly write then remove a temporary probe file to confirm writability, but it does not write the full report bundle. When interactive setup saves or generates a profile during a dry run, the completion output prints the saved profile path so you can inspect and edit it before a full run.
+For a new repository, the easiest path is the guided `--interactive --dry-run` command in Quickstart. If the profile path does not exist, interactive setup asks whether to create it, then writes a minimal `repository-profile.v1` profile with user-provided workflow context and optional release PR title rules. It may create the output directory and briefly write then remove a temporary probe file to confirm writability. When interactive setup saves or generates a profile during a dry run, the completion output prints the saved profile path so you can inspect and edit it before a full run.
 
 Use `fixtures/github/mcp-writing/profile.json` as a starting point when you prefer to copy an existing profile by hand. The full profile format is documented in `docs/reference/repository-profile.md`, and the schema lives at `schemas/repository-profile.schema.json`.
 
 ## Outputs
 
-A successful run writes a report bundle to the output directory:
+A successful run writes a report bundle to the output directory. Read these first:
 
 - `friction-report.md`: the main report to read first.
 - `methodology.md`: data coverage, caveats, and interpretation notes.
+
+Use these when you want to audit, automate, or build follow-up analysis:
+
 - `friction-report.json`: machine-readable report data.
 - `metrics-summary.json`: computed metrics used by the report.
 - `normalized.json`: normalized repository, PR, file, review, and validation entities.
 - `source-bundle.json`: collected source data for auditability.
+
+When CSV exports are enabled, the bundle also includes spreadsheet-friendly evidence files:
+
 - `pr-metrics.csv`: per-PR metrics for spreadsheet review.
 - `bottleneck-examples.csv`: representative bottleneck examples.
 - `comment-sources.csv`: review-comment source breakdowns.
@@ -136,11 +142,13 @@ When using a model this way, keep the deterministic artifacts authoritative: pre
 
 No separate model-ready context artifact is required for this workflow. Reconsider a new artifact only if a concrete consumer needs a smaller single-file context, machine-readable prompt packaging, or fields that cannot be represented clearly by `friction-report.json` plus curated CSV evidence.
 
-## Current Direction
+## Development Notes
+
+### Current Direction
 
 Delivery Friction Analyzer is currently a local, GitHub-connected analyzer that produces repository-level friction reports from live pull request data. It is repo-source-agnostic: repository-specific assumptions live in profiles.
 
-The current product wedge is a maintainer workflow:
+The current product focus is a maintainer workflow:
 
 - collect the latest merged PR sample from a target repository;
 - classify files and PRs through repository profiles;
@@ -152,8 +160,6 @@ The product should eventually combine GitHub delivery friction with token and mo
 
 `hannasdev/mcp-writing` remains the first validation target and fixture source, not product-specific scope.
 
-## Development Notes
-
 The existing metrics-summary-only report command remains available for fixture and advanced workflows:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "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-19 — Interactive Setup Choice Presets
+
+- What changed: Interactive setup now shows workflow profile choices as labeled selections and can add an opt-in Conventional Commit PR class preset to generated or updated repository profiles.
+- Why it matters: Maintainers can capture common repository assumptions without typing schema identifiers or hand-writing the first set of title-based PR class rules.
+- Who is affected: Maintainers running `--interactive` to create or update repository profiles.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/40
+
 ### 2026-06-19 — Workflow Context Surfacing
 
 - What changed: Friction reports and methodology now show configured repository workflow context from the profile when it is present.

package/src/cli/analyze-github.js

@@ -17,6 +17,7 @@ import {
   renderRepositoryFrictionMarkdown,
 } from "../report/friction-report.js";
 import { assertValidPrClassRules } from "../profile/pr-class.js";
+import { conventionalCommitPrClassRules } from "../profile/pr-class-presets.js";
 import {
   WORKFLOW_BRANCH_STRATEGIES,
   WORKFLOW_PRIMARY_MERGE_METHODS,
@@ -197,6 +198,20 @@ function defaultOutDirForRepository(repository) {
   return join("reports", name || "analysis");
 }
 
+function choiceValue(choice) {
+  return typeof choice === "object" && choice !== null ? choice.value : choice;
+}
+
+function choiceLabel(choice) {
+  return typeof choice === "object" && choice !== null ? choice.label : choice;
+}
+
+function formatChoiceList(choices) {
+  return choices
+    .map((choice, index) => `${index + 1}. ${choiceLabel(choice)} (${choiceValue(choice)})`)
+    .join("\n");
+}
+
 function formatInteractivePrompt(prompt) {
   const suffix = prompt.defaultValue === undefined
     ? ""
@@ -207,10 +222,10 @@ function formatInteractivePrompt(prompt) {
     return `${prompt.message}${prompt.defaultValue ? " [Y/n]" : " [y/N]"} `;
   }
   if (prompt.type === "multi-select" && prompt.choices?.length) {
-    return `${prompt.message} (${prompt.choices.join(",")})${suffix}: `;
+    return `${prompt.message} (${prompt.choices.map(choiceValue).join(",")})${suffix}: `;
   }
   if (prompt.type === "select" && prompt.choices?.length) {
-    return `${prompt.message} (${prompt.choices.join(",")})${suffix}: `;
+    return `${prompt.message}\n${formatChoiceList(prompt.choices)}\nChoose a number or identifier${suffix}: `;
   }
   return `${prompt.message}${suffix}: `;
 }
@@ -277,8 +292,14 @@ function normalizeConfirmAnswer(raw, prompt) {
 
 function normalizeChoiceAnswer(raw, prompt) {
   const value = normalizeTextAnswer(raw, prompt);
-  if (prompt.choices?.includes(value)) return value;
-  throw new Error(`${prompt.id} must be one of: ${prompt.choices.join(", ")}`);
+  const choices = prompt.choices ?? [];
+  const numericIndex = Number(value);
+  if (Number.isInteger(numericIndex) && numericIndex >= 1 && numericIndex <= choices.length) {
+    return choiceValue(choices[numericIndex - 1]);
+  }
+  const match = choices.find(choice => choiceValue(choice) === value || choiceLabel(choice) === value);
+  if (match) return choiceValue(match);
+  throw new Error(`${prompt.id} must be one of: ${choices.map(choiceValue).join(", ")}`);
 }
 
 function normalizeMultiSelectAnswer(raw, prompt) {
@@ -519,12 +540,74 @@ function releasePrClassRule(profile, titleIncludes, existingRule = null) {
   };
 }
 
+function withAvailablePrClassRuleIds(profile, rules) {
+  const profileWithIds = {
+    ...profile,
+    prClasses: Array.isArray(profile.prClasses) ? [...profile.prClasses] : [],
+  };
+  return rules.map(rule => {
+    const id = nextPrClassRuleId(profileWithIds, rule.id);
+    const nextRule = {
+      ...rule,
+      id,
+      match: { ...rule.match },
+    };
+    profileWithIds.prClasses.push(nextRule);
+    return nextRule;
+  });
+}
+
+async function promptConventionalCommitPrClassPreset(promptAdapter, output, profile) {
+  const hasExistingPrClasses = Array.isArray(profile.prClasses) && profile.prClasses.length > 0;
+  const message = hasExistingPrClasses
+    ? "Add Conventional Commit PR class preset to existing PR class rules"
+    : "Add Conventional Commit PR class preset";
+  const shouldAddPreset = await askUntilValid(promptAdapter, {
+    id: "addConventionalCommitPrClasses",
+    type: "confirm",
+    message,
+    defaultValue: false,
+  }, {
+    output,
+    normalize: normalizeConfirmAnswer,
+    validate() {},
+  });
+  if (!shouldAddPreset) return { profile, prClassRulesWritten: false };
+
+  const updated = cloneJson(profile);
+  updated.prClasses = Array.isArray(updated.prClasses) ? [...updated.prClasses] : [];
+  const presetRules = withAvailablePrClassRuleIds(updated, conventionalCommitPrClassRules());
+  updated.prClasses.push(...presetRules);
+  return { profile: updated, prClassRulesWritten: true };
+}
+
+const WORKFLOW_CHOICE_LABELS = Object.freeze({
+  merge_commit: "Merge commits",
+  squash_merge: "Squash merges",
+  rebase_merge: "Rebase merges",
+  release_prs: "Release PRs",
+  direct_tags: "Direct tags",
+  release_branches: "Release branches",
+  trunk_based: "Trunk-based",
+  main_plus_release_branches: "Main plus release branches",
+  long_lived_development_branches: "Long-lived development branches",
+  mixed: "Mixed",
+  unknown: "Unknown",
+});
+
+function workflowChoices(values) {
+  return values.map(value => ({
+    value,
+    label: WORKFLOW_CHOICE_LABELS[value] ?? value,
+  }));
+}
+
 async function promptWorkflowField(promptAdapter, output, { id, message, choices, defaultValue }) {
   return askUntilValid(promptAdapter, {
     id,
     type: "select",
     message,
-    choices,
+    choices: workflowChoices(choices),
     defaultValue,
   }, {
     output,
@@ -535,6 +618,7 @@ async function promptWorkflowField(promptAdapter, output, { id, message, choices
 
 async function promptWorkflowProfileUpdate(promptAdapter, output, profile, { isNewProfile }) {
   const updated = cloneJson(profile);
+  let prClassRulesWritten = false;
   updated.workflow = {
     primaryMergeMethod: await promptWorkflowField(promptAdapter, output, {
       id: "primaryMergeMethod",
@@ -588,6 +672,7 @@ async function promptWorkflowProfileUpdate(promptAdapter, output, profile, { isN
             titleIncludes,
             updated.prClasses[updateableReleaseIndex],
           );
+          prClassRulesWritten = true;
         }
       } else {
         const shouldAddReleaseRule = isNewProfile
@@ -604,13 +689,18 @@ async function promptWorkflowProfileUpdate(promptAdapter, output, profile, { isN
           });
         if (shouldAddReleaseRule) {
           updated.prClasses.push(releasePrClassRule(updated, titleIncludes));
+          prClassRulesWritten = true;
         }
       }
     }
   }
 
-  validateProfile(updated);
-  return updated;
+  const presetUpdate = await promptConventionalCommitPrClassPreset(promptAdapter, output, updated);
+  validateProfile(presetUpdate.profile);
+  return {
+    profile: presetUpdate.profile,
+    prClassRulesWritten: prClassRulesWritten || presetUpdate.prClassRulesWritten,
+  };
 }
 
 async function maybeConfigureInteractiveProfile(promptAdapter, output, profileState, repository) {
@@ -644,15 +734,33 @@ async function maybeConfigureInteractiveProfile(promptAdapter, output, profileSt
       validate() {},
     });
     if (!shouldConfigureWorkflow) {
+      const presetUpdate = await promptConventionalCommitPrClassPreset(promptAdapter, output, profile);
+      validateProfile(presetUpdate.profile);
+      if (presetUpdate.prClassRulesWritten) {
+        const savedProfilePath = await writeInteractiveProfile(profileState.profilePath, presetUpdate.profile, {
+          exists: profileState.exists,
+          originalProfile,
+          originalText: profileState.text,
+          originalIsSymbolicLink: profileState.isSymbolicLink,
+        });
+        return {
+          profile: presetUpdate.profile,
+          profilePath: savedProfilePath,
+          savedProfilePath,
+          prClassRulesWritten: true,
+        };
+      }
       return {
         profile,
         profilePath: profileState.profilePath,
         savedProfilePath: null,
+        prClassRulesWritten: false,
       };
     }
   }
 
-  profile = await promptWorkflowProfileUpdate(promptAdapter, output, profile, { isNewProfile });
+  const profileUpdate = await promptWorkflowProfileUpdate(promptAdapter, output, profile, { isNewProfile });
+  profile = profileUpdate.profile;
   const savedProfilePath = await writeInteractiveProfile(profileState.profilePath, profile, {
     exists: profileState.exists,
     originalProfile,
@@ -663,6 +771,7 @@ async function maybeConfigureInteractiveProfile(promptAdapter, output, profileSt
     profile,
     profilePath: savedProfilePath,
     savedProfilePath,
+    prClassRulesWritten: profileUpdate.prClassRulesWritten,
   };
 }
 
@@ -774,6 +883,7 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
     resolved.profilePath = profileUpdate.profilePath;
     if (profileUpdate.savedProfilePath) {
       resolved.savedProfilePath = profileUpdate.savedProfilePath;
+      resolved.prClassRulesWritten = profileUpdate.prClassRulesWritten;
       if (typeof onSavedProfilePath === "function") {
         onSavedProfilePath(profileUpdate.savedProfilePath);
       }
@@ -1022,7 +1132,7 @@ function attachCollectionCoverage(report, sourceBundle) {
   };
 }
 
-function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report, requestedLimit, sampledLimit, csv, analysisFilter, savedProfilePath }) {
+function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report, requestedLimit, sampledLimit, csv, analysisFilter, savedProfilePath, prClassRulesWritten }) {
   const summary = {
     ok: true,
     dryRun,
@@ -1041,6 +1151,9 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
   if (savedProfilePath) {
     summary.savedProfilePath = savedProfilePath;
   }
+  if (prClassRulesWritten) {
+    summary.prClassRulesWritten = true;
+  }
   return summary;
 }
 
@@ -1114,6 +1227,7 @@ export async function runAnalyzeGithub(options, {
       csv: false,
       analysisFilter: null,
       savedProfilePath: options.savedProfilePath,
+      prClassRulesWritten: options.prClassRulesWritten,
     });
   }
 
@@ -1166,6 +1280,7 @@ export async function runAnalyzeGithub(options, {
     csv: csvEnabled,
     analysisFilter: normalized.analysisFilter ?? null,
     savedProfilePath: options.savedProfilePath,
+    prClassRulesWritten: options.prClassRulesWritten,
   });
 }
 
@@ -1238,6 +1353,9 @@ export function formatAnalyzeGithubCompletion(result) {
   if (result.savedProfilePath) {
     lines.push(`Repository profile saved: ${result.savedProfilePath}.`);
   }
+  if (result.prClassRulesWritten) {
+    lines.push("PR class rules written: Conventional Commit preset or release title rule.");
+  }
 
   lines.push(`Collection coverage: ${result.collectionCoverage?.status ?? "unknown"}.`);
 

package/src/profile/pr-class-presets.js

@@ -0,0 +1,47 @@
+export const CONVENTIONAL_COMMIT_PR_CLASS_PRESET = Object.freeze([
+  Object.freeze({
+    id: "conventional-dependency",
+    class: "dependency",
+    match: Object.freeze({ titleRegex: "^(?:deps!?|(?:build|chore|fix)\\(deps\\)!?):|^Bump\\b" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+  Object.freeze({
+    id: "conventional-feature",
+    class: "feature",
+    match: Object.freeze({ titleRegex: "^feat(?:\\([^)]+\\))?!?:" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+  Object.freeze({
+    id: "conventional-fix",
+    class: "fix",
+    match: Object.freeze({ titleRegex: "^fix(?:\\((?!deps\\))[^)]+\\))?!?:" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+  Object.freeze({
+    id: "conventional-docs",
+    class: "docs",
+    match: Object.freeze({ titleRegex: "^docs(?:\\([^)]+\\))?!?:" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+  Object.freeze({
+    id: "conventional-test",
+    class: "test",
+    match: Object.freeze({ titleRegex: "^test(?:\\([^)]+\\))?!?:" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+  Object.freeze({
+    id: "conventional-maintenance",
+    class: "maintenance",
+    match: Object.freeze({ titleRegex: "^(refactor|perf|style|build|ci)(?:\\([^)]+\\))?!?:|^chore(?:\\((?!deps\\))[^)]+\\))?!?:" }),
+    notes: "Generated by interactive setup from the Conventional Commit PR title preset.",
+  }),
+]);
+
+export function conventionalCommitPrClassRules() {
+  return CONVENTIONAL_COMMIT_PR_CLASS_PRESET.map(rule => ({
+    id: rule.id,
+    class: rule.class,
+    match: { ...rule.match },
+    notes: rule.notes,
+  }));
+}