docs-util: fixes to package renames + other options (#9671)

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

@@ -1,11 +1,11 @@
 {
   "$schema": "http://json.schemastore.org/tsconfig",
   "extends": [
-    "../../../../packages/modules/inventory-next/tsconfig.json"
+    "../../../../packages/modules/inventory/tsconfig.json"
   ],
-  "include": ["../../../../packages/modules/inventory-next/src"],
+  "include": ["../../../../packages/modules/inventory/src"],
   "exclude": [
-    "../../../../packages/modules/inventory-next/dist", 
+    "../../../../packages/modules/inventory/dist", 
-    "../../../../packages/modules/inventory-next/node_modules"
+    "../../../../packages/modules/inventory/node_modules"
   ]
 }

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

@@ -1,11 +1,11 @@
 {
   "$schema": "http://json.schemastore.org/tsconfig",
   "extends": [
-    "../../../../packages/modules/stock-location-next/tsconfig.json"
+    "../../../../packages/modules/stock-location/tsconfig.json"
   ],
-  "include": ["../../../../packages/modules/stock-location-next/src"],
+  "include": ["../../../../packages/modules/stock-location/src"],
   "exclude": [
-    "../../../../packages/modules/stock-location-next/dist", 
+    "../../../../packages/modules/stock-location/dist", 
-    "../../../../packages/modules/stock-location-next/node_modules"
+    "../../../../packages/modules/stock-location/node_modules"
   ]
 }

www/utils/packages/typedoc-generate-references/src/commands/generate.ts

@@ -40,14 +40,22 @@ export default async function generate(
           outputType: "json",
         })
 
