From f72d7b77acd4619f01f304c5577d5077e6d539f0 Mon Sep 17 00:00:00 2001
From: Daniel Lockyer <hi@daniellockyer.com>
Date: Mon, 6 May 2024 21:16:43 +0200
Subject: [PATCH] Fixed miscellaneous jsdoc comments

- this helps tsserver figure out what the type of things is around our
  codebase
- nothing crazy, mostly Express types for the middleware, application and router levels
---
 ghost/api-framework/lib/http.js                     |  7 ++++++-
 ghost/core/core/server/GhostServer.js               |  2 +-
 ghost/core/core/server/web/admin/app.js             |  4 ++++
 ghost/core/core/server/web/admin/controller.js      |  4 ++--
 .../web/admin/middleware/redirect-admin-urls.js     |  6 ++++++
 ghost/core/core/server/web/announcement/routes.js   |  3 +++
 ghost/core/core/server/web/api/app.js               |  3 +++
 .../core/core/server/web/api/endpoints/admin/app.js |  3 +++
 .../server/web/api/endpoints/admin/middleware.js    | 13 +++++++++++++
 .../core/server/web/api/endpoints/admin/routes.js   |  3 +++
 .../core/server/web/api/endpoints/content/app.js    |  3 +++
 .../server/web/api/endpoints/content/middleware.js  |  2 ++
 .../core/server/web/api/endpoints/content/routes.js |  3 +++
 ghost/core/core/server/web/api/middleware/upload.js | 10 ++++++++--
 ghost/core/core/server/web/comments/routes.js       |  3 +++
 ghost/core/core/server/web/members/app.js           |  3 +++
 ghost/core/core/server/web/parent/app.js            |  3 +++
 ghost/core/core/server/web/parent/backend.js        |  2 +-
 ghost/core/core/server/web/parent/frontend.js       |  2 +-
 .../server/web/parent/middleware/emit-events.js     |  5 +++++
 .../server/web/parent/middleware/ghost-locals.js    |  9 +++++++--
 .../server/web/parent/middleware/log-request.js     |  4 ++++
 .../server/web/parent/middleware/queue-request.js   |  5 +++++
 .../core/server/web/parent/middleware/request-id.js |  4 ++++
 ghost/core/core/server/web/webmentions/routes.js    |  3 +++
 ghost/core/core/shared/express.js                   |  5 +++++
 26 files changed, 104 insertions(+), 10 deletions(-)

diff --git a/ghost/api-framework/lib/http.js b/ghost/api-framework/lib/http.js
index 369ce13aa4..65188185f8 100644
--- a/ghost/api-framework/lib/http.js
+++ b/ghost/api-framework/lib/http.js
@@ -11,9 +11,14 @@ const headers = require('./headers');
  * The wrapper receives the express request, prepares the frame and forwards the request to the pipeline.
  *
  * @param {Function} apiImpl - Pipeline wrapper, which executes the target ctrl function.
