Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

15.9 KB
Raw Blame
import { spawnSync } from 'node:child_process'
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import path from 'node:path'

import { loggedOutSpecifiers, planStableChunks, shiftMappingsForPrelude, stableFileName } from './stableChunkNames.mjs'

// Two chunks: an entry that imports a shared chunk, the way esbuild writes them with publicPath /static.
const OUTPUTS = {
    'dist/Scene-AAAA1111.js': { entryPoint: 'src/scenes/Scene.tsx', inputs: { 'src/scenes/Scene.tsx': {} } },
    'dist/chunk-BBBB2222.js': { inputs: { 'src/lib/shared.ts': {}, 'src/lib/other.ts': {} } },
}

function plan(sources: Record<string, string>): Map<string, { source: string; mapValid: boolean }> {
    return planStableChunks(OUTPUTS, (outputPath: string) => sources[outputPath]).plan
}

describe('planStableChunks', () => {
    const entry = (shared: string, own = 'render()'): Record<string, string> => ({
        'dist/Scene-AAAA1111.js': `import{a}from"/static/chunk-BBBB2222.js";${own};new URL("/static/Inter-CCCC3333.woff2");new Worker(new URL("/static/chunk-BBBB2222.js"))`,
        'dist/chunk-BBBB2222.js': shared,
    })

    // The point of the step: a changed chunk must not rename the chunks that import it, or returning
    // users download those again after every deploy.
    it.each([
        [
            'keeps the importer when only the imported chunk changes',
            entry('export const a=1'),
            entry('export const a=2'),
            true,
        ],
        [
            'renames the importer when its own code changes',
            entry('export const a=1'),
            entry('export const a=1', 'renderAgain()'),
            false,
        ],
    ])('%s', (_name, before, after, importerKeepsSource) => {
        const [first, second] = [plan(before), plan(after)]
        expect(first.get('dist/Scene-AAAA1111.js')!.source === second.get('dist/Scene-AAAA1111.js')!.source).toBe(
            importerKeepsSource
        )
    })

    it('rewrites chunk imports to identity specifiers and leaves URLs alone', () => {
        const before = entry('export const a=1')
        const { source } = plan(before).get('dist/Scene-AAAA1111.js')!

        expect(source).toMatch(/from"@c\/c[0-9A-F]{10}"/)
        expect(source).not.toContain('from"/static/chunk-BBBB2222.js"')
        expect(source).toContain('new URL("/static/chunk-BBBB2222.js")')
        expect(source).toContain('"/static/Inter-CCCC3333.woff2"')
    })

    it('pads a shorter specifier so the rewritten source keeps its original length', () => {
        const before = entry('export const a=1')
        const { source, mapValid } = plan(before).get('dist/Scene-AAAA1111.js')!

        expect(source.length).toBe(before['dist/Scene-AAAA1111.js'].length)
        expect(source).toMatch(/from"@c\/c[0-9A-F]{10}" +;/)
        expect(mapValid).toBe(true)
    })

    describe('identity collisions', () => {
        afterEach(() => jest.restoreAllMocks())

        it('warns and falls back to a unique name when two chunks share an identity', () => {
            // Two chunks with no inputs hash to the same identity (see the comment in the source).
            const outputs = {
                'dist/chunk-EEEE0000.js': {},
                'dist/chunk-FFFF0000.js': {},
            }
            const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})

            const { plan: collisionPlan } = planStableChunks(outputs, () => '')

            expect(warn).toHaveBeenCalledWith(expect.stringContaining('identity collision for dist/chunk-'))
            expect(collisionPlan.get('dist/chunk-EEEE0000.js')!.identity).not.toBe(
                collisionPlan.get('dist/chunk-FFFF0000.js')!.identity
            )
        })

        it('marks the map invalid when a collision fallback identity outgrows a short chunk name', () => {
            // Both empty-input chunks hash to the same identity; the second falls back to a longer
            // one (its own identity plus a hash of its output path), which can outgrow a short
            // original file name and make the replacement longer than the specifier it replaces.
            const outputs = {
                'dist/c-a.js': {},
                'dist/c-b.js': {},
                'dist/e-x.js': { entryPoint: 'src/x.tsx', inputs: { 'src/x.tsx': {} } },
            }
            const sources: Record<string, string> = {
                'dist/c-a.js': '',
                'dist/c-b.js': '',
                'dist/e-x.js': 'from"/static/c-b.js";render()',
            }
            jest.spyOn(console, 'warn').mockImplementation(() => {})

            const { plan: collisionPlan } = planStableChunks(outputs, (outputPath: string) => sources[outputPath])

            expect(collisionPlan.get('dist/e-x.js')!.mapValid).toBe(false)
        })
    })

    describe('stableFileName', () => {
        it('throws when the esbuild output name has no -<hash> suffix to replace', () => {
            expect(() => stableFileName('index.js', 'source')).toThrow(/does not end in the expected/)
        })
    })

    // Pins the one-line shift so a regression here doesn't only show up as misattributed stack traces.
    describe('shiftMappingsForPrelude', () => {
        it('adds one leading empty generated line to the mappings', () => {
            expect(shiftMappingsForPrelude('AAAA')).toBe(';AAAA')
        })
    })

    // The copied source map is shifted down exactly one line, so the prelude must be a line of its own.
    it('puts a prelude on its own first line, keyed by the chunk specifier', () => {
        const sources = entry('export const a=1')
        const withPrelude = planStableChunks(
            OUTPUTS,
            (outputPath: string) => sources[outputPath],
            'dist/',
            new Map([['dist/Scene-AAAA1111.js', (specifier: string) => `register(${JSON.stringify(specifier)});`]])
        ).plan.get('dist/Scene-AAAA1111.js')!

        expect(withPrelude.source.split('\n')[0]).toMatch(/^register\("@c\/e[0-9A-F]{10}"\);$/)
    })

    it('imports a chunk with a prelude dynamically through the stylesheet-aware loader, and statically as is', () => {
        const outputs = {
            ...OUTPUTS,
            'dist/Lazy-DDDD4444.js': { entryPoint: 'src/scenes/Lazy.tsx', inputs: { 'src/scenes/Lazy.tsx': {} } },
        }
        const importer =
            'import("/static/Lazy-DDDD4444.js");import("/static/chunk-BBBB2222.js");import"/static/Lazy-DDDD4444.js"'
        const { plan: lazyPlan } = planStableChunks(
            outputs,
            (outputPath: string) => (outputPath === 'dist/Scene-AAAA1111.js' ? importer : ''),
            'dist/',
            new Map([['dist/Lazy-DDDD4444.js', () => 'register();']])
        )
        const { source, mapValid } = lazyPlan.get('dist/Scene-AAAA1111.js')!

        expect(source).toMatch(
            /^ESBUILD_IMPORT\("@c\/e[0-9A-F]{10}" *\);import\("@c\/c[0-9A-F]{10}" *\);import"@c\/e[0-9A-F]{10}" *$/
        )
        expect(mapValid).toBe(true)
    })

    describe('writeStableChunks', () => {
        interface Written {
            files: Record<string, string>
            stableFileOf: (outputPath: string) => string
        }

        // esbuild refuses to load under jsdom, so the writer runs in a node process of its own.
        function runWriter(
            absWorkingDir: string,
            outputs: Record<string, object>,
            preludes: Record<string, string>
        ): any {
            const script = `
                const { writeStableChunks } = await import(${JSON.stringify(path.join(__dirname, 'stableChunkNames.mjs'))})
                const [absWorkingDir, outputs, preludes] = JSON.parse(process.argv[1])
                const { manifest } = await writeStableChunks({
                    absWorkingDir,
                    outputs,
                    chunks: {},
                    entrypoints: [],
                    preloadManifest: undefined,
                    preludes: new Map(Object.entries(preludes).map(([file, prelude]) => [file, () => prelude])),
                    target: 'es2020',
                })
                process.stdout.write(JSON.stringify(manifest))
            `
            const result = spawnSync(
                'node',
                ['--input-type=module', '-e', script, JSON.stringify([absWorkingDir, outputs, preludes])],
                { encoding: 'utf8' }
            )
            if (result.status !== 0) {
                throw new Error(result.stderr)
            }
            return JSON.parse(result.stdout)
        }

        function write(
            outputs: Record<string, object>,
            sources: Record<string, string>,
            preludes: Record<string, string> = {}
        ): Written {
            const absWorkingDir = mkdtempSync(path.join(tmpdir(), 'stable-chunks-'))
            try {
                const distDir = path.join(absWorkingDir, 'dist')
                mkdirSync(distDir, { recursive: true })
                for (const [outputPath, source] of Object.entries(sources)) {
                    writeFileSync(path.join(absWorkingDir, outputPath), source)
                }

                const manifest = runWriter(absWorkingDir, outputs, preludes)

                const files = Object.fromEntries(
                    readdirSync(distDir).map((file) => [file, readFileSync(path.join(distDir, file), 'utf8')])
                )
                const { plan: written } = planStableChunks(outputs, (outputPath: string) => sources[outputPath])
                const stableFileOf = (outputPath: string): string =>
                    manifest.imports[`@c/${written.get(outputPath)!.identity}`].replace(/^static\//, '')
                return { files, stableFileOf }
            } finally {
                rmSync(absWorkingDir, { recursive: true, force: true })
            }
        }

        // Minified while bundling, an unchanged library chunk got new bytes, and a new name, on most deploys.
        it('keeps a chunk stable name when only a chunk it imports changes', () => {
            const library = 'const someLongLibraryName=function(){return 1};export{someLongLibraryName as a};'
            const sources = (render: string): Record<string, string> => ({
                'dist/Scene-AAAA1111.js': `import{a as libraryValue}from"/static/chunk-BBBB2222.js";${render}`,
                'dist/chunk-BBBB2222.js': library,
            })

            const before = write(OUTPUTS, sources('console.log(libraryValue())'))
            const after = write(OUTPUTS, sources('console.log(libraryValue(),2)'))

            const libraryFile = before.stableFileOf('dist/chunk-BBBB2222.js')
            expect(after.stableFileOf('dist/chunk-BBBB2222.js')).toBe(libraryFile)
            expect(after.stableFileOf('dist/Scene-AAAA1111.js')).not.toBe(before.stableFileOf('dist/Scene-AAAA1111.js'))
            expect(before.files[libraryFile]).not.toContain('someLongLibraryName')
        })

        // The prelude becomes part of the bytes a chunk's stable name hashes, so adding one must
        // give the chunk a new name, the same as any other change to its own code.
        it('gives a chunk a new stable name when a prelude is added', () => {
            const outputs = {
                'dist/Lazy-DDDD4444.js': { entryPoint: 'src/scenes/Lazy.tsx', inputs: { 'src/scenes/Lazy.tsx': {} } },
            }
            const sources = { 'dist/Lazy-DDDD4444.js': 'console.log(1)' }

            const noPrelude = write(outputs, sources)
            const withPrelude = write(outputs, sources, { 'dist/Lazy-DDDD4444.js': 'register();' })

            expect(withPrelude.stableFileOf('dist/Lazy-DDDD4444.js')).not.toBe(
                noPrelude.stableFileOf('dist/Lazy-DDDD4444.js')
            )
        })

        // A wrong map only shows up later, as stack traces that point at the wrong code.
        it.each([
            ['a prelude chunk', { 'dist/entry-AAAA1111.js': 'register();' }],
            ['a chunk with no prelude', {}],
        ])('points the source map of %s back at the original source', (_name, preludes) => {
            const outputs = {
                'dist/entry-AAAA1111.js': { entryPoint: 'src/entry.tsx', inputs: { 'src/entry.tsx': {} } },
            }
            const { files, stableFileOf } = write(
                outputs,
                {
                    'dist/entry-AAAA1111.js': 'console.log(1)\n//# sourceMappingURL=entry-AAAA1111.js.map\n',
                    'dist/entry-AAAA1111.js.map': JSON.stringify({
                        version: 3,
                        sources: ['../src/entry.tsx'],
                        sourcesContent: ['console.log(1)'],
                        names: [],
                        mappings: 'AAAA',
                    }),
                },
                preludes
            )

            const stableFile = stableFileOf('dist/entry-AAAA1111.js')
            expect(files[stableFile]).toContain(`//# sourceMappingURL=${stableFile}.map`)
            const map = JSON.parse(files[`${stableFile}.map`])
            expect(map.sources).toEqual(['../src/entry.tsx'])
            expect(map.sourcesContent).toEqual(['console.log(1)'])
        })
    })

    describe('loggedOutSpecifiers', () => {
        // The entry imports App, which lazy-loads a logged-out scene, a signed-in scene and a helper.
        const WALK_OUTPUTS = {
            'dist/index-AAAA1111.js': {
                entryPoint: 'src/index.tsx',
                imports: [{ path: 'dist/App-BBBB2222.js', kind: 'dynamic-import' }],
            },
            'dist/App-BBBB2222.js': {
                entryPoint: 'src/scenes/App.tsx',
                imports: [
                    { path: 'dist/Login-CCCC3333.js', kind: 'dynamic-import' },
                    { path: 'dist/Insight-DDDD4444.js', kind: 'dynamic-import' },
                    { path: 'dist/helper-EEEE5555.js', kind: 'dynamic-import' },
                ],
            },
            'dist/Login-CCCC3333.js': {
                entryPoint: 'src/scenes/Login.tsx',
                imports: [{ path: 'dist/chunk-FFFF6666.js', kind: 'import-statement' }],
            },
            'dist/Insight-DDDD4444.js': {
                entryPoint: '../products/insights/Insight.tsx',
                imports: [{ path: 'dist/chunk-GGGG7777.js', kind: 'import-statement' }],
            },
            'dist/helper-EEEE5555.js': { entryPoint: 'src/lib/helper.ts', imports: [] },
            'dist/chunk-FFFF6666.js': { inputs: { 'src/lib/form.ts': {} }, imports: [] },
            'dist/chunk-GGGG7777.js': { inputs: { 'src/lib/chart.ts': {} }, imports: [] },
        }
        const walkPlan = planStableChunks(WALK_OUTPUTS, () => 'export {}', 'dist/').plan
        const specifierOf = (outputPath: string): string => `@c/${walkPlan.get(outputPath)!.identity}`
        const walk = (loggedOutModules: string[]): string[] =>
            loggedOutSpecifiers(WALK_OUTPUTS, walkPlan, {
                entry: 'src/index.tsx',
                loggedOutModules: new Set(loggedOutModules),
                signedInModules: new Set(['../products/insights/Insight']),
                cssSpecifiersByOutput: new Map([
                    ['dist/Login-CCCC3333.js', ['@css/login']],
                    ['dist/Insight-DDDD4444.js', ['@css/insight']],
                ]),
            })

        it('keeps what a logged-out page can load and drops the chunks of signed-in scenes', () => {
            expect(walk(['src/scenes/Login'])).toEqual(
                [
                    ...[
                        'dist/index-AAAA1111.js',
                        'dist/App-BBBB2222.js',
                        'dist/Login-CCCC3333.js',
                        'dist/helper-EEEE5555.js',
                        'dist/chunk-FFFF6666.js',
                    ].map(specifierOf),
                    '@css/login',
                ].sort()
            )
        })

        it('fails when a logged-out scene is not reachable from the entry', () => {
            expect(() => walk(['src/scenes/Login', 'src/scenes/Renamed'])).toThrow('src/scenes/Renamed')
        })
    })
})