delivery-friction-analyzer 0.2.3 → 0.4.0

package/README.md

@@ -44,6 +44,14 @@ npx delivery-friction-analyzer \
 
 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.
 
+For a guided first run in a local terminal, use the opt-in interactive flow:
+
+```sh
+npm run analyze:github -- --interactive
+```
+
+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. Scripted and CI usage should keep passing explicit flags; missing required flags without `--interactive` fail deterministically instead of waiting for input.
+
 ## Repository Profiles
 
 Every run needs a repository profile. Profiles keep repository-specific assumptions out of the analyzer code by describing how paths and pull request titles should be classified.
@@ -84,6 +92,8 @@ Use `--exclude-pr-class <class>` to remove a configured PR class from downstream
 
 Use `--json` when automation needs the full machine-readable completion receipt on stdout.
 
+Use `--interactive` only in a terminal when you want prompts. When combined with `--json`, prompts and progress stay off stdout so the final completion receipt remains parseable JSON.
+
 ## How To Read A Report
 
 Start with `friction-report.md`. If a bottleneck looks surprising, inspect `methodology.md`, the CSV exports, `friction-report.json`, and `source-bundle.json`.

package/docs/reference/repository-profile.md

@@ -53,3 +53,29 @@ If both matchers are present on one rule, both must match. If no rule matches, t
 ```
 
 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.
+
+## Workflow Context
+
+`workflow` is optional user-configured context. It records repository workflow assumptions that later setup and report milestones can rely on, but M2 does not infer these values from GitHub and does not change scoring, rankings, collection, PR class matching, or report wording.
+
+When provided, `workflow` must include at least one supported field.
+
+Supported fields:
+
+- `primaryMergeMethod`: `merge_commit`, `squash_merge`, `rebase_merge`, `mixed`, or `unknown`.
+- `releaseStrategy`: `release_prs`, `direct_tags`, `release_branches`, `mixed`, or `unknown`.
+- `branchStrategy`: `trunk_based`, `main_plus_release_branches`, `long_lived_development_branches`, `mixed`, or `unknown`.
+
+Example:
+
+```json
+{
+  "workflow": {
+    "primaryMergeMethod": "squash_merge",
+    "releaseStrategy": "release_prs",
+    "branchStrategy": "main_plus_release_branches"
+  }
+}
+```
+
+Use stable identifiers exactly as shown above. Display labels such as "squash merges" or "release PRs" belong in CLI prompts or documentation, not in profile data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.2.3",
+  "version": "0.4.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-06-17 — Workflow Profile Contract
+
+- What changed: Repository profiles can now declare optional workflow context for merge method, release strategy, and branch strategy using validated stable identifiers.
+- Why it matters: Future interactive setup and report milestones can rely on a documented profile contract without inferring workflow assumptions from GitHub history or changing scoring.
+- Who is affected: Maintainers authoring or validating repository profiles.
+- Action needed: Add `workflow` context only when you want to record repository workflow assumptions; existing profiles remain valid without it.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/35
+
+### 2026-06-17 — Opt-In Interactive CLI Setup
+
+- What changed: GitHub analysis now supports `--interactive` to prompt for existing run options such as repository, PR limit, profile path, output directory, dry-run mode, CSV exports, JSON completion output, and configured PR class exclusions.
+- Why it matters: First-time maintainers can complete a guided local analysis without memorizing every required flag, while scripts and CI keep deterministic flag-based behavior.
+- Who is affected: Maintainers and contributors running local GitHub analysis from a terminal.
+- Action needed: Use `--interactive` for guided local setup; keep explicit flags for automation.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/34
+
 ### 2026-06-15 — Review Decision Author Detection
 
 - What changed: Review decision evidence now recognizes human approvals from live `gh pr view` review events that include only an author login.

package/schemas/repository-profile.schema.json

@@ -87,6 +87,22 @@
           "notes": { "type": "string" }
         }
       }
+    },
+    "workflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primaryMergeMethod": {
+          "enum": ["merge_commit", "squash_merge", "rebase_merge", "mixed", "unknown"]
+        },
+        "releaseStrategy": {
+          "enum": ["release_prs", "direct_tags", "release_branches", "mixed", "unknown"]
+        },
+        "branchStrategy": {
+          "enum": ["trunk_based", "main_plus_release_branches", "long_lived_development_branches", "mixed", "unknown"]
+        }
+      },
+      "minProperties": 1
     }
   }
 }

package/src/cli/analyze-github.js

@@ -2,6 +2,7 @@
 import { constants, realpathSync } from "node:fs";
 import { access, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 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 { createGhCliProvider } from "../collect/gh-provider.js";
@@ -15,6 +16,8 @@ import {
   generateRepositoryFrictionReport,
   renderRepositoryFrictionMarkdown,
 } from "../report/friction-report.js";
+import { assertValidPrClassRules } from "../profile/pr-class.js";
+import { assertValidWorkflowContext } from "../profile/workflow.js";
 
 const ALLOWED_OPTIONS = new Set([
   "repo",
@@ -27,6 +30,7 @@ const ALLOWED_OPTIONS = new Set([
   "no-csv",
   "exclude-pr-class",
   "json",
+  "interactive",
 ]);
 
 const REPOSITORY_SLUG = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
@@ -66,6 +70,7 @@ Options:
   --exclude-pr-class <cls>  Exclude a PR class from normalized, metrics, report, methodology, and CSV artifacts. Repeat or comma-separate values.
   --no-csv                  Suppress curated CSV evidence exports.
   --json                    Print the machine-readable completion receipt to stdout.
+  --interactive             Prompt for missing run options in a terminal.
 `;
 
 export function parseAnalyzeGithubArgs(argv) {
@@ -90,6 +95,7 @@ export function parseAnalyzeGithubArgs(argv) {
       || key === "validation-target"
       || key === "no-csv"
       || key === "json"
+      || key === "interactive"
     ) {
       options[key] = true;
       continue;
@@ -117,6 +123,7 @@ export function parseAnalyzeGithubArgs(argv) {
     excludedPrClasses: normalizeExcludedPrClasses(options["exclude-pr-class"] ?? []),
     csv: !options["no-csv"],
     json: Boolean(options.json),
+    interactive: Boolean(options.interactive),
   };
 }
 
@@ -159,7 +166,8 @@ function validateExcludedPrClasses(excludedPrClasses = []) {
 }
 
 function configuredPrClasses(repositoryProfile) {
-  return new Set((repositoryProfile.prClasses ?? []).map(rule => rule.class));
+  const rules = Array.isArray(repositoryProfile?.prClasses) ? repositoryProfile.prClasses : [];
+  return new Set(rules.map(rule => rule.class));
 }
 
 function validateExcludedPrClassesAreConfigured(excludedPrClasses = [], repositoryProfile) {
@@ -176,14 +184,276 @@ function validateExcludedPrClassesAreConfigured(excludedPrClasses = [], reposito
 }
 
 async function readProfile(profilePath) {
+  let profile;
   try {
-    return JSON.parse(await readFile(profilePath, "utf8"));
+    profile = JSON.parse(await readFile(profilePath, "utf8"));
   } catch (error) {
     if (error instanceof SyntaxError) {
       throw new Error(`profile must be valid JSON: ${error.message}`);
     }
     throw new Error(`profile could not be read: ${error.message}`);
   }
+  try {
+    assertValidPrClassRules(profile);
+    assertValidWorkflowContext(profile);
+  } catch (error) {
+    throw new Error(`profile is invalid: ${error.message}`);
+  }
+  return profile;
+}
+
+function configuredPrClassList(repositoryProfile) {
+  return [...configuredPrClasses(repositoryProfile)].sort();
+}
+
+function defaultOutDirForRepository(repository) {
+  const [, name] = String(repository ?? "").split("/");
+  return join("reports", name || "analysis");
+}
+
+function formatInteractivePrompt(prompt) {
+  const suffix = prompt.defaultValue === undefined
+    ? ""
+    : Array.isArray(prompt.defaultValue)
+      ? (prompt.defaultValue.length ? ` [${prompt.defaultValue.join(",")}]` : "")
+      : ` [${prompt.defaultValue}]`;
+  if (prompt.type === "confirm") {
+    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}${suffix}: `;
+}
+
+function createTerminalPromptAdapter({ input, output }) {
+  const readline = createInterface({ input, output, terminal: true });
+  return {
+    async ask(prompt) {
+      return readline.question(formatInteractivePrompt(prompt));
+    },
+    writeError(message) {
+      output.write(`${message}\n`);
+    },
+    close() {
+      readline.close();
+    },
+  };
+}
+
+async function callPromptAdapter(promptAdapter, prompt) {
+  if (typeof promptAdapter === "function") {
+    return promptAdapter(prompt);
+  }
+  return promptAdapter.ask(prompt);
+}
+
+async function askUntilValid(promptAdapter, prompt, { normalize, validate, output }) {
+  for (;;) {
+    const raw = await callPromptAdapter(promptAdapter, prompt);
+    try {
+      const value = normalize(raw, prompt);
+      await validate(value);
+      return value;
+    } catch (error) {
+      const message = error?.message ?? String(error);
+      if (typeof promptAdapter.writeError === "function") {
+        promptAdapter.writeError(message);
+      } else if (output?.write) {
+        output.write(`${message}\n`);
+      }
+    }
+  }
+}
+
+function normalizeTextAnswer(raw, prompt) {
+  const value = String(raw ?? "").trim();
+  if (value) return value;
+  if (prompt.defaultValue !== undefined) return prompt.defaultValue;
+  return value;
+}
+
+function normalizeIntegerAnswer(raw, prompt) {
+  const value = normalizeTextAnswer(raw, prompt);
+  return Number(value);
+}
+
+function normalizeConfirmAnswer(raw, prompt) {
+  const value = String(raw ?? "").trim().toLowerCase();
+  if (!value && prompt.defaultValue !== undefined) return Boolean(prompt.defaultValue);
+  if (["y", "yes", "true", "1"].includes(value)) return true;
+  if (["n", "no", "false", "0"].includes(value)) return false;
+  throw new Error("Answer yes or no.");
+}
+
+function normalizeMultiSelectAnswer(raw, prompt) {
+  const value = String(raw ?? "").trim();
+  if (!value) return prompt.defaultValue ?? [];
+  return normalizeExcludedPrClasses([value]);
+}
+
+async function promptProfilePath(promptAdapter, output, prompt) {
+  let profile = null;
+  const profilePath = await askUntilValid(promptAdapter, prompt, {
+    output,
+    normalize: normalizeTextAnswer,
+    async validate(value) {
+      profile = await readProfile(value);
+    },
+  });
+  return { profilePath, profile };
+}
+
+function hasOwnOption(options, key) {
+  return Object.prototype.hasOwnProperty.call(options, key);
+}
+
+function shouldPromptInteractiveOption(options, key) {
+  const promptDefaults = options.interactivePromptDefaults ?? {};
+  if (hasOwnOption(promptDefaults, key)) {
+    return Boolean(promptDefaults[key]);
+  }
+  return !hasOwnOption(options, key);
+}
+
+export async function collectInteractiveAnalyzeGithubOptions(options, {
+  promptAdapter = null,
+  input = process.stdin,
+  output = process.stderr,
+  isInteractiveTerminal = Boolean(input?.isTTY),
+} = {}) {
+  if (!isInteractiveTerminal) {
+    throw new Error("interactive mode requires a terminal. Re-run with --repo <owner/name> --limit <1-100> --profile <path> --out <directory>, or provide a TTY for prompts.");
+  }
+
+  const adapter = promptAdapter ?? createTerminalPromptAdapter({ input, output });
+  const ownsAdapter = !promptAdapter;
+  const resolved = { ...options };
+  delete resolved.interactivePromptDefaults;
+  let repositoryProfile = null;
+
+  try {
+    if (!resolved.repository) {
+      resolved.repository = await askUntilValid(adapter, {
+        id: "repository",
+        type: "text",
+        message: "Target GitHub repository",
+      }, {
+        output,
+        normalize: normalizeTextAnswer,
+        validate: validateRepositorySlug,
+      });
+    }
+
+    if (resolved.limit === undefined) {
+      resolved.limit = await askUntilValid(adapter, {
+        id: "limit",
+        type: "integer",
+        message: "Latest merged pull request count",
+        defaultValue: 30,
+      }, {
+        output,
+        normalize: normalizeIntegerAnswer,
+        validate: validateLimit,
+      });
+    }
+
+    if (!resolved.profilePath) {
+      const prompted = await promptProfilePath(adapter, output, {
+        id: "profilePath",
+        type: "path",
+        message: "Repository profile path",
+      });
+      resolved.profilePath = prompted.profilePath;
+      repositoryProfile = prompted.profile;
+    } else {
+      repositoryProfile = await readProfile(resolved.profilePath);
+    }
+
+    if (!resolved.outDir) {
+      resolved.outDir = await askUntilValid(adapter, {
+        id: "outDir",
+        type: "path",
+        message: "Output directory",
+        defaultValue: defaultOutDirForRepository(resolved.repository),
+      }, {
+        output,
+        normalize: normalizeTextAnswer,
+        async validate(value) {
+          if (!value) throw new Error("Output directory is required.");
+          await validateOutputDirectory(value);
+        },
+      });
+    }
+
+    if (shouldPromptInteractiveOption(options, "dryRun")) {
+      resolved.dryRun = await askUntilValid(adapter, {
+        id: "dryRun",
+        type: "confirm",
+        message: "Run metadata-only dry run",
+        defaultValue: false,
+      }, {
+        output,
+        normalize: normalizeConfirmAnswer,
+        validate() {},
+      });
+    }
+    if (resolved.dryRun === undefined) resolved.dryRun = false;
+
+    if (!resolved.dryRun && shouldPromptInteractiveOption(options, "csv")) {
+      resolved.csv = await askUntilValid(adapter, {
+        id: "csv",
+        type: "confirm",
+        message: "Write CSV evidence files",
+        defaultValue: true,
+      }, {
+        output,
+        normalize: normalizeConfirmAnswer,
+        validate() {},
+      });
+    }
+    if (resolved.csv === undefined) resolved.csv = true;
+
+    if (shouldPromptInteractiveOption(options, "json")) {
+      resolved.json = await askUntilValid(adapter, {
+        id: "json",
+        type: "confirm",
+        message: "Print completion as JSON",
+        defaultValue: false,
+      }, {
+        output,
+        normalize: normalizeConfirmAnswer,
+        validate() {},
+      });
+    }
+    if (resolved.json === undefined) resolved.json = false;
+
+    if (!resolved.excludedPrClasses?.length) {
+      const availablePrClasses = configuredPrClassList(repositoryProfile);
+      if (availablePrClasses.length) {
+        resolved.excludedPrClasses = await askUntilValid(adapter, {
+          id: "excludedPrClasses",
+          type: "multi-select",
+          message: "Exclude PR classes (comma-separated, blank for none)",
+          choices: availablePrClasses,
+          defaultValue: [],
+        }, {
+          output,
+          normalize: normalizeMultiSelectAnswer,
+          validate(value) {
+            validateExcludedPrClasses(value);
+            validateExcludedPrClassesAreConfigured(value, repositoryProfile);
+          },
+        });
+      }
+    }
+
+    return resolved;
+  } finally {
+    if (ownsAdapter && typeof adapter.close === "function") {
+      adapter.close();
+    }
+  }
 }
 
 async function validateOutputDirectory(outDir) {
@@ -480,8 +750,8 @@ export async function runAnalyzeGithub(options, {
   });
 }
 
-function writeProgress(message) {
-  process.stderr.write(`${message}\n`);
+function writeProgress(message, stderr = process.stderr) {
+  stderr.write(`${message}\n`);
 }
 
 function coverageLine(family) {
@@ -568,15 +838,49 @@ export function writeAnalyzeGithubCompletion(result, { json = false, stdout = pr
   stdout.write(formatAnalyzeGithubCompletion(result));
 }
 
-async function main(argv) {
+export async function runAnalyzeGithubCli(argv, {
+  provider,
+  now,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  promptAdapter = null,
+  isInteractiveTerminal = Boolean(stdin?.isTTY),
+} = {}) {
   const options = parseAnalyzeGithubArgs(argv);
   if (options.help) {
-    process.stdout.write(USAGE);
-    return;
+    stdout.write(USAGE);
+    return null;
   }
 
-  const result = await runAnalyzeGithub(options, { onProgress: writeProgress });
-  writeAnalyzeGithubCompletion(result, { json: options.json });
+  const resolvedOptions = options.interactive
+    ? await collectInteractiveAnalyzeGithubOptions({
+      ...options,
+      interactivePromptDefaults: {
+        dryRun: !options.dryRun,
+        csv: options.csv !== false,
+        json: !options.json,
+      },
+    }, {
+      promptAdapter,
+      input: stdin,
+      output: stderr,
+      isInteractiveTerminal,
+    })
+    : options;
+  const runOptions = {
+    onProgress: message => writeProgress(message, stderr),
+  };
+  if (provider !== undefined) runOptions.provider = provider;
+  if (now !== undefined) runOptions.now = now;
+
+  const result = await runAnalyzeGithub(resolvedOptions, runOptions);
+  writeAnalyzeGithubCompletion(result, { json: resolvedOptions.json, stdout });
+  return result;
+}
+
+async function main(argv) {
+  await runAnalyzeGithubCli(argv);
 }
 
 function isCliEntrypoint(entryPath) {

package/src/normalize/github-fixture.js

@@ -1,6 +1,7 @@
 import { classifyCommentSource, groupByCommentSource } from "../github/comment-source.js";
 import { classifyFilePath } from "../profile/file-role.js";
 import { assertValidPrClassRules, classifyPullRequest } from "../profile/pr-class.js";
+import { assertValidWorkflowContext } from "../profile/workflow.js";
 
 function minDate(values) {
   return values.filter(Boolean).sort()[0] ?? null;
@@ -112,6 +113,7 @@ function normalizeCommit(commit) {
 export function normalizeFixtureBundle(bundle, { repositoryProfile } = {}) {
   const profile = repositoryProfile ?? {};
   assertValidPrClassRules(profile);
+  assertValidWorkflowContext(profile);
 
   const pullRequests = (bundle.pullRequests ?? []).map(pr => {
     const reviewDates = (pr.reviews ?? []).map(review => review.submittedAt);

package/src/profile/workflow.js

@@ -0,0 +1,75 @@
+export const WORKFLOW_PRIMARY_MERGE_METHODS = Object.freeze([
+  "merge_commit",
+  "squash_merge",
+  "rebase_merge",
+  "mixed",
+  "unknown",
+]);
+
+export const WORKFLOW_RELEASE_STRATEGIES = Object.freeze([
+  "release_prs",
+  "direct_tags",
+  "release_branches",
+  "mixed",
+  "unknown",
+]);
+
+export const WORKFLOW_BRANCH_STRATEGIES = Object.freeze([
+  "trunk_based",
+  "main_plus_release_branches",
+  "long_lived_development_branches",
+  "mixed",
+  "unknown",
+]);
+
+const WORKFLOW_FIELDS = Object.freeze({
+  primaryMergeMethod: WORKFLOW_PRIMARY_MERGE_METHODS,
+  releaseStrategy: WORKFLOW_RELEASE_STRATEGIES,
+  branchStrategy: WORKFLOW_BRANCH_STRATEGIES,
+});
+
+function allowedValues(values) {
+  return values.join(", ");
+}
+
+export function validateWorkflowContext(profile = {}) {
+  const errors = [];
+  if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+    return errors;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(profile, "workflow")) {
+    return errors;
+  }
+
+  const workflow = profile.workflow;
+  if (!workflow || typeof workflow !== "object" || Array.isArray(workflow)) {
+    return ["workflow must be an object when provided"];
+  }
+  if (Object.keys(workflow).length === 0) {
+    return ["workflow must include at least one field when provided"];
+  }
+
+  for (const key of Object.keys(workflow)) {
+    if (!Object.prototype.hasOwnProperty.call(WORKFLOW_FIELDS, key)) {
+      errors.push(`workflow.${key} is not supported`);
+    }
+  }
+
+  for (const [field, values] of Object.entries(WORKFLOW_FIELDS)) {
+    const value = workflow[field];
+    if (value === undefined) continue;
+    if (!values.includes(value)) {
+      errors.push(`workflow.${field} must be one of: ${allowedValues(values)}`);
+    }
+  }
+
+  return errors;
+}
+
+export function assertValidWorkflowContext(profile = {}) {
+  const errors = validateWorkflowContext(profile);
+  if (errors.length > 0) {
+    throw new Error(`invalid workflow profile context: ${errors.join("; ")}`);
+  }
+}