Generate citation strings from citation.cff file as part of build process

package.json

@@ -27,8 +27,8 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.4.7",
     "@changesets/cli": "^2.25.2",
-    "@jspsych/config": "^1.3.2",
-    "husky": "^8.0.2",
+    "@jspsych/config": "^3.0.0",
+    "husky": "^8.0.3",
     "import-sort-style-module": "^6.0.0",
     "lint-staged": "^13.0.3",
     "prettier": "^2.7.1",

packages/config/generateCitations.js

@@ -0,0 +1,89 @@
+import "@citation-js/plugin-bibtex";
+import "@citation-js/plugin-software-formats";
+import "@citation-js/plugin-csl";
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { Cite } from "@citation-js/core";
+import appRootPath from "app-root-path";
+import yaml from "yaml";
+
+/**
+ * Generate citation data from CITATION.cff file
+ * Currently supported formats: APA, BibTeX
+ *
+ * @returns {Object} - Object containing APA and BibTeX formatted citation data
+ */
+export default function generateCitations() {
+  let preferredCitation = false;
+
+  // Try to find CITATION.cff file and look for preferred-citation
+  const citationCff = (() => {
+    let rawCff;
+    try {
+      rawCff = fs.readFileSync("./CITATION.cff", "utf-8").toString();
+      const cffData = yaml.parse(rawCff);
+      if (cffData["preferred-citation"]) {
+        preferredCitation = true;
+      }
+      return yaml.stringify(rawCff);
+    } catch (error) {
+      try {
+        rawCff = fs.readFileSync(path.join(appRootPath.path, "CITATION.cff"), "utf-8").toString();
+        return yaml.stringify(rawCff);
+      } catch (error) {
+        console.warn(
+          `No CITATION.cff file found: ${error.message}. If you would like to include a citation, please create a CITATION.cff file in the root of your repository.`
+        );
+        return null;
+      }
+    }
+  })();
+
+  if (!citationCff) {
+    return { apa: "", bibtex: "" };
+  }
+
+  // Convert CITATION.cff to APA string
+  const citationApa = (() => {
+    try {
+      const apaCite = new Cite(citationCff);
+      apaCite["data"] = preferredCitation ? apaCite["data"].slice(1) : apaCite["data"];
+      const citationApa = apaCite.format("bibliography", {
+        format: "text",
+        template: "apa",
+        lang: "en-us",
+      });
+      return citationApa;
+    } catch (error) {
+      console.log(`Error converting CITATION.cff to APA string: ${error.message}`);
+      return "";
+    }
+  })();
+
+  // Convert CITATION.cff to BibTeX string
+  const citationBibtex = (() => {
+    try {
+      const bibtexCite = new Cite(citationCff);
+      bibtexCite["data"] = preferredCitation ? bibtexCite["data"].slice(1) : bibtexCite["data"];
+      const citationBibtex = bibtexCite.format("bibtex", {
+        format: "text",
+        template: "bibtex",
+        lang: "en-us",
+      });
+      return citationBibtex;
+    } catch (error) {
+      console.log(`Error converting CITATION.cff to BibTeX string: ${error.message}`);
+      return null;
+    }
+  })();
+
+  // Return formatted citation data
+  const citationData = {
+    apa: citationApa.replace(/\n/g, " "),
+    bibtex: citationBibtex.replace(/\n/g, " "),
+  };
+
+  return citationData;
+}

packages/config/package.json

@@ -35,12 +35,18 @@
   },
   "homepage": "https://www.jspsych.org/latest/developers/configuration",
   "dependencies": {
+    "@citation-js/core": "^0.7.14",
+    "@citation-js/plugin-bibtex": "^0.7.14",
+    "@citation-js/plugin-csl": "^0.7.14",
+    "@citation-js/plugin-software-formats": "^0.6.1",
     "@rollup/plugin-commonjs": "26.0.1",
     "@rollup/plugin-node-resolve": "15.2.3",
+    "@rollup/plugin-replace": "^6.0.1",
     "@sucrase/jest-plugin": "3.0.0",
     "@types/gulp": "4.0.17",
     "@types/jest": "29.5.8",
     "alias-hq": "6.2.4",
+    "app-root-path": "^3.1.0",
     "canvas": "^2.11.2",
     "esbuild": "0.23.1",
     "gulp": "5.0.0",
@@ -55,9 +61,17 @@
     "rollup": "4.21.2",
     "rollup-plugin-dts": "6.1.1",
     "rollup-plugin-esbuild": "6.1.1",
+    "rollup-plugin-modify": "^3.0.0",
     "rollup-plugin-node-externals": "7.1.3",
     "sucrase": "3.34.0",
     "tslib": "2.6.2",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "yaml": "^2.5.1"
+  },
+  "overrides": {
+    "alias-hq": {
+      "jscodeshift": "0.16.1",
+      "inquirer": "10.1.6"
+    }
   }
 }

