Add JSDoc types for govuk-prototype-kit.config.json

alphagov · Nov 3, 2023 · 39a3b41 · 39a3b41
1 parent 3cce265
commit 39a3b41
Show file tree

Hide file tree

Showing 2 changed files with 82 additions and 25 deletions.
diff --git a/lib/govukFrontendPaths.js b/lib/govukFrontendPaths.js
@@ -47,5 +47,5 @@ module.exports = {
  * @property {string} baseDir - GOV.UK Frontend directory path
  * @property {URL["pathname"]} includePath - URL path to GOV.UK Frontend includes
  * @property {URL["pathname"]} assetPath - URL path to GOV.UK Frontend assets
- * @property {{ [key: string]: unknown }} config - GOV.UK Frontend plugin config
+ * @property {import('./plugins/plugins').ConfigManifest} config - GOV.UK Frontend plugin config
  */
diff --git a/lib/plugins/plugins.js b/lib/plugins/plugins.js
@@ -11,26 +11,7 @@
  * The kit code retrieves the paths as and when needed; this module just
  * contains the code to find and list paths defined by plugins.
  *
- * A schema for an example manifest file follows:
- *
- *     // govuk-prototype-kit.config.json
- *     {
- *       "assets": path | path[],
- *       "importNunjucksMacrosInto": path | path[],
- *       "nunjucksPaths": path | path[],
- *       "nunjucksFilters": path | path[],
- *       "sass": path | path[],
- *       "scripts": path | path[],
- *       "stylesheets": path | path[],
- *       "templates": {
- *         "name": string,
- *         "path": path,
- *         "type": string
- *       }[]
- *     }
- *
- * Note that all of the top-level keys are optional.
- *
+ * See JSDoc `ConfigManifest` for example govuk-prototype-kit.json manifiest
  */
 
 // core dependencies
@@ -300,8 +281,9 @@ const getByType = type => getList(type)
 
 /**
  * Gets public urls for all plugins of type
- * @param {string} listType - (scripts, stylesheets, nunjucks etc)
- * @return {string[]} A list of urls
+ * @template {'assets' | 'scripts' | 'stylesheets'} ListType
+ * @param {ListType} listType - (scripts, stylesheets, nunjucks etc)
+ * @return {ListType extends 'scripts' ? ConfigScript[] | string[] : string[]} A list of urls or script objects
  */
 const getPublicUrls = listType => getList(listType).map(({ packageName, item }) => {
   // item will either be the plugin path or will be an object containing the plugin path within the src property
@@ -330,8 +312,8 @@ const getPublicUrlAndFileSystemPaths = type => getList(type).map(getPublicUrlAnd
 
 /**
  * This is used in the views to output links and scripts for each file
- * @param {{scripts: string[], stylesheets: string[]}} additionalConfig
- * @return {{scripts: {src: string, type: string}[], stylesheets: string[]}} Returns an object containing two keys(scripts & stylesheets),
+ * @param {Partial<ConfigManifest>} [additionalConfig]
+ * @return {{ scripts: ConfigScript[], stylesheets: string[] }} Returns an object containing two keys(scripts & stylesheets),
  *   each item contains an array of full paths to specific files.
  */
 function getAppConfig (additionalConfig) {
@@ -372,3 +354,78 @@ const self = module.exports = {
   setPluginsByType,
   watchPlugins
 }
+
+/**
+ * Prototype Kit plugin config
+ *
+ * Schema for govuk-prototype-kit.json manifiest
+ * Note: All top-level keys are optional
+ *
+ * @typedef {object} ConfigManifest
+ * @property {string | string[]} [assets] - Static asset paths
+ * @property {string | string[]} [importNunjucksMacrosInto] - Templates to import Nunjucks macros into
+ * @property {string | string[]} [nunjucksPaths] - Nunjucks paths
+ * @property {ConfigNunjucksMacro[]} [nunjucksMacros] - Nunjucks macros to include
+ * @property {string | string[]} [nunjucksFilters] - Nunjucks filters to include
+ * @property {string | string[]} [sass] - Sass stylesheets to compile
+ * @property {ConfigScript[] | string[]} [scripts] - JavaScripts to serve
+ * @property {string | string[]} [stylesheets] - Stylesheets to serve
+ * @property {ConfigTemplate[]} [templates] - Templates available
+ * @property {ConfigDependency[]} [pluginDependencies] - Plugin dependencies
+ * @property {ConfigMeta} [meta] - Plugin metadata
+ */
+
+/**
+ * Prototype Kit plugin Nunjucks macro
+ *
+ * @typedef {object} ConfigNunjucksMacro
+ * @property {string} macroName - Nunjucks macro name
+ * @property {string} importFrom - Path to import Nunjucks macro from
+ */
+
+/**
+ * Prototype Kit plugin script
+ *
+ * @typedef {object} ConfigScript
+ * @property {string} src - Path to script
+ * @property {string} [type] - Type attribute for script
+ */
+
+/**
+ * Prototype Kit plugin template
+ *
+ * @typedef {object} ConfigTemplate
+ * @property {string} name - Template name
+ * @property {string} type - Template type
+ * @property {string} path - Path to template
+ */
+
+/**
+ * Prototype Kit plugin dependency
+ *
+ * @typedef {object} ConfigDependency
+ * @property {string} packageName - Package name
+ * @property {string} minVersion - Package minimum version
+ * @property {string} maxVersion - Package maximum version
+ */
+
+/**
+ * Prototype Kit plugin metadata
+ *
+ * @typedef {object} ConfigMeta
+ * @property {string} description - Plugin description
+ * @property {ConfigURLs} urls - Plugin URLs
+ */
+
+/**
+ * Prototype Kit plugin URLs
+ *
+ * @typedef {object} ConfigURLs
+ * @property {string} documentation - Documentation URL
+ * @property {string} releaseNotes - Release notes URL
+ * @property {string} versionHistory - Version history URL
+ */
+
+/**
+ * @typedef {string | string[] | ConfigNunjucksMacro | ConfigScript | ConfigTemplate | ConfigDependency | ConfigMeta} ConfigEntry
+ */