@morehao/trendradar-contract 0.0.0-stage → 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 ADDED
@@ -0,0 +1,59 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@morehao/trendradar-contract` are documented here.
4
+ This project adheres to a `contract/vX.Y.Z` tag per release (npm + Go submodule).
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
+
42
+ ## 0.2.0
43
+
44
+ Initial v2 contract (breaking re-baseline; no v1 wire compatibility).
45
+
46
+ - `ipcSchema = 2`, `digestSchema = 2`; new `contractVersion` handshake.
47
+ - `RunResult` gains optional `branch` / `commit` / `prUrl` / `contentHash`; errors
48
+ flow through `ErrorInfo` instead of stderr text.
49
+ - `Digest` gains `contentHashAlgo` (`jcs-sha256-v1` | `legacy-struct-marshal-v1`).
50
+ - `contentHash` computed with RFC 8785 JCS + sha256 (Go/TS identical).
51
+ - `RepoDigest` composes `RepoSnapshot` via `allOf` (Go: embedded struct).
52
+ - New `errors.v2.json` (17 codes with retriable/description) and `ErrorCatalog`.
53
+ - `VersionInfo` moves into the contract with `contractVersion` + `supportedProviders`.
54
+ - `serve` HTTP moves to `/api/v2/digests/{date}` and `/api/v2/manifest`.
55
+
56
+ ### Consumers
57
+
58
+ - core: pair with core `0.3.0` (first run re-renders; `state.json` re-baselined).
59
+ - plugin: pair with plugin `0.2.0` (`lastDigest`/`pendingPr` reset on first run).
package/README.md CHANGED
@@ -1,3 +1,97 @@
1
- # Temporary Holding Version
1
+ # @morehao/trendradar-contract (0.3.0)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The single source of truth for the data shapes shared by the **trendradar Go
4
+ core** (`github.com/morehao/trendradar`) and the **DSH plugin**
5
+ (`@morehao/dsh-github-trending`).
6
+
7
+ This package lives inside the core repository at `contract/` and ships two
8
+ artifacts from one tag:
9
+
10
+ - an **npm package** `@morehao/trendradar-contract` (types + ajv validators + fixtures), and
11
+ - a **nested Go module** `github.com/morehao/trendradar/contract` (structs + error catalog + embedded schemas).
12
+
13
+ Both are released together by the tag `contract/v0.Y.Z` (see `CHANGELOG.md`).
14
+
15
+ > Version model: the **package** is `0.3.0`, while the
16
+ > **wire format** it carries is the second generation — `ipcSchema=2`,
17
+ > `digestSchema=2`. The integers 2 distinguish this contract from the legacy
18
+ > in-repo v1; they are intentionally decoupled from the package semver.
19
+
20
+ ## Install
21
+
22
+ ```bash
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
+ ```
26
+
27
+ ## Layout
28
+
29
+ | Path | Purpose |
30
+ |---|---|
31
+ | `schema/model.v2.json` | `RepoSnapshot`; `RepoDigest` composes it via `allOf` |
32
+ | `schema/ipc.v2.json` | `RunRequest` (strict), `RunResult`, `ErrorInfo`, `State`, `FileArtifact` |
33
+ | `schema/digest.v2.json` | rendered digest document, incl. `contentHashAlgo` |
34
+ | `schema/releases.v2.json` | release-subscription document + `ReleasesReport` (run cost) |
35
+ | `schema/errors.v2.json` | 17 error codes with `retriable`/`description` (single source of truth) |
36
+ | `schema/version-info.v2.json` | `trendradar version --json` handshake |
37
+ | `schema/api.v2.yaml` | `trendradar serve` OpenAPI (`/api/v2`, incl. releases) |
38
+ | `fixtures/*.json` | golden v2 digests + release documents |
39
+ | `version-map.json` | schema file → version carrier → propagation |
40
+ | `contract.gen.go` | generated Go structs + `ErrorCode` + `ErrorCatalog` + `SchemaFS` |
41
+ | `gen/ts/index.{js,d.ts}` | generated TS types + runtime (`validators`, `errorCatalog`, `fixtures`, `rawSchema`) |
42
+
43
+ ## TypeScript usage
44
+
45
+ ```ts
46
+ import { validators, fixtures, errorCatalog, type Digest, type RunResult } from '@morehao/trendradar-contract'
47
+
48
+ validators.digest(fixtures.normal) // => true (ajv, draft 2020-12 + formats)
49
+ errorCatalog.FETCH_RATE_LIMITED.retriable // => true
50
+ ```
51
+
52
+ ## Go usage
53
+
54
+ ```go
55
+ import contract "github.com/morehao/trendradar/contract"
56
+
57
+ var _ contract.RunResult
58
+ contract.ErrorCatalog[contract.ErrorCodeREPO_DIRTY].Retriable // => false
59
+ contract.SchemaFS // embedded schema/* files
60
+ ```
61
+
62
+ ## Versioning & compatibility
63
+
64
+ - `ipcSchema` (const 2) and `digestSchema` (const 2) are the wire integers;
65
+ `contractVersion` (`"0.3.0"`) is the package handshake.
66
+ - Adding an **optional** field is a minor change. Removing/renaming a field,
67
+ changing a type, or tightening validation is **breaking**: bump the affected
68
+ wire integer and/or the package version, declared in `version-map.json`.
69
+ `make verify-versions` enforces this against the PR base.
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.
77
+
78
+ ## contentHash
79
+
80
+ `contentHash` = `sha256(JCS({schema,date,period,languages,count,degraded,repos}))`
81
+ (RFC 8785 JCS; `generatedAt`/`coreVersion`/`contentHash`/`contentHashAlgo`
82
+ excluded; optional repo fields omitted when absent). New files use
83
+ `contentHashAlgo: "jcs-sha256-v1"`; historical v1 digests normalized on read use
84
+ `"legacy-struct-marshal-v1"` with their original `contentHash` preserved.
85
+
86
+ ## Development
87
+
88
+ ```bash
89
+ npm ci
90
+ npm run generate # regenerate contract.gen.go + gen/ts (deterministic, gofmt'd)
91
+ npm run verify-versions # carriers consistent (+ breaking gate when BASE_REF set)
92
+ npm test # ajv fixture validation + JCS cross-checks
93
+ go test ./... # jsonschema fixture validation + JCS hash + error catalog
94
+ ```
95
+
96
+ Generated files (`contract.gen.go`, `gen/ts/*`) are committed; CI fails if they
97
+ drift from `schema/`.
@@ -0,0 +1,43 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-30",
4
+ "period": "daily",
5
+ "languages": [
6
+ "all",
7
+ "go"
8
+ ],
9
+ "count": 2,
10
+ "degraded": true,
11
+ "contentHash": "sha256:a21dfa56cbd2fe611c9e7b9844d672b3608922156bf8e998f49f4293ab5ce3e3",
12
+ "contentHashAlgo": "jcs-sha256-v1",
13
+ "coreVersion": "0.1.0",
14
+ "generatedAt": "2026-10-30T00:05:00Z",
15
+ "repos": [
16
+ {
17
+ "fullName": "golang/go",
18
+ "url": "https://github.com/golang/go",
19
+ "description": "The Go programming language",
20
+ "language": "go",
21
+ "stars": 126000,
22
+ "starsInPeriod": 0,
23
+ "forks": 17800,
24
+ "rank": 1,
25
+ "source": "search-api",
26
+ "summaryZh": "[原文] The Go programming language",
27
+ "summarySource": "original"
28
+ },
29
+ {
30
+ "fullName": "gin-gonic/gin",
31
+ "url": "https://github.com/gin-gonic/gin",
32
+ "description": "HTTP web framework written in Go",
33
+ "language": "go",
34
+ "stars": 80200,
35
+ "starsInPeriod": 0,
36
+ "forks": 8100,
37
+ "rank": 2,
38
+ "source": "search-api",
39
+ "summaryZh": "[原文] HTTP web framework written in Go",
40
+ "summarySource": "original"
41
+ }
42
+ ]
43
+ }
@@ -0,0 +1,43 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-30",
4
+ "period": "daily",
5
+ "languages": [
6
+ "all",
7
+ "unknown"
8
+ ],
9
+ "count": 2,
10
+ "degraded": false,
11
+ "contentHash": "sha256:84a5ef479995ae104544dfc0869227442f3d8968c0d27b5f76410040d4c8b2e4",
12
+ "contentHashAlgo": "jcs-sha256-v1",
13
+ "coreVersion": "0.1.0",
14
+ "generatedAt": "2026-10-30T00:05:00Z",
15
+ "repos": [
16
+ {
17
+ "fullName": "someorg/no-language",
18
+ "url": "https://github.com/someorg/no-language",
19
+ "description": "A repo whose primary language could not be detected",
20
+ "language": "unknown",
21
+ "stars": 1200,
22
+ "starsInPeriod": 40,
23
+ "forks": 30,
24
+ "rank": 1,
25
+ "source": "trending-html",
26
+ "summaryZh": "语言未知的仓库,热度进入榜单。",
27
+ "summarySource": "model"
28
+ },
29
+ {
30
+ "fullName": "someorg/aggregate-only",
31
+ "url": "https://github.com/someorg/aggregate-only",
32
+ "description": "Repo surfaced only in the all-languages list",
33
+ "language": "unknown",
34
+ "stars": 980,
35
+ "starsInPeriod": 33,
36
+ "forks": 12,
37
+ "rank": 2,
38
+ "source": "trending-html",
39
+ "summaryZh": "仅在全局榜单出现的仓库。",
40
+ "summarySource": "model"
41
+ }
42
+ ]
43
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-30",
4
+ "period": "daily",
5
+ "languages": [
6
+ "all",
7
+ "go",
8
+ "python",
9
+ "rust"
10
+ ],
11
+ "count": 2,
12
+ "degraded": false,
13
+ "contentHash": "sha256:38c38188602424014a7fdd8a3bfd0408690ce8a5db21be9c8559ac3ca85b2b4c",
14
+ "contentHashAlgo": "jcs-sha256-v1",
15
+ "coreVersion": "0.1.0",
16
+ "generatedAt": "2026-10-30T00:05:00Z",
17
+ "repos": [
18
+ {
19
+ "fullName": "golang/go",
20
+ "url": "https://github.com/golang/go",
21
+ "language": "go",
22
+ "stars": 126000,
23
+ "starsInPeriod": 320,
24
+ "rank": 1,
25
+ "source": "trending-html",
26
+ "summaryZh": "Go 官方仓库,今日新增 star 位居榜单前列。",
27
+ "summarySource": "model"
28
+ },
29
+ {
30
+ "fullName": "gin-gonic/gin",
31
+ "url": "https://github.com/gin-gonic/gin",
32
+ "language": "go",
33
+ "stars": 80200,
34
+ "starsInPeriod": 210,
35
+ "rank": 2,
36
+ "source": "trending-html",
37
+ "summaryZh": "流行的 Go Web 框架,热度持续。",
38
+ "summarySource": "model"
39
+ }
40
+ ]
41
+ }
@@ -0,0 +1,97 @@
1
+ {
2
+ "schema": 2,
3
+ "date": "2026-10-30",
4
+ "period": "daily",
5
+ "languages": [
6
+ "all",
7
+ "go",
8
+ "python",
9
+ "rust"
10
+ ],
11
+ "count": 6,
12
+ "degraded": false,
13
+ "contentHash": "sha256:a4769ff29cd41f2f85703c20faf9104a7f8b34500295d991f0b87786719544b2",
14
+ "contentHashAlgo": "jcs-sha256-v1",
15
+ "coreVersion": "0.1.0",
16
+ "generatedAt": "2026-10-30T00:05:00Z",
17
+ "repos": [
18
+ {
19
+ "fullName": "golang/go",
20
+ "url": "https://github.com/golang/go",
21
+ "description": "The Go programming language",
22
+ "language": "go",
23
+ "stars": 126000,
24
+ "starsInPeriod": 320,
25
+ "forks": 17800,
26
+ "rank": 1,
27
+ "source": "trending-html",
28
+ "summaryZh": "Go 官方仓库,今日新增 star 位居榜单前列。",
29
+ "summarySource": "model"
30
+ },
31
+ {
32
+ "fullName": "gin-gonic/gin",
33
+ "url": "https://github.com/gin-gonic/gin",
34
+ "description": "HTTP web framework written in Go",
35
+ "language": "go",
36
+ "stars": 80200,
37
+ "starsInPeriod": 210,
38
+ "forks": 8100,
39
+ "rank": 2,
40
+ "source": "trending-html",
41
+ "summaryZh": "流行的 Go Web 框架,热度持续。",
42
+ "summarySource": "model"
43
+ },
44
+ {
45
+ "fullName": "python/cpython",
46
+ "url": "https://github.com/python/cpython",
47
+ "description": "The Python programming language",
48
+ "language": "python",
49
+ "stars": 64500,
50
+ "starsInPeriod": 180,
51
+ "forks": 30500,
52
+ "rank": 3,
53
+ "source": "trending-html",
54
+ "summaryZh": "CPython 官方实现,今日关注度上升。",
55
+ "summarySource": "model"
56
+ },
57
+ {
58
+ "fullName": "psf/requests",
59
+ "url": "https://github.com/psf/requests",
60
+ "description": "A simple, yet elegant HTTP library",
61
+ "language": "python",
62
+ "stars": 52500,
63
+ "starsInPeriod": 95,
64
+ "forks": 9400,
65
+ "rank": 4,
66
+ "source": "trending-html",
67
+ "summaryZh": "经典 Python HTTP 库,稳居热榜。",
68
+ "summarySource": "model"
69
+ },
70
+ {
71
+ "fullName": "rust-lang/rust",
72
+ "url": "https://github.com/rust-lang/rust",
73
+ "description": "Empowering everyone to build reliable and efficient software",
74
+ "language": "rust",
75
+ "stars": 102000,
76
+ "starsInPeriod": 260,
77
+ "forks": 13200,
78
+ "rank": 5,
79
+ "source": "trending-html",
80
+ "summaryZh": "Rust 语言主仓库,社区活跃。",
81
+ "summarySource": "model"
82
+ },
83
+ {
84
+ "fullName": "tokio-rs/tokio",
85
+ "url": "https://github.com/tokio-rs/tokio",
86
+ "description": "A runtime for writing reliable asynchronous applications with Rust",
87
+ "language": "rust",
88
+ "stars": 28600,
89
+ "starsInPeriod": 120,
90
+ "forks": 2650,
91
+ "rank": 6,
92
+ "source": "trending-html",
93
+ "summaryZh": "Rust 异步运行时,性能方向关注度高。",
94
+ "summarySource": "model"
95
+ }
96
+ ]
97
+ }
@@ -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
+ }