Support execute.cache frontmatter for notebook caching (#259)

Fixes #216.

Author: MichaelHatherly

.gitignore

@@ -8,5 +8,6 @@ Manifest.toml
 *.jls
 .DS_Store
 .CondaPkg
+.cache
 !/test/assets/*
 !/src/QuartoNotebookWorker/src/vendor/Manifest.toml

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Support for `execute.cache` frontmatter option, which allows notebooks to
+cache the output of cells and reuse them between runs. This is coarse-grained
+and the cache will be invalidated if any text within any executable cells is
+changed, if the frontmatter is changed, or if the `Project.toml` is changed.
+The cached output is stored in a `.cache` folder alongside the notebook where
+caching is enabled. Delete this folder to clear the cache. [#259]
+
 ## [v0.13.2] - 2025-02-24
 
 ### Fixed
@@ -386,5 +395,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#253]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/253
 [#255]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/255
 [#257]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/257
+[#259]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/259
 [#262]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/262
 [#265]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/265

Project.toml

@@ -8,6 +8,7 @@ BSON = "fbb218c0-5317-5bc6-957e-2ee96dd4b1f0"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 CommonMark = "a80b9123-70ca-4bc0-993e-6e3bcb318db6"
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
@@ -30,6 +31,7 @@ BSON = "0.3"
 Base64 = "1.6"
 CommonMark = "0.8"
 Compat = "4"
+Dates = "1.6"
 IOCapture = "0.2"
 InteractiveUtils = "1.6"
 IterTools = "1"

src/Malt.jl

@@ -81,8 +81,10 @@ mutable struct Worker <: AbstractWorker
     current_message_id::MsgID
     expected_replies::Dict{MsgID,Channel{WorkerResult}}
 
+    manifest_file::String
+
     function Worker(; exe = Base.julia_cmd()[1], env = String[], exeflags = [])
-        proc, port, manifest_error = mktempdir() do temp_dir
+        proc, port, manifest_error, manifest_file = mktempdir() do temp_dir
             # The `errors.log` file is used by the worker process to pass back
             # any errors that occur during startup. This is used instead of
             # capturing the process's `stderr` via a pipe since we only need to
@@ -118,7 +120,7 @@ mutable struct Worker <: AbstractWorker
             # the worker is connected to the socket and if there is a mismatch
             # we call `stop` to gracefully close the worker. We cannot
             # gracefully close it until that point.
-            manifest_error =
+            manifest_file, manifest_error =
                 _validate_worker_process_manifest(metadata_toml_file, errors_log_file)
 
             if port === nothing
@@ -160,7 +162,7 @@ mutable struct Worker <: AbstractWorker
                 end
             end
 
-            return proc, port, manifest_error
+            return proc, port, manifest_error, manifest_file
         end
 
         # Connect
@@ -178,6 +180,7 @@ mutable struct Worker <: AbstractWorker
                 socket,
                 MsgID(0),
                 Dict{MsgID,Channel{WorkerResult}}(),
+                manifest_file,
             ),
         )
         atexit(() -> stop(w))
@@ -218,14 +221,15 @@ function _validate_worker_process_manifest(
 
     # When there is no manifest file yet then we don't need to report any
     # issues since there will be no resolver issues.
-    isfile(manifest_toml_file) || return nothing
+    isfile(manifest_toml_file) || return "", nothing
 
     manifest = TOML.parsefile(manifest_toml_file)
     expected_julia_version = get(manifest, "julia_version", "")
+    project_hash = get(manifest, "project_hash", "")
 
     # The older manifest format does not include the `julia_version`. For these
     # ones, just skip the check. To revisit if we encounter issues with this.
-    isempty(expected_julia_version) && return nothing
+    isempty(expected_julia_version) && return project_hash, nothing
 
     if !_compare_versions(actual_julia_version, expected_julia_version)
         message = """
@@ -246,8 +250,9 @@ function _validate_worker_process_manifest(
             message *= "\nERROR: $error_output"
         end
 
-        return message
+        return project_hash, message
     end
+    return project_hash, nothing
 end
 
 # This check needs to happen on the worker process since the hashing of the

src/QuartoNotebookRunner.jl

@@ -22,6 +22,7 @@ import BSON
 import Base64
 import CommonMark
 import Compat
+import Dates
 import InteractiveUtils
 import IterTools
 import JSON3