delivery-friction-analyzer 0.6.1 → 0.7.0

package/README.md

@@ -64,7 +64,21 @@ 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.
 
-Use `fixtures/github/mcp-writing/profile.json` as a starting point, then save a copy for the repository you want to analyze. The full profile format is documented in `docs/reference/repository-profile.md`, and the schema lives at `schemas/repository-profile.schema.json`.
+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.
+
+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
 
@@ -85,7 +99,7 @@ Each ranked bottleneck example includes source references, workflow-run conclusi
 
 ## Common Options
 
-Use `--dry-run` or `--metadata-only` to validate repository access, profile JSON, output directory writability, and sampled API coverage without writing full report artifacts.
+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/repository-profile.md

@@ -37,7 +37,7 @@ This keeps validation-target details in profile data rather than hardcoded produ
 
 ## Pull Request Classes
 
-`prClasses` is optional. Rules are evaluated in order and the first matching rule wins. M1 supports title-only matchers:
+`prClasses` is optional. Rules are evaluated in order and the first matching rule wins. The current profile contract supports title-only matchers:
 
 - `titleIncludes`: literal substring match against the PR title.
 - `titleRegex`: JavaScript regular expression matched against the PR title.
@@ -52,9 +52,86 @@ If both matchers are present on one rule, both must match. If no rule matches, t
 }
 ```
 
+In reports, `unknown` means no configured `prClasses` rule matched that PR title. It is the transparent no-matching-rule fallback, not a collection failure and not an inferred repository taxonomy.
+
 Class identifiers are validated as lower-kebab-case or lower_snake_case strings. Profile validation rejects duplicate PR class rule IDs, empty match objects, invalid class identifiers, and invalid title regexes.
 
-Interactive setup can add a release PR class rule from a confirmed title convention using the current title-only matcher shape. Branch strategy answers stay in `workflow` context only; they do not create branch-based PR class matching.
+PR class evidence is interpretive and profile-driven. It helps reports show class distributions, dominance notes, and explicit `--exclude-pr-class` filtering when you request filtering, but configured PR class rules do not change default scoring, ranking formulas, collection, or CSV export shape by themselves.
+
+Interactive setup can add a release PR class rule from a confirmed title convention using the current title-only matcher shape. Branch strategy answers stay in `workflow` context only; they do not create branch-based PR class matching. Branch-based class matching is deferred until a future matcher contract supports branch fields explicitly.
+
+### Copyable PR Class Examples
+
+Add one `prClasses` array to the top level of a profile, next to `repository` and `rules`. Keep the rules ordered from most specific to broadest because the first match wins.
+
+Release PRs with titles such as `Release 2026.06.19`:
+
+```json
+{
+  "prClasses": [
+    {
+      "id": "release-title",
+      "class": "release",
+      "match": { "titleRegex": "^Release\\b" }
+    }
+  ]
+}
+```
+
+Dependency PRs with Dependabot-style titles and common dependency prefixes:
+
+```json
+{
+  "prClasses": [
+    {
+      "id": "dependency-title",
+      "class": "dependency",
+      "match": { "titleRegex": "^(?:deps!?|(?:build|chore|fix)\\(deps\\)!?):|^Bump\\b" }
+    }
+  ]
+}
+```
+
+Conventional Commit-style PR titles. Dependency-scoped rules come first so `chore(deps): ...` and `fix(deps): ...` do not fall through to maintenance or fix classes:
+
+```json
+{
+  "prClasses": [
+    {
+      "id": "conventional-dependency",
+      "class": "dependency",
+      "match": { "titleRegex": "^(?:deps!?|(?:build|chore|fix)\\(deps\\)!?):|^Bump\\b" }
+    },
+    {
+      "id": "conventional-feature",
+      "class": "feature",
+      "match": { "titleRegex": "^feat(?:\\([^)]+\\))?!?:" }
+    },
+    {
+      "id": "conventional-fix",
+      "class": "fix",
+      "match": { "titleRegex": "^fix(?:\\((?!deps\\))[^)]+\\))?!?:" }
+    },
+    {
+      "id": "conventional-docs",
+      "class": "docs",
+      "match": { "titleRegex": "^docs(?:\\([^)]+\\))?!?:" }
+    },
+    {
+      "id": "conventional-test",
+      "class": "test",
+      "match": { "titleRegex": "^test(?:\\([^)]+\\))?!?:" }
+    },
+    {
+      "id": "conventional-maintenance",
+      "class": "maintenance",
+      "match": { "titleRegex": "^(refactor|perf|style|build|ci)(?:\\([^)]+\\))?!?:|^chore(?:\\((?!deps\\))[^)]+\\))?!?:" }
+    }
+  ]
+}
+```
+
+These examples are starting points, not a universal PR taxonomy. Adjust class names and title patterns to match the repository's own conventions.
 
 ## Workflow Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.6.1",
+  "version": "0.7.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-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,
+  }));
+}