Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): the doc importers read an edited CommonJS doc again (#10760)

Christopher Chedeau09b4ff94d81c
diff --git a/.changeset/doc-importers-read-edits.md b/.changeset/doc-importers-read-edits.md
new file mode 100644
index 0000000000..31630c315f
--- /dev/null
+++ b/.changeset/doc-importers-read-edits.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] A long-running process that calls the CLI's API, such as a docs site's search route, now reads an edited CommonJS `.doc.js` file again in docs, search and template reads. It read the doc as first loaded.
+
+@vjeux
diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
index eb240f6251..cad3d857cd 100644
--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
@@ -342,12 +342,14 @@ const RUNNERS = {
sites: ['require(@babel/parser)', 'require(jscodeshift)'],
},
'foundation/doc-compiler/import.mjs': {
- runs: 'authored doc files, for the doc reader and discovery, and again after an edit',
+ runs: 'authored doc files, for the doc reader and discovery, and again after an edit, without the cache entry of a CommonJS doc',
sites: [
'.import() ×2',
'createJiti ×2',
- 'importUrl ×4',
+ 'importUrl ×2',
'importUserModule ×2',
+ 'readFreshInTurn',
+ 'readInTurn',
],
},
'foundation/doc-compiler/read.mjs': {
diff --git a/packages/cli/foundation/doc-compiler/import.mjs b/packages/cli/foundation/doc-compiler/import.mjs
index e5e23ef273..8232e1448a 100644
--- a/packages/cli/foundation/doc-compiler/import.mjs
+++ b/packages/cli/foundation/doc-compiler/import.mjs
@@ -25,7 +25,11 @@
import {pathToFileURL} from 'node:url';
import {createJiti} from 'jiti';
import {importUrl} from '../fs/import-url.mjs';
-import {importUserModule} from '../fs/module-loader.mjs';
+import {
+ importUserModule,
+ readFreshInTurn,
+ readInTurn,
+} from '../fs/module-loader.mjs';
import {fileStamp, recordContentRead} from '../fs/read-record.mjs';
/** @type {ReturnType<typeof createJiti> | undefined} */
@@ -79,6 +83,28 @@ function freshUrl(file) {
return url.href;
}
+/**
+ * Import `file` from `url`, in its turn with every other read of the file in
+ * this process (`readInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @param {string} url
+ * @returns {Promise<any>}
+ */
+function importInTurn(file, url) {
+ return readInTurn(file, () => importUrl(url));
+}
+
+/**
+ * Import `file` again, for a change, as a new module. Node chooses its format
+ * as for the first import. The read takes its turn without the file's
+ * CommonJS cache entry (`readFreshInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @returns {Promise<any>}
+ */
+function importFresh(file) {
+ return readFreshInTurn(file, () => importUrl(freshUrl(file)));
+}
+
/**
* Import a component, hook, topic, or self-doc module: `.ts` through jiti,
* anything else natively.
@@ -106,14 +132,14 @@ export function importTemplateModule(file) {
jsxJiti ??= createJiti(import.meta.url, {jsx: true});
return jsxJiti.import(first);
}
- return importUrl(`file://${first}`);
+ return importInTurn(first, `file://${first}`);
},
changed =>
changed.endsWith('.ts')
? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
changed,
)
- : importUrl(freshUrl(changed)),
+ : importFresh(changed),
);
}
@@ -127,7 +153,7 @@ export function importNativeModule(file) {
return importCurrent(
file,
'native',
- first => importUrl(pathToFileURL(first).href),
- changed => importUrl(freshUrl(changed)),
+ first => importInTurn(first, pathToFileURL(first).href),
+ changed => importFresh(changed),
);
}
diff --git a/packages/cli/foundation/doc-compiler/read.test.mjs b/packages/cli/foundation/doc-compiler/read.test.mjs
index 0df0db7838..14a0266412 100644
--- a/packages/cli/foundation/doc-compiler/read.test.mjs
+++ b/packages/cli/foundation/doc-compiler/read.test.mjs
@@ -389,4 +389,106 @@ describe('an edited doc file, read again in the same process', () => {
fs.writeFileSync(file, doc('Fixed again'));
expect((await loadDocs(file)).displayName).toBe('Fixed again');
});
+
+ it.each([
+ ['a CommonJS doc', 'Edited.doc.js', {type: 'commonjs'}],
+ [
+ 'a CommonJS doc in a package without a "type"',
+ 'Edited.doc.js',
+ {name: 'kit'},
+ ],
+ ['an ES module doc', 'Edited.doc.mjs', {name: 'kit'}],
+ ])(
+ 'reads %s again with each importer, in a real Node process',
+ (_what, name, packageJson) => {
+ const cjs = name.endsWith('.js');
+ const source = (/** @type {string} */ displayName) =>
+ cjs
+ ? doc(displayName).replace('export default', 'module.exports =')
+ : doc(displayName);
+ const dir = path.join(tmpDir, 'kit');
+ fs.mkdirSync(dir);
+ fs.writeFileSync(
+ path.join(dir, 'package.json'),
+ JSON.stringify(packageJson),
+ );
+ const file = path.join(dir, name);
+ fs.writeFileSync(file, source('First'));
+ const importers = pathToFileURL(
+ path.join(CLI_ROOT, 'foundation/doc-compiler/import.mjs'),
+ ).href;
+ const run = spawnSync(
+ process.execPath,
+ [
+ '--input-type=module',
+ '-e',
+ `import fs from 'node:fs';
+const m = await import(${JSON.stringify(importers)});
+const names = ['importNativeModule', 'importTemplateModule', 'importDocModule'];
+const file = process.env.DOC_FILE;
+const inOrder = async () => {
+ const mods = [];
+ for (const n of names) mods.push(await m[n](file));
+ return mods;
+};
+const atOnce = async () => {
+ try {
+ return await Promise.all(names.map(n => m[n](file)));
+ } catch (error) {
+ return names.map(() => ({default: {displayName: error.code ?? error.name}}));
+ }
+};
+const before = await inOrder();
+fs.writeFileSync(file, process.env.EDITED);
+const after = await inOrder();
+fs.writeFileSync(file, process.env.EDITED_AGAIN);
+const again = await atOnce();
+const racing = file.replace('Edited', 'Racing');
+fs.writeFileSync(racing, process.env.FIRST);
+const firstRead = m.importNativeModule(racing);
+fs.writeFileSync(racing, process.env.EDITED);
+let race;
+try {
+ const [first, fresh] = await Promise.all([firstRead, m.importTemplateModule(racing)]);
+ race = {first: first.default.displayName, fresh: fresh.default.displayName};
+} catch (error) {
+ race = {error: error.code ?? error.name};
+}
+const shown = mods => Object.fromEntries(names.map((n, i) => [n, mods[i].default.displayName]));
+const keys = mod => Object.keys(mod).sort().join();
+process.stdout.write(JSON.stringify({before: shown(before), after: shown(after), again: shown(again), race, sameExports: before.every((mod, i) => keys(mod) === keys(after[i]))}));`,
+ ],
+ {
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ DOC_FILE: file,
+ FIRST: source('First'),
+ EDITED: source('Second, longer'),
+ EDITED_AGAIN: source('Third, the longest'),
+ },
+ },
+ );
+ expect(run.stderr).not.toMatch(/Error/);
+ const all = (/** @type {string} */ displayName) => ({
+ importNativeModule: displayName,
+ importTemplateModule: displayName,
+ importDocModule: displayName,
+ });
+ // `after` reads one importer at a time, so no other importer's read
+ // changes what it sees. `again` reads with all three at once. `race`
+ // starts a fresh read while a first read of the same file still
+ // imports; that first read can show either version.
+ expect(JSON.parse(run.stdout)).toEqual({
+ before: all('First'),
+ after: all('Second, longer'),
+ again: all('Third, the longest'),
+ race: {
+ first: expect.stringMatching(/^(First|Second, longer)$/),
+ fresh: 'Second, longer',
+ },
+ sameExports: true,
+ });
+ },
+ );
});
diff --git a/packages/cli/foundation/fs/module-loader.mjs b/packages/cli/foundation/fs/module-loader.mjs
index e255097ab2..19913c2597 100644
--- a/packages/cli/foundation/fs/module-loader.mjs
+++ b/packages/cli/foundation/fs/module-loader.mjs
@@ -236,10 +236,7 @@ async function importModule(file, fresh) {
// "type", the extension, or the source's syntax. The query names a new ES
// module. A CommonJS module also needs its cache entry gone.
url.searchParams.set('astryx-fresh', String(++freshImportNonce));
- return await readInTurn(file, () => {
- delete requireFromHere.cache[cacheKey(file)];
- return import(url.href);
- });
+ return await readFreshInTurn(file, () => import(url.href));
}
/**
@@ -287,6 +284,22 @@ export function readInTurn(file, read) {
return result;
}
+/**
+ * Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
+ * once the file is gone from Node's CommonJS cache. A new URL names a new ES
+ * module only, so a CommonJS module also needs its cache entry gone.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readFreshInTurn(file, read) {
+ return readInTurn(file, () => {
+ delete requireFromHere.cache[cacheKey(file)];
+ return read();
+ });
+}
+
/**
* Import a user-authored module, take its default export, and validate it