@proofline/sdk 1.0.4 → 2.0.0

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 CHANGED
@@ -1,8 +1,6 @@
1
1
  # @proofline/sdk
2
2
 
3
- Typed TypeScript client for the [Proofline](https://proofline.sh) review API. It reads
4
- and requests reviews with a scoped API token, and adds pagination, waiting for a review,
5
- retries and typed errors. It needs Node 22 or newer.
3
+ `@proofline/sdk` is the typed TypeScript client for the [Proofline](https://proofline.sh) review API. It reads and requests reviews with a scoped API token, and supports pagination, waiting for a review, retries, and typed errors. It requires Node 22 or newer.
6
4
 
7
5
  ```sh
8
6
  npm install @proofline/sdk
@@ -17,16 +15,13 @@ const client = new ProoflineClient({
17
15
  });
18
16
  ```
19
17
 
20
- The client reads `PROOFLINE_TOKEN` when no token is passed, keeps the token in memory
21
- and redacts it from diagnostic output. The [SDK guide](https://proofline.sh/docs/sdks/)
22
- and [API reference](https://proofline.sh/docs/api/) cover every operation.
18
+ When no token is passed, the client reads `PROOFLINE_TOKEN`, keeps it in memory, and redacts it from diagnostic output. The [SDK guide](https://proofline.sh/docs/sdks/) and [API reference](https://proofline.sh/docs/api/) cover every operation.
19
+
20
+ This repository is the published distribution of the Proofline TypeScript SDK. The public OpenAPI contract in `openapi.public.json` generates `src/operations.ts` and `src/schema.d.ts`. The transport in `src/transport.ts`, client helpers, and tests in `tests/` are hand-written. Open an [issue](https://github.com/prooflinedev/sdk-typescript/issues) for changes to the OpenAPI contract, generated code, or workflows. Pull requests are welcome for the hand-written parts.
23
21
 
24
22
  ## Coverage uploads
25
23
 
26
- Upload the reports produced by CI with a repository-restricted token that holds
27
- `coverage:write`. The token's holder needs current GitHub write access to that
28
- repository. Set `PROOFLINE_TOKEN` to that token and name the full commit the tests
29
- ran on; a branch name or abbreviated SHA is refused.
24
+ Upload CI coverage reports with a repository-restricted token that holds `coverage:write`. The token holder must have current GitHub write access to that repository. Set `PROOFLINE_TOKEN` to that token and pass the full commit SHA that the tests ran on. The server refuses branch names and abbreviated SHAs.
30
25
 
31
26
  ```typescript
32
27
  import { readFile } from "node:fs/promises";
@@ -43,21 +38,13 @@ const report = await client.uploadCoverageReports(
43
38
  console.log(report.report_id, report.created);
44
39
  ```
45
40
 
46
- Send one to 50 LCOV, Cobertura XML, JaCoCo XML or Go cover reports in a JSON body
47
- of at most 64 MiB. Names are unique relative paths, and content is the original
48
- report text. An identical upload returns the existing report with `created: false`.
49
- An upload receipt records evidence; it does not say that a coverage check is met.
41
+ Send 1 to 50 LCOV, Cobertura XML, JaCoCo XML, or Go cover reports in a JSON body of at most 64 MiB. Each report name must be a unique relative path, and content must be the original report text. Repeating an identical upload returns the existing report with `created: false`. An upload receipt records evidence; it does not indicate that a coverage check is met.
50
42
 
51
- Licensed under the Apache License, Version 2.0.
43
+ ## Review exports
52
44
 
53
- ## Exports
45
+ `exportReviews` reads one CSV or NDJSON page through the bounded transport. Export tokens require `analytics:read`. Each call returns the original text, decoded rows, dataset version, settled horizon, and an optional next cursor. CSV cells remain strings, including nested JSON cells, while NDJSON retains JSON values. Each CSV page includes its own header.
54
46
 
55
- `exportReviews` reads one CSV or NDJSON page through the existing bounded transport.
56
- It returns the original text, decoded rows, dataset version, settled horizon and
57
- optional next cursor. CSV cells remain strings, including nested JSON cells;
58
- NDJSON retains JSON values. Export tokens need `analytics:read`.
59
- Repeat with the returned cursor and the same dataset, window, format and grouping.
60
- A missing next cursor marks the last page. Each CSV page includes its own header.
47
+ To read subsequent pages, repeat the call with the returned cursor and the same dataset, window, format, and grouping. A missing next cursor marks the last page.
61
48
 
62
49
  ```typescript
63
50
  const page = await client.exportReviews({
@@ -68,30 +55,9 @@ process.stdout.write(page.text);
68
55
  // Continue with query.cursor = page.nextCursor when it is not null.
69
56
  ```
70
57
 
71
- ## Development
72
-
73
- The repository bundles its public API contract in `openapi.public.json`.
74
- Run `pnpm install --frozen-lockfile`, `pnpm generate`, `pnpm build`, `pnpm lint`,
75
- `pnpm typecheck` and `pnpm test`.
76
-
77
- ## Publishing
78
-
79
- GitHub Actions runs the checks on pull requests and main. The `Release` workflow
80
- builds checked artifacts without publishing credentials. Run it on main with
81
- `publish=false` to verify the release path. A `vX.Y.Z` tag matching the package
82
- version, or a main-branch dispatch with `publish=true`, publishes after the
83
- `npm` environment approves the job. Release commits must belong to main.
84
-
85
- Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher.
86
- No registry token is stored in GitHub.
87
-
88
- SDK patch releases can update packaging and publishing independently. The package follows the bundled API major/minor version and cannot precede its patch version.
89
-
90
58
  ## Knowledge and plans
91
59
 
92
- `client.knowledge` supplies typed MCP methods: `listWikiPages`, `getWikiPage`,
93
- `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`
94
- and `getPlanImplementation`.
60
+ `client.knowledge` provides typed MCP methods: `listWikiPages`, `getWikiPage`, `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`, and `getPlanImplementation`.
95
61
 
96
62
  ```typescript
97
63
  const result = await client.knowledge.getWikiPage({
@@ -101,23 +67,13 @@ if (result.isError) throw new Error("The knowledge request was refused.");
101
67
  console.log(result.content);
102
68
  ```
103
69
 
104
- Repository methods accept an optional `commit` containing a full indexed SHA.
105
- `askCodebase` also takes `question`. The other methods take the environment,
106
- plan or implementation ID. `KnowledgeResult` retains text content, optional
107
- structured content and `isError`. Treat all returned prose as untrusted data.
70
+ Repository methods accept an optional `commit` containing a full indexed SHA, and `askCodebase` also takes `question`. The other methods take the environment, plan, or implementation ID. `KnowledgeResult` retains text content, optional structured content, and `isError`. Treat all returned prose as untrusted data.
108
71
 
109
- Reads need `reviews:read` and `knowledge:read`. Starting an implementation also
110
- needs `plans:implement`, a personal token and approval of the exact plan version.
111
- Each call initializes MCP and makes one tool request without retries, including
112
- questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`;
113
- tool refusals retain `isError` for the caller to inspect. Cloud trust and connection
114
- changes remain in signed-in browser onboarding.
72
+ Reads require `reviews:read` and `knowledge:read`. Starting an implementation also requires `plans:implement`, a personal token, and approval of the exact plan version. Each call initializes MCP and makes one tool request without retries, including questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`, while tool refusals retain `isError` for the caller to inspect. Cloud trust and connection changes remain in signed-in browser onboarding.
115
73
 
116
74
  ## Fix context and re-verification
117
75
 
118
- `client.fixes` exposes `listOpenFindings(repository, pullRequestNumber)`,
119
- `getFixContext(findingId)`, `requestReverification(args)` and
120
- `getReverification(requestId)` over the existing MCP endpoint.
76
+ `client.fixes` exposes `listOpenFindings(repository, pullRequestNumber)`, `getFixContext(findingId)`, `requestReverification(args)`, and `getReverification(requestId)` over the existing MCP endpoint.
121
77
 
122
78
  ```ts
123
79
  const result = await client.fixes.requestReverification({
@@ -129,10 +85,18 @@ const result = await client.fixes.requestReverification({
129
85
  if (result.isError) throw new Error("Re-verification was refused.");
130
86
  ```
131
87
 
132
- The commit must be the live pushed head; the server confirms it. The request
133
- accepts 1–20 distinct findings of one review and an optional 1–2,000-character
134
- note. Reads need `reviews:read`; requesting verification also needs
135
- `reviews:request` and repository write access. Calls never retry.
136
- Results retain untrusted-text wrappers, availability, assessment gaps and
137
- `isError`. `PENDING` and `NOT_VERIFIED` do not establish a fix. A tool request
138
- never records a human disposition.
88
+ The commit must be the live pushed head, which the server confirms. Each request accepts 1 to 20 distinct findings from one review and an optional note of 1 to 2,000 characters. Reads require `reviews:read`; requesting re-verification also requires `reviews:request` and repository write access. Calls never retry. Results retain untrusted-text wrappers, availability, assessment gaps, and `isError`. `PENDING` and `NOT_VERIFIED` do not establish a fix, and a tool request never records a human disposition.
89
+
90
+ ## Contributing and development
91
+
92
+ The repository bundles its public API contract in `openapi.public.json`. New public operations generate typed methods on `ProoflineClient` from their OpenAPI operation IDs. To regenerate the client and verify changes locally, run `pnpm install --frozen-lockfile`, `pnpm generate`, `pnpm build`, `pnpm lint`, `pnpm typecheck`, and `pnpm test`.
93
+
94
+ ## Publishing
95
+
96
+ GitHub Actions runs checks on pull requests and `main`. The `Release` workflow builds checked artifacts without publishing credentials. Run it on `main` with `publish=false` to verify the release path. A `vX.Y.Z` tag matching the package version, or a `main`-branch dispatch with `publish=true`, publishes after the `npm` environment approves the job. Release commits must belong to `main`.
97
+
98
+ Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher, so no registry token is stored in GitHub. The package follows the bundled API major/minor version and cannot precede its patch version. SDK patch releases can update packaging and publishing independently.
99
+
100
+ ## License
101
+
102
+ Licensed under the Apache License, Version 2.0.
package/dist/schema.d.ts CHANGED
@@ -773,6 +773,15 @@ export interface components {
773
773
  */
774
774
  route?: components["schemas"]["SummaryRoute"] | null;
775
775
  };
776
+ /** @description One file World cited for a check's result. */
777
+ CheckFile: {
778
+ /** @description The repository-relative path. It is repository text. */
779
+ path: components["schemas"]["UntrustedText"];
780
+ /** @description The revision World read the file at. */
781
+ revision: components["schemas"]["CheckFileRevision"];
782
+ };
783
+ /** @description The revision a cited file was read at. */
784
+ CheckFileRevision: "PROPOSED_CODE_REVISION" | "BASE_CODE_REVISION";
776
785
  /**
777
786
  * @description World's lifecycle disclosure for the evaluator version that answered, as
778
787
  * the receipt recorded it. A deployment gate counts only `GATING` results
@@ -780,6 +789,46 @@ export interface components {
780
789
  * evaluates a deployment; the lifecycle alone permits or blocks nothing.
781
790
  */
782
791
  CheckLifecycle: "GATING" | "SHADOW" | "QUARANTINED" | "RETIRED" | "UNKNOWN";
792
+ /**
793
+ * @description What the control plane records as a failure's cause.
794
+ * @enum {string}
795
+ */
796
+ CiFailureAttribution: "CAUSED_BY_CHANGE" | "PRE_EXISTING_ON_BASE" | "FLAKY_OR_INFRASTRUCTURE" | "ENVIRONMENT_STATE" | "UNKNOWN";
797
+ /** @description One failed CI job as the Check states it. */
798
+ CiFailureLine: {
799
+ /**
800
+ * @description The recorded cause: `CAUSED_BY_CHANGE`, `PRE_EXISTING_ON_BASE`,
801
+ * `FLAKY_OR_INFRASTRUCTURE`, `ENVIRONMENT_STATE` or `UNKNOWN`. `UNKNOWN`
802
+ * means the failure was not diagnosed, and `undiagnosed` says why.
803
+ */
804
+ attribution: components["schemas"]["CiFailureAttribution"];
805
+ /**
806
+ * @description The first failed step's name, admitted the same way. Null when no
807
+ * step concluded as failed.
808
+ */
809
+ failed_step?: string | null;
810
+ /**
811
+ * @description The job's name as the diagnosis admitted it: masked, or `<withheld>`.
812
+ * A protected value of the observing review reads as the withheld
813
+ * marker.
814
+ */
815
+ job_name: string;
816
+ /**
817
+ * Format: int64
818
+ * @description The GitHub Actions run attempt the job failed in, from 1. The line
819
+ * is the newest diagnosed attempt of its run.
820
+ */
821
+ run_attempt: number;
822
+ /** @description Whether the job timed out rather than failed. */
823
+ timed_out: boolean;
824
+ /**
825
+ * @description Why the failure was not diagnosed. Set exactly when `attribution` is
826
+ * `UNKNOWN`.
827
+ */
828
+ undiagnosed?: components["schemas"]["CiFailureUndiagnosed"] | null;
829
+ };
830
+ /** @description Why a failed job's attribution is `UNKNOWN`. */
831
+ CiFailureUndiagnosed: "LOG_UNAVAILABLE" | "LOG_TOO_LARGE" | "LOG_NOT_ADMITTED" | "DECISION_UNAVAILABLE" | "SHADOW" | "UNDETERMINED";
783
832
  /**
784
833
  * @description A code assessment's recorded execution status. It is never a verdict on
785
834
  * the change: only `COMPLETED` says the assessment covered what it read.
@@ -1066,6 +1115,12 @@ export interface components {
1066
1115
  * this instant, which can precede the assessment.
1067
1116
  */
1068
1117
  evaluated_at?: string | null;
1118
+ /**
1119
+ * @description The files World cited as evidence for this result, once each in
1120
+ * World's order, with the revision World read each at. Empty when World
1121
+ * cited no file, and on results recorded before World cited files.
1122
+ */
1123
+ files: components["schemas"]["CheckFile"][];
1069
1124
  /**
1070
1125
  * @description The lifecycle of the evaluator version that answered. It says whether
1071
1126
  * a deployment gate could count this result, not whether one did.
@@ -1115,6 +1170,11 @@ export interface components {
1115
1170
  * @description When the code assessment ended. Null while it has not.
1116
1171
  */
1117
1172
  completed_at?: string | null;
1173
+ /**
1174
+ * @description Recorded check coverage counts and fixed cancellation causes, without source text.
1175
+ * Absent coverage does not establish that every check ran.
1176
+ */
1177
+ coverage_details?: string[];
1118
1178
  /**
1119
1179
  * @description The code-only findings the code assessment recorded, `SERIOUS` first.
1120
1180
  * An empty list does not establish deployment safety.
@@ -1298,6 +1358,11 @@ export interface components {
1298
1358
  * or `REINTRODUCED`.
1299
1359
  */
1300
1360
  lifecycle_state: string;
1361
+ /**
1362
+ * @description Earlier occurrences in the author's local reviews linked by exact patch
1363
+ * identity. These links carry no verdict or finding decision.
1364
+ */
1365
+ local_findings?: components["schemas"]["MatchedLocalFinding"][];
1301
1366
  /**
1302
1367
  * @description Where this review's comment gate placed the finding, as it recorded
1303
1368
  * the placement. Null when the review recorded none.
@@ -1733,6 +1798,31 @@ export interface components {
1733
1798
  /** @description `CONSIDERED` or `SKIPPED`. */
1734
1799
  status: string;
1735
1800
  };
1801
+ /** @description A published occurrence of an unresolved series absent from the current run. */
1802
+ EarlierOpenFinding: {
1803
+ /**
1804
+ * Format: uuid
1805
+ * @description The occurrence in the series' first published review.
1806
+ */
1807
+ finding_id: string;
1808
+ /**
1809
+ * Format: uuid
1810
+ * @description The unresolved environment finding series counted for this run.
1811
+ */
1812
+ finding_series_id: string;
1813
+ /**
1814
+ * Format: uuid
1815
+ * @description The first published review containing this occurrence.
1816
+ */
1817
+ review_id: string;
1818
+ /**
1819
+ * Format: int64
1820
+ * @description The earlier pull-request run that contains this occurrence.
1821
+ */
1822
+ run_number: number;
1823
+ /** @description Severity used by the series count; the linked occurrence may be less severe. */
1824
+ severity: string;
1825
+ };
1736
1826
  /** @enum {string} */
1737
1827
  EvidenceView: "REQUIRED_PROPERTIES_ESTABLISHED" | "INCOMPLETE" | "NO_APPLICABLE_OBLIGATIONS";
1738
1828
  /** @enum {string} */
@@ -2260,6 +2350,24 @@ export interface components {
2260
2350
  * @enum {string}
2261
2351
  */
2262
2352
  LocalReverificationOutcome: "RESOLVED_VERIFIED" | "STILL_PRESENT" | "NOT_VERIFIED" | "PENDING";
2353
+ /** @description A local occurrence with the same semantic fingerprint as this finding. */
2354
+ MatchedLocalFinding: {
2355
+ /**
2356
+ * Format: date-time
2357
+ * @description When the local review was requested.
2358
+ */
2359
+ created_at: string;
2360
+ /**
2361
+ * Format: uuid
2362
+ * @description The occurrence in that local review.
2363
+ */
2364
+ finding_id: string;
2365
+ /**
2366
+ * Format: uuid
2367
+ * @description The author's local review, linked by exact patch identity.
2368
+ */
2369
+ review_id: string;
2370
+ };
2263
2371
  NotAssessedView: {
2264
2372
  /**
2265
2373
  * @description The display name of the environment whose assessment is not
@@ -2371,6 +2479,8 @@ export interface components {
2371
2479
  * @description Finding series whose current decision is an unexpired `ACCEPTED_RISK`.
2372
2480
  */
2373
2481
  accepted_risks: number;
2482
+ /** @description Exact published occurrences of earlier unresolved environment findings. */
2483
+ earlier_findings?: components["schemas"]["EarlierOpenFinding"][];
2374
2484
  /** @description Recorded assessment gaps, including explicit policy exclusions. */
2375
2485
  not_assessed: components["schemas"]["NotAssessedView"][];
2376
2486
  /**
@@ -2831,6 +2941,29 @@ export interface components {
2831
2941
  * @description Finding series whose current decision is an unexpired `ACCEPTED_RISK`.
2832
2942
  */
2833
2943
  accepted_risk_count: number;
2944
+ /**
2945
+ * @description Failed CI jobs diagnosed on the reviewed head, the newest diagnosed
2946
+ * attempt of each run, in diagnosis order. The Check states each one;
2947
+ * none is a Proofline open item. Absent when no job was diagnosed.
2948
+ */
2949
+ ci_failures?: components["schemas"]["CiFailureLine"][];
2950
+ /**
2951
+ * Format: uint64
2952
+ * @description Diagnosed failed CI jobs on the reviewed head beyond `ci_failures`.
2953
+ */
2954
+ ci_failures_omitted?: number;
2955
+ /**
2956
+ * Format: uint64
2957
+ * @description Failed CI run attempts on the reviewed head whose diagnosis is queued
2958
+ * or running, so none of their jobs has a line yet.
2959
+ */
2960
+ ci_runs_pending?: number;
2961
+ /**
2962
+ * Format: uint64
2963
+ * @description Failed CI run attempts on the reviewed head whose diagnosis failed or
2964
+ * was cancelled, so none of their jobs has a line.
2965
+ */
2966
+ ci_runs_unfinished?: number;
2834
2967
  /**
2835
2968
  * Format: date-time
2836
2969
  * @description GitHub's update time for the recorded pull request state that
@@ -2842,6 +2975,11 @@ export interface components {
2842
2975
  * GitHub. Null when no pull request state is recorded.
2843
2976
  */
2844
2977
  current_head_sha?: string | null;
2978
+ /**
2979
+ * @description Exact published occurrences of earlier unresolved environment findings.
2980
+ * Absent from observations recorded before destinations were captured.
2981
+ */
2982
+ earlier_findings?: components["schemas"]["EarlierOpenFinding"][];
2845
2983
  /**
2846
2984
  * @description This review's environment assessments that are not `COMPLETED`, ordered
2847
2985
  * by environment key.
@@ -3179,6 +3317,13 @@ export interface components {
3179
3317
  placement: string;
3180
3318
  /** @description Human override beside the original decision, when one was requested. */
3181
3319
  promotion?: components["schemas"]["FindingPromotionView"] | null;
3320
+ /**
3321
+ * Format: uuid
3322
+ * @description The finding that represents this finding's publication group, when an
3323
+ * applied group publishes it in one comment with other findings. Every
3324
+ * member names the same finding, the representative included.
3325
+ */
3326
+ publication_group?: string | null;
3182
3327
  /** @description Recognized safe reason codes; unknown values are represented as `UNRECOGNIZED`. */
3183
3328
  reason_codes: string[];
3184
3329
  /** @description Rule that produced the recorded placement. */
package/dist/transport.js CHANGED
@@ -1,4 +1,4 @@
1
- const VERSION = "1.0.4";
1
+ const VERSION = "2.0.0";
2
2
  const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
3
3
  const MAX_RETRIES = 3;
4
4
  const MAX_RETRY_SECONDS = 60;
@@ -763,6 +763,47 @@
763
763
  ],
764
764
  "type": "object"
765
765
  },
766
+ "CheckFile": {
767
+ "description": "One file World cited for a check's result.",
768
+ "properties": {
769
+ "path": {
770
+ "allOf": [
771
+ {
772
+ "$ref": "#/components/schemas/UntrustedText"
773
+ }
774
+ ],
775
+ "description": "The repository-relative path. It is repository text."
776
+ },
777
+ "revision": {
778
+ "allOf": [
779
+ {
780
+ "$ref": "#/components/schemas/CheckFileRevision"
781
+ }
782
+ ],
783
+ "description": "The revision World read the file at."
784
+ }
785
+ },
786
+ "required": [
787
+ "revision",
788
+ "path"
789
+ ],
790
+ "type": "object"
791
+ },
792
+ "CheckFileRevision": {
793
+ "description": "The revision a cited file was read at.",
794
+ "oneOf": [
795
+ {
796
+ "const": "PROPOSED_CODE_REVISION",
797
+ "description": "The reviewed commit.",
798
+ "type": "string"
799
+ },
800
+ {
801
+ "const": "BASE_CODE_REVISION",
802
+ "description": "Its merge base.",
803
+ "type": "string"
804
+ }
805
+ ]
806
+ },
766
807
  "CheckLifecycle": {
767
808
  "description": "World's lifecycle disclosure for the evaluator version that answered, as\n the receipt recorded it. A deployment gate counts only `GATING` results\n (`DeterministicCoverage::gate_effective_status`), and only when it\n evaluates a deployment; the lifecycle alone permits or blocks nothing.",
768
809
  "oneOf": [
@@ -793,6 +834,103 @@
793
834
  }
794
835
  ]
795
836
  },
837
+ "CiFailureAttribution": {
838
+ "description": "What the control plane records as a failure's cause.",
839
+ "enum": [
840
+ "CAUSED_BY_CHANGE",
841
+ "PRE_EXISTING_ON_BASE",
842
+ "FLAKY_OR_INFRASTRUCTURE",
843
+ "ENVIRONMENT_STATE",
844
+ "UNKNOWN"
845
+ ],
846
+ "type": "string"
847
+ },
848
+ "CiFailureLine": {
849
+ "description": "One failed CI job as the Check states it.",
850
+ "properties": {
851
+ "attribution": {
852
+ "allOf": [
853
+ {
854
+ "$ref": "#/components/schemas/CiFailureAttribution"
855
+ }
856
+ ],
857
+ "description": "The recorded cause: `CAUSED_BY_CHANGE`, `PRE_EXISTING_ON_BASE`,\n `FLAKY_OR_INFRASTRUCTURE`, `ENVIRONMENT_STATE` or `UNKNOWN`. `UNKNOWN`\n means the failure was not diagnosed, and `undiagnosed` says why."
858
+ },
859
+ "failed_step": {
860
+ "description": "The first failed step's name, admitted the same way. Null when no\n step concluded as failed.",
861
+ "type": [
862
+ "string",
863
+ "null"
864
+ ]
865
+ },
866
+ "job_name": {
867
+ "description": "The job's name as the diagnosis admitted it: masked, or `<withheld>`.\n A protected value of the observing review reads as the withheld\n marker.",
868
+ "type": "string"
869
+ },
870
+ "run_attempt": {
871
+ "description": "The GitHub Actions run attempt the job failed in, from 1. The line\n is the newest diagnosed attempt of its run.",
872
+ "format": "int64",
873
+ "type": "integer"
874
+ },
875
+ "timed_out": {
876
+ "description": "Whether the job timed out rather than failed.",
877
+ "type": "boolean"
878
+ },
879
+ "undiagnosed": {
880
+ "anyOf": [
881
+ {
882
+ "$ref": "#/components/schemas/CiFailureUndiagnosed"
883
+ },
884
+ {
885
+ "type": "null"
886
+ }
887
+ ],
888
+ "description": "Why the failure was not diagnosed. Set exactly when `attribution` is\n `UNKNOWN`."
889
+ }
890
+ },
891
+ "required": [
892
+ "job_name",
893
+ "timed_out",
894
+ "run_attempt",
895
+ "attribution"
896
+ ],
897
+ "type": "object"
898
+ },
899
+ "CiFailureUndiagnosed": {
900
+ "description": "Why a failed job's attribution is `UNKNOWN`.",
901
+ "oneOf": [
902
+ {
903
+ "const": "LOG_UNAVAILABLE",
904
+ "description": "GitHub returned no log for the job.",
905
+ "type": "string"
906
+ },
907
+ {
908
+ "const": "LOG_TOO_LARGE",
909
+ "description": "The complete log exceeds the read bound.",
910
+ "type": "string"
911
+ },
912
+ {
913
+ "const": "LOG_NOT_ADMITTED",
914
+ "description": "The log could not cross the credential mask or protected-value\n admission. The console names which.",
915
+ "type": "string"
916
+ },
917
+ {
918
+ "const": "DECISION_UNAVAILABLE",
919
+ "description": "The attribution decision fell back: Jev was unavailable or refused.",
920
+ "type": "string"
921
+ },
922
+ {
923
+ "const": "SHADOW",
924
+ "description": "The attribution decision runs in shadow mode, so its answer is not\n applied.",
925
+ "type": "string"
926
+ },
927
+ {
928
+ "const": "UNDETERMINED",
929
+ "description": "The decision applied no cause.",
930
+ "type": "string"
931
+ }
932
+ ]
933
+ },
796
934
  "CodeAssessmentStatus": {
797
935
  "description": "A code assessment's recorded execution status. It is never a verdict on\n the change: only `COMPLETED` says the assessment covered what it read.",
798
936
  "oneOf": [
@@ -1308,6 +1446,13 @@
1308
1446
  "null"
1309
1447
  ]
1310
1448
  },
1449
+ "files": {
1450
+ "description": "The files World cited as evidence for this result, once each in\n World's order, with the revision World read each at. Empty when World\n cited no file, and on results recorded before World cited files.",
1451
+ "items": {
1452
+ "$ref": "#/components/schemas/CheckFile"
1453
+ },
1454
+ "type": "array"
1455
+ },
1311
1456
  "lifecycle": {
1312
1457
  "allOf": [
1313
1458
  {
@@ -1339,7 +1484,8 @@
1339
1484
  "required": [
1340
1485
  "name",
1341
1486
  "outcome",
1342
- "lifecycle"
1487
+ "lifecycle",
1488
+ "files"
1343
1489
  ],
1344
1490
  "type": "object"
1345
1491
  },
@@ -1383,6 +1529,13 @@
1383
1529
  "null"
1384
1530
  ]
1385
1531
  },
1532
+ "coverage_details": {
1533
+ "description": "Recorded check coverage counts and fixed cancellation causes, without source text.\n Absent coverage does not establish that every check ran.",
1534
+ "items": {
1535
+ "type": "string"
1536
+ },
1537
+ "type": "array"
1538
+ },
1386
1539
  "findings": {
1387
1540
  "description": "The code-only findings the code assessment recorded, `SERIOUS` first.\n An empty list does not establish deployment safety.",
1388
1541
  "items": {
@@ -1698,6 +1851,13 @@
1698
1851
  "description": "The finding's recorded lifecycle state: `NEW`, `UNCHANGED`, `RESOLVED`\n or `REINTRODUCED`.",
1699
1852
  "type": "string"
1700
1853
  },
1854
+ "local_findings": {
1855
+ "description": "Earlier occurrences in the author's local reviews linked by exact patch\n identity. These links carry no verdict or finding decision.",
1856
+ "items": {
1857
+ "$ref": "#/components/schemas/MatchedLocalFinding"
1858
+ },
1859
+ "type": "array"
1860
+ },
1701
1861
  "placement": {
1702
1862
  "anyOf": [
1703
1863
  {
@@ -2462,6 +2622,43 @@
2462
2622
  ],
2463
2623
  "type": "object"
2464
2624
  },
2625
+ "EarlierOpenFinding": {
2626
+ "description": "A published occurrence of an unresolved series absent from the current run.",
2627
+ "properties": {
2628
+ "finding_id": {
2629
+ "description": "The occurrence in the series' first published review.",
2630
+ "format": "uuid",
2631
+ "type": "string"
2632
+ },
2633
+ "finding_series_id": {
2634
+ "description": "The unresolved environment finding series counted for this run.",
2635
+ "format": "uuid",
2636
+ "type": "string"
2637
+ },
2638
+ "review_id": {
2639
+ "description": "The first published review containing this occurrence.",
2640
+ "format": "uuid",
2641
+ "type": "string"
2642
+ },
2643
+ "run_number": {
2644
+ "description": "The earlier pull-request run that contains this occurrence.",
2645
+ "format": "int64",
2646
+ "type": "integer"
2647
+ },
2648
+ "severity": {
2649
+ "description": "Severity used by the series count; the linked occurrence may be less severe.",
2650
+ "type": "string"
2651
+ }
2652
+ },
2653
+ "required": [
2654
+ "finding_series_id",
2655
+ "finding_id",
2656
+ "review_id",
2657
+ "run_number",
2658
+ "severity"
2659
+ ],
2660
+ "type": "object"
2661
+ },
2465
2662
  "EvidenceView": {
2466
2663
  "enum": [
2467
2664
  "REQUIRED_PROPERTIES_ESTABLISHED",
@@ -3637,6 +3834,32 @@
3637
3834
  ],
3638
3835
  "type": "string"
3639
3836
  },
3837
+ "MatchedLocalFinding": {
3838
+ "description": "A local occurrence with the same semantic fingerprint as this finding.",
3839
+ "properties": {
3840
+ "created_at": {
3841
+ "description": "When the local review was requested.",
3842
+ "format": "date-time",
3843
+ "type": "string"
3844
+ },
3845
+ "finding_id": {
3846
+ "description": "The occurrence in that local review.",
3847
+ "format": "uuid",
3848
+ "type": "string"
3849
+ },
3850
+ "review_id": {
3851
+ "description": "The author's local review, linked by exact patch identity.",
3852
+ "format": "uuid",
3853
+ "type": "string"
3854
+ }
3855
+ },
3856
+ "required": [
3857
+ "review_id",
3858
+ "finding_id",
3859
+ "created_at"
3860
+ ],
3861
+ "type": "object"
3862
+ },
3640
3863
  "NotAssessedView": {
3641
3864
  "properties": {
3642
3865
  "environment_display_name": {
@@ -3921,6 +4144,13 @@
3921
4144
  "minimum": 0,
3922
4145
  "type": "integer"
3923
4146
  },
4147
+ "earlier_findings": {
4148
+ "description": "Exact published occurrences of earlier unresolved environment findings.",
4149
+ "items": {
4150
+ "$ref": "#/components/schemas/EarlierOpenFinding"
4151
+ },
4152
+ "type": "array"
4153
+ },
3924
4154
  "not_assessed": {
3925
4155
  "description": "Recorded assessment gaps, including explicit policy exclusions.",
3926
4156
  "items": {
@@ -4808,6 +5038,31 @@
4808
5038
  "minimum": 0,
4809
5039
  "type": "integer"
4810
5040
  },
5041
+ "ci_failures": {
5042
+ "description": "Failed CI jobs diagnosed on the reviewed head, the newest diagnosed\n attempt of each run, in diagnosis order. The Check states each one;\n none is a Proofline open item. Absent when no job was diagnosed.",
5043
+ "items": {
5044
+ "$ref": "#/components/schemas/CiFailureLine"
5045
+ },
5046
+ "type": "array"
5047
+ },
5048
+ "ci_failures_omitted": {
5049
+ "description": "Diagnosed failed CI jobs on the reviewed head beyond `ci_failures`.",
5050
+ "format": "uint64",
5051
+ "minimum": 0,
5052
+ "type": "integer"
5053
+ },
5054
+ "ci_runs_pending": {
5055
+ "description": "Failed CI run attempts on the reviewed head whose diagnosis is queued\n or running, so none of their jobs has a line yet.",
5056
+ "format": "uint64",
5057
+ "minimum": 0,
5058
+ "type": "integer"
5059
+ },
5060
+ "ci_runs_unfinished": {
5061
+ "description": "Failed CI run attempts on the reviewed head whose diagnosis failed or\n was cancelled, so none of their jobs has a line.",
5062
+ "format": "uint64",
5063
+ "minimum": 0,
5064
+ "type": "integer"
5065
+ },
4811
5066
  "current_head_provider_updated_at": {
4812
5067
  "description": "GitHub's update time for the recorded pull request state that\n `current_head_sha` comes from. Null when none is recorded.",
4813
5068
  "format": "date-time",
@@ -4823,6 +5078,13 @@
4823
5078
  "null"
4824
5079
  ]
4825
5080
  },
5081
+ "earlier_findings": {
5082
+ "description": "Exact published occurrences of earlier unresolved environment findings.\n Absent from observations recorded before destinations were captured.",
5083
+ "items": {
5084
+ "$ref": "#/components/schemas/EarlierOpenFinding"
5085
+ },
5086
+ "type": "array"
5087
+ },
4826
5088
  "environments": {
4827
5089
  "description": "This review's environment assessments that are not `COMPLETED`, ordered\n by environment key.",
4828
5090
  "items": {
@@ -5450,6 +5712,14 @@
5450
5712
  ],
5451
5713
  "description": "Human override beside the original decision, when one was requested."
5452
5714
  },
5715
+ "publication_group": {
5716
+ "description": "The finding that represents this finding's publication group, when an\n applied group publishes it in one comment with other findings. Every\n member names the same finding, the representative included.",
5717
+ "format": "uuid",
5718
+ "type": [
5719
+ "string",
5720
+ "null"
5721
+ ]
5722
+ },
5453
5723
  "reason_codes": {
5454
5724
  "description": "Recognized safe reason codes; unknown values are represented as `UNRECOGNIZED`.",
5455
5725
  "items": {
@@ -6454,7 +6724,7 @@
6454
6724
  },
6455
6725
  "info": {
6456
6726
  "title": "Proofline Review API",
6457
- "version": "1.0.0"
6727
+ "version": "2.0.0"
6458
6728
  },
6459
6729
  "openapi": "3.1.0",
6460
6730
  "paths": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "1.0.4",
3
+ "version": "2.0.0",
4
4
  "description": "Typed clients for the token-scoped Proofline review API",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",