diff --git a/packages/compiler-test-utils/oracle/README.md b/packages/compiler-test-utils/oracle/README.md index 3ca9d01932..f806982b0b 100644 --- a/packages/compiler-test-utils/oracle/README.md +++ b/packages/compiler-test-utils/oracle/README.md @@ -241,8 +241,6 @@ with and without it, test by test, apart from #34 rows that passed alone. Caveats: -- **Pending user rulings hold some rows** (table below). They count toward acceptance as they are until ruled, and a - correct compiler may fail some of them: they (Q10) keep an assertion or input whose fate the ruling decides. - **Chromium can run out of shared memory in the temporary directory (FINAL-PASS #40, open).** A full router-plugin `test:integration` run at 4 workers holds up to about 2.2 GB of Chromium shared memory, in files in `TMPDIR` (Playwright starts Chromium with `--disable-dev-shm-usage`). Chromium keeps 2 MB per module script that a 304 @@ -369,11 +367,10 @@ warnings that name the importer, not `onViolation` calls. ## Lanes -| Lane | Where | Targets | Decides acceptance | -| --------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------ | -| Corpus | `tests/**`, except the noncompiler list | `test:unit`, `test:integration` | yes | -| Pending rulings | the rows the pending rulings hold (table below) | `test:unit`, `test:integration` (held in the corpus as they are) | yes, until ruled | -| Noncompiler | main's own tests at main's paths, listed in `tests/noncompiler-tests.json` (start-plugin-core, react-start-rsc) | `test:noncompiler` | no | +| Lane | Where | Targets | Decides acceptance | +| ----------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------ | +| Corpus | `tests/**`, except the noncompiler list | `test:unit`, `test:integration` | yes | +| Noncompiler | main's own tests at main's paths, listed in `tests/noncompiler-tests.json` (start-plugin-core, react-start-rsc) | `test:noncompiler` | no | The corpus (acceptance) is the compilers' test suite. Main's own tests split in two: @@ -406,9 +403,10 @@ A few pins use names a user chose that collide with today's generated names; a c flips them (RULINGS "restructured compilers"). The adaptive pins next to them read the names a compiler actually generates and are the structure-free checks. -## Pending user rulings +## User rulings on held tests -These tests are kept exactly as they are until the user rules; do not reroute or delete them before that. +No ruling is pending (2026-10-23; Q10, the owned-import cap in `router-generator/tests/owned-edits.ts`, is ruled: +RULINGS "Q10"). These rows held tests until the user ruled: | Ruling | What it holds | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -416,7 +414,6 @@ These tests are kept exactly as they are until the user rules; do not reroute or | Q4 | ruled 2026-10-23 (RULINGS "Q4"): a star re-export of a denied module is a safe mock, or the build fails (dev: warns); never a secret or crash | | Q6 | ruled 2026-10-22 (RULINGS "Q6"): the rows driving the internal compiler with a hand-built package graph are deleted; real-app tests cover what they meant | | Q7 | ruled 2026-10-22 (RULINGS "Q7"): reachable; the CommonJS pin is now a real-app pin in `start-plugin-core/tests/integration/known-bugs-start-compiler.test.ts` | -| Q10 | the owned-import numeric cap in `router-generator/tests/owned-edits.ts` | | #34 | ruled 2026-10-23 (RULINGS "Vite's dependency optimizer: close wait"): the Vite dev harnesses wait for the optimizer before `close()` | Accepted for now, to revisit at the end (2026-10-23): start-plugin-core integration memory (#57). Its workers keep diff --git a/packages/compiler-test-utils/oracle/RULINGS.md b/packages/compiler-test-utils/oracle/RULINGS.md index b134e8c121..32bdd28120 100644 --- a/packages/compiler-test-utils/oracle/RULINGS.md +++ b/packages/compiler-test-utils/oracle/RULINGS.md @@ -389,6 +389,17 @@ A real bug: `export @dec class` is valid TypeScript (5.0 and later). The pin sta (router-plugin `integration/pages/known-bugs-code-splitter-bindings.test.ts`, "a decorator after `export` compiles"). Clauses: §2.1, G1. +### Q10: other import statements (2026-10-23) + +Asked whether the generator, when it adds a missing route constructor import, may touch other import statements, the +user: "I don't think we should specify that. Let it." The oracle does not constrain the import statements: the +generator may write a new import or edit, merge, split, reorder or reprint any of them, router package or not, and +no cap limits how many change. What stays checked is the outcome: the route file still evaluates with the real +router, its `Route` has the right constructor and id, everything outside the import statements keeps its bytes, and +the imports still bind what the user's code uses (each binding with its imported and local name, source module, +type/value meaning and import attributes; side-effect imports stay). `router-generator/tests/owned-edits.ts` +(`expectOnlyOwnedEdits`). Clauses: J1.1, J1.2. + ## Start (J4–J7) ### D2: `generateFunctionId` input diff --git a/packages/compiler-test-utils/oracle/SPEC.md b/packages/compiler-test-utils/oracle/SPEC.md index fd3a2d9c4c..df0b2142a0 100644 --- a/packages/compiler-test-utils/oracle/SPEC.md +++ b/packages/compiler-test-utils/oracle/SPEC.md @@ -316,10 +316,13 @@ rsc, srcDirectory, … })` `[type: start-plugin-core/src/schema.ts]`. Which clau a template literal), replacing it with the correct literal (J1.2 still holds elsewhere) and an actionable diagnostic naming the file are both acceptable; tests accept either outcome `[ruling: valid alternative compilers]`. `[doc: api/router/createFileRouteFunction.md:15-22; createLazyFileRouteFunction.md:15]` - **J1.2** Nothing else in the file changes: other statements, comments, formatting, line endings and the file's - encoding are byte-preserved outside the edited literal/import. Newly scaffolded files follow `quoteStyle` and - `semicolons`. Within the edited argument the quote character is free; an edited import keeps its other - bindings, aliases and type/value meaning; keeping or removing a factory import the edit made unused (e.g. - `createFileRoute` after a switch to `createLazyFileRoute`) are both allowed. Filesystem metadata (mode, owner) + encoding are byte-preserved outside the edited literal and the import statements. Newly scaffolded files follow + `quoteStyle` and `semicolons`. Within the edited argument the quote character is free. How the generator adds, + moves or drops the factory's binding is free: it may write a new import or edit, merge, split, reorder or reprint + any import statement `[ruling: Q10]`, as long as every other binding keeps its imported and local name, source + module, type/value meaning and import attributes, and every side-effect import stays; keeping or removing a + factory import the edit made unused (e.g. `createFileRoute` after a switch to `createLazyFileRoute`) are both + allowed. Filesystem metadata (mode, owner) is outside this clause (§1.2). `[doc: api/file-based-routing.md:171-187]` - **J1.3** An empty route file is scaffolded from the default template or `customScaffolding.{routeTemplate, lazyRouteTemplate}`; `.lazy.tsx`/`.lazy.ts` files get the lazy template (a `.lazy.vue` piece is an SFC, not a diff --git a/packages/router-generator/tests/owned-edits.ts b/packages/router-generator/tests/owned-edits.ts index c628c9031c..2f37c668fd 100644 --- a/packages/router-generator/tests/owned-edits.ts +++ b/packages/router-generator/tests/owned-edits.ts @@ -2,25 +2,23 @@ * Shared test helper: what the generator may change in a route file it * keeps up (SPEC J1.1, J1.2). * - * The generator owns the route id argument of the `Route` constructor call, - * the constructor's callee (`createFileRoute` / `createLazyFileRoute`) and - * the router package import statements that bind a route constructor (to - * add, move or drop the constructor's binding). When the file does not - * import the constructor its callee now names, the generator may also add - * that binding to one other router package import (or write a new import). - * Everything else is the user's and keeps its exact bytes: other - * statements, the other imports (other router package imports included), - * comments, formatting and line endings. Inside the edited imports, the - * other bindings keep their imported name, local name, source package and - * type/value meaning; an import of the constructor under its own name may - * stay or go (the edit may have made it unused, J1.2), an aliased one is the - * user's. The quote character and printing of the edited argument and of an - * edited import are free, and so is where an import sits among the imports - * (§5.5). + * The generator owns the route id argument of the `Route` constructor call + * and the constructor's callee (`createFileRoute` / `createLazyFileRoute`), + * and it may add, move or drop the constructor's binding. How it does that + * to the import statements is free (ruling Q10): it may write a new import + * or edit, merge, split, reorder or reprint any import statement. What the + * imports bind is the user's: every binding keeps its imported name, local + * name, source module, type/value meaning and import attributes, and every + * side-effect import stays. A value import of a route constructor under its + * own name from a router package may stay or go (the edit may have made it + * unused, J1.2); an aliased one, or one from another module, is the user's. + * Everything outside the import statements keeps its exact bytes: other + * statements, comments, formatting and line endings. The quote character and + * printing of the edited argument are free. * * `expectOnlyOwnedEdits(before, after)` asserts exactly that; the caller * checks the outcome of the edit itself (`routeCallOf`: the constructor and - * the id the file now has). + * the id the file now has) and that the file still evaluates. */ import { parseSync } from 'vite' import { expect } from 'vitest' @@ -37,84 +35,73 @@ type Node = Record /** A marker that occurs in no source. */ const owned = '\u0000' -/** A router package import statement of a module. */ -interface RouterImport { - start: number - end: number - /** The statement's exact source text. */ - text: string - /** Whether it binds a route constructor (under any local name). */ - bindsConstructor: boolean - /** The local names it binds. */ - locals: Array - /** - * Its bindings other than value imports of a route constructor under its - * own name: ` as from ` (`* as ` for a - * namespace), with `type ` in front of type-only ones. - */ - bindings: Array +function importsOf(code: string, fileName: string) { + const { program } = parseSync(fileName, code) + return (program.body as Array).filter( + (statement) => statement.type === 'ImportDeclaration', + ) } -function routerImportsOf(code: string, fileName: string) { - const { program } = parseSync(fileName, code) - const imports: Array = [] - for (const statement of program.body as Array) { - if ( - statement.type !== 'ImportDeclaration' || - !routerPackages.test(statement.source.value) - ) { - continue - } +function nameOf(node: Node) { + return (node.type === 'Identifier' ? node.name : node.value) as string +} + +/** + * What the import statements of `code` bind, one entry per binding + * (` as from `, `* as ` for a namespace, + * `type ` in front of type-only ones) and per side-effect import + * (`import `), each with the statement's import attributes; without + * value imports of a route constructor under its own name from a router + * package. Sorted, without duplicates. + */ +function bindingsOf(code: string, fileName: string) { + const bindings = new Set() + for (const statement of importsOf(code, fileName)) { const source = statement.source.value as string - const entry: RouterImport = { - start: statement.start, - end: statement.end, - text: code.slice(statement.start, statement.end), - bindsConstructor: false, - locals: [], - bindings: [], + const attributes = ((statement.attributes ?? []) as Array) + .map((attribute) => `${nameOf(attribute.key)}: ${attribute.value.value}`) + .sort() + const from = `${source}${attributes.length ? ` with { ${attributes.join(', ')} }` : ''}` + const specifiers = statement.specifiers as Array + if (specifiers.length === 0) { + bindings.add(`import ${from}`) } - for (const specifier of statement.specifiers as Array) { + for (const specifier of specifiers) { const type = statement.importKind === 'type' || specifier.importKind === 'type' ? 'type ' : '' const local = specifier.local.name as string - entry.locals.push(local) if (specifier.type === 'ImportNamespaceSpecifier') { - entry.bindings.push(`${type}* as ${local} from ${source}`) + bindings.add(`${type}* as ${local} from ${from}`) } else if (specifier.type === 'ImportDefaultSpecifier') { - entry.bindings.push(`${type}default as ${local} from ${source}`) + bindings.add(`${type}default as ${local} from ${from}`) } else { - const imported = - specifier.imported.type === 'Identifier' - ? specifier.imported.name - : specifier.imported.value - if (constructors.has(imported)) { - entry.bindsConstructor = true - // (an aliased constructor import is the user's: other code may use it) - if (!type && local === imported) { - continue - } + const imported = nameOf(specifier.imported) + if ( + !type && + local === imported && + constructors.has(imported) && + routerPackages.test(source) + ) { + continue } - entry.bindings.push(`${type}${imported} as ${local} from ${source}`) + bindings.add(`${type}${imported} as ${local} from ${from}`) } } - imports.push(entry) } - return imports + return [...bindings].sort() } /** * `code` with the spans the generator owns replaced by markers, and without - * the lines that held nothing but router package imports (where an import - * sits is free; the router package imports are compared separately). + * the lines that held nothing but import statements (the import statements + * are compared by what they bind). */ function unownedText(code: string, fileName: string) { - const spans: Array<[number, number, string]> = routerImportsOf( - code, - fileName, - ).map((statement) => [statement.start, statement.end, 'import']) + const spans: Array<[number, number, string]> = importsOf(code, fileName).map( + (statement) => [statement.start, statement.end, 'import'], + ) const call = routeCallSpansOf(code, fileName) spans.push([...call.callee, 'constructor']) if (call.id) { @@ -137,27 +124,6 @@ function unownedText(code: string, fileName: string) { .join('') } -/** `from` without one statement of the same exact text per statement of `other`. */ -function withoutStatementsOf( - from: Array, - other: Array, -) { - const remaining = other.map((statement) => statement.text) - return from.filter((statement) => { - const index = remaining.indexOf(statement.text) - if (index === -1) { - return true - } - remaining.splice(index, 1) - return false - }) -} - -/** The identifier a callee (`createFileRoute`, `Router.createFileRoute`) starts with. */ -function rootIdentifierOf(callee: string) { - return /^[\p{ID_Start}$_][\p{ID_Continue}$‌‍]*/u.exec(callee)?.[0] -} - /** * Asserts that `after` (a route file as the generator left it) differs from * `before` only where the generator may edit it: see the module comment. @@ -169,37 +135,10 @@ export function expectOnlyOwnedEdits( ) { expect( unownedText(after, fileName), - 'the code the generator does not own', + 'the code outside the import statements the generator does not own', ).toBe(unownedText(before, fileName)) - - const importsBefore = routerImportsOf(before, fileName) - const importsAfter = routerImportsOf(after, fileName) - // the router package imports the generator rewrote or dropped, and the - // ones it rewrote them into or added - const edited = withoutStatementsOf(importsBefore, importsAfter) - const written = withoutStatementsOf(importsAfter, importsBefore) - - const [calleeStart, calleeEnd] = routeCallSpansOf(after, fileName).callee - const calleeRoot = rootIdentifierOf(after.slice(calleeStart, calleeEnd)) - const constructorWasImported = importsBefore.some( - (statement) => calleeRoot && statement.locals.includes(calleeRoot), - ) - const editedWithoutConstructor = edited - .filter((statement) => !statement.bindsConstructor) - .map((statement) => statement.text) - if (constructorWasImported) { - expect( - editedWithoutConstructor, - 'the router package imports binding no route constructor (the file already imported the one it uses)', - ).toEqual([]) - } else { - expect( - editedWithoutConstructor.length, - 'the router package imports binding no route constructor (only one may take the missing constructor)', - ).toBeLessThanOrEqual(1) - } expect( - written.flatMap((statement) => statement.bindings).sort(), - 'the other bindings of the edited router package imports', - ).toEqual(edited.flatMap((statement) => statement.bindings).sort()) + bindingsOf(after, fileName), + 'what the import statements bind (other than the route constructor)', + ).toEqual(bindingsOf(before, fileName)) } diff --git a/packages/router-generator/tests/route-file-upkeep.test.ts b/packages/router-generator/tests/route-file-upkeep.test.ts index 479224ff60..f6508ffc85 100644 --- a/packages/router-generator/tests/route-file-upkeep.test.ts +++ b/packages/router-generator/tests/route-file-upkeep.test.ts @@ -6,11 +6,10 @@ * wrote it. Read back from disk and evaluated. * * What the generator may change is checked by `expectOnlyOwnedEdits` - * (owned-edits.ts): the id argument, the constructor callee and the router - * package imports, whose other bindings stay. An unused import of the other - * route constructor may be removed or kept (coordinator ruling on audit D - * ASK-1; SPEC J1.2), and the printing of an edited import (quotes, - * semicolons, line) is free. + * (owned-edits.ts): the id argument, the constructor callee and the import + * statements, as long as every other binding they hold stays (ruling Q10). + * An unused import of the other route constructor may be removed or kept + * (coordinator ruling on audit D ASK-1; SPEC J1.2). */ import path from 'node:path' import { afterEach, describe, expect, test, vi } from 'vitest'