delivery-friction-analyzer 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -2
- package/docs/reference/repository-profile.md +79 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -64,7 +64,21 @@ Profiles can define:
|
|
|
64
64
|
- PR classes such as release, dependency, feature, or other repository-specific groups;
|
|
65
65
|
- workflow context such as merge method, release strategy, and branch strategy.
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
For a new repository, the easiest path is to let interactive setup create the profile file you plan to use:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
npm run analyze:github -- \
|
|
71
|
+
--interactive \
|
|
72
|
+
--repo owner/name \
|
|
73
|
+
--limit 30 \
|
|
74
|
+
--profile profiles/owner-name.json \
|
|
75
|
+
--out reports/owner-name \
|
|
76
|
+
--dry-run
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
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`.
|
|
68
82
|
|
|
69
83
|
## Outputs
|
|
70
84
|
|
|
@@ -85,7 +99,7 @@ Each ranked bottleneck example includes source references, workflow-run conclusi
|
|
|
85
99
|
|
|
86
100
|
## Common Options
|
|
87
101
|
|
|
88
|
-
Use `--dry-run` or `--metadata-only` to validate repository access, profile JSON, output directory writability, and sampled API coverage without writing full report artifacts.
|
|
102
|
+
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.
|
|
89
103
|
|
|
90
104
|
Use `--no-csv` when you want the Markdown, JSON, source, normalized, metrics, and methodology artifacts without spreadsheet-friendly CSV exports.
|
|
91
105
|
|
|
@@ -37,7 +37,7 @@ This keeps validation-target details in profile data rather than hardcoded produ
|
|
|
37
37
|
|
|
38
38
|
## Pull Request Classes
|
|
39
39
|
|
|
40
|
-
`prClasses` is optional. Rules are evaluated in order and the first matching rule wins.
|
|
40
|
+
`prClasses` is optional. Rules are evaluated in order and the first matching rule wins. The current profile contract supports title-only matchers:
|
|
41
41
|
|
|
42
42
|
- `titleIncludes`: literal substring match against the PR title.
|
|
43
43
|
- `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
|
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
+
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.
|
|
56
|
+
|
|
55
57
|
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.
|
|
56
58
|
|
|
57
|
-
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
|
|
63
|
+
### Copyable PR Class Examples
|
|
64
|
+
|
|
65
|
+
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.
|
|
66
|
+
|
|
67
|
+
Release PRs with titles such as `Release 2026.06.19`:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"prClasses": [
|
|
72
|
+
{
|
|
73
|
+
"id": "release-title",
|
|
74
|
+
"class": "release",
|
|
75
|
+
"match": { "titleRegex": "^Release\\b" }
|
|
76
|
+
}
|
|
77
|
+
]
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Dependency PRs with Dependabot-style titles and common dependency prefixes:
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"prClasses": [
|
|
86
|
+
{
|
|
87
|
+
"id": "dependency-title",
|
|
88
|
+
"class": "dependency",
|
|
89
|
+
"match": { "titleRegex": "^(?:deps!?|(?:build|chore|fix)\\(deps\\)!?):|^Bump\\b" }
|
|
90
|
+
}
|
|
91
|
+
]
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
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:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"prClasses": [
|
|
100
|
+
{
|
|
101
|
+
"id": "conventional-dependency",
|
|
102
|
+
"class": "dependency",
|
|
103
|
+
"match": { "titleRegex": "^(?:deps!?|(?:build|chore|fix)\\(deps\\)!?):|^Bump\\b" }
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"id": "conventional-feature",
|
|
107
|
+
"class": "feature",
|
|
108
|
+
"match": { "titleRegex": "^feat(?:\\([^)]+\\))?!?:" }
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
"id": "conventional-fix",
|
|
112
|
+
"class": "fix",
|
|
113
|
+
"match": { "titleRegex": "^fix(?:\\((?!deps\\))[^)]+\\))?!?:" }
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"id": "conventional-docs",
|
|
117
|
+
"class": "docs",
|
|
118
|
+
"match": { "titleRegex": "^docs(?:\\([^)]+\\))?!?:" }
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"id": "conventional-test",
|
|
122
|
+
"class": "test",
|
|
123
|
+
"match": { "titleRegex": "^test(?:\\([^)]+\\))?!?:" }
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
"id": "conventional-maintenance",
|
|
127
|
+
"class": "maintenance",
|
|
128
|
+
"match": { "titleRegex": "^(refactor|perf|style|build|ci)(?:\\([^)]+\\))?!?:|^chore(?:\\((?!deps\\))[^)]+\\))?!?:" }
|
|
129
|
+
}
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
These examples are starting points, not a universal PR taxonomy. Adjust class names and title patterns to match the repository's own conventions.
|
|
58
135
|
|
|
59
136
|
## Workflow Context
|
|
60
137
|
|