@morehao/trendradar-contract 0.2.0 → 0.3.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/CHANGELOG.md CHANGED
@@ -3,6 +3,42 @@
3
3
  All notable changes to `@morehao/trendradar-contract` are documented here.
4
4
  This project adheres to a `contract/vX.Y.Z` tag per release (npm + Go submodule).
5
5
 
6
+ ## Unreleased
7
+
8
+ _Nothing yet._
9
+
10
+ ## 0.3.0
11
+
12
+ Repo release subscriptions become a first-class contract capability. The wire
13
+ integers stay at `ipcSchema = 2` / `digestSchema = 2`: every addition here is
14
+ backward compatible, so existing plugins keep working without a handshake bump.
15
+
16
+ ### Added
17
+ - `schema/releases.v2.json`: `ReleaseDigest` (the on-disk document, `schema: 1`),
18
+ `RepoReleases`, `ReleaseItem`, plus `ReleasesReport`,
19
+ `ReleaseManifestEntry` and `SubscriptionList`.
20
+ - `RunRequest.command` accepts `subscribe`, with `action`
21
+ (`list|add|remove`) and `repo`. The envelope stays strict
22
+ (`additionalProperties: false`); conditional rules enforce that `list` takes
23
+ no `repo`, `add`/`remove` require one, and non-subscribe commands carry
24
+ neither.
25
+ - `RunResult.releases`: the releases-stage diagnostic, now schema-checked
26
+ instead of riding on `additionalProperties`.
27
+ - `api.v2.yaml`: `GET /api/v2/releases`, `GET /api/v2/releases/{date}` and
28
+ `GET /api/v2/subscriptions` (read-only; empty arrays rather than 404 when no
29
+ data exists).
30
+
31
+ ### Notes
32
+ - **Token cost**: `ReleasesReport.usage` is required and always serialized so a
33
+ consumer can tell "nothing spent" (`calls = 0`) from "spent but the provider
34
+ reported nothing" (`calls > 0` with `usageKnown = false`). Cost is
35
+ deliberately absent from `ReleaseDigest` and from
36
+ `ReleaseManifestEntry`: a stored document describes content, not one run.
37
+ - `ReleaseItem.id` is `int64` in Go (GitHub ids exceed int32 on 32-bit
38
+ platforms) and required (`0` for tag fallbacks).
39
+ - Generated Go/TS names `id` as `ID`; the generator gained an `x-go-type:
40
+ int64` escape hatch and a conditional-`allOf` branch.
41
+
6
42
  ## 0.2.0
7
43
 
8
44
  Initial v2 contract (breaking re-baseline; no v1 wire compatibility).
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # @morehao/trendradar-contract (0.2.0)
1
+ # @morehao/trendradar-contract (0.3.0)
2
2
 
3
3
  The single source of truth for the data shapes shared by the **trendradar Go
4
4
  core** (`github.com/morehao/trendradar`) and the **DSH plugin**
@@ -12,7 +12,7 @@ artifacts from one tag:
12
12
 
13
13
  Both are released together by the tag `contract/v0.Y.Z` (see `CHANGELOG.md`).
14
14
 
15
- > Version model: the **package** is `0.2.0` (its first public release), while the
15
+ > Version model: the **package** is `0.3.0`, while the
16
16
  > **wire format** it carries is the second generation — `ipcSchema=2`,
17
17
  > `digestSchema=2`. The integers 2 distinguish this contract from the legacy
18
18
  > in-repo v1; they are intentionally decoupled from the package semver.
@@ -20,8 +20,8 @@ Both are released together by the tag `contract/v0.Y.Z` (see `CHANGELOG.md`).
20
20
  ## Install
21
21
 
22
22
  ```bash
23
- npm i @morehao/trendradar-contract@0.2.0
24
- go get github.com/morehao/trendradar/contract@v0.2.0 # resolves tag contract/v0.2.0
23
+ npm i @morehao/trendradar-contract@0.3.0
24
+ go get github.com/morehao/trendradar/contract@v0.3.0 # resolves tag contract/v0.3.0
25
25
  ```
26
26
 
27
27
  ## Layout
