TS migration setup for url-utils

vershwal · web-flow · commit c8b49fea708e · 2025-11-19T18:03:17.000+05:30
ref https://linear.app/ghost/issue/PRO-1535/ - This PR does the basic TS setup for urlUtils without changing/adding the actual types. This adds // @ts-nocheck in code files and changes the dir structure with TS conventions. - Added TS dependencies and config - Moved files to /src - Renamed files to .ts with // @ts-nocheck - Updated tests to use compiled lib output instead of TS source
diff --git a/packages/url-utils/.eslintrc.js b/packages/url-utils/.eslintrc.js
@@ -1,6 +1,20 @@
 module.exports = {
     plugins: ['ghost'],
     extends: [
-        'plugin:ghost/node'
+        'plugin:ghost/ts'
+    ],
+    overrides: [
+        {
+            // Files with @ts-nocheck are intentionally not fully migrated yet
+            // Disable all linting rules that would fail on these files
+            files: ['**/*.ts'],
+            rules: {
+                '@typescript-eslint/ban-ts-comment': ['error', {
+                    'ts-nocheck': false
+                }],
+                '@typescript-eslint/no-var-requires': 'off',
+                'prefer-const': 'off'
+            }
+        }
     ]
 };
diff --git a/packages/url-utils/.gitignore b/packages/url-utils/.gitignore
@@ -0,0 +1 @@
+lib/
diff --git a/packages/url-utils/index.js b/packages/url-utils/index.js
@@ -1 +1,2 @@
 module.exports = require('./lib/UrlUtils');
+
diff --git a/packages/url-utils/package.json b/packages/url-utils/package.json
@@ -9,10 +9,14 @@
   "author": "Ghost Foundation",
   "license": "MIT",
   "main": "index.js",
