@scalar/release-notes 0.1.1

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.
Files changed (65) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/LICENSE +21 -0
  3. package/README.md +132 -0
  4. package/dist/cli.d.ts +4 -0
  5. package/dist/cli.d.ts.map +1 -0
  6. package/dist/cli.js +18 -0
  7. package/dist/commands/generate.d.ts +5 -0
  8. package/dist/commands/generate.d.ts.map +1 -0
  9. package/dist/commands/generate.js +105 -0
  10. package/dist/commands/sync-markdown.d.ts +5 -0
  11. package/dist/commands/sync-markdown.d.ts.map +1 -0
  12. package/dist/commands/sync-markdown.js +25 -0
  13. package/dist/config/define-config.d.ts +6 -0
  14. package/dist/config/define-config.d.ts.map +1 -0
  15. package/dist/config/define-config.js +4 -0
  16. package/dist/config/read-config.d.ts +18 -0
  17. package/dist/config/read-config.d.ts.map +1 -0
  18. package/dist/config/read-config.js +86 -0
  19. package/dist/config/types.d.ts +70 -0
  20. package/dist/config/types.d.ts.map +1 -0
  21. package/dist/config/types.js +1 -0
  22. package/dist/core/detect-versioned-changelog-paths.d.ts +5 -0
  23. package/dist/core/detect-versioned-changelog-paths.d.ts.map +1 -0
  24. package/dist/core/detect-versioned-changelog-paths.js +56 -0
  25. package/dist/core/extract-changelog-section.d.ts +5 -0
  26. package/dist/core/extract-changelog-section.d.ts.map +1 -0
  27. package/dist/core/extract-changelog-section.js +16 -0
  28. package/dist/core/fetch-pull-requests.d.ts +28 -0
  29. package/dist/core/fetch-pull-requests.d.ts.map +1 -0
  30. package/dist/core/fetch-pull-requests.js +65 -0
  31. package/dist/core/generate-release-note.d.ts +45 -0
  32. package/dist/core/generate-release-note.d.ts.map +1 -0
  33. package/dist/core/generate-release-note.js +186 -0
  34. package/dist/core/paths.d.ts +7 -0
  35. package/dist/core/paths.d.ts.map +1 -0
  36. package/dist/core/paths.js +13 -0
  37. package/dist/core/products.d.ts +8 -0
  38. package/dist/core/products.d.ts.map +1 -0
  39. package/dist/core/products.js +12 -0
  40. package/dist/core/run-release-notes-generator.d.ts +26 -0
  41. package/dist/core/run-release-notes-generator.d.ts.map +1 -0
  42. package/dist/core/run-release-notes-generator.js +150 -0
  43. package/dist/index.d.ts +22 -0
  44. package/dist/index.d.ts.map +1 -0
  45. package/dist/index.js +15 -0
  46. package/dist/providers/anthropic.d.ts +9 -0
  47. package/dist/providers/anthropic.d.ts.map +1 -0
  48. package/dist/providers/anthropic.js +53 -0
  49. package/dist/providers/openai.d.ts +9 -0
  50. package/dist/providers/openai.d.ts.map +1 -0
  51. package/dist/providers/openai.js +54 -0
  52. package/dist/types.d.ts +129 -0
  53. package/dist/types.d.ts.map +1 -0
  54. package/dist/types.js +167 -0
  55. package/dist/writers/write-release-notes-json.d.ts +15 -0
  56. package/dist/writers/write-release-notes-json.d.ts.map +1 -0
  57. package/dist/writers/write-release-notes-json.js +114 -0
  58. package/dist/writers/write-release-notes-markdown.d.ts +13 -0
  59. package/dist/writers/write-release-notes-markdown.d.ts.map +1 -0
  60. package/dist/writers/write-release-notes-markdown.js +23 -0
  61. package/dist/writers/write-release-notes-schema.d.ts +20 -0
  62. package/dist/writers/write-release-notes-schema.d.ts.map +1 -0
  63. package/dist/writers/write-release-notes-schema.js +37 -0
  64. package/package.json +68 -0
  65. package/schemas/release-notes.schema.json +232 -0