@@ -31,10 +31,11 @@ go get github.com/morehao/trendradar/contract@v0.2.0 # resolves tag contract/v
31
31
  | `schema/model.v2.json` | `RepoSnapshot`; `RepoDigest` composes it via `allOf` |
32
32
  | `schema/ipc.v2.json` | `RunRequest` (strict), `RunResult`, `ErrorInfo`, `State`, `FileArtifact` |
33
33
  | `schema/digest.v2.json` | rendered digest document, incl. `contentHashAlgo` |
34
+ | `schema/releases.v2.json` | release-subscription document + `ReleasesReport` (run cost) |
34
35
  | `schema/errors.v2.json` | 17 error codes with `retriable`/`description` (single source of truth) |
35
36
  | `schema/version-info.v2.json` | `trendradar version --json` handshake |
36
- | `schema/api.v2.yaml` | `trendradar serve` OpenAPI (`/api/v2`) |
37
- | `fixtures/*.json` | golden v2 digests (incl. `digest-missing-optional.json`) |
37
+ | `schema/api.v2.yaml` | `trendradar serve` OpenAPI (`/api/v2`, incl. releases) |
38
+ | `fixtures/*.json` | golden v2 digests + release documents |
38
39
  | `version-map.json` | schema file → version carrier → propagation |
39
40
  | `contract.gen.go` | generated Go structs + `ErrorCode` + `ErrorCatalog` + `SchemaFS` |
40
41
  | `gen/ts/index.{js,d.ts}` | generated TS types + runtime (`validators`, `errorCatalog`, `fixtures`, `rawSchema`) |
@@ -61,12 +62,18 @@ contract.SchemaFS // embedded schema/* files
61
62
  ## Versioning & compatibility
62
63
 
63
64
  - `ipcSchema` (const 2) and `digestSchema` (const 2) are the wire integers;
64
- `contractVersion` (`"0.2.0"`) is the package handshake.
65
+ `contractVersion` (`"0.3.0"`) is the package handshake.
65
66
  - Adding an **optional** field is a minor change. Removing/renaming a field,
66
67
  changing a type, or tightening validation is **breaking**: bump the affected
67
68
  wire integer and/or the package version, declared in `version-map.json`.
68
69
  `make verify-versions` enforces this against the PR base.
69
- - `RunRequest` is the only strict object (`additionalProperties: false`).
70
+ - `RunRequest` is the only strict object (`additionalProperties: false`). It
71
+ carries conditional rules for `command: "subscribe"`: `action` is required,
72
+ `list` takes no `repo`, `add`/`remove` require one, and other commands must
73
+ not carry either field.
74
+ - Token cost for releases lives in `ReleasesReport.usage` (always present) and
75
+ **not** in the stored `ReleaseDigest`, because cost describes one run and
76
+ cannot be reproduced from a document.
70
77
 
71
78
  ## contentHash
72
79
 
@@ -82,7 +89,6 @@ excluded; optional repo fields omitted when absent). New files use
82
89
  npm ci
83
90
  npm run generate # regenerate contract.gen.go + gen/ts (deterministic, gofmt'd)
84
91
  npm run verify-versions # carriers consistent (+ breaking gate when BASE_REF set)
85
- npm run verify-field-map# every v1 field covered by v2
86
92
  npm test # ajv fixture validation + JCS cross-checks
87
93
  go test ./... # jsonschema fixture validation + JCS hash + error catalog
