delivery-friction-analyzer 0.15.0 → 0.16.0

package/README.md

@@ -92,7 +92,10 @@ Use these when you want to audit, automate, or build follow-up analysis:
 - `friction-report.json`: machine-readable report data.
 - `metrics-summary.json`: computed metrics used by the report.
 - `normalized.json`: normalized repository, PR, file, review, and validation entities.
-- `source-bundle.json`: collected source data for auditability.
+- `source-bundle.json`: collected source data for auditability. Its canonical
+  analyzer contract is documented in `docs/contracts/source-bundle.md` and
+  checked by `schemas/github-source-bundle.schema.json`; it is not a full GitHub
+  API payload schema.
 
 When CSV exports are enabled, the bundle also includes spreadsheet-friendly evidence files:
 

package/docs/contracts/source-bundle.md

@@ -0,0 +1,35 @@
+# Source Bundle Contract
+
+Schema: `schemas/github-source-bundle.schema.json`.
+
+`source-bundle.json` is the analyzer's canonical GitHub collection artifact. It
+is source-shaped evidence for later normalization, metrics, reports, and audit
+work, but it is not a full GitHub REST or GraphQL API dump.
+
+The `github-source-bundle.v1` schema covers collector-owned fields:
+
+- collection metadata, target repository, repository metadata, latest-merged PR
+  selection, API coverage diagnostics, and language distribution context;
+- optional sanitized contributor-source metadata: source type, repository path,
+  coverage/status diagnostics, and parsed hint count;
+- pull request fields consumed downstream: identity, title, author object, URL,
+  state, timestamps, refs, final diff counts, PR-open diff source/confidence,
+  commits, files, reviews, review threads/comments, status check rollup,
+  workflow-run summary, and per-PR coverage.
+
+The schema intentionally preserves unavailable and partial coverage. For
+example, unavailable PR-open diff data keeps `source: "unavailable"` and
+`confidence: "unavailable"` without inventing additions, deletions, or changed
+file counts. Unavailable workflow-run history uses `totalCount: null` rather
+than pretending zero runs were observed.
+
+Contributor-source metadata must not persist raw contributor file contents or
+parsed login lists. Parsed contributor hints may be used transiently during a
+run, but generated artifacts keep only the sanitized metadata and `hintCount`.
+
+The schema is strict for analyzer-owned wrapper objects and mapped entities. It
+does not attempt to schema every raw GitHub field, and normal upstream GitHub API
+additions should not require schema updates unless the collector maps them into
+the canonical bundle. Future raw or provider-specific payloads must live under
+an explicit `raw` subtree so downstream normalization stays tied to canonical
+fields.

package/docs/reference/github-data-inventory.md

@@ -53,3 +53,7 @@ Availability decision:
 - `gh api 'repos/hannasdev/mcp-writing/actions/runs?branch=feat/extended-vocabulary-resolution&event=pull_request&per_page=30'`
 
 Fixtures store compact, redacted source-shaped data rather than full raw payloads.
+Live `source-bundle.json` artifacts use the analyzer-owned
+`github-source-bundle.v1` contract in `schemas/github-source-bundle.schema.json`;
+that schema covers the canonical fields consumed downstream, not the full GitHub
+REST or GraphQL API response shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.15.0",
+  "version": "0.16.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-21 — Source Bundle Schema Contract
+
+- What changed: Live GitHub `source-bundle.json` artifacts now have a documented analyzer-owned schema that covers the canonical fields used downstream, including coverage metadata and sanitized contributor-source context.
+- Why it matters: Maintainers can tell when collector output drifts from the supported contract without treating the bundle as a complete raw GitHub API dump.
+- Who is affected: Maintainers reviewing source bundles, contract tests, collector changes, or packaged schema/docs.
+- Action needed: None.
+- PR: #56
+
 ### 2026-06-21 — Runtime Contract Preflight
 
 - What changed: GitHub analysis now rejects this tool's product repository before collection and validates repository profiles more completely before provider calls, including file-rule shape, duplicate IDs, unsupported keys, invalid values, and malformed regexes.

package/schemas/github-source-bundle.schema.json

