|
| 1 | +/** |
| 2 | + * The cross-package `_`-field contract with `@solidjs/signals`. |
| 3 | + * |
| 4 | + * Signals' prod and observe artifacts mangle every `_`-prefixed property |
| 5 | + * (scripts/mangle-props.mjs) except a reserved list; the dev artifact is |
| 6 | + * unmangled. Any `_` field a downstream package reads or writes on a |
| 7 | + * signals object — an `Owner`, `Computed`, `Signal` — therefore only works |
| 8 | + * in every tier if it is on that list. The suite cannot see this: it runs |
| 9 | + * against source, where nothing is mangled. Two things went wrong before |
| 10 | + * this spec existed — the client's hydration root lookup walked `_parent` |
| 11 | + * (mangled → the wrong snapshot scope in prod), and the core's owner walks |
| 12 | + * found nothing on a server owner in the observe tier (`OBSERVE.exclude` a |
| 13 | + * silent no-op) — so the contract is pinned from both ends here: |
| 14 | + * |
| 15 | + * - the reserved fields survive in the mangled signals artifacts, and a |
| 16 | + * private one does not (so a change to the mangler's regex or list shows); |
| 17 | + * - every `_` field the built client artifacts of solid-js and |
| 18 | + * @solidjs/web touch is either reserved or not a signals field at all. |
| 19 | + * |
| 20 | + * Requires a prior `pnpm build`. |
| 21 | + */ |
| 22 | +import { readdirSync, readFileSync, statSync } from "node:fs"; |
| 23 | +import { join, resolve } from "node:path"; |
| 24 | +import { describe, expect, test } from "vitest"; |
| 25 | + |
| 26 | +const ROOT = resolve(import.meta.dirname, "../.."); |
| 27 | +const SIGNALS = join(ROOT, "signals"); |
| 28 | + |
| 29 | +/** The mangler's reserved list, read from the script so the two cannot drift. */ |
| 30 | +function reservedFields(): string[] { |
| 31 | + const script = readFileSync(join(SIGNALS, "scripts/mangle-props.mjs"), "utf8"); |
| 32 | + const match = script.match(/reserved:\s*\[([^\]]*)\]/); |
| 33 | + if (!match) throw new Error("mangle-props.mjs: could not find the reserved list"); |
| 34 | + return [...match[1].matchAll(/"(_\w+)"/g)].map(m => m[1]); |
| 35 | +} |
| 36 | + |
| 37 | +/** Every `_` field declared on signals' node types — the ones the mangler renames. */ |
| 38 | +function signalsFields(): Set<string> { |
| 39 | + const types = readFileSync(join(SIGNALS, "src/core/types.ts"), "utf8"); |
| 40 | + return new Set([...types.matchAll(/^\s+(_\w+)\??:/gm)].map(m => m[1])); |
| 41 | +} |
| 42 | + |
| 43 | +function jsFiles(dir: string): string[] { |
| 44 | + const out: string[] = []; |
| 45 | + for (const entry of readdirSync(dir)) { |
| 46 | + const path = join(dir, entry); |
| 47 | + if (statSync(path).isDirectory()) { |
| 48 | + if (entry !== "types" && entry !== "node_modules") out.push(...jsFiles(path)); |
| 49 | + } else if (entry.endsWith(".js")) out.push(path); |
| 50 | + } |
| 51 | + return out; |
| 52 | +} |
| 53 | + |
| 54 | +/** `._name` member accesses in `code`, by field, with a short context for the report. */ |
| 55 | +function fieldAccesses(code: string): Map<string, string> { |
| 56 | + const seen = new Map<string, string>(); |
| 57 | + for (const m of code.matchAll(/\.(_[A-Za-z]\w*)\b/g)) { |
| 58 | + if (!seen.has(m[1])) seen.set(m[1], code.slice(Math.max(0, m.index! - 40), m.index! + 40)); |
| 59 | + } |
| 60 | + return seen; |
| 61 | +} |
| 62 | + |
| 63 | +describe("cross-package _-fields", () => { |
| 64 | + const reserved = reservedFields(); |
| 65 | + |
| 66 | + test("the mangler reserves the two owner fields downstream packages walk", () => { |
| 67 | + expect(reserved).toEqual(expect.arrayContaining(["_name", "_parent"])); |
| 68 | + }); |
| 69 | + |
| 70 | + test("the reserved fields survive in the mangled signals artifacts; a private one does not", () => { |
| 71 | + for (const tier of ["prod", "observe"]) { |
| 72 | + const core = readFileSync(join(SIGNALS, `dist/${tier}/core/core.js`), "utf8"); |
| 73 | + for (const field of reserved) expect(core, `${tier}: ${field}`).toMatch(`.${field}`); |
| 74 | + // `_firstChild` is the owner tree's other link and is private: its |
| 75 | + // absence proves the mangler ran on this file at all. |
| 76 | + expect(core, `${tier}: _firstChild should be mangled`).not.toMatch("._firstChild"); |
| 77 | + } |
| 78 | + // The dev artifact is the unmangled one the suite runs against (flat and |
| 79 | + // code-split: the core sits in the chunk shared with the engine entry). |
| 80 | + const dev = readdirSync(join(SIGNALS, "dist")) |
| 81 | + .filter(f => /^dev.*\.js$/.test(f)) |
| 82 | + .map(f => readFileSync(join(SIGNALS, "dist", f), "utf8")) |
| 83 | + .join("\n"); |
| 84 | + expect(dev).toMatch("._firstChild"); |
| 85 | + }); |
| 86 | + |
| 87 | + test("the built client artifacts touch no signals field the mangler renames", () => { |
| 88 | + const fields = signalsFields(); |
| 89 | + expect(fields.has("_parent")).toBe(true); // the parser found the node types |
| 90 | + const artifacts = [ |
| 91 | + ...jsFiles(join(ROOT, "solid/dist")), |
| 92 | + ...jsFiles(join(ROOT, "web/dist")), |
| 93 | + ...jsFiles(join(ROOT, "web/frames/dist")), |
| 94 | + ...jsFiles(join(ROOT, "web/server-functions/dist")), |
| 95 | + ...jsFiles(join(ROOT, "universal/dist")) |
| 96 | + ].filter( |
| 97 | + // Server artifacts work on solid-js's own SSR owners, whose `_` fields |
| 98 | + // are solid-js's and unmangled; only the client's objects are signals'. |
| 99 | + f => !/[/\\]server[^/\\]*\.js$/.test(f) && !/[/\\]server[/\\]/.test(f) |
| 100 | + ); |
| 101 | + expect(artifacts.length).toBeGreaterThan(5); |
| 102 | + const offenders: string[] = []; |
| 103 | + for (const file of artifacts) { |
| 104 | + for (const [field, context] of fieldAccesses(readFileSync(file, "utf8"))) { |
| 105 | + if (fields.has(field) && !reserved.includes(field)) |
| 106 | + offenders.push(`${file.slice(ROOT.length + 1)}: ${field} — …${context.trim()}…`); |
| 107 | + } |
| 108 | + } |
| 109 | + expect( |
| 110 | + offenders, |
| 111 | + "a downstream artifact reads a signals `_` field the mangler renames — reserve it in " + |
| 112 | + "packages/signals/scripts/mangle-props.mjs or stop reaching into the node" |
| 113 | + ).toEqual([]); |
| 114 | + }); |
| 115 | +}); |
0 commit comments