docs-util: Upgrade typedoc to 0.26 (#7853)

Upgrade typedoc to v0.26 + make changes based on the update

Note: This update produces an error when generating model references when the models use the `createPsqlIndexStatementHelper` decorator. As this isn't a breaking error, and as we'll move to DML in the future, it's not necessary to spend time on a fix.

www/utils/packages/docblock-generator/package.json

@@ -27,7 +27,7 @@
     "pluralize": "^8.0.0",
     "prettier": "^3.2.4",
     "ts-node": "^10.9.1",
-    "typescript": "5.2",
+    "typescript": "5.5",
     "utils": "*",
     "yaml": "^2.3.4"
   },

www/utils/packages/react-docs-generator/package.json

@@ -23,9 +23,9 @@
     "react-docgen": "^7.0.1",
     "resolve": "^1.22.8",
     "ts-node": "^10.9.1",
-    "typedoc": "^0.25.12",
+    "typedoc": "^0.26.2",
     "typedoc-plugin-custom": "*",
-    "typescript": "5.2",
+    "typescript": "5.5",
     "utils": "*"
   },
   "devDependencies": {

www/utils/packages/react-docs-generator/tsconfig.json

@@ -11,7 +11,7 @@
     "skipLibCheck": true,
     "resolveJsonModule": true,
   },
