Unverified Commit 8619c015 authored by Will Binns-Smith's avatar Will Binns-Smith Committed by GitHub

Bundle Analyzer Agent Skill: Trace conditional async and worker chunk loading (#99174)

## Summary

Make the bundle analyzer explain how emitted chunks can load other
chunks. This gives the initial-load optimizer skill the relationships it
needs to distinguish startup code from conditionally loaded code and
trace why a dependency is reachable.

- Export typed load relationships for dynamic imports, async manifests,
and service-worker registration.
- Tie async triggers to the actual dynamically imported module.
- Preserve unresolved relationships and worker modules compiled in
separate graphs so missing data is not mistaken for “nothing loads.”

This builds on the preceding branch’s client chunk groups and
machine-readable graph export. The relationships describe possible loads
at build time; browser measurements are still needed to establish what
actually loads initially.

## Verification

- Previously reported: Next.js package no-emit types passed.
- Native dev/prod analyzer e2e and a full Rust build were not run
locally due to sandbox disk capacity. Current-head CI must validate
them; earlier-head results do not verify this stack.
- Analyzer graph-dump and snapshot-selection unit suites were removed
earlier in the stack. Their malformed-data, stream, collision,
packaging, and mocked-history/path coverage has no replacement.

<!-- NEXT_JS_LLM -->

<!-- fleet d7bdbc2b-b0bc-4591-99eb-dccb0fa49c73 -->

<!-- fleet ea768377-d71c-4a15-90b2-f4d50d4f6a1c -->

---------
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent d6d83cfd
This diff is collapsed.
//! Build-time output groups with joined async and worker triggers.
use anyhow::Result;
use rustc_hash::{FxHashMap, FxHashSet};
use turbo_tasks::{FxIndexSet, ResolvedVc, ValueToString, ValueToStringRef, Vc};
use turbopack_core::{module::Module, output::OutputAsset};
use turbopack_ecmascript::references::service_worker::service_worker_chunk_filename;
use crate::{
analyze::{AnalyzeChunkGroupData, AnalyzeDataBuilder, AnalyzeModuleIndex, ChunkLoadCandidate},
route::AnalyzeChunkGroups,
};
pub(super) async fn collect_groups(
builder: &mut AnalyzeDataBuilder,
candidates: Vec<ChunkLoadCandidate>,
asset_indices: &FxHashMap<ResolvedVc<Box<dyn OutputAsset>>, Vec<u32>>,
chunk_groups: Vc<AnalyzeChunkGroups>,
module_index: &AnalyzeModuleIndex,
browser_chunks: &FxHashSet<u32>,
) -> Result<()> {
record_async_groups(builder, candidates, asset_indices);
record_groups(builder, asset_indices, chunk_groups, module_index).await?;
record_worker_groups(builder, module_index, browser_chunks).await?;
for (id, group) in builder.chunk_groups.iter_mut().enumerate() {
group.id = id as u32;
}
Ok(())
}
fn record_async_groups(
builder: &mut AnalyzeDataBuilder,
candidates: Vec<ChunkLoadCandidate>,
asset_indices: &FxHashMap<ResolvedVc<Box<dyn OutputAsset>>, Vec<u32>>,
) {
let mut async_groups = FxHashMap::default();
for candidate in candidates {
let Some(target_indices) = asset_indices.get(&candidate.target) else {
continue;
};
for &target in target_indices {
if target == candidate.source {
continue;
}
let key = (candidate.source, candidate.trigger_module_index);
let group_index = *async_groups.entry(key).or_insert_with(|| {
let index = builder.chunk_groups.len();
builder.chunk_groups.push(AnalyzeChunkGroupData {
id: index as u32,
kind: "async".into(),
trigger_module_index: Some(candidate.trigger_module_index),
output_file_indices: vec![],
});
index
});
let outputs = &mut builder.chunk_groups[group_index].output_file_indices;
if !outputs.contains(&target) {
outputs.push(target);
}
}
}
}
async fn record_groups(
builder: &mut AnalyzeDataBuilder,
asset_indices: &FxHashMap<ResolvedVc<Box<dyn OutputAsset>>, Vec<u32>>,
chunk_groups: Vc<AnalyzeChunkGroups>,
module_index: &AnalyzeModuleIndex,
) -> Result<()> {
for group in chunk_groups.await?.iter() {
let id = builder.chunk_groups.len() as u32;
let mut output_indices = FxIndexSet::default();
for &asset in group.assets.await?.iter() {
let Some(indices) = asset_indices.get(&asset) else {
let path = asset.path().await?.to_string_ref().await?;
anyhow::bail!("chunk-group asset {path} not present among emitted output files");
};
output_indices.extend(indices.iter().copied());
}
let trigger_module_index = if let Some(module) = group.trigger {
let ident = module.ident().to_string().owned().await?;
Some(*module_index.by_ident.get(&ident).ok_or_else(|| {
anyhow::anyhow!(
"{} group trigger {ident} is missing from the analyzer module index",
group.kind
)
})?)
} else {
None
};
builder.chunk_groups.push(AnalyzeChunkGroupData {
id,
kind: group.kind.clone(),
trigger_module_index,
output_file_indices: output_indices.into_iter().collect(),
});
}
Ok(())
}
/// The marker is in the page graph, but its worker payload is in a separate
/// compilation graph. Trace only synchronous dependents to a browser item.
async fn record_worker_groups(
builder: &mut AnalyzeDataBuilder,
module_index: &AnalyzeModuleIndex,
browser_chunks: &FxHashSet<u32>,
) -> Result<()> {
let worker_files: FxHashSet<u32> = builder
.chunk_groups
.iter()
.filter(|group| group.kind == "worker")
.flat_map(|group| group.output_file_indices.iter().copied())
.collect();
builder.chunk_groups.retain(|group| group.kind != "worker");
let mut worker_groups = FxHashMap::default();
if !worker_files.is_empty() {
for &(importer, marker) in &module_index.worker_entries {
let marker = marker.await?;
let filename = service_worker_chunk_filename(&marker.scope);
for target in &worker_files {
let output = &builder.output_files[*target as usize].output_file.filename;
if !output.ends_with(filename.as_str()) {
continue;
}
// A registration may live in generated `<locals>`; find the
// enclosing emitted item without crossing async/traced edges.
let mut triggers = FxIndexSet::default();
let mut pending = vec![importer];
let mut seen = FxHashSet::default();
while let Some(module) = pending.pop() {
if !seen.insert(module) {
continue;
}
let ident = module.ident().to_string().owned().await?;
let mut found = false;
if let Some(&index) = module_index.by_ident.get(&ident) {
found = builder.output_files.iter().enumerate().any(|(i, file)| {
browser_chunks.contains(&(i as u32))
&& file.module_indices.contains(&index)
});
if found {
triggers.insert(index);
}
}
if !found && let Some(parents) = module_index.sync_dependents.get(&module) {
pending.extend(parents.iter().copied());
}
}
for trigger in triggers {
let group_index = *worker_groups.entry(trigger).or_insert_with(|| {
let index = builder.chunk_groups.len();
builder.chunk_groups.push(AnalyzeChunkGroupData {
id: index as u32,
kind: "worker".into(),
trigger_module_index: Some(trigger),
output_file_indices: vec![],
});
index
});
let outputs = &mut builder.chunk_groups[group_index].output_file_indices;
if !outputs.contains(target) {
outputs.push(*target);
}
}
}
}
}
Ok(())
}
//! Enumerate emitted chunk modules against this snapshot's ordered module index. //! Enumerate emitted chunk modules and typed loader candidates against this
//! snapshot's ordered module index. Unknown wrappers remain unsupported.
use anyhow::{Context, Result, anyhow}; use anyhow::{Context, Result, anyhow};
use rustc_hash::FxHashMap; use rustc_hash::FxHashMap;
...@@ -11,17 +12,18 @@ use turbopack_browser::ecmascript::{ ...@@ -11,17 +12,18 @@ use turbopack_browser::ecmascript::{
use turbopack_core::{ use turbopack_core::{
chunk::{Chunk, ChunkItem}, chunk::{Chunk, ChunkItem},
module::Module, module::Module,
output::OutputAsset, output::{OutputAsset, OutputAssetsReference},
}; };
use turbopack_css::chunk::CssChunk; use turbopack_css::chunk::CssChunk;
use turbopack_ecmascript::{ use turbopack_ecmascript::{
async_chunk::module::AsyncLoaderModule, async_chunk::module::AsyncLoaderModule,
chunk::{EcmascriptChunk, EcmascriptChunkItemOrBatchWithAsyncInfo}, chunk::{EcmascriptChunk, EcmascriptChunkItemOrBatchWithAsyncInfo},
manifest::{chunk_asset::ManifestAsyncModule, loader_module::ManifestLoaderModule},
single_file_ecmascript_output::SingleFileEcmascriptOutput, single_file_ecmascript_output::SingleFileEcmascriptOutput,
}; };
use turbopack_nodejs::{EcmascriptBuildNodeChunk, EcmascriptBuildNodeRuntimeChunk}; use turbopack_nodejs::{EcmascriptBuildNodeChunk, EcmascriptBuildNodeRuntimeChunk};
use crate::analyze::{AnalyzeModuleIndex, AnalyzeOutputFileCoverage}; use crate::analyze::{AnalyzeModuleIndex, AnalyzeOutputFileCoverage, ChunkLoadCandidate};
async fn insert_chunk_item( async fn insert_chunk_item(
module: Vc<Box<dyn Module>>, module: Vc<Box<dyn Module>>,
...@@ -71,23 +73,65 @@ fn insert_chunk_item_ident( ...@@ -71,23 +73,65 @@ fn insert_chunk_item_ident(
Ok(()) Ok(())
} }
/// Get exact constituent module identities only for chunk types whose items we /// Only a loader or manifest item supplies a typed async relationship;
/// can enumerate. Empty rows marked unsupported must not be treated as empty chunks. /// generic output references do not establish an async load.
async fn chunk_item_load_candidates(
item: ResolvedVc<Box<dyn turbopack_ecmascript::chunk::EcmascriptChunkItem>>,
index: &AnalyzeModuleIndex,
source: u32,
) -> Result<Vec<ChunkLoadCandidate>> {
let module = item.module().to_resolved().await?;
let trigger = if let Some(loader) = ResolvedVc::try_downcast_type::<AsyncLoaderModule>(module) {
loader.await?.inner
} else if let Some(manifest) = ResolvedVc::try_downcast_type::<ManifestAsyncModule>(module) {
manifest.await?.inner
} else if let Some(loader) = ResolvedVc::try_downcast_type::<ManifestLoaderModule>(module) {
loader.await?.manifest.await?.inner
} else {
return Ok(vec![]);
};
// Use the same typed target as the module graph's async dependency, including
// next/dynamic entry wrappers. Synthetic loader identities do not join it.
let ident = trigger.ident().to_string().owned().await?;
let trigger_module_index = *index.by_ident.get(&ident).ok_or_else(|| {
anyhow!("Async group trigger {ident} is missing from the analyzer module index")
})?;
let references = item.references().await?;
let assets = references.assets.await?;
Ok(assets
.iter()
.copied()
.map(|target| ChunkLoadCandidate {
source,
target,
trigger_module_index,
})
.collect())
}
/// Enumerate known browser/Node.js JS and CSS chunk items; unknown wrappers remain unsupported.
pub(super) async fn output_chunk_modules( pub(super) async fn output_chunk_modules(
asset: ResolvedVc<Box<dyn OutputAsset>>, asset: ResolvedVc<Box<dyn OutputAsset>>,
filename: &str, filename: &str,
module_index: &AnalyzeModuleIndex, module_index: &AnalyzeModuleIndex,
) -> Result<(Vec<u32>, AnalyzeOutputFileCoverage, Vec<u32>)> { output_file_index: u32,
) -> Result<(
Vec<u32>,
AnalyzeOutputFileCoverage,
Vec<ChunkLoadCandidate>,
Vec<u32>,
)> {
if ResolvedVc::try_downcast_type::<EcmascriptBrowserRuntimeChunk>(asset).is_some() if ResolvedVc::try_downcast_type::<EcmascriptBrowserRuntimeChunk>(asset).is_some()
|| ResolvedVc::try_downcast_type::<EcmascriptBuildNodeRuntimeChunk>(asset).is_some() || ResolvedVc::try_downcast_type::<EcmascriptBuildNodeRuntimeChunk>(asset).is_some()
|| ResolvedVc::try_downcast_type::<SingleFileEcmascriptOutput>(asset).is_some() || ResolvedVc::try_downcast_type::<SingleFileEcmascriptOutput>(asset).is_some()
|| ResolvedVc::try_downcast_type::<EcmascriptBrowserSingleEntryChunk>(asset).is_some() || ResolvedVc::try_downcast_type::<EcmascriptBrowserSingleEntryChunk>(asset).is_some()
|| ResolvedVc::try_downcast_type::<EcmascriptBrowserWorkerEntrypoint>(asset).is_some() || ResolvedVc::try_downcast_type::<EcmascriptBrowserWorkerEntrypoint>(asset).is_some()
{ {
return Ok((vec![], AnalyzeOutputFileCoverage::NotAChunk, vec![])); return Ok((vec![], AnalyzeOutputFileCoverage::NotAChunk, vec![], vec![]));
} }
let mut indices = FxIndexSet::default(); let mut indices = FxIndexSet::default();
let mut async_loaders = FxIndexSet::default(); let mut async_loaders = FxIndexSet::default();
let mut candidates = Vec::new();
let mut enumerated = true; let mut enumerated = true;
let ecmascript_content = if let Some(browser_chunk) = let ecmascript_content = if let Some(browser_chunk) =
ResolvedVc::try_downcast_type::<EcmascriptBrowserChunk>(asset) ResolvedVc::try_downcast_type::<EcmascriptBrowserChunk>(asset)
...@@ -113,6 +157,14 @@ pub(super) async fn output_chunk_modules( ...@@ -113,6 +157,14 @@ pub(super) async fn output_chunk_modules(
) )
.await .await
.with_context(|| format!("Analyzing output {filename}"))?; .with_context(|| format!("Analyzing output {filename}"))?;
candidates.extend(
chunk_item_load_candidates(
item.chunk_item,
module_index,
output_file_index,
)
.await?,
);
} }
EcmascriptChunkItemOrBatchWithAsyncInfo::Batch(batch) => { EcmascriptChunkItemOrBatchWithAsyncInfo::Batch(batch) => {
for item in &batch.await?.chunk_items { for item in &batch.await?.chunk_items {
...@@ -124,6 +176,14 @@ pub(super) async fn output_chunk_modules( ...@@ -124,6 +176,14 @@ pub(super) async fn output_chunk_modules(
) )
.await .await
.with_context(|| format!("Analyzing output {filename}"))?; .with_context(|| format!("Analyzing output {filename}"))?;
candidates.extend(
chunk_item_load_candidates(
item.chunk_item,
module_index,
output_file_index,
)
.await?,
);
} }
} }
} }
...@@ -144,7 +204,7 @@ pub(super) async fn output_chunk_modules( ...@@ -144,7 +204,7 @@ pub(super) async fn output_chunk_modules(
// Other emitted JS/CSS wrappers cannot enumerate their module members. // Other emitted JS/CSS wrappers cannot enumerate their module members.
enumerated = false; enumerated = false;
} else { } else {
return Ok((vec![], AnalyzeOutputFileCoverage::NotAChunk, vec![])); return Ok((vec![], AnalyzeOutputFileCoverage::NotAChunk, vec![], vec![]));
} }
let coverage = if enumerated { let coverage = if enumerated {
AnalyzeOutputFileCoverage::Exact AnalyzeOutputFileCoverage::Exact
...@@ -154,6 +214,7 @@ pub(super) async fn output_chunk_modules( ...@@ -154,6 +214,7 @@ pub(super) async fn output_chunk_modules(
Ok(( Ok((
indices.into_iter().collect(), indices.into_iter().collect(),
coverage, coverage,
candidates,
async_loaders.into_iter().collect(), async_loaders.into_iter().collect(),
)) ))
} }
......
...@@ -2418,6 +2418,17 @@ impl Endpoint for AppEndpoint { ...@@ -2418,6 +2418,17 @@ impl Endpoint for AppEndpoint {
pages_html: false, pages_html: false,
}); });
} }
let workers = service_worker_output_assets(project, *graphs.base)
.to_resolved()
.await?;
if !workers.await?.is_empty() {
groups.push(AnalyzeChunkGroup {
kind: rcstr!("worker"),
trigger: None,
assets: workers,
pages_html: false,
});
}
Ok(Vc::cell(groups)) Ok(Vc::cell(groups))
} }
......
...@@ -1793,12 +1793,25 @@ impl Endpoint for PageEndpoint { ...@@ -1793,12 +1793,25 @@ impl Endpoint for PageEndpoint {
.await? .await?
.first() .first()
.map(|module| ResolvedVc::upcast(*module)); .map(|module| ResolvedVc::upcast(*module));
Ok(Vc::cell(vec![AnalyzeChunkGroup { let workers =
service_worker_output_assets(this.pages_project.project(), self.client_module_graph())
.to_resolved()
.await?;
let mut groups = vec![AnalyzeChunkGroup {
kind: rcstr!("bootstrap"), kind: rcstr!("bootstrap"),
trigger: bootstrap, trigger: bootstrap,
assets: client.assets, assets: client.assets,
pages_html: true, pages_html: true,
}])) }];
if !workers.await?.is_empty() {
groups.push(AnalyzeChunkGroup {
kind: rcstr!("worker"),
trigger: None,
assets: workers,
pages_html: false,
});
}
Ok(Vc::cell(groups))
} }
#[turbo_tasks::function] #[turbo_tasks::function]
......
...@@ -274,11 +274,11 @@ ...@@ -274,11 +274,11 @@
}, },
"trigger_module_ident": { "trigger_module_ident": {
"type": ["string", "null"], "type": ["string", "null"],
"description": "Exact trigger identity when joined or explicitly unjoined." "description": "Exact trigger identity, or null when absent. For async groups, this is the joined dynamically imported target module's ident. Outputs in the same route whose async_loaders contain this trigger can load the group outputs. For worker groups, this is the joined registering module or its emitted synchronous ancestor. Outputs whose modules contain this trigger can load the worker group outputs. Other kinds retain their bootstrap or render-dependent trigger semantics."
}, },
"trigger_join": { "trigger_join": {
"enum": ["joined", "unjoined", "none"], "enum": ["joined", "none"],
"description": "Whether the trigger identity joined the indexed snapshot modules, is unjoined, or absent." "description": "Whether the group has an indexed trigger or no trigger."
}, },
"outputs": { "outputs": {
"type": "array", "type": "array",
......
...@@ -45,7 +45,6 @@ type RouteHeader = { ...@@ -45,7 +45,6 @@ type RouteHeader = {
id: number id: number
kind: string kind: string
trigger_module_index?: number trigger_module_index?: number
unjoined_trigger_ident?: string
output_file_indices: number[] output_file_indices: number[]
}> }>
} }
...@@ -290,12 +289,6 @@ function groupRecords( ...@@ -290,12 +289,6 @@ function groupRecords(
seen.add(group.id) seen.add(group.id)
let trigger_module_ident: string | null = null let trigger_module_ident: string | null = null
let trigger_join = 'none' let trigger_join = 'none'
if (
group.trigger_module_index !== undefined &&
group.unjoined_trigger_ident !== undefined
) {
throw new Error('Conflicting analyzer group triggers')
}
if (group.trigger_module_index !== undefined) { if (group.trigger_module_index !== undefined) {
requireIndex( requireIndex(
group.trigger_module_index, group.trigger_module_index,
...@@ -304,11 +297,6 @@ function groupRecords( ...@@ -304,11 +297,6 @@ function groupRecords(
) )
trigger_module_ident = modules.modules[group.trigger_module_index].ident trigger_module_ident = modules.modules[group.trigger_module_index].ident
trigger_join = 'joined' trigger_join = 'joined'
} else if (group.unjoined_trigger_ident !== undefined) {
if (typeof group.unjoined_trigger_ident !== 'string')
throw new Error('Invalid unjoined analyzer trigger')
trigger_module_ident = group.unjoined_trigger_ident
trigger_join = 'unjoined'
} }
return { return {
id: group.id, id: group.id,
......
...@@ -10,9 +10,9 @@ description: > ...@@ -10,9 +10,9 @@ description: >
## 1. Set the scope ## 1. Set the scope
Choose a route and **audit** or **fix** mode. Audit is the default: generate analyzer artifacts and report candidates while leaving application source, dependencies and lockfiles unchanged. Fix mode requires an explicit request to change the app. Ask before changing visible behavior, timing, compatibility or a trust boundary. For a route's static App Shell, use `next-cache-components-optimizer`; for navigation prefetch work, use `next-partial-prefetching-optimizer`. Analyze the whole app by default, covering all routes and shared client dependencies. Narrow the scope only when the user specifies a route, dependency, feature or other subset. Choose **audit** or **fix** mode. Audit is the default: generate analyzer artifacts and report candidates while leaving application source, dependencies and lockfiles unchanged. Fix mode requires an explicit request to change the app. Ask before changing visible behavior, timing, compatibility or a trust boundary. For a route's static App Shell, use `next-cache-components-optimizer`; for navigation prefetch work, use `next-partial-prefetching-optimizer`.
**Done:** the route, mode and intended behavior are recorded. A request to capture or export data is audit mode, not permission to fix. **Done:** the whole-app or user-specified scope, mode and intended behavior are recorded. A request to capture or export data is audit mode, not permission to fix.
## 2. Capture and export a baseline ## 2. Capture and export a baseline
...@@ -26,14 +26,14 @@ Run the pipeline in Bash: ...@@ -26,14 +26,14 @@ Run the pipeline in Bash:
set -o pipefail set -o pipefail
# Capture only when a new baseline is needed # Capture only when a new baseline is needed
pnpm exec next analyze --output --snapshot 'audit-before-unique-1' pnpm exec next analyze --output --snapshot 'audit-before-unique-1'
pnpm exec next analyze export --snapshot 'audit-before-unique-1' --route '/dashboard' | gzip > /tmp/analyze-dashboard-before.jsonl.gz pnpm exec next analyze export --snapshot 'audit-before-unique-1' | gzip > /tmp/analyze-app-before.jsonl.gz
``` ```
`--output` builds and saves binary/UI artifacts without serving. `next analyze export` reads a saved snapshot without building; stdout is one typed JSON record per line, with errors on stderr. The route filter keeps the whole-app module graph, so scope it in the next step. `--output` builds and saves binary/UI artifacts without serving. `next analyze export` reads a saved snapshot without building; stdout is one typed JSON record per line, with errors on stderr. Omit `--route` for whole-app analysis; add it for a user-specified route. The route filter keeps the whole-app module graph, so scope it in the next step.
For a custom `distDir`, replay with `--dist-dir <configured-directory>` (relative or absolute): capture loads the app config, replay does not. `--snapshot <name>` selects a retained name; omission selects the newest snapshot. Capture generates a unique timestamp name when omitted, and **replaces** an existing capture when an explicit name is reused. Use distinct before/after names, including names with spaces, to preserve both baselines. For interactive exploration, capture without `--output` to serve the UI; `next build --analyze` also produces replayable data. For a custom `distDir`, replay with `--dist-dir <configured-directory>` (relative or absolute): capture loads the app config, replay does not. `--snapshot <name>` selects a retained name; omission selects the newest snapshot. Capture generates a unique timestamp name when omitted, and **replaces** an existing capture when an explicit name is reused. Use distinct before/after names, including names with spaces, to preserve both baselines. For interactive exploration, capture without `--output` to serve the UI; `next build --analyze` also produces replayable data.
**Done:** the chosen capture is identified, export succeeded, and the baseline file, snapshot name and selected route are recorded. Check the whole pipeline's exit status before processing the compressed file: `pipefail` prevents gzip from hiding a failed export. Export validates one route at a time, so a failure can leave a partial archive even if `gzip -t` accepts it. Discard output when export or gzip fails. **Done:** the chosen capture is identified, export succeeded, and the baseline file, snapshot name and analysis scope are recorded. Check the whole pipeline's exit status before processing the compressed file: `pipefail` prevents gzip from hiding a failed export. Export validates one route at a time, so a failure can leave a partial archive even if `gzip -t` accepts it. Discard output when export or gzip fails.
## 3. Interpret the evidence ## 3. Interpret the evidence
...@@ -43,13 +43,13 @@ Resolve the schema from the app's **installed Next.js**, using its Node launcher ...@@ -43,13 +43,13 @@ Resolve the schema from the app's **installed Next.js**, using its Node launcher
pnpm exec node -p "require.resolve('next/analyze/graph-v1.schema.json')" pnpm exec node -p "require.resolve('next/analyze/graph-v1.schema.json')"
``` ```
Read its descriptions for record meanings, joins, attribution and coverage. Stream decompression with `gzip -dc /tmp/analyze-dashboard-before.jsonl.gz` into a line-oriented analysis script rather than loading the whole dump into context. Use the schema to interpret the selected route's client/server contributions and choose the metric. Read its descriptions for record meanings, joins, attribution and coverage. Stream decompression with `gzip -dc /tmp/analyze-app-before.jsonl.gz` into a line-oriented analysis script rather than loading the whole dump into context. Use the schema to interpret client/server contributions across every route in scope and choose the metric.
**Done:** the baseline's route-attributed client/server contributions and the metric are identified. Treat this as **build evidence**: claims about observed browser requests, timing or transfer savings need separate evidence. **Done:** the baseline's route-attributed client/server contributions and the metric are identified. Treat this as **build evidence**: claims about observed browser requests, timing or transfer savings need separate evidence.
## 4. Explain a candidate ## 4. Explain a candidate
Inspect actual project source and exact importers. Start with the named route or rank scoped client-output contributions by attributed size, repetition, likely runtime cost, need before interaction and correctness risk. Inspect actual project source and exact importers. Rank client-output contributions across the whole app, or within the user-specified scope, by attributed size, repetition, likely runtime cost, need before interaction and correctness risk.
### Community → min-cut pass ### Community → min-cut pass
...@@ -66,8 +66,8 @@ For a narrow audit of a named dependency or feature, use direct importer reasoni ...@@ -66,8 +66,8 @@ For a narrow audit of a named dependency or feature, use direct importer reasoni
Before proposing an edit, record these items for each candidate. Mark an inapplicable item with its reason; give missing evidence an explicit gap. Before proposing an edit, record these items for each candidate. Mark an inapplicable item with its reason; give missing evidence an explicit gap.
- **Scope:** name the route, snapshot, render conditions, client/server output class, exact target identities and metric. For reachability claims, identify every selected client root, including applicable client references. - **Scope:** name the affected routes, snapshot, render conditions, client/server output class, exact target identities and metric. For reachability claims, identify every selected client root, including applicable client references.
- **Coverage:** summarize relevant unsupported outputs and unresolved references, with available reasons and their effect on the claim. Scope conclusions to the known subgraph when completeness is uncertain. - **Coverage:** summarize relevant unsupported outputs and absent group triggers, and their effect on the claim. Scope conclusions to the known subgraph when completeness is uncertain.
- **Attribution:** count each selected output contribution once. Record repeated-record handling and distinguish source paths from module identities; explain any mapping used for solver weights and preserve unknown weights as gaps. - **Attribution:** count each selected output contribution once. Record repeated-record handling and distinguish source paths from module identities; explain any mapping used for solver weights and preserve unknown weights as gaps.
- **Reachability:** for a lazy boundary, check **all** synchronous root-to-target paths, alternate importers and cycles, including a target that is itself a root. Record which paths the proposed boundary severs and which stay reachable. Verify async and erased type-only imports against source. - **Reachability:** for a lazy boundary, check **all** synchronous root-to-target paths, alternate importers and cycles, including a target that is itself a root. Record which paths the proposed boundary severs and which stay reachable. Verify async and erased type-only imports against source.
- **Source checks:** inspect import triggers, mount-time preloading, module side effects and shared routes. Record the conditions under which an async import executes. The graph establishes indexed reachability; an after snapshot verifies emitted outputs and attribution changes. - **Source checks:** inspect import triggers, mount-time preloading, module side effects and shared routes. Record the conditions under which an async import executes. The graph establishes indexed reachability; an after snapshot verifies emitted outputs and attribution changes.
...@@ -79,7 +79,7 @@ For lazy interaction features, duplicate packages, server-rendered display work ...@@ -79,7 +79,7 @@ For lazy interaction features, duplicate packages, server-rendered display work
## 5. Verify one change — fix mode only ## 5. Verify one change — fix mode only
Make one small, cohesive change. Capture/export an after snapshot with a new name and compare the **same route, output class and metric** with the baseline. Run relevant behavior tests and type-check; use `next-dev-loop` when verifying the edit in the running app. Make one small, cohesive change. Capture/export an after snapshot with a new name and compare the **same analysis scope, output class and metric** with the baseline. For whole-app analysis, account for changes across all routes, including shared dependencies. Run relevant behavior tests and type-check; use `next-dev-loop` when verifying the edit in the running app.
**Done:** retain the change only when the scoped metric improves and the intended behavior passes its checks. Revert a change that fails either condition. If checks are blocked, report the unverified edit and blocker rather than accepting it. Record the accepted after snapshot as the next baseline before another edit. **Done:** retain the change only when the scoped metric improves and the intended behavior passes its checks. Revert a change that fails either condition. If checks are blocked, report the unverified edit and blocker rather than accepting it. Record the accepted after snapshot as the next baseline before another edit.
......
...@@ -4,7 +4,7 @@ Read the section matching the candidate before proposing a change. Each section ...@@ -4,7 +4,7 @@ Read the section matching the candidate before proposing a change. Each section
## Lazy interaction feature ## Lazy interaction feature
For an editor, chart or dialog needed after interaction, inspect its actual importer and confirm the feature is not already async. Add one lazy boundary with a stable placeholder, preserving loading/error states, keyboard/focus, direct visits and client/server behavior. For a large component such as an editor, chart or dialog needed after interaction, inspect its actual importer and confirm the feature is not already async. Add one lazy boundary with a stable placeholder, preserving loading/error states, keyboard/focus, direct visits and client/server behavior.
Preload on intent only after measuring its benefit. Idle preloading can waste data/battery and compete with important requests. Preload on intent only after measuring its benefit. Idle preloading can waste data/battery and compete with important requests.
......
...@@ -13,7 +13,7 @@ Use Louvain/Leiden or another community algorithm on the scoped, deduplicated or ...@@ -13,7 +13,7 @@ Use Louvain/Leiden or another community algorithm on the scoped, deduplicated or
## Conditional min cut — detach a target ## Conditional min cut — detach a target
1. **Define the scenario:** record the route/render conditions, verified client roots and heavy target. Use directed synchronous importer→imported edges and exact output→module memberships. 1. **Define the scenario:** record the route/render conditions, verified client roots and heavy target. Use directed synchronous importer→imported edges and exact output→module memberships.
2. **Establish completeness:** check every relevant output's coverage and unjoined/unresolved evidence. Account for positive or unknown unresolved-reference counts, unknown client roles, uncertain triggers and overlapping/cumulative group memberships. A group that cannot isolate one reference or an unsupported membership may supply another path. Output membership and group role establish build provenance, not cold-request scope. 2. **Establish completeness:** check every relevant output's coverage and group triggers against route output membership. Account for unknown client roles, uncertain triggers and overlapping/cumulative group memberships. A group that cannot isolate one reference or an unsupported membership may supply another path. Output membership and group role establish build provenance, not cold-request scope.
3. **Choose the claim:** make a definitive cut only if every possibly relevant root→target path is accounted for. Otherwise report a cut of the **known subgraph** as provisional, identify the missing evidence and give a verification plan. 3. **Choose the claim:** make a definitive cut only if every possibly relevant root→target path is accounted for. Otherwise report a cut of the **known subgraph** as provisional, identify the missing evidence and give a verification plan.
4. **Solve and check:** connect selected roots to a super-source and targets to a sink. Choose unit-edge or size/edit-cost capacities deliberately. Protect shared runtime and required initial UI edges with uncuttable capacities or equivalent constraints; record the protected edges and reasons. If no feasible cut remains, report that result. Condense strongly connected components if needed. Check that every synchronous path in the claimed scenario is severed, including alternate roots and cycles. 4. **Solve and check:** connect selected roots to a super-source and targets to a sink. Choose unit-edge or size/edit-cost capacities deliberately. Protect shared runtime and required initial UI edges with uncuttable capacities or equivalent constraints; record the protected edges and reasons. If no feasible cut remains, report that result. Condense strongly connected components if needed. Check that every synchronous path in the claimed scenario is severed, including alternate roots and cycles.
......
export function GET() { export async function GET() {
return Response.json({ ok: true }) const { platform } = await import('node:os')
return Response.json({ ok: true, platform: platform() })
} }
...@@ -7,6 +7,7 @@ const DynamicTarget = dynamic(() => import('./dynamic-target')) ...@@ -7,6 +7,7 @@ const DynamicTarget = dynamic(() => import('./dynamic-target'))
export default function ClientEntry() { export default function ClientEntry() {
const [count, setCount] = useState(0) const [count, setCount] = useState(0)
const [message, setMessage] = useState('not loaded')
useEffect(() => { useEffect(() => {
if ('serviceWorker' in navigator) { if ('serviceWorker' in navigator) {
navigator.serviceWorker.register(new URL('./pwa', import.meta.url)) navigator.serviceWorker.register(new URL('./pwa', import.meta.url))
...@@ -24,6 +25,14 @@ export default function ClientEntry() { ...@@ -24,6 +25,14 @@ export default function ClientEntry() {
Load async target Load async target
</button> </button>
<DynamicTarget /> <DynamicTarget />
<button
onClick={() =>
import('./lazy').then((module) => setMessage(module.message))
}
>
Load on demand
</button>
<span>{message}</span>
</> </>
) )
} }
export const message = 'loaded on demand'
...@@ -33,7 +33,7 @@ type ChunkGraphHeader = { ...@@ -33,7 +33,7 @@ type ChunkGraphHeader = {
output_file_module_coverage: Array<'exact' | 'unsupported' | 'not_a_chunk'> output_file_module_coverage: Array<'exact' | 'unsupported' | 'not_a_chunk'>
chunk_groups: Array<{ chunk_groups: Array<{
id: number id: number
kind: 'bootstrap' | 'render_dependent' kind: 'bootstrap' | 'render_dependent' | 'async' | 'worker'
trigger_module_index?: number trigger_module_index?: number
output_file_indices: number[] output_file_indices: number[]
}> }>
...@@ -328,6 +328,74 @@ describe('next analyze', () => { ...@@ -328,6 +328,74 @@ describe('next analyze', () => {
.some((ident: string) => ident.endsWith('async loader)')) .some((ident: string) => ident.endsWith('async loader)'))
).toBe(false) ).toBe(false)
const modulesByIdent = new Map(
records
.filter((record) => record.type === 'module')
.map((record) => [record.ident, record])
)
const allAsyncDependencies = new Set(
[...modulesByIdent.values()].flatMap(
(module) => module.dependencies.async
)
)
const asyncGroups = records.filter(
(record) => record.type === 'group' && record.kind === 'async'
)
for (const group of records.filter(
(record) =>
record.type === 'group' &&
(record.kind === 'async' || record.kind === 'worker')
)) {
expect(group.trigger_join).toBe('joined')
expect(
records.some(
(output) =>
output.type === 'output' &&
output.route === group.route &&
output[
group.kind === 'async' ? 'async_loaders' : 'modules'
].includes(group.trigger_module_ident)
)
).toBe(true)
}
expect(asyncGroups.length).toBeGreaterThan(0)
for (const record of asyncGroups) {
expect(record.trigger_join).toBe('joined')
const target = modulesByIdent.get(record.trigger_module_ident)
expect(target).toBeDefined()
expect(record.trigger_module_ident).toBe(target.ident)
expect(allAsyncDependencies.has(target.ident)).toBe(true)
}
const expectedTargets = [
...asyncTargets.filter(
(target) =>
target.ident.includes('next/dynamic entry') ||
target.path.endsWith('/app/async-target.ts')
),
...[...modulesByIdent.values()].filter(
(module) =>
module.path.endsWith('/app/lazy.ts') &&
module.ident.includes('[app-client]')
),
...[...modulesByIdent.values()].filter(
(module) =>
module.ident.includes('node:os') &&
module.ident.includes('[external]')
),
]
expect(
expectedTargets.some((target) => target.path.endsWith('/app/lazy.ts'))
).toBe(true)
expect(
expectedTargets.some((target) => target.ident.includes('node:os'))
).toBe(true)
for (const target of expectedTargets) {
expect(allAsyncDependencies.has(target.ident)).toBe(true)
expect(
asyncGroups.some((group) => group.trigger_module_ident === target.ident)
).toBe(true)
}
const filtered = await next.runCommand([ const filtered = await next.runCommand([
'analyze', 'analyze',
'export', 'export',
...@@ -672,6 +740,14 @@ describe('next analyze', () => { ...@@ -672,6 +740,14 @@ describe('next analyze', () => {
expect(row).toEqual([]) expect(row).toEqual([])
} }
} }
for (const group of header.chunk_groups) {
if (group.kind === 'worker') {
expect(group.trigger_module_index).toBeDefined()
expect(
rows.some((row) => row.includes(group.trigger_module_index!))
).toBe(true)
}
}
} }
expect( expect(
routeGraphs.some(({ header, binary }) => { routeGraphs.some(({ header, binary }) => {
...@@ -731,12 +807,18 @@ describe('next analyze', () => { ...@@ -731,12 +807,18 @@ describe('next analyze', () => {
(group) => group.kind === 'render_dependent' (group) => group.kind === 'render_dependent'
) )
).toBe(true) ).toBe(true)
expect(
appGraph.chunk_groups.some((group) => group.kind === 'worker')
).toBe(true)
expect( expect(
pagesGraph.chunk_groups.some((group) => group.kind === 'bootstrap') pagesGraph.chunk_groups.some((group) => group.kind === 'bootstrap')
).toBe(true) ).toBe(true)
expect( expect(
apiGraph.chunk_groups.some((group) => group.kind === 'bootstrap') apiGraph.chunk_groups.some((group) => group.kind === 'bootstrap')
).toBe(false) ).toBe(false)
expect(
appGraph.chunk_groups.some((group) => group.kind === 'async')
).toBe(true)
const appRows = readRows( const appRows = readRows(
routeGraphs[0].binary, routeGraphs[0].binary,
appGraph.output_file_modules appGraph.output_file_modules
...@@ -746,6 +828,11 @@ describe('next analyze', () => { ...@@ -746,6 +828,11 @@ describe('next analyze', () => {
row.some((index) => modules[index].ident.includes('client-entry')) row.some((index) => modules[index].ident.includes('client-entry'))
) )
).toBe(true) ).toBe(true)
expect(
appRows.some((row) =>
row.some((index) => modules[index].ident.includes('/lazy'))
)
).toBe(true)
expect(appGraph.output_file_module_coverage).toContain('exact') expect(appGraph.output_file_module_coverage).toContain('exact')
const groupedFileIndices = appGraph.chunk_groups.flatMap( const groupedFileIndices = appGraph.chunk_groups.flatMap(
(group) => group.output_file_indices (group) => group.output_file_indices
...@@ -753,6 +840,14 @@ describe('next analyze', () => { ...@@ -753,6 +840,14 @@ describe('next analyze', () => {
expect(new Set(groupedFileIndices).size).toBeLessThan( expect(new Set(groupedFileIndices).size).toBeLessThan(
groupedFileIndices.length groupedFileIndices.length
) )
for (const index of appGraph.chunk_groups
.filter((group) => group.kind === 'worker')
.flatMap((group) => group.output_file_indices)) {
expect(appGraph.output_file_module_coverage[index]).toBe(
'not_a_chunk'
)
expect(appRows[index]).toEqual([])
}
expect( expect(
appRows.some( appRows.some(
(row, index) => (row, index) =>
......
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