: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(ci): block new frontend layer imports (#126768)
Paul D'Ambra31e6acfc967b
diff --git a/.github/workflows/ci-frontend.yml b/.github/workflows/ci-frontend.ymlindex ecc32082befb..0f4bf069b8ac 100644--- a/.github/workflows/ci-frontend.yml+++ b/.github/workflows/ci-frontend.yml@@ -514,6 +514,22 @@ jobs:- name: Build frontend (bundle-size + eager-graph report)run: pnpm --filter=@posthog/frontend build:with-report+ # Reads the layer report the build above wrote, so it needs no second esbuild pass. It runs+ # before the base build resets the tree, because the baseline it compares with must be the+ # PR's. continue-on-error keeps the base build and the CI report running; the last step of+ # this job turns a failure here into the job's verdict.+ - name: Check frontend layer imports+ id: layer-check+ if: github.event_name == 'pull_request'+ continue-on-error: true+ run: |+ REPORT="frontend/layer-report-${GITHUB_SHA}.json"+ if [ ! -f "$REPORT" ] || ! grep -q -- '--from-report' frontend/bin/check-layers.mjs; then+ echo "Skipping frontend layer check, no layer report or check script on this checkout"+ exit 0+ fi+ node frontend/bin/check-layers.mjs --from-report "$REPORT"+# The PR's layer graph, written by build:with-report before the base build replaces it.- name: Upload frontend layer graphid: layer-graph@@ -717,6 +733,12 @@ jobs:"event_type": ${{ toJSON(github.event_name) }}}+ - name: Fail on frontend layer check+ if: ${{ !cancelled() && steps.layer-check.outcome == 'failure' }}+ run: |+ echo "::error::The frontend layer check failed. Read the log of the 'Check frontend layer imports' step for the cause. A layer failure there names each new upward import or fixed baseline entry, and the command that fixes it."+ exit 1+frontend-typescript-checks:name: Frontend typecheckingneeds: [changes]@@ -810,16 +832,6 @@ jobs:- name: Validate SetupTaskId completionsrun: node bin/validate-setup-tasks.mjs- # Warn-only until the baseline has settled on master; then drop continue-on-error.- - name: Check frontend layer imports- continue-on-error: true- run: |- if [ ! -f frontend/bin/check-layers.mjs ]; then- echo "Skipping frontend layer check, script not present on this checkout"- exit 0- fi- node frontend/bin/check-layers.mjs-# Warn-only until the baseline has settled on master; then drop continue-on-error.- name: Check frontend stylesheet importscontinue-on-error: truediff --git a/frontend/bin/check-layers.mjs b/frontend/bin/check-layers.mjsindex d1d324760c57..8ec7f2bbb439 100644--- a/frontend/bin/check-layers.mjs+++ b/frontend/bin/check-layers.mjs@@ -6,6 +6,7 @@// node frontend/bin/check-layers.mjs --update-baseline rewrite the baseline, new debt included// node frontend/bin/check-layers.mjs --html <file> write an interactive view of the graph// node frontend/bin/check-layers.mjs --report-only write layer-report.json for the CI report, never fail+// node frontend/bin/check-layers.mjs --from-report <f> check a layer report against the baseline, no rebuildimport { execSync } from 'node:child_process'import fs from 'node:fs'import path from 'node:path'@@ -14,7 +15,7 @@ import { AUTHENTICATED_SHELL } from './bootEntries.mjs'import { chainTo, isAssetPath, readImportGraph, repoRoot, staticReach } from './importGraph.mjs'import { renderLayerGraphHtml } from './layerGraphHtml.mjs'import { findOpportunities } from './layerOpportunities.mjs'-import { LAYERS, isUpward, layerOf } from './layers.mjs'+import { LAYERS, compareWithBaseline, isUpward, layerOf } from './layers.mjs'const baselinePath = path.join(repoRoot, 'frontend', 'bin', 'layer-baseline.txt')const BASELINE_HEADER = `# Static imports from a lower frontend layer into a higher one (see frontend/bin/layers.mjs).@@ -58,55 +59,80 @@ function eagerBytesByLayer(files, reach) {return totals}+function eagerChainsOf(upward, shellReach) {+ return Object.fromEntries(+ upward+ .map((edge) => edge.split(' -> ')[0])+ .filter((from) => shellReach.has(from))+ .map((from) => [from, chainTo(shellReach, from)])+ )+}++function readReport(reportPath) {+ const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'))+ return { current: report.upward, eagerChains: report.eagerChains ?? {} }+}+const args = process.argv.slice(2)const htmlIndex = args.indexOf('--html')+const fromReportIndex = args.indexOf('--from-report')+if (fromReportIndex !== -1 && (htmlIndex !== -1 || args.includes('--report-only'))) {+ console.error('--from-report reads an existing report, so it cannot be combined with --html or --report-only.')+ process.exit(2)+}-const files = await readImportGraph()-const shellRoot = `frontend/${AUTHENTICATED_SHELL}`-const shellReach = staticReach(files, shellRoot)-const current = upwardImports(files)-const baseline = readBaseline()-const added = current.filter((edge) => !baseline.includes(edge))-const fixed = baseline.filter((edge) => !current.includes(edge))--const mib = (bytes) => `${(bytes / 2 ** 20).toFixed(2)} MiB`-const eager = eagerBytesByLayer(files, shellReach)-console.info(- `Upward imports: ${current.length} (${baseline.length} in the baseline, ${added.length} new, ${fixed.length} fixed)`-)-console.info(- `Shell eager graph by layer (source bytes): ${LAYERS.map((layer) => `${layer} ${mib(eager[layer])}`).join(', ')}`-)+let current+let eagerChains+if (fromReportIndex !== -1) {+ ;({ current, eagerChains } = readReport(path.resolve(args[fromReportIndex + 1])))+} else {+ const files = await readImportGraph()+ const shellRoot = `frontend/${AUTHENTICATED_SHELL}`+ const shellReach = staticReach(files, shellRoot)+ current = upwardImports(files)+ eagerChains = eagerChainsOf(current, shellReach)-if (htmlIndex !== -1) {- const htmlPath = path.resolve(args[htmlIndex + 1])- const opportunities = findOpportunities({ files, shellRoot, shellReach })- fs.writeFileSync(- htmlPath,- renderLayerGraphHtml({ files, shellRoot, shellReach, upward: current, layerOf, layers: LAYERS, opportunities })+ const mib = (bytes) => `${(bytes / 2 ** 20).toFixed(2)} MiB`+ const eager = eagerBytesByLayer(files, shellReach)+ console.info(+ `Shell eager graph by layer (source bytes): ${LAYERS.map((layer) => `${layer} ${mib(eager[layer])}`).join(', ')}`)- console.info(`Wrote ${htmlPath}`)-}-// Same naming as check-eager-graph: the CI bundle-size job measures the PR and then the base in one-// workspace, so the sha-suffixed file keeps the PR's numbers and the plain file ends up with the base's.-if (args.includes('--report-only')) {- const report = {- sha: execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf-8' }).trim(),- layers: LAYERS,- eagerBytes: eager,- upward: current,- eagerChains: Object.fromEntries(- current- .map((edge) => edge.split(' -> ')[0])- .filter((from) => shellReach.has(from))- .map((from) => [from, chainTo(shellReach, from)])- ),+ if (htmlIndex !== -1) {+ const htmlPath = path.resolve(args[htmlIndex + 1])+ const opportunities = findOpportunities({ files, shellRoot, shellReach })+ fs.writeFileSync(+ htmlPath,+ renderLayerGraphHtml({+ files,+ shellRoot,+ shellReach,+ upward: current,+ layerOf,+ layers: LAYERS,+ opportunities,+ })+ )+ console.info(`Wrote ${htmlPath}`)+ }++ // Same naming as check-eager-graph: the CI bundle-size job measures the PR and then the base in one+ // workspace, so the sha-suffixed file keeps the PR's numbers and the plain file ends up with the base's.+ if (args.includes('--report-only')) {+ const { added, fixed } = compareWithBaseline(current, readBaseline())+ const report = {+ sha: execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf-8' }).trim(),+ layers: LAYERS,+ eagerBytes: eager,+ upward: current,+ eagerChains,+ baseline: { added, fixed },+ }+ const serialized = JSON.stringify(report)+ fs.writeFileSync(path.join(repoRoot, 'frontend', 'layer-report.json'), serialized)+ fs.writeFileSync(path.join(repoRoot, 'frontend', `layer-report-${report.sha}.json`), serialized)+ process.exit(0)}- const serialized = JSON.stringify(report)- fs.writeFileSync(path.join(repoRoot, 'frontend', 'layer-report.json'), serialized)- fs.writeFileSync(path.join(repoRoot, 'frontend', `layer-report-${report.sha}.json`), serialized)- process.exit(0)}if (args.includes('--update-baseline')) {@@ -114,27 +140,35 @@ if (args.includes('--update-baseline')) {console.info(`Baseline rewritten with ${current.length} entries.`)process.exit(0)}+let baseline = readBaseline()if (args.includes('--prune-baseline')) {- writeBaseline(baseline.filter((edge) => current.includes(edge)))- console.info(`Dropped ${fixed.length} fixed entries.`)- fixed.length = 0+ const kept = baseline.filter((edge) => current.includes(edge))+ writeBaseline(kept)+ console.info(`Dropped ${baseline.length - kept.length} fixed entries.`)+ baseline = kept}+const { added, fixed, failed, pruneHint, fixHint } = compareWithBaseline(current, baseline)+console.info(+ `Upward imports: ${current.length} (${baseline.length} in the baseline, ${added.length} new, ${fixed.length} fixed)`+)for (const edge of added) {const [from, to] = edge.split(' -> ')console.info(`\nNew upward import, ${layerOf(from)} -> ${layerOf(to)}:\n ${edge}`)- if (shellReach.has(from)) {+ if (eagerChains[from]) {console.info(- ` It puts ${layerOf(to)} code on the eager path of every logged-in page:\n ${chainTo(shellReach, from).join('\n -> ')}`+ ` It puts ${layerOf(to)} code on the eager path of every logged-in page:\n ${eagerChains[from].join('\n -> ')}`)}- console.info(- ` Load it with lazyWithRetry() or retryImport(() => import(...)), or move the shared code down a layer.`- )}-if (fixed.length) {- console.info(- `\n${fixed.length} baseline entries are fixed. Run \`hogli lint:frontend-layers --prune-baseline\` to lock in the win.`- )+if (fixHint) {+ console.info(`\n${fixHint}`)+}+if (pruneHint) {+ console.info(`\n${pruneHint}`)+ if (process.env.GITHUB_ACTIONS) {+ // A workflow command ends at the first newline, so GitHub needs %0A to keep the list in one annotation.+ console.info(`::error file=frontend/bin/layer-baseline.txt::${pruneHint.replaceAll('\n', '%0A')}`)+ }}-process.exit(added.length || fixed.length ? 1 : 0)+process.exit(failed ? 1 : 0)diff --git a/frontend/bin/layers.mjs b/frontend/bin/layers.mjsindex 4d4a2a820b42..3ebf7c2b94a8 100644--- a/frontend/bin/layers.mjs+++ b/frontend/bin/layers.mjs@@ -30,6 +30,25 @@ export function isUpward(fromFile, toFile) {return LAYERS.indexOf(layerOf(toFile)) > LAYERS.indexOf(layerOf(fromFile))}+// A fixed entry fails too. If it stayed in the baseline, the same upward import could come back unnoticed.+export function compareWithBaseline(current, baseline) {+ const added = current.filter((edge) => !baseline.includes(edge))+ const fixed = baseline.filter((edge) => !current.includes(edge))+ const pruneHint = fixed.length+ ? `${fixed.length} baseline entries are fixed. Run \`hogli lint:frontend-layers --prune-baseline\` to drop them:\n${fixed.map((edge) => ` ${edge}`).join('\n')}`+ : null+ const fixHint = added.length+ ? [+ 'Fix each new upward import in one of these ways:',+ ' 1. Move the imported code down to the layer of the importer, or lower.',+ ' 2. Load it with a dynamic import: lazyWithRetry() or retryImport(() => import(...)).',+ ' 3. Register it in a registry that the higher layer fills.',+ 'Never run --update-baseline to hide a new upward import. Run --prune-baseline only after you fix one.',+ ].join('\n')+ : null+ return { added, fixed, failed: added.length > 0 || fixed.length > 0, pruneHint, fixHint }+}+export const shortName = (file) => file.replace(/^frontend\/src\//, '')// Folder a report shows a file under: a product, a lib component, or a top-level folder.diff --git a/frontend/bin/layers.test.ts b/frontend/bin/layers.test.tsindex 91b791c44885..6a7e4a6a356d 100644--- a/frontend/bin/layers.test.ts+++ b/frontend/bin/layers.test.ts@@ -1,4 +1,4 @@-import { isUpward, layerOf } from './layers.mjs'+import { compareWithBaseline, isUpward, layerOf } from './layers.mjs'describe('layers.mjs', () => {it.each([@@ -28,4 +28,40 @@ describe('layers.mjs', () => {])('%s -> %s is upward: %s', (from, to, upward) => {expect(isUpward(from, to)).toEqual(upward)})++ const NEW = 'frontend/src/layout/Navigation.tsx -> frontend/src/scenes/max/maxLogic.tsx'+ const KEPT = 'frontend/src/lib/components/Command/Command.tsx -> frontend/src/scenes/max/maxLogic.tsx'+ const FIXED = 'frontend/src/models/thing.ts -> frontend/src/scenes/dashboard/dashboardLogic.tsx'++ const PRUNE_HINT = `1 baseline entries are fixed. Run \`hogli lint:frontend-layers --prune-baseline\` to drop them:\n ${FIXED}`+ const FIX_HINT = [+ 'Fix each new upward import in one of these ways:',+ ' 1. Move the imported code down to the layer of the importer, or lower.',+ ' 2. Load it with a dynamic import: lazyWithRetry() or retryImport(() => import(...)).',+ ' 3. Register it in a registry that the higher layer fills.',+ 'Never run --update-baseline to hide a new upward import. Run --prune-baseline only after you fix one.',+ ].join('\n')++ it.each([+ [+ 'an exact match passes',+ [KEPT],+ [KEPT],+ { added: [], fixed: [], failed: false, pruneHint: null, fixHint: null },+ ],+ [+ 'a new edge fails',+ [KEPT, NEW],+ [KEPT],+ { added: [NEW], fixed: [], failed: true, pruneHint: null, fixHint: FIX_HINT },+ ],+ [+ 'a fixed edge fails with the prune hint',+ [KEPT],+ [KEPT, FIXED],+ { added: [], fixed: [FIXED], failed: true, pruneHint: PRUNE_HINT, fixHint: null },+ ],+ ])('compares with the baseline: %s', (_, current, baseline, expected) => {+ expect(compareWithBaseline(current, baseline)).toEqual(expected)+ })})diff --git a/frontend/bin/post-layer-comment.mjs b/frontend/bin/post-layer-comment.mjsindex e6464414fdb4..bc2569bbb30d 100644--- a/frontend/bin/post-layer-comment.mjs+++ b/frontend/bin/post-layer-comment.mjs@@ -22,13 +22,45 @@ export function compareLayerReports(report, baseReport) {}// Edge and chain paths come from the PR's own build output, so a crafted file name could carry-// a newline or an HTML comment delimiter and forge the CI report's own section markers.+// a newline, an HTML comment delimiter or a backtick, and forge the CI report's markers or markdown.const sanitizeForReport = (text) =>text.replace(/[\r\n]/g, ' ')+ .replace(/`/g, "'").replace(/<!--/g, '< !--').replace(/-->/g, '-- >')const shortName = (file) => sanitizeForReport(file.replace(/^frontend\/src\//, ''))+const formatEdge = (edge) => `\`${edge.split(' -> ').map(shortName).join(' -> ')}\``++function listEdges(lines, edges) {+ lines.push(...edges.slice(0, MAX_LISTED).map((edge) => `- ${formatEdge(edge)}`))+ if (edges.length > MAX_LISTED) {+ lines.push(`- …and ${edges.length - MAX_LISTED} more.`)+ }+ lines.push('')+}++// A report from before that field existed has no verdict, so it renders as a comparison with the base only.+function renderBaselineVerdict(lines, verdict) {+ if (verdict.added.length) {+ lines.push(+ `❌ ${verdict.added.length} upward import(s) are not in \`layer-baseline.txt\`, so the layer check fails:`,+ ''+ )+ listEdges(lines, verdict.added)+ lines.push(+ 'Move the shared code down a layer, or load the higher layer with `lazyWithRetry()` or `retryImport(() => import(...))`.',+ ''+ )+ }+ if (verdict.fixed.length) {+ lines.push(+ `❌ ${verdict.fixed.length} fixed entry(ies) are still in \`layer-baseline.txt\`. Run \`hogli lint:frontend-layers --prune-baseline\` to drop them:`,+ ''+ )+ listEdges(lines, verdict.fixed)+ }+}export function renderLayerSection(report, baseReport, graphUrl) {const { added, removed, layers } = compareLayerReports(report, baseReport)@@ -45,13 +77,18 @@ export function renderLayerSection(report, baseReport, graphUrl) {),'',]+ const verdict = report.baseline+ const verdictFails = Boolean(verdict && (verdict.added.length || verdict.fixed.length))+ if (verdictFails) {+ renderBaselineVerdict(lines, verdict)+ }if (!baseReport) {lines.push('ℹ️ No base report, so new and removed imports are not listed.', '')}for (const edge of added.slice(0, MAX_LISTED)) {const [from] = edge.split(' -> ')const chain = report.eagerChains?.[from]- lines.push(`🟡 New upward import: \`${edge.split(' -> ').map(shortName).join(' -> ')}\``)+ lines.push(`🟡 New upward import: ${formatEdge(edge)}`)if (chain) {lines.push('',@@ -85,6 +122,10 @@ export function renderLayerSection(report, baseReport, graphUrl) {lines.push('<sub>Posted automatically by [check-layers](https://github.com/PostHog/posthog/blob/master/frontend/bin/check-layers.mjs)</sub>')+ if (verdictFails) {+ const summary = `${verdict.added.length} import(s) not in the baseline, ${verdict.fixed.length} fixed baseline entry(ies)`+ return { status: 'fail', summary, body: lines.join('\n') }+ }// Without a base there is no comparison, so a new upward import must not read as a pass.if (!baseReport) {return { status: 'info', summary: 'no base comparison available', body: lines.join('\n') }diff --git a/frontend/bin/post-layer-comment.test.ts b/frontend/bin/post-layer-comment.test.tsindex 15d3ec8a484e..15b49e786848 100644--- a/frontend/bin/post-layer-comment.test.ts+++ b/frontend/bin/post-layer-comment.test.ts@@ -1,30 +1,77 @@import { compareLayerReports, renderLayerSection } from './post-layer-comment.mjs'-const report = (upward: string[]): Record<string, unknown> => ({+type Verdict = { added: string[]; fixed: string[] }++const report = (upward: string[], baseline?: Verdict): Record<string, unknown> => ({layers: ['kernel', 'shell', 'query', 'features'],eagerBytes: { kernel: 100, shell: 200, query: 0, features: 50 },upward,eagerChains: {},+ ...(baseline ? { baseline } : {}),})+const CLEAN: Verdict = { added: [], fixed: [] }+describe('post-layer-comment.mjs', () => {it.each([- ['a new upward import', ['a -> b', 'c -> d'], ['a -> b'], ['c -> d'], [], 'warn'],- ['a removed upward import', ['a -> b'], ['a -> b', 'c -> d'], [], ['c -> d'], 'ok'],- ['no change', ['a -> b'], ['a -> b'], [], [], 'ok'],- ])('reports %s against the base, not the baseline', (_, prUpward, baseUpward, added, removed, status) => {- expect(compareLayerReports(report(prUpward), report(baseUpward))).toMatchObject({ added, removed })- expect(renderLayerSection(report(prUpward), report(baseUpward), undefined).status).toEqual(status)+ ['a new upward import, report without a verdict', ['a -> b', 'c -> d'], ['a -> b'], undefined, 'warn'],+ ['a removed upward import, report without a verdict', ['a -> b'], ['a -> b', 'c -> d'], undefined, 'ok'],+ ['no change, report without a verdict', ['a -> b'], ['a -> b'], undefined, 'ok'],+ [+ 'a new import missing from the baseline',+ ['a -> b', 'c -> d'],+ ['a -> b'],+ { added: ['c -> d'], fixed: [] },+ 'fail',+ ],+ [+ 'a fixed import still in the baseline',+ ['a -> b'],+ ['a -> b', 'c -> d'],+ { added: [], fixed: ['c -> d'] },+ 'fail',+ ],+ ['a new import the PR also adds to the baseline', ['a -> b', 'c -> d'], ['a -> b'], CLEAN, 'warn'],+ ['no change with a clean verdict', ['a -> b'], ['a -> b'], CLEAN, 'ok'],+ ])('reports %s', (_, prUpward, baseUpward, verdict, status) => {+ expect(renderLayerSection(report(prUpward, verdict), report(baseUpward), undefined).status).toEqual(status)})- it('lists nothing as new, and does not claim a pass, when the base has no report', () => {+ it('lists new and removed imports against the base, not the baseline', () => {+ expect(compareLayerReports(report(['a -> b', 'c -> d']), report(['a -> b', 'e -> f']))).toMatchObject({+ added: ['c -> d'],+ removed: ['e -> f'],+ })+ })++ it('names each failing edge and the fix for it', () => {+ const { summary, body } = renderLayerSection(+ report(['a -> b', 'c -> d'], { added: ['c -> d'], fixed: ['e -> f'] }),+ report(['a -> b', 'e -> f']),+ undefined+ )+ expect(summary).toEqual('1 import(s) not in the baseline, 1 fixed baseline entry(ies)')+ expect(body).toContain('`c -> d`')+ expect(body).toContain('`e -> f`')+ expect(body).toContain('hogli lint:frontend-layers --prune-baseline')+ })++ it.each([+ ['does not claim a pass', undefined, 'info'],+ ['still fails on the baseline verdict', { added: ['a -> b'], fixed: [] }, 'fail'],+ ])('without a base report, it lists nothing as new and %s', (_, verdict, status) => {expect(compareLayerReports(report(['a -> b']), null)).toMatchObject({ added: [], removed: [] })- expect(renderLayerSection(report(['a -> b']), null, undefined).status).toEqual('info')+ expect(renderLayerSection(report(['a -> b'], verdict), null, undefined).status).toEqual(status)})- it('neutralizes a report marker hidden in an edge path', () => {- const withMarker = report(['a -> b', `evil<!-- ci-report:section-end:eager-graph --> -> b`])- const { body } = renderLayerSection(withMarker, report(['a -> b']), undefined)+ const EVIL = 'evil<!-- ci-report:section-end:eager-graph -->`[x](https://example.com)` -> b'++ it.each([+ ['a new import vs base', report(['a -> b', EVIL])],+ ['a baseline verdict', report(['a -> b'], { added: [EVIL], fixed: [EVIL] })],+ ])('neutralizes a report marker and a backtick hidden in an edge path in %s', (_, prReport) => {+ const { body } = renderLayerSection(prReport, report(['a -> b']), undefined)expect(body).not.toContain('<!-- ci-report:section-end:eager-graph -->')+ expect(body).not.toContain('`[x](https://example.com)`')})})