@alauda/doom 0.6.2 → 0.6.3

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.
@@ -82,9 +82,11 @@ const getCommonConfig = async (config, cliRoot, prefix, configFilePath, version,
82
82
  referencePlugin({
83
83
  base,
84
84
  root,
85
+ lang: fallbackToZh ? null : (config.lang ?? 'en'),
85
86
  localBasePath: configFilePath ? path.dirname(configFilePath) : root,
86
87
  items: config.reference,
87
88
  force,
89
+ releaseNotes: config.releaseNotes,
88
90
  }),
89
91
  shikiPlugin({
90
92
  langs: ['dockerfile', 'html', 'go', 'jsonc'],
@@ -1,9 +1,11 @@
1
1
  import type { RspressPlugin } from '@rspress/core';
2
- import type { ReferenceItem } from './types.js';
3
- export declare const referencePlugin: ({ base, root, localBasePath, items, force, }: {
2
+ import type { ReferenceItem, ReleaseNotesOptions } from './types.js';
3
+ export declare const referencePlugin: ({ base, root, lang, localBasePath, items, force, releaseNotes, }: {
4
4
  base: string;
5
5
  root: string;
6
+ lang: string | null;
6
7
  localBasePath: string;
7
8
  items?: ReferenceItem[];
8
9
  force?: boolean;
10
+ releaseNotes?: ReleaseNotesOptions;
9
11
  }) => RspressPlugin;
@@ -1,16 +1,11 @@
1
1
  import fs from 'node:fs/promises';
2
- import remarkGfm from 'remark-gfm';
3
- import remarkMdx from 'remark-mdx';
4
- import remarkParse from 'remark-parse';
2
+ import { logger } from '@rspress/shared/logger';
5
3
  import remarkStringify from 'remark-stringify';
6
- import { unified } from 'unified';
7
4
  import { remarkPluginNormalizeLink } from './remark-normalize-link.js';
8
- import { maybeHaveRef, refCache, remarkReplace } from './remark-replace.js';
5
+ import { maybeHaveRef, remarkReplace } from './remark-replace.js';
9
6
  import { remarkPluginToc } from './remark-toc.js';
10
- import { normalizeReferenceItems } from './utils.js';
11
- const mdProcessor = unified().use(remarkParse).use(remarkGfm);
12
- const mdxProcessor = mdProcessor().use(remarkMdx);
13
- export const referencePlugin = ({ base, root, localBasePath, items = [], force, }) => {
7
+ import { mdProcessor, mdxProcessor, normalizeReferenceItems } from './utils.js';
8
+ export const referencePlugin = ({ base, root, lang, localBasePath, items = [], force, releaseNotes, }) => {
14
9
  const normalizedItems = normalizeReferenceItems(items);
15
10
  return {
16
11
  name: 'doom-reference',
@@ -19,8 +14,11 @@ export const referencePlugin = ({ base, root, localBasePath, items = [], force,
19
14
  [
20
15
  remarkReplace,
21
16
  {
17
+ lang,
22
18
  localBasePath,
19
+ root,
23
20
  items: normalizedItems,
21
+ releaseNotes,
24
22
  force,
25
23
  },
26
24
  ],
@@ -29,25 +27,43 @@ export const referencePlugin = ({ base, root, localBasePath, items = [], force,
29
27
  ],
30
28
  },
31
29
  async modifySearchIndexData(pages) {
32
- refCache.clear();
33
- for (const page of pages) {
30
+ const results = await Promise.allSettled(pages.map(async (page) => {
34
31
  const filepath = page._filepath;
35
32
  if (!/\.mdx?$/.test(filepath)) {
36
- continue;
33
+ return;
37
34
  }
38
35
  const content = await fs.readFile(filepath, 'utf8');
39
36
  if (!maybeHaveRef(filepath, content)) {
40
- continue;
37
+ return;
41
38
  }
42
- const processor = filepath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
43
- const vfile = await processor()
44
- .use(remarkReplace, { localBasePath, items: normalizedItems, force })
45
- .use(remarkStringify)
46
- .process({
39
+ const processor = filepath.endsWith('.mdx')
40
+ ? mdxProcessor
41
+ : mdProcessor;
42
+ const compiler = processor()
43
+ .use(remarkReplace, {
44
+ lang,
45
+ localBasePath,
46
+ root,
47
+ items: normalizedItems,
48
+ force,
49
+ releaseNotes,
50
+ })
51
+ .use(remarkPluginToc)
52
+ .use(remarkStringify);
53
+ compiler.data('pageMeta', {});
54
+ const vfile = await compiler.process({
47
55
  path: filepath,
48
56
  value: content,
49
57
  });
58
+ const { toc, title } = compiler.data('pageMeta');
59
+ page.title = title;
60
+ page.toc = toc;
50
61
  page.content = vfile.toString();
62
+ }));
63
+ for (const result of results) {
64
+ if (result.status === 'rejected') {
65
+ logger.error(result.reason);
66
+ }
51
67
  }
52
68
  },
53
69
  };
@@ -1,14 +1,14 @@
1
- import type { Content, Root } from 'mdast';
1
+ import type { Root } from 'mdast';
2
2
  import { type Plugin } from 'unified';
3
- import { NormalizedReferenceSource } from './types.js';
4
- export declare const MD_REF_PATTERN: RegExp;
5
- export declare const MDX_REF_PATTERN: RegExp;
3
+ import type { NormalizedReferenceSource, ReleaseNotesOptions } from './types.js';
6
4
  export declare const maybeHaveRef: (filepath: string, content: string) => boolean;
7
- export declare const refCache: Map<string, Content[] | undefined>;
8
5
  export declare const remarkReplace: Plugin<[
9
6
  {
7
+ lang: string | null;
10
8
  localBasePath: string;
9
+ root: string;
11
10
  items: Record<string, NormalizedReferenceSource>;
12
11
  force?: boolean;
12
+ releaseNotes?: ReleaseNotesOptions;
13
13
  }
14
14
  ], Root>;
@@ -2,16 +2,20 @@ import fs from 'node:fs/promises';
2
2
  import os from 'node:os';
3
3
  import path from 'node:path';
4
4
  import { logger } from '@rspress/shared/logger';
5
- import remarkGfm from 'remark-gfm';
6
- import remarkMdx from 'remark-mdx';
7
- import remarkParse from 'remark-parse';
5
+ import { render } from 'ejs';
8
6
  import { simpleGit } from 'simple-git';
9
- import { unified } from 'unified';
10
7
  import { cyan, red } from 'yoctocolors';
11
8
  import { parseToc } from './remark-toc.js';
12
- import { flatMap } from './utils.js';
9
+ import { flatMap, mdProcessor, mdxProcessor } from './utils.js';
13
10
  const remotesFolder = path.resolve(os.homedir(), '.doom/remotes');
14
- const resolveReference = async (localBasePath, source, force) => {
11
+ const refCache = new Map();
12
+ const resolveReference_ = async (localBasePath, items, refName, force) => {
13
+ // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
14
+ if (!items[refName]) {
15
+ logger.error(`Reference \`${red(refName)}\` not found`);
16
+ return;
17
+ }
18
+ const source = items[refName];
15
19
  let sourcePath = source.path;
16
20
  if (source.repo) {
17
21
  const repoFolder = path.resolve(remotesFolder, source.slug);
@@ -53,10 +57,7 @@ const resolveReference = async (localBasePath, source, force) => {
53
57
  if (!found) {
54
58
  logger.error(`Reference path \`${red(source.path)}\` for \`${red(source.name)}\` not found`);
55
59
  }
56
- const processor = unified().use(remarkParse).use(remarkGfm);
57
- if (sourcePath.endsWith('.mdx')) {
58
- processor.use(remarkMdx);
59
- }
60
+ const processor = sourcePath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
60
61
  const root = processor.parse(await fs.readFile(sourcePath));
61
62
  if (!source.anchor) {
62
63
  return root.children;
@@ -82,40 +83,144 @@ const resolveReference = async (localBasePath, source, force) => {
82
83
  }
83
84
  return nodes;
84
85
  };
85
- export const MD_REF_PATTERN = /<!-{2,} reference-include#(.*?) -{2,}>/;
86
- export const MDX_REF_PATTERN = /\/\*+ reference-include#(.*?) \*+\//;
87
- export const maybeHaveRef = (filepath, content) => (filepath.endsWith('.mdx') ? MDX_REF_PATTERN : MD_REF_PATTERN).test(content);
88
- export const refCache = new Map();
89
- export const remarkReplace = function ({ localBasePath, items, force }) {
90
- return async (root, vfile) => {
86
+ const resolveReference = async (localBasePath, items, refName, force) => {
87
+ if (refCache.has(refName)) {
88
+ return refCache.get(refName);
89
+ }
90
+ const resolving = resolveReference_(localBasePath, items, refName, force);
91
+ refCache.set(refName, resolving);
92
+ return resolving;
93
+ };
94
+ const releaseCache = new Map();
95
+ const FIELD_MAPPER = {
96
+ zh: 'customfield_13800',
97
+ en: 'customfield_13801',
98
+ };
99
+ const { JIRA_TOKEN, JIRA_USERNAME, JIRA_PASSWORD } = process.env;
100
+ const issuesToMdast = (issues, lang) => {
101
+ return issues
102
+ .map((issue) => {
103
+ const description = ((lang !== 'en' && issue.fields[FIELD_MAPPER[lang]]) ||
104
+ issue.fields[FIELD_MAPPER.en])?.trim();
105
+ if (!description) {
106
+ return;
107
+ }
108
+ return {
109
+ type: 'listItem',
110
+ children: [
111
+ {
112
+ type: 'paragraph',
113
+ children: description
114
+ .split('\n')
115
+ .map((line) => {
116
+ return {
117
+ type: 'text',
118
+ value: line,
119
+ };
120
+ })
121
+ .reduce((acc, curr, index) => {
122
+ if (index === 0) {
123
+ return [curr];
124
+ }
125
+ return acc.concat({ type: 'html', value: '<br>' }, curr);
126
+ }, []),
127
+ },
128
+ ],
129
+ };
130
+ })
131
+ .filter((_) => !!_);
132
+ };
133
+ const resolveRelease_ = async (releaseTemplates, releaseQuery) => {
134
+ const query = new URLSearchParams(releaseQuery);
135
+ const templateName = query.get('template');
136
+ if (!templateName) {
137
+ logger.error(`Release notes template not found in query \`${red(releaseQuery)}\``);
138
+ return;
139
+ }
140
+ const template = releaseTemplates[templateName];
141
+ if (!template) {
142
+ logger.error(`Release notes template \`${red(templateName)}\` not found`);
143
+ return;
144
+ }
145
+ let Authorization;
146
+ if (JIRA_TOKEN) {
147
+ Authorization = `Bearer ${JIRA_TOKEN}`;
148
+ }
149
+ else if (JIRA_USERNAME && JIRA_PASSWORD) {
150
+ Authorization = `Basic ${Buffer.from(`${JIRA_USERNAME}:${JIRA_PASSWORD}`).toString('base64')}`;
151
+ }
152
+ else {
153
+ throw new Error('`JIRA_TOKEN` or `JIRA_USERNAME` and `JIRA_PASSWORD` environments must be set for fetching Jira issues');
154
+ }
155
+ const data = {};
156
+ for (const [key, value] of query.entries()) {
157
+ if (key === 'template') {
158
+ continue;
159
+ }
160
+ data[key] = value;
161
+ }
162
+ const jql = await render(template, data, { async: true });
163
+ logger.info(`Fetching release notes for query \`${cyan(releaseQuery)}\``);
164
+ const res = await fetch(`https://jira.alauda.cn/rest/api/2/search?${new URLSearchParams({ jql })}`, { headers: { Authorization } });
165
+ if (!res.ok) {
166
+ logger.error(`Failed to fetch release notes for query \`${red(releaseQuery)}\` with status \`${res.status}\``);
167
+ return;
168
+ }
169
+ const { issues } = (await res.json());
170
+ return ['en', 'zh'].reduce((acc, curr) => Object.assign(acc, {
171
+ [curr]: { type: 'list', children: issuesToMdast(issues, curr) },
172
+ }), {});
173
+ };
174
+ const resolveRelease = async (releaseTemplates, releaseQuery, lang) => {
175
+ if (releaseCache.has(releaseQuery)) {
176
+ const cached = await releaseCache.get(releaseQuery);
177
+ return cached?.[lang] ?? cached?.en;
178
+ }
179
+ const resolving = resolveRelease_(releaseTemplates, releaseQuery);
180
+ releaseCache.set(releaseQuery, resolving);
181
+ const resolved = await resolving;
182
+ return resolved?.[lang] ?? resolved?.en;
183
+ };
184
+ const MD_REF_COMMENT_PATTERN = /<!-{2,} *reference-include#(.+) *-{2,}>/;
185
+ const MDX_REF_COMMENT_PATTERN = /{\/\*+ *reference-include#(.+) *\*+\/}/;
186
+ const MDX_REF_PATTERN = /\/\*+ *reference-include#(.+) \*+\//;
187
+ const MD_RELEASE_COMMENT_PATTERN = /<!-{2,} *release-notes-for-bugs\?(.+) *-{2,}>/;
188
+ const MDX_RELEASE_COMMENT_PATTERN = /{\/\*+ *release-notes-for-bugs\?(.+) *\*+\/}/;
189
+ const MDX_RELEASE_PATTERN = /\/\*+ *release-notes-for-bugs\?(.+) *\*+\//;
190
+ export const maybeHaveRef = (filepath, content) => (filepath.endsWith('.mdx')
191
+ ? [MDX_REF_COMMENT_PATTERN, MDX_RELEASE_COMMENT_PATTERN]
192
+ : [MD_REF_COMMENT_PATTERN, MD_RELEASE_COMMENT_PATTERN]).some((p) => p.test(content));
193
+ export const remarkReplace = function ({ lang, localBasePath, root, items, force, releaseNotes }) {
194
+ return async (ast, vfile) => {
91
195
  const filepath = vfile.path;
92
196
  const content = vfile.toString();
93
197
  if (!maybeHaveRef(filepath, content)) {
94
198
  return;
95
199
  }
96
- return flatMap(root, async (node) => {
97
- let matched = null;
200
+ const relativePath = path.relative(root, filepath);
201
+ const currLang = lang === null ? 'zh' : relativePath.split('/')[0];
202
+ return flatMap(ast, async (node) => {
203
+ let refMatched = null;
204
+ let releaseMatched = null;
98
205
  if (node.type === 'html') {
99
- matched = node.value.match(MD_REF_PATTERN);
206
+ refMatched = node.value.match(MD_REF_COMMENT_PATTERN);
207
+ releaseMatched = node.value.match(MD_RELEASE_COMMENT_PATTERN);
100
208
  }
101
209
  else if (node.type === 'mdxFlowExpression') {
102
- matched = node.value.match(MDX_REF_PATTERN);
210
+ refMatched = node.value.match(MDX_REF_PATTERN);
211
+ releaseMatched = node.value.match(MDX_RELEASE_PATTERN);
103
212
  }
104
- const name = matched?.[1];
105
- if (!name) {
213
+ else {
106
214
  return;
107
215
  }
108
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
109
- if (!items[name]) {
110
- logger.error(`Reference \`${red(name)}\` not found`);
111
- return;
216
+ const refName = refMatched?.[1];
217
+ const releaseQuery = releaseMatched?.[1];
218
+ if (refName) {
219
+ return resolveReference(localBasePath, items, refName.trim(), force);
112
220
  }
113
- if (refCache.has(name)) {
114
- return refCache.get(name);
221
+ if (releaseNotes?.queryTemplates && releaseQuery) {
222
+ return resolveRelease(releaseNotes.queryTemplates, releaseQuery.trim(), currLang);
115
223
  }
116
- const resolved = await resolveReference(localBasePath, items[name], force);
117
- refCache.set(name, resolved);
118
- return resolved;
119
224
  });
120
225
  };
121
226
  };
@@ -12,3 +12,13 @@ export interface NormalizedReferenceSource extends ReferenceItemSource {
12
12
  slug?: string;
13
13
  anchor?: string;
14
14
  }
15
+ export interface ReleaseNotesOptions {
16
+ queryTemplates: Record<string, string>;
17
+ }
18
+ export interface JiraIssue {
19
+ expand: string;
20
+ id: string;
21
+ self: string;
22
+ key: string;
23
+ fields: Partial<Record<string, string>>;
24
+ }
@@ -1,6 +1,6 @@
1
- import type { Root, Parent } from 'mdast';
2
- import type { Node } from 'unist';
1
+ import type { Parent, Root } from 'mdast';
3
2
  import type { MdxjsEsm } from 'mdast-util-mdxjs-esm';
3
+ import type { Node } from 'unist';
4
4
  import type { NormalizedReferenceSource, ReferenceItem } from './types.js';
5
5
  /**
6
6
  * hello world {#custom-id} -> { text: 'hello world', id: 'custom-id' }
@@ -9,3 +9,5 @@ export declare const extractTextAndId: (title: string) => string[];
9
9
  export declare const normalizeReferenceItems: (items: ReferenceItem[]) => Record<string, NormalizedReferenceSource>;
10
10
  export declare const flatMap: (root: Root, fn: (node: Node, index: number, parent: Parent | null) => Promise<Node | Node[] | undefined> | Node | Node[] | undefined) => Promise<Root>;
11
11
  export declare const getASTNodeImport: (name: string, from: string) => MdxjsEsm;
12
+ export declare const mdProcessor: import("unified").FrozenProcessor<Root, Root, Root, void>;
13
+ export declare const mdxProcessor: import("unified").FrozenProcessor<Root, Root, Root, void>;
@@ -1,4 +1,9 @@
1
1
  import { logger } from '@rspress/shared/logger';
2
+ import remarkFrontmatter from 'remark-frontmatter';
3
+ import remarkGfm from 'remark-gfm';
4
+ import remarkMdx from 'remark-mdx';
5
+ import remarkParse from 'remark-parse';
6
+ import { unified } from 'unified';
2
7
  import { red } from 'yoctocolors';
3
8
  /**
4
9
  * hello world {#custom-id} -> { text: 'hello world', id: 'custom-id' }
@@ -86,3 +91,9 @@ export const getASTNodeImport = (name, from) => ({
86
91
  },
87
92
  },
88
93
  });
94
+ export const mdProcessor = unified()
95
+ .use(remarkParse)
96
+ .use(remarkFrontmatter)
97
+ .use(remarkGfm)
98
+ .freeze();
99
+ export const mdxProcessor = mdProcessor().use(remarkMdx).freeze();
@@ -1,11 +1,12 @@
1
1
  import { UserConfig } from '@rspress/core';
2
2
  import type { ApiPluginOptions } from '../plugins/api/types.js';
3
3
  import type { AutoSidebarPluginOptions } from '../plugins/index.js';
4
- import type { ReferenceItem } from '../plugins/reference/types.js';
4
+ import type { ReferenceItem, ReleaseNotesOptions } from '../plugins/reference/types.js';
5
5
  import type { DoomSite } from '../shared/index.js';
6
6
  export interface DoomConfig extends UserConfig {
7
7
  api?: ApiPluginOptions;
8
8
  sites?: DoomSite[];
9
9
  reference?: ReferenceItem[];
10
10
  sidebar?: AutoSidebarPluginOptions;
11
+ releaseNotes?: ReleaseNotesOptions;
11
12
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.6.2",
3
+ "version": "0.6.3",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -52,6 +52,7 @@
52
52
  "openapi-types": "^12.1.3",
53
53
  "react-markdown": "^8.0.7",
54
54
  "rehype-raw": "^6.1.1",
55
+ "remark-frontmatter": "^4.0.1",
55
56
  "remark-gfm": "^3.0.1",
56
57
  "shiki": "^1.26.1",
57
58
  "simple-git": "^3.27.0",