+        const modelReferenceName = `${referenceName}-models`
+
         const modelOptions = getModelOptions({
           moduleName: referenceName,
+          typedocOptions: Object.hasOwn(
+            customModulesOptions,
+            modelReferenceName
+          )
+            ? customModulesOptions[modelReferenceName]
+            : undefined,
         })
 
         try {
           await generateReference({
             options: modelOptions,
-            referenceName: `${referenceName}-models`,
+            referenceName: modelReferenceName,
             outputType: "json",
           })
         } catch (e) {

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

@@ -58,6 +58,7 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     tsConfigName: "js-sdk.json",
     name: "js-sdk",
     enableInternalResolve: true,
+    exclude: [...(baseOptions.exclude || []), "**/dist/**"],
   }),
   "helper-steps": getOptions({
     entryPointPath: "packages/core/core-flows/src/common/index.ts",

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/js-sdk.ts

@@ -37,7 +37,7 @@ const jsSdkOptions: FormattingOptionsType = {
     reflectionDescription:
       "This documentation provides a reference to the `sdk.store.{{alias}}` set of methods used to send requests to Medusa's Store API routes.",
   },
-  "^js_sdk/store/classes/.*Admin": {
+  "^js_sdk/admin/classes/.*Admin": {
     frontmatterData: {
       slug: "/references/js-sdk/admin",
     },
@@ -60,7 +60,7 @@ const jsSdkOptions: FormattingOptionsType = {
     reflectionDescription:
       "This documentation provides a reference to the `sdk.admin.{{alias}}` set of methods used to send requests to Medusa's Admin API routes.",
   },
-  "^js_sdk/store/classes/.*Auth": {
+  "^js_sdk/auth/classes/.*Auth": {
     frontmatterData: {
       slug: "/references/js-sdk/auth",
     },

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

@@ -1,4 +1,4 @@
-import { TypeDocOptions } from "typedoc"
+import { ReflectionKind, TypeDocOptions } from "typedoc"
 import { baseOptions } from "./base-options.js"
 import path from "path"
 import { jsonOutputPathPrefix, rootPathPrefix } from "./general.js"
@@ -8,7 +8,7 @@ import {
   customModuleTitles,
   dmlModules,
 } from "./references-details.js"
-import { FormattingOptionType } from "types"
+import { AllowedProjectDocumentsOption, FormattingOptionType } from "types"
 import { kebabToCamel, kebabToPascal, kebabToSnake, kebabToTitle } from "utils"
 import baseSectionsOptions from "./base-section-options.js"
 import mergerCustomOptions from "./merger-custom-options/index.js"
@@ -17,6 +17,39 @@ import {
   getNamespaceNames,
 } from "../utils/get-namespaces.js"
 
+const commonAllowedDocuments = {
+  [ReflectionKind.Variable]: true,
+  [ReflectionKind.Function]: true,
+  [ReflectionKind.Method]: true,
+}
+const allowedProjectDocuments: AllowedProjectDocumentsOption = {
+  dml: commonAllowedDocuments,
+  "helper-steps": commonAllowedDocuments,
+  workflows: commonAllowedDocuments,
+  "js-sdk": {
+    [ReflectionKind.Method]: true,
+    [ReflectionKind.Property]: true,
+  },
+}
+
+modules.forEach((module) => {
+  allowedProjectDocuments[module] = {
+    ...commonAllowedDocuments,
+  }
+})
+
+dmlModules.forEach((module) => {
+  allowedProjectDocuments[`${module}-models`] = {
+    ...commonAllowedDocuments,
+  }
+})
+
+getNamespaceNames(getCoreFlowNamespaces()).forEach((namespace) => {
+  allowedProjectDocuments[namespace] = {
+    ...commonAllowedDocuments,
+  }
+})
+
 const mergerOptions: Partial<TypeDocOptions> = {
   ...baseOptions,
   entryPoints: [path.join(jsonOutputPathPrefix, "*.json")],
@@ -33,17 +66,8 @@ const mergerOptions: Partial<TypeDocOptions> = {
   objectLiteralTypeDeclarationStyle: "component",
   mdxOutput: true,
   maxLevel: 3,
-  allReflectionsHaveOwnDocument: [
+  // @ts-expect-error this is due to a typing issue in typedoc
-    ...modules,
+  allowedProjectDocuments,
-    ...dmlModules.map((module) => `${module}-models`),
-    "dml",
-    "helper-steps",
-    "workflows",
-  ],
-  allPropertyReflectionsHaveOwnDocument: ["js-sdk"],
-  allReflectionsHaveOwnDocumentInNamespace: [
-    ...getNamespaceNames(getCoreFlowNamespaces()),
-  ],
   formatting: {
     "*": {
       showCommentsAsHeader: true,

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

@@ -22,6 +22,16 @@ export const customModulesOptions: Record<string, Partial<TypeDocOptions>> = {
       "packages/core/types/src/stock-location/service.ts"
     ),
   },
+  "inventory-next-models": {
+    entryPoints: getEntryPoints(
+      "packages/modules/inventory/src/models/index.ts"
+    ),
+  },
+  "stock-location-next-models": {
+    entryPoints: getEntryPoints(
+      "packages/modules/stock-location/src/models/index.ts"
+    ),
+  },
 }
 
 // a list of modules that now support DML

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

@@ -33,13 +33,6 @@ export function load(app: Application) {
     defaultValue: false,
   })
 
-  app.options.addDeclaration({
-    help: "[Markdown Plugin] Specify module names where all reflections are outputted into seperate files.",
-    name: "allReflectionsHaveOwnDocument",
-    type: ParameterType.Array,
-    defaultValue: [],
-  })
-
   app.options.addDeclaration({
     help: "[Markdown Plugin] Specify module names where property reflections are outputted into seperate files.",
     name: "allPropertyReflectionsHaveOwnDocument",
@@ -48,9 +41,9 @@ export function load(app: Application) {
   })
 
   app.options.addDeclaration({
-    help: "[Markdown Plugin] Specify namespace names where all reflections are outputted into seperate files.",
+    help: "[Markdown Plugin] Specify for each project / module the allowed document types",
-    name: "allReflectionsHaveOwnDocumentInNamespace",
+    name: "allowedProjectDocuments",
-    type: ParameterType.Array,
+    type: ParameterType.Mixed,
     defaultValue: [],
   })
 

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

@@ -14,13 +14,15 @@ export default function (theme: MarkdownTheme) {
     function (this: ProjectReflection | DeclarationReflection) {
       const md: string[] = []
 
-      const { hideInPageTOC, allReflectionsHaveOwnDocumentInNamespace } = theme
+      const { hideInPageTOC } = theme
       const { hideTocHeaders, reflectionGroupRename = {} } =
         theme.getFormattingOptionsForLocation()
 
       const isNamespaceVisible =
         this.kind === ReflectionKind.Namespace &&
-        allReflectionsHaveOwnDocumentInNamespace.includes(this.name)
+        theme.getMappings(this as DeclarationReflection)[
+          ReflectionKind.Namespace
+        ]
       const isVisible =
         isNamespaceVisible ||
         this.groups?.some((group) => {

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

@@ -22,6 +22,7 @@ import {
 import { formatContents } from "./utils"
 
 import type {
+  AllowedProjectDocumentsOption,
   FormattingOptionType,
   FormattingOptionsType,
   ParameterStyle,
@@ -29,9 +30,8 @@ import type {
 import { Mapping } from "./types"
 
 export class MarkdownTheme extends Theme {
-  allReflectionsHaveOwnDocument!: string[]
   allPropertyReflectionsHaveOwnDocument!: string[]
-  allReflectionsHaveOwnDocumentInNamespace: string[]
+  allowedProjectDocuments: AllowedProjectDocumentsOption
   entryDocument: string
   entryPoints!: string[]
   filenameSeparator!: string
@@ -64,14 +64,12 @@ export class MarkdownTheme extends Theme {
   constructor(renderer: Renderer) {
     super(renderer)
 
-    // prettier-ignore
-    this.allReflectionsHaveOwnDocument = this.getOption("allReflectionsHaveOwnDocument") as string[]
     this.allPropertyReflectionsHaveOwnDocument = this.getOption(
       "allPropertyReflectionsHaveOwnDocument"
     ) as string[]
-    this.allReflectionsHaveOwnDocumentInNamespace = this.getOption(
+    this.allowedProjectDocuments = this.getOption(
-      "allReflectionsHaveOwnDocumentInNamespace"
+      "allowedProjectDocuments"
-    ) as string[]
+    ) as AllowedProjectDocumentsOption
     this.entryDocument = this.getOption("entryDocument") as string
     this.entryPoints = this.getOption("entryPoints") as string[]
     this.filenameSeparator = this.getOption("filenameSeparator") as string
@@ -338,33 +336,52 @@ export class MarkdownTheme extends Theme {
     return parents
   }
 
-  getAllReflectionsHaveOwnDocument(
+  getAllowedReflectionDocuments(reflection: DeclarationReflection) {
-    reflection: DeclarationReflection,
+    const documents = {
-    checkProperties?: boolean
+      [ReflectionKind.Module]: true,
-  ): boolean {
+      [ReflectionKind.Namespace]: true,
+      [ReflectionKind.Enum]: true,
+      [ReflectionKind.Class]: true,
+      [ReflectionKind.Interface]: true,
+      [ReflectionKind.TypeAlias]: true,
+      [ReflectionKind.Variable]: false,
+      [ReflectionKind.Function]: false,
+      [ReflectionKind.Method]: false,
+      [ReflectionKind.Property]: false,
+    }
+
+    let options: Record<ReflectionKind, boolean> | undefined
+
     const moduleParents = this.getParentsOfKind(
       reflection,
       ReflectionKind.Module
-    )
+    ).reverse() // projects come last, this changes the direction to give projects higher priority
     const namespaceParents = this.getParentsOfKind(
       reflection,
       ReflectionKind.Namespace
     )
 
-    if (checkProperties) {
+    moduleParents.some((parent) => {
-      return moduleParents.some((parent) =>
+      if (!Object.hasOwn(this.allowedProjectDocuments, parent.name)) {
-        this.allPropertyReflectionsHaveOwnDocument.includes(parent.name)
+        return false
-      )
+      }
-    }
 
-    return (
+      options = this.allowedProjectDocuments[parent.name]
-      moduleParents.some((parent) =>
+      return true
-        this.allReflectionsHaveOwnDocument.includes(parent.name)
+    }) ||
-      ) ||
+      namespaceParents.some((parent) => {
-      namespaceParents.some((parent) =>
+        if (!Object.hasOwn(this.allowedProjectDocuments, parent.name)) {
-        this.allReflectionsHaveOwnDocumentInNamespace.includes(parent.name)
+          return false
-      )
+        }
-    )
+
+        options = this.allowedProjectDocuments[parent.name]
+        return true
+      })
+
+    return {
+      ...documents,
+      ...(options || {}),
+    }
   }
 
   getFileNameSeparator(pathPrefix: string): string {
@@ -376,8 +393,11 @@ export class MarkdownTheme extends Theme {
     reflection: DeclarationReflection,
     directoryPrefix?: string
   ): Mapping[] {
-    return [
+    const allowedDocuments = this.getAllowedReflectionDocuments(reflection)
-      {
+    const mappings: Mapping[] = []
+
+    if (allowedDocuments[ReflectionKind.Module]) {
+      mappings.push({
         kind: [ReflectionKind.Module],
         modifiers: {
           has: [],
@@ -386,8 +406,10 @@ export class MarkdownTheme extends Theme {
         isLeaf: false,
         directory: path.join(directoryPrefix || "", "modules"),
         template: this.getReflectionTemplate(),
-      },
+      })
-      {
+    }
+    if (allowedDocuments[ReflectionKind.Namespace]) {
+      mappings.push({
         kind: [ReflectionKind.Namespace],
         modifiers: {
           has: [],
@@ -396,8 +418,10 @@ export class MarkdownTheme extends Theme {
         isLeaf: false,
         directory: path.join(directoryPrefix || ""),
         template: this.getReflectionTemplate(),
-      },
+      })
-      {
+    }
+    if (allowedDocuments[ReflectionKind.Enum]) {
+      mappings.push({
         kind: [ReflectionKind.Enum],
         modifiers: {
           has: [],
@@ -406,8 +430,10 @@ export class MarkdownTheme extends Theme {
         isLeaf: false,
         directory: path.join(directoryPrefix || "", "enums"),
         template: this.getReflectionTemplate(),
-      },
+      })
-      {
+    }
+    if (allowedDocuments[ReflectionKind.Class]) {
+      mappings.push({
         kind: [ReflectionKind.Class],
         modifiers: {
           has: [],
@@ -416,8 +442,10 @@ export class MarkdownTheme extends Theme {
         isLeaf: false,
         directory: path.join(directoryPrefix || "", "classes"),
         template: this.getReflectionTemplate(),
-      },
+      })
-      {
+    }
+    if (allowedDocuments[ReflectionKind.Interface]) {
+      mappings.push({
         kind: [ReflectionKind.Interface],
         modifiers: {
           has: [],
@@ -426,8 +454,11 @@ export class MarkdownTheme extends Theme {
         isLeaf: false,
         directory: path.join(directoryPrefix || "", "interfaces"),
         template: this.getReflectionTemplate(),
-      },
+      })
-      {
+    }
+
+    if (allowedDocuments[ReflectionKind.TypeAlias]) {
+      mappings.push({
         kind: [ReflectionKind.TypeAlias],
         modifiers: {
           has: [],
@@ -436,56 +467,59 @@ export class MarkdownTheme extends Theme {
         isLeaf: true,
         directory: path.join(directoryPrefix || "", "types"),
         template: this.getReflectionMemberTemplate(),
-      },
+      })
-      ...(this.getAllReflectionsHaveOwnDocument(reflection)
+    }
-        ? [
+
-            {
+    if (allowedDocuments[ReflectionKind.Variable]) {
-              kind: [ReflectionKind.Variable],
+      mappings.push({
-              modifiers: {
+        kind: [ReflectionKind.Variable],
-                has: [],
+        modifiers: {
-                not: [],
+          has: [],
-              },
+          not: [],
-              isLeaf: true,
+        },
-              directory: path.join(directoryPrefix || "", "variables"),
+        isLeaf: true,
-              template: this.getReflectionMemberTemplate(),
+        directory: path.join(directoryPrefix || "", "variables"),
-            },
+        template: this.getReflectionMemberTemplate(),
-            {
+      })
-              kind: [ReflectionKind.Function],
+    }
-              modifiers: {
+    if (allowedDocuments[ReflectionKind.Function]) {
-                has: [],
+      mappings.push({
-                not: [],
+        kind: [ReflectionKind.Function],
-              },
+        modifiers: {
-              isLeaf: true,
+          has: [],
-              directory: path.join(directoryPrefix || "", "functions"),
+          not: [],
-              template: this.getReflectionMemberTemplate(),
+        },
-            },
+        isLeaf: true,
-            {
+        directory: path.join(directoryPrefix || "", "functions"),
-              kind: [ReflectionKind.Method],
+        template: this.getReflectionMemberTemplate(),
-              modifiers: {
+      })
-                has: [],
+    }
-                not: [],
+    if (allowedDocuments[ReflectionKind.Method]) {
-              },
+      mappings.push({
-              isLeaf: true,
+        kind: [ReflectionKind.Method],
-              directory: path.join(directoryPrefix || "", "methods"),
+        modifiers: {
-              template: this.getReflectionMemberTemplate(),
+          has: [],
-            },
+          not: [],
-          ]
+        },
-        : []),
+        isLeaf: true,
-      ...(this.getAllReflectionsHaveOwnDocument(reflection, true)
+        directory: path.join(directoryPrefix || "", "methods"),
-        ? [
+        template: this.getReflectionMemberTemplate(),
-            {
+      })
-              kind: [ReflectionKind.Property],
+    }
-              modifiers: {
+    if (allowedDocuments[ReflectionKind.Property]) {
-                has: [],
+      mappings.push({
-                not: [],
+        kind: [ReflectionKind.Property],
-              },
+        modifiers: {
-              isLeaf: true,
+          has: [],
-              directory: path.join(directoryPrefix || "", "properties"),
+          not: [],
-              template: this.getReflectionMemberTemplate(),
+        },
-            },
+        isLeaf: true,
-          ]
+        directory: path.join(directoryPrefix || "", "properties"),
-        : []),
+        template: this.getReflectionMemberTemplate(),
-    ]
+      })
+    }
+
+    return mappings
   }
 
   /**

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

@@ -86,6 +86,10 @@ export type FormattingOptionType = {
   workflowDiagramComponent?: string
 }
 
+export type AllowedProjectDocumentsOption = {
+  [k: string]: Record<number, boolean>
+}
+
 export declare module "typedoc" {
   declare interface TypeDocOptionMap {
     /**
@@ -136,14 +140,7 @@ export declare module "typedoc" {
      * @defaultValue false
      */
     namedAnchors: boolean
-    /**
+    allowedProjectDocuments: AllowedProjectDocumentsOption
-     * [Markdown Plugin] Specify module names where all reflections are outputted into seperate files.
-     */
-    allReflectionsHaveOwnDocument: string[]
-    /**
-     * [Markdown Plugin] Specify module names where property reflections are outputted into seperate files.
-     */
-    allPropertyReflectionsHaveOwnDocument: string[]
     /**
      * [Markdown Plugin] Separator used to format filenames.
      * @defaultValue "."