88
94
  ```
@@ -0,0 +1,30 @@
1
+ {
2
+ "schema": 1,
3
+ "date": "2026-10-31",
4
+ "period": "daily",
5
+ "contentHash": "sha256:f952f1607ff1708120c35e7a9551f0691ae747edf2ee959445edcd53bc0edf25",
6
+ "contentHashAlgo": "jcs-sha256-v1",
7
+ "count": 1,
8
+ "degraded": true,
9
+ "repos": [
10
+ {
11
+ "fullName": "acme/widget",
12
+ "url": "https://github.com/acme/widget",
13
+ "latestTag": "v2.0.0",
14
+ "newCount": 1,
15
+ "releases": [
16
+ {
17
+ "id": 0,
18
+ "tag": "v2.0.0",
19
+ "name": "v2.0.0",
20
+ "kind": "release",
21
+ "url": "https://github.com/acme/widget/releases/tag/v2.0.0",
22
+ "prerelease": false,
23
+ "draft": false,
24
+ "summaryZh": "版本 v2.0.0(未获取到变更说明)",
25
+ "summarySource": "original"
26
+ }
27
+ ]
28
+ }
29
+ ]
30
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "schema": 1,
3
+ "date": "2026-10-31",
4
+ "period": "daily",
5
+ "contentHash": "sha256:501d8c4be30af9d1dacdf15b2e48ccd3134cbe439695f7685deea11e00c24de8",
6
+ "contentHashAlgo": "jcs-sha256-v1",
7
+ "count": 0,
8
+ "degraded": false,
9
+ "repos": []
10
+ }
@@ -0,0 +1,53 @@
1
+ {
2
+ "schema": 1,
3
+ "date": "2026-10-31",
4
+ "period": "daily",
5
+ "contentHash": "sha256:6ffddcbca4448be9db6dcdfcc407183516c35ed78001b32c3d567ad8a4b4ff42",
6
+ "contentHashAlgo": "jcs-sha256-v1",
7
+ "coreVersion": "0.5.0",
8
+ "generatedAt": "2026-10-31T13:04:00Z",
9
+ "count": 2,
10
+ "degraded": false,
11
+ "repos": [
12
+ {
13
+ "fullName": "infiniflow/ragflow",
14
+ "url": "https://github.com/infiniflow/ragflow",
15
+ "latestTag": "v1.0.0-rc3",
16
+ "newCount": 1,
17
+ "releases": [
18
+ {
19
+ "id": 428974489,
20
+ "tag": "v1.0.0-rc3",
21
+ "name": "v1.0.0-rc3",
22
+ "kind": "release",
23
+ "publishedAt": "2026-10-30T11:53:15Z",
24
+ "url": "https://github.com/infiniflow/ragflow/releases/tag/v1.0.0-rc3",
25
+ "prerelease": false,
26
+ "draft": false,
27
+ "bodyExcerpt": "1.0.0-rc3 fixes several issues found in rc2.",
28
+ "summaryZh": "新增证据充分性决策模型与 Categorize 组件,兼容 rc2 schema,可直接升级。",
29
+ "summarySource": "model"
30
+ }
31
+ ]
32
+ },
33
+ {
34
+ "fullName": "deepseek-ai/deepseek-harness",
35
+ "url": "https://github.com/deepseek-ai/deepseek-harness",
36
+ "latestTag": "dsh-v0.2.2-alpha.2",
37
+ "newCount": 1,
38
+ "releases": [
39
+ {
40
+ "id": 0,
41
+ "tag": "dsh-v0.2.2-alpha.2",
42
+ "name": "dsh-v0.2.2-alpha.2",
43
+ "kind": "tag",
44
+ "url": "https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.2.2-alpha.2",
45
+ "prerelease": false,
46
+ "draft": false,
47
+ "summaryZh": "发布说明缺失,已回退到 commit 信息。",
48
+ "summarySource": "model"
49
+ }
50
+ ]
51
+ }
52
+ ]
53
+ }
package/gen/ts/index.d.ts CHANGED
@@ -38,11 +38,13 @@ export interface FileArtifact {
38
38
 
39
39
  export interface RunRequest {
40
40
  "ipcSchema": 2;
41
- "command": "run" | "serve" | "config" | "version";
41
+ "command": "run" | "serve" | "config" | "version" | "subscribe";
42
42
  "configPath"?: string;
43
43
  "date"?: string;
44
44
  "dryRun"?: boolean;
45
45
  "outputDir"?: string;
46
+ "action"?: "list" | "add" | "remove";
47
+ "repo"?: string;
46
48
  }
47
49
 
48
50
  export interface RunResult {
@@ -59,6 +61,21 @@ export interface RunResult {
59
61
  "contentHash"?: string;
60
62
  "error"?: ErrorInfo;
61
63
  "warnings"?: Array<string>;
64
+ "usage"?: Usage;
65
+ "releases"?: ReleasesReport;
66
+ [k: string]: unknown;
67
+ }
68
+
69
+ export interface Usage {
70
+ "promptTokens": number;
71
+ "completionTokens": number;
72
+ "totalTokens": number;
73
+ "cachedTokens": number;
74
+ "usageKnown": boolean;
75
+ "calls": number;
76
+ "retries": number;
77
+ "batches": number;
78
+ "cacheHits": number;
62
79
  [k: string]: unknown;
63
80
  }
64
81
 
@@ -77,6 +94,60 @@ export interface State {
77
94
  [k: string]: unknown;
78
95
  }
79
96
 
97
+ export interface ReleaseItem {
98
+ "id": number;
99
+ "tag": string;
100
+ "name": string;
101
+ "kind": "release" | "tag";
102
+ "publishedAt"?: string;
103
+ "url": string;
104
+ "prerelease": boolean;
105
+ "draft": boolean;
106
+ "bodyExcerpt"?: string;
107
+ "summaryZh": string;
108
+ "summarySource": "model" | "original";
109
+ [k: string]: unknown;
110
+ }
111
+
112
+ export interface RepoReleases {
113
+ "fullName": string;
114
+ "url": string;
115
+ "latestTag": string;
116
+ "newCount": number;
117
+ "releases": Array<ReleaseItem>;
118
+ [k: string]: unknown;
119
+ }
120
+
121
+ export interface ReleasesReport {
122
+ "enabled": boolean;
123
+ "repos": number;
124
+ "newReleases": number;
125
+ "summarized"?: number;
126
+ "degraded"?: number;
127
+ "failed"?: number;
128
+ "rateLimited"?: number;
129
+ "skipped"?: number;
130
+ "truncated"?: number;
131
+ "historyTruncated"?: number;
132
+ "durationMs": number;
133
+ "usage": Usage;
134
+ [k: string]: unknown;
135
+ }
136
+
137
+ export interface ReleaseManifestEntry {
138
+ "date": string;
139
+ "period": "daily" | "weekly" | "monthly";
140
+ "count": number;
141
+ "degraded"?: boolean;
142
+ "contentHash": string;
143
+ [k: string]: unknown;
144
+ }
145
+
146
+ export interface SubscriptionList {
147
+ "repos": Array<string>;
148
+ [k: string]: unknown;
149
+ }
150
+
80
151
  export interface ErrorMeta {
81
152
  "retriable": boolean;
82
153
  "description": string;
@@ -97,6 +168,20 @@ export interface Digest {
97
168
  [k: string]: unknown;
98
169
  }
99
170
 
171
+ export interface ReleaseDigest {
172
+ "schema": 1;
173
+ "date": string;
174
+ "period": "daily" | "weekly" | "monthly";
175
+ "contentHash": string;
176
+ "contentHashAlgo": "jcs-sha256-v1";
177
+ "coreVersion"?: string;
178
+ "generatedAt"?: string;
179
+ "count": number;
180
+ "degraded": boolean;
181
+ "repos": Array<RepoReleases>;
182
+ [k: string]: unknown;
183
+ }
184
+
100
185
  export interface VersionInfo {
101
186
  "version": string;
102
187
  "commit": string;
@@ -114,13 +199,18 @@ export declare const fixtures: {
114
199
  degraded: Digest;
115
200
  emptyLang: Digest;
116
201
  missingOptional: Digest;
202
+ releaseNormal: ReleaseDigest;
203
+ releaseDegraded: ReleaseDigest;
204
+ releaseEmpty: ReleaseDigest;
117
205
  };
118
206
  export declare const validators: {
119
207
  runRequest: (value: unknown) => boolean;
120
208
  runResult: (value: unknown) => boolean;
121
209
  digest: (value: unknown) => boolean;
210
+ releases: (value: unknown) => boolean;
211
+ releasesReport: (value: unknown) => boolean;
122
212
  versionInfo: (value: unknown) => boolean;
123
213
  };
124
214
  export declare const rawSchema: {
125
- model: object; ipc: object; digest: object; errors: object; versionInfo: object; api: string;
215
+ model: object; ipc: object; digest: object; releases: object; errors: object; versionInfo: object; api: string;
126
216
  };