packages/config/rollup.js

@@ -6,9 +6,12 @@ import resolve from "@rollup/plugin-node-resolve";
 import { defineConfig } from "rollup";
 import dts from "rollup-plugin-dts";
 import esbuild from "rollup-plugin-esbuild";
+import modify from "rollup-plugin-modify";
 import externals from "rollup-plugin-node-externals";
 import ts from "typescript";
 
+import generateCitations from "./generateCitations.js";
+
 const getTsCompilerOptions = () => {
   const cwd = process.cwd();
   return ts.parseJsonConfigFileContent(
@@ -38,6 +41,8 @@ const makeConfig = ({
     ...outputOptions,
   };
 
+  const citationData = generateCitations();
+
   /** @type{import("rollup-plugin-esbuild").Options} */
   const esBuildPluginOptions = {
     loaders: { ".json": "json" },
@@ -71,6 +76,11 @@ const makeConfig = ({
       input,
       plugins: [
         externals(),
+        modify({
+          // prettier-ignore
+          find: /'__CITATIONS__'/g,
+          replace: JSON.stringify(citationData, null, 2),
+        }),
         esbuild({ ...esBuildPluginOptions, target: "node18" }),
         commonjs(commonjsPluginOptions),
       ],
@@ -96,6 +106,10 @@ const makeConfig = ({
       input,
       plugins: [
         externals({ deps: false }),
+        modify({
+          find: /'__CITATIONS__'/g,
+          replace: JSON.stringify(citationData, null, 2),
+        }),
         resolve({ preferBuiltins: false }),
         esbuild({ ...esBuildPluginOptions, target: "esnext" }),
         commonjs(commonjsPluginOptions),
@@ -115,6 +129,10 @@ const makeConfig = ({
       input,
       plugins: [
         externals({ deps: false }),
+        modify({
+          find: /'__CITATIONS__'/g,
+          replace: JSON.stringify(citationData, null, 2),
+        }),
         resolve({ preferBuiltins: false }),
         esbuild({ ...esBuildPluginOptions, target: "es2015", minify: true }),
         commonjs(commonjsPluginOptions),
@@ -164,8 +182,9 @@ export const makeCoreRollupConfig = () =>
 /**
  * Returns the rollup configuration for Node.js-only packages
  */
-export const makeNodeRollupConfig = () =>
-  makeConfig({
+export const makeNodeRollupConfig = () => {
+  return makeConfig({
     globalOptions: { external: ["jspsych"] },
     isNodeOnlyBuild: true,
   });
+};

packages/extension-mouse-tracking/CITATION.cff

@@ -0,0 +1,47 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Leeuw
+  given-names: Joshua R.
+  name-particle: de
+  orcid: "https://orcid.org/0000-0003-4815-2364"
+- family-names: Gilbert
+  given-names: Rebecca A.
+  orcid: "https://orcid.org/0000-0003-4574-7792"
+- family-names: Luchterhandt
+  given-names: Björn
+  orcid: "https://orcid.org/0000-0002-9225-2787"
+contact:
+- family-names: Leeuw
+  given-names: Joshua R.
+  name-particle: de
+  orcid: "https://orcid.org/0000-0003-4815-2364"
+doi: 10.5281/zenodo.7702307
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Leeuw
+    given-names: Joshua R.
+    name-particle: de
+    orcid: "https://orcid.org/0000-0003-4815-2364"
+  - family-names: Gilbert
+    given-names: Rebecca A.
+    orcid: "https://orcid.org/0000-0003-4574-7792"
+  - family-names: Luchterhandt
+    given-names: Björn
+    orcid: "https://orcid.org/0000-0002-9225-2787"
+  date-published: 2023-05-11
+  doi: 10.21105/joss.05351
+  issn: 2475-9066
+  issue: 85
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 5351
+  title: "jsPsych: Enabling an Open-Source Collaborative Ecosystem of
+    Behavioral Experiments"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.05351"
+  volume: 8
+title: "jsPsych: Enabling an Open-Source Collaborative Ecosystem of
+  Behavioral Experiments"

packages/extension-mouse-tracking/src/index.ts

@@ -95,6 +95,8 @@ class MouseTrackingExtension implements JsPsychExtension {
         },
       },
     },
+    // prettier-ignore
+    citations: '__CITATIONS__',
   };
 
   constructor(private jsPsych: JsPsych) {}

packages/extension-record-video/src/index.ts

@@ -16,6 +16,8 @@ class RecordVideoExtension implements JsPsychExtension {
         type: ParameterType.STRING,
       },
     },
+    // prettier-ignore
+    citations: '__CITATIONS__',
   };
 
   constructor(private jsPsych: JsPsych) {

packages/extension-webgazer/src/index.ts

@@ -91,6 +91,8 @@ class WebGazerExtension implements JsPsychExtension {
         },
       },
     },
+    // prettier-ignore
+    citations: '__CITATIONS__',
   };
 
   constructor(private jsPsych: JsPsych) {}

packages/jspsych/src/ExtensionManager.spec.ts

@@ -1,6 +1,6 @@
 import { Class } from "type-fest";
 
-import { TestExtension } from "../tests/extensions/test-extension";
+import { TestExtension } from "../tests/extensions/TestExtension";
 import { ExtensionManager, ExtensionManagerDependencies } from "./ExtensionManager";
 import { JsPsych } from "./JsPsych";
 import { JsPsychExtension } from "./modules/extensions";

packages/jspsych/src/JsPsych.ts

@@ -1,9 +1,13 @@
 import autoBind from "auto-bind";
+// To work with citations
+import { Class } from "type-fest";
 
 import { version } from "../package.json";
 import { ExtensionManager, ExtensionManagerDependencies } from "./ExtensionManager";
 import { JsPsychData, JsPsychDataDependencies } from "./modules/data";
+import { JsPsychExtension } from "./modules/extensions";
 import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
+import { JsPsychPlugin } from "./modules/plugins";
 import * as randomization from "./modules/randomization";
 import * as turk from "./modules/turk";
 import * as utils from "./modules/utils";
@@ -257,6 +261,31 @@ export class JsPsych {
     return this.timeline?.description.timeline;
   }
 
+  getCitations(
+    plugins: Array<Class<JsPsychPlugin<any>> | Class<JsPsychExtension>>,
+    format?: string
+  ) {
+    format = format ? format.toLowerCase() : "apa";
+    // Check if plugins is an array
+    if (!Array.isArray(plugins)) {
+      throw new Error("Expected array of plugins/extensions");
+    }
+    // Check if array is empty
+    else if (plugins.length == 0) {
+      console.warn("No plugins/extensions provided");
+      return;
+    }
+    // Check if format is supported
+    else if (!Object.keys(plugins[0]["info"].citations).includes(format)) {
+      throw new Error("Unsupported citation format");
+    } else {
+      plugins.map((plugin) => {
+        let pluginCitations = plugin["info"].citations;
+        console.log(format == "apa" ? `${pluginCitations.apa}` : `${pluginCitations.bibtex}`);
+      });
+    }
+  }
+
   get extensions() {
     return this.extensionManager?.extensions ?? {};
   }

packages/jspsych/src/modules/extensions.ts

@@ -4,6 +4,7 @@ export interface JsPsychExtensionInfo {
   name: string;
   version?: string;
   data?: ParameterInfos;
+  citations?: Record<string, string> | string;
 }
 
 export interface JsPsychExtension {

packages/jspsych/src/modules/plugins.ts

@@ -141,6 +141,7 @@ export interface PluginInfo {
   version?: string;
   parameters: ParameterInfos;
   data?: ParameterInfos;
+  citations?: Record<string, string> | string;
 }
 
 export interface JsPsychPlugin<I extends PluginInfo> {

packages/jspsych/tests/TestPlugin.ts

@@ -10,6 +10,10 @@ export const testPluginInfo = <const>{
   version: "0.0.1",
   parameters: {},
   data: {},
+  citations: {
+    apa: "Test plugin APA citation",
+    bibtex: "Test plugin BibTeX citation",
+  },
 };
 
 class TestPlugin implements JsPsychPlugin<typeof testPluginInfo> {