Unverified Commit 76cf4089 authored by vercel-fleet-prod[bot]'s avatar vercel-fleet-prod[bot] Committed by GitHub

Teach analyzer fact and judgment workflow

Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent 16aa2bd5
...@@ -38,14 +38,16 @@ pnpm exec next experimental-analyze \ ...@@ -38,14 +38,16 @@ pnpm exec next experimental-analyze \
"loadScopes":["initial"], "loadScopes":["initial"],
"groupBy":"package", "groupBy":"package",
"metric":"compressed", "metric":"compressed",
"limit":100 "limit":500
}' }'
``` ```
`loadScopes` are module-graph heuristics, not network measurements. An `initial` `loadScopes` use exact route entries in current analyzer artifacts, with a
source is reachable from the route through synchronous edges. An `async` source labeled heuristic fallback for older artifacts. They are graph evidence, not
is behind at least one asynchronous edge. Use source inspection to determine network measurements. An `initial` source is reachable from the route through
whether the feature is actually needed before interaction. synchronous edges. An `async` source is behind at least one asynchronous edge.
Use source inspection to determine whether the feature is actually needed before
interaction.
Common opportunities include: Common opportunities include:
...@@ -73,6 +75,14 @@ pnpm exec next experimental-analyze \ ...@@ -73,6 +75,14 @@ pnpm exec next experimental-analyze \
}' }'
``` ```
For a complete account of every synchronous path retaining a candidate, query
`get_initial_import_graph`. Its SCC-collapsed graph reports edge counterfactuals
without enumerating exponentially many path arrays. Before changing an edge,
use `analyze_import_edge` to list the sources/packages and estimated attribution
that would leave initial scope. Use `get_route_outputs` and `get_css_assets` for
emitted CSS/media evidence; those queries do not claim the browser requested the
files.
After each change, regenerate and compare analyzer data. Source cleanup or a After each change, regenerate and compare analyzer data. Source cleanup or a
type-only import change can have zero bundle impact when the bundler already type-only import change can have zero bundle impact when the bundler already
removes it, so do not infer a win from the source diff. Removal, narrower imports, removes it, so do not infer a win from the source diff. Removal, narrower imports,
......
...@@ -26,8 +26,9 @@ compatibility. ...@@ -26,8 +26,9 @@ compatibility.
- Optimize **initial browser work**, not total package size in isolation. - Optimize **initial browser work**, not total package size in isolation.
- Treat analyzer compressed sizes as independently compressed attribution - Treat analyzer compressed sizes as independently compressed attribution
estimates, not network-transfer measurements. estimates, not network-transfer measurements.
- `loadScopes` are graph-reachability heuristics. They do not prove request - `loadScopes` are graph reachability, using exact route entries when the
timing; source and browser behavior settle that. artifact provides them and an explicitly labeled heuristic fallback for older
artifacts. They do not prove request timing; source and browser behavior do.
- Never move code behind a dynamic boundary when it is already `async`. - Never move code behind a dynamic boundary when it is already `async`.
- Inspect source before narrowing a namespace or moving work server-side. - Inspect source before narrowing a namespace or moving work server-side.
Runtime lookup, enumeration, live editing, or local-only data may require it. Runtime lookup, enumeration, live editing, or local-only data may require it.
...@@ -81,7 +82,7 @@ Rank client route totals and save the baseline snapshot ID returned by ...@@ -81,7 +82,7 @@ Rank client route totals and save the baseline snapshot ID returned by
```bash ```bash
pnpm exec next experimental-analyze \ pnpm exec next experimental-analyze \
query get_app_overview \ query get_app_overview \
--input '{"environment":"client","metric":"compressed","limit":100}' --input '{"environment":"client","metric":"compressed","limit":500}'
``` ```
If the user named routes, optimize those. Otherwise start with the largest If the user named routes, optimize those. Otherwise start with the largest
...@@ -102,12 +103,29 @@ pnpm exec next experimental-analyze \ ...@@ -102,12 +103,29 @@ pnpm exec next experimental-analyze \
"loadScopes":["initial"], "loadScopes":["initial"],
"groupBy":"package", "groupBy":"package",
"metric":"compressed", "metric":"compressed",
"limit":100 "limit":500
}' }'
``` ```
Change `groupBy` to `source` to list individual initial-scope modules. Page Change `groupBy` to `source` to list individual initial-scope modules. Use
through every result when `pagination.truncated` is true. Rank candidates using `--all` for the complete bounded result and `--fields` when only a few row facts
are needed; do not manually loop offsets:
```bash
pnpm exec next experimental-analyze \
query get_route_modules \
--all \
--fields key,compressedSize,loadScopes,chunkCount \
--input '{
"route":"/dashboard",
"environment":"client",
"loadScopes":["initial"],
"groupBy":"source",
"metric":"compressed"
}'
```
Rank candidates using
all of: all of:
- estimated initial client contribution; - estimated initial client contribution;
...@@ -130,7 +148,7 @@ pnpm exec next experimental-analyze \ ...@@ -130,7 +148,7 @@ pnpm exec next experimental-analyze \
"loadScopes":["initial"], "loadScopes":["initial"],
"groupBy":"source", "groupBy":"source",
"search":"node_modules/<package>", "search":"node_modules/<package>",
"limit":100 "limit":500
}' }'
pnpm exec next experimental-analyze \ pnpm exec next experimental-analyze \
...@@ -143,17 +161,64 @@ pnpm exec next experimental-analyze \ ...@@ -143,17 +161,64 @@ pnpm exec next experimental-analyze \
}' }'
``` ```
### Reverse import edges When `chunkCount` matters, enumerate the selected source's exact emitted outputs
instead of expecting chunk names inline on every module row:
```bash
pnpm exec next experimental-analyze \
query get_source_chunks \
--all \
--input '{
"route":"/dashboard",
"sourcePath":"<exact sourcePath>"
}'
```
### Reverse import edges and counterfactuals
Run reverse-edge analysis **before editing**. Start with
`explain_route_module` to select an exact `moduleIdent` and, when relevant, a
`routeEntryId`. Use its project importer and client-boundary evidence to find
the source that must be inspected; do not choose a boundary from package name
or size alone.
Run reverse-edge analysis **before editing**. `explain_route_module` walks from Then ask the CLI for the complete synchronous predecessor graph. This graph is
an attributed source back toward the route entry and can reveal that the right the factual representation of every synchronous path keeping the selected
fix is an intermediate re-export or application import rather than the named module initial; SCCs represent cycles without enumerating path arrays:
package itself.
Use `nearestProjectImporter`, `nearestClientBoundary`, `firstAsyncBoundary`, ```bash
`importerChain`, and both chain orientations to find the application source to pnpm exec next experimental-analyze \
inspect. When an explanation is ambiguous, select a returned `moduleIdent`; do query get_initial_import_graph \
not guess one. --input '{
"route":"/dashboard",
"environment":"client",
"sourcePath":"<exact sourcePath>",
"moduleIdent":"<selected moduleIdent>",
"routeEntryId":"<selected routeEntryId>"
}'
```
Use each edge's `targetRemainsInitial` and `leavingInitial*` fields to reject
false positives caused by alternate synchronous paths. Before editing a
promising edge, request its full source/package impact:
```bash
pnpm exec next experimental-analyze \
query analyze_import_edge \
--all \
--input '{
"route":"/dashboard",
"sourcePath":"<exact sourcePath>",
"moduleIdent":"<selected moduleIdent>",
"routeEntryId":"<selected routeEntryId>",
"edgeId":"<edgeId from get_initial_import_graph>",
"granularity":"source"
}'
```
The CLI owns reachability, SCC, edge-cut, and byte calculations. The agent owns
the judgment about whether the reported edge is an appropriate product and
source boundary to change.
### Baseline comparisons ### Baseline comparisons
...@@ -168,13 +233,30 @@ pnpm exec next experimental-analyze \ ...@@ -168,13 +233,30 @@ pnpm exec next experimental-analyze \
"granularity":"route", "granularity":"route",
"environment":"client", "environment":"client",
"metric":"compressed", "metric":"compressed",
"limit":100 "limit":500
}' }'
``` ```
For package or source attribution, set `granularity` to `package` or `source` For package or source attribution, set `granularity` to `package` or `source`
and pass the target `route`. Use `get_route_modules` on each snapshot when you and pass the target `route`. For lazy-loading proof, query source granularity
need to compare `initial` versus `async` scope rather than bytes. with `"scopeTransition":"initial-to-async"`; do not manually compare two scope
lists:
```bash
pnpm exec next experimental-analyze \
query compare_bundles \
--all \
--input '{
"baselineSnapshot":"<saved baseline snapshot ID>",
"comparisonSnapshot":"current",
"granularity":"source",
"route":"/dashboard",
"environment":"client",
"scopeTransition":"initial-to-async"
}'
```
The CLI returns the transition and aggregate totals directly.
## 3. Evaluate opportunities ## 3. Evaluate opportunities
...@@ -326,23 +408,31 @@ Inspect these only when analyzer evidence ranks them materially: ...@@ -326,23 +408,31 @@ Inspect these only when analyzer evidence ranks them materially:
- the same expensive initial dependency repeated across routes instead of being - the same expensive initial dependency repeated across routes instead of being
removed, narrowed, or deliberately shared. removed, narrowed, or deliberately shared.
Assets need a separate pass because they may not carry module reachability: Assets need a separate factual pass. Query actual emitted outputs rather than
interpreting source-level `asset` attribution as filenames:
```bash ```bash
pnpm exec next experimental-analyze \ pnpm exec next experimental-analyze \
query get_route_modules \ query get_route_outputs \
--all \
--fields filename,kind,compressedSize,outputCount \
--input '{ --input '{
"route":"/dashboard", "route":"/dashboard",
"environment":"client", "kinds":["css","font","image","media"],
"fileTypes":["css","asset"], "groupBy":"file",
"groupBy":"source", "metric":"compressed"
"metric":"compressed",
"limit":100
}' }'
pnpm exec next experimental-analyze \
query get_css_assets \
--all \
--input '{"route":"/dashboard"}'
``` ```
Use this as route attribution only. Whether a font/image/CSS file was actually `emissionEvidence` and CSS output-reference evidence are build facts.
requested during cold initial navigation requires browser network evidence. `requestEvidence: "unknown"` means the CLI has not observed a browser request.
Whether a file was requested during cold initial navigation remains separate
browser network evidence, tabled from this workflow.
Do not maintain a generic package deny list. Tie every recommendation to Do not maintain a generic package deny list. Tie every recommendation to
measured route evidence and inspected source behavior. measured route evidence and inspected source behavior.
...@@ -364,10 +454,10 @@ For each candidate: ...@@ -364,10 +454,10 @@ For each candidate:
5. Query the affected route/source again. 5. Query the affected route/source again.
6. For removal, server migration, narrowing, or deduplication, require a client 6. For removal, server migration, narrowing, or deduplication, require a client
byte reduction. For lazy loading, require `initial` → `async` and verify the byte reduction. For lazy loading, require the CLI's direct
trigger. `initial-to-async` transition and verify the trigger.
7. When two distinct snapshots exist, use `compare_bundles` for route/package 7. When two distinct snapshots exist, use `compare_bundles` for route/package
byte deltas; use source queries for scope changes. Treat a source-only or deltas and source scope transitions. Treat a source-only or
type-only edit with no analyzer delta as no bundle win. type-only edit with no analyzer delta as no bundle win.
8. Run targeted behavior tests and the narrowest relevant type-check. The 8. Run targeted behavior tests and the narrowest relevant type-check. The
analyzer has already performed its own production analysis, so do not start analyzer has already performed its own production analysis, so do not start
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment