From 4d6e14903c3f28a991532ec6d98fa78de44cfe95 Mon Sep 17 00:00:00 2001 From: muhammad-musa-ml <81491067+muhammad-musa-ml@users.noreply.github.com> Date: Mon, 9 Nov 2026 04:12:44 -0600 Subject: [PATCH 1/3] Add ignorePattern to FilesystemLoader A file is not loaded as a page when the pattern matches at the start of its path. The path is relative to the content directory and uses forward slashes on every platform. RegExp(r'(.*/)?README\.md$') skips every README.md and RegExp(r'drafts/.*') skips the files below the top-level drafts folder. loadPageSources and addFile both apply the pattern, so a file created while serving does not become a page either. As with filterExtensions, an ignored file can still be read as a partial, and adding one invalidates the pages that read it, so they are rebuilt. Refs #789 --- .../src/route_loader/filesystem_loader.dart | 23 +- .../route_loaders/filesystem_loader_test.dart | 257 ++++++++++++++++++ 2 files changed, 279 insertions(+), 1 deletion(-) diff --git a/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart b/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart index 4ff6b4c37..77473c50c 100644 --- a/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart +++ b/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart @@ -21,6 +21,7 @@ class FilesystemLoader extends RouteLoaderBase { this.directory, { this.filterExtensions = const {}, this.keepSuffixPattern, + this.ignorePattern, super.debugPrint, @visibleForTesting this.fileSystem = const LocalFileSystem(), @visibleForTesting DirectoryWatcherFactory? watcherFactory, @@ -37,6 +38,15 @@ class FilesystemLoader extends RouteLoaderBase { /// A pattern to keep the file suffix for all matching pages. final Pattern? keepSuffixPattern; + /// A pattern for files that should not be loaded as pages. + /// + /// A file is skipped when the pattern matches at the start of its path. The path is relative to [directory] + /// and written with forward slashes on every platform. For example, `RegExp(r'(.*/)?README\.md$')` skips + /// every README.md, and `RegExp(r'drafts/.*')` skips everything below the top-level drafts folder. + /// + /// Like files excluded by [filterExtensions], ignored files can still be read as partials. + final Pattern? ignorePattern; + @visibleForTesting final FileSystem fileSystem; @visibleForTesting @@ -44,6 +54,8 @@ class FilesystemLoader extends RouteLoaderBase { static DirectoryWatcher _defaultWatcherFactory(String path) => DirectoryWatcher(path); + bool _isIgnored(String posixPath) => ignorePattern?.matchAsPrefix(posixPath) != null; + final Map> dependentSources = {}; StreamSubscription? _watcherSub; @@ -113,6 +125,9 @@ class FilesystemLoader extends RouteLoaderBase { final posixPath = p.posix.fromUri( fileSystem.path.toUri(fileSystem.path.relative(entry.path, from: directory)), ); + if (_isIgnored(posixPath)) { + continue; + } entities.add( FilePageSource( posixPath, @@ -142,6 +157,12 @@ class FilesystemLoader extends RouteLoaderBase { final posixPath = p.posix.fromUri( fileSystem.path.toUri(fileSystem.path.relative(path, from: directory)), ); + if (_isIgnored(posixPath)) { + // Like partials excluded by filterExtensions, ignored files are not page sources, + // but pages that read them as partials need a rebuild if they failed while the file was missing. + _invalidateDependentSources(path); + return; + } addSource( FilePageSource( posixPath, @@ -161,7 +182,7 @@ class FilesystemLoader extends RouteLoaderBase { if (source != null) { removeSource(source); } else { - // Partials excluded by filterExtensions are not page sources, + // Partials excluded by filterExtensions or ignorePattern are not page sources, // but might still have dependents registered through readPartial. _invalidateDependentSources(path); } diff --git a/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart b/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart index 21d92a0ae..b7531e34b 100644 --- a/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart +++ b/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart @@ -168,6 +168,127 @@ void main() { expect(sources, hasLength(1)); expect(sources, equals([pageSource('index.md', '/', private: false)])); }); + + test('loads README files when no ignore pattern is set', () async { + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + pagesDir.childFile('index.md').createSync(); + pagesDir.childFile('README.md').createSync(); + + final loader = FilesystemLoader('pages', fileSystem: fileSystem); + + final sources = await loader.loadPageSources(); + + expect( + sources, + unorderedEquals([ + pageSource('index.md', '/', private: false), + pageSource('README.md', '/README', private: false), + ]), + ); + }); + + test('skips files that match the ignore pattern at any depth', () async { + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + pagesDir.childFile('index.md').createSync(); + pagesDir.childFile('README.md').createSync(); + fileSystem.directory('pages/blog').createSync(); + fileSystem.file('pages/blog/post-1.md').createSync(); + fileSystem.file('pages/blog/README.md').createSync(); + fileSystem.directory('pages/blog/2026').createSync(); + fileSystem.file('pages/blog/2026/recap.md').createSync(); + fileSystem.file('pages/blog/2026/README.md').createSync(); + + final loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'(.*/)?README\.md$'), + ); + + final sources = await loader.loadPageSources(); + + expect( + sources, + unorderedEquals([ + pageSource('index.md', '/', private: false), + pageSource('blog/post-1.md', '/blog/post-1', private: false), + pageSource('blog/2026/recap.md', '/blog/2026/recap', private: false), + ]), + ); + }); + + test('matches the ignore pattern from the start of the path only', () async { + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + pagesDir.childFile('README.md').createSync(); + fileSystem.directory('pages/blog/drafts').createSync(recursive: true); + fileSystem.file('pages/blog/README.md').createSync(); + fileSystem.file('pages/blog/drafts/wip.md').createSync(); + fileSystem.directory('pages/notes').createSync(); + fileSystem.file('pages/notes/a.md').createSync(); + + // The last alternative matches only the first part of notes/a.md. + final loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'README\.md$|drafts/.*|notes/'), + ); + + final sources = await loader.loadPageSources(); + + expect( + sources, + unorderedEquals([ + pageSource('blog/README.md', '/blog/README', private: false), + pageSource('blog/drafts/wip.md', '/blog/drafts/wip', private: false), + ]), + ); + }); + + test('skips every file below an ignored directory', () async { + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + pagesDir.childFile('index.md').createSync(); + fileSystem.directory('pages/drafts/old').createSync(recursive: true); + fileSystem.file('pages/drafts/wip.md').createSync(); + fileSystem.file('pages/drafts/old/idea.md').createSync(); + + final loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'drafts/.*'), + ); + + final sources = await loader.loadPageSources(); + + expect(sources, equals([pageSource('index.md', '/', private: false)])); + }); + + test('matches the ignore pattern against forward slash paths on windows', () async { + final fileSystem = MemoryFileSystem(style: FileSystemStyle.windows); + final pagesDir = fileSystem.directory('pages')..createSync(); + pagesDir.childFile('index.md').createSync(); + fileSystem.directory(r'pages\blog').createSync(); + fileSystem.file(r'pages\blog\post-1.md').createSync(); + fileSystem.file(r'pages\blog\README.md').createSync(); + + final loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'blog/README\.md$'), + ); + + final sources = await loader.loadPageSources(); + + expect( + sources, + unorderedEquals([ + pageSource('index.md', '/', private: false), + pageSource('blog/post-1.md', '/blog/post-1', private: false), + ]), + ); + }); }); group('File Watching', () { @@ -217,6 +338,60 @@ void main() { expect(loader.sources.first.url, equals('/about')); }); + test('does not add a source for an ignored file on file add event', () async { + // Arrange + final fileSystem = MemoryFileSystem(); + fileSystem.directory('pages').createSync(); + loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'(.*/)?README\.md$|drafts/'), + watcherFactory: (_) => mockWatcher, + ); + await loader.loadRoutes((_) => PageConfig(), false); + + // Act + fileSystem.file('pages/README.md').createSync(); + eventController.add(WatchEvent(ChangeType.ADD, 'pages/README.md')); + fileSystem.file('pages/blog/README.md').createSync(recursive: true); + eventController.add(WatchEvent(ChangeType.ADD, 'pages/blog/README.md')); + fileSystem.file('pages/drafts/wip.md').createSync(recursive: true); + eventController.add(WatchEvent(ChangeType.ADD, 'pages/drafts/wip.md')); + fileSystem.file('pages/about.md').createSync(); + eventController.add(WatchEvent(ChangeType.ADD, 'pages/about.md')); + await Future.delayed(Duration.zero); + + // Assert + expect(loader.sources.map((source) => source.url), equals(['/about'])); + }); + + test('does not add a source for an ignored file on file add event on windows', () async { + // Arrange + final fileSystem = MemoryFileSystem(style: FileSystemStyle.windows); + fileSystem.directory('pages').createSync(); + loader = FilesystemLoader( + 'pages', + fileSystem: fileSystem, + ignorePattern: RegExp(r'(.*/)?README\.md$|drafts/'), + watcherFactory: (_) => mockWatcher, + ); + await loader.loadRoutes((_) => PageConfig(), false); + + // Act + fileSystem.file(r'pages\README.md').createSync(); + eventController.add(WatchEvent(ChangeType.ADD, r'pages\README.md')); + fileSystem.file(r'pages\blog\README.md').createSync(recursive: true); + eventController.add(WatchEvent(ChangeType.ADD, r'pages\blog\README.md')); + fileSystem.file(r'pages\drafts\wip.md').createSync(recursive: true); + eventController.add(WatchEvent(ChangeType.ADD, r'pages\drafts\wip.md')); + fileSystem.file(r'pages\about.md').createSync(); + eventController.add(WatchEvent(ChangeType.ADD, r'pages\about.md')); + await Future.delayed(Duration.zero); + + // Assert + expect(loader.sources.map((source) => source.url), equals(['/about'])); + }); + test('removes source on file remove event', () async { // Arrange final fileSystem = MemoryFileSystem(); @@ -376,6 +551,88 @@ void main() { expect(await pageSource.load(), isNot(same(cachedComponent))); }); + test('invalidates dependent page when an ignored partial is added', () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + ignorePattern: RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // The page reads the partial while it is missing. + expect( + () => loader.readPartialSync('pages/README.md', pageSource.page!), + throwsA(isA()), + ); + + // Act: Create the partial and simulate its add event. + fileSystem.file('pages/README.md') + ..createSync() + ..writeAsStringSync('Readme'); + eventController.add(WatchEvent(ChangeType.ADD, 'pages/README.md')); + await Future.delayed(Duration.zero); + + // Assert: The page is invalidated, and the partial is not a page source. + expect(pageSource.page, isNull); + expect(loader.sources, hasLength(1)); + + // The rebuilt page can read the partial. + await pageSource.load(); + expect(loader.readPartialSync('pages/README.md', pageSource.page!), equals('Readme')); + }); + + test('invalidates dependent page when an ignored partial is added on windows', () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(style: FileSystemStyle.windows); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + ignorePattern: RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // The page reads the partial while it is missing. + expect( + () => loader.readPartialSync(r'pages\README.md', pageSource.page!), + throwsA(isA()), + ); + + // Act: Create the partial and simulate its add event. + fileSystem.file(r'pages\README.md') + ..createSync() + ..writeAsStringSync('Readme'); + eventController.add(WatchEvent(ChangeType.ADD, r'pages\README.md')); + await Future.delayed(Duration.zero); + + // Assert: The page is invalidated, and the partial is not a page source. + expect(pageSource.page, isNull); + expect(loader.sources, hasLength(1)); + + // The rebuilt page can read the partial. + await pageSource.load(); + expect(loader.readPartialSync(r'pages\README.md', pageSource.page!), equals('Readme')); + }); + for (final filtered in [false, true]) { test('invalidates dependent page when removed partial is restored ' '(${filtered ? 'filtered' : 'unfiltered'})', () async { From e8d7881383574277a1348fc22531fa319e8d8548 Mon Sep 17 00:00:00 2001 From: muhammad-musa-ml <81491067+muhammad-musa-ml@users.noreply.github.com> Date: Mon, 9 Nov 2026 04:12:55 -0600 Subject: [PATCH 2/3] Invalidate pages when a partial that is not a page source changes invalidateFile only acted on files that have a page source, so editing a partial excluded by filterExtensions or ignorePattern left the pages that read it stale until the next reload. It now invalidates those pages, as addFile and removeFile already do. Pages that did not read the partial are left alone. Refs #789 --- .../src/route_loader/filesystem_loader.dart | 4 + .../route_loaders/filesystem_loader_test.dart | 137 ++++++++++++++++++ 2 files changed, 141 insertions(+) diff --git a/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart b/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart index 77473c50c..9920244ac 100644 --- a/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart +++ b/packages/jaspr_content/lib/src/route_loader/filesystem_loader.dart @@ -192,6 +192,10 @@ class FilesystemLoader extends RouteLoaderBase { final source = sources.where((source) => source.file.path == path).firstOrNull; if (source != null) { invalidateSource(source, rebuild: rebuild); + } else { + // Partials excluded by filterExtensions or ignorePattern are not page sources, + // but might still have dependents registered through readPartial. + _invalidateDependentSources(path, rebuild: rebuild); } } diff --git a/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart b/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart index b7531e34b..d4c773248 100644 --- a/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart +++ b/packages/jaspr_content/test/route_loaders/filesystem_loader_test.dart @@ -686,6 +686,143 @@ void main() { }); } + for (final filtered in [false, true]) { + test('invalidates dependent page when ${filtered ? 'an excluded' : 'an ignored'} partial changes', () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + filterExtensions: filtered ? {'.md'} : const {}, + ignorePattern: filtered ? null : RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + + final partialPath = filtered ? 'pages/header.html' : 'pages/README.md'; + fileSystem.file(partialPath) + ..createSync() + ..writeAsStringSync('Old'); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // Establish dependency by reading the partial. + expect(loader.readPartialSync(partialPath, pageSource.page!), equals('Old')); + + // Act: Simulate a modify event on the partial. + eventController.add(WatchEvent(ChangeType.MODIFY, partialPath)); + await Future.delayed(Duration.zero); + + // Assert: The page was invalidated. + expect(pageSource.page, isNull); + }); + + test( + 'invalidates dependent page when ${filtered ? 'an excluded' : 'an ignored'} partial changes on windows', + () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(style: FileSystemStyle.windows); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + filterExtensions: filtered ? {'.md'} : const {}, + ignorePattern: filtered ? null : RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + + final partialPath = filtered ? r'pages\header.html' : r'pages\README.md'; + fileSystem.file(partialPath) + ..createSync() + ..writeAsStringSync('Old'); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // Establish dependency by reading the partial. + expect(loader.readPartialSync(partialPath, pageSource.page!), equals('Old')); + + // Act: Simulate a modify event on the partial. + eventController.add(WatchEvent(ChangeType.MODIFY, partialPath)); + await Future.delayed(Duration.zero); + + // Assert: The page was invalidated. + expect(pageSource.page, isNull); + }, + ); + } + + test('keeps a page that did not read a changed partial that is not a page source', () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + ignorePattern: RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + fileSystem.file('pages/README.md') + ..createSync() + ..writeAsStringSync('Old'); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. The page never reads the partial. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // Act: Simulate a modify event on the partial. + eventController.add(WatchEvent(ChangeType.MODIFY, 'pages/README.md')); + await Future.delayed(Duration.zero); + + // Assert: The page was not invalidated. + expect(pageSource.page, isNotNull); + }); + + test('keeps a page that did not read a changed partial that is not a page source on windows', () async { + // Arrange the file system layout and content. + final fileSystem = MemoryFileSystem(style: FileSystemStyle.windows); + final pagesDir = fileSystem.directory('pages')..createSync(); + final loader = FilesystemLoader( + 'pages', + ignorePattern: RegExp(r'(.*/)?README\.md$'), + fileSystem: fileSystem, + watcherFactory: (_) => mockWatcher, + ); + fileSystem.file(r'pages\README.md') + ..createSync() + ..writeAsStringSync('Old'); + pagesDir.childFile('index.md') + ..createSync() + ..writeAsStringSync('Page content'); + + // Initial load to activate the watcher. The page never reads the partial. + await loader.loadRoutes((_) => PageConfig(), false); + final pageSource = loader.sources.single; + await pageSource.load(); + + // Act: Simulate a modify event on the partial. + eventController.add(WatchEvent(ChangeType.MODIFY, r'pages\README.md')); + await Future.delayed(Duration.zero); + + // Assert: The page was not invalidated. + expect(pageSource.page, isNotNull); + }); + for (final eager in [false, true]) { test('invalidates dependent page when ' 'partial is removed (${eager ? 'eager' : 'lazy'})', () async { From e8fecb328025c2d8ec22e6bbca76cd5543e3acbc Mon Sep 17 00:00:00 2001 From: muhammad-musa-ml <81491067+muhammad-musa-ml@users.noreply.github.com> Date: Mon, 9 Nov 2026 04:12:56 -0600 Subject: [PATCH 3/3] Document ignorePattern Add the option to the FilesystemLoader entry of the route loading page, and two lines to the jaspr_content changelog. Refs #789 --- docs/content/concepts/route_loading.mdx | 1 + packages/jaspr_content/CHANGELOG.md | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/docs/content/concepts/route_loading.mdx b/docs/content/concepts/route_loading.mdx index 260c03803..1d5902778 100644 --- a/docs/content/concepts/route_loading.mdx +++ b/docs/content/concepts/route_loading.mdx @@ -34,6 +34,7 @@ The `FilesystemLoader` loads pages from a specified directory on your local file - Supports hot-reloading in debug mode: Changes to files trigger a rebuild of the affected pages. - Can keep file suffixes for specific paths using the `keepSuffixPattern` argument. - Can ignore unknown file extensions using the `filterExtensions` argument, which allows for co-locating data files or assets within the content directory. + - Can skip files by path using the `ignorePattern` argument, for example `RegExp(r'(.*/)?README\.md$')` to leave out every `README.md`. **Example:** diff --git a/packages/jaspr_content/CHANGELOG.md b/packages/jaspr_content/CHANGELOG.md index cdaa6988b..1aac2a6fa 100644 --- a/packages/jaspr_content/CHANGELOG.md +++ b/packages/jaspr_content/CHANGELOG.md @@ -1,3 +1,8 @@ +## Unreleased minor + +- Added `ignorePattern` parameter to `FilesystemLoader`, which skips the files whose path it matches from the start. This can be used to leave files such as `README.md` out of the pages. +- Fixed pages not being rebuilt when a partial that is not a page source, such as a file excluded by `filterExtensions`, is edited while serving. + ## 0.6.0-beta.0 - Require Dart 3.13 or later.