feat: adding differential builds

[jaredwray]

Please check if the PR fulfills these requirements

• Followed the Contributing and Code of Conduct guidelines.
• Tests for the changes have been added (for bug fixes/features) with 100% code coverage.

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
feat: adding differential builds

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant performance enhancement by implementing differential builds. The system now tracks content hashes of all source files and assets in a build manifest. On subsequent builds, it intelligently re-processes only the content that has changed, leading to much faster build times, especially in watch mode. This optimization reduces redundant work by leveraging cached parsed objects for unchanged documents and changelog entries, and by conditionally copying assets.

Highlights

• Differential Builds Implementation: Introduced a new differential build system that leverages content hashing and a build manifest to significantly improve build performance by only reprocessing changed content. This includes documents, changelog entries, and assets.
• Caching Mechanism Enhancement: Updated the caching strategy to store parsed document and changelog objects, allowing subsequent builds to load these from cache instead of re-parsing, further speeding up the build process.
• Asset Copy Optimization: Optimized asset copying by comparing content hashes, ensuring that static assets like favicons, logos, CSS, and JS files are only copied if they have actually changed.
• Watch Mode Improvement: Enhanced the watch mode to ignore changes within the .cache directory, preventing infinite rebuild loops triggered by the internal caching files themselves.
• Comprehensive Testing: Added extensive unit tests to validate the new differential build logic, covering scenarios like manifest creation, build skipping, document changes, config changes, and asset change detection.
• Documentation Update: Updated the caching.md documentation to reflect the new differential build features and how they contribute to faster build times.

Changelog

• site/docs/caching.md
  • Updated template overrides section to mention content hashes and incremental updates.
  • Added a new section detailing the build manifest and how differential builds work for documents, changelog entries, and assets.
• src/builder.ts
  • Defined BuildManifest interface for storing build metadata and content hashes.
  • Introduced logic in the build method to load/save build manifests, compute current hashes for config, templates, documents, changelog, and assets.
  • Added a full build skip mechanism if no changes are detected and the output directory exists.
  • Modified getDocuments and getDocumentInDirectory to utilize cached parsed document objects based on content hashes.
  • Modified getChangelogEntries to utilize cached parsed changelog entries based on content hashes.
  • Updated asset copying logic (e.g., favicon, logo, CSS, JS, variables.css) to conditionally skip copying if assets haven't changed based on hashes.
  • Added new private methods: loadBuildManifest, saveBuildManifest, hashOptions, hashTemplateDirectory, loadCachedDocuments, saveCachedDocuments, loadCachedChangelog, saveCachedChangelog, hashSourceFiles, hasAssetsChanged, shouldSkipAssetCopy, and copyDirectoryWithHashing.
• src/docula.ts
  • Adjusted console output for build completion in watch mode.
  • Added logic to the file watcher to ignore changes in the .cache directory.
• test/builder.test.ts
  • Added afterEach hook to clean up build manifests in test fixtures.
  • Introduced a new test suite for "Docula Builder - Differential Builds" with tests for manifest writing, build skipping, document changes, cached document usage, config changes, manifest loading/saving, corrupt manifest handling, asset copy skipping, asset change detection, cached changelog entries, and corrupt changelog handling.
• test/docula.test.ts
  • Added afterEach hook to clean up build manifests in test fixtures.
  • Updated the --clean flag test to verify that the build manifest is recreated after a clean build.
• test/fixtures/mega-custom-template/docs/keyv.md
  • Adjusted whitespace in the document.

Activity

• The author, jaredwray, created this pull request to introduce differential builds.
• No human review comments or activities have been recorded yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a differential build system to improve performance by caching build artifacts and skipping redundant work. The changes are primarily in src/builder.ts, with new logic for hashing files, managing a build manifest, and conditionally skipping build steps. New tests have been added to validate this caching behavior.

My review focuses on the correctness and maintainability of the new caching logic. I've identified a potential correctness issue with how file hashes are compared, which could lead to unnecessary rebuilds. I've also pointed out a couple of areas for improvement regarding function purity and efficiency in asset handling. Overall, this is a great feature addition.

[codecov]

Codecov Report

❌ Patch coverage is 99.43503% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.94%. Comparing base (3138837) to head (48ebea9).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
src/docula.ts	85.71%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #358      +/-   ##
===========================================
- Coverage   100.00%   99.94%   -0.06%     
===========================================
  Files            7        7              
  Lines         1625     1788     +163     
  Branches       474      520      +46     
===========================================
+ Hits          1625     1787     +162     
- Misses           0        1       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5458b46569

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".