+  "types": "lib/UrlUtils.d.ts",
   "scripts": {
     "dev": "echo \"Implement me!\"",
-    "test": "NODE_ENV=testing c8 --all --reporter text --reporter cobertura --reporter html mocha './test/**/*.test.js'",
-    "lint": "eslint . --ext .js --cache",
+    "pretest": "yarn build",
+    "test": "NODE_ENV=testing c8 --src lib --all --reporter text --reporter cobertura --reporter html mocha './test/**/*.test.js'",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src test index.js --ext .js,.ts --cache",
+    "prepare": "NODE_ENV=production yarn build",
     "posttest": "yarn lint"
   },
   "files": [
@@ -24,11 +28,15 @@
   },
   "devDependencies": {
     "@tryghost/config-url-helpers": "^1.0.18",
+    "@types/cheerio": "^0.22.31",
+    "@types/lodash": "^4.14.202",
+    "@types/node": "^20.0.0",
     "c8": "10.1.3",
     "mocha": "11.7.5",
     "rewire": "9.0.1",
     "should": "13.2.3",
-    "sinon": "21.0.0"
+    "sinon": "21.0.0",
+    "typescript": "5.9.3"
   },
   "dependencies": {
     "cheerio": "^0.22.0",
diff --git a/packages/url-utils/src/UrlUtils.ts b/packages/url-utils/src/UrlUtils.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 // Contains all path information to be used throughout the codebase.
 const _ = require('lodash');
 const utils = require('./utils');
diff --git a/packages/url-utils/src/utils/absolute-to-relative.ts b/packages/url-utils/src/utils/absolute-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 // require the whatwg compatible URL library (same behaviour in node and browser)
 const {URL} = require('url');
 const stripSubdirectoryFromPath = require('./strip-subdirectory-from-path');
diff --git a/packages/url-utils/src/utils/absolute-to-transform-ready.ts b/packages/url-utils/src/utils/absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const {URL} = require('url');
 const absoluteToRelative = require('./absolute-to-relative');
 
diff --git a/packages/url-utils/src/utils/build-early-exit-match.ts b/packages/url-utils/src/utils/build-early-exit-match.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
diff --git a/packages/url-utils/src/utils/deduplicate-double-slashes.ts b/packages/url-utils/src/utils/deduplicate-double-slashes.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 function deduplicateDoubleSlashes(url) {
     // Preserve protocol slashes (e.g., http://, https://) and only deduplicate
     // slashes in the path portion. The pattern (^|[^:])\/\/+ matches double slashes
diff --git a/packages/url-utils/src/utils/deduplicate-subdirectory.ts b/packages/url-utils/src/utils/deduplicate-subdirectory.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const {URL} = require('url');
 
 /**
diff --git a/packages/url-utils/src/utils/html-absolute-to-relative.ts b/packages/url-utils/src/utils/html-absolute-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const htmlTransform = require('./html-transform');
 const absoluteToRelative = require('./absolute-to-relative');
 
diff --git a/packages/url-utils/src/utils/html-absolute-to-transform-ready.ts b/packages/url-utils/src/utils/html-absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const htmlTransform = require('./html-transform');
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 const {buildEarlyExitMatch} = require('./build-early-exit-match');
diff --git a/packages/url-utils/src/utils/html-relative-to-absolute.ts b/packages/url-utils/src/utils/html-relative-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const htmlTransform = require('./html-transform');
 const relativeToAbsolute = require('./relative-to-absolute');
 
diff --git a/packages/url-utils/src/utils/html-relative-to-transform-ready.ts b/packages/url-utils/src/utils/html-relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const htmlTransform = require('./html-transform');
 const relativeToTransformReady = require('./relative-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/html-to-transform-ready.ts b/packages/url-utils/src/utils/html-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const htmlRelativeToAbsolute = require('./html-relative-to-absolute');
 const htmlAbsoluteToTransformReady = require('./html-absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/html-transform.ts b/packages/url-utils/src/utils/html-transform.ts
@@ -1,3 +1,6 @@
+// @ts-nocheck
+const cheerio = require('cheerio');
+
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -28,7 +31,6 @@ function htmlTransform(html = '', siteUrl, transformFunction, itemPath, _options
         return html;
     }
 
-    const cheerio = require('cheerio');
     const htmlContent = cheerio.load(html, {decodeEntities: false});
 
     // replacements is keyed with the attr name + original relative value so
diff --git a/packages/url-utils/src/utils/index.ts b/packages/url-utils/src/utils/index.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 module.exports = {
     absoluteToRelative: require('./absolute-to-relative'),
     absoluteToTransformReady: require('./absolute-to-transform-ready'),
diff --git a/packages/url-utils/src/utils/is-ssl.ts b/packages/url-utils/src/utils/is-ssl.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 // require the whatwg compatible URL library (same behaviour in node and browser)
 const {URL} = require('url');
 
diff --git a/packages/url-utils/src/utils/lexical-absolute-to-relative.ts b/packages/url-utils/src/utils/lexical-absolute-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const absoluteToRelative = require('./absolute-to-relative');
 const lexicalTransform = require('./lexical-transform');
 
diff --git a/packages/url-utils/src/utils/lexical-absolute-to-transform-ready.ts b/packages/url-utils/src/utils/lexical-absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 const lexicalTransform = require('./lexical-transform');
 
diff --git a/packages/url-utils/src/utils/lexical-relative-to-absolute.ts b/packages/url-utils/src/utils/lexical-relative-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToAbsolute = require('./relative-to-absolute');
 const lexicalTransform = require('./lexical-transform');
 
diff --git a/packages/url-utils/src/utils/lexical-relative-to-transform-ready.ts b/packages/url-utils/src/utils/lexical-relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToTransformReady = require('./relative-to-transform-ready');
 const lexicalTransform = require('./lexical-transform');
 
diff --git a/packages/url-utils/src/utils/lexical-to-transform-ready.ts b/packages/url-utils/src/utils/lexical-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const lexicalRelativeToAbsolute = require('./lexical-relative-to-absolute');
 const lexicalAbsoluteToTransformReady = require('./lexical-absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/lexical-transform.ts b/packages/url-utils/src/utils/lexical-transform.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const _ = require('lodash');
 
 // options.transformMap = {
diff --git a/packages/url-utils/src/utils/markdown-absolute-to-relative.ts b/packages/url-utils/src/utils/markdown-absolute-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const markdownTransform = require('./markdown-transform');
 const absoluteToRelative = require('./absolute-to-relative');
 const htmlAbsoluteToRelative = require('./html-absolute-to-relative');
diff --git a/packages/url-utils/src/utils/markdown-absolute-to-transform-ready.ts b/packages/url-utils/src/utils/markdown-absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const markdownTransform = require('./markdown-transform');
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 const htmlAbsoluteToTransformReady = require('./html-absolute-to-transform-ready');
diff --git a/packages/url-utils/src/utils/markdown-relative-to-absolute.ts b/packages/url-utils/src/utils/markdown-relative-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const markdownTransform = require('./markdown-transform');
 const htmlRelativeToAbsolute = require('./html-relative-to-absolute');
 const relativeToAbsolute = require('./relative-to-absolute');
diff --git a/packages/url-utils/src/utils/markdown-relative-to-transform-ready.ts b/packages/url-utils/src/utils/markdown-relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const markdownTransform = require('./markdown-transform');
 const htmlRelativeToTransformReady = require('./html-relative-to-transform-ready');
 const relativeToTransformReady = require('./relative-to-transform-ready');
diff --git a/packages/url-utils/src/utils/markdown-to-transform-ready.ts b/packages/url-utils/src/utils/markdown-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const markdownRelativeToAbsolute = require('./markdown-relative-to-absolute');
 const markdownAbsoluteToTransformReady = require('./markdown-absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/markdown-transform.ts b/packages/url-utils/src/utils/markdown-transform.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 let remark;
 const footnotes = require('remark-footnotes');
 const visit = require('unist-util-visit');
diff --git a/packages/url-utils/src/utils/mobiledoc-absolute-to-relative.ts b/packages/url-utils/src/utils/mobiledoc-absolute-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const absoluteToRelative = require('./absolute-to-relative');
 const mobiledocTransform = require('./mobiledoc-transform');
 
diff --git a/packages/url-utils/src/utils/mobiledoc-absolute-to-transform-ready.ts b/packages/url-utils/src/utils/mobiledoc-absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 const mobiledocTransform = require('./mobiledoc-transform');
 
diff --git a/packages/url-utils/src/utils/mobiledoc-relative-to-absolute.ts b/packages/url-utils/src/utils/mobiledoc-relative-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToAbsolute = require('./relative-to-absolute');
 const mobiledocTransform = require('./mobiledoc-transform');
 
diff --git a/packages/url-utils/src/utils/mobiledoc-relative-to-transform-ready.ts b/packages/url-utils/src/utils/mobiledoc-relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToTransformReady = require('./relative-to-transform-ready');
 const mobiledocTransform = require('./mobiledoc-transform');
 
diff --git a/packages/url-utils/src/utils/mobiledoc-to-transform-ready.ts b/packages/url-utils/src/utils/mobiledoc-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const mobiledocRelativeToAbsolute = require('./mobiledoc-relative-to-absolute');
 const mobiledocAbsoluteToTransformReady = require('./mobiledoc-absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/mobiledoc-transform.ts b/packages/url-utils/src/utils/mobiledoc-transform.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 function mobiledocTransform(serializedMobiledoc, siteUrl, transformFunction, itemPath, _options = {}) {
     const defaultOptions = {assetsOnly: false, secure: false, cardTransformers: []};
     const options = Object.assign({}, defaultOptions, _options, {siteUrl, itemPath});
diff --git a/packages/url-utils/src/utils/plaintext-absolute-to-transform-ready.ts b/packages/url-utils/src/utils/plaintext-absolute-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 const {escapeRegExp} = require('./build-early-exit-match');
 
diff --git a/packages/url-utils/src/utils/plaintext-relative-to-transform-ready.ts b/packages/url-utils/src/utils/plaintext-relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToTransformReady = require('./relative-to-transform-ready');
 
 const plaintextRelativeToTransformReady = function plaintextRelativeToTransformReady(plaintext, rootUrl, itemPath, options) {
diff --git a/packages/url-utils/src/utils/plaintext-to-transform-ready.ts b/packages/url-utils/src/utils/plaintext-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const plaintextRelativeToTransformReady = require('./plaintext-relative-to-transform-ready');
 const plaintextAbsoluteToTransformReady = require('./plaintext-absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/relative-to-absolute.ts b/packages/url-utils/src/utils/relative-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 // require the whatwg compatible URL library (same behaviour in node and browser)
 const {URL} = require('url');
 const urlJoin = require('./url-join');
diff --git a/packages/url-utils/src/utils/relative-to-transform-ready.ts b/packages/url-utils/src/utils/relative-to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToAbsolute = require('./relative-to-absolute');
 
 const relativeToTransformReady = function (url, root, itemPath, _options) {
diff --git a/packages/url-utils/src/utils/replace-permalink.ts b/packages/url-utils/src/utils/replace-permalink.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const moment = require('moment-timezone');
 
 /**
diff --git a/packages/url-utils/src/utils/strip-subdirectory-from-path.ts b/packages/url-utils/src/utils/strip-subdirectory-from-path.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const {URL} = require('url');
 
 /**
diff --git a/packages/url-utils/src/utils/to-transform-ready.ts b/packages/url-utils/src/utils/to-transform-ready.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const relativeToAbsolute = require('./relative-to-absolute');
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 
diff --git a/packages/url-utils/src/utils/transform-ready-to-absolute.ts b/packages/url-utils/src/utils/transform-ready-to-absolute.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
diff --git a/packages/url-utils/src/utils/transform-ready-to-relative.ts b/packages/url-utils/src/utils/transform-ready-to-relative.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
diff --git a/packages/url-utils/src/utils/url-join.ts b/packages/url-utils/src/utils/url-join.ts
@@ -1,3 +1,4 @@
+// @ts-nocheck
 const deduplicateSubdirectory = require('./deduplicate-subdirectory');
 
 /** urlJoin
diff --git a/packages/url-utils/tsconfig.json b/packages/url-utils/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+
diff --git a/yarn.lock b/yarn.lock
@@ -3358,6 +3358,13 @@
     "@types/deep-eql" "*"
     assertion-error "^2.0.1"
 
+"@types/cheerio@^0.22.31":
+  version "0.22.35"
+  resolved "https://registry.yarnpkg.com/@types/cheerio/-/cheerio-0.22.35.tgz#0d16dc1f24d426231c181b9c31847f673867595f"
+  integrity sha512-yD57BchKRvTV+JD53UZ6PD8KWY5g5rvvMLRnZR3EQBCZXiDT/HR+pKpMzFGlWNhFrXlo7VPZXtKvIEwZkAWOIA==
+  dependencies:
+    "@types/node" "*"
+
 "@types/color-convert@*":
   version "2.0.4"
   resolved "https://registry.yarnpkg.com/@types/color-convert/-/color-convert-2.0.4.tgz#843398ae71e951dc5415d202dfd5e43108823eeb"
@@ -3409,6 +3416,11 @@
   dependencies:
     "@types/node" "*"
 
+"@types/lodash@^4.14.202":
+  version "4.17.20"
+  resolved "https://registry.yarnpkg.com/@types/lodash/-/lodash-4.17.20.tgz#1ca77361d7363432d29f5e55950d9ec1e1c6ea93"
+  integrity sha512-H3MHACvFUEiujabxhaI/ImO6gUrd8oOurg7LQtS7mbwIXA/cUqWrvBsaeJ23aZEPk1TAYkurjfMbSELfoCXlGA==
+
 "@types/minimatch@^3.0.3":
   version "3.0.5"
   resolved "https://registry.yarnpkg.com/@types/minimatch/-/minimatch-3.0.5.tgz#1001cc5e6a3704b83c236027e77f2f58ea010f40"
@@ -3431,6 +3443,13 @@
   dependencies:
     undici-types "~7.16.0"
 
+"@types/node@^20.0.0":
+  version "20.19.25"
+  resolved "https://registry.yarnpkg.com/@types/node/-/node-20.19.25.tgz#467da94a2fd966b57cc39c357247d68047611190"
+  integrity sha512-ZsJzA5thDQMSQO788d7IocwwQbI8B5OPzmqNvpf3NY/+MHDAS759Wo0gd2WQeXYt5AAAQjzcrTVC6SKCuYgoCQ==
+  dependencies:
+    undici-types "~6.21.0"
+
 "@types/normalize-package-data@^2.4.0":
   version "2.4.4"
   resolved "https://registry.yarnpkg.com/@types/normalize-package-data/-/normalize-package-data-2.4.4.tgz#56e2cc26c397c038fab0e3a917a12d5c5909e901"
@@ -12165,6 +12184,11 @@ underscore.string@~3.3.4:
     sprintf-js "^1.1.1"
     util-deprecate "^1.0.2"
 
+undici-types@~6.21.0:
+  version "6.21.0"
+  resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-6.21.0.tgz#691d00af3909be93a7faa13be61b3a5b50ef12cb"
+  integrity sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==
+
 undici-types@~7.16.0:
   version "7.16.0"
   resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.16.0.tgz#ffccdff36aea4884cbfce9a750a0580224f58a46"

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`module.exports = require('./lib/UrlUtils');`
	`2`	`+`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// @ts-nocheck`
`1`	`2`	`// Contains all path information to be used throughout the codebase.`
`2`	`3`	`const _ = require('lodash');`
`3`	`4`	`const utils = require('./utils');`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// @ts-nocheck`
`1`	`2`	`// require the whatwg compatible URL library (same behaviour in node and browser)`
`2`	`3`	`const {URL} = require('url');`
`3`	`4`	`const stripSubdirectoryFromPath = require('./strip-subdirectory-from-path');`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// @ts-nocheck`
`1`	`2`	`function escapeRegExp(string) {`
`2`	`3`	`return string.replace(/[.*+?^${}()\|[\]\\]/g, '\\$&');`
`3`	`4`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// @ts-nocheck`
`1`	`2`	`function deduplicateDoubleSlashes(url) {`
`2`	`3`	`// Preserve protocol slashes (e.g., http://, https://) and only deduplicate`
`3`	`4`	`// slashes in the path portion. The pattern (^\|[^:])\/\/+ matches double slashes`