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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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