@morehao/trendradar-contract 0.2.0 → 0.4.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,75 @@
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.4.0
11
+
12
+ Weekly release records. The wire integers stay at `ipcSchema = 2` /
13
+ `digestSchema = 2`; `ReleaseDigest.schema` moves 1 → 2. Every field change below
14
+ is additive at the envelope level, so a plugin built against 0.3.0 keeps working.
15
+
16
+ ### Added
17
+ - `SubscriptionList.items[]` (`SubscriptionItem`: `fullName`, `url`,
18
+ `latestTag`, `latestSummaryAt`, `lastCheckedAt`, `status`). `repos` stays the
19
+ only required field, so an older core still satisfies the schema.
20
+ - `SubscriptionDoc` + `SubscriptionVolume`: the exact markdown of one volume of a
21
+ repo's release document plus its volume index (`index`, `file`, `from`, `to`,
22
+ `lines`). Shared by the IPC `subscribe releases` command and
23
+ `GET /api/v2/repos/{owner}/{repo}/releases`.
24
+ - `RunRequest.stages` (`trending|digest|releases`) and `RunRequest.volume`;
25
+ `action` gains `releases` (requires `repo`, optional `volume`).
26
+ - `RunResult.subscriptions` / `RunResult.subscriptionDoc`: the subscribe
27
+ command's payload now rides inside the result envelope instead of stdout.
28
+ `RunResult.command` accepts `subscribe`.
29
+ - `ReleasesReport.checked` / `changed` (both required).
30
+ - Fixtures: `release-weekly.json` (schema-2 weekly shape without per-item
31
+ summaries), `subscriptions-normal.json`, `subscriptions-40.json` (the 10 KB
32
+ first-paint budget), `subscription-doc-normal.json`.
33
+ - `api.v2.yaml`: `GET /api/v2/repos/{owner}/{repo}/releases`.
34
+
35
+ ### Changed
36
+ - `ReleaseDigest.schema` = 2: `RepoReleases` gains `summaryZh`,
37
+ `periodStart`, `periodEnd`; `ReleaseItem.summaryZh` becomes optional (still
38
+ readable for documents written before this version, no longer written).
39
+ - Release fixtures regenerated with `schema: 2` (their `contentHash` changes
40
+ accordingly; the JCS basis is unchanged).
41
+ - The contract test now asserts the 40-repo subscription fixture stays ≤ 10 KB.
42
+
43
+ ## 0.3.0
44
+
45
+ Repo release subscriptions become a first-class contract capability. The wire
46
+ integers stay at `ipcSchema = 2` / `digestSchema = 2`: every addition here is
47
+ backward compatible, so existing plugins keep working without a handshake bump.
48
+
49
+ ### Added
50
+ - `schema/releases.v2.json`: `ReleaseDigest` (the on-disk document, `schema: 1`),
51
+ `RepoReleases`, `ReleaseItem`, plus `ReleasesReport`,
52
+ `ReleaseManifestEntry` and `SubscriptionList`.
53
+ - `RunRequest.command` accepts `subscribe`, with `action`
54
+ (`list|add|remove`) and `repo`. The envelope stays strict
55
+ (`additionalProperties: false`); conditional rules enforce that `list` takes
56
+ no `repo`, `add`/`remove` require one, and non-subscribe commands carry
57
+ neither.
58
+ - `RunResult.releases`: the releases-stage diagnostic, now schema-checked
59
+ instead of riding on `additionalProperties`.
60
+ - `api.v2.yaml`: `GET /api/v2/releases`, `GET /api/v2/releases/{date}` and
61
+ `GET /api/v2/subscriptions` (read-only; empty arrays rather than 404 when no
62
+ data exists).
63
+
64
+ ### Notes
65
+ - **Token cost**: `ReleasesReport.usage` is required and always serialized so a
66
+ consumer can tell "nothing spent" (`calls = 0`) from "spent but the provider
67
+ reported nothing" (`calls > 0` with `usageKnown = false`). Cost is
68
+ deliberately absent from `ReleaseDigest` and from
69
+ `ReleaseManifestEntry`: a stored document describes content, not one run.
70
+ - `ReleaseItem.id` is `int64` in Go (GitHub ids exceed int32 on 32-bit
71
+ platforms) and required (`0` for tag fallbacks).
72
+ - Generated Go/TS names `id` as `ID`; the generator gained an `x-go-type:
73
+ int64` escape hatch and a conditional-`allOf` branch.
74
+
6
75
  ## 0.2.0