- * @return {Function}
+ * @return {import('express').RequestHandler}
  */
 const http = (apiImpl) => {
+    /**
+     * @param {import('express').Request} req - Express request object.
+     * @param {import('express').Response} res - Express response object.
+     * @param {import('express').NextFunction} next - Express next function.
+     */
     return async function Http(req, res, next) {
         debug(`External API request to ${req.url}`);
         let apiKey = null;
diff --git a/ghost/core/core/server/GhostServer.js b/ghost/core/core/server/GhostServer.js
index ebcbe0fab5..dd6c1eeddc 100644
--- a/ghost/core/core/server/GhostServer.js
+++ b/ghost/core/core/server/GhostServer.js
@@ -67,7 +67,7 @@ class GhostServer {
      * Starts the ghost server listening on the configured port.
      * Requires an express app to be passed in
      *
-     * @param  {Object} rootApp - Required express app instance.
+     * @param  {import('express').Application} rootApp - Required express app instance.
      * @return {Promise} Resolves once Ghost has started
      */
     start(rootApp) {
diff --git a/ghost/core/core/server/web/admin/app.js b/ghost/core/core/server/web/admin/app.js
index d67dc2b7b5..02280dbb9d 100644
--- a/ghost/core/core/server/web/admin/app.js
+++ b/ghost/core/core/server/web/admin/app.js
@@ -10,6 +10,10 @@ const errorHandler = require('@tryghost/mw-error-handler');
 const sentry = require('../../../shared/sentry');
 const redirectAdminUrls = require('./middleware/redirect-admin-urls');
 
+/**
+ *
+ * @returns {import('express').Application}
+ */
 module.exports = function setupAdminApp() {
     debug('Admin setup start');
     const adminApp = express('admin');
diff --git a/ghost/core/core/server/web/admin/controller.js b/ghost/core/core/server/web/admin/controller.js
index 20277694b7..eee566cd4b 100644
--- a/ghost/core/core/server/web/admin/controller.js
+++ b/ghost/core/core/server/web/admin/controller.js
@@ -20,8 +20,8 @@ const messages = {
  *
  * Every request to the admin panel will re-trigger the update check service.
  *
- * @param req
- * @param res
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
  */
 module.exports = function adminController(req, res) {
     debug('index called');
diff --git a/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js b/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js
index 097c0d784a..09d08d1047 100644
--- a/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js
+++ b/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js
@@ -1,5 +1,11 @@
 const urlUtils = require('../../../../shared/url-utils');
 
+/**
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 function redirectAdminUrls(req, res, next) {
     const subdir = urlUtils.getSubdir();
     const ghostPathRegex = new RegExp(`^${subdir}/ghost/(.+)`);
diff --git a/ghost/core/core/server/web/announcement/routes.js b/ghost/core/core/server/web/announcement/routes.js
index 9b97b2358a..054069e75c 100644
--- a/ghost/core/core/server/web/announcement/routes.js
+++ b/ghost/core/core/server/web/announcement/routes.js
@@ -3,6 +3,9 @@ const api = require('../../api').endpoints;
 const {http} = require('@tryghost/api-framework');
 const shared = require('../shared');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('announcements');
 
diff --git a/ghost/core/core/server/web/api/app.js b/ghost/core/core/server/web/api/app.js
index cb26e1e18b..a99445d54d 100644
--- a/ghost/core/core/server/web/api/app.js
+++ b/ghost/core/core/server/web/api/app.js
@@ -5,6 +5,9 @@ const sentry = require('../../../shared/sentry');
 const errorHandler = require('@tryghost/mw-error-handler');
 const APIVersionCompatibilityService = require('../../services/api-version-compatibility');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Parent API setup start');
     const apiApp = express('api');
diff --git a/ghost/core/core/server/web/api/endpoints/admin/app.js b/ghost/core/core/server/web/api/endpoints/admin/app.js
index f315febc38..f8e340528a 100644
--- a/ghost/core/core/server/web/api/endpoints/admin/app.js
+++ b/ghost/core/core/server/web/api/endpoints/admin/app.js
@@ -12,6 +12,9 @@ const routes = require('./routes');
 const APIVersionCompatibilityService = require('../../../../services/api-version-compatibility');
 const GhostNestApp = require('@tryghost/ghost');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Admin API setup start');
     const apiApp = express('admin api');
diff --git a/ghost/core/core/server/web/api/endpoints/admin/middleware.js b/ghost/core/core/server/web/api/endpoints/admin/middleware.js
index a3595c061c..ab4dde91fc 100644
--- a/ghost/core/core/server/web/api/endpoints/admin/middleware.js
+++ b/ghost/core/core/server/web/api/endpoints/admin/middleware.js
@@ -8,6 +8,11 @@ const messages = {
     notImplemented: 'The server does not support the functionality required to fulfill the request.'
 };
 
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 const notImplemented = function notImplemented(req, res, next) {
     // CASE: user is logged in, allow
     if (!req.api_key) {
@@ -63,8 +68,12 @@ const notImplemented = function notImplemented(req, res, next) {
     }));
 };
 
+/** @typedef {import('express').RequestHandler} RequestHandler */
+
 /**
  * Authentication for private endpoints
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.authAdminApi = [
     auth.authenticate.authenticateAdminApi,
@@ -79,6 +88,8 @@ module.exports.authAdminApi = [
 /**
  * Authentication for private endpoints with token in URL
  * Ex.: For scheduler publish endpoint
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.authAdminApiWithUrl = [
     auth.authenticate.authenticateAdminApiWithUrl,
@@ -92,6 +103,8 @@ module.exports.authAdminApiWithUrl = [
 
 /**
  * Middleware for public admin endpoints
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.publicAdminApi = [
     apiMw.cors,
diff --git a/ghost/core/core/server/web/api/endpoints/admin/routes.js b/ghost/core/core/server/web/api/endpoints/admin/routes.js
index 52791c3bc3..3ea39dbb7f 100644
--- a/ghost/core/core/server/web/api/endpoints/admin/routes.js
+++ b/ghost/core/core/server/web/api/endpoints/admin/routes.js
@@ -7,6 +7,9 @@ const mw = require('./middleware');
 const shared = require('../../../shared');
 const labs = require('../../../../../shared/labs');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('admin api');
 
diff --git a/ghost/core/core/server/web/api/endpoints/content/app.js b/ghost/core/core/server/web/api/endpoints/content/app.js
index 7d8aa98b89..0d6c371143 100644
--- a/ghost/core/core/server/web/api/endpoints/content/app.js
+++ b/ghost/core/core/server/web/api/endpoints/content/app.js
@@ -9,6 +9,9 @@ const routes = require('./routes');
 const errorHandler = require('@tryghost/mw-error-handler');
 const apiVersionCompatibility = require('../../../../services/api-version-compatibility');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Content API setup start');
     const apiApp = express('content api');
diff --git a/ghost/core/core/server/web/api/endpoints/content/middleware.js b/ghost/core/core/server/web/api/endpoints/content/middleware.js
index b16cfd947d..c5c484c95b 100644
--- a/ghost/core/core/server/web/api/endpoints/content/middleware.js
+++ b/ghost/core/core/server/web/api/endpoints/content/middleware.js
@@ -12,6 +12,8 @@ const shared = require('../../../shared');
 
 /**
  * Authentication for public endpoints
+ *
+ * @type {import('express').RequestHandler[]}
  */
 module.exports.authenticatePublic = [
     shared.middleware.brute.contentApiKey,
diff --git a/ghost/core/core/server/web/api/endpoints/content/routes.js b/ghost/core/core/server/web/api/endpoints/content/routes.js
index 8d23e81b28..1db03d362a 100644
--- a/ghost/core/core/server/web/api/endpoints/content/routes.js
+++ b/ghost/core/core/server/web/api/endpoints/content/routes.js
@@ -5,6 +5,9 @@ const {http} = require('@tryghost/api-framework');
 const mw = require('./middleware');
 const config = require('../../../../../shared/config');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('content api');
 
diff --git a/ghost/core/core/server/web/api/middleware/upload.js b/ghost/core/core/server/web/api/middleware/upload.js
index 165ec209cf..30549356a6 100644
--- a/ghost/core/core/server/web/api/middleware/upload.js
+++ b/ghost/core/core/server/web/api/middleware/upload.js
@@ -156,10 +156,16 @@ const checkFileIsValid = (fileData, types, extensions) => {
  *
  * @param {Object} options
  * @param {String} options.type - type of the file
- * @returns {Function}
+ * @returns {import('express').RequestHandler}
  */
 const validation = function ({type}) {
     // if we finish the data/importer logic, we forward the request to the specified importer
+
+    /**
+     * @param {import('express').Request} req
+     * @param {import('express').Response} res
+     * @param {import('express').NextFunction} next
+     */
     return function uploadValidation(req, res, next) {
         const extensions = (config.get('uploads')[type] && config.get('uploads')[type].extensions) || [];
         const contentTypes = (config.get('uploads')[type] && config.get('uploads')[type].contentTypes) || [];
@@ -192,7 +198,7 @@ const validation = function ({type}) {
  *
  * @param {Object} options
  * @param {String} options.type - type of the file
- * @returns {Function}
+ * @returns {import('express').RequestHandler}
  */
 const mediaValidation = function ({type}) {
     return function mediaUploadValidation(req, res, next) {
diff --git a/ghost/core/core/server/web/comments/routes.js b/ghost/core/core/server/web/comments/routes.js
index b2c731c34c..82a350674d 100644
--- a/ghost/core/core/server/web/comments/routes.js
+++ b/ghost/core/core/server/web/comments/routes.js
@@ -7,6 +7,9 @@ const shared = require('../shared');
 const bodyParser = require('body-parser');
 const membersService = require('../../../server/services/members');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('comment api');
     router.use(bodyParser.json({limit: '50mb'}));
diff --git a/ghost/core/core/server/web/members/app.js b/ghost/core/core/server/web/members/app.js
index df8daaa79d..89311ea8ea 100644
--- a/ghost/core/core/server/web/members/app.js
+++ b/ghost/core/core/server/web/members/app.js
@@ -16,6 +16,9 @@ const api = require('../../api').endpoints;
 const commentRouter = require('../comments');
 const announcementRouter = require('../announcement');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupMembersApp() {
     debug('Members App setup start');
     const membersApp = express('members');
diff --git a/ghost/core/core/server/web/parent/app.js b/ghost/core/core/server/web/parent/app.js
index 2a1c8d9a4b..bbc698966a 100644
--- a/ghost/core/core/server/web/parent/app.js
+++ b/ghost/core/core/server/web/parent/app.js
@@ -4,6 +4,9 @@ const express = require('../../../shared/express');
 const compress = require('compression');
 const mw = require('./middleware');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupParentApp() {
     debug('ParentApp setup start');
     const parentApp = express('parent');
diff --git a/ghost/core/core/server/web/parent/backend.js b/ghost/core/core/server/web/parent/backend.js
index 792ef3686a..66c1019340 100644
--- a/ghost/core/core/server/web/parent/backend.js
+++ b/ghost/core/core/server/web/parent/backend.js
@@ -4,7 +4,7 @@ const {BASE_API_PATH} = require('../../../shared/url-utils');
 
 /**
  *
- * @returns {import('express').RequestHandler}
+ * @returns {import('express').Application}
  */
 module.exports = () => {
     debug('BackendApp setup start');
diff --git a/ghost/core/core/server/web/parent/frontend.js b/ghost/core/core/server/web/parent/frontend.js
index 4b0a8fc991..69d27c7372 100644
--- a/ghost/core/core/server/web/parent/frontend.js
+++ b/ghost/core/core/server/web/parent/frontend.js
@@ -5,7 +5,7 @@ const shared = require('../shared');
 /**
  *
  * @param {import('../../../frontend/services/routing/RouterManager').RouterConfig} routerConfig
- * @returns {import('express').RequestHandler}
+ * @returns {import('express').Application}
  */
 module.exports = (routerConfig) => {
     debug('FrontendApp setup start', routerConfig);
diff --git a/ghost/core/core/server/web/parent/middleware/emit-events.js b/ghost/core/core/server/web/parent/middleware/emit-events.js
index 318bd32612..5d58d3b386 100644
--- a/ghost/core/core/server/web/parent/middleware/emit-events.js
+++ b/ghost/core/core/server/web/parent/middleware/emit-events.js
@@ -3,6 +3,11 @@ const INVALIDATE_ALL = '/*';
 // Emit the site.changed event, a special model event used for webhooks
 const events = require('../../../lib/common/events');
 
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 module.exports = function emitEvents(req, res, next) {
     res.on('finish', function triggerEvents() {
         if (res.get('X-Cache-Invalidate') === INVALIDATE_ALL) {
diff --git a/ghost/core/core/server/web/parent/middleware/ghost-locals.js b/ghost/core/core/server/web/parent/middleware/ghost-locals.js
index 213abedba7..146a6d20fa 100644
--- a/ghost/core/core/server/web/parent/middleware/ghost-locals.js
+++ b/ghost/core/core/server/web/parent/middleware/ghost-locals.js
@@ -1,7 +1,12 @@
 const ghostVersion = require('@tryghost/version');
 
-// ### GhostLocals Middleware
-// Expose the standard locals that every request will need to have available
+/**
+ * Expose the standard locals that every request will need to have available
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 module.exports = function ghostLocals(req, res, next) {
     // Make sure we have a locals value.
     res.locals = res.locals || {};
diff --git a/ghost/core/core/server/web/parent/middleware/log-request.js b/ghost/core/core/server/web/parent/middleware/log-request.js
index 121b63d385..bc1391eaf6 100644
--- a/ghost/core/core/server/web/parent/middleware/log-request.js
+++ b/ghost/core/core/server/web/parent/middleware/log-request.js
@@ -2,6 +2,10 @@ const logging = require('@tryghost/logging');
 
 /**
  * @TODO: move this middleware to Framework monorepo?
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
  */
 module.exports = function logRequest(req, res, next) {
     const startTime = Date.now();
diff --git a/ghost/core/core/server/web/parent/middleware/queue-request.js b/ghost/core/core/server/web/parent/middleware/queue-request.js
index c1cd4a5fe0..debdf8fb2e 100644
--- a/ghost/core/core/server/web/parent/middleware/queue-request.js
+++ b/ghost/core/core/server/web/parent/middleware/queue-request.js
@@ -44,6 +44,11 @@ module.exports = function queueRequest(
         debug(`Request completed: ${job.data.req.path}`);
     });
 
+    /**
+     * @param {import('express').Request} req
+     * @param {import('express').Response} res
+     * @param {import('express').NextFunction} next
+     */
     return function queueRequestMw(req, res, next) {
         req.queueDepth = queue.queue.getLength();
 
diff --git a/ghost/core/core/server/web/parent/middleware/request-id.js b/ghost/core/core/server/web/parent/middleware/request-id.js
index 14ea5cf123..1e537cb191 100644
--- a/ghost/core/core/server/web/parent/middleware/request-id.js
+++ b/ghost/core/core/server/web/parent/middleware/request-id.js
@@ -2,6 +2,10 @@ const uuid = require('uuid');
 
 /**
  * @TODO: move this middleware to Framework monorepo?
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
  */
 module.exports = function requestIdMw(req, res, next) {
     const requestId = req.get('X-Request-ID') || uuid.v4();
diff --git a/ghost/core/core/server/web/webmentions/routes.js b/ghost/core/core/server/web/webmentions/routes.js
index f4bdf0723f..d41978461f 100644
--- a/ghost/core/core/server/web/webmentions/routes.js
+++ b/ghost/core/core/server/web/webmentions/routes.js
@@ -5,6 +5,9 @@ const shared = require('../shared');
 
 const bodyParser = require('body-parser');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('webmentions');
 
diff --git a/ghost/core/core/shared/express.js b/ghost/core/core/shared/express.js
index bf207f7b46..338babcac3 100644
--- a/ghost/core/core/shared/express.js
+++ b/ghost/core/core/shared/express.js
@@ -5,6 +5,11 @@ const sentry = require('./sentry');
 
 const lazyLoad = createLazyRouter();
 
+/**
+ *
+ * @param {String} name
+ * @returns {import('express').Application}
+ */
 module.exports = (name) => {
     debug('new app start', name);
     const app = express();