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 b2af57525..82a3ff59f 100644 --- a/packages/jaspr_content/CHANGELOG.md +++ b/packages/jaspr_content/CHANGELOG.md @@ -1,5 +1,7 @@ ## Unreleased 0.6.0-beta.1 +- 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. - Fixed `RSSOutput` writing feeds that are not valid RSS 2.0. Dates now use the RFC 822 format, text is escaped, and the `guid` is marked as not a permalink. ## 0.6.0-beta.0 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..9920244ac 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); } @@ -171,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 21d92a0ae..d4c773248 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 { @@ -429,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 {