diff --git a/packages/router-utils/src/compiler/README.md b/packages/router-utils/src/compiler/README.md index 2cf31bbb44..a3df6f3b13 100644 --- a/packages/router-utils/src/compiler/README.md +++ b/packages/router-utils/src/compiler/README.md @@ -292,6 +292,13 @@ directives, never license comments. the mutation model. A property of any other value may be a getter, and that includes an enum that escapes (`w(E)`, `const a = E`, `E.__defineGetter__(…)`), an imported enum (one module can't tell it from any other value) and a `declare enum` (whatever the global is). + Placement's own judgement of a top-level evaluation (the unit model, `ModuleAnalysis.effectPurity`) adds rule L + (`languagePurity`): a member read, a spread, `in`/`instanceof`, a call or `new` of a standard global + (`Object.keys`, `new Set`, `Math.max`, `JSON.stringify`, `new Intl.NumberFormat`) and a method of what one returns + or of a literal (`Object.entries(x).map(f)`), with pure arguments, are no effect; a function such a call is handed + runs there, so an inline one's calls are judged the same way, a named one of the module too, and an imported one + is an effect. Getters, proxies, iterators and `toString` stay outside the model, as for reads (R97). What may be + deleted (`effects()` of raw facts, function-scope orphans) still counts every operation that may run code. - **Builder chains** (`purity.ts` `builderCall`): a recognizer's `builderLinks` (Start's: `createServerFn()…handler()`, `createMiddleware()…server()`, `createIsomorphicFn()…`) name each link's argument and the environment that keeps it. In one environment's purity, a chain whose kept arguments are pure is no effect: an argument the environment's diff --git a/packages/router-utils/src/compiler/analysis.ts b/packages/router-utils/src/compiler/analysis.ts index 515dba2d64..a18b460eae 100644 --- a/packages/router-utils/src/compiler/analysis.ts +++ b/packages/router-utils/src/compiler/analysis.ts @@ -19,6 +19,7 @@ import { SymbolTable, valueBinding } from './symbols' import { buildItems, buildUnits, memberUse } from './units' import { MutationModel, writeConstruct, writeKind } from './mutation' import { + languagePurity, linkedBuilder, noteBuilderConsts, seedNoSideEffectDeclarations, @@ -375,6 +376,8 @@ export class ModuleAnalysis { readonly hasImportOrExport: boolean /** The planners' purity (with a compile's builder chains: `env`). */ readonly purity: PurityContext + /** The purity the unit model judges top-level effects with, for placement: the planners', where language operations are no effect (rule L, `languagePurity`). */ + readonly effectPurity: PurityContext /** The purity of the module's own statements, whatever the environment (`effects()` derives each one's). */ private readonly ownPurity: PurityContext /** The recognizer's chain factories the module imports, if any (each environment's builder purity). */ @@ -515,6 +518,7 @@ export class ModuleAnalysis { opts.env && builderImports ? builderPurityOf(ownPurity, builderImports, opts.env).ctx : ownPurity + this.effectPurity = languagePurity(this.purity) for (let i = this.header.directiveCount; i < body.length; i++) { const stmt = body[i]! switch (stmt.type) { @@ -1140,7 +1144,7 @@ export class ModuleAnalysis { file, items, symbols, - this.purity, + this.effectPurity, (s) => this.importIndexOfStatement(s), ) diff --git a/packages/router-utils/src/compiler/kept-diagnostics.ts b/packages/router-utils/src/compiler/kept-diagnostics.ts index 14aa8245a2..4d226e50f5 100644 --- a/packages/router-utils/src/compiler/kept-diagnostics.ts +++ b/packages/router-utils/src/compiler/kept-diagnostics.ts @@ -286,7 +286,8 @@ function annotationFrees( (n?.type === 'CallExpression' || n?.type === 'NewExpression') && n.arguments.every( (a) => - a.type !== 'SpreadElement' && isPureExpression(plan.analysis.purity, a), + a.type !== 'SpreadElement' && + isPureExpression(plan.analysis.effectPurity, a), ) ) } @@ -419,12 +420,15 @@ export function firstImpure( if (n.type === 'ObjectExpression') { for (const p of n.properties) { if (p.type === 'SpreadElement') { - if (!isPureExpression(analysis.purity, p)) { + if (!isPureExpression(analysis.effectPurity, p)) { return { node: p, key } } continue } - if (p.computed && !isPureExpression(analysis.purity, p.key as Node)) { + if ( + p.computed && + !isPureExpression(analysis.effectPurity, p.key as Node) + ) { return { node: p.key as Node, key } } if (p.kind !== 'init' || env.isErasedAt(p.start)) { @@ -440,7 +444,7 @@ export function firstImpure( } return null } - return isPureExpression(analysis.purity, v) ? null : { node: v, key } + return isPureExpression(analysis.effectPurity, v) ? null : { node: v, key } } let n: Node = unwrapExpression(expr) let calls = 0 diff --git a/packages/router-utils/src/compiler/purity.ts b/packages/router-utils/src/compiler/purity.ts index 5a0cbb5a4a..4e38c91a20 100644 --- a/packages/router-utils/src/compiler/purity.ts +++ b/packages/router-utils/src/compiler/purity.ts @@ -11,7 +11,7 @@ * plain enum of the module (`isPlainEnum`; a property of any other object may be a getter). * `import()` is impure. The same classification yields the module's own effects at statement granularity (`ModuleAnalysis.effects()`). */ -import { BindingFlags } from 'yuku' +import { BindingFlags, walk } from 'yuku' import { unwrapExpression } from './source' import { ownEntry } from './strings' import type { @@ -46,6 +46,251 @@ export interface PurityContext { * (`ModuleAnalysisOptions.env`). */ builders?: BuilderPurity + /** + * Rule L (`languagePurity`): language operations are no effect. Set on + * the purity placement judges effects with (`ModuleAnalysis.effectPurity`), + * never on the one that decides what may be deleted. + */ + language?: boolean +} + +/** + * The purity placement judges a top-level evaluation's effects with (rule + * L): `ctx`, and a member read, a spread, `in` and `instanceof`, a call or + * `new` of a standard global (`Object.keys`, `new Set`, `Math.max`, + * `JSON.stringify`, `new Intl.NumberFormat`, …) and a method of the value + * one returns or of a literal (`Object.entries(x).map(f)`, `'a,b'.split()`), + * with pure arguments, are no effect. A function such a call is handed runs + * there: an inline one's calls must be language operations too, a named one + * of the module is judged so, an imported one is an effect. Getters, + * proxies, iterators and `toString` stay outside the model, as for reads + * (R97): the language defines what these operations do, a library does not. + * Only placement's timing takes it: what may be deleted (`effects()`, the + * orphans) still counts every operation that may run code. + */ +export function languagePurity(ctx: PurityContext): PurityContext { + return { ...ctx, language: true } +} + +/** The standard globals whose calls (`Number(x)`) are language operations. */ +const LANGUAGE_FUNCTIONS = new Set([ + 'Array', + 'BigInt', + 'Boolean', + 'Number', + 'Object', + 'String', + 'Symbol', + 'decodeURI', + 'decodeURIComponent', + 'encodeURI', + 'encodeURIComponent', + 'isFinite', + 'isNaN', + 'parseFloat', + 'parseInt', + 'structuredClone', +]) +/** The standard constructors whose `new` is a language operation. */ +const LANGUAGE_CONSTRUCTORS = new Set([ + 'Array', + 'Date', + 'Error', + 'Map', + 'Object', + 'RegExp', + 'Set', + 'URL', + 'URLSearchParams', + 'WeakMap', + 'WeakSet', +]) +/** The standard namespaces and constructors whose statics (`Object.keys`) are language operations: all of them (`true`), or these. */ +const LANGUAGE_STATICS = new Map | true>([ + [ + 'Object', + new Set([ + 'create', + 'entries', + 'freeze', + 'fromEntries', + 'getOwnPropertyNames', + 'keys', + 'values', + ]), + ], + ['Array', new Set(['from', 'isArray', 'of'])], + ['Date', new Set(['UTC', 'now', 'parse'])], + ['Symbol', new Set(['for'])], + ['Intl', true], + ['JSON', true], + ['Math', true], + ['Number', true], + ['String', true], +]) + +/** Whether an identifier names a global (no binding of the module or of a scope around it). */ +function isGlobal(ctx: PurityContext, id: Node): boolean { + return ctx.file.referenceOf(id)?.binding === null +} + +/** Whether calling (or `new` of) `callee` is a language operation, its arguments aside (rule L). */ +function languageCallee( + ctx: PurityContext, + callee: Node, + isNew: boolean, +): boolean { + const c = unwrapExpression(callee) + if (c.type === 'Identifier') { + return ( + isGlobal(ctx, c) && + (isNew ? LANGUAGE_CONSTRUCTORS : LANGUAGE_FUNCTIONS).has(c.name) + ) + } + if (c.type !== 'MemberExpression') { + return false + } + const object = unwrapExpression(c.object as Node) + if (object.type === 'Identifier' && isGlobal(ctx, object)) { + const statics = LANGUAGE_STATICS.get(object.name) + const name = + !c.computed && c.property.type === 'Identifier' ? c.property.name : null + return ( + statics === true || + (statics !== undefined && name !== null && statics.has(name)) + ) + } + // a method of a value the language made: a literal, or what a language + // operation returns (`Object.entries(x).map`, `new Set(a).has`) + if (isNew) { + return false + } + switch (object.type) { + case 'ArrayExpression': + case 'ObjectExpression': + case 'Literal': + case 'TemplateLiteral': + return true + case 'CallExpression': + case 'NewExpression': + return languageCallee(ctx, object.callee, object.type === 'NewExpression') + default: + return false + } +} + +/** + * A function a language operation is handed, which it may call: an inline + * one whose body only calls language operations (or calls the model takes + * as pure), and creates no module; a named one, if a function of the module + * (`follow`: judged so) or not a function the module declares. An import + * may be any function: an effect. + */ +function languageCallback( + ctx: PurityContext, + arg: Node, + follow: boolean, +): boolean { + const a = unwrapExpression(arg) + if (a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression') { + return languageBody(ctx, a) + } + if (a.type !== 'Identifier') { + return true + } + const b = ctx.file.referenceOf(a)?.binding + if (b === undefined || b === null) { + return true + } + if (b.has(BindingFlags.Import)) { + return false + } + if (b.scope !== ctx.file.rootScope) { + return true + } + const decl = b.declarations[0] + const parent = decl === undefined ? null : ctx.file.parentOf(decl) + const fn = + parent?.type === 'FunctionDeclaration' + ? parent + : parent?.type === 'VariableDeclarator' && parent.init !== null + ? unwrapExpression(parent.init) + : null + if ( + fn === null || + (fn.type !== 'FunctionDeclaration' && + fn.type !== 'ArrowFunctionExpression' && + fn.type !== 'FunctionExpression') + ) { + return true + } + return follow && languageBody(ctx, fn) +} + +/** Whether every call a function's body makes is a language operation or one the model takes as pure (rule L: what a language operation it is handed runs). */ +function languageBody(ctx: PurityContext, fn: Node): boolean { + let pure = true + walk(fn, { + enter: (n, w) => { + if (!pure) { + w.stop() + return + } + switch (n.type) { + case 'CallExpression': + case 'NewExpression': + pure = + hasPureAnnotation(ctx, n) || + (n.type === 'CallExpression' && + isPureCallee(ctx, unwrapExpression(n.callee))) || + (languageCallee(ctx, n.callee, n.type === 'NewExpression') && + n.arguments.every((a) => + languageCallback( + ctx, + a.type === 'SpreadElement' ? a.argument : a, + false, + ), + )) + break + case 'TaggedTemplateExpression': + pure = languageCallee(ctx, n.tag, false) + break + case 'ImportExpression': + pure = false + break + case 'ClassExpression': + case 'ClassDeclaration': + pure = isPureClass(ctx, n) + break + case 'JSXElement': + pure = isPureJsxTag(ctx, n.openingElement.name) + break + } + }, + }) + return pure +} + +/** A call or `new` that is a language operation with pure arguments, each function it is handed judged as it may run (rule L). */ +function isLanguageCall( + ctx: PurityContext, + node: Extract, +): boolean { + const callee = unwrapExpression(node.callee) + return ( + languageCallee(ctx, callee, node.type === 'NewExpression') && + // (a method's receiver is evaluated: `[f()].map(g)`) + (callee.type !== 'MemberExpression' || isPureExpression(ctx, callee)) && + node.arguments.every((a) => { + const arg = a.type === 'SpreadElement' ? a.argument : a + const f = unwrapExpression(arg) + return f.type === 'ArrowFunctionExpression' || + f.type === 'FunctionExpression' || + f.type === 'Identifier' + ? languageCallback(ctx, arg, true) + : isPureExpression(ctx, arg) + }) + ) } /** The builder chains `isPureExpression` takes as pure in one environment (`PurityContext.builders`). */ @@ -277,7 +522,8 @@ export function isPureExpression( (e) => e === null || (e.type === 'SpreadElement' - ? unwrapExpression(e.argument).type === 'ArrayExpression' && + ? (ctx.language === true || + unwrapExpression(e.argument).type === 'ArrayExpression') && isPureExpression(ctx, e.argument) : isPureExpression(ctx, e)), ) @@ -285,7 +531,8 @@ export function isPureExpression( return node.properties.every((p) => { if (p.type === 'SpreadElement') { return ( - unwrapExpression(p.argument).type === 'ObjectExpression' && + (ctx.language === true || + unwrapExpression(p.argument).type === 'ObjectExpression') && isPureExpression(ctx, p.argument) ) } @@ -301,8 +548,8 @@ export function isPureExpression( return node.operator !== 'delete' && isPureExpression(ctx, node.argument) case 'BinaryExpression': return ( - node.operator !== 'in' && - node.operator !== 'instanceof' && + (ctx.language === true || + (node.operator !== 'in' && node.operator !== 'instanceof')) && isPureExpression(ctx, node.left) && isPureExpression(ctx, node.right) ) @@ -334,27 +581,20 @@ export function isPureExpression( ) } return ( - ctx.builders !== undefined && - node.type === 'CallExpression' && - builderCall(ctx, ctx.builders, node) !== null + (ctx.builders !== undefined && + node.type === 'CallExpression' && + builderCall(ctx, ctx.builders, node) !== null) || + (ctx.language === true && isLanguageCall(ctx, node)) ) } case 'JSXElement': { - const name = node.openingElement.name - if (name.type === 'JSXNamespacedName') { + if (!isPureJsxTag(ctx, node.openingElement.name)) { return false } - if (name.type === 'JSXIdentifier') { - const c = name.name.charCodeAt(0) - const intrinsic = c >= 97 && c <= 122 - if (!intrinsic && !ctx.file.referenceOf(name)?.binding) { - return false - } - } return ( node.openingElement.attributes.every((a) => a.type === 'JSXSpreadAttribute' - ? false + ? ctx.language === true && isPureExpression(ctx, a.argument) : a.value === null || a.value.type === 'Literal' || a.value.type === 'JSXElement' || @@ -368,9 +608,20 @@ export function isPureExpression( case 'JSXFragment': return node.children.every((ch) => isPureJsxChild(ctx, ch)) case 'MemberExpression': - return isPlainMemberRead(ctx, node) + return ( + isPlainMemberRead(ctx, node) || + (ctx.language === true && + isPureExpression(ctx, node.object as Node) && + (!node.computed || isPureExpression(ctx, node.property as Node))) + ) case 'ChainExpression': + return ctx.language === true && isPureExpression(ctx, node.expression) case 'TaggedTemplateExpression': + return ( + ctx.language === true && + languageCallee(ctx, node.tag, false) && + node.quasi.expressions.every((e) => isPureExpression(ctx, e)) + ) case 'ImportExpression': case 'AwaitExpression': case 'YieldExpression': @@ -622,6 +873,21 @@ function isPureCallee(ctx: PurityContext, callee: Node): boolean { return false } +/** A JSX tag whose element runs no code of its own: intrinsic (`div`), or bound (``, ``). */ +function isPureJsxTag(ctx: PurityContext, name: Node): boolean { + if (name.type === 'JSXNamespacedName') { + return false + } + if (name.type === 'JSXIdentifier') { + const c = name.name.charCodeAt(0) + const intrinsic = c >= 97 && c <= 122 + if (!intrinsic && !ctx.file.referenceOf(name)?.binding) { + return false + } + } + return true +} + function isPureJsxChild(ctx: PurityContext, ch: Node): boolean { switch (ch.type) { case 'JSXText': diff --git a/packages/router-utils/src/compiler/units.ts b/packages/router-utils/src/compiler/units.ts index 0b2e85a658..e0580b698d 100644 --- a/packages/router-utils/src/compiler/units.ts +++ b/packages/router-utils/src/compiler/units.ts @@ -73,6 +73,7 @@ export interface Unit { declares: Array /** Export names this unit provides directly (`export const a`, `export { a as b }`, `default`). */ exported: Array + /** Its evaluation has an effect, as placement judges one (`ModuleAnalysis.effectPurity`: language operations are none, rule L). */ effectful: boolean /** Effect units that augment/write module bindings (`X.p = …`, `X.push(…)`, `X = …`). */ augments: Array @@ -560,6 +561,7 @@ interface UnitBuildResult { declaringUnits: Map> } +/** The unit model; `purity` judges effects (`ModuleAnalysis.effectPurity`). */ export function buildUnits( file: SourceFile, items: Array, diff --git a/packages/router-utils/tests/placement.test.ts b/packages/router-utils/tests/placement.test.ts index aeb307c8d8..a1de301bf1 100644 --- a/packages/router-utils/tests/placement.test.ts +++ b/packages/router-utils/tests/placement.test.ts @@ -2616,13 +2616,15 @@ describe('extracted-export outputs', () => { ["Page[track('k')] = 1", false], ['Page.count++', false], // a member of a namespace import reads that module's binding (no code - // runs, as for an imported identifier); a property of an imported - // object, or of a namespace member's value, may be a getter + // runs, as for an imported identifier); so, under rule L, does a + // property of an imported object ['Page.icon = Icons.Home', true], ["Page.icon = Icons['Home']", true], ['Object.assign(Page, { Item: Icons.Item })', true], - ['Page.icon = Shapes.Home', false], - ['Page.icon = Icons.Home.small', false], + // (rule L: a member read is a language operation, a getter outside the + // model as for reads, R97; not extracted before) + ['Page.icon = Shapes.Home', true], + ['Page.icon = Icons.Home.small', true], ])( 'extracts an export augmented by `%s` only when the augmentation writes nothing but pure values (%s)', async (augmentation, extracted) => { @@ -6478,8 +6480,9 @@ describe('declarations only split code needs that stay in the route module', () it('names the initialisers of several declarations in the plural', async () => { const code = dedent(` import { createFileRoute } from 'toy-router' - const homeUrl = new URL('https://example.com/') - const docsUrl = new URL('https://example.com/docs') + import { Link } from './lib' + const homeUrl = new Link('https://example.com/') + const docsUrl = new Link('https://example.com/docs') homeUrl.search = docsUrl.search = '?ref=x' export const Route = createFileRoute('/')({ component: () => [homeUrl, docsUrl], @@ -6487,11 +6490,13 @@ describe('declarations only split code needs that stay in the route module', () `) // (design 2 step 3: one statement writes both, so they are one cluster; // `const HOME = homeUrl.toString()` after `homeUrl.search = …` was one - // with `homeUrl` through ordered evaluation, and now moves) + // with `homeUrl` through ordered evaluation, and now moves; tanstack.com + // wrote `new URL`, a language operation under rule L: an unknown + // constructor keeps the shape) const r = await kept(code) expect(r.diagnostics.map((d) => d.message)).toEqual([ expect.stringContaining( - '`homeUrl`, `docsUrl` in /app/route.tsx stay in the route module because the module changes them outside their declarations when it loads (line 4); move `homeUrl`, `docsUrl` and what writes them to their own module, or mark their initialisers `/* @__PURE__ */` if they have no side effects', + '`homeUrl`, `docsUrl` in /app/route.tsx stay in the route module because the module changes them outside their declarations when it loads (line 5); move `homeUrl`, `docsUrl` and what writes them to their own module, or mark their initialisers `/* @__PURE__ */` if they have no side effects', ), ]) }) @@ -6541,7 +6546,7 @@ describe('declarations only split code needs that stay in the route module', () const route = (body: Array, options: Array) => [ "import { createFileRoute } from 'toy-router'", - "import { CONFIG, make } from './lib'", + "import { CONFIG, Link, make } from './lib'", ...body, "export const Route = createFileRoute('/')({", ...options, @@ -6581,8 +6586,9 @@ describe('declarations only split code needs that stay in the route module', () const at = (source: string) => (d: { range?: { start: number } }) => d.range?.start === source.indexOf(`${name} = `) // a template literal (openstory), or a call the annotation cannot - // free (an argument has effects): only the move - for (const init of ['`${CONFIG.url}/mcp`', 'make(CONFIG.url)']) { + // free (an argument has effects): only the move (rule L: a member + // read is none, `CONFIG.url()` is a call) + for (const init of ['`${CONFIG.url()}/mcp`', 'make(CONFIG.url())']) { const source = route(body(init), options) const d = (await report(source)).find(at(source)) expect(d, source).toMatchObject({ code }) @@ -6590,7 +6596,7 @@ describe('declarations only split code needs that stay in the route module', () expect(d!.message, source).toContain('own module') } // a call or `new`: the annotation too, and it works - for (const init of ['make()', "new URL('https://x')"]) { + for (const init of ['make()', "new Link('https://x')"]) { const source = route(body(init), options) const d = (await report(source)).find(at(source)) expect(d, source).toMatchObject({ code }) @@ -6616,7 +6622,7 @@ describe('declarations only split code needs that stay in the route module', () const [freed] = (await kept(effect("'ready'"))).diagnostics expect(freed).toMatchObject({ code: 'eager-split:order' }) expect(freed!.message).toContain('mark the call `/* @__PURE__ */`') - const [kept_] = (await kept(effect('CONFIG.url'))).diagnostics + const [kept_] = (await kept(effect('CONFIG.url()'))).diagnostics expect(kept_).toMatchObject({ code: 'eager-split:order' }) expect(kept_!.message).not.toContain('@__PURE__') expect(kept_!.message).toContain('declare `first` after it')