@morehao/trendradar-contract 0.3.0 → 0.5.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,6 @@
1
1
  {
2
2
  "name": "@morehao/trendradar-contract",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Language-neutral contract (JSON Schema, fixtures, generated Go & TypeScript types) shared by the trendradar Go core and its DSH plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1,7 +1,7 @@
1
1
  openapi: 3.1.0
2
2
  info:
3
3
  title: trendradar serve API
4
- version: 0.3.0
4
+ version: 0.5.0
5
5
  description: |
6
6
  Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the
7
7
  contract schemas, so the plugin and any web UI consume the same shapes
@@ -123,8 +123,12 @@ paths:
123
123
  operationId: listSubscriptions
124
124
  summary: List the repo subscriptions the core will poll
125
125
  description: |
126
- Read-only. Returns an empty array when the subscription file is missing
127
- or empty. Writing subscriptions stays on the CLI / IPC subscribe command.
126
+ Read-only mirror of the IPC `subscribe list` command: both return the
127
+ same SubscriptionList. `repos` is the legacy field; `items` adds the
128
+ per-repo row detail (latest tag, last summary date, check status) and is
129
+ optional, so an older core still satisfies this schema. Writing
130
+ subscriptions stays on the CLI / IPC subscribe command and is never
131
+ exposed over HTTP.
128
132
  responses:
129
133
  "200":
130
134
  description: Current subscription list
@@ -132,6 +136,47 @@ paths:
132
136
  application/json:
133
137
  schema:
134
138
  $ref: "./releases.v2.json#/$defs/SubscriptionList"
139
+ /api/v2/repos/{owner}/{repo}/releases:
140
+ get:
141
+ operationId: getSubscriptionDoc
142
+ summary: Read one repo's release document
143
+ description: |
144
+ Read-only mirror of the IPC `subscribe releases` command. Returns the
145
+ exact markdown file content (plus the volume index) so a client renders
146
+ what the data repo stores instead of re-summarizing it. `volume`
147
+ defaults to the newest volume. Only repos matching
148
+ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ are served: the path is resolved
149
+ inside the releases document root and never escapes it.
150
+ parameters:
151
+ - name: owner
152
+ in: path
153
+ required: true
154
+ schema:
155
+ type: string
156
+ pattern: "^[A-Za-z0-9_.-]+$"
157
+ - name: repo
158
+ in: path
159
+ required: true
160
+ schema:
161
+ type: string
162
+ pattern: "^[A-Za-z0-9_.-]+$"
163
+ - name: volume
164
+ in: query
165
+ required: false
166
+ schema:
167
+ type: integer
168
+ minimum: 1
169
+ responses:
170
+ "200":
171
+ description: The repo's release document
172
+ content:
173
+ application/json:
174
+ schema:
175
+ $ref: "./releases.v2.json#/$defs/SubscriptionDoc"
176
+ "400":
177
+ description: Malformed owner/repo or non-positive volume
178
+ "404":
179
+ description: The repo has no release document, or that volume is absent
135
180
  /feed.xml:
136
181
  get:
137
182
  operationId: getFeed
@@ -118,15 +118,34 @@
118
118
  "enum": [
119
119
  "list",
120
120
  "add",
121
- "remove"
121
+ "remove",
122
+ "releases"
122
123
  ]
123
124
  },
124
125
  "repo": {
125
126
  "type": "string",
126
- "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
127
+ "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
128
+ "description": "command=subscribe: the target repo for action=add/remove/releases. command=run: with stages including 'releases', analyze only this repository's releases (absent = every subscribed repo)."
129
+ },
130
+ "volume": {
131
+ "type": "integer",
132
+ "minimum": 1,
133
+ "description": "subscribe action=releases only: which volume of the repo's release document to read. Defaults to the newest volume."
134
+ },
135
+ "stages": {
136
+ "type": "array",
137
+ "description": "command=run only: which stages to execute. Absent means every enabled stage (backwards compatible); an explicit list narrows the run, e.g. ['releases'] for a release-only run.",
138
+ "items": {
139
+ "type": "string",
140
+ "enum": [
141
+ "trending",
142
+ "digest",
143
+ "releases"
144
+ ]
145
+ }
127
146
  }
128
147
  },
129
- "description": "Strict request envelope. command=subscribe manages the repo subscription list: action=list needs no repo; action=add/remove require exactly one repo.",
148
+ "description": "Strict request envelope. command=subscribe manages the repo subscription list: action=list needs no repo; action=add/remove require exactly one repo; action=releases requires a repo and may name a volume. command=run may narrow its work with stages; when stages includes 'releases', repo optionally restricts the release analysis to a single repository.",
130
149
  "allOf": [
131
150
  {
132
151
  "if": {
@@ -148,7 +167,8 @@
148
167
  "enum": [
149
168
  "list",
150
169
  "add",
151
- "remove"
170
+ "remove",
171
+ "releases"
152
172
  ]
153
173
  }
154
174
  },
@@ -166,8 +186,17 @@
166
186
  },
