@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/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@morehao/trendradar-contract",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Language-neutral contract (JSON Schema, fixtures, generated Go & TypeScript types) shared by the trendradar Go core and its DSH plugin.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/morehao/trendradar.git",
10
+ "directory": "contract"
11
+ },
12
+ "files": [
13
+ "schema",
14
+ "fixtures",
15
+ "gen/ts",
16
+ "version-map.json",
17
+ "README.md",
18
+ "CHANGELOG.md"
19
+ ],
20
+ "exports": {
21
+ ".": {
22
+ "types": "./gen/ts/index.d.ts",
23
+ "import": "./gen/ts/index.js"
24
+ },
25
+ "./schema/*": "./schema/*",
26
+ "./fixtures/*": "./fixtures/*"
27
+ },
28
+ "types": "./gen/ts/index.d.ts",
29
+ "scripts": {
30
+ "generate": "node scripts/generate.mjs",
31
+ "verify": "node scripts/generate.mjs && git diff --exit-code -- gen contract.gen.go schema",
32
+ "verify-versions": "node scripts/check-versions.mjs",
33
+ "verify-field-map": "node scripts/check-field-map.mjs",
34
+ "test": "node --test test/*.test.mjs",
35
+ "prepack": "npm run verify-versions && npm run verify-field-map"
36
+ },
37
+ "devDependencies": {
38
+ "canonicalize": "5.1.0"
39
+ },
40
+ "dependencies": {
41
+ "ajv": "8.20.0",
42
+ "ajv-formats": "3.0.1"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public",
46
+ "registry": "https://registry.npmjs.org"
47
+ }
48
+ }
@@ -0,0 +1,76 @@
1
+ openapi: 3.1.0
2
+ info:
3
+ title: trendradar serve API
4
+ version: 0.2.0
5
+ description: |
6
+ Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the
7
+ digest.v2 schema, so the plugin can consume the same shape whether data comes
8
+ from the filesystem or over HTTP. Historical v1 digests read from disk are
9
+ normalized to this v2 shape with contentHashAlgo=legacy-struct-marshal-v1.
10
+ servers:
11
+ - url: http://127.0.0.1:8787
12
+ paths:
13
+ /api/v2/digests/{date}:
14
+ get:
15
+ operationId: getDigest
16
+ summary: Fetch one day's digest
17
+ parameters:
18
+ - name: date
19
+ in: path
20
+ required: true
21
+ schema:
22
+ type: string
23
+ format: date
24
+ responses:
25
+ "200":
26
+ description: The digest document
27
+ content:
28
+ application/json:
29
+ schema:
30
+ $ref: "./digest.v2.json"
31
+ "404":
32
+ description: No digest for that date
33
+ /api/v2/manifest:
34
+ get:
35
+ operationId: getManifest
36
+ summary: List available dates and their content identity
37
+ responses:
38
+ "200":
39
+ description: Manifest of available digests
40
+ content:
41
+ application/json:
42
+ schema:
43
+ type: object
44
+ required: [entries]
45
+ properties:
46
+ coreVersion:
47
+ type: string
48
+ entries:
49
+ type: array
50
+ items:
51
+ type: object
52
+ required: [date, contentHash, schema, contentHashAlgo]
53
+ properties:
54
+ date:
55
+ type: string
56
+ format: date
57
+ contentHash:
58
+ type: string
59
+ schema:
60
+ type: integer
61
+ contentHashAlgo:
62
+ type: string
63
+ enum: [jcs-sha256-v1, legacy-struct-marshal-v1]
64
+ degraded:
65
+ type: boolean
66
+ /feed.xml:
67
+ get:
68
+ operationId: getFeed
69
+ summary: RSS feed of the most recent digests
70
+ responses:
71
+ "200":
72
+ description: RSS 2.0 feed
73
+ content:
74
+ application/rss+xml:
75
+ schema:
76
+ type: string
@@ -0,0 +1,25 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/digest.v2.json",
4
+ "title": "trendradar digest v2",
5
+ "description": "One day's rendered digest document. contentHash is stable across runs (generatedAt/coreVersion excluded); contentHashAlgo records which algorithm produced it.",
6
+ "type": "object",
7
+ "additionalProperties": true,
8
+ "required": ["schema", "date", "period", "languages", "count", "degraded", "contentHash", "contentHashAlgo", "repos"],
9
+ "properties": {
10
+ "schema": { "const": 2 },
11
+ "date": { "type": "string", "format": "date" },
12
+ "period": { "type": "string", "enum": ["daily", "weekly", "monthly"] },
13
+ "languages": { "type": "array", "minItems": 1, "items": { "type": "string" } },
14
+ "count": { "type": "integer", "minimum": 0 },
15
+ "degraded": { "type": "boolean" },
16
+ "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
17
+ "contentHashAlgo": { "type": "string", "enum": ["jcs-sha256-v1", "legacy-struct-marshal-v1"] },
18
+ "coreVersion": { "type": "string" },
19
+ "generatedAt": { "type": "string", "format": "date-time" },
20
+ "repos": {
21
+ "type": "array",
22
+ "items": { "$ref": "model.v2.json#/$defs/RepoDigest" }
23
+ }
24
+ }
25
+ }
@@ -0,0 +1,341 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/errors.v2.json",
4
+ "title": "trendradar errors v2",
5
+ "description": "Canonical error-code catalog. Each property is one error code whose retriable/description are consts, so this file is the single source of truth for retriability. ipc.v2.json ErrorCode enum must match these keys exactly.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "INTERNAL",
10
+ "CONFIG_INVALID",
11
+ "PAYLOAD_TOO_LARGE",
12
+ "FETCH_FAILED",
13
+ "FETCH_RATE_LIMITED",
14
+ "PARSE_FAILED",
15
+ "MODEL_UNAUTHORIZED",
16
+ "MODEL_RATE_LIMITED",
17
+ "MODEL_TIMEOUT",
18
+ "MODEL_FAILED",
19
+ "MODEL_BAD_OUTPUT",
20
+ "GIT_NOT_INSTALLED",
21
+ "REPO_NOT_GIT",
22
+ "REPO_DIRTY",
23
+ "GIT_OPERATION_FAILED",
24
+ "PR_FAILED",
25
+ "NOT_MERGEABLE"
26
+ ],
27
+ "properties": {
28
+ "INTERNAL": {
29
+ "type": "object",
30
+ "additionalProperties": false,
31
+ "required": [
32
+ "retriable",
33
+ "description"
34
+ ],
35
+ "properties": {
36
+ "retriable": {
37
+ "const": true
38
+ },
39
+ "description": {
40
+ "const": "Unexpected internal error (transient panic/IO); retry may succeed."
41
+ }
42
+ }
43
+ },
44
+ "CONFIG_INVALID": {
45
+ "type": "object",
46
+ "additionalProperties": false,
47
+ "required": [
48
+ "retriable",
49
+ "description"
50
+ ],
51
+ "properties": {
52
+ "retriable": {
53
+ "const": false
54
+ },
55
+ "description": {
56
+ "const": "Configuration is invalid or unreadable."
57
+ }
58
+ }
59
+ },
60
+ "PAYLOAD_TOO_LARGE": {
61
+ "type": "object",
62
+ "additionalProperties": false,
63
+ "required": [
64
+ "retriable",
65
+ "description"
66
+ ],
67
+ "properties": {
68
+ "retriable": {
69
+ "const": false
70
+ },
71
+ "description": {
72
+ "const": "Input payload exceeds the allowed size."
73
+ }
74
+ }
75
+ },
76
+ "FETCH_FAILED": {
77
+ "type": "object",
78
+ "additionalProperties": false,
79
+ "required": [
80
+ "retriable",
81
+ "description"
82
+ ],
83
+ "properties": {
84
+ "retriable": {
85
+ "const": false
86
+ },
87
+ "description": {
88
+ "const": "Fetching trending data failed terminally (retries exhausted)."
89
+ }
90
+ }
91
+ },
92
+ "FETCH_RATE_LIMITED": {
93
+ "type": "object",
94
+ "additionalProperties": false,
95
+ "required": [
96
+ "retriable",
97
+ "description"
98
+ ],
99
+ "properties": {
100
+ "retriable": {
101
+ "const": true
102
+ },
103
+ "description": {
104
+ "const": "Fetching was rate limited; retry later."
105
+ }
106
+ }
107
+ },
108
+ "PARSE_FAILED": {
109
+ "type": "object",
110
+ "additionalProperties": false,
111
+ "required": [
112
+ "retriable",
113
+ "description"
114
+ ],
115
+ "properties": {
116
+ "retriable": {
117
+ "const": false
118
+ },
119
+ "description": {
120
+ "const": "Parsing fetched HTML/JSON failed."
121
+ }
122
+ }
123
+ },
124
+ "MODEL_UNAUTHORIZED": {
125
+ "type": "object",
126
+ "additionalProperties": false,
127
+ "required": [
128
+ "retriable",
129
+ "description"
130
+ ],
131
+ "properties": {
132
+ "retriable": {
133
+ "const": false
134
+ },
135
+ "description": {
136
+ "const": "Model provider rejected the credentials."
137
+ }
138
+ }
139
+ },
140
+ "MODEL_RATE_LIMITED": {
141
+ "type": "object",
142
+ "additionalProperties": false,
143
+ "required": [
144
+ "retriable",
145
+ "description"
146
+ ],
147
+ "properties": {
148
+ "retriable": {
149
+ "const": true
150
+ },
151
+ "description": {
152
+ "const": "Model provider rate limited the request."
153
+ }
154
+ }
155
+ },
156
+ "MODEL_TIMEOUT": {
157
+ "type": "object",
158
+ "additionalProperties": false,
159
+ "required": [
160
+ "retriable",
161
+ "description"
162
+ ],
163
+ "properties": {
164
+ "retriable": {
165
+ "const": true
166
+ },
167
+ "description": {
168
+ "const": "Model request timed out."
169
+ }
170
+ }
171
+ },
172
+ "MODEL_FAILED": {
173
+ "type": "object",
174
+ "additionalProperties": false,
175
+ "required": [
176
+ "retriable",
177
+ "description"
178
+ ],
179
+ "properties": {
180
+ "retriable": {
181
+ "const": true
182
+ },
183
+ "description": {
184
+ "const": "Model request failed."
185
+ }
186
+ }
187
+ },
188
+ "MODEL_BAD_OUTPUT": {
189
+ "type": "object",
190
+ "additionalProperties": false,
191
+ "required": [
192
+ "retriable",
193
+ "description"
194
+ ],
195
+ "properties": {
196
+ "retriable": {
197
+ "const": false
198
+ },
199
+ "description": {
200
+ "const": "Model returned output that violates the expected shape."
201
+ }
202
+ }
203
+ },
204
+ "GIT_NOT_INSTALLED": {
205
+ "type": "object",
206
+ "additionalProperties": false,
207
+ "required": [
208
+ "retriable",
209
+ "description"
210
+ ],
211
+ "properties": {
212
+ "retriable": {
213
+ "const": false
214
+ },
215
+ "description": {
216
+ "const": "git executable was not found."
217
+ }
218
+ }
219
+ },
220
+ "REPO_NOT_GIT": {
221
+ "type": "object",
222
+ "additionalProperties": false,
223
+ "required": [
224
+ "retriable",
225
+ "description"
226
+ ],
227
+ "properties": {
228
+ "retriable": {
229
+ "const": false
230
+ },
231
+ "description": {
232
+ "const": "Target directory is not a git repository."
233
+ }
234
+ }
235
+ },
236
+ "REPO_DIRTY": {
237
+ "type": "object",
238
+ "additionalProperties": false,
239
+ "required": [
240
+ "retriable",
241
+ "description"
242
+ ],
243
+ "properties": {
244
+ "retriable": {
245
+ "const": false
246
+ },
247
+ "description": {
248
+ "const": "Git working tree has uncommitted changes."
249
+ }
250
+ }
251
+ },
252
+ "GIT_OPERATION_FAILED": {
253
+ "type": "object",
254
+ "additionalProperties": false,
255
+ "required": [
256
+ "retriable",
257
+ "description"
258
+ ],
259
+ "properties": {
260
+ "retriable": {
261
+ "const": true
262
+ },
263
+ "description": {
264
+ "const": "A git operation (commit/push) failed."
265
+ }
266
+ }
267
+ },
268
+ "PR_FAILED": {
269
+ "type": "object",
270
+ "additionalProperties": false,
271
+ "required": [
272
+ "retriable",
273
+ "description"
274
+ ],
275
+ "properties": {
276
+ "retriable": {
277
+ "const": true
278
+ },
279
+ "description": {
280
+ "const": "Opening or updating the pull request failed."
281
+ }
282
+ }
283
+ },
284
+ "NOT_MERGEABLE": {
285
+ "type": "object",
286
+ "additionalProperties": false,
287
+ "required": [
288
+ "retriable",
289
+ "description"
290
+ ],
291
+ "properties": {
292
+ "retriable": {
293
+ "const": false
294
+ },
295
+ "description": {
296
+ "const": "Pull request is not mergeable."
297
+ }
298
+ }
299
+ }
300
+ },
301
+ "$defs": {
302
+ "ErrorCode": {
303
+ "type": "string",
304
+ "enum": [
305
+ "INTERNAL",
306
+ "CONFIG_INVALID",
307
+ "PAYLOAD_TOO_LARGE",
308
+ "FETCH_FAILED",
309
+ "FETCH_RATE_LIMITED",
310
+ "PARSE_FAILED",
311
+ "MODEL_UNAUTHORIZED",
312
+ "MODEL_RATE_LIMITED",
313
+ "MODEL_TIMEOUT",
314
+ "MODEL_FAILED",
315
+ "MODEL_BAD_OUTPUT",
316
+ "GIT_NOT_INSTALLED",
317
+ "REPO_NOT_GIT",
318
+ "REPO_DIRTY",
319
+ "GIT_OPERATION_FAILED",
320
+ "PR_FAILED",
321
+ "NOT_MERGEABLE"
322
+ ]
323
+ },
324
+ "ErrorMeta": {
325
+ "type": "object",
326
+ "additionalProperties": false,
327
+ "required": [
328
+ "retriable",
329
+ "description"
330
+ ],
331
+ "properties": {
332
+ "retriable": {
333
+ "type": "boolean"
334
+ },
335
+ "description": {
336
+ "type": "string"
337
+ }
338
+ }
339
+ }
340
+ }
341
+ }
@@ -0,0 +1,109 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/ipc.v2.json",
4
+ "title": "trendradar ipc v2",
5
+ "description": "Envelope exchanged between the trendradar core binary and the DSH plugin. Only RunRequest forbids extra fields. ipcSchema is const 2.",
6
+ "oneOf": [
7
+ { "$ref": "#/$defs/RunRequest" },
8
+ { "$ref": "#/$defs/RunResult" }
9
+ ],
10
+ "$defs": {
11
+ "ErrorCode": {
12
+ "type": "string",
13
+ "enum": [
14
+ "INTERNAL",
15
+ "CONFIG_INVALID",
16
+ "PAYLOAD_TOO_LARGE",
17
+ "FETCH_FAILED",
18
+ "FETCH_RATE_LIMITED",
19
+ "PARSE_FAILED",
20
+ "MODEL_UNAUTHORIZED",
21
+ "MODEL_RATE_LIMITED",
22
+ "MODEL_TIMEOUT",
23
+ "MODEL_FAILED",
24
+ "MODEL_BAD_OUTPUT",
25
+ "GIT_NOT_INSTALLED",
26
+ "REPO_NOT_GIT",
27
+ "REPO_DIRTY",
28
+ "GIT_OPERATION_FAILED",
29
+ "PR_FAILED",
30
+ "NOT_MERGEABLE"
31
+ ]
32
+ },
33
+ "ErrorInfo": {
34
+ "type": "object",
35
+ "additionalProperties": true,
36
+ "required": ["code", "message", "retriable"],
37
+ "properties": {
38
+ "code": { "$ref": "#/$defs/ErrorCode" },
39
+ "message": { "type": "string" },
40
+ "retriable": { "type": "boolean" },
41
+ "details": { "type": "object", "additionalProperties": true }
42
+ }
43
+ },
44
+ "FileArtifact": {
45
+ "type": "object",
46
+ "additionalProperties": true,
47
+ "required": ["path", "bytes", "sha256"],
48
+ "properties": {
49
+ "path": { "type": "string" },
50
+ "bytes": { "type": "integer", "minimum": 0 },
51
+ "sha256": { "type": "string" }
52
+ }
53
+ },
54
+ "RunRequest": {
55
+ "type": "object",
56
+ "additionalProperties": false,
57
+ "required": ["ipcSchema", "command"],
58
+ "properties": {
59
+ "ipcSchema": { "const": 2 },
60
+ "command": { "type": "string", "enum": ["run", "serve", "config", "version"] },
61
+ "configPath": { "type": "string" },
62
+ "date": { "type": "string", "format": "date" },
63
+ "dryRun": { "type": "boolean" },
64
+ "outputDir": { "type": "string" }
65
+ }
66
+ },
67
+ "RunResult": {
68
+ "type": "object",
69
+ "additionalProperties": true,
70
+ "required": ["ipcSchema", "ok", "command", "startedAt", "finishedAt", "skipped", "files"],
71
+ "properties": {
72
+ "ipcSchema": { "const": 2 },
73
+ "ok": { "type": "boolean" },
74
+ "command": { "type": "string", "enum": ["run", "serve", "config", "version"] },
75
+ "startedAt": { "type": "string", "format": "date-time" },
76
+ "finishedAt": { "type": "string", "format": "date-time" },
77
+ "skipped": { "type": "boolean" },
78
+ "files": { "type": "array", "items": { "$ref": "#/$defs/FileArtifact" } },
79
+ "branch": { "type": "string" },
80
+ "commit": { "type": "string" },
81
+ "prUrl": { "type": "string", "format": "uri" },
82
+ "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
83
+ "error": { "$ref": "#/$defs/ErrorInfo" },
84
+ "warnings": { "type": "array", "items": { "type": "string" } }
85
+ }
86
+ },
87
+ "StateRun": {
88
+ "type": "object",
89
+ "additionalProperties": true,
90
+ "required": ["date", "contentHash", "runAt"],
91
+ "properties": {
92
+ "date": { "type": "string", "format": "date" },
93
+ "contentHash": { "type": "string" },
94
+ "outputDir": { "type": "string" },
95
+ "runAt": { "type": "string", "format": "date-time" }
96
+ }
97
+ },
98
+ "State": {
99
+ "type": "object",
100
+ "additionalProperties": true,
101
+ "required": ["ipcSchema", "stateSchema"],
102
+ "properties": {
103
+ "ipcSchema": { "const": 2 },
104
+ "stateSchema": { "const": 2 },
105
+ "lastRun": { "$ref": "#/$defs/StateRun" }
106
+ }
107
+ }
108
+ }
109
+ }
@@ -0,0 +1,40 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/model.v2.json",
4
+ "title": "trendradar model v2",
5
+ "description": "Domain model: a scraped repository snapshot (RepoSnapshot) and its digested form (RepoDigest). RepoDigest composes RepoSnapshot via allOf instead of flattening.",
6
+ "$ref": "#/$defs/RepoDigest",
7
+ "$defs": {
8
+ "RepoSnapshot": {
9
+ "type": "object",
10
+ "additionalProperties": true,
11
+ "required": ["fullName", "url", "language", "stars", "starsInPeriod", "rank", "source"],
12
+ "properties": {
13
+ "fullName": { "type": "string", "pattern": "^[^/]+/[^/]+$" },
14
+ "url": { "type": "string", "format": "uri" },
15
+ "description": { "type": "string" },
16
+ "language": { "type": "string" },
17
+ "stars": { "type": "integer", "minimum": 0 },
18
+ "starsInPeriod": { "type": "integer", "minimum": 0 },
19
+ "forks": { "type": "integer", "minimum": 0 },
20
+ "rank": { "type": "integer", "minimum": 1 },
21
+ "source": { "type": "string", "enum": ["trending-html", "search-api"] }
22
+ }
23
+ },
24
+ "RepoDigest": {
25
+ "description": "RepoSnapshot plus the digest-only summary fields; the two sub-schemas are merged with allOf.",
26
+ "allOf": [
27
+ { "$ref": "#/$defs/RepoSnapshot" },
28
+ {
29
+ "type": "object",
30
+ "additionalProperties": true,
31
+ "required": ["summaryZh", "summarySource"],
32
+ "properties": {
33
+ "summaryZh": { "type": "string" },
34
+ "summarySource": { "type": "string", "enum": ["model", "original"] }
35
+ }
36
+ }
37
+ ]
38
+ }
39
+ }
40
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/version-info.v2.json",
4
+ "title": "trendradar version info v2",
5
+ "description": "Handshake payload returned by `trendradar version --json`. The plugin requires ipcSchema===2 && digestSchema===2 && contractVersion major===2.",
6
+ "type": "object",
7
+ "additionalProperties": true,
8
+ "required": ["version", "commit", "ipcSchema", "digestSchema", "contractVersion", "supportedProviders"],
9
+ "properties": {
10
+ "version": { "type": "string" },
11
+ "commit": { "type": "string" },
12
+ "ipcSchema": { "const": 2 },
13
+ "digestSchema": { "const": 2 },
14
+ "contractVersion": { "type": "string" },
15
+ "supportedProviders": { "type": "array", "items": { "type": "string" } }
16
+ }
17
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "ipc.v2.json": { "wireKey": "ipcSchema", "current": 2, "breakingBump": ["ipcSchema", "packageMajor"] },
3
+ "digest.v2.json": { "wireKey": "digestSchema", "current": 2, "breakingBump": ["digestSchema", "packageMajor"] },
4
+ "model.v2.json": { "wireKey": null, "current": 2, "propagatesTo": ["digestSchema"], "breakingBump": ["packageMajor"] },
5
+ "errors.v2.json": { "wireKey": null, "current": 2, "breakingBump": ["packageMajor"] },
6
+ "version-info.v2.json": { "wireKey": "contractVersion", "current": "0.2.0", "breakingBump": ["packageMajor"] },
7
+ "api.v2.yaml": { "wireKey": "info.version", "current": "0.2.0", "breakingBump": ["packageMajor"] }
8
+ }