[cross imports] Check examples cross imports by navaronbracke · Pull Request #187662 · flutter/flutter

navaronbracke · 2026-06-07T20:08:55Z

This PR adds a check that checks examples under /examples for cross imports.

Since most of the structure is shared with the existing cross imports checker, I opted to share some bits and pieces in a utils file as well.

A new test suite was added, which mirrors most of the setup in the existing test.

Currently the examples checker is too strict by design, as it does not allow any cross imports at all (including Material examples importing Cupertino). There are some edge cases that we should fix (such as context menu examples?) where both imports are allowed. But for now, since we have no checks in place, I opted for strict first,
exempt later, since this gives us a good starting point.

I did notice that examples like examples/api/lib/material/context_menu/editable_text_toolbar_builder.0.dart,
could definitely be cleaned up before we add exemptions. To be looked at later.

I also copied over a small fix into the cross imports checker that I needed in #187587
relating to lastIndexOf(), just to make my job a bit easier when either of those PR's lands first.

Lastly, I found 4 violations of cross imports for some Cupertino examples, which have been fixed as well, as part of this effort.

Fixes #187645

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gemini-code-assist

Code Review

This pull request extracts shared cross-import checking logic into a new utility file, cross_imports_checker_utils.dart, and introduces a new script, check_examples_cross_imports.dart, to check examples for cross imports, along with corresponding tests and test utilities. The review feedback points out multiple instances where Platform.pathSeparator or the global path package are used directly, which can cause test failures on Windows or when using a MemoryFileSystem with a different path style. The reviewer recommends using the file-system-specific path context (e.g., file.fileSystem.path) to ensure robust cross-platform compatibility.

gemini-code-assist · 2026-06-13T16:39:05Z

