@zenfs/devel 0.0.1 → 1.0.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.
Files changed (105) hide show
  1. package/dist/bin/make-index.js +37 -74
  2. package/dist/bin/node-compat.d.ts +2 -0
  3. package/dist/bin/node-compat.js +337 -0
  4. package/dist/bin/zci.js +33 -44
  5. package/dist/bin/zenfs-test.js +48 -80
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +1 -0
  8. package/dist/make_index.d.ts +20 -0
  9. package/dist/make_index.js +49 -0
  10. package/dist/node_compat/analysis.d.ts +53 -0
  11. package/dist/node_compat/analysis.js +60 -0
  12. package/dist/node_compat/changelog.d.ts +25 -0
  13. package/dist/node_compat/changelog.js +60 -0
  14. package/dist/node_compat/commits.d.ts +26 -0
  15. package/dist/node_compat/commits.js +66 -0
  16. package/dist/node_compat/config.d.ts +6 -0
  17. package/dist/node_compat/config.js +18 -0
  18. package/dist/node_compat/docs.d.ts +58 -0
  19. package/dist/node_compat/docs.js +213 -0
  20. package/dist/node_compat/git.d.ts +22 -0
  21. package/dist/node_compat/git.js +74 -0
  22. package/dist/node_compat/index.d.ts +10 -0
  23. package/dist/node_compat/index.js +11 -0
  24. package/dist/node_compat/node.d.ts +42 -0
  25. package/dist/node_compat/node.js +84 -0
  26. package/dist/node_compat/output.d.ts +29 -0
  27. package/dist/node_compat/output.js +95 -0
  28. package/dist/node_compat/pr.d.ts +59 -0
  29. package/dist/node_compat/pr.js +125 -0
  30. package/dist/node_compat/state.d.ts +18 -0
  31. package/dist/node_compat/state.js +12 -0
  32. package/dist/node_compat/versions.d.ts +5 -0
  33. package/dist/node_compat/versions.js +13 -0
  34. package/dist/node_compat/zenfs.d.ts +3 -0
  35. package/dist/node_compat/zenfs.js +108 -0
  36. package/dist/tests/common.js +1 -1
  37. package/dist/tests/fs/append.test.d.ts +1 -0
  38. package/dist/tests/fs/append.test.js +27 -0
  39. package/dist/tests/fs/concurrency.test.d.ts +1 -0
  40. package/dist/tests/fs/concurrency.test.js +76 -0
  41. package/dist/tests/fs/dir.test.d.ts +1 -0
  42. package/dist/tests/fs/dir.test.js +83 -0
  43. package/dist/tests/fs/directory.test.d.ts +1 -0
  44. package/dist/tests/fs/directory.test.js +151 -0
  45. package/dist/tests/fs/errors.test.d.ts +1 -0
  46. package/dist/tests/fs/errors.test.js +141 -0
  47. package/dist/tests/fs/exists.test.d.ts +1 -0
  48. package/dist/tests/fs/exists.test.js +19 -0
  49. package/dist/tests/fs/links.test.d.ts +1 -0
  50. package/dist/tests/fs/links.test.js +248 -0
  51. package/dist/tests/fs/open.test.d.ts +1 -0
  52. package/dist/tests/fs/open.test.js +95 -0
  53. package/dist/tests/fs/permissions.test.d.ts +1 -0
  54. package/dist/tests/fs/permissions.test.js +346 -0
  55. package/dist/tests/fs/read.test.d.ts +1 -0
  56. package/dist/tests/fs/read.test.js +149 -0
  57. package/dist/tests/fs/readFile.test.d.ts +1 -0
  58. package/dist/tests/fs/readFile.test.js +110 -0
  59. package/dist/tests/fs/rename.test.d.ts +1 -0
  60. package/dist/tests/fs/rename.test.js +70 -0
  61. package/dist/tests/fs/scaling.test.d.ts +1 -0
  62. package/dist/tests/fs/scaling.test.js +27 -0
  63. package/dist/tests/fs/stat.test.d.ts +1 -0
  64. package/dist/tests/fs/stat.test.js +93 -0
  65. package/dist/tests/fs/streams.test.d.ts +1 -0
  66. package/dist/tests/fs/streams.test.js +161 -0
  67. package/dist/tests/fs/tempdir.test.d.ts +1 -0
  68. package/dist/tests/fs/tempdir.test.js +118 -0
  69. package/dist/tests/fs/times.test.d.ts +7 -0
  70. package/dist/tests/fs/times.test.js +134 -0
  71. package/dist/tests/fs/truncate.test.d.ts +1 -0
  72. package/dist/tests/fs/truncate.test.js +62 -0
  73. package/dist/tests/fs/watch.test.d.ts +1 -0
  74. package/dist/tests/fs/watch.test.js +320 -0
  75. package/dist/tests/fs/write.test.d.ts +1 -0
  76. package/dist/tests/fs/write.test.js +83 -0
  77. package/dist/tests/fs/xattr.test.d.ts +1 -0
  78. package/dist/tests/fs/xattr.test.js +137 -0
  79. package/dist/tests/setup/memory.d.ts +1 -0
  80. package/dist/tests/setup/memory.js +3 -0
  81. package/package.json +11 -6
  82. package/tests/readme.md +2 -2
  83. package/tests/fs/append.test.ts +0 -34
  84. package/tests/fs/concurrency.test.ts +0 -113
  85. package/tests/fs/dir.test.ts +0 -103
  86. package/tests/fs/directory.test.ts +0 -189
  87. package/tests/fs/errors.test.ts +0 -159
  88. package/tests/fs/exists.test.ts +0 -23
  89. package/tests/fs/links.test.ts +0 -308
  90. package/tests/fs/open.test.ts +0 -23
  91. package/tests/fs/permissions.test.ts +0 -344
  92. package/tests/fs/read.test.ts +0 -94
  93. package/tests/fs/readFile.test.ts +0 -58
  94. package/tests/fs/rename.test.ts +0 -93
  95. package/tests/fs/scaling.test.ts +0 -35
  96. package/tests/fs/stat.test.ts +0 -115
  97. package/tests/fs/streams.test.ts +0 -204
  98. package/tests/fs/tempdir.test.ts +0 -64
  99. package/tests/fs/times.test.ts +0 -85
  100. package/tests/fs/truncate.test.ts +0 -89
  101. package/tests/fs/watch.test.ts +0 -246
  102. package/tests/fs/write.test.ts +0 -118
  103. package/tests/fs/xattr.test.ts +0 -96
  104. package/tests/setup/memory.ts +0 -3
  105. package/tests/tsconfig.json +0 -8
