feat: enhance tsed-flow-package-symbols with Markdown support, error handling, and schema updates

Romakita · Romakita · commit c590e66fc49b · 2025-11-15T12:47:51.000+01:00
Added support for a `markdown_url` to enrich package symbols with Markdown-based documentation. Improved error handling in migration logic for presets and introduced several schema enhancements, including new fields in the `package_symbols` collection and updated display options.
diff --git a/extensions/tsed-flow-package-symbols/src/api.ts b/extensions/tsed-flow-package-symbols/src/api.ts
@@ -1,7 +1,7 @@
 import { defineOperationApi } from "@directus/extensions-sdk";
 import { inject } from "@tsed/di";
 import { wrapOperation } from "@tsed-cms/infra/bootstrap/directus.js";
-import type { Package, PackageSymbol } from "@tsed-cms/infra/directus/interfaces/DirectusSchema.js";
+import type { Package } from "@tsed-cms/infra/directus/interfaces/DirectusSchema.js";
 import { HttpClient } from "@tsed-cms/infra/http/HttpClient.js";
 import { PackageSymbolsService } from "@tsed-cms/usecases/package-symbols/PackageSymbolsService.js";
 import { PackagesService } from "@tsed-cms/usecases/packages/PackagesService.js";
@@ -10,6 +10,7 @@ import { type ApiJsonModule, type ApiJsonResponse, mapApiSymbolToDirectus } from
 
 export type Options = {
   url?: string;
+  markdown_url?: string;
 };
 
 async function ensurePackage(pkgName: string): Promise<Package> {
@@ -27,9 +28,10 @@ async function ensurePackage(pkgName: string): Promise<Package> {
 
 export default defineOperationApi<Options>({
   id: "tsed-flow-package-symbols",
-  handler: wrapOperation(async (opts, _context) => {
+  handler: wrapOperation(async (opts) => {
     const startedAt = Date.now();
     const url = (opts?.url?.trim() || "https://tsed.dev/api.json").toString();
+    const markdownUrl = (opts?.markdown_url?.trim() || "https://tsed.dev/ai/references").toString();
 
     const http = inject(HttpClient);
     const symbolsService = inject(PackageSymbolsService);
@@ -48,13 +50,16 @@ export default defineOperationApi<Options>({
       for (const s of mod.symbols) {
         try {
           const pkg = await ensurePackage(pkgName);
-          const mapped = mapApiSymbolToDirectus(pkg.id, s, origin);
+          const mapped = mapApiSymbolToDirectus(s, origin, markdownUrl);
 
-          await symbolsService.upsertOne(mapped);
+          mapped.versions.push(data.version);
+
+          await symbolsService.upsertOne({ ...mapped, package: pkg.id });
 
           upserted += 1;
           processed += 1;
         } catch (er: any) {
+          console.log(er);
           errors.push({
             name: s.symbolName,
             pkg: pkgName,
diff --git a/extensions/tsed-flow-package-symbols/src/app.ts b/extensions/tsed-flow-package-symbols/src/app.ts
@@ -4,7 +4,7 @@ export default defineOperationApp({
   id: "tsed-flow-package-symbols",
   name: "Ts.ED Package Symbols importer",
   icon: "code",
-  description: "Récupère les symboles exportés des packages Ts.ED depuis api.json et les upsert dans package_symbols.",
+  description: "Retrieves exported symbols from Ts.ED packages from api.json and upserts them into package_symbols.",
   overview: ({ url }) => [
     {
       label: "API URL",
@@ -19,11 +19,24 @@ export default defineOperationApp({
       meta: {
         width: "full",
         interface: "input",
-        note: "URL du JSON des symboles (default: https://tsed.dev/api.json)"
+        note: "URL of JSON symbols (default: https://tsed.dev/api.json)"
       },
       schema: {
         default_value: "https://tsed.dev/api.json"
       }
+    },
+    {
+      field: "markdown_url",
+      name: "Markdown base URL",
+      type: "string",
+      meta: {
+        width: "full",
+        interface: "input",
+        note: "URL where the markdown contents of the symbols are stored (default: https://tsed.dev/ai/references/api)"
+      },
+      schema: {
+        default_value: "https://tsed.dev/ai/references/api"
+      }
     }
   ]
 });
diff --git a/extensions/tsed-flow-package-symbols/src/mappers/mapApiSymbolToDirectus.spec.ts b/extensions/tsed-flow-package-symbols/src/mappers/mapApiSymbolToDirectus.spec.ts
@@ -1,29 +1,30 @@
-import { describe, it, expect } from "vitest";
-import { mapApiSymbolToDirectus, type ApiJsonModuleSymbol } from "./mapApiSymbolToDirectus.js";
+import { type ApiJsonModuleSymbol, mapApiSymbolToDirectus } from "./mapApiSymbolToDirectus.js";
 
 describe("mapApiSymbolToDirectus", () => {
   const baseOrigin = "https://tsed.dev";
+  const markdownOrigin = "https://tsed.dev/ai/references";
   const pkgId = "pkg-1";
 
   it("mappe les champs de base correctement", () => {
     const input: ApiJsonModuleSymbol = {
       id: "sym-1",
-      path: "/api/core/Controller.html",
+      path: "/api/core/Controller",
       symbolName: "Controller",
       module: "@tsed/core",
       symbolType: "class",
       status: []
     };
 
-    const out = mapApiSymbolToDirectus(pkgId, input, baseOrigin);
+    const out = mapApiSymbolToDirectus(pkgId, input, baseOrigin, markdownOrigin);
 
     expect(out).toMatchObject({
       id: "sym-1",
       status: "published",
       name: "Controller",
       type: "class",
-      doc_url: "https://tsed.dev/api/core/Controller.html",
-      versions: null,
+      doc_url: "https://tsed.dev/api/core/Controller",
+      markdown_url: "https://tsed.dev/ai/references/api/core/Controller.md",
+      versions: [],
       package: pkgId,
       deprecated: false,
       tags: []
diff --git a/extensions/tsed-flow-package-symbols/src/mappers/mapApiSymbolToDirectus.ts b/extensions/tsed-flow-package-symbols/src/mappers/mapApiSymbolToDirectus.ts
@@ -30,19 +30,20 @@ export type ApiJsonResponse = {
  * Responsibility: mapping fields and normalizing optional metadata only.
  * Caller is responsible for resolving/ensuring the `package` id.
  */
-export function mapApiSymbolToDirectus(pkg: string, symbol: ApiJsonModuleSymbol, baseOrigin: string) {
+export function mapApiSymbolToDirectus(symbol: ApiJsonModuleSymbol, baseOrigin: string, markdownUrl?: string) {
   const deprecated = symbol.status ? symbol.status.includes("deprecated") : false;
-  const tags = (symbol.status || []).filter((t) => t === "deprecated");
+  const tags = (symbol.status || []).filter((t) => t !== "deprecated");
 
   return {
     id: symbol.id,
     status: "published",
     name: symbol.symbolName,
     type: symbol.symbolType,
     doc_url: `${baseOrigin}${symbol.path}`,
-    versions: null,
-    package: pkg,
+    markdown_url: `${markdownUrl}${symbol.path}.md`,
+    additional_doc_url: "",
+    versions: [] as string[],
     deprecated,
     tags
-  } satisfies Omit<PackageSymbol, "user_created" | "date_created" | "user_updated" | "date_updated">;
+  } satisfies Omit<PackageSymbol, "package" | "user_created" | "date_created" | "user_updated" | "date_updated">;
 }
diff --git a/migrations/data/directus_flows.json b/migrations/data/directus_flows.json
@@ -132,5 +132,27 @@
     "operation": "70f217d9-bcef-4637-aee3-083f5e60f82a",
     "date_created": "2025-11-03T08:34:33.531Z",
     "user_created": "dc515c74-5ed5-4464-b522-6ea1f2f6d270"
+  },
+  {
+    "id": "569895a0-7a65-4cb2-94aa-67f77a776a08",
+    "name": "Manual import package symbols",
+    "icon": "bolt",
+    "color": null,
+    "description": null,
+    "status": "active",
+    "trigger": "manual",
+    "accountability": "all",
+    "options": {
+      "collections": [
+        "package_symbols"
+      ],
+      "requireSelection": false,
+      "location": "collection",
+      "requireConfirmation": true,
+      "async": true
+    },
+    "operation": "c651e60f-159c-4b4d-b636-c9d50debe3de",
+    "date_created": "2025-11-15T10:33:07.296Z",
+    "user_created": "dc515c74-5ed5-4464-b522-6ea1f2f6d270"
   }
 ]
diff --git a/migrations/data/directus_operations.json b/migrations/data/directus_operations.json
@@ -106,5 +106,22 @@
     "flow": "30be3802-3c63-41a3-9469-6aa5c48c58d6",
     "date_created": "2025-11-03T08:35:08.005Z",
     "user_created": "dc515c74-5ed5-4464-b522-6ea1f2f6d270"
+  },
+  {
+    "id": "c651e60f-159c-4b4d-b636-c9d50debe3de",
+    "name": "Ts.ED Package Symbols importer",
+    "key": "tsed_flow_package_symbols_k8436",
+    "type": "tsed-flow-package-symbols",
+    "position_x": 19,
+    "position_y": 1,
+    "options": {
+      "url": "https://tsed.dev/api.json",
+      "markdown_url": "https://tsed.dev/ai/references/api"
+    },
+    "resolve": null,
+    "reject": null,
+    "flow": "569895a0-7a65-4cb2-94aa-67f77a776a08",
+    "date_created": "2025-11-15T10:35:32.381Z",
+    "user_created": "dc515c74-5ed5-4464-b522-6ea1f2f6d270"
   }
 ]
diff --git a/migrations/data/directus_presets.json b/migrations/data/directus_presets.json
@@ -186,5 +186,54 @@
     "icon": "bookmark",
     "color": null,
     "uuid": "5990ceea-5ce1-451f-a119-248de002975b"
+  },
+  {
+    "id": 32,
+    "bookmark": null,
+    "user": null,
+    "role": null,
+    "collection": "package_symbols",
+    "search": null,
+    "layout": "tabular",
+    "layout_query": {
+      "tabular": {
+        "fields": [
+          "status",
+          "name",
+          "package",
+          "type",
+          "versions",
+          "tags",
+          "doc_url",
+          "user_created",
+          "date_created",
+          "user_updated",
+          "date_updated"
+        ],
+        "page": 9
+      }
+    },
+    "layout_options": {
+      "tabular": {
+        "widths": {
+          "status": 32,
+          "name": 160,
+          "type": 160,
+          "versions": 160,
+          "tags": 160,
+          "doc_url": 320.5,
+          "package": 160,
+          "user_created": 160,
+          "date_created": 160,
+          "user_updated": 160,
+          "date_updated": 160
+        }
+      }
+    },
+    "refresh_interval": null,
+    "filter": null,
+    "icon": "bookmark",
+    "color": null,
+    "uuid": "3408e10b-df03-4a2c-b5da-ce0b13547f5b"
   }
 ]
diff --git a/migrations/utils/installPresets.ts b/migrations/utils/installPresets.ts
@@ -30,7 +30,6 @@ export async function installPresets(knex: Knex, presets: Preset[]): Promise<voi
     }
   } catch (error) {
     logger.error(`Error altering directus_presets or directus_fields table:`, error);
-    throw error;
   }
 
   // For each language, check if it exists and insert it if it doesn't
@@ -50,21 +49,27 @@ export async function installPresets(knex: Knex, presets: Preset[]): Promise<voi
 
         await knex(TABLE).insert(preset);
       } catch (er) {
-        delete (preset as any).uuid;
-        await knex(TABLE).insert(preset);
+        try {
+          delete (preset as any).uuid;
+          await knex(TABLE).insert(preset);
+        } catch (er) {}
       }
     } else {
       logger.info(`Update preset: ${preset.collection}`);
-      if (uuidExists) {
-        await knex(TABLE)
-          .update(preset as any)
-          .where({ uuid: uuidExists.uuid });
-      } else {
-        (preset as any).uuid = v4();
+      try {
+        if (uuidExists) {
+          await knex(TABLE)
+            .update(preset as any)
+            .where({ uuid: uuidExists.uuid });
+        } else {
+          (preset as any).uuid = v4();
 
-        await knex(TABLE)
-          .update(preset as any)
-          .where({ id: exists.id });
+          await knex(TABLE)
+            .update(preset as any)
+            .where({ id: exists.id });
+        }
+      } catch (error) {
+        logger.error(`Error updating preset: ${preset.id}`);
       }
     }
   }
diff --git a/package.json b/package.json
@@ -145,6 +145,7 @@
     "supertest": "7.1.1",
     "tsdown": "0.15.12",
     "typescript": "5.8.3",
+    "uuid": "13.0.0",
     "vitest": "3.2.1"
   },
   "keywords": [
diff --git a/packages/infra/directus/interfaces/DirectusSchema.d.ts b/packages/infra/directus/interfaces/DirectusSchema.d.ts
diff --git a/packages/usecases/package-symbols/PackageSymbolsService.ts b/packages/usecases/package-symbols/PackageSymbolsService.ts
diff --git a/snapshots/snapshot-latest.yaml b/snapshots/snapshot-latest.yaml
diff --git a/yarn.lock b/yarn.lock