+  factory _ExamplesLibrary.fromDirectory(Directory directory, {required Directory flutterRoot}) {
+    if (!directory.absolute.path.startsWith(flutterRoot.absolute.path)) {
+      throw ArgumentError('Directory must be inside ${flutterRoot.absolute.path}.', 'directory');
+    }
+
+    final String relativePath = path
+        .relative(directory.absolute.path, from: flutterRoot.absolute.path)
+        .replaceAll(Platform.pathSeparator, '/');


Using path.relative and Platform.pathSeparator directly can cause test failures on Windows CI or when running tests with a different file system style (e.g., using a Windows MemoryFileSystem on a POSIX host). Additionally, path casing on Windows (e.g., C:\ vs c:\) can cause startsWith to fail. It is highly recommended to use directory.fileSystem.path and canonicalize the paths first to ensure robust cross-platform compatibility.

factory _ExamplesLibrary.fromDirectory(Directory directory, {required Directory flutterRoot}) { final String canonicalDirectoryPath = directory.fileSystem.path.canonicalize(directory.absolute.path); final String canonicalFlutterRootPath = directory.fileSystem.path.canonicalize(flutterRoot.absolute.path); if (!canonicalDirectoryPath.startsWith(canonicalFlutterRootPath)) { throw ArgumentError('Directory must be inside ${flutterRoot.absolute.path}.', 'directory'); } final String relativePath = directory.fileSystem.path .relative(directory.absolute.path, from: flutterRoot.absolute.path) .replaceAll(directory.fileSystem.path.separator, '/');

gemini-code-assist · 2026-06-13T16:39:05Z

+Set<String> differencePaths(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {
+  final Set<String> testPaths = files.map((File file) {
+    final int index = file.absolute.path.indexOf(prefix);
+    if (index < 0) {
+      throw ArgumentError('All files must include $prefix in their path.', 'files');
+    }
+
+    return file.absolute.path.substring(index).replaceAll(Platform.pathSeparator, '/');
+  }).toSet();


Using Platform.pathSeparator can cause issues when running tests using a MemoryFileSystem with a different path style than the host platform. Use file.fileSystem.path.separator instead to ensure the path separators are correctly replaced regardless of the host platform.

Suggested change

Set<String> differencePaths(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {

final Set<String> testPaths = files.map((File file) {

final int index = file.absolute.path.indexOf(prefix);

if (index < 0) {

throw ArgumentError('All files must include $prefix in their path.', 'files');

}

return file.absolute.path.substring(index).replaceAll(Platform.pathSeparator, '/');

}).toSet();

Set<String> differencePaths(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {

final Set<String> testPaths = files.map((File file) {

final int index = file.absolute.path.indexOf(prefix);

if (index < 0) {

throw ArgumentError('All files must include $prefix in their path.', 'files');

}

return file.absolute.path.substring(index).replaceAll(file.fileSystem.path.separator, '/');

}).toSet();

gemini-code-assist · 2026-06-13T16:39:06Z

+String getImportError({
+  required Set<File> files,
+  required Directory flutterRoot,
+  required CrossImportCheckedLibrary checkedLibrary,
+  required LibraryCrossImportStatementType importStatement,
+}) {
+  assert(!checkedLibrary.canImport(importStatement), checkedLibrary.cannotImportMessage);
+
+  final String importedLibraryName = importStatement.readableName;
+  final buffer = StringBuffer(
+    checkedLibrary.getDisallowedImportMessage(importedLibraryName, files.length),
+  );
+  for (final file in files) {
+    buffer.writeln(
+      '  ${getRelativePath(file, flutterRoot: flutterRoot).replaceAll(Platform.pathSeparator, '/')}',
+    );
+  }
+  return buffer.toString().trimRight();
+}
+
+/// Returns the [file]'s relative path, relative to [flutterRoot].
+String getRelativePath(File file, {required Directory flutterRoot}) {
+  return path.relative(file.absolute.path, from: flutterRoot.absolute.path);


Using the global path context and Platform.pathSeparator directly can cause test failures on Windows or when running tests with a different file system style. Use file.fileSystem.path and flutterRoot.fileSystem.path to ensure correct path operations.

String getImportError({ required Set<File> files, required Directory flutterRoot, required CrossImportCheckedLibrary checkedLibrary, required LibraryCrossImportStatementType importStatement, }) { assert(!checkedLibrary.canImport(importStatement), checkedLibrary.cannotImportMessage); final String importedLibraryName = importStatement.readableName; final buffer = StringBuffer( checkedLibrary.getDisallowedImportMessage(importedLibraryName, files.length), ); for (final file in files) { buffer.writeln( ' ${getRelativePath(file, flutterRoot: flutterRoot).replaceAll(file.fileSystem.path.separator, '/')}', ); } return buffer.toString().trimRight(); } /// Returns the [file]'s relative path, relative to [flutterRoot]. String getRelativePath(File file, {required Directory flutterRoot}) { return flutterRoot.fileSystem.path.relative(file.absolute.path, from: flutterRoot.absolute.path); }

gemini-code-assist · 2026-06-13T16:39:06Z

+Set<File> getUnknowns(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {
+  return files.where((File file) {
+    final int index = file.absolute.path.indexOf(prefix);
+
+    if (index < 0) {
+      throw ArgumentError('All files must include $prefix in their path.', 'files');
+    }
+
+    final String comparablePath = file.absolute.path
+        .substring(index)
+        .replaceAll(Platform.pathSeparator, '/');
+
+    return !knownPaths.contains(comparablePath);
+  }).toSet();


Using Platform.pathSeparator can cause issues when running tests using a MemoryFileSystem with a different path style than the host platform. Use file.fileSystem.path.separator instead to ensure the path separators are correctly replaced regardless of the host platform.

Suggested change

Set<File> getUnknowns(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {

return files.where((File file) {

final int index = file.absolute.path.indexOf(prefix);

if (index < 0) {

throw ArgumentError('All files must include $prefix in their path.', 'files');

}

final String comparablePath = file.absolute.path

.substring(index)

.replaceAll(Platform.pathSeparator, '/');

return !knownPaths.contains(comparablePath);

}).toSet();

Set<File> getUnknowns(Set<String> knownPaths, Set<File> files, {required Pattern prefix}) {

return files.where((File file) {

final int index = file.absolute.path.indexOf(prefix);

if (index < 0) {

throw ArgumentError('All files must include $prefix in their path.', 'files');

}

final String comparablePath = file.absolute.path

.substring(index)

.replaceAll(file.fileSystem.path.separator, '/');

return !knownPaths.contains(comparablePath);

}).toSet();

gemini-code-assist · 2026-06-13T16:39:06Z

+File getFile(String filepath, Directory directory) {
+  final String platformFilepath = filepath.replaceAll('/', Platform.pathSeparator);
+  final String searchPattern = directory.basename + Platform.pathSeparator;
+  // Don't use `lastIndexOf`, as for files in test fixes
+  // i.e. `packages/flutter_test/test_fixes/flutter_test/matchers.dart`
+  // the overlap index could appear multiple times.
+  // Only take the first one.
+  final int overlapIndex = platformFilepath.indexOf(searchPattern);
+
+  if (overlapIndex < 0) {
+    throw ArgumentError('filepath $filepath must be located in directory ${directory.path}.');
+  }
+
+  final String filename = platformFilepath.substring(overlapIndex + searchPattern.length);
+  return directory.childFile(filename);


Using Platform.pathSeparator and directory.basename directly can cause test failures or compilation errors. It is safer and more robust to use directory.fileSystem.path to retrieve the path separator and basename context-awarely.

Suggested change

File getFile(String filepath, Directory directory) {

final String platformFilepath = filepath.replaceAll('/', Platform.pathSeparator);

final String searchPattern = directory.basename + Platform.pathSeparator;

// Don't use `lastIndexOf`, as for files in test fixes

// i.e. `packages/flutter_test/test_fixes/flutter_test/matchers.dart`

// the overlap index could appear multiple times.

// Only take the first one.

final int overlapIndex = platformFilepath.indexOf(searchPattern);

if (overlapIndex < 0) {

throw ArgumentError('filepath $filepath must be located in directory ${directory.path}.');

}

final String filename = platformFilepath.substring(overlapIndex + searchPattern.length);

return directory.childFile(filename);

File getFile(String filepath, Directory directory) {

final String platformFilepath = filepath.replaceAll('/', directory.fileSystem.path.separator);

final String searchPattern = directory.fileSystem.path.basename(directory.path) + directory.fileSystem.path.separator;

// Don't use `lastIndexOf`, as for files in test fixes

// i.e. `packages/flutter_test/test_fixes/flutter_test/matchers.dart`

// the overlap index could appear multiple times.

// Only take the first one.

final int overlapIndex = platformFilepath.indexOf(searchPattern);

if (overlapIndex < 0) {

throw ArgumentError('filepath $filepath must be located in directory ${directory.path}.');

}

final String filename = platformFilepath.substring(overlapIndex + searchPattern.length);

return directory.childFile(filename);

}

navaronbracke · 2026-06-13T16:39:06Z

 /// image, creates single flutter widget with five copies of requested
 /// image and prints how long the loading took.
 ///
-/// This is used in [$FH/flutter/devicelab/bin/tasks/image_list_reported_duration.dart] test.


Noticed this while fixing up a test. I don't know what $FH is, so I removed it.

navaronbracke · 2026-06-13T16:41:11Z

@@ -0,0 +1,1440 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.


There's a bunch of big switch cases and the new known import lists are also pretty big.

Piinks · 2026-07-08T17:21:07Z

+  /// that we can catch any new cross imports that are added.
+  // TODO(justinmc): Fix all of these tests so there are no cross imports.
+  // See https://github.com/flutter/flutter/issues/187645.
+  static final Set<String> knownExamplesSlashApiCupertinoCrossImports = <String>{


So, I don't know that we need to address cross imports in cupertino or material. All of the sample code has moved over, so there should be no need to make additional changes to those directories. But further, cross imports is I think a lot less strict wrt examples/api. For example, I moved over an example for the cupertino_ui docs in https://github.com/flutter/packages/pull/12086/files that contained no cupertino code, but it was a helpful, contextual example that was already embedded in the docs.
Eventually we will delete the material/ and cupertino/ API examples directories, so I think being able to do that should be the main focus this helps enforce leading up to that, WDYT?

I agree, eventually material/cupertino examples go in material_ui/cupertino_ui

This PR is mainly to flag examples in the core widgets/painting/rendering etc layers, which should ever only import widgets.

Opened flutter/packages#12228 to fix the upstream examples.

Eventually the checker can be updated when the old examples are removed, but this unblocks landing the checker during the code freeze period :)

navaronbracke · 2026-07-16T06:39:14Z

@Piinks Updated the examples cross imports checker with the following:

since the Cupertino magnifier examples were moved from examples/api/widgets to examples/api/cupertino there is no more cross import for those, so they have been removed from the known cross imports
the remaining cross imports for the Cupertino examples have been fixed:

Two tests had a convenience import on Material, instead of Cupertino
For the list tile example, it imported Material for the Icons class + Colors.lightBlue. I decided to let the examples depend on the version of cupertino_icons that the root workspace provides, and used a CupertinoIcons equivalent + a plain blue color as replacement

So yes, now there are no more Cupertino samples with cross imports!

However, this looks to break the code freeze check. I'll post said commit to cupertino_ui instead, but we will have to delete the example here when the time comes.

Piinks

Hey @navaronbracke, thanks for working on this! The shared utility refactoring in cross_imports_checker_utils.dart and cross-platform path handling look great.

Before we land this, I think we should simplify the scope of check_examples_cross_imports.dart to better align with the sample migration strategy:

The primary goal of cross-import checking is to unblock the relocation and eventual deletion of material and cupertino code and samples from flutter/flutter into the standalone material_ui and cupertino_ui package repos.
Since the Material and Cupertino API samples (examples/api/lib/material, examples/api/lib/cupertino, etc.) have already been relocated to material_ui and cupertino_ui, their legacy copies here are temporary placeholders waiting for deletion, so we don't need to check or maintain baseline lists for them (knownExamplesSlashApiMaterialCrossImports / knownExamplesSlashApiCupertinoCrossImports).
I don't think we need to enforce strict subfolder boundaries within core framework samples (e.g. banning rendering imports inside widgets samples). Core framework layers are naturally interdependent, and enforcing granular subfolder separation creates unnecessary churn and large baseline maintenance overhead.

So here is what I suggest, curious too for what @justinmc thinks:

Treat examples/api (or generic non-Material/non-Cupertino samples) as a single library check verifying they don't introduce Material/Cupertino dependencies.
Omit material/ and cupertino/ subfolders under examples/api from the check.
Collapse the 12+ separate knownExamplesSlashApi...CrossImports baseline sets into a much simpler, smaller set.

LMKWYT and thanks again!

Piinks · 2026-07-21T19:49:19Z

The CI failure here is just a timeout, all good. 👍

navaronbracke · 2026-07-21T22:14:16Z

Hey @navaronbracke, thanks for working on this! The shared utility refactoring in cross_imports_checker_utils.dart and cross-platform path handling look great.

Before we land this, I think we should simplify the scope of check_examples_cross_imports.dart to better align with the sample migration strategy:

The primary goal of cross-import checking is to unblock the relocation and eventual deletion of material and cupertino code and samples from flutter/flutter into the standalone material_ui and cupertino_ui package repos.

Since the Material and Cupertino API samples (examples/api/lib/material, examples/api/lib/cupertino, etc.) have already been relocated to material_ui and cupertino_ui, their legacy copies here are temporary placeholders waiting for deletion, so we don't need to check or maintain baseline lists for them (knownExamplesSlashApiMaterialCrossImports / knownExamplesSlashApiCupertinoCrossImports).

I don't think we need to enforce strict subfolder boundaries within core framework samples (e.g. banning rendering imports inside widgets samples). Core framework layers are naturally interdependent, and enforcing granular subfolder separation creates unnecessary churn and large baseline maintenance overhead.

So here is what I suggest, curious too for what @justinmc thinks:

Treat examples/api (or generic non-Material/non-Cupertino samples) as a single library check verifying they don't introduce Material/Cupertino dependencies.

Omit material/ and cupertino/ subfolders under examples/api from the check.

Collapse the 12+ separate knownExamplesSlashApi...CrossImports baseline sets into a much simpler, smaller set.

LMKWYT and thanks again!

Yeah, that sounds reasonable wrt the current situation and where we're going to.
I'll implement those adjustments and let you know when this can be reviewed again.

flutter-dashboard Bot added the CICD Run CI/CD label Jun 7, 2026

navaronbracke requested a review from justinmc June 7, 2026 20:09

Piinks added the framework flutter/packages/flutter repository. See also f: labels. label Jun 8, 2026

navaronbracke force-pushed the check_examples_cross_imports branch from 491ff00 to 81a16df Compare June 13, 2026 09:32

github-actions Bot removed framework flutter/packages/flutter repository. See also f: labels. CICD Run CI/CD labels Jun 13, 2026

flutter-dashboard Bot added the CICD Run CI/CD label Jun 13, 2026

github-actions Bot added the d: examples Sample code and demos label Jun 13, 2026

navaronbracke marked this pull request as ready for review June 13, 2026 16:37

gemini-code-assist Bot reviewed Jun 13, 2026

View reviewed changes

navaronbracke commented Jun 13, 2026

View reviewed changes

navaronbracke force-pushed the check_examples_cross_imports branch from 8e010db to bc37d36 Compare June 14, 2026 08:57

github-actions Bot removed the CICD Run CI/CD label Jun 14, 2026

nate-thegrate mentioned this pull request Jun 23, 2026

Add StreamBuilder sample for changing streams #188335

Draft

navaronbracke force-pushed the check_examples_cross_imports branch from bc37d36 to d6b87d5 Compare June 30, 2026 09:03

navaronbracke mentioned this pull request Jul 2, 2026

Relocate cupertino samples that were under widgets/ #188876

Merged

10 tasks

navaronbracke requested a review from Piinks July 2, 2026 10:28

navaronbracke added the CICD Run CI/CD label Jul 3, 2026

navaronbracke force-pushed the check_examples_cross_imports branch from d6b87d5 to 56c21d0 Compare July 4, 2026 07:52

Piinks added the framework flutter/packages/flutter repository. See also f: labels. label Jul 6, 2026

navaronbracke force-pushed the check_examples_cross_imports branch from 56c21d0 to 2aa3eb5 Compare July 7, 2026 06:35

github-actions Bot removed the framework flutter/packages/flutter repository. See also f: labels. label Jul 7, 2026

navaronbracke force-pushed the check_examples_cross_imports branch 2 times, most recently from 497e404 to 749570f Compare July 8, 2026 13:20

Piinks reviewed Jul 8, 2026

View reviewed changes

navaronbracke added 4 commits July 16, 2026 08:09

move some cross import checker utils to a new file

23924c9

add test setup for examples cross imports checker

9fed581

implement examples cross import checker

25c21dc

add tests for the generic examples

d93b858

navaronbracke added 14 commits July 16, 2026 08:09

add TODO for exemption list

b9c4ccc

smoke test the baseline

caca27a

fix test

dc57fba

update baseline with known imports

e89b058

fix typo

6d7779d

add test for subdirectories

1574bc2

avoid functions inside main() to workaround dartdoc issue

22e2e30

write the correct import string

8f96a9c

walk subdirectories in _getExampleFilesForDirectory()

27c7bc6

support arbitrary subdirectories in _ExamplesLibrary.fromDirectory()

29f72ad

skip test when in example root

43b0cb3

fix path seaprator bug on windows

8932215

add cupertino magnifier examples to exclusion list

5493e76

account for moved cupertino magnifier samples

52eb703

navaronbracke force-pushed the check_examples_cross_imports branch from 3bc100c to 52eb703 Compare July 16, 2026 06:16

github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. f: cupertino flutter/packages/flutter/cupertino repository d: api docs Issues with https://api.flutter.dev/ labels Jul 16, 2026

navaronbracke mentioned this pull request Jul 16, 2026

Move examples of flutter/widgets widgets out from flutter/material #189532

Open

10 tasks

update comment for cupertino samples

6ee4f53

navaronbracke force-pushed the check_examples_cross_imports branch from 5b36af3 to 6ee4f53 Compare July 17, 2026 07:27

github-actions Bot removed framework flutter/packages/flutter repository. See also f: labels. f: cupertino flutter/packages/flutter/cupertino repository d: api docs Issues with https://api.flutter.dev/ labels Jul 17, 2026

navaronbracke mentioned this pull request Jul 17, 2026

[cupertino_ui] fix material_ui cross imports in cupertino_ui samples flutter/packages#12228

Draft

11 tasks

Piinks added the team-framework Owned by Framework team label Jul 20, 2026

Piinks reviewed Jul 21, 2026

View reviewed changes

		@@ -0,0 +1,1440 @@
		// Copyright 2014 The Flutter Authors. All rights reserved.

Uh oh!

Conversation

navaronbracke commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

navaronbracke Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

navaronbracke Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

Piinks Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

navaronbracke Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

navaronbracke Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

navaronbracke commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

Piinks commented Jul 21, 2026

Uh oh!

navaronbracke commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

navaronbracke commented Jun 7, 2026 •

edited

Loading

navaronbracke commented Jul 16, 2026 •

edited

Loading