@@ -0,0 +1,53 @@
1
+ const ANTHROPIC_API_URL = 'https://api.anthropic.com/v1/messages';
2
+ const ANTHROPIC_API_VERSION = '2023-06-01';
3
+ const DEFAULT_MODEL = 'claude-sonnet-4-5';
4
+ const extractText = (response) => {
5
+ const block = response.content?.find((entry) => entry.type === 'text' && typeof entry.text === 'string');
6
+ const text = block?.text?.trim() ?? '';
7
+ if (!text) {
8
+ throw new Error('Anthropic response did not include any text content');
9
+ }
10
+ return text;
11
+ };
12
+ export const createAnthropicProvider = (options = {}) => {
13
+ return {
14
+ name: 'anthropic',
15
+ defaultModel: options.model ?? DEFAULT_MODEL,
16
+ generateJson: async ({ model, systemPrompt, userPrompt, maxOutputTokens, signal }) => {
17
+ const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
18
+ if (!apiKey) {
19
+ throw new Error('ANTHROPIC_API_KEY is not set. Pass an API key or configure another provider.');
20
+ }
21
+ const fetchImpl = options.fetchImpl ?? fetch;
22
+ const response = await fetchImpl(ANTHROPIC_API_URL, {
23
+ method: 'POST',
24
+ signal,
25
+ headers: {
26
+ 'content-type': 'application/json',
27
+ 'x-api-key': apiKey,
28
+ 'anthropic-version': ANTHROPIC_API_VERSION,
29
+ },
30
+ body: JSON.stringify({
31
+ model: model ?? options.model ?? DEFAULT_MODEL,
32
+ max_tokens: maxOutputTokens,
33
+ system: systemPrompt,
34
+ messages: [
35
+ {
36
+ role: 'user',
37
+ content: userPrompt,
38
+ },
39
+ ],
40
+ }),
41
+ });
42
+ if (!response.ok) {
43
+ const detail = await response.text().catch(() => '');
44
+ throw new Error(`Anthropic API call failed (${response.status}): ${detail}`);
45
+ }
46
+ const payload = (await response.json());
47
+ if (payload.error?.message) {
48
+ throw new Error(`Anthropic API returned an error: ${payload.error.message}`);
49
+ }
50
+ return extractText(payload);
51
+ },
52
+ };
53
+ };
@@ -0,0 +1,9 @@
1
+ import type { ReleaseNotesProvider } from '../config/types.js';
2
+ type OpenAIProviderOptions = {
3
+ apiKey?: string;
4
+ model?: string;
5
+ fetchImpl?: typeof fetch;
6
+ };
7
+ export declare const createOpenAIProvider: (options?: OpenAIProviderOptions) => ReleaseNotesProvider;
8
+ export {};
9
+ //# sourceMappingURL=openai.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAK3D,KAAK,qBAAqB,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAqBD,eAAO,MAAM,oBAAoB,GAAI,UAAS,qBAA0B,KAAG,oBAgD1E,CAAA"}
@@ -0,0 +1,54 @@
1
+ const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
2
+ const DEFAULT_MODEL = 'gpt-4.1-mini';
3
+ const extractText = (response) => {
4
+ const text = response.choices?.[0]?.message?.content?.trim() ?? '';
5
+ if (!text) {
6
+ throw new Error('OpenAI response did not include any message content');
7
+ }
8
+ return text;
9
+ };
10
+ export const createOpenAIProvider = (options = {}) => {
11
+ return {
12
+ name: 'openai',
13
+ defaultModel: options.model ?? DEFAULT_MODEL,
14
+ generateJson: async ({ model, systemPrompt, userPrompt, maxOutputTokens, signal }) => {
15
+ const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
16
+ if (!apiKey) {
17
+ throw new Error('OPENAI_API_KEY is not set. Pass an API key or configure another provider.');
18
+ }
19
+ const fetchImpl = options.fetchImpl ?? fetch;
20
+ const response = await fetchImpl(OPENAI_API_URL, {
21
+ method: 'POST',
22
+ signal,
23
+ headers: {
24
+ authorization: `Bearer ${apiKey}`,
25
+ 'content-type': 'application/json',
26
+ },
27
+ body: JSON.stringify({
28
+ model: model ?? options.model ?? DEFAULT_MODEL,
29
+ max_tokens: maxOutputTokens,
30
+ response_format: { type: 'json_object' },
31
+ messages: [
32
+ {
33
+ role: 'system',
34
+ content: systemPrompt,
35
+ },
36
+ {
37
+ role: 'user',
38
+ content: userPrompt,
39
+ },
40
+ ],
41
+ }),
42
+ });
43
+ if (!response.ok) {
44
+ const detail = await response.text().catch(() => '');
45
+ throw new Error(`OpenAI API call failed (${response.status}): ${detail}`);
46
+ }
47
+ const payload = (await response.json());
48
+ if (payload.error?.message) {
49
+ throw new Error(`OpenAI API returned an error: ${payload.error.message}`);
50
+ }
51
+ return extractText(payload);
52
+ },
53
+ };
54
+ };
@@ -0,0 +1,129 @@
1
+ import { z } from 'zod';
2
+ declare const contentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
3
+ type: z.ZodLiteral<"paragraph">;
4
+ text: z.ZodString;
5
+ }, z.core.$strip>, z.ZodObject<{
6
+ type: z.ZodLiteral<"heading">;
7
+ text: z.ZodString;
8
+ level: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
9
+ }, z.core.$strip>, z.ZodObject<{
10
+ type: z.ZodLiteral<"list">;
11
+ items: z.ZodArray<z.ZodString>;
12
+ ordered: z.ZodOptional<z.ZodBoolean>;
13
+ }, z.core.$strip>, z.ZodObject<{
14
+ type: z.ZodLiteral<"image">;
15
+ src: z.ZodString;
16
+ alt: z.ZodString;
17
+ caption: z.ZodOptional<z.ZodString>;
18
+ width: z.ZodOptional<z.ZodNumber>;
19
+ height: z.ZodOptional<z.ZodNumber>;
20
+ }, z.core.$strip>, z.ZodObject<{
21
+ type: z.ZodLiteral<"video">;
22
+ src: z.ZodString;
23
+ poster: z.ZodOptional<z.ZodString>;
24
+ caption: z.ZodOptional<z.ZodString>;
25
+ autoplay: z.ZodOptional<z.ZodBoolean>;
26
+ loop: z.ZodOptional<z.ZodBoolean>;
27
+ muted: z.ZodOptional<z.ZodBoolean>;
28
+ controls: z.ZodOptional<z.ZodBoolean>;
29
+ }, z.core.$strip>, z.ZodObject<{
30
+ type: z.ZodLiteral<"href">;
31
+ href: z.ZodString;
32
+ label: z.ZodString;
33
+ }, z.core.$strip>], "type">;
34
+ /**
35
+ * JSON object returned by an AI provider before trusted release metadata is merged in.
36
+ */
37
+ export declare const aiReleaseNoteSchema: z.ZodObject<{
38
+ version: z.ZodString;
39
+ title: z.ZodString;
40
+ description: z.ZodOptional<z.ZodString>;
41
+ highlights: z.ZodOptional<z.ZodArray<z.ZodString>>;
42
+ }, z.core.$strict>;
43
+ export declare const releaseNoteSchema: z.ZodObject<{
44
+ version: z.ZodString;
45
+ date: z.ZodString;
46
+ title: z.ZodString;
47
+ content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
48
+ type: z.ZodLiteral<"paragraph">;
49
+ text: z.ZodString;
50
+ }, z.core.$strip>, z.ZodObject<{
51
+ type: z.ZodLiteral<"heading">;
52
+ text: z.ZodString;
53
+ level: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
54
+ }, z.core.$strip>, z.ZodObject<{
55
+ type: z.ZodLiteral<"list">;
56
+ items: z.ZodArray<z.ZodString>;
57
+ ordered: z.ZodOptional<z.ZodBoolean>;
58
+ }, z.core.$strip>, z.ZodObject<{
59
+ type: z.ZodLiteral<"image">;
60
+ src: z.ZodString;
61
+ alt: z.ZodString;
62
+ caption: z.ZodOptional<z.ZodString>;
63
+ width: z.ZodOptional<z.ZodNumber>;
64
+ height: z.ZodOptional<z.ZodNumber>;
65
+ }, z.core.$strip>, z.ZodObject<{
66
+ type: z.ZodLiteral<"video">;
67
+ src: z.ZodString;
68
+ poster: z.ZodOptional<z.ZodString>;
69
+ caption: z.ZodOptional<z.ZodString>;
70
+ autoplay: z.ZodOptional<z.ZodBoolean>;
71
+ loop: z.ZodOptional<z.ZodBoolean>;
72
+ muted: z.ZodOptional<z.ZodBoolean>;
73
+ controls: z.ZodOptional<z.ZodBoolean>;
74
+ }, z.core.$strip>, z.ZodObject<{
75
+ type: z.ZodLiteral<"href">;
76
+ href: z.ZodString;
77
+ label: z.ZodString;
78
+ }, z.core.$strip>], "type">>>;
79
+ }, z.core.$strip>;
80
+ export declare const releaseNotesFileSchema: z.ZodArray<z.ZodObject<{
81
+ version: z.ZodString;
82
+ date: z.ZodString;
83
+ title: z.ZodString;
84
+ content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
85
+ type: z.ZodLiteral<"paragraph">;
86
+ text: z.ZodString;
87
+ }, z.core.$strip>, z.ZodObject<{
88
+ type: z.ZodLiteral<"heading">;
89
+ text: z.ZodString;
90
+ level: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
91
+ }, z.core.$strip>, z.ZodObject<{
92
+ type: z.ZodLiteral<"list">;
93
+ items: z.ZodArray<z.ZodString>;
94
+ ordered: z.ZodOptional<z.ZodBoolean>;
95
+ }, z.core.$strip>, z.ZodObject<{
96
+ type: z.ZodLiteral<"image">;
97
+ src: z.ZodString;
98
+ alt: z.ZodString;
99
+ caption: z.ZodOptional<z.ZodString>;
100
+ width: z.ZodOptional<z.ZodNumber>;
101
+ height: z.ZodOptional<z.ZodNumber>;
102
+ }, z.core.$strip>, z.ZodObject<{
103
+ type: z.ZodLiteral<"video">;
104
+ src: z.ZodString;
105
+ poster: z.ZodOptional<z.ZodString>;
106
+ caption: z.ZodOptional<z.ZodString>;
107
+ autoplay: z.ZodOptional<z.ZodBoolean>;
108
+ loop: z.ZodOptional<z.ZodBoolean>;
109
+ muted: z.ZodOptional<z.ZodBoolean>;
110
+ controls: z.ZodOptional<z.ZodBoolean>;
111
+ }, z.core.$strip>, z.ZodObject<{
112
+ type: z.ZodLiteral<"href">;
113
+ href: z.ZodString;
114
+ label: z.ZodString;
115
+ }, z.core.$strip>], "type">>>;
116
+ }, z.core.$strip>>;
117
+ type AiReleaseNote = z.infer<typeof aiReleaseNoteSchema>;
118
+ export type ReleaseNoteContentBlock = z.infer<typeof contentBlockSchema>;
119
+ export type ReleaseNote = z.infer<typeof releaseNoteSchema>;
120
+ /**
121
+ * Build a stored release note from validated AI fields and trusted metadata.
122
+ */
123
+ export declare const buildReleaseNoteFromAiOutput: (ai: AiReleaseNote, trusted: {
124
+ version: string;
125
+ date: string;
126
+ href: string;
127
+ }) => ReleaseNote;
128
+ export {};
129
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA8HvB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAS2F,CAAA;AAEnH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;kBAQ4D,CAAA;AAE5F,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAae,CAAA;AAE7C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAEmC,CAAA;AAEtE,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAExD,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;GAEG;AACH,eAAO,MAAM,4BAA4B,GACvC,IAAI,aAAa,EACjB,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACvD,WAmBF,CAAA"}
package/dist/types.js ADDED
@@ -0,0 +1,167 @@
1
+ import { z } from 'zod';
2
+ const versionSchema = z
3
+ .string()
4
+ .regex(/^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/, 'Expected a semver-like version string')
5
+ .describe('Semver-style version string for the release (for example `3.5.1`).');
6
+ const dateSchema = z
7
+ .string()
8
+ .regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected an ISO `YYYY-MM-DD` date')
9
+ .describe('Release date in ISO `YYYY-MM-DD` format.');
10
+ const titleSchema = z.string().min(1).max(120).describe('Short, sentence-case headline summarizing the release.');
11
+ const descriptionSchema = z
12
+ .string()
13
+ .min(1)
14
+ .max(500)
15
+ .describe('Optional one-paragraph summary rendered above any rich content. Mostly used by AI-generated entries; reach for `content` paragraphs when you need rich copy.');
16
+ const highlightItemSchema = z
17
+ .string()
18
+ .min(1)
19
+ .max(280)
20
+ .describe('A single-sentence highlight rendered as a bullet point.');
21
+ const aiHighlightsSchema = z
22
+ .array(highlightItemSchema)
23
+ .max(5)
24
+ .describe('Optional bullet list of single-sentence highlights (at most five items for generated notes).');
25
+ const paragraphBlockSchema = z
26
+ .object({
27
+ type: z.literal('paragraph').describe('Discriminator for the paragraph block type.'),
28
+ text: z
29
+ .string()
30
+ .min(1)
31
+ .max(2000)
32
+ .describe('Plain-text paragraph copy. Use multiple paragraph blocks for multi-paragraph notes.'),
33
+ })
34
+ .describe('A free-form paragraph rendered between other content blocks.');
35
+ const headingBlockSchema = z
36
+ .object({
37
+ type: z.literal('heading').describe('Discriminator for the heading block type.'),
38
+ text: z.string().min(1).max(120).describe('Subsection heading shown inside the release entry.'),
39
+ level: z
40
+ .union([z.literal(3), z.literal(4)])
41
+ .optional()
42
+ .describe('Heading level. Defaults to 3 (rendered below the release title).'),
43
+ })
44
+ .describe('A subsection heading inside a release entry.');
45
+ const listBlockSchema = z
46
+ .object({
47
+ type: z.literal('list').describe('Discriminator for the list block type.'),
48
+ items: z
49
+ .array(z.string().min(1).max(280).describe('A single-sentence list item.'))
50
+ .min(1)
51
+ .max(20)
52
+ .describe('Bullet items rendered as a list. Keep each item to a single sentence.'),
53
+ ordered: z.boolean().optional().describe('Render as a numbered list when `true`. Defaults to a bullet list.'),
54
+ })
55
+ .describe('A bullet (or numbered) list of single-sentence items.');
56
+ const imageBlockSchema = z
57
+ .object({
58
+ type: z.literal('image').describe('Discriminator for the image block type.'),
59
+ src: z.string().url().describe('Absolute URL of the image asset.'),
60
+ alt: z.string().min(1).max(280).describe('Accessibility text. Required - describe what the image shows.'),
61
+ caption: z.string().min(1).max(280).optional().describe('Optional caption rendered beneath the image.'),
62
+ width: z
63
+ .number()
64
+ .int()
65
+ .positive()
66
+ .optional()
67
+ .describe('Optional natural width of the image in pixels. Helps the layout reserve space before the image loads.'),
68
+ height: z
69
+ .number()
70
+ .int()
71
+ .positive()
72
+ .optional()
73
+ .describe('Optional natural height of the image in pixels. Helps the layout reserve space before the image loads.'),
74
+ })
75
+ .describe('An inline image. Provide alt text for accessibility and an optional caption rendered beneath.');
76
+ const videoBlockSchema = z
77
+ .object({
78
+ type: z.literal('video').describe('Discriminator for the video block type.'),
79
+ src: z.string().url().describe('Absolute URL of an MP4/WebM video asset (self-hosted works best).'),
80
+ poster: z
81
+ .string()
82
+ .url()
83
+ .optional()
84
+ .describe('Optional URL of a poster image shown before the video starts playing.'),
85
+ caption: z.string().min(1).max(280).optional().describe('Optional caption rendered beneath the video.'),
86
+ autoplay: z
87
+ .boolean()
88
+ .optional()
89
+ .describe('When `true`, the video starts playing as soon as it is rendered. Pair with `muted: true`.'),
90
+ loop: z.boolean().optional().describe('When `true`, the video loops back to the start when it ends.'),
91
+ muted: z
92
+ .boolean()
93
+ .optional()
94
+ .describe('When `true`, the video is muted. Required for autoplay to work in modern browsers.'),
95
+ controls: z
96
+ .boolean()
97
+ .optional()
98
+ .describe('When `true`, native playback controls are shown. Defaults to `true` when omitted.'),
99
+ })
100
+ .describe('An inline video clip. Self-hosted MP4/WebM URLs work best - autoplay clips should also set `muted: true`.');
101
+ const hrefBlockSchema = z
102
+ .object({
103
+ type: z.literal('href').describe('Discriminator for an outbound URL block.'),
104
+ href: z.string().url().describe('Destination URL (opened in a new tab).'),
105
+ label: z.string().min(1).max(120).describe('Accessible link text (for example "Read full release notes").'),
106
+ })
107
+ .describe('Call-to-action link (for example to full release notes on GitHub).');
108
+ const contentBlockSchema = z
109
+ .discriminatedUnion('type', [
110
+ paragraphBlockSchema,
111
+ headingBlockSchema,
112
+ listBlockSchema,
113
+ imageBlockSchema,
114
+ videoBlockSchema,
115
+ hrefBlockSchema,
116
+ ])
117
+ .describe('Rich content block rendered inside a release note (paragraph, heading, list, image, video, or href).');
118
+ /**
119
+ * JSON object returned by an AI provider before trusted release metadata is merged in.
120
+ */
121
+ export const aiReleaseNoteSchema = z
122
+ .object({
123
+ version: versionSchema,
124
+ title: titleSchema,
125
+ description: descriptionSchema.optional(),
126
+ highlights: aiHighlightsSchema.optional(),
127
+ })
128
+ .strict()
129
+ .describe('Minimal AI-generated release note payload before merge with trusted metadata.');
130
+ export const releaseNoteSchema = z
131
+ .object({
132
+ version: versionSchema,
133
+ date: dateSchema,
134
+ title: titleSchema,
135
+ content: z
136
+ .array(contentBlockSchema)
137
+ .max(40)
138
+ .optional()
139
+ .describe('Body copy and rich blocks after the headline: `paragraph` for intro text, `list` for bullet highlights, then headings, media, and optional `href` blocks.'),
140
+ })
141
+ .describe('A single curated release note.');
142
+ export const releaseNotesFileSchema = z
143
+ .array(releaseNoteSchema)
144
+ .describe('Curated, user-facing release notes. Newest entry first.');
145
+ /**
146
+ * Build a stored release note from validated AI fields and trusted metadata.
147
+ */
148
+ export const buildReleaseNoteFromAiOutput = (ai, trusted) => {
149
+ const content = [];
150
+ if (ai.description !== undefined) {
151
+ content.push({ type: 'paragraph', text: ai.description });
152
+ }
153
+ if (ai.highlights !== undefined && ai.highlights.length > 0) {
154
+ content.push({ type: 'list', items: [...ai.highlights], ordered: false });
155
+ }
156
+ content.push({
157
+ type: 'href',
158
+ href: trusted.href,
159
+ label: 'Read full release notes',
160
+ });
161
+ return releaseNoteSchema.parse({
162
+ version: trusted.version,
163
+ date: trusted.date,
164
+ title: ai.title,
165
+ content,
166
+ });
167
+ };
@@ -0,0 +1,15 @@
1
+ import { type ReleaseNote } from '../types.js';
2
+ export declare const readReleaseNotesJsonFile: (path: string) => Promise<ReleaseNote[]>;
3
+ export declare const mergeReleaseNotes: (existing: readonly ReleaseNote[], next: ReleaseNote) => ReleaseNote[];
4
+ type WriteJsonOptions = {
5
+ path: string;
6
+ note: ReleaseNote;
7
+ };
8
+ type WriteJsonResult = {
9
+ path: string;
10
+ created: boolean;
11
+ entries: ReleaseNote[];
12
+ };
13
+ export declare const writeReleaseNoteJson: (options: WriteJsonOptions) => Promise<WriteJsonResult>;
14
+ export {};
15
+ //# sourceMappingURL=write-release-notes-json.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"write-release-notes-json.d.ts","sourceRoot":"","sources":["../../src/writers/write-release-notes-json.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,UAAU,CAAA;AAiB9D,eAAO,MAAM,wBAAwB,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,WAAW,EAAE,CA6BlF,CAAA;AA2BD,eAAO,MAAM,iBAAiB,GAAI,UAAU,SAAS,WAAW,EAAE,EAAE,MAAM,WAAW,KAAG,WAAW,EAalG,CAAA;AAED,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;CAClB,CAAA;AAED,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,eAAe,CAS7F,CAAA"}
@@ -0,0 +1,114 @@
1
+ import { mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
3
+ import { compareVersions } from '@scalar/helpers/general/compare-versions';
4
+ import { releaseNoteSchema } from '../types.js';
5
+ const parseReleaseNoteEntries = (parsed, pathForLogs) => {
6
+ const valid = [];
7
+ for (const candidate of parsed) {
8
+ const result = releaseNoteSchema.safeParse(candidate);
9
+ if (result.success) {
10
+ valid.push(result.data);
11
+ continue;
12
+ }
13
+ const version = typeof candidate === 'object' && candidate !== null && 'version' in candidate ? String(candidate.version) : '?';
14
+ console.warn(`Skipping malformed entry for version ${version} in ${pathForLogs}: ${result.error.message}`);
15
+ }
16
+ return valid;
17
+ };
18
+ export const readReleaseNotesJsonFile = async (path) => {
19
+ let raw;
20
+ try {
21
+ raw = await readFile(path, 'utf-8');
22
+ }
23
+ catch (error) {
24
+ if (error.code === 'ENOENT') {
25
+ throw new Error(`Release notes JSON not found: ${path}`);
26
+ }
27
+ throw error;
28
+ }
29
+ let parsed;
30
+ try {
31
+ parsed = JSON.parse(raw);
32
+ }
33
+ catch (error) {
34
+ throw new Error(`Could not parse ${path} as JSON: ${error.message}`);
35
+ }
36
+ if (!Array.isArray(parsed)) {
37
+ throw new Error(`Expected ${path} to contain a JSON array of release notes.`);
38
+ }
39
+ const valid = parseReleaseNoteEntries(parsed, path);
40
+ if (parsed.length > 0 && valid.length === 0) {
41
+ throw new Error(`No valid release note entries in ${path} (all ${String(parsed.length)} entries failed validation).`);
42
+ }
43
+ return valid;
44
+ };
45
+ const compareReleaseNoteOrder = (a, b) => {
46
+ const byVersion = compareVersions(b.version, a.version);
47
+ if (byVersion !== 0) {
48
+ return byVersion;
49
+ }
50
+ if (a.date !== b.date) {
51
+ return a.date < b.date ? 1 : -1;
52
+ }
53
+ return 0;
54
+ };
55
+ const lowerBoundInsertIndex = (sorted, next) => {
56
+ let lo = 0;
57
+ let hi = sorted.length;
58
+ while (lo < hi) {
59
+ const mid = (lo + hi) >>> 1;
60
+ if (compareReleaseNoteOrder(sorted[mid], next) < 0) {
61
+ lo = mid + 1;
62
+ }
63
+ else {
64
+ hi = mid;
65
+ }
66
+ }
67
+ return lo;
68
+ };
69
+ export const mergeReleaseNotes = (existing, next) => {
70
+ const filtered = existing.filter((entry) => entry.version !== next.version);
71
+ const insertAt = lowerBoundInsertIndex(filtered, next);
72
+ const merged = new Array(filtered.length + 1);
73
+ for (let j = 0; j < insertAt; j += 1) {
74
+ merged[j] = filtered[j];
75
+ }
76
+ merged[insertAt] = next;
77
+ for (let j = insertAt; j < filtered.length; j += 1) {
78
+ merged[j + 1] = filtered[j];
79
+ }
80
+ return merged;
81
+ };
82
+ export const writeReleaseNoteJson = async (options) => {
83
+ const existing = await readJsonIfExists(options.path);
84
+ const created = existing === null;
85
+ const merged = mergeReleaseNotes(existing ?? [], options.note);
86
+ await mkdir(dirname(options.path), { recursive: true });
87
+ await writeFile(options.path, `${JSON.stringify(merged, null, 2)}\n`, 'utf-8');
88
+ return { path: options.path, created, entries: merged };
89
+ };
90
+ const readJsonIfExists = async (path) => {
91
+ let raw;
92
+ try {
93
+ raw = await readFile(path, 'utf-8');
94
+ }
95
+ catch (error) {
96
+ if (error.code === 'ENOENT') {
97
+ return null;
98
+ }
99
+ throw error;
100
+ }
101
+ let parsed;
102
+ try {
103
+ parsed = JSON.parse(raw);
104
+ }
105
+ catch (error) {
106
+ console.warn(`Could not parse ${path} as JSON; treating as empty. ${error.message}`);
107
+ return [];
108
+ }
109
+ if (!Array.isArray(parsed)) {
110
+ console.warn(`Expected ${path} to contain a JSON array of release notes; treating as empty.`);
111
+ return [];
112
+ }
113
+ return parseReleaseNoteEntries(parsed, path);
114
+ };
@@ -0,0 +1,13 @@
1
+ import type { ReleaseNote } from '../types.js';
2
+ type WriteMarkdownOptions = {
3
+ path: string;
4
+ entries: readonly ReleaseNote[];
5
+ preamble?: string;
6
+ };
7
+ type WriteMarkdownResult = {
8
+ path: string;
9
+ created: boolean;
10
+ };
11
+ export declare const writeReleaseNotesMarkdown: (options: WriteMarkdownOptions) => Promise<WriteMarkdownResult>;
12
+ export {};
13
+ //# sourceMappingURL=write-release-notes-markdown.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"write-release-notes-markdown.d.ts","sourceRoot":"","sources":["../../src/writers/write-release-notes-markdown.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,mBAAmB,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,yBAAyB,GAAU,SAAS,oBAAoB,KAAG,OAAO,CAAC,mBAAmB,CAS1G,CAAA"}
@@ -0,0 +1,23 @@
1
+ import { mkdir, stat, writeFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
3
+ import { buildReleaseNotesPreamble, serializeReleaseNotes, } from '@scalar/helpers/markdown/release-notes';
4
+ export const writeReleaseNotesMarkdown = async (options) => {
5
+ const created = !(await pathExists(options.path));
6
+ const preamble = options.preamble ?? buildReleaseNotesPreamble();
7
+ const next = serializeReleaseNotes(options.entries, { preamble });
8
+ await mkdir(dirname(options.path), { recursive: true });
9
+ await writeFile(options.path, next, 'utf-8');
10
+ return { path: options.path, created };
11
+ };
12
+ const pathExists = async (path) => {
13
+ try {
14
+ await stat(path);
15
+ return true;
16
+ }
17
+ catch (error) {
18
+ if (error.code === 'ENOENT') {
19
+ return false;
20
+ }
21
+ throw error;
22
+ }
23
+ };
@@ -0,0 +1,20 @@
1
+ export declare const DEFAULT_RELEASE_NOTES_SCHEMA_PATH = "schemas/release-notes.schema.json";
2
+ export declare const DEFAULT_RELEASE_NOTES_SCHEMA_ID = "https://scalar.com/schemas/release-notes.schema.json";
3
+ export declare const DEFAULT_RELEASE_NOTES_SCHEMA_TITLE = "Release notes";
4
+ export type ReleaseNotesJsonSchemaMetadata = {
5
+ /** JSON Schema `$id`. */
6
+ id?: string;
7
+ /** JSON Schema title. */
8
+ title?: string;
9
+ };
10
+ export declare const buildReleaseNotesJsonSchema: (options?: ReleaseNotesJsonSchemaMetadata) => Record<string, unknown>;
11
+ type WriteSchemaOptions = ReleaseNotesJsonSchemaMetadata & {
12
+ path: string;
13
+ };
14
+ type WriteSchemaResult = {
15
+ path: string;
16
+ changed: boolean;
17
+ };
18
+ export declare const writeReleaseNotesJsonSchema: (options: WriteSchemaOptions) => Promise<WriteSchemaResult>;
19
+ export {};
20
+ //# sourceMappingURL=write-release-notes-schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"write-release-notes-schema.d.ts","sourceRoot":"","sources":["../../src/writers/write-release-notes-schema.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,iCAAiC,sCAAsC,CAAA;AACpF,eAAO,MAAM,+BAA+B,yDAAyD,CAAA;AACrG,eAAO,MAAM,kCAAkC,kBAAkB,CAAA;AAEjE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,yBAAyB;IACzB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAI,UAAS,8BAAmC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAYhH,CAAA;AAED,KAAK,kBAAkB,GAAG,8BAA8B,GAAG;IACzD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,iBAAiB,CAmBxG,CAAA"}
@@ -0,0 +1,37 @@
1
+ import { mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
3
+ import { z } from 'zod';
4
+ import { releaseNotesFileSchema } from '../types.js';
5
+ export const DEFAULT_RELEASE_NOTES_SCHEMA_PATH = 'schemas/release-notes.schema.json';
6
+ export const DEFAULT_RELEASE_NOTES_SCHEMA_ID = 'https://scalar.com/schemas/release-notes.schema.json';
7
+ export const DEFAULT_RELEASE_NOTES_SCHEMA_TITLE = 'Release notes';
8
+ export const buildReleaseNotesJsonSchema = (options = {}) => {
9
+ const schema = z.toJSONSchema(releaseNotesFileSchema, {
10
+ target: 'draft-2020-12',
11
+ unrepresentable: 'any',
12
+ });
13
+ return {
14
+ $schema: 'https://json-schema.org/draft/2020-12/schema',
15
+ $id: options.id ?? DEFAULT_RELEASE_NOTES_SCHEMA_ID,
16
+ title: options.title ?? DEFAULT_RELEASE_NOTES_SCHEMA_TITLE,
17
+ ...schema,
18
+ };
19
+ };
20
+ export const writeReleaseNotesJsonSchema = async (options) => {
21
+ const next = `${JSON.stringify(buildReleaseNotesJsonSchema(options), null, 2)}\n`;
22
+ let previous = null;
23
+ try {
24
+ previous = await readFile(options.path, 'utf-8');
25
+ }
26
+ catch (error) {
27
+ if (error.code !== 'ENOENT') {
28
+ throw error;
29
+ }
30
+ }
31
+ if (previous === next) {
32
+ return { path: options.path, changed: false };
33
+ }
34
+ await mkdir(dirname(options.path), { recursive: true });
35
+ await writeFile(options.path, next, 'utf-8');
36
+ return { path: options.path, changed: true };
37
+ };