167
187
  "then": {
168
188
  "not": {
169
- "required": [
170
- "repo"
189
+ "anyOf": [
190
+ {
191
+ "required": [
192
+ "repo"
193
+ ]
194
+ },
195
+ {
196
+ "required": [
197
+ "volume"
198
+ ]
199
+ }
171
200
  ]
172
201
  }
173
202
  }
@@ -186,6 +215,28 @@
186
215
  "action"
187
216
  ]
188
217
  },
218
+ "then": {
219
+ "required": [
220
+ "repo"
221
+ ],
222
+ "not": {
223
+ "required": [
224
+ "volume"
225
+ ]
226
+ }
227
+ }
228
+ },
229
+ {
230
+ "if": {
231
+ "properties": {
232
+ "action": {
233
+ "const": "releases"
234
+ }
235
+ },
236
+ "required": [
237
+ "action"
238
+ ]
239
+ },
189
240
  "then": {
190
241
  "required": [
191
242
  "repo"
@@ -200,7 +251,57 @@
200
251
  "properties": {
201
252
  "command": {
202
253
  "enum": [
203
- "run",
254
+ "run"
255
+ ]
256
+ }
257
+ },
258
+ "required": [
259
+ "command"
260
+ ]
261
+ },
262
+ "then": {
263
+ "not": {
264
+ "anyOf": [
265
+ {
266
+ "required": [
267
+ "action"
268
+ ]
269
+ },
270
+ {
271
+ "required": [
272
+ "volume"
273
+ ]
274
+ }
275
+ ]
276
+ },
277
+ "allOf": [
278
+ {
279
+ "if": {
280
+ "required": [
281
+ "repo"
282
+ ]
283
+ },
284
+ "then": {
285
+ "required": [
286
+ "stages"
287
+ ],
288
+ "properties": {
289
+ "stages": {
290
+ "contains": {
291
+ "const": "releases"
292
+ }
293
+ }
294
+ }
295
+ }
296
+ }
297
+ ]
298
+ }
299
+ },
300
+ {
301
+ "if": {
302
+ "properties": {
303
+ "command": {
304
+ "enum": [
204
305
  "serve",
205
306
  "config",
206
307
  "version"
@@ -223,10 +324,39 @@
223
324
  "required": [
224
325
  "repo"
225
326
  ]
327
+ },
328
+ {
329
+ "required": [
330
+ "volume"
331
+ ]
226
332
  }
227
333
  ]
228
334
  }
229
335
  }
336
+ },
337
+ {
338
+ "if": {
339
+ "properties": {
340
+ "command": {
341
+ "enum": [
342
+ "subscribe",
343
+ "serve",
344
+ "config",
345
+ "version"
346
+ ]
347
+ }
348
+ },
349
+ "required": [
350
+ "command"
351
+ ]
352
+ },
353
+ "then": {
354
+ "not": {
355
+ "required": [
356
+ "stages"
357
+ ]
358
+ }
359
+ }
230
360
  }
231
361
  ]
232
362
  },
@@ -255,7 +385,8 @@
255
385
  "run",
256
386
  "serve",
257
387
  "config",
258
- "version"
388
+ "version",
389
+ "subscribe"
259
390
  ]
260
391
  },
261
392
  "startedAt": {
@@ -303,6 +434,12 @@
303
434
  },
304
435
  "releases": {
305
436
  "$ref": "releases.v2.json#/$defs/ReleasesReport"
437
+ },
438
+ "subscriptions": {
439
+ "$ref": "releases.v2.json#/$defs/SubscriptionList"
440
+ },
441
+ "subscriptionDoc": {
442
+ "$ref": "releases.v2.json#/$defs/SubscriptionDoc"
306
443
  }
307
444
  }
308
445
  },
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://github.com/morehao/trendradar/contract/schema/releases.v2.json",
4
4
  "title": "trendradar releases v2",
5
- "description": "Repo release subscription documents. ReleaseDigest is the rendered on-disk document; ReleasesReport is the per-run diagnostic carried in RunResult.releases. Token cost lives in ReleasesReport.usage (always present), never in ReleaseDigest, because cost is a property of one run and cannot be reproduced from a stored document.",
5
+ "description": "Repo release subscription documents. ReleaseDigest is the rendered on-disk document; ReleasesReport is the per-run diagnostic carried in RunResult.releases. Token cost lives in ReleasesReport.usage (always present), never in ReleaseDigest, because cost is a property of one run and cannot be reproduced from a stored document. schema=2 adds the per-repo weekly batch summary (repos[].summaryZh + periodStart/periodEnd); the per-item summaryZh stays readable for old documents but is no longer written.",
6
6
  "type": "object",
