Skip to content

Commit 2e1e09d

Browse files
committed
fix(adr-0087): predicate 2 reads a default export through its import, and a package name inside a path or URL
An export named `default` is read through the import arm only: `default` is an ordinary key in metadata surfaces, so the bare-word arm refused every default retirement. A whole package's mention regex now admits a `/`-preceded occurrence (a path or URL in a string) while still refusing a scope segment, so an unscoped `plugin-x` is not `@scope/plugin-x`. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WGufziGaNnGcwiYSC9Qzck
1 parent 72629f3 commit 2e1e09d

1 file changed

Lines changed: 126 additions & 4 deletions

File tree

‎scripts/check-adr-0087-registration.mjs‎

Lines changed: 126 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -463,7 +463,8 @@ const SELF_TEST_BATTERIES = Object.freeze({
463463
'REX-L: the compiler is loaded only when a marker names the category': 6,
464464
'WS (#26220): ui workspace packages, `.tsx` modules, aliases and shims': 11,
465465
'IX (#26220): predicate 4 reads an `any` index signature; the entry may be `src/index.tsx`': 52,
466-
'WP (#26220): a deleted published package is retired whole, `<package>#*`': 55,
466+
'WP (#26220): a deleted published package is retired whole, `<package>#*`': 59,
467+
'DX (#26324): an export named `default` is reached through an import, never through the word': 11,
467468
'G6: a changeset that was ALREADY breaking at base is inherited': 1,
468469
'R15: a changeset RENAMED AND turned breaking in the same commit': 5,
469470
'G10: a PURE rename of an ALREADY-breaking stock changeset': 3,
@@ -3161,9 +3162,13 @@ export function verifyRuntimeInterfaceOnly(refs, { rev, cwd, packages }) {
31613162
* @param {Map<string, string>} surfaceTexts path -> text of every metadata surface
31623163
* @param {() => Map<string, {private: boolean, file: string}>} packages workspace
31633164
* manifests, read only when an import has to be attributed to a package
3165+
* An export named `default` is read through the import arm only: see
3166+
* `defaultImportReference`.
3167+
*
31643168
* @returns {{ kind: 'import', hitPath: string } | { kind: 'mention', hitPath: string, line: string } | null}
31653169
*/
31663170
export function metadataSurfaceReference(symbol, declPath, surfaceTexts, packages) {
3171+
if (symbol === 'default') return defaultImportReference(declPath, surfaceTexts, packages);
31673172
const word = new RegExp(`\\b${symbol}\\b`);
31683173
for (const [hitPath, rawText] of surfaceTexts) {
31693174
if (hitPath === declPath || !word.test(rawText)) continue;
@@ -3199,6 +3204,48 @@ export function metadataSurfaceReference(symbol, declPath, surfaceTexts, package
31993204
return null;
32003205
}
32013206

3207+
/**
3208+
* The two import shapes that bind a module's DEFAULT export, each anchored at a
3209+
* statement start and each linear in the text. ⛔ Not `importSpecifiersFor`'s
3210+
* `[\s\S]*?` clause scan: that one runs only on files that already name the symbol,
3211+
* and over every metadata surface it is super-linear in the whitespace runs
3212+
* `maskComments` leaves (measured: 41 s on one `*.zod.ts`).
3213+
*
3214+
* import x from 'm' a default binding, named bindings or a namespace
3215+
* import x, { y } from 'm' beside it or not, `type` or not
3216+
* import { default as x } from 'm' `default` named inside the braces, an
3217+
* export { default } from 'm' `export ... from` re-export included
3218+
*/
3219+
const DEFAULT_BINDING_IMPORT_RE =
3220+
/(?:^|;)[ \t]*import\s+(?:type\s+)?[A-Za-z_$][\w$]*\s*(?:,\s*(?:\{[^}]*\}|\*\s*as\s+[A-Za-z_$][\w$]*)\s*)?from\s*(['"])([^'"\n]+)\1/gm;
3221+
const BRACED_IMPORT_RE = /(?:^|;)[ \t]*(?:import|export)\s+(?:type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"\n]+)\2/gm;
3222+
3223+
/**
3224+
* `metadataSurfaceReference` for an export named `default` (#26324): the IMPORT arm
3225+
* only. `default` is an ordinary object key and member name in exactly the files
3226+
* this step reads -- a field option `{ value: 'technology', default: true }`, a Zod
3227+
* `.default(...)` -- so the bare-word arm hit on every tree, and no retirement of a
3228+
* default export could ever certify. A metadata surface reaches a default export
3229+
* through an import that binds it (the two shapes above). The specifier is
3230+
* attributed as for any other name (`specifierNamesModule`), and comment spans are
3231+
* blanked first, so a docblock quoting the import is not one.
3232+
* ⛔ A namespace import's `ns.default` and a dynamic `import()` are not read here:
3233+
* both reach the export through a member named `default`, the very spelling that
3234+
* cannot be told from the object keys above.
3235+
*/
3236+
function defaultImportReference(declPath, surfaceTexts, packages) {
3237+
for (const [hitPath, rawText] of surfaceTexts) {
3238+
if (hitPath === declPath || !(rawText.includes('import') || rawText.includes('export'))) continue;
3239+
const code = maskComments(rawText);
3240+
const specifiers = [...code.matchAll(DEFAULT_BINDING_IMPORT_RE)].map((m) => m[2]);
3241+
for (const m of code.matchAll(BRACED_IMPORT_RE)) if (/\bdefault\b/.test(m[1])) specifiers.push(m[3]);
3242+
if (specifiers.length === 0) continue;
3243+
const pkgs = packages();
3244+
if (specifiers.some((s) => specifierNamesModule(s, hitPath, declPath, pkgs))) return { kind: 'import', hitPath };
3245+
}
3246+
return null;
3247+
}
3248+
32023249
// ---------------------------------------------------------------------------
32033250
// The sixth category: `type-surface-only` (#13080)
32043251
//
@@ -4802,8 +4849,12 @@ function verifyWholePackageRetired(pkg, { base, head, cwd, packagesAt, kit }) {
48024849
* any occurrence counts -- a plugin id or package reference held as a VALUE as much
48034850
* as an import. An import specifier (`from '…'`, a bare `import '…'`, `import('…')`,
48044851
* `require('…')`, by the root or a subpath) is the case reported as `import`; every
4805-
* other occurrence is a `mention`. A name that merely starts with `pkg`
4806-
* (`plugin-xy` for `plugin-x`) is not it.
4852+
* other occurrence is a `mention`, one inside a path or URL included
4853+
* (`…/node_modules/@scope/pkg/dist/index.js`, `https://npm.im/@scope/pkg`, #27022).
4854+
* A name that merely starts or ends with `pkg` (`plugin-xy` for `plugin-x`) is not
4855+
* it, and neither is a scoped package whose last segment is an unscoped `pkg`
4856+
* (`@scope/plugin-x` for `plugin-x`): a `/` may precede the name, but not one that
4857+
* closes an `@scope` segment.
48074858
*
48084859
* @param {string} pkg
48094860
* @param {string} pkgDir the package's directory, no trailing slash
@@ -4813,7 +4864,7 @@ function verifyWholePackageRetired(pkg, { base, head, cwd, packagesAt, kit }) {
48134864
export function packageReference(pkg, pkgDir, surfaceTexts) {
48144865
const name = pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
48154866
const spec = new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*\\(\\s*|\\brequire\\s*\\(\\s*|^\\s*import\\s+)(['"])${name}(?:/[^'"\\n]*)?\\1`, 'm');
4816-
const mention = new RegExp(`(?<![\\w@./-])${name}(?![\\w.-])`);
4867+
const mention = new RegExp(`(?<![\\w@.-])(?<!@[\\w.~-]+/)${name}(?![\\w.-])`);
48174868
// `maskComments` blanks in place, so an offset in `code` is the same offset in the file.
48184869
const lineAt = (raw, code, at) => {
48194870
const end = code.indexOf('\n', at);
@@ -8262,6 +8313,77 @@ function selfTest() {
82628313
]));
82638314
assert(u5?.kind === 'mention' && u5.hitPath === 'packages/spec/src/d.zod.ts' && u5.line === `export const D = { plugin: '${WP_PKG}' };`,
82648315
`WP-U5: a string VALUE naming the package is a reference in code, reported with its line; a comment is not (${JSON.stringify(u5)})`);
8316+
// #27022: an occurrence inside a path or URL is "any other occurrence" (D9); a
8317+
// `/` may precede the name, but not one closing an `@scope` segment.
8318+
const mentionIn = (pkg, line) => packageReference(pkg, 'ui/packages/plugin-x', new Map([['packages/spec/src/e.zod.ts', `${line}\n`]]));
8319+
const u6Line = `export const E = { entry: '/repo/node_modules/${WP_PKG}/dist/index.js' };`;
8320+
const u6 = mentionIn(WP_PKG, u6Line);
8321+
assert(u6?.kind === 'mention' && u6.line === u6Line,
8322+
`WP-U6: the package name inside a PATH string is a mention, reported with its line (${JSON.stringify(u6)})`);
8323+
const u7Line = `export const E = { docs: 'https://npm.im/${WP_PKG}' };`;
8324+
const u7 = mentionIn(WP_PKG, u7Line);
8325+
assert(u7?.kind === 'mention' && u7.line === u7Line,
8326+
`WP-U7: the package name inside a URL string is a mention, reported with its line (${JSON.stringify(u7)})`);
8327+
assert(['@scope/plugin-x', '/repo/node_modules/@scope/plugin-x/dist/index.js', 'https://npm.im/@scope/plugin-x']
8328+
.every((v) => mentionIn('plugin-x', `export const E = { v: '${v}' };`) === null),
8329+
'WP-U8: `@scope/plugin-x` is another package than an unscoped `plugin-x`, bare, in a path or in a URL');
8330+
assert(['/repo/node_modules/plugin-x/dist/index.js', 'https://npm.im/plugin-x']
8331+
.every((v) => mentionIn('plugin-x', `export const E = { v: '${v}' };`)?.kind === 'mention'),
8332+
'WP-U9: an unscoped `plugin-x` in a path or a URL is still a mention (the `/` refused is only a scope\'s)');
8333+
}
8334+
8335+
// ---- DX (#26324): an export named `default` ------------------------------
8336+
//
8337+
// `default` is an ordinary key in exactly the files predicate 2 reads -- a field
8338+
// option `{ value: 'technology', default: true }`, a Zod `.default(...)` -- so the
8339+
// bare-word arm refused every `default` retirement on every tree (measured on
8340+
// #26206's `@objectstack/driver-memory#default`). The import arm is the reading:
8341+
// a metadata surface reaches a default export only through an import binding it.
8342+
battery('DX (#26324): an export named `default` is reached through an import, never through the word');
8343+
{
8344+
const DX_KEYS = {
8345+
'packages/platform-objects/src/crm/account.object.ts':
8346+
"export const Account = { fields: { industry: { options: [{ label: 'Technology', value: 'technology', default: true }] } } };\n",
8347+
'packages/spec/src/data/field.zod.ts': "import { z } from 'zod';\nexport const FieldSchema = z.object({ label: z.string().default('') });\n",
8348+
};
8349+
const DX_HOST = 'packages/platform-objects/src/ui/host.object.ts';
8350+
const dx = (surfaces = {}) => run(mk(REX_FIXTURE(['default'],
8351+
'- FROM `default` TO `EmailServicePlugin`: register `new EmailServicePlugin()` with the kernel.', {
8352+
baseFiles: { [rexPath('src/index.ts')]: `${REX_INDEX_BASE}export default { id: 'com.objectstack.plugin.email' };\n`, ...DX_KEYS, ...surfaces },
8353+
})));
8354+
const DX_P2 = /`runtime-export-retired @objectstack\/plugin-email#default` \[predicate 2: no-metadata-surface\] is false: packages\/platform-objects\/src\/ui\/host\.object\.ts \(an object definition\) IMPORTS `default`/;
8355+
8356+
const dxG1 = dx();
8357+
green('DX-G1 THE #26206 SHAPE: a retired default export, beside unrelated `default:` keys and `.default(...)` calls in metadata surfaces', dxG1);
8358+
assert(/default \(export, packages\/plugins\/plugin-email\/src\/index\.ts\)/.test(dxG1.judged[0]?.detail ?? ''),
8359+
`DX-G1b: the verdict names the \`default\` operand and the entry that declared it. Got: ${dxG1.judged[0]?.detail}`);
8360+
green('DX-G2 a metadata surface that quotes the default import only in a COMMENT', dx({
8361+
[DX_HOST]: `// import emailPlugin from '${REX_PKG}';\nexport const Host = { name: 'host', default: true };\n`,
8362+
}));
8363+
green('DX-G3 a metadata surface that imports ANOTHER module\'s default', dx({
8364+
[DX_HOST]: "import other from '@objectstack/spec';\nexport const Host = { name: 'host', plugin: other };\n",
8365+
}));
8366+
red('DX-R1 a metadata surface that IMPORTS the package\'s default', dx({
8367+
[DX_HOST]: `import emailPlugin from '${REX_PKG}';\nexport const Host = { name: 'host', plugin: emailPlugin };\n`,
8368+
}), [DX_P2]);
8369+
red('DX-R2 ...and the same default named inside the braces, `{ default as x }`', dx({
8370+
[DX_HOST]: `import { default as emailPlugin } from '${REX_PKG}';\nexport const Host = { name: 'host', plugin: emailPlugin };\n`,
8371+
}), [DX_P2]);
8372+
8373+
const DX_DECL = rexPath('src/index.ts');
8374+
const dxPkgs = () => new Map([[REX_PKG, { private: false, file: rexPath('package.json') }]]);
8375+
const dxRef = (text) => metadataSurfaceReference('default', DX_DECL, new Map([['packages/spec/src/a.zod.ts', text]]), dxPkgs);
8376+
assert(dxRef(`import email, { LogTransport } from '${REX_PKG}';\n`)?.kind === 'import' &&
8377+
dxRef(`import type email from '${REX_PKG}/sub';\n`)?.kind === 'import' &&
8378+
dxRef(`import { z } from 'zod'; export {\n default,\n} from '${REX_PKG}';\n`)?.kind === 'import',
8379+
'DX-U1: a default binding beside named bindings, a type-only default import of a subpath, and a ' +
8380+
'multi-line `export { default } from` after a `;` on the same line, are imports');
8381+
assert(dxRef(`import { LogTransport } from '${REX_PKG}';\nexport const A = { default: LogTransport };\n`) === null &&
8382+
dxRef(`import type { T } from '${REX_PKG}';\nexport const A = z.string().default('');\n`) === null,
8383+
'DX-U2: named bindings alone, a `default:` key and a `.default(...)` call never reach the default export');
8384+
assert(metadataSurfaceReference('LogTransport', rexPath('src/log-transport.ts'),
8385+
new Map([['packages/spec/src/a.zod.ts', 'export const A = { LogTransport: true };\n']]), dxPkgs)?.kind === 'mention',
8386+
'DX-U3: every other export name keeps the bare-word arm (a key named after it is still a mention)');
82658387
}
82668388

82678389
// ---- G6: a changeset that was ALREADY breaking at base is inherited -------

0 commit comments

Comments
 (0)