@@ -0,0 +1,470 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://delivery-friction-analyzer.local/schemas/github-source-bundle.schema.json",
+  "title": "GitHubSourceBundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "collectedAt",
+    "collector",
+    "targetRepository",
+    "repositoryMetadata",
+    "selection",
+    "coverage",
+    "languageDistribution",
+    "pullRequests"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "github-source-bundle.v1" },
+    "collectedAt": { "type": "string" },
+    "collector": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "provider"],
+      "properties": {
+        "name": { "const": "github-live-collector" },
+        "provider": { "type": "string", "minLength": 1 }
+      }
+    },
+    "targetRepository": { "$ref": "target-repository.schema.json" },
+    "repositoryMetadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "owner", "fullName", "defaultBranch", "visibility", "isPrivate", "htmlUrl"],
+      "properties": {
+        "id": { "type": ["integer", "string", "null"] },
+        "name": { "type": ["string", "null"] },
+        "owner": { "type": ["string", "null"] },
+        "fullName": { "type": ["string", "null"] },
+        "defaultBranch": { "type": ["string", "null"] },
+        "visibility": { "enum": ["public", "private", "unknown"] },
+        "isPrivate": { "type": ["boolean", "null"] },
+        "htmlUrl": { "type": ["string", "null"] }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy", "requestedLimit", "collectedCount", "source"],
+      "properties": {
+        "strategy": { "const": "latest_merged_pull_requests" },
+        "requestedLimit": { "type": "integer", "minimum": 1, "maximum": 100 },
+        "collectedCount": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "apiFamilies"],
+      "properties": {
+        "status": { "$ref": "#/$defs/coverageStatus" },
+        "apiFamilies": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/apiCoverageEntry" }
+        }
+      }
+    },
+    "languageDistribution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "bytesByLanguage", "coverage"],
+      "properties": {
+        "source": { "const": "rest:/repos/{owner}/{repo}/languages" },
+        "bytesByLanguage": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "coverage": {
+          "allOf": [
+            { "$ref": "#/$defs/coverageEntry" },
+            {
+              "type": "object",
+              "properties": {
+                "family": { "const": "languages" },
+                "source": { "const": "rest:/repos/{owner}/{repo}/languages" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "contributorSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceType", "path", "coverage", "hintCount"],
+      "properties": {
+        "sourceType": { "enum": ["all_contributors"] },
+        "path": { "type": "string", "minLength": 1 },
+        "coverage": {
+          "allOf": [
+            { "$ref": "#/$defs/coverageEntry" },
+            {
+              "type": "object",
+              "properties": {
+                "family": { "const": "contributor_source" },
+                "source": { "const": "rest:/repos/{owner}/{repo}/contents/{path}" }
+              }
+            }
+          ]
+        },
+        "hintCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "pullRequests": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pullRequest" }
+    },
+    "raw": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "coverageStatus": {
+      "enum": ["available", "partial", "unavailable", "malformed", "unsupported", "rate_limited"]
+    },
+    "nullableString": { "type": ["string", "null"] },
+    "author": {
+      "type": ["object", "null"],
+      "properties": {
+        "login": { "type": ["string", "null"] },
+        "type": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "coverageEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["family", "source", "status", "attempts", "diagnostics", "downstreamImpact"],
+      "properties": {
+        "family": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "status": { "$ref": "#/$defs/coverageStatus" },
+        "attempts": { "type": "integer", "minimum": 0 },
+        "diagnostics": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "downstreamImpact": { "type": ["string", "null"] }
+      }
+    },
+    "apiCoverageEntry": {
+      "allOf": [
+        { "$ref": "#/$defs/coverageEntry" },
+        {
+          "type": "object",
+          "properties": {
+            "family": {
+              "enum": [
+                "repository_metadata",
+                "languages",
+                "pull_request_inventory",
+                "pull_request_details",
+                "review_threads",
+                "workflow_runs",
+                "pr_open_diff",
+                "contributor_source"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "pullRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "number",
+        "title",
+        "author",
+        "url",
+        "state",
+        "createdAt",
+        "mergedAt",
+        "updatedAt",
+        "baseRefName",
+        "headRefName",
+        "headRefOid",
+        "additions",
+        "deletions",
+        "changedFiles",
+        "prOpenDiff",
+        "commits",
+        "files",
+        "reviews",
+        "reviewThreads",
+        "statusCheckRollup",
+        "workflowRuns",
+        "coverage"
+      ],
+      "properties": {
+        "number": { "type": "integer" },
+        "title": { "type": "string" },
+        "author": { "$ref": "#/$defs/author" },
+        "url": { "type": "string" },
+        "state": { "enum": ["OPEN", "CLOSED", "MERGED"] },
+        "createdAt": { "$ref": "#/$defs/nullableString" },
+        "mergedAt": { "$ref": "#/$defs/nullableString" },
+        "updatedAt": { "$ref": "#/$defs/nullableString" },
+        "baseRefName": { "$ref": "#/$defs/nullableString" },
+        "headRefName": { "$ref": "#/$defs/nullableString" },
+        "headRefOid": { "$ref": "#/$defs/nullableString" },
+        "additions": { "type": "integer", "minimum": 0 },
+        "deletions": { "type": "integer", "minimum": 0 },
+        "changedFiles": { "type": "integer", "minimum": 0 },
+        "prOpenDiff": { "$ref": "#/$defs/prOpenDiff" },
+        "commits": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/commit" }
+        },
+        "files": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/changedFile" }
+        },
+        "reviews": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/review" }
+        },
+        "reviewThreads": { "$ref": "#/$defs/reviewThreads" },
+        "statusCheckRollup": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/statusCheck" }
+        },
+        "workflowRuns": { "$ref": "#/$defs/workflowRuns" },
+        "coverage": { "$ref": "#/$defs/prCoverage" }
+      }
+    },
+    "prOpenDiff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "confidence"],
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "anyOf": [
+              { "required": ["additions"] },
+              { "required": ["deletions"] },
+              { "required": ["changedFiles"] }
+            ]
+          },
+          "then": { "required": ["additions", "deletions", "changedFiles"] }
+        },
+        {
+          "if": {
+            "type": "object",
+            "required": ["source"],
+            "properties": { "source": { "enum": ["snapshot_only", "unavailable"] } }
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                { "required": ["additions"] },
+                { "required": ["deletions"] },
+                { "required": ["changedFiles"] }
+              ]
+            }
+          }
+        }
+      ],
+      "properties": {
+        "source": { "enum": ["direct", "reconstructed", "snapshot_only", "unavailable"] },
+        "confidence": { "type": "string" },
+        "reason": { "type": "string" },
+        "additions": { "type": "integer", "minimum": 0 },
+        "deletions": { "type": "integer", "minimum": 0 },
+        "changedFiles": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "commit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["oid", "authoredDate", "committedDate", "messageHeadline"],
+      "properties": {
+        "oid": { "$ref": "#/$defs/nullableString" },
+        "authoredDate": { "$ref": "#/$defs/nullableString" },
+        "committedDate": { "$ref": "#/$defs/nullableString" },
+        "messageHeadline": { "$ref": "#/$defs/nullableString" }
+      }
+    },
+    "changedFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "additions", "deletions", "changeType"],
+      "properties": {
+        "path": { "$ref": "#/$defs/nullableString" },
+        "additions": { "type": "integer", "minimum": 0 },
+        "deletions": { "type": "integer", "minimum": 0 },
+        "changeType": { "$ref": "#/$defs/nullableString" }
+      }
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "author", "submittedAt", "state", "commitOid", "generatedCommentCount", "failedAttempt"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nullableString" },
+        "author": { "$ref": "#/$defs/author" },
+        "submittedAt": { "$ref": "#/$defs/nullableString" },
+        "state": { "$ref": "#/$defs/nullableString" },
+        "commitOid": { "$ref": "#/$defs/nullableString" },
+        "generatedCommentCount": { "type": ["integer", "null"], "minimum": 0 },
+        "failedAttempt": { "type": "boolean" }
+      }
+    },
+    "reviewThreads": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "totalCount", "nodes"],
+      "properties": {
+        "source": { "enum": ["graphql:repository.pullRequest.reviewThreads", "unavailable"] },
+        "totalCount": { "type": "integer", "minimum": 0 },
+        "nodes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/reviewThread" }
+        }
+      }
+    },
+    "reviewThread": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "isResolved", "isOutdated", "path", "line", "comments"],
+      "properties": {
+        "id": { "type": "string" },
+        "isResolved": { "type": "boolean" },
+        "isOutdated": { "type": "boolean" },
+        "path": { "$ref": "#/$defs/nullableString" },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "comments": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/reviewThreadComment" }
+        }
+      }
+    },
+    "reviewThreadComment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["databaseId", "author", "path", "line", "originalLine", "createdAt", "updatedAt", "url"],
+      "properties": {
+        "databaseId": { "type": ["integer", "string", "null"] },
+        "author": { "$ref": "#/$defs/author" },
+        "path": { "$ref": "#/$defs/nullableString" },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "originalLine": { "type": ["integer", "null"], "minimum": 1 },
+        "createdAt": { "$ref": "#/$defs/nullableString" },
+        "updatedAt": { "$ref": "#/$defs/nullableString" },
+        "url": { "$ref": "#/$defs/nullableString" }
+      }
+    },
+    "statusCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["__typename", "name", "context", "workflowName", "status", "conclusion", "startedAt", "completedAt"],
+      "properties": {
+        "__typename": { "enum": ["CheckRun", "StatusContext"] },
+        "name": { "$ref": "#/$defs/nullableString" },
+        "context": { "$ref": "#/$defs/nullableString" },
+        "workflowName": { "$ref": "#/$defs/nullableString" },
+        "status": { "$ref": "#/$defs/nullableString" },
+        "conclusion": { "$ref": "#/$defs/nullableString" },
+        "startedAt": { "$ref": "#/$defs/nullableString" },
+        "completedAt": { "$ref": "#/$defs/nullableString" }
+      }
+    },
+    "workflowRuns": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "totalCount", "conclusions", "runs"],
+      "properties": {
+        "source": { "enum": ["rest:/repos/{owner}/{repo}/actions/runs?branch={branch}&event=pull_request", "unavailable"] },
+        "totalCount": { "type": ["integer", "null"], "minimum": 0 },
+        "conclusions": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "runs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/workflowRun" }
+        }
+      }
+    },
+    "workflowRun": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "name",
+        "workflowName",
+        "headSha",
+        "headBranch",
+        "event",
+        "status",
+        "conclusion",
+        "createdAt",
+        "updatedAt",
+        "runStartedAt",
+        "htmlUrl"
+      ],
+      "properties": {
+        "id": { "type": ["integer", "string", "null"] },
+        "name": { "$ref": "#/$defs/nullableString" },
+        "workflowName": { "$ref": "#/$defs/nullableString" },
+        "headSha": { "$ref": "#/$defs/nullableString" },
+        "headBranch": { "$ref": "#/$defs/nullableString" },
+        "event": { "$ref": "#/$defs/nullableString" },
+        "status": { "$ref": "#/$defs/nullableString" },
+        "conclusion": { "$ref": "#/$defs/nullableString" },
+        "createdAt": { "$ref": "#/$defs/nullableString" },
+        "updatedAt": { "$ref": "#/$defs/nullableString" },
+        "runStartedAt": { "$ref": "#/$defs/nullableString" },
+        "htmlUrl": { "$ref": "#/$defs/nullableString" }
+      }
+    },
+    "prCoverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prOpenDiff", "reviewThreads", "workflowRuns"],
+      "properties": {
+        "prOpenDiff": {
+          "allOf": [
+            { "$ref": "#/$defs/coverageEntry" },
+            {
+              "type": "object",
+              "properties": {
+                "family": { "const": "pr_open_diff" },
+                "source": { "const": "historical_snapshot" },
+                "status": { "enum": ["available", "partial", "unavailable", "rate_limited"] }
+              }
+            }
+          ]
+        },
+        "reviewThreads": {
+          "allOf": [
+            { "$ref": "#/$defs/coverageEntry" },
+            {
+              "type": "object",
+              "properties": {
+                "family": { "const": "review_threads" },
+                "source": { "const": "graphql:repository.pullRequest.reviewThreads" }
+              }
+            }
+          ]
+        },
+        "workflowRuns": {
+          "allOf": [
+            { "$ref": "#/$defs/coverageEntry" },
+            {
+              "type": "object",
+              "properties": {
+                "family": { "const": "workflow_runs" },
+                "source": { "const": "rest:/repos/{owner}/{repo}/actions/runs?branch={branch}&event=pull_request" }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}