@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 +36 -0
- package/README.md +15 -9
- package/fixtures/release-degraded.json +30 -0
- package/fixtures/release-empty.json +10 -0
- package/fixtures/release-normal.json +53 -0
- package/gen/ts/index.d.ts +92 -2
- package/gen/ts/index.js +553 -5
- package/package.json +2 -3
- package/schema/api.v2.yaml +73 -4
- package/schema/ipc.v2.json +339 -42
- package/schema/releases.v2.json +278 -0
- package/version-map.json +55 -6
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.
|
|
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.
|
|
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.
|
|
24
|
-
go get github.com/morehao/trendradar/contract@v0.
|
|
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
|
|
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.
|
|
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,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
|
};
|