-  "include": ["src", "../typedoc-plugin-custom/src/types"],
+  "include": ["src"],
   "ts-node": {
     "esm": true,
     "experimentalSpecifierResolution": "node",

www/utils/packages/scripts/freshness-check.ts

@@ -17,7 +17,16 @@ const linearClient = new LinearClient({
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
-const repoPath = path.join(__dirname, "..", "..", "..", "apps", "book", "app")
+const repoPath = path.join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "..",
+  "apps",
+  "book",
+  "app"
+)
 let freshnessCheckLabelId = ""
 let documentationTeamId = ""
 

www/utils/packages/scripts/package.json

@@ -7,9 +7,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "generate:announcement": "ts-node ./doc-change-release.ts",
-    "check:freshness": "ts-node ./freshness-check.ts",
-    "generate:message": "ts-node ./get-generate-diff-message.ts",
+    "check:freshness": "node ./dist/freshness-check.js",
+    "generate:message": "node ./dist/get-generate-diff-message.js",
     "check:release-commit": "node ./dist/check-release-commit.js",
     "generate:changeset": "node ./dist/run-changeset.js",
     "check:pr-files-count": "node ./dist/check-pr-files-count.js"
@@ -25,7 +24,7 @@
     "glob": "^10.3.10",
     "randomcolor": "^0.6.2",
     "ts-node": "^10.9.1",
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "devDependencies": {
     "@types/randomcolor": "^0.5.8"

www/utils/packages/scripts/run-changeset.ts

@@ -18,7 +18,7 @@ async function main() {
 
   // run changeset
   await promiseExec(`yarn changeset --empty`, {
-    cwd: path.resolve("..", "..", ".."),
+    cwd: path.resolve("..", "..", "..", ".."),
   })
   console.log("Generated changeset.")
 }

www/utils/packages/typedoc-config/inventory.json

@@ -1,6 +0,0 @@
-{
-  "$schema": "http://json.schemastore.org/tsconfig",
-  "extends": [
-    "../../../../packages/modules/inventory/tsconfig.json"
-  ]
-}

www/utils/packages/typedoc-config/stock-location.json

@@ -1,6 +0,0 @@
-{
-  "$schema": "http://json.schemastore.org/tsconfig",
-  "extends": [
-    "../../../../packages/modules/stock-location/tsconfig.json"
-  ]
-}

www/utils/packages/typedoc-generate-references/package.json

@@ -21,16 +21,17 @@
     "dotenv": "^16.3.1",
     "randomcolor": "^0.6.2",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.26.2",
     "typedoc-plugin-custom": "*",
     "typedoc-plugin-markdown-medusa": "*",
     "typedoc-plugin-rename-defaults": "^0.7.0",
     "types": "*",
-    "typescript": "5.2",
+    "typescript": "5.5",
     "utils": "*",
     "yaml": "^2.3.4"
   },
   "peerDependencies": {
-    "typedoc": "0.25.x"
+    "typedoc": "0.26.x"
   },
   "devDependencies": {
     "@types/node": "^20.9.4",

www/utils/packages/typedoc-generate-references/src/constants/references-details.ts

@@ -2,8 +2,8 @@ import { TypeDocOptions } from "typedoc"
 import { getEntryPoints } from "../utils/get-options.js"
 
 export const customModuleServiceNames: Record<string, string> = {
-  "inventory-next": "IInventoryServiceNext",
-  "stock-location-next": "IStockLocationServiceNext",
+  "inventory-next": "IInventoryService",
+  "stock-location-next": "IStockLocationService",
 }
 
 // if any module requires a custom formatting to their title representation,
@@ -15,13 +15,11 @@ export const customModuleTitles: Record<string, string> = {
 // if any module requires custom options, they're added to this object
 export const customModulesOptions: Record<string, Partial<TypeDocOptions>> = {
   "inventory-next": {
-    entryPoints: getEntryPoints(
-      "packages/core/types/src/inventory/service-next.ts"
-    ),
+    entryPoints: getEntryPoints("packages/core/types/src/inventory/service.ts"),
   },
   "stock-location-next": {
     entryPoints: getEntryPoints(
-      "packages/core/types/src/stock-location/service-next.ts"
+      "packages/core/types/src/stock-location/service.ts"
     ),
   },
 }

www/utils/packages/typedoc-plugin-custom/package.json

@@ -19,12 +19,12 @@
     "lint": "eslint --ext .ts src"
   },
   "peerDependencies": {
-    "typedoc": "0.25.x"
+    "typedoc": "0.26.x"
   },
   "devDependencies": {
     "@types/eslint": "^8.56.6",
     "@types/node": "^16.11.10",
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "keywords": [
     "typedocplugin",

www/utils/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts

@@ -1,4 +1,3 @@
-import { ok } from "assert"
 import {
   Application,
   Context,
@@ -10,8 +9,19 @@ import {
   DeclarationReflection,
   ProjectReflection,
   ParameterType,
+  ContainerReflection,
 } from "typedoc"
 
+declare module "typedoc" {
+  export interface Reflection {
+    [InternalModule]?: boolean
+  }
+}
+
+const ModuleLike: ReflectionKind =
+  ReflectionKind.Project | ReflectionKind.Module
+const InternalModule = Symbol()
+
 export function load(app: Application) {
   app.options.addDeclaration({
     name: "internalModule",
@@ -32,19 +42,18 @@ export function load(app: Application) {
     defaultValue: false,
   })
 
-  let activeReflection: Reflection | undefined
   let referencedSymbols = new Map<ts.Program, Set<ts.Symbol>>()
-  let symbolToActiveRefl = new Map<ts.Symbol, Reflection>()
+  let symbolToOwningModule = new Map<ts.Symbol, Reflection>()
   let knownPrograms = new Map<Reflection, ts.Program>()
   let checkedVariableSymbols = false
 
   function discoverMissingExports(
+    owningModule: Reflection,
     context: Context,
     program: ts.Program
   ): Set<ts.Symbol> {
     // An export is missing if if was referenced
     // Is not contained in the documented
-    // And is "owned" by the active reflection
     const referenced = referencedSymbols.get(program) || new Set()
     const ownedByOther = new Set<ts.Symbol>()
     referencedSymbols.set(program, ownedByOther)
@@ -52,7 +61,7 @@ export function load(app: Application) {
     for (const s of [...referenced]) {
       if (context.project.getReflectionFromSymbol(s)) {
         referenced.delete(s)
-      } else if (symbolToActiveRefl.get(s) !== activeReflection) {
+      } else if (symbolToOwningModule.get(s) !== owningModule) {
         referenced.delete(s)
         ownedByOther.add(s)
       }
@@ -67,9 +76,9 @@ export function load(app: Application) {
     if (!app.options.getValue("enableInternalResolve")) {
       return origCreateSymbolReference.call(this, symbol, context, name)
     }
-    ok(activeReflection, "active reflection has not been set")
+    const owningModule = getOwningModule(context)
     const set = referencedSymbols.get(context.program)
-    symbolToActiveRefl.set(symbol, activeReflection)
+    symbolToOwningModule.set(symbol, owningModule)
     if (set) {
       set.add(symbol)
     } else {
@@ -84,9 +93,14 @@ export function load(app: Application) {
       if (!app.options.getValue("enableInternalResolve")) {
         return
       }
-      if (refl.kindOf(ReflectionKind.Project | ReflectionKind.Module)) {
+      // TypeDoc 0.26 doesn't fire EVENT_CREATE_DECLARATION for project
+      // We need to ensure the project has a program attached to it, so
+      // do that when the first declaration is created.
+      if (knownPrograms.size === 0) {
+        knownPrograms.set(refl.project, context.program)
+      }
+      if (refl.kindOf(ModuleLike)) {
         knownPrograms.set(refl, context.program)
-        activeReflection = refl
       }
     }
   )
@@ -147,13 +161,11 @@ export function load(app: Application) {
       }
 
       for (const mod of modules) {
-        activeReflection = mod
-
         const program = knownPrograms.get(mod)
         if (!program) {
           continue
         }
-        let missing = discoverMissingExports(context, program)
+        let missing = discoverMissingExports(mod, context, program)
         if (!missing || !missing.size) {
           continue
         }
@@ -178,7 +190,7 @@ export function load(app: Application) {
             tried.add(s)
           }
 
-          missing = discoverMissingExports(context, program)
+          missing = discoverMissingExports(mod, context, program)
           for (const s of tried) {
             missing.delete(s)
           }
@@ -192,9 +204,11 @@ export function load(app: Application) {
           }
         })
 
-        // All the missing symbols were excluded, so get rid of our namespace.
-        if (internalNs && !internalNs.children?.length) {
-          context.project.removeReflection(internalNs)
+        if (
+          internalContext.scope[InternalModule] &&
+          !(internalContext.scope as ContainerReflection).children?.length
+        ) {
+          context.project.removeReflection(internalContext.scope)
         }
 
         context.setActiveProgram(void 0)
@@ -202,21 +216,34 @@ export function load(app: Application) {
 
       knownPrograms.clear()
       referencedSymbols.clear()
-      symbolToActiveRefl.clear()
     },
-    void 0,
-    1e9
+    void 0
   )
 
   app.converter.on(Converter.EVENT_END, () => {
     ReferenceType.createSymbolReference = origCreateSymbolReference
-    activeReflection = undefined
     referencedSymbols = new Map()
-    symbolToActiveRefl = new Map()
+    symbolToOwningModule = new Map()
     knownPrograms = new Map()
     checkedVariableSymbols = false
   })
 }
+
+function getOwningModule(context: Context): Reflection {
+  let refl = context.scope
+  // Go up the reflection hierarchy until we get to a module
+  while (!refl.kindOf(ModuleLike)) {
+    refl = refl.parent!
+  }
+
+  // The <internal> module cannot be an owning module.
+  if (refl[InternalModule]) {
+    return refl.parent!
+  }
+
+  return refl
+}
+
 function shouldConvertSymbol(symbol: ts.Symbol, checker: ts.TypeChecker) {
   while (symbol.flags & ts.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol)

www/utils/packages/typedoc-plugin-markdown-medusa/package.json

@@ -18,13 +18,14 @@
     "lint": "eslint --ext .ts src"
   },
   "peerDependencies": {
-    "typedoc": "0.25.x"
+    "typedoc": "0.26.x"
   },
   "devDependencies": {
     "@types/node": "^16.11.10",
     "copyfiles": "^2.4.1",
+    "typedoc": "^0.26.2",
     "types": "*",
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "keywords": [
     "typedocplugin",

www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -94,7 +94,7 @@ export function registerPartials() {
 
 export function registerHelpers(theme: MarkdownTheme) {
   breadcrumbsHelper(theme)
-  commentHelper(theme)
+  commentHelper()
   commentsHelper()
   declarationTitleHelper(theme)
   escapeHelper()

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comment.ts

@@ -1,11 +1,9 @@
 import * as fs from "fs"
 import * as Handlebars from "handlebars"
-import * as Path from "path"
 import { CommentDisplayPart } from "typedoc/dist/lib/models/comments/comment"
-import { MarkdownTheme } from "../../theme"
 import { escapeChars } from "utils"
 
-export default function (theme: MarkdownTheme) {
+export default function () {
   Handlebars.registerHelper("comment", function (parts: CommentDisplayPart[]) {
     const result: string[] = []
     for (const part of parts) {
@@ -51,43 +49,10 @@ export default function (theme: MarkdownTheme) {
       }
     }
 
-    return parseMarkdown(result.join(""), theme)
+    return result.join("")
   })
 }
 
-function parseMarkdown(text: string, theme: MarkdownTheme) {
-  const includePattern = /\[\[include:([^\]]+?)\]\]/g
-  const mediaPattern = /media:\/\/([^ ")\]}]+)/g
-
-  if (theme.includes) {
-    text = text.replace(includePattern, (_match, path) => {
-      path = Path.join(theme.includes!, path.trim())
-      if (fs.existsSync(path) && fs.statSync(path).isFile()) {
-        const contents = readFile(path)
-        return contents
-      } else {
-        theme.application.logger.warn("Could not find file to include: " + path)
-        return ""
-      }
-    })
-  }
-
-  if (theme.mediaDirectory) {
-    text = text.replace(mediaPattern, (match: string, path: string) => {
-      const fileName = Path.join(theme.mediaDirectory!, path)
-
-      if (fs.existsSync(fileName) && fs.statSync(fileName).isFile()) {
-        return Handlebars.helpers.relativeURL("media") + "/" + path
-      } else {
-        theme.application.logger.warn("Could not find media file: " + fileName)
-        return match
-      }
-    })
-  }
-
-  return text
-}
-
 /**
  * Load the given file and return its contents.
  *

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/declaration-title.ts

@@ -34,8 +34,11 @@ export default function (theme: MarkdownTheme) {
         )
       }
 
-      if (this.flags && this.flags.length > 0 && !this.flags.isRest) {
-        md.push(" " + this.flags.map((flag) => `\`${flag}\``).join(" "))
+      const flags = this.flags.getFlagStrings(
+        theme.application.internationalization
+      )
+      if (flags.length > 0 && !this.flags.isRest) {
+        md.push(" " + flags.map((flag) => `\`${flag}\``).join(" "))
       }
       md.push(
         `${this.flags.isRest ? "... " : ""} **${escapeChars(this.name)}**`

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts

@@ -38,8 +38,11 @@ export default function (theme: MarkdownTheme) {
         md.push(`${memberSymbol(this)} `)
       }
 
-      if (this.parent && this.parent.flags?.length > 0) {
-        md.push(this.parent.flags.join(" ") + " ")
+      const parentFlags = this.parent.flags.getFlagStrings(
+        theme.application.internationalization
+      )
+      if (this.parent && parentFlags.length > 0) {
+        md.push(parentFlags.join(" ") + " ")
       }
 
       if (accessor) {

www/utils/packages/typedoc-plugin-markdown-medusa/src/theme.ts

@@ -38,9 +38,7 @@ export class MarkdownTheme extends Theme {
   hideInPageTOC!: boolean
   hidePageTitle!: boolean
   hideMembersSymbol!: boolean
-  includes!: string
   indexTitle!: string
-  mediaDirectory!: string
   namedAnchors!: boolean
   readme!: string
   out!: string
@@ -77,9 +75,7 @@ export class MarkdownTheme extends Theme {
     this.hideInPageTOC = this.getOption("hideInPageTOC") as boolean
     this.hidePageTitle = this.getOption("hidePageTitle") as boolean
     this.hideMembersSymbol = this.getOption("hideMembersSymbol") as boolean
-    this.includes = this.getOption("includes") as string
     this.indexTitle = this.getOption("indexTitle") as string
-    this.mediaDirectory = this.getOption("media") as string
     this.namedAnchors = this.getOption("namedAnchors") as boolean
     this.readme = this.getOption("readme") as string
     this.out = this.getOption("out") as string
@@ -98,13 +94,11 @@ export class MarkdownTheme extends Theme {
     this.outputModules = this.getOption("outputModules") as boolean
     MarkdownTheme.MAX_LEVEL = this.getOption("maxLevel") as number
 
-    this.listenTo(this.owner, {
-      [RendererEvent.BEGIN]: this.onBeginRenderer,
-      [PageEvent.BEGIN]: this.onBeginPage,
-    })
-
     registerPartials()
     registerHelpers(this)
+
+    renderer.on(RendererEvent.BEGIN, this.onBeginRenderer.bind(this))
+    renderer.on(PageEvent.BEGIN, this.onBeginPage.bind(this))
   }
 
   render(

www/utils/packages/types/lib/index.d.ts

@@ -120,11 +120,13 @@ export declare module "typedoc" {
      */
     hideBreadcrumbs: boolean
     /**
-     * [Markdown Plugin] Specifies the base path that all links to be served from. If omitted all urls will be relative.
+     * [Markdown Plugin] Specifies the base path that all links to be served from.
+     * If omitted all urls will be relative.
      */
     publicPath: string
     /**
-     * [Markdown Plugin] Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids. Should be set for Bitbucket Server docs.
+     * [Markdown Plugin] Use HTML named anchors as fragment identifiers for engines
+     * that do not automatically assign header ids. Should be set for Bitbucket Server docs.
      * @defaultValue false
      */
     namedAnchors: boolean

www/utils/packages/types/package.json

@@ -11,10 +11,10 @@
     "lint": "eslint --ext .ts src"
   },
   "peerDependencies": {
-    "typedoc": "0.25.x"
+    "typedoc": "0.26.x"
   },
   "devDependencies": {
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "version": "0.0.0",
   "main": "./lib/index.js",

www/utils/packages/utils/package.json

@@ -14,11 +14,11 @@
     "clean": "rimraf dist"
   },
   "peerDependencies": {
-    "typedoc": "0.25.x"
+    "typedoc": "0.26.x"
   },
   "devDependencies": {
     "@types/node": "^16.11.10",
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "dependencies": {
     "octokit": "^3.1.2",

www/utils/packages/utils/src/get-type-str.ts

@@ -187,9 +187,9 @@ export function getDeclarationType({
 }: TypeOptions<DeclarationReflection>): string {
   escape = getShouldEscape(wrapBackticks, escape)
 
-  if (model.indexSignature || model.children) {
+  if (model.indexSignatures || model.children) {
     let indexSignature = ""
-    const declarationIndexSignature = model.indexSignature
+    const declarationIndexSignature = model.indexSignatures?.[0]
     if (declarationIndexSignature) {
       const key = declarationIndexSignature.parameters
         ? declarationIndexSignature.parameters.map(

www/utils/packages/workflows-diagrams-generator/package.json

@@ -21,7 +21,7 @@
     "@mermaid-js/mermaid-cli": "^10.6.1",
     "commander": "^11.1.0",
     "ts-node": "^10.9.1",
-    "typescript": "5.2"
+    "typescript": "5.5"
   },
   "devDependencies": {
     "@types/node": "^20.9.4"