7
7
  "additionalProperties": true,
8
8
  "required": [
@@ -17,7 +17,7 @@
17
17
  ],
18
18
  "properties": {
19
19
  "schema": {
20
- "const": 1
20
+ "const": 2
21
21
  },
22
22
  "date": {
23
23
  "type": "string",
@@ -66,7 +66,7 @@
66
66
  "ReleaseItem": {
67
67
  "type": "object",
68
68
  "additionalProperties": true,
69
- "description": "One release or tag. kind distinguishes a GitHub release (has notes) from a tag fallback (commit message used as the summary basis).",
69
+ "description": "One release or tag. kind distinguishes a GitHub release (has notes) from a tag fallback (commit message used as the summary basis). summaryZh is optional and no longer written by schema 2: the summary now lives once per repo per week in RepoReleases.summaryZh.",
70
70
  "required": [
71
71
  "id",
72
72
  "tag",
@@ -75,7 +75,6 @@
75
75
  "url",
76
76
  "prerelease",
77
77
  "draft",
78
- "summaryZh",
79
78
  "summarySource"
80
79
  ],
81
80
  "properties": {
@@ -116,7 +115,8 @@
116
115
  "description": "Truncated raw release notes. Untrusted text: display only, never execute."
117
116
  },
118
117
  "summaryZh": {
119
- "type": "string"
118
+ "type": "string",
119
+ "description": "Legacy per-item summary. Still accepted so documents written before schema 2 stay readable; schema 2 writers leave it empty."
120
120
  },
121
121
  "summarySource": {
122
122
  "type": "string",
@@ -130,6 +130,7 @@
130
130
  "RepoReleases": {
131
131
  "type": "object",
132
132
  "additionalProperties": true,
133
+ "description": "One repo's release batch for one summary period. summaryZh covers the whole week in a single model call; periodStart/periodEnd bound that week so a consumer can label it without parsing dates.",
133
134
  "required": [
134
135
  "fullName",
135
136
  "url",
@@ -153,6 +154,18 @@
153
154
  "type": "integer",
154
155
  "minimum": 0
155
156
  },
157
+ "periodStart": {
158
+ "type": "string",
159
+ "format": "date"
160
+ },
161
+ "periodEnd": {
162
+ "type": "string",
163
+ "format": "date"
164
+ },
165
+ "summaryZh": {
166
+ "type": "string",
167
+ "description": "One Chinese summary for every version in this period. Empty when no summary was produced."
168
+ },
156
169
  "releases": {
157
170
  "type": "array",
158
171
  "items": {
@@ -164,10 +177,12 @@
164
177
  "ReleasesReport": {
165
178
  "type": "object",
166
179
  "additionalProperties": true,
167
- "description": "Per-run diagnostic for the releases stage. usage is required and always serialized so a consumer can tell 'nothing spent' (calls=0) from 'spent but not reported' (calls>0 with usageKnown=false).",
180
+ "description": "Per-run diagnostic for the releases stage. usage, checked and changed are required and always serialized so a consumer can tell 'nothing spent / checked / changed' (0) from 'not reported' (missing). checked counts repos the stage examined; changed counts repos that produced a document write.",
168
181
  "required": [
169
182
  "enabled",
170
183
  "repos",
184
+ "checked",
185
+ "changed",
171
186
  "newReleases",
172
187
  "durationMs",
173
188
  "usage"
@@ -180,6 +195,14 @@
180
195
  "type": "integer",
181
196
  "minimum": 0
182
197
  },
198
+ "checked": {
199
+ "type": "integer",
200
+ "minimum": 0
201
+ },
202
+ "changed": {
203
+ "type": "integer",
204
+ "minimum": 0
205
+ },
183
206
  "newReleases": {
184
207
  "type": "integer",
185
208
  "minimum": 0
@@ -257,10 +280,55 @@
257
280
  }
258
281
  }
259
282
  },
283
+ "SubscriptionStatus": {
284
+ "type": "string",
285
+ "description": "Per-repo check state of the most recent weekly release run: baseline (first sighting, no section written), ok (a week section was written), no_change (checked, nothing new), rate_limited / failed (check failed, cursor kept so the next run retries).",
286
+ "enum": [
287
+ "baseline",
288
+ "ok",
289
+ "no_change",
290
+ "rate_limited",
291
+ "failed"
292
+ ]
293
+ },
294
+ "SubscriptionItem": {
295
+ "type": "object",
296
+ "additionalProperties": true,
297
+ "description": "One row of the subscriptions table. Deliberately small: the full markdown lives behind SubscriptionDoc so the list stays under the first-paint payload budget.",
298
+ "required": [
299
+ "fullName",
300
+ "status"
301
+ ],
302
+ "properties": {
303
+ "fullName": {
304
+ "type": "string",
305
+ "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
306
+ },
307
+ "url": {
308
+ "type": "string",
309
+ "format": "uri"
310
+ },
311
+ "latestTag": {
312
+ "type": "string"
313
+ },
314
+ "latestSummaryAt": {
315
+ "type": "string",
316
+ "format": "date",
317
+ "description": "Date of the newest week section (its period end), used as the 'last summary' column."
318
+ },
319
+ "lastCheckedAt": {
320
+ "type": "string",
321
+ "format": "date-time"
322
+ },
323
+ "status": {
324
+ "$ref": "#/$defs/SubscriptionStatus"
325
+ }
326
+ }
327
+ },
260
328
  "SubscriptionList": {
261
329
  "type": "object",
262
330
  "additionalProperties": true,
263
- "description": "Response of GET /api/v2/subscriptions.",
331
+ "description": "Response of GET /api/v2/subscriptions and of the IPC subscribe list command. repos stays the only field old consumers read; items is the additive per-repo detail.",
264
332
  "required": [
265
333
  "repos"
266
334
  ],
@@ -271,6 +339,76 @@
271
339
  "type": "string",
272
340
  "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
273
341
  }
342
+ },
343
+ "items": {
344
+ "type": "array",
345
+ "items": {
346
+ "$ref": "#/$defs/SubscriptionItem"
347
+ }
348
+ }
349
+ }
350
+ },
351
+ "SubscriptionVolume": {
352
+ "type": "object",
353
+ "additionalProperties": true,
354
+ "description": "One volume file of a repo's release document. Every volume is numbered: index N is <repo>-0N.md (zero padded), so the first volume is -01. from/to are the oldest/newest week bounds present in that file.",
355
+ "required": [
356
+ "index",
357
+ "file"
358
+ ],
359
+ "properties": {
360
+ "index": {
361
+ "type": "integer",
362
+ "minimum": 1
363
+ },
364
+ "file": {
365
+ "type": "string",
366
+ "description": "Path relative to the releases document root (e.g. vercel/next.js-01.md)."
367
+ },
368
+ "from": {
369
+ "type": "string",
370
+ "format": "date"
371
+ },
372
+ "to": {
373
+ "type": "string",
374
+ "format": "date"
375
+ },
376
+ "lines": {
377
+ "type": "integer",
378
+ "minimum": 0
379
+ }
380
+ }
381
+ },
382
+ "SubscriptionDoc": {
383
+ "type": "object",
384
+ "additionalProperties": true,
385
+ "description": "Response of the IPC subscribe releases command and of GET /api/v2/repos/{owner}/{repo}/releases. markdown is the exact file content: the panel renders it verbatim (single source of truth, no re-summarizing).",
386
+ "required": [
387
+ "fullName",
388
+ "volume",
389
+ "markdown"
390
+ ],
391
+ "properties": {
392
+ "fullName": {
393
+ "type": "string",
394
+ "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
395
+ },
396
+ "volume": {
397
+ "type": "integer",
398
+ "minimum": 1
399
+ },
400
+ "volumes": {
401
+ "type": "array",
402
+ "items": {
403
+ "$ref": "#/$defs/SubscriptionVolume"
404
+ }
405
+ },
406
+ "updatedAt": {
407
+ "type": "string",
408
+ "format": "date"
409
+ },
410
+ "markdown": {
411
+ "type": "string"
274
412
  }
275
413
  }
276
414
  }
package/version-map.json CHANGED
@@ -34,21 +34,21 @@
34
34
  },
35
35
  "version-info.v2.json": {
36
36
  "wireKey": "contractVersion",
37
- "current": "0.3.0",
37
+ "current": "0.5.0",
38
38
  "breakingBump": [
39
39
  "packageMajor"
40
40
  ]
41
41
  },
42
42
  "api.v2.yaml": {
43
43
  "wireKey": "info.version",
44
- "current": "0.3.0",
44
+ "current": "0.5.0",
45
45
  "breakingBump": [
46
46
  "packageMajor"
47
47
  ]
48
48
  },
49
49
  "releases.v2.json": {
50
50
  "wireKey": null,
51
- "current": 1,
51
+ "current": 2,
52
52
  "propagatesTo": [],
53
53
  "breakingBump": [
54
54
  "packageMajor"