@@ -1,85 +1,53 @@
1
1
  #!/usr/bin/env node
2
2
  // SPDX-License-Identifier: LGPL-3.0-or-later
3
+ import { Command, InvalidArgumentError, Option } from 'commander';
3
4
  import { execFileSync } from 'node:child_process';
4
5
  import { existsSync, globSync, mkdirSync, rmSync } from 'node:fs';
5
6
  import { join, parse, basename } from 'node:path';
6
- import { parseArgs, styleText } from 'node:util';
7
- const { values: options, positionals } = parseArgs({
8
- options: {
9
- // Output
10
- help: { short: 'h', type: 'boolean', default: false },
11
- verbose: { short: 'v', type: 'boolean', default: false },
12
- quiet: { short: 'q', type: 'boolean', default: false },
13
- log: { short: 'l', type: 'string', default: '' },
14
- 'file-names': { short: 'N', type: 'boolean', default: false },
15
- ci: { short: 'C', type: 'boolean', default: false },
16
- debug: { short: 'd', type: 'boolean', default: false },
17
- // Test behavior
18
- test: { short: 't', type: 'string' },
19
- force: { short: 'f', type: 'boolean', default: false },
20
- auto: { short: 'a', type: 'boolean', default: false },
21
- build: { short: 'b', type: 'boolean', default: false },
22
- common: { short: 'c', type: 'boolean', default: false },
23
- inspect: { short: 'I', type: 'boolean', default: false },
24
- skip: { short: 's', type: 'string', multiple: true, default: [] },
25
- 'exit-on-fail': { short: 'e', type: 'boolean' },
26
- runs: { short: 'r', type: 'string', default: '1' },
27
- // Coverage and performance
28
- coverage: { type: 'string', default: 'tests/.coverage' },
29
- preserve: { short: 'p', type: 'boolean' },
30
- report: { type: 'boolean', default: false },
31
- 'report-only': { type: 'boolean', default: false },
32
- clean: { type: 'boolean', default: false },
33
- profile: { type: 'boolean', default: false },
34
- },
35
- strict: true,
36
- allowPositionals: true,
37
- });
7
+ import { fileURLToPath } from 'node:url';
8
+ import { styleText } from 'node:util';
9
+ function positiveInteger(value) {
10
+ const number = Number(value);
11
+ if (!Number.isSafeInteger(number) || number < 1)
12
+ throw new InvalidArgumentError('Not a positive integer.');
13
+ return number;
14
+ }
15
+ const cli = new Command('zenfs-test')
16
+ .description('Runs the ZenFS test suites')
17
+ .argument('[paths...]', 'The setup files to run tests on')
18
+ .optionsGroup('Behavior:')
19
+ .option('-a, --auto', 'Automatically detect setup files')
20
+ .option('-b, --build', 'Run the npm build script prior to running tests')
21
+ .option('-c, --common', 'Also run tests not specific to any backend')
22
+ .option('-e, --exit-on-fail', 'If any tests suites fail, exit immediately')
23
+ .option('-r, --runs <n>', 'Run tests n times and print average result', positiveInteger, 1)
24
+ .option('-t, --test <glob>', 'Which FS test suite(s) to run')
25
+ .option('-f, --force', 'Whether to use --test-force-exit')
26
+ .option('-I, --inspect', 'Use the inspector for debugging')
27
+ .option('-s, --skip <pattern...>', 'Skip tests with names matching the given pattern; can be passed multiple times', [])
28
+ .option('-d, --debug', 'Output debug messages from the test runner')
29
+ .optionsGroup('Output:')
30
+ .option('-v, --verbose', 'Output verbose messages')
31
+ .addOption(new Option('-q, --quiet', "Don't output normal messages").conflicts('verbose'))
32
+ .option('-l, --log <level>', 'Change the default log level for test output; can be a number or string')
33
+ .option('-N, --file-names', 'Use full file paths for tests from setup files instead of the base name')
34
+ .option('-C, --ci', 'Continuous integration (CI) mode, which reports to the GitHub Checks API; requires @octokit/action')
35
+ .optionsGroup('Coverage:')
36
+ .option('--coverage <dir>', 'Override the default coverage data directory', 'tests/.coverage')
37
+ .option('-p, --preserve', 'Do not delete or report coverage data')
38
+ .option('--report', 'Report coverage along with test results')
39
+ .option('--report-only', 'Only report coverage')
40
+ .option('--clean', 'Only clean up the coverage directory')
41
+ .option('--profile', 'Record performance profiles')
42
+ .parse();
43
+ const options = cli.opts();
44
+ const [positionals] = cli.processedArgs;
38
45
  function debug(...args) {
39
46
  if (options.debug || process.env.DEBUG)
40
47
  console.debug(styleText('dim', '[debug]'), ...args.map(a => (typeof a === 'string' ? styleText('dim', a) : a)));
41
48
  }
