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

.gitignore

@@ -11,3 +11,4 @@ coverage/
 dist.zip
 packages/jspsych/README.md
 .turbo
+.env

docs/about/about.md

@@ -8,10 +8,20 @@ jsPsych was created by [Josh de Leeuw](https://www.vassar.edu/faculty/jdeleeuw).
 
 If you use this library in academic work, the preferred citation is:
 
-de Leeuw, J.R., Gilbert, R.A., & Luchterhandt, B. (2023). jsPsych: Enabling an open-source collaborative ecosystem of behavioral experiments. *Journal of Open Source Software*, *8*(85), 5351, [https://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
+> de Leeuw, J.R., Gilbert, R.A., & Luchterhandt, B. (2023). jsPsych: Enabling an open-source collaborative ecosystem of behavioral experiments. *Journal of Open Source Software*, *8*(85), 5351, [https://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
 
 This paper is an updated description of jsPsych and includes all current core team members. It replaces the earlier paper that described jsPsych:
 
-de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
+> de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
 
 Citations help us demonstrate that this library is used and valued, which allows us to continue working on it.
+
+#### Citation tool for third-party plugins/extensions
+
+jsPsych is an open-source, collaborative ecosystem, and many of the plugins/extensions you end up using may be contributed by third-party developers! We want to make sure they get recognition for their good work, so we  made a command-line citation tool that you should use to cite this library and the plugins/extensions used in your experiment. You can see this tool in action by following these steps:
+
+1. Launch a jsPsych experiment in your browser
+2. Open up the browser console using Ctrl + ⇧ + J (Windows) or ⌘ + ⌥ + J (Mac)
+3. Type `jsPsych.getCitations([], "apa")`
+
+This should print the APA format citation for the jsPsych library, which you can then copy and paste into your working document. You can type any number of plugins/extensions by name in the array `[ ]` to generate a list of citations, e.g. `jsPsych.getCitations([jsPsychHtmlKeyboardResponse, jsPsychMouseTrackingExtension], "apa")`. We currently support APA formatting (`"apa"`) and BibTex formatting (`"bibtex"`).

docs/developers/contributing.md

@@ -20,6 +20,8 @@ We welcome contributions of any scope. Before we can merge changes into the main
 
 * **An example file should be included if applicable.** If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the `/examples` folder in the repository.
 
+* **We strongly encourage including a file containing citation information.** This file should be named `CITATION.cff` and placed at the root of your repository. This allows people who use your plugin/extension in their code to easily cite your work by calling `jsPsych.getCitations([<yourPlugin>])` from their command line. More information on `.cff` files can be found [here](https://citation-file-format.github.io/).
+
 * **A changeset must be included in the pull request**. We use [changesets](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) to generate new releases and their corresponding release notes. [This is a good overview of changesets](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) that explains how to add one to your pull request. Feel free to ask for help with this!
 
 * **Update the contributors.md file**. If you are a first time contributor to jsPsych please add your name to our [contributors file](https://github.com/jspsych/jsPsych/blob/main/contributors.md). And thanks!

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,94 @@
+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;
+    const getCff = (path) => {
+      rawCff = fs.readFileSync(path, "utf-8").toString();
+      const cffData = yaml.parse(rawCff);
+      if (cffData["preferred-citation"]) {
+        preferredCitation = true;
+      }
+      return yaml.stringify(rawCff);
+    };
+
+    try {
+      // look for CITATION.cff in the current directory
+      return getCff("./CITATION.cff");
+    } catch (error) {
+      try {
+        // look for CITATION.cff in the root of the repository
+        return getCff(path.join(appRootPath.path, "CITATION.cff"));
+      } 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/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,40 @@ export class JsPsych {
     return this.timeline?.description.timeline;
   }
 
+  getCitations(
+    plugins: Array<Class<JsPsychPlugin<any>> | Class<JsPsychExtension>> = [],
+    format: "apa" | "bibtex" = "apa"
+  ) {
+    const formatOptions = ["apa", "bibtex"];
+    // prettier-ignore
+    const jsPsychCitations: any = '__CITATIONS__';
+    format = format.toLowerCase() as "apa" | "bibtex";
+    // Check if plugins is an array
+    if (!Array.isArray(plugins)) {
+      throw new Error("Expected array of plugins/extensions");
+    }
+    // Check if format is supported
+    else if (!formatOptions.includes(format)) {
+      throw new Error("Unsupported citation format");
+    }
+    // Print citations
+    else {
+      const jsPsychCitation = jsPsychCitations[format];
+      const citationSet = new Set([jsPsychCitation]);
+
+      for (const plugin of plugins) {
+        try {
+          const pluginCitation = plugin["info"].citations[format];
+          citationSet.add(pluginCitation);
+        } catch {
+          console.error(`${plugin} does not have citation in ${format} format.`);
+        }
+      }
+      const citationList = Array.from(citationSet).join("\n");
+      return citationList;
+    }
+  }
+
   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> {