delivery-friction-analyzer 0.3.0 → 0.4.0

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.3.0",
+  "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,14 @@
 
 ## 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.

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

@@ -17,6 +17,7 @@ import {
   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",
@@ -194,6 +195,7 @@ async function readProfile(profilePath) {
   }
   try {
     assertValidPrClassRules(profile);
+    assertValidWorkflowContext(profile);
   } catch (error) {
     throw new Error(`profile is invalid: ${error.message}`);
   }

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("; ")}`);
+  }
+}