7
76
 
8
77
  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.4.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.4.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.4.0
24
+ go get github.com/morehao/trendradar/contract@v0.4.0 # resolves tag contract/v0.4.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,42 @@ 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.4.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`/`volume`, `add`/`remove` require a `repo` and no
73
+ `volume`, `releases` requires a `repo` and may name a `volume`; other commands
74
+ must not carry any of them. `stages` is run-only.
75
+ - `ReleaseDigest.schema` is `2`: the summary moved from per-tag
76
+ (`ReleaseItem.summaryZh`, now optional and no longer written) to one per repo
77
+ per week (`RepoReleases.summaryZh` + `periodStart`/`periodEnd`). Old documents
78
+ still parse; new writers leave the per-item field empty.
79
+ - `ReleasesReport.checked` / `changed` are **required** so `0` ("checked nothing")
80
+ is distinguishable from "not reported".
81
+ - Token cost for releases lives in `ReleasesReport.usage` (always present) and
82
+ **not** in the stored `ReleaseDigest`, because cost describes one run and
83
+ cannot be reproduced from a document.
84
+
85
+ ### IPC ↔ HTTP mirrors
86
+
87
+ Every read-only IPC capability has an HTTP mirror that returns the *same*
88
+ contract type (only the transport envelope differs). Writes are never exposed
89
+ over HTTP; the surface is read-only, `no-store`, and unauthenticated by design
90
+ (bind to `127.0.0.1`).
91
+
92
+ | IPC | HTTP | Status |
93
+ |---|---|---|
94
+ | `subscribe list` (`SubscriptionList`, incl. `items[]`) | `GET /api/v2/subscriptions` | added in 0.4.0 |
95
+ | `subscribe releases --repo` (`SubscriptionDoc`) | `GET /api/v2/repos/{owner}/{repo}/releases?volume=N` | added in 0.4.0 |
96
+ | `run` weekly digest (`ReleaseDigest`) | `GET /api/v2/releases`, `GET /api/v2/releases/{date}` | unchanged since 0.3.0 |
97
+ | `subscribe add/remove` | — | writes stay IPC-only |
98
+
99
+ When adding a read-only IPC command, add its route in the same PR (and a row
100
+ here); when adding a write command, state in the PR why it is not mirrored.
70
101
 
71
102
  ## contentHash
72
103
 
@@ -82,7 +113,6 @@ excluded; optional repo fields omitted when absent). New files use
82
113
  npm ci
83
114
  npm run generate # regenerate contract.gen.go + gen/ts (deterministic, gofmt'd)
84
115
  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
116
  npm test # ajv fixture validation + JCS cross-checks
87
117
  go test ./... # jsonschema fixture validation + JCS hash + error catalog