42
- if (options.help) {
43
- console.log(`zenfs-test [...options] <...paths>
44
-
45
- Paths: The setup files to run tests on
46
-
47
- Behavior:
48
- -a, --auto Automatically detect setup files
49
- -b, --build Run the npm build script prior to running tests
50
- -c, --common Also run tests not specific to any backend
51
- -e, --exit-on-fail If any tests suites fail, exit immediately
52
- -r, --runs <n> Run tests n times and print average result
53
- -t, --test <glob> Which FS test suite(s) to run
54
- -f, --force Whether to use --test-force-exit
55
- -I, --inspect Use the inspector for debugging
56
- -s, --skip <pattern> Skip tests with names matching the given pattern. Can be specified multiple times.
57
- -d, --debug Output debug messages from the test runner
58
-
59
- Output:
60
- -h, --help Outputs this help message
61
- -v, --verbose Output verbose messages
62
- -q, --quiet Don't output normal messages
63
- -l, --logs <level> Change the default log level for test output. Level can be a number or string
64
- -N, --file-names Use full file paths for tests from setup files instead of the base name
65
- -C, --ci Continuous integration (CI) mode. This interacts with the Github
66
- Checks API for better test status. Requires @octokit/action
67
-
68
- Coverage:
69
- --coverage <dir> Override the default coverage data directory
70
- -p, --preserve Do not delete or report coverage data
71
- --report Report coverage along with test results
72
- --report-only ONLY report coverage
73
- --clean ONLY clean up coverage directory
74
- --profile Record performance profiles`);
75
- process.exit();
76
- }
77
- if (options.quiet && options.verbose) {
78
- console.error('ERROR: Can not specify --verbose and --quiet');
79
- process.exit(1);
80
- }
81
49
  process.env.NODE_V8_COVERAGE = options.coverage;
82
- process.env.ZENFS_LOG_LEVEL = options.log;
50
+ process.env.ZENFS_LOG_LEVEL = options.log ?? '';
83
51
  if (options.verbose)
84
52
  process.env.VERBOSE = '1';
