refactor: decouple build pipeline

[saberzero1]

WIP refactor to decouple as much as possible for the upcoming plugin system.

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
quartz	✅ Ready (View Log)	Visit Preview	2b63a09

[Copilot]

Pull Request Overview

This PR implements a comprehensive refactoring to decouple the Quartz build pipeline, improving modularity and maintainability. The changes introduce a plugin utilities abstraction layer, centralize VFile data types, and enforce immutability in the build context to prevent unintended side effects.

Key changes:

• Introduces PluginUtilities interface for abstracted utility functions accessible via ctx.utils
• Centralizes VFile data schema in vfile-schema.ts for type safety
• Makes BuildCtx readonly with a separate MutableBuildCtx for orchestration

Reviewed Changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
quartz/util/path.ts	Updated TransformOptions.allSlugs to readonly array
quartz/util/ctx.ts	Added readonly modifiers to BuildCtx and created MutableBuildCtx
quartz/plugins/vfile-schema.ts	New centralized VFile data type definitions
quartz/plugins/plugin-context.ts	New plugin utilities abstraction layer
quartz/plugins/test-helpers.ts	New testing utilities for plugin development
quartz/plugins/shared-types.ts	New shared type definitions breaking circular dependencies
quartz/components/resources.ts	New component resource registry
quartz/plugins/transformers/*.ts	Updated to use ctx.utils and added documentation
quartz/plugins/emitters/*.ts	Updated to use ctx.utils instead of direct imports
quartz/plugins/filters/*.ts	Added JSDoc documentation
quartz/components/*.tsx	Removed mutations of ctx.trie
quartz/build.ts	Updated to use MutableBuildCtx and collect aliases properly
quartz.config.ts	Added documentation files to ignore patterns
Documentation files	New migration guide, security summary, and implementation summary

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The split function wrapper adds no value - it simply calls splitAnchor and returns its result. Consider removing this wrapper and directly assigning splitAnchor to maintain simplicity: split: splitAnchor.

Suggested change

	split: (slug: string) => {
	const [path, anchor] = splitAnchor(slug)
	return [path, anchor]
	},
	split: splitAnchor,

[Copilot]

The unescape implementation has a double-unescaping vulnerability. If input contains &, it will be converted to & (correct), but then in a second call, that & will be converted to & (incorrect). The comment acknowledges this matches production, but this is a security issue that should be fixed in both the mock and production code. Consider implementing proper HTML entity decoding that handles all cases correctly, or at minimum, add a TODO comment indicating this is a known issue that needs fixing.

[Copilot]

The non-null assertion utils! is used throughout this file. While the code works, this bypasses TypeScript's safety. Consider adding a guard at the function start: if (!utils) throw new Error('utils not available') or restructure the code to handle the optional utils gracefully.

[Copilot]

The function uses a non-null assertion file.data.aliases! after filtering for its existence. While safe due to the filter, this could be more explicit: .flatMap(([_, file]) => file.data.aliases ?? []) to avoid the assertion and handle edge cases more robustly.

Suggested change

	.filter(([_, file]) => file.data.aliases)
	.flatMap(([_, file]) => file.data.aliases!)
	}
	.flatMap(([_, file]) => file.data.aliases ?? [])
	}

[Copilot]

Multiple non-null assertions on utils! throughout emitter files create potential runtime errors if utils is undefined. Consider adding type guards or making utils required in the BuildCtx interface for emitters, as they consistently need these utilities.

[Copilot]

The trie is now computed on every render if ctx.trie is undefined. Previously, with the nullish coalescing assignment operator, it was computed once and cached. Consider memoizing this computation with useMemo to avoid unnecessary recalculations on re-renders.

[Copilot]

Similar to FolderContent, the trie computation is no longer cached. This could impact performance if the component re-renders frequently. Consider using useMemo to cache the trie computation: const trie = useMemo(() => ctx.trie ?? trieFromAllFiles(allFiles), [ctx.trie, allFiles]).