@morehao/trendradar-contract 0.0.0-stage → 0.2.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,23 @@
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
+ ## 0.2.0
7
+
8
+ Initial v2 contract (breaking re-baseline; no v1 wire compatibility).
9
+
10
+ - `ipcSchema = 2`, `digestSchema = 2`; new `contractVersion` handshake.
11
+ - `RunResult` gains optional `branch` / `commit` / `prUrl` / `contentHash`; errors
12
+ flow through `ErrorInfo` instead of stderr text.
13
+ - `Digest` gains `contentHashAlgo` (`jcs-sha256-v1` | `legacy-struct-marshal-v1`).
14
+ - `contentHash` computed with RFC 8785 JCS + sha256 (Go/TS identical).
15
+ - `RepoDigest` composes `RepoSnapshot` via `allOf` (Go: embedded struct).
16
+ - New `errors.v2.json` (17 codes with retriable/description) and `ErrorCatalog`.
17
+ - `VersionInfo` moves into the contract with `contractVersion` + `supportedProviders`.
18
+ - `serve` HTTP moves to `/api/v2/digests/{date}` and `/api/v2/manifest`.
19
+
20
+ ### Consumers
21
+
22
+ - core: pair with core `0.3.0` (first run re-renders; `state.json` re-baselined).
23
+ - plugin: pair with plugin `0.2.0` (`lastDigest`/`pendingPr` reset on first run).
package/README.md CHANGED
@@ -1,3 +1,91 @@
1
- # Temporary Holding Version
1
+ # @morehao/trendradar-contract (0.2.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.2.0` (its first public release), 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.2.0
24
+ go get github.com/morehao/trendradar/contract@v0.2.0 # resolves tag contract/v0.2.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/errors.v2.json` | 17 error codes with `retriable`/`description` (single source of truth) |
35
+ | `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`) |
38
+ | `version-map.json` | schema file → version carrier → propagation |
39
+ | `contract.gen.go` | generated Go structs + `ErrorCode` + `ErrorCatalog` + `SchemaFS` |
40
+ | `gen/ts/index.{js,d.ts}` | generated TS types + runtime (`validators`, `errorCatalog`, `fixtures`, `rawSchema`) |
41
+
42
+ ## TypeScript usage
43
+
44
+ ```ts
45
+ import { validators, fixtures, errorCatalog, type Digest, type RunResult } from '@morehao/trendradar-contract'
46
+
47
+ validators.digest(fixtures.normal) // => true (ajv, draft 2020-12 + formats)
48
+ errorCatalog.FETCH_RATE_LIMITED.retriable // => true
49
+ ```
50
+
51
+ ## Go usage
52
+
53
+ ```go
54
+ import contract "github.com/morehao/trendradar/contract"
55
+
56
+ var _ contract.RunResult
57
+ contract.ErrorCatalog[contract.ErrorCodeREPO_DIRTY].Retriable // => false
58
+ contract.SchemaFS // embedded schema/* files
59
+ ```
60
+
61
+ ## Versioning & compatibility
62
+
63
+ - `ipcSchema` (const 2) and `digestSchema` (const 2) are the wire integers;
64
+ `contractVersion` (`"0.2.0"`) is the package handshake.
65
+ - Adding an **optional** field is a minor change. Removing/renaming a field,
66
+ changing a type, or tightening validation is **breaking**: bump the affected
67
+ wire integer and/or the package version, declared in `version-map.json`.
68
+ `make verify-versions` enforces this against the PR base.
69
+ - `RunRequest` is the only strict object (`additionalProperties: false`).
70
+
71
+ ## contentHash
72
+
73
+ `contentHash` = `sha256(JCS({schema,date,period,languages,count,degraded,repos}))`
74
+ (RFC 8785 JCS; `generatedAt`/`coreVersion`/`contentHash`/`contentHashAlgo`
75
+ excluded; optional repo fields omitted when absent). New files use
76
+ `contentHashAlgo: "jcs-sha256-v1"`; historical v1 digests normalized on read use
77
+ `"legacy-struct-marshal-v1"` with their original `contentHash` preserved.
78
+
79
+ ## Development
80
+
81
+ ```bash
82
+ npm ci
83
+ npm run generate # regenerate contract.gen.go + gen/ts (deterministic, gofmt'd)
84
+ 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
+ npm test # ajv fixture validation + JCS cross-checks
87
+ go test ./... # jsonschema fixture validation + JCS hash + error catalog
88
+ ```
89
+
90
+ Generated files (`contract.gen.go`, `gen/ts/*`) are committed; CI fails if they
91
+ 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,126 @@
1
+ // Code generated by scripts/generate.mjs; DO NOT EDIT.
2
+
3
+ export interface RepoSnapshot {
4
+ "fullName": string;
5
+ "url": string;
6
+ "description"?: string;
7
+ "language": string;
8
+ "stars": number;
9
+ "starsInPeriod": number;
10
+ "forks"?: number;
11
+ "rank": number;
12
+ "source": "trending-html" | "search-api";
13
+ [k: string]: unknown;
14
+ }
15
+
16
+ export type RepoDigest = RepoSnapshot & {
17
+ "summaryZh": string;
18
+ "summarySource": "model" | "original";
19
+ [k: string]: unknown;
20
+ };
21
+
22
+ export type ErrorCode = "INTERNAL" | "CONFIG_INVALID" | "PAYLOAD_TOO_LARGE" | "FETCH_FAILED" | "FETCH_RATE_LIMITED" | "PARSE_FAILED" | "MODEL_UNAUTHORIZED" | "MODEL_RATE_LIMITED" | "MODEL_TIMEOUT" | "MODEL_FAILED" | "MODEL_BAD_OUTPUT" | "GIT_NOT_INSTALLED" | "REPO_NOT_GIT" | "REPO_DIRTY" | "GIT_OPERATION_FAILED" | "PR_FAILED" | "NOT_MERGEABLE";
23
+
24
+ export interface ErrorInfo {
25
+ "code": ErrorCode;
26
+ "message": string;
27
+ "retriable": boolean;
28
+ "details"?: { [k: string]: unknown };
29
+ [k: string]: unknown;
30
+ }
31
+
32
+ export interface FileArtifact {
33
+ "path": string;
34
+ "bytes": number;
35
+ "sha256": string;
36
+ [k: string]: unknown;
37
+ }
38
+
39
+ export interface RunRequest {
40
+ "ipcSchema": 2;
41
+ "command": "run" | "serve" | "config" | "version";
42
+ "configPath"?: string;
43
+ "date"?: string;
44
+ "dryRun"?: boolean;
45
+ "outputDir"?: string;
46
+ }
47
+
48
+ export interface RunResult {
49
+ "ipcSchema": 2;
50
+ "ok": boolean;
51
+ "command": "run" | "serve" | "config" | "version";
52
+ "startedAt": string;
53
+ "finishedAt": string;
54
+ "skipped": boolean;
55
+ "files": Array<FileArtifact>;
56
+ "branch"?: string;
57
+ "commit"?: string;
58
+ "prUrl"?: string;
59
+ "contentHash"?: string;
60
+ "error"?: ErrorInfo;
61
+ "warnings"?: Array<string>;
62
+ [k: string]: unknown;
63
+ }
64
+
65
+ export interface StateRun {
66
+ "date": string;
67
+ "contentHash": string;
68
+ "outputDir"?: string;
69
+ "runAt": string;
70
+ [k: string]: unknown;
71
+ }
72
+
73
+ export interface State {
74
+ "ipcSchema": 2;
75
+ "stateSchema": 2;
76
+ "lastRun"?: StateRun;
77
+ [k: string]: unknown;
78
+ }
79
+
80
+ export interface ErrorMeta {
81
+ "retriable": boolean;
82
+ "description": string;
83
+ }
84
+
85
+ export interface Digest {
86
+ "schema": 2;
87
+ "date": string;
88
+ "period": "daily" | "weekly" | "monthly";
89
+ "languages": Array<string>;
90
+ "count": number;
91
+ "degraded": boolean;
92
+ "contentHash": string;
93
+ "contentHashAlgo": "jcs-sha256-v1" | "legacy-struct-marshal-v1";
94
+ "coreVersion"?: string;
95
+ "generatedAt"?: string;
96
+ "repos": Array<RepoDigest>;
97
+ [k: string]: unknown;
98
+ }
99
+
100
+ export interface VersionInfo {
101
+ "version": string;
102
+ "commit": string;
103
+ "ipcSchema": 2;
104
+ "digestSchema": 2;
105
+ "contractVersion": string;
106
+ "supportedProviders": Array<string>;
107
+ [k: string]: unknown;
108
+ }
109
+
110
+ export declare const contractVersion: string;
111
+ export declare const errorCatalog: Record<ErrorCode, { retriable: boolean; description: string }>;
112
+ export declare const fixtures: {
113
+ normal: Digest;
114
+ degraded: Digest;
115
+ emptyLang: Digest;
116
+ missingOptional: Digest;
117
+ };
118
+ export declare const validators: {
119
+ runRequest: (value: unknown) => boolean;
120
+ runResult: (value: unknown) => boolean;
121
+ digest: (value: unknown) => boolean;
122
+ versionInfo: (value: unknown) => boolean;
123
+ };
124
+ export declare const rawSchema: {
125
+ model: object; ipc: object; digest: object; errors: object; versionInfo: object; api: string;
126
+ };