85
53
  if (options.clean) {
@@ -88,7 +56,7 @@ if (options.clean) {
88
56
  }
89
57
  function report() {
90
58
  try {
91
- execFileSync('npx', ['--silent', 'c8', 'report', '--reporter=text'], { stdio: 'inherit' });
59
+ execFileSync(process.execPath, [fileURLToPath(import.meta.resolve('c8/bin/c8.js')), 'report', '--reporter=text'], { stdio: 'inherit' });
92
60
  }
93
61
  catch (e) {
94
62
  console.error('Failed to generate coverage report!');
@@ -98,14 +66,14 @@ function report() {
98
66
  rmSync(options.coverage, { recursive: true });
99
67
  }
100
68
  }
101
- if (options['report-only']) {
69
+ if (options.reportOnly) {
102
70
  report();
103
71
  process.exit();
104
72
  }
105
- const nRuns = Number.isSafeInteger(parseInt(options.runs)) ? parseInt(options.runs) : 1;
73
+ const nRuns = options.runs;
106
74
  let ci;
107
75
  if (options.ci) {
108
- if (options.runs && nRuns !== 1) {
76
+ if (nRuns != 1) {
109
77
  console.error('Cannot use --ci with --runs');
110
78
  process.exit(1);
111
79
  }
@@ -205,7 +173,7 @@ async function runTests(config) {
205
173
  console.error(`${styleText(['red', 'bold'], 'failed')}${identText} ${time()}`);
206
174
  await ci?.completeCheck(statusName, 'failure');
207
175
  process.exitCode = 1;
208
- if (options['exit-on-fail'])
176
+ if (options.exitOnFail)
209
177
  process.exit();
210
178
  return;
211
179
  }
@@ -221,7 +189,7 @@ if (options.common) {
221
189
  statusName: 'Common tests',
222
190
  });
223
191
  }
224
- const testsGlob = join(import.meta.dirname, `../../tests/fs/${options.test || '*'}.test.ts`);
192
+ const testsGlob = join(import.meta.dirname, `../tests/fs/${options.test || '*'}.test.js`);
225
193
  for (const setupFile of positionals) {
226
194
  if (!existsSync(setupFile)) {
227
195
  if (!options.quiet)
@@ -229,12 +197,12 @@ for (const setupFile of positionals) {
229
197
  continue;
230
198
  }
231
199
  process.env.SETUP = setupFile;
232
- const name = options['file-names'] && !options.ci ? setupFile : parse(setupFile).name;
200
+ const name = options.fileNames && !options.ci ? setupFile : parse(setupFile).name;
233
201
  await runTests({
234
202
  name,
235
203
  args: [`${testsGlob.replaceAll("'", "\\'")}`, process.env.CMD || ''],
236
204
  shouldSkip() {
237
- return basename(setupFile).startsWith('_') && options.auto;
205
+ return basename(setupFile).startsWith('_') && !!options.auto;
238
206
  },
239
207
  });
240
208
  }
@@ -0,0 +1 @@
1
+ export { default as makeIndex } from './make_index.js';
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ export { default as makeIndex } from './make_index.js';
@@ -0,0 +1,20 @@
1
+ import type { IndexData } from '@zenfs/core';
2
+ import { type Stats } from 'node:fs';
3
+ export interface MakeIndexOptions {
4
+ /** Glob patterns of paths to leave out */
5
+ ignore?: string[];
6
+ /** Include entries from devices other than the one `root` is on */
7
+ xdev?: boolean;
8
+ /** Called with a message when an entry crosses a device boundary */
9
+ onWarning?(message: string): void;
10
+ /** Called when an entry can not be added. If not set, the error is thrown. */
11
+ onError?(path: string, error: Error): void;
12
+ /** Called for each entry added to the index */
13
+ onEntry?(path: string, stats: Stats): void;
14
+ /** Called for each path left out because it matches `ignore` */
15
+ onIgnore?(path: string): void;
16
+ }
17
+ /**
18
+ * Creates an index of the host file system at `root`, for use with backends like `Fetch`
19
+ */
20
+ export default function makeIndex(root?: string, options?: MakeIndexOptions): IndexData;
@@ -0,0 +1,49 @@
1
+ import { constants as c, lstatSync, readdirSync } from 'node:fs';
2
+ import { join, matchesGlob, relative } from 'node:path/posix';
3
+ const supportedTypes = new Set([c.S_IFBLK, c.S_IFCHR, c.S_IFIFO, c.S_IFSOCK, c.S_IFREG, c.S_IFDIR, c.S_IFLNK]);
4
+ /**
5
+ * Creates an index of the host file system at `root`, for use with backends like `Fetch`
6
+ */
7
+ export default function makeIndex(root = '.', options = {}) {
8
+ const entries = new Map();
9
+ const seenDevs = new Set();
10
+ function computeEntries(path) {
11
+ try {
12
+ if (options.ignore?.some(pattern => matchesGlob(path, pattern))) {
13
+ options.onIgnore?.(path);
14
+ return;
15
+ }
16
+ const stats = lstatSync(path);
17
+ if (!seenDevs.size)
18
+ seenDevs.add(stats.dev);
19
+ else if (!seenDevs.has(stats.dev))
20
+ if (options.xdev) {
21
+ options.onWarning?.(`--xdev: Adding entries from device ${stats.dev} (${path}). You may get duplicate inos which MUST be de-duplicated manually.`);
22
+ seenDevs.add(stats.dev);
23
+ }
24
+ else {
25
+ options.onWarning?.(`Ignoring ${path} because it crosses a device boundary`);
26
+ return;
27
+ }
28
+ if (!supportedTypes.has(stats.mode & c.S_IFMT))
29
+ throw new Error(`Unknown file type: 0o${(stats.mode & c.S_IFMT).toString(8)}`);
30
+ entries.set('/' + relative(root, path), stats);
31
+ options.onEntry?.(path, stats);
32
+ if (stats.isDirectory()) {
33
+ for (const file of readdirSync(path))
34
+ computeEntries(join(path, file));
35
+ }
36
+ }
37
+ catch (e) {
38
+ const error = e instanceof Error ? e : new Error(String(e));
39
+ if (!options.onError)
40
+ throw error;
41
+ options.onError(path, error);
42
+ }
43
+ }
44
+ computeEntries(root);
45
+ return {
46
+ version: 1,
47
+ entries: Object.fromEntries(entries),
48
+ };
49
+ }
@@ -0,0 +1,53 @@
1
+ import type { Api } from './docs.js';
2
+ import type { NodeRepository } from './node.js';
3
+ import type { PR } from './pr.js';
4
+ import type { MarkEntry, Marks } from './state.js';
5
+ /**
6
+ * `auto` means every API the PR added exists in ZenFS.
7
+ */
8
+ export type Status = 'pending' | 'resolved' | 'ignored' | 'auto';
9
+ export interface ApiStatus {
10
+ api: Api;
11
+ present: boolean;
12
+ mark?: MarkEntry;
13
+ }
14
+ export interface PRStatus {
15
+ pr: PR;
16
+ status: Status;
17
+ mark?: MarkEntry;
18
+ /** Affected APIs that ZenFS lacks */
19
+ missing: string[];
20
+ }
21
+ export interface PRFilter {
22
+ /** Include PRs released in this version or later */
23
+ since?: string;
24
+ /** Include unreleased PRs that landed on or after this ISO date */
25
+ landedSince?: string;
26
+ semver?: PR['semver'][];
27
+ status?: Status[];
28
+ /** Release lines the PR must have been released in */
29
+ lines?: number[];
30
+ /** Tags the PR must have; prefix with `!` to exclude */
31
+ tags?: string[];
32
+ /** Matched against the title and commit messages */
33
+ grep?: RegExp;
34
+ /** Only PRs not in any release */
35
+ unreleased?: boolean;
36
+ }
37
+ /**
38
+ * Combines Node.js data, the ZenFS probe, and manual marks.
39
+ */
40
+ export declare class Analysis {
41
+ readonly node: NodeRepository;
42
+ readonly apis: Map<string, ApiStatus>;
43
+ readonly prs: Map<number, PRStatus>;
44
+ constructor(node: NodeRepository, marks: Marks);
45
+ /**
46
+ * @param prs Defaults to every PR
47
+ */
48
+ filterPRs(filter: PRFilter, prs?: Iterable<PRStatus>): PRStatus[];
49
+ }
50
+ /**
51
+ * Sorts newest first, by landing date on the tracked ref or by first release.
52
+ */
53
+ export declare function byNewest(left: PRStatus, right: PRStatus): number;
@@ -0,0 +1,60 @@
1
+ import { compareVersions } from './versions.js';
2
+ import * as zenfs from './zenfs.js';
3
+ /**
4
+ * Combines Node.js data, the ZenFS probe, and manual marks.
5
+ */
6
+ export class Analysis {
7
+ node;
8
+ apis = new Map();
9
+ prs = new Map();
10
+ constructor(node, marks) {
11
+ this.node = node;
12
+ const snapshot = new Map(marks);
13
+ for (const api of node.apis.values()) {
14
+ this.apis.set(api.id, { api, present: zenfs.has(api), mark: snapshot.get(api.id) });
15
+ }
16
+ for (const pr of node.prs.values()) {
17
+ const mark = snapshot.get(pr.key);
18
+ const missing = [...pr.apis.added, ...pr.apis.changed].filter(id => {
19
+ const status = this.apis.get(id);
20
+ return status && !status.present && !status.mark;
21
+ });
22
+ const auto = pr.apis.added.length > 0 && pr.apis.added.every(id => this.apis.get(id)?.present);
23
+ this.prs.set(pr.number, { pr, mark, missing, status: mark?.status ?? (auto ? 'auto' : 'pending') });
24
+ }
25
+ }
26
+ /**
27
+ * @param prs Defaults to every PR
28
+ */
29
+ filterPRs(filter, prs = this.prs.values()) {
30
+ const { since, landedSince, grep } = filter;
31
+ return [...prs].filter(({ pr, status }) => {
32
+ if (filter.unreleased && pr.releases.length)
33
+ return false;
34
+ if (since && pr.releases.length && !pr.releases.some(release => compareVersions(release.version, since) >= 0))
35
+ return false;
36
+ if (landedSince && !pr.releases.length && (pr.commits[0]?.date ?? '') < landedSince)
37
+ return false;
38
+ if (filter.semver && !filter.semver.includes(pr.semver))
39
+ return false;
40
+ if (filter.status && !filter.status.includes(status))
41
+ return false;
42
+ if (filter.lines && !filter.lines.every(line => pr.releases.some(release => release.line == line)))
43
+ return false;
44
+ const { tags } = pr;
45
+ for (const tag of filter.tags ?? []) {
46
+ if (tag.startsWith('!') ? tags.includes(tag.slice(1)) : !tags.includes(tag))
47
+ return false;
48
+ }
49
+ if (grep && !grep.test(pr.title) && !pr.commits.some(commit => grep.test(commit.body)))
50
+ return false;
51
+ return true;
52
+ });
53
+ }
54
+ }
55
+ /**
56
+ * Sorts newest first, by landing date on the tracked ref or by first release.
57
+ */
58
+ export function byNewest(left, right) {
59
+ return right.pr.date.localeCompare(left.pr.date) || right.pr.number - left.pr.number;
60
+ }
@@ -0,0 +1,25 @@
1
+ import type { Repository } from './git.js';
2
+ export type Semver = 'major' | 'minor' | 'patch';
3
+ export interface Release {
4
+ version: string;
5
+ /** Major version */
6
+ line: number;
7
+ /** ISO date */
8
+ date: string;
9
+ }
10
+ export interface Entry {
11
+ pr: number;
12
+ /** Abbreviated hash on the release branch */
13
+ commit: string;
14
+ subsystems: string[];
15
+ title: string;
16
+ author: string;
17
+ semver: Semver;
18
+ revert: boolean;
19
+ release: Release;
20
+ }
21
+ /**
22
+ * Parses the commit lines of a changelog, including the duplicates listed under notable changes.
23
+ */
24
+ export declare function parse(text: string): Entry[];
25
+ export declare function read(repo: Repository): Entry[];
@@ -0,0 +1,60 @@
1
+ import { parseVersion } from './versions.js';
2
+ const releaseHeading = /^## (?<date>\d{4}-\d{2}-\d{2}), Version (?<version>\d+\.\d+\.\d+)/;
3
+ const changelogLine = /^\* \\\[\[`(?<commit>[0-9a-f]+)`\]\([^)]*\)\] - (?<rest>.+?)\s*\[#(?<pr>\d+)\]\(https:\/\/github\.com\/nodejs\/node\/pull\/\d+\)\s*$/;
4
+ /**
5
+ * Parses the commit lines of a changelog, including the duplicates listed under notable changes.
6
+ */
7
+ export function parse(text) {
8
+ const entries = [];
9
+ let release;
10
+ for (const line of text.split('\n')) {
11
+ const heading = releaseHeading.exec(line);
12
+ if (heading?.groups) {
13
+ const { date, version } = heading.groups;
14
+ release = { version, line: parseVersion(version)[0], date };
15
+ continue;
16
+ }
17
+ const match = release && changelogLine.exec(line);
18
+ if (!release || !match?.groups)
19
+ continue;
20
+ let rest = match.groups.rest;
21
+ let semver = 'patch';
22
+ for (let tag; (tag = /^\*\*\((?<tag>[^)]+)\)\*\*\s*/.exec(rest)); rest = rest.slice(tag[0].length)) {
23
+ if (tag.groups?.tag == 'SEMVER-MAJOR')
24
+ semver = 'major';
25
+ if (tag.groups?.tag == 'SEMVER-MINOR' && semver != 'major')
26
+ semver = 'minor';
27
+ }
28
+ const revert = /^_\*\*Revert\*\*_ "/.test(rest);
29
+ if (revert)
30
+ rest = rest.replace(/^_\*\*Revert\*\*_ "/, '');
31
+ const subject = /^\*\*(?<subsystems>[^*]+)\*\*: (?<text>.*)$/.exec(rest);
32
+ if (!subject?.groups)
33
+ continue;
34
+ let { text: title } = subject.groups;
35
+ let author = '';
36
+ const authorStart = title.lastIndexOf(' (');
37
+ if (authorStart != -1 && title.endsWith(')')) {
38
+ author = title.slice(authorStart + 2, -1);
39
+ title = title.slice(0, authorStart);
40
+ }
41
+ if (revert)
42
+ title = title.replace(/"$/, '');
43
+ entries.push({
44
+ pr: Number(match.groups.pr),
45
+ commit: match.groups.commit,
46
+ subsystems: subject.groups.subsystems.split(',').map(name => name.trim()),
47
+ title,
48
+ author,
49
+ semver,
50
+ revert,
51
+ release,
52
+ });
53
+ }
54
+ return entries;
55
+ }
56
+ export function read(repo) {
57
+ const listing = repo.git(['ls-tree', repo.ref, 'doc/changelogs/']);
58
+ const hashes = [...listing.matchAll(/^\S+ blob (\S+)\tdoc\/changelogs\/CHANGELOG_V\d+\.md$/gm)].map(match => match[1]);
59
+ return [...repo.readBlobs(hashes).values()].flatMap(parse);
60
+ }
@@ -0,0 +1,26 @@
1
+ import type { Repository } from './git.js';
2
+ export interface Subject {
3
+ revert: boolean;
4
+ subsystems: string[];
5
+ title: string;
6
+ }
7
+ export declare function parseSubject(subject: string): Subject | undefined;
8
+ export declare function matchesSubsystem(subsystems: string[], wanted: string[]): boolean;
9
+ export interface Commit {
10
+ hash: string;
11
+ /** ISO date */
12
+ date: string;
13
+ author: string;
14
+ subject: string;
15
+ body: string;
16
+ files: string[];
17
+ }
18
+ export declare function readCommits(repo: Repository, subsystems: string[]): Commit[];
19
+ export interface ApiHistory {
20
+ added: string[];
21
+ removed: string[];
22
+ }
23
+ /**
24
+ * Finds which APIs each commit added or removed by diffing the parsed docs before and after it.
25
+ */
26
+ export declare function readApiHistory(repo: Repository, docs: string, hashes: Set<string>): Map<string, ApiHistory>;
@@ -0,0 +1,66 @@
1
+ // SPDX-License-Identifier: LGPL-3.0-or-later
2
+ import { Api } from './docs.js';
3
+ const subjectPattern = /^(?<revert>Revert ")?(?:\[v\d+\.x\]\s*)?(?<subsystems>[\w./-]+(?:,\s?[\w./-]+)*): (?<title>.+?)"?$/;
4
+ export function parseSubject(subject) {
5
+ const match = subjectPattern.exec(subject);
6
+ if (!match?.groups)
7
+ return;
8
+ const { revert, subsystems, title } = match.groups;
9
+ return { revert: !!revert, subsystems: subsystems.split(',').map(name => name.trim()), title };
10
+ }
11
+ export function matchesSubsystem(subsystems, wanted) {
12
+ return subsystems.some(name => wanted.some(want => name == want || name.startsWith(want + '/')));
13
+ }
14
+ export function readCommits(repo, subsystems) {
15
+ const commits = [];
16
+ for (const record of repo.git(['log', repo.ref, '--format=%x1e%H%x1f%cI%x1f%an%x1f%s%x1f%b']).split('\x1e')) {
17
+ if (!record)
18
+ continue;
19
+ const [hash, date, author, subject, body] = record.split('\x1f');
20
+ const parsed = parseSubject(subject);
21
+ if (!parsed || !matchesSubsystem(parsed.subsystems, subsystems))
22
+ continue;
23
+ commits.push({ hash, date, author, subject, body: body.trim(), files: [] });
24
+ }
25
+ if (!commits.length)
26
+ return commits;
27
+ const byHash = new Map(commits.map(commit => [commit.hash, commit]));
28
+ const hashes = commits.map(commit => commit.hash).join('\n');
29
+ for (const record of repo.git(['log', '--no-walk=unsorted', '--stdin', '--format=%x1e%H', '--name-only'], hashes).split('\x1e')) {
30
+ const [hash, ...files] = record.trim().split('\n');
31
+ const commit = byHash.get(hash);
32
+ if (commit)
33
+ commit.files = files.filter(Boolean);
34
+ }
35
+ return commits;
36
+ }
37
+ /**
38
+ * Finds which APIs each commit added or removed by diffing the parsed docs before and after it.
39
+ */
40
+ export function readApiHistory(repo, docs, hashes) {
41
+ const changes = [];
42
+ for (const record of repo.git(['log', repo.ref, '--format=%x1e%H', '--raw', '--no-abbrev', '--', docs]).split('\x1e')) {
43
+ const [hash, raw] = record.split('\n').filter(Boolean);
44
+ if (!hashes.has(hash) || !raw)
45
+ continue;
46
+ const [, , before, after] = raw.split(/\s+/);
47
+ changes.push({ hash, before, after });
48
+ }
49
+ const blobs = repo.readBlobs([...new Set(changes.flatMap(change => [change.before, change.after]))]);
50
+ const parsed = new Map();
51
+ function idsOf(blob) {
52
+ let ids = parsed.get(blob);
53
+ if (!ids)
54
+ parsed.set(blob, (ids = new Set(Api.parse(blobs.get(blob) ?? '').keys())));
55
+ return ids;
56
+ }
57
+ const history = new Map();
58
+ for (const { hash, before, after } of changes) {
59
+ const old = idsOf(before), current = idsOf(after);
60
+ history.set(hash, {
61
+ added: [...current].filter(id => !old.has(id)),
62
+ removed: [...old].filter(id => !current.has(id)),
63
+ });
64
+ }
65
+ return history;
66
+ }
@@ -0,0 +1,6 @@
1
+ export declare const configPath: string;
2
+ /**
3
+ * Path to the saved Node.js clone, if any.
4
+ */
5
+ export declare function savedRepo(): string | undefined;
6
+ export declare function saveRepo(path: string): void;
@@ -0,0 +1,18 @@
1
+ // SPDX-License-Identifier: LGPL-3.0-or-later
2
+ import { existsSync, mkdirSync } from 'node:fs';
3
+ import { homedir } from 'node:os';
4
+ import { dirname, join } from 'node:path';
5
+ import { JSONFileMap } from 'utilium/fs';
6
+ export const configPath = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'zenfs', 'node-compat.json');
7
+ /**
8
+ * Path to the saved Node.js clone, if any.
9
+ */
10
+ export function savedRepo() {
11
+ if (!existsSync(configPath))
12
+ return;
13
+ return new JSONFileMap(configPath, { overwrite_invalid: true }).get('repo');
14
+ }
15
+ export function saveRepo(path) {
16
+ mkdirSync(dirname(configPath), { recursive: true });
17
+ new JSONFileMap(configPath, { overwrite_invalid: true }).set('repo', path);
18
+ }
@@ -0,0 +1,58 @@
1
+ import type { Repository } from './git.js';
2
+ export declare const fs = "doc/api/fs.md";
3
+ export interface ApiChange {
4
+ versions: string[];
5
+ pr?: number;
6
+ description: string;
7
+ }
8
+ export type ApiKind = 'module' | 'class' | 'member' | 'constant';
9
+ export declare class Api {
10
+ /** `<owner>.<path>` for modules, classes, and constants; `<Class>#<member>` for members */
11
+ readonly id: string;
12
+ readonly kind: ApiKind;
13
+ /** The object the API lives on: `fs`, `fsPromises`, or a class name */
14
+ readonly owner: string;
15
+ /** Property path from `owner` */
16
+ readonly path: (string | symbol)[];
17
+ /** Top-level docs section */
18
+ readonly section: string;
19
+ /** Headings from the docs, without backticks */
20
+ readonly signatures: string[];
21
+ readonly added: string[];
22
+ readonly deprecated: string[];
23
+ readonly removed: string[];
24
+ readonly changes: ApiChange[];
25
+ stability?: number;
26
+ constructor(
27
+ /** `<owner>.<path>` for modules, classes, and constants; `<Class>#<member>` for members */
28
+ id: string, kind: ApiKind,
29
+ /** The object the API lives on: `fs`, `fsPromises`, or a class name */
30
+ owner: string,
31
+ /** Property path from `owner` */
32
+ path: (string | symbol)[],
33
+ /** Top-level docs section */
34
+ section: string);
35
+ /**
36
+ * Adds metadata from a YAML doc comment, skipping duplicates.
37
+ */
38
+ merge(yaml: Yaml): void;
39
+ toJSON(): this & {
40
+ path: string;
41
+ };
42
+ /**
43
+ * @param text Contents of the `fs` docs
44
+ */
45
+ static parse(text: string): Map<string, Api>;
46
+ static read(repo: Repository, path?: string): Map<string, Api>;
47
+ }
48
+ export interface Yaml {
49
+ added: string[];
50
+ deprecated: string[];
51
+ removed: string[];
52
+ changes: ApiChange[];
53
+ }
54
+ /**
55
+ * Parses the subset of YAML used in `<!-- YAML -->` doc comments.
56
+ */
57
+ export declare function parseYaml(lines: string[]): Yaml;
58
+ export declare function formatPath(path: (string | symbol)[]): string;