Merge pull request #9953 from quarto-dev/bugfix/9948

extensions - canonicalize to array, process post-render scripts

Author: cscheid

news/changelog-1.5.md

@@ -122,7 +122,7 @@ All changes included in 1.5:
 
 - ([#8385](https://github.com/quarto-dev/quarto-cli/issues/8385)): Properly copy project resources when extensions are installed at project level.
 - ([#8547](https://github.com/quarto-dev/quarto-cli/issues/8547)): Support installing extensions from github branch with forward slash in the name.
-- ([#9889](https://github.com/quarto-dev/quarto-cli/issues/9889)): Support `pre-render` and `post-render` script lists in `project` contributions from extensions.
+- ([#9948](https://github.com/quarto-dev/quarto-cli/issues/9948)): New extension type: `metadata`. Example use case: support `pre-render` and `post-render` script lists in `project` metadata.
 
 ## Shortcodes
 

src/command/create/artifacts/extension.ts

@@ -40,6 +40,7 @@ const kExtensionTypes: Array<string | ExtensionType> = [
   },
   { name: "journal format", value: "journal", openfiles: ["template.qmd"] },
   { name: "custom format", value: "format", openfiles: ["template.qmd"] },
+  { name: "metadata", value: "metadata", openfiles: [] },
 ];
 
 const kExtensionSubtypes: Record<string, string[]> = {

src/command/render/project.ts

@@ -7,6 +7,7 @@
 import { ensureDirSync, existsSync } from "fs/mod.ts";
 import { dirname, isAbsolute, join, relative } from "../../deno_ral/path.ts";
 import { info, warning } from "../../deno_ral/log.ts";
+import { mergeProjectMetadata } from "../../config/metadata.ts";
 
 import * as colors from "fmt/colors.ts";
 
@@ -72,6 +73,8 @@ import { Format } from "../../config/types.ts";
 import { fileExecutionEngine } from "../../execute/engine.ts";
 import { projectContextForDirectory } from "../../project/project-context.ts";
 import { ProjectType } from "../../project/types/types.ts";
+import { ProjectConfig as ProjectConfig_Project } from "../../resources/types/schema-types.ts";
+import { Extension } from "../../extension/types.ts";
 
 const noMutationValidations = (
   projType: ProjectType,
@@ -217,14 +220,7 @@ const computeProjectRenderConfig = async (
 
 const getProjectRenderScripts = async (
   context: ProjectContext,
-  pOptions: RenderOptions,
 ) => {
-  const extensions = await pOptions.services.extension.extensions(
-    undefined,
-    context.config,
-    context.isSingleFile ? undefined : context.dir,
-    { builtIn: false },
-  );
   const preRenderScripts: string[] = [],
     postRenderScripts: string[] = [];
   if (context.config?.project?.[kProjectPreRender]) {
@@ -237,35 +233,40 @@ const getProjectRenderScripts = async (
       ...asArray(context.config?.project?.[kProjectPostRender]!),
     );
   }
-  extensions.forEach((extension) => {
-    if (extension.contributes.project?.project) {
-      const project = extension.contributes.project.project as Record<
-        string,
-        unknown
-      >;
-      if (project[kProjectPreRender]) {
-        preRenderScripts.push(
-          ...asArray(project[kProjectPreRender] as string | string[]),
-        );
-      }
-      if (project[kProjectPostRender]) {
-        postRenderScripts.push(
-          ...asArray(project[kProjectPostRender] as string | string[]),
-        );
-      }
-    }
-  });
   return { preRenderScripts, postRenderScripts };
 };
 
+const mergeExtensionMetadata = async (
+  context: ProjectContext,
+  pOptions: RenderOptions,
+) => {
+  // this will mutate context.config.project to merge
+  // in any project metadata from extensions
+  if (context.config) {
+    const extensions = await pOptions.services.extension.extensions(
+      undefined,
+      context.config,
+      context.isSingleFile ? undefined : context.dir,
+      { builtIn: false },
+    );
+    const projectMetadata = extensions.map((extension) =>
+      extension.contributes.metadata?.project
+    ).filter((project) => project) as ProjectConfig_Project[];
+    context.config.project = mergeProjectMetadata(
+      context.config.project,
+      ...projectMetadata,
+    );
+  }
+};
+
 export async function renderProject(
   context: ProjectContext,
   pOptions: RenderOptions,
   pFiles?: string[],
 ): Promise<RenderResult> {
+  mergeExtensionMetadata(context, pOptions);
   const { preRenderScripts, postRenderScripts } = await getProjectRenderScripts(
     context,
-    pOptions,
   );
 
   // lookup the project type

src/extension/extension.ts

@@ -347,6 +347,8 @@ function findExtensions(
       return true;
     } else if (contributes === "project" && ext.contributes.project) {
       return true;
+    } else if (contributes === "metadata" && ext.contributes.metadata) {
+      return true;
     } else if (
       contributes === kRevealJSPlugins && ext.contributes[kRevealJSPlugins]
     ) {
@@ -625,6 +627,7 @@ function validateExtension(extension: Extension) {
     extension.contributes.formats,
     extension.contributes.project,
     extension.contributes[kRevealJSPlugins],
+    extension.contributes.metadata,
   ];
   contribs.forEach((contrib) => {
     if (contrib) {
@@ -783,22 +786,31 @@ async function readExtension(
       return resolveFilterPath(extensionDir, filter);
     },
   );
-  const project = (contributes?.project || {}) as Record<string, unknown>;
-  // resolve project pre- and post-render scripts to their full path
-  if (
-    project.project &&
-    (project.project as Record<string, unknown>)["pre-render"]
-  ) {
-    const preRender =
-      (project.project as Record<string, unknown>)["pre-render"] as string[];
-    const resolved = resolvePathGlobs(
-      extensionDir,
-      preRender as string[],
-      [],
-    );
-    if (resolved.include.length > 0) {
-      (project.project as Record<string, unknown>)["pre-render"] = resolved
-        .include;
+  const project = contributes?.project as Record<string, unknown> | undefined;
+  const metadata = contributes?.metadata as Record<string, unknown> | undefined;
+
+  // resolve metadata/project pre- and post-render scripts to their full path
+  for (const key of ["pre-render", "post-render"]) {
+    for (const object of [metadata, project]) {
+      if (!object?.project || typeof object.project !== "object") {
+        continue;
+      }
+      // object.project is truthy and typeof object.project is object
+      // so we can safely cast object.project to Record<string, unknown>
+      // the TypeScript checker doesn't appear to recognize this
+      const t = (object.project as Record<string, unknown>)[key];
+      if (t) {
+        const value = (Array.isArray(t) ? t : [t]) as string[];
+        const resolved = resolvePathGlobs(
+          extensionDir,
+          value as string[],
+          [],
+        );
+        if (resolved.include.length > 0) {
+          (object.project as Record<string, unknown>)[key] = resolved
+            .include;
+        }
+      }
     }
   }
   const revealJSPlugins = ((contributes?.[kRevealJSPlugins] || []) as Array<
@@ -816,10 +828,11 @@ async function readExtension(
     id: extensionId,
     path: extensionDir,
     contributes: {
+      metadata,
       shortcodes,
       filters,
       formats,
-      project,
+      project: project ?? {},
       [kRevealJSPlugins]: revealJSPlugins,
     },
   };

src/extension/types.ts

@@ -23,7 +23,8 @@ export type Contributes =
   | "filters"
   | "formats"
   | "project"
-  | "revealjs-plugins";
+  | "revealjs-plugins"
+  | "metadata";
 
 export interface Extension extends Record<string, unknown> {
   id: ExtensionId;
@@ -33,6 +34,7 @@ export interface Extension extends Record<string, unknown> {
   quartoVersion?: Range;
   path: string;
   contributes: {
+    metadata?: Metadata;
     project?: Record<string, unknown>;
     shortcodes?: string[];
     filters?: QuartoFilter[];
@@ -75,7 +77,8 @@ export interface ExtensionContext {
       | "filters"
       | "formats"
       | "project"
-      | "revealjs-plugins",
+      | "revealjs-plugins"
+      | "metadata",
     config?: ProjectConfig,
     projectDir?: string,
     options?: ExtensionOptions,

src/resources/create/extensions/metadata/.gitignore

@@ -0,0 +1,3 @@
+*.html
+*.pdf
+*_files/

src/resources/create/extensions/metadata/README.ejs.md

@@ -0,0 +1,22 @@
+# <%= title %> Extension For Quarto
+
+_TODO_: Add a short description of your extension.
+
+## Installing
+
+_TODO_: Replace the `<github-organization>` with your GitHub organization.
+
+```bash
+quarto add <github-organization>/<%= filesafename %>
+```
+
+This will install the extension under the `_extensions` subdirectory.
+If you're using version control, you will want to check in this directory.
+
+## Using
+
+_TODO_: Describe how to use your extension.
+
+## Example
+
+Here is the source code for a minimal example: [example.qmd](example.qmd).

src/resources/create/extensions/metadata/_extensions/qstart-filesafename-qend/_extension.ejs.yml

@@ -0,0 +1,8 @@
+title: <%= title %>
+author: <%= author %>
+version: <%= version %>
+quarto-required: ">=<%= quartoversion %>"
+contributes:
+  metadata:
+    project:
+      # your per-project metadata goes here

…ion/_extensions/prerender/_extension.yml …tensions/author/prerender/_extension.ymltests/docs/project/prepost/extension/_extensions/prerender/_extension.yml renamed to tests/docs/project/prepost/extension/_extensions/author/prerender/_extension.yml tests/docs/project/prepost/extension/_extensions/prerender/_extension.yml renamed to tests/docs/project/prepost/extension/_extensions/author/prerender/_extension.yml

@@ -3,9 +3,9 @@ author: cscheid
 version: 1.0.0
 quarto-required: ">=1.2.0"
 contributes:
-  project:
+  metadata:
     project:
       pre-render:
         - pre-render.ts
-
-  
+      post-render:
+        - post-render.ts

tests/docs/project/prepost/extension/_extensions/author/prerender/post-render.ts

@@ -0,0 +1,12 @@
+import { join } from "https://deno.land/std/path/mod.ts";
+
+try {
+  Deno.removeSync(join(Deno.cwd(), "i-exist.txt"));
+  console.log("post-render ok");
+} catch (e) {
+  if (e instanceof Deno.errors.NotFound) {
+    throw new Error("File should exist.");
+  } else {
+    throw e;
+  }
+}