delivery-friction-analyzer 0.7.0 → 0.7.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.
Files changed (2) hide show
  1. package/README.md +34 -28
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -15,12 +15,14 @@ The analyzer runs locally with your GitHub credentials. Generated artifacts pres
15
15
 
16
16
  - Node.js 20 or newer.
17
17
  - GitHub CLI (`gh`) installed and authenticated with access to the target repository.
18
- - A repository profile JSON for the repository you want to analyze.
18
+ - A repository profile JSON for the repository you want to analyze. Interactive setup can create a starter profile for you.
19
19
 
20
20
  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.
21
21
 
22
22
  ## Quickstart
23
23
 
24
+ ### Try the sample target
25
+
24
26
  From this repository, install dependencies and run the analyzer against the sample validation target:
25
27
 
26
28
  ```sh
@@ -32,25 +34,35 @@ npm run analyze:github -- \
32
34
  --out reports/mcp-writing
33
35
  ```
34
36
 
35
- From another project or script, run the published CLI with `npx`:
37
+ 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.
38
+
39
+ ### Analyze your own repository
40
+
41
+ For a guided first run in a local terminal, let interactive setup create or confirm the repository profile:
36
42
 
37
43
  ```sh
38
- npx delivery-friction-analyzer \
39
- --repo hannasdev/mcp-writing \
44
+ npm run analyze:github -- \
45
+ --interactive \
46
+ --repo owner/name \
40
47
  --limit 30 \
41
- --profile path/to/repository-profile.json \
42
- --out reports/mcp-writing
48
+ --profile profiles/owner-name.json \
49
+ --out reports/owner-name \
50
+ --dry-run
43
51
  ```
44
52
 
45
- 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.
53
+ 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`.
46
54
 
47
- For a guided first run in a local terminal, use the opt-in interactive flow:
55
+ To run the CLI from another project with the npm package, pass the same choices as explicit flags:
48
56
 
49
57
  ```sh
50
- npm run analyze:github -- --interactive
58
+ npx delivery-friction-analyzer \
59
+ --repo owner/name \
60
+ --limit 30 \
61
+ --profile path/to/repository-profile.json \
62
+ --out reports/owner-name
51
63
  ```
52
64
 
53
- 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.
65
+ 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.
54
66
 
55
67
  ## Repository Profiles
56
68
 
@@ -64,32 +76,26 @@ Profiles can define:
64
76
  - PR classes such as release, dependency, feature, or other repository-specific groups;
65
77
  - workflow context such as merge method, release strategy, and branch strategy.
66
78
 
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.
79
+ 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.
80
80
 
81
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`.
82
82
 
83
83
  ## Outputs
84
84
 
85
- A successful run writes a report bundle to the output directory:
85
+ A successful run writes a report bundle to the output directory. Read these first:
86
86
 
87
87
  - `friction-report.md`: the main report to read first.
88
88
  - `methodology.md`: data coverage, caveats, and interpretation notes.
89
+
90
+ Use these when you want to audit, automate, or build follow-up analysis:
91
+
89
92
  - `friction-report.json`: machine-readable report data.
90
93
  - `metrics-summary.json`: computed metrics used by the report.
91
94
  - `normalized.json`: normalized repository, PR, file, review, and validation entities.
92
95
  - `source-bundle.json`: collected source data for auditability.
96
+
97
+ When CSV exports are enabled, the bundle also includes spreadsheet-friendly evidence files:
98
+
93
99
  - `pr-metrics.csv`: per-PR metrics for spreadsheet review.
94
100
  - `bottleneck-examples.csv`: representative bottleneck examples.
95
101
  - `comment-sources.csv`: review-comment source breakdowns.
@@ -136,11 +142,13 @@ When using a model this way, keep the deterministic artifacts authoritative: pre
136
142
 
137
143
  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.
138
144
 
139
- ## Current Direction
145
+ ## Development Notes
146
+
147
+ ### Current Direction
140
148
 
141
149
  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.
142
150
 
143
- The current product wedge is a maintainer workflow:
151
+ The current product focus is a maintainer workflow:
144
152
 
145
153
  - collect the latest merged PR sample from a target repository;
146
154
  - classify files and PRs through repository profiles;
@@ -152,8 +160,6 @@ The product should eventually combine GitHub delivery friction with token and mo
152
160
 
153
161
  `hannasdev/mcp-writing` remains the first validation target and fixture source, not product-specific scope.
154
162
 
155
- ## Development Notes
156
-
157
163
  The existing metrics-summary-only report command remains available for fixture and advanced workflows:
158
164
 
159
165
  ```sh
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "delivery-friction-analyzer",
3
- "version": "0.7.0",
3
+ "version": "0.7.2",
4
4
  "description": "Local GitHub pull request analytics for delivery friction reports.",
5
5
  "license": "MIT",
6
6
  "type": "module",