88
118
  ```
@@ -0,0 +1,33 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-31",
4
+ "period": "weekly",
5
+ "contentHash": "sha256:5f34a40370d022ed06a995e32917a0299a121973ef13eee0e2f1a747a0a6aecb",
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
+ "periodStart": "2026-10-26",
29
+ "periodEnd": "2026-11-01",
30
+ "summaryZh": "本周 1 个版本:v2.0.0。"
31
+ }
32
+ ]
33
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-31",
4
+ "period": "weekly",
5
+ "contentHash": "sha256:e9cd2c19bcaf079d832114be1dff9ce81351d1643c5c6e8efd5da781ef18d5e4",
6
+ "contentHashAlgo": "jcs-sha256-v1",
7
+ "count": 0,
8
+ "degraded": false,
9
+ "repos": []
10
+ }
@@ -0,0 +1,59 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-31",
4
+ "period": "weekly",
5
+ "contentHash": "sha256:87fe3cf94463a7011dbebfbeae9d77544a613751fdd0ba194a6e4534c1bb02ba",
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
+ "periodStart": "2026-10-26",
33
+ "periodEnd": "2026-11-01",
34
+ "summaryZh": "本周 1 个版本:v1.0.0-rc3。"
35
+ },
36
+ {
37
+ "fullName": "deepseek-ai/deepseek-harness",
38
+ "url": "https://github.com/deepseek-ai/deepseek-harness",
39
+ "latestTag": "dsh-v0.2.2-alpha.2",
40
+ "newCount": 1,
41
+ "releases": [
42
+ {
43
+ "id": 0,
44
+ "tag": "dsh-v0.2.2-alpha.2",
45
+ "name": "dsh-v0.2.2-alpha.2",
46
+ "kind": "tag",
47
+ "url": "https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.2.2-alpha.2",
48
+ "prerelease": false,
49
+ "draft": false,
50
+ "summaryZh": "发布说明缺失,已回退到 commit 信息。",
51
+ "summarySource": "model"
52
+ }
53
+ ],
54
+ "periodStart": "2026-10-26",
55
+ "periodEnd": "2026-11-01",
56
+ "summaryZh": "本周 1 个版本:dsh-v0.2.2-alpha.2。"
57
+ }
58
+ ]
59
+ }
@@ -0,0 +1,47 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-11-01",
4
+ "period": "weekly",
5
+ "contentHash": "sha256:0e93b38ea1e36f475161528332375d6e48a7fef1bad6125f96b27358d79b838e",
6
+ "contentHashAlgo": "jcs-sha256-v1",
7
+ "coreVersion": "0.7.0",
8
+ "generatedAt": "2026-11-01T00:30:00Z",
9
+ "count": 2,
10
+ "degraded": false,
11
+ "repos": [
12
+ {
13
+ "fullName": "vercel/next.js",
14
+ "url": "https://github.com/vercel/next.js",
15
+ "latestTag": "v15.2.0",
16
+ "newCount": 2,
17
+ "periodStart": "2026-10-26",
18
+ "periodEnd": "2026-11-01",
19
+ "summaryZh": "本周发布 v15.2.0 与 v15.1.9:构建缓存命中率提升,修复 App Router 下动态段预渲染的回归。",
20
+ "releases": [
21
+ {
22
+ "id": 428974490,
23
+ "tag": "v15.2.0",
24
+ "name": "v15.2.0",
25
+ "kind": "release",
26
+ "publishedAt": "2026-10-29T10:00:00Z",
27
+ "url": "https://github.com/vercel/next.js/releases/tag/v15.2.0",
28
+ "prerelease": false,
29
+ "draft": false,
30
+ "bodyExcerpt": "Faster builds and a fix for dynamic segment prerendering.",
31
+ "summarySource": "model"
32
+ },
33
+ {
34
+ "id": 428974480,
35
+ "tag": "v15.1.9",
36
+ "name": "v15.1.9",
37
+ "kind": "release",
38
+ "publishedAt": "2026-10-27T09:00:00Z",
39
+ "url": "https://github.com/vercel/next.js/releases/tag/v15.1.9",
40
+ "prerelease": false,
41
+ "draft": false,
42
+ "summarySource": "model"
43
+ }
44
+ ]
45
+ }
46
+ ]
47
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "fullName": "vercel/next.js",
3
+ "volume": 1,
4
+ "volumes": [
5
+ {
6
+ "index": 1,
7
+ "file": "vercel/next.js-01.md",
8
+ "from": "2026-10-19",
9
+ "to": "2026-11-01",
10
+ "lines": 18
11
+ },
12
+ {
13
+ "index": 2,
14
+ "file": "vercel/next.js-02.md",
15
+ "from": "2026-09-28",
16
+ "to": "2026-10-18",
17
+ "lines": 412
18
+ }
19
+ ],
20
+ "updatedAt": "2026-11-01",
21
+ "markdown": "# vercel/next.js\n\n> 发版记录 · 每周一次 · 最近更新 2026-11-01\n\n## 2026-10-26 ~ 2026-11-01\n\n- [v15.2.0](https://github.com/vercel/next.js/releases/tag/v15.2.0) · 10-29\n- [v15.1.9](https://github.com/vercel/next.js/releases/tag/v15.1.9) · 10-27\n\n本周发布 v15.2.0 与 v15.1.9:构建缓存命中率提升,修复 App Router 下动态段预渲染的回归。\n"
22
+ }