@qualcomm-ui/mdx-vite 2.6.4 → 2.8.0

package/dist/cli.js

@@ -3549,6 +3549,27 @@ var routeMetaSchema = implement().with({
 var typeDocPropsSchema = implement().with({
   includeInSearchIndex: z2.boolean().optional()
 });
+var knowledgeExtraFileSchema = implement().with({
+  contents: z2.string(),
+  id: z2.string(),
+  title: z2.string()
+});
+var knowledgeIntegrationSchema = implement().with(
+  {
+    baseUrl: z2.string().optional(),
+    description: z2.string().optional(),
+    exclude: z2.array(z2.string()).optional(),
+    extraFiles: z2.array(knowledgeExtraFileSchema).optional(),
+    metadata: z2.record(z2.string(), z2.string()).optional(),
+    name: z2.string().optional(),
+    outputMode: z2.union([z2.literal("per-page"), z2.literal("aggregated")]).optional(),
+    outputPath: z2.string().optional(),
+    pageTitlePrefix: z2.string().optional()
+  }
+);
+var knowledgeConfigSchema = implement().with({
+  global: knowledgeIntegrationSchema.optional()
+});
 var configSchema = implement().with({
   appDirectory: z2.string().optional(),
   disableCache: z2.boolean().optional(),
@@ -3563,6 +3584,7 @@ var configSchema = implement().with({
     ])
   ).optional(),
   hotUpdateIgnore: z2.instanceof(RegExp).optional(),
+  knowledge: knowledgeConfigSchema.optional(),
   navConfig: z2.array(z2.union([routeMetaSchema, navMetaSchema])).optional(),
   pageDirectory: z2.string().optional(),
   pageTimestampMetadata: z2.union([
@@ -3570,10 +3592,7 @@ var configSchema = implement().with({
     z2.literal("timestamp"),
     z2.literal("user-and-timestamp")
   ]).optional(),
-  routingStrategy: z2.union([
-    z2.literal("vite-generouted"),
-    z2.function(z2.tuple([z2.string()]), z2.array(z2.string()))
-  ]).optional(),
+  routingStrategy: z2.union([z2.literal("vite-generouted"), z2.any()]).optional(),
   typeDocProps: z2.string().optional(),
   typeDocPropsOptions: typeDocPropsSchema.optional()
 });
@@ -3585,6 +3604,7 @@ function defined(value) {
 }
 var frontmatterSchema = implement().with({
   categories: z3.string().array().optional(),
+  description: z3.string().optional(),
   group: z3.string().optional(),
   hidden: z3.boolean().optional(),
   hideBreadcrumbs: z3.boolean().optional(),
@@ -5017,6 +5037,7 @@ var SearchIndexer = class {
         this.metaJson,
         routeMeta?.title || frontmatter.title || ""
       ),
+      description: frontmatter.description,
       hidden: defined(routeMeta.hidden) ? routeMeta.hidden : frontmatter.hidden,
       hideBreadcrumbs: defined(routeMeta.hideBreadcrumbs) ? routeMeta.hideBreadcrumbs : frontmatter.hideBreadcrumbs,
       hideFromSearch: defined(routeMeta.hideFromSearch) ? routeMeta.hideFromSearch : frontmatter.hideFromSearch,
@@ -5592,6 +5613,7 @@ function addDownloadKnowledgeCommand() {
 }
 
 // src/open-web-ui-knowledge/generate-knowledge.ts
+import { minimatch } from "minimatch";
 import {
   access,
   mkdir as mkdir2,
@@ -5601,14 +5623,14 @@ import {
   stat,
   writeFile as writeFile3
 } from "node:fs/promises";
-import { basename, dirname, extname, join as join3, resolve as resolve5 } from "node:path";
+import { basename, dirname, extname, join as join3, relative as relative2, resolve as resolve5 } from "node:path";
 import remarkFrontmatter3 from "remark-frontmatter";
 import remarkMdx3 from "remark-mdx";
 import remarkParse4 from "remark-parse";
 import remarkParseFrontmatter2 from "remark-parse-frontmatter";
 import remarkStringify3 from "remark-stringify";
 import { unified as unified4 } from "unified";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 import { kebabCase } from "@qualcomm-ui/utils/change-case";
 
 // src/docs-plugin/docs-plugin.ts
@@ -5775,9 +5797,12 @@ import { headingRank as headingRank2 } from "hast-util-heading-rank";
 // src/docs-plugin/remark/remark-code-tabs.ts
 import { visit as visit4 } from "unist-util-visit";
 
+// src/docs-plugin/remark/remark-frontmatter-description.ts
+import { visit as visit5 } from "unist-util-visit";
+
 // src/docs-plugin/remark/remark-self-link-headings.ts
 import { toString as toString2 } from "mdast-util-to-string";
-import { visit as visit5 } from "unist-util-visit";
+import { visit as visit6 } from "unist-util-visit";
 var emptyOptions2 = {};
 function remarkSelfLinkHeadings(baseUrl = "", options) {
   if (!baseUrl) {
@@ -5805,7 +5830,7 @@ function remarkSelfLinkHeadings(baseUrl = "", options) {
     }
     return (tree) => {
       seenIds.clear();
-      visit5(tree, "heading", (node) => {
+      visit6(tree, "heading", (node) => {
         if (allowedLevels.has(node.depth)) {
           const text = toString2(node);
           const slug = prefix + createSlug(text);
@@ -5822,7 +5847,7 @@ function remarkSelfLinkHeadings(baseUrl = "", options) {
 }
 
 // src/docs-plugin/remark/remark-spoilers.ts
-import { visit as visit6 } from "unist-util-visit";
+import { visit as visit7 } from "unist-util-visit";
 
 // src/docs-plugin/shiki/shiki-transformer-preview-block.ts
 import { dedent } from "@qualcomm-ui/utils/dedent";
@@ -5830,15 +5855,21 @@ import { dedent } from "@qualcomm-ui/utils/dedent";
 // src/open-web-ui-knowledge/load-config-from-env.ts
 import { existsSync } from "node:fs";
 import { join as join2, resolve as resolve4 } from "node:path";
+function parseCliMetadata(cliMetadata) {
+  if (!cliMetadata?.length) {
+    return void 0;
+  }
+  return Object.fromEntries(cliMetadata.map((entry) => entry.split("=")));
+}
 function loadKnowledgeConfigFromEnv(options) {
-  const exclude = options.exclude || (process.env.FILE_EXCLUDE_PATTERN ?? "").split(",");
-  const outputPath = options.outputPath || process.env.KNOWLEDGE_OUTPUT_PATH;
-  const prefix = process.env.PAGE_TITLE_PREFIX;
+  const configLoader = new ConfigLoader({});
+  const resolvedConfig = configLoader.loadConfig();
+  const fileConfig = resolvedConfig.knowledge?.global;
+  const exclude = (options.exclude?.length ? options.exclude : void 0) ?? fileConfig?.exclude ?? (process.env.FILE_EXCLUDE_PATTERN ?? "").split(",").filter(Boolean);
+  const outputPath = options.outputPath ?? fileConfig?.outputPath ?? process.env.KNOWLEDGE_OUTPUT_PATH;
   if (!outputPath) {
     throw new Error("Missing required outputPath");
   }
-  const configLoader = new ConfigLoader({});
-  const resolvedConfig = configLoader.loadConfig();
   const routeDir = join2(
     resolvedConfig.appDirectory,
     resolvedConfig.pageDirectory
@@ -5846,13 +5877,18 @@ function loadKnowledgeConfigFromEnv(options) {
   if (!existsSync(resolve4(routeDir))) {
     throw new Error(`Route directory ${routeDir} does not exist`);
   }
+  const cliMetadata = parseCliMetadata(options.metadata);
+  const mergedMetadata = fileConfig?.metadata || cliMetadata ? { ...fileConfig?.metadata, ...cliMetadata } : void 0;
   return {
+    ...fileConfig,
     ...options,
-    baseUrl: options.baseUrl || process.env.DOCS_SITE_BASE_URL,
+    baseUrl: options.baseUrl ?? fileConfig?.baseUrl ?? process.env.DOCS_SITE_BASE_URL,
     docPropsPath: resolvedConfig.typeDocProps,
     exclude,
+    extraFiles: fileConfig?.extraFiles,
+    metadata: mergedMetadata,
     outputPath,
-    pageTitlePrefix: prefix,
+    pageTitlePrefix: options.pageTitlePrefix ?? fileConfig?.pageTitlePrefix ?? process.env.PAGE_TITLE_PREFIX,
     routeDir
   };
 }
@@ -5919,14 +5955,11 @@ async function resolveModulePath(importPath, fromFile) {
   return null;
 }
 function extractMetadata(metadata) {
-  return (metadata ?? []).map((current) => {
-    const [key, value] = current.split("=");
-    return [key, value];
-  });
+  return Object.entries(metadata ?? {});
 }
 var replaceNpmInstallTabs = () => {
   return (tree, _file, done) => {
-    visit7(tree, "mdxJsxFlowElement", (node) => {
+    visit8(tree, "mdxJsxFlowElement", (node) => {
       if (node?.name === "NpmInstallTabs") {
         const packages = node.attributes?.find(
           (attr) => attr.type === "mdxJsxAttribute" && attr.name === "packages"
@@ -6001,6 +6034,7 @@ var KnowledgeGenerator = class {
         processedPages,
         extractedMetadata
       );
+      await this.generateExtraFiles(extractedMetadata);
     }
   }
   async loadDocProps() {
@@ -6031,26 +6065,27 @@ var KnowledgeGenerator = class {
   async scanPages() {
     const components = [];
     const excludePatterns = this.config.exclude ?? [];
-    const shouldExclude = (fileOrDir) => {
-      const dirName = basename(fileOrDir);
-      return excludePatterns.some((pattern) => {
-        if (pattern.includes("*")) {
-          const regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
-          return regex.test(dirName);
-        }
-        return dirName === pattern;
-      });
+    const shouldExclude = (absolutePath) => {
+      if (excludePatterns.length === 0) {
+        return false;
+      }
+      const relativePath = relative2(this.config.routeDir, absolutePath);
+      return excludePatterns.some(
+        (pattern) => minimatch(relativePath, pattern, { matchBase: true })
+      );
     };
     const scanDirectory = async (dirPath) => {
       if (shouldExclude(dirPath)) {
         if (this.config.verbose) {
-          console.log(`Excluding directory: ${basename(dirPath)}`);
+          console.log(
+            `Excluding directory: ${relative2(this.config.routeDir, dirPath)}`
+          );
         }
         return;
       }
       const entries = await readdir(dirPath, { withFileTypes: true });
       const mdxFiles = entries.filter(
-        (f) => f.name.endsWith(".mdx") && !shouldExclude(f.name)
+        (f) => f.name.endsWith(".mdx") && !shouldExclude(join3(dirPath, f.name))
       ) ?? [];
       for (const mdxFile of mdxFiles) {
         const demosFolder = entries.find((f) => f.name === "demos");
@@ -6069,7 +6104,7 @@ var KnowledgeGenerator = class {
           url: this.config.baseUrl ? new URL(url, this.config.baseUrl).toString() : void 0
         });
         if (this.config.verbose) {
-          console.log(`Found component: ${basename(dirPath)}`);
+          console.log(`Found file: ${basename(dirPath)}`);
           console.log(`  Demos folder: ${demosFolderPath || "NOT FOUND"}`);
         }
       }
@@ -6240,7 +6275,7 @@ ${codeText}
       }
     };
     return () => (tree, _file, done) => {
-      visit7(tree, "mdxJsxFlowElement", (node) => {
+      visit8(tree, "mdxJsxFlowElement", (node) => {
         const handler = node.name && handlers[node.name];
         if (!handler) {
           return;
@@ -6280,7 +6315,7 @@ ${codeText}
    */
   replaceTypeDocProps() {
     return () => (tree, _file, done) => {
-      visit7(
+      visit8(
         tree,
         "mdxJsxFlowElement",
         (node, index, parent) => {
@@ -6341,7 +6376,7 @@ ${codeText}
   replaceDemos(demosFolder, demoFiles) {
     return () => async (tree) => {
       const promises = [];
-      visit7(
+      visit8(
         tree,
         "mdxJsxFlowElement",
         (node, index, parent) => {
@@ -6429,11 +6464,32 @@ ${codeText}
       await Promise.all(promises);
     };
   }
+  replaceFrontmatterDescription(frontmatter) {
+    return () => (tree) => {
+      visit8(
+        tree,
+        "mdxFlowExpression",
+        (node, index, parent) => {
+          if (node.value.trim() !== "frontmatter.description" || index === void 0 || !parent) {
+            return;
+          }
+          if (frontmatter.description) {
+            parent.children.splice(index, 1, {
+              children: [{ type: "text", value: frontmatter.description }],
+              type: "paragraph"
+            });
+          } else {
+            parent.children.splice(index, 1);
+          }
+        }
+      );
+    };
+  }
   /**
    * Processes MDX content by transforming JSX elements (TypeDocProps, demos)
    * into markdown, resolving relative links, and cleaning up formatting.
    */
-  async processMdxContent(mdxContent, pageUrl, demosFolder) {
+  async processMdxContent(mdxContent, pageUrl, demosFolder, frontmatter) {
     const demoFiles = [];
     let processedContent = mdxContent;
     const lines = processedContent.split("\n");
@@ -6443,7 +6499,7 @@ ${codeText}
       /\[([^\]]+)\]\(\.\/#([^)]+)\)/g,
       (_, text, anchor) => pageUrl && this.config.outputMode === "per-page" ? `[${text}](${pageUrl}#${anchor})` : text
     );
-    const processor = unified4().use(remarkParse4).use(remarkMdx3).use(this.replaceTypeDocProps()).use(await this.replaceThemeNodes()).use(this.replaceDemos(demosFolder, demoFiles)).use(remarkStringify3);
+    const processor = unified4().use(remarkParse4).use(remarkMdx3).use(this.replaceTypeDocProps()).use(this.replaceFrontmatterDescription(frontmatter)).use(await this.replaceThemeNodes()).use(this.replaceDemos(demosFolder, demoFiles)).use(remarkStringify3);
     const processed = await processor.process(processedContent);
     processedContent = String(processed);
     processedContent = processedContent.replace(/\n\s*\n\s*\n/g, "\n\n");
@@ -6465,7 +6521,8 @@ ${codeText}
       const { content: processedContent, demoFiles } = await this.processMdxContent(
         String(parsed),
         component.url,
-        component.demosFolder
+        component.demosFolder,
+        frontmatter
       );
       const removeJsxProcessor = unified4().use(remarkParse4).use(remarkMdx3).use(remarkRemoveJsx).use(remarkStringify3);
       const removedJsx = String(
@@ -6520,10 +6577,41 @@ ${codeText}
     const outputStats = await stat(this.config.outputPath);
     const outputSizeKb = (outputStats.size / 1024).toFixed(1);
     console.log(
-      `Generated ${this.config.outputPath} with ${pages.length} component(s) at: ${this.config.outputPath}`
+      `Generated ${this.config.outputPath} with ${pages.length} files(s) at: ${this.config.outputPath}`
     );
     console.log(`File size: ${outputSizeKb} KB`);
   }
+  async generateExtraFiles(metadata) {
+    const extraFiles = this.config.extraFiles ?? [];
+    if (extraFiles.length === 0) {
+      return;
+    }
+    let totalSize = 0;
+    await Promise.all(
+      extraFiles.map(async (extraFile) => {
+        const lines = [];
+        if (metadata.length) {
+          lines.push("---");
+          for (const [key, value] of metadata) {
+            lines.push(`${key}: ${value}`);
+          }
+          lines.push("---");
+          lines.push("");
+        }
+        lines.push(`# ${extraFile.title}`);
+        lines.push("");
+        lines.push(extraFile.contents);
+        lines.push("");
+        const outfile = `${resolve5(this.config.outputPath)}/${kebabCase(extraFile.id)}.md`;
+        await writeFile3(outfile, lines.join("\n"), "utf-8");
+        const stats = await stat(outfile);
+        totalSize += stats.size / 1024;
+      })
+    );
+    console.log(
+      `Generated ${extraFiles.length} extra file(s) (${totalSize.toFixed(1)} KB)`
+    );
+  }
   async generatePerPageExports(pages, processedPages, metadata) {
     await mkdir2(dirname(this.config.outputPath), { recursive: true }).catch(
       () => {
@@ -6563,7 +6651,7 @@ ${codeText}
         }
         lines.push(content);
         lines.push("");
-        if (this.config.includeImports && processedPage.demoFiles.length > 0) {
+        if (processedPage.demoFiles.length > 0) {
           if (this.config.verbose) {
             console.log(
               `Collecting imports for ${page.name} from ${processedPage.demoFiles.length} demo files`
@@ -6605,7 +6693,7 @@ ${codeText}
         totalSize += stats.size / 1024;
       })
     );
-    console.log(`Generated ${count} component(s) in ${this.config.outputPath}`);
+    console.log(`Generated ${count} files(s) in ${this.config.outputPath}`);
     console.log(`Folder size: ${totalSize.toFixed(1)} KB`);
   }
 };
@@ -6619,7 +6707,7 @@ function addGenerateKnowledgeCommand() {
     "Project description for llms.txt"
   ).option("-v, --verbose", "Enable verbose logging", false).option(
     "--exclude <patterns...>",
-    "Exclude file or folder patterns (supports * wildcards)",
+    "Glob patterns to exclude (e.g., **/internal/**, guide/drafts/*)",
     []
   ).option("--base-url <url>", "Base URL for component documentation links").option("--metadata <pairs...>", "metadata key-value pairs").option("--clean", "Clean the output path before generating").option("--include-imports", "Include relative import source files", true).action(async (options) => {
     loadEnv();
@@ -6959,11 +7047,11 @@ import { dedent as dedent2 } from "@qualcomm-ui/utils/dedent";
 // src/react-demo-plugin/demo-plugin-utils.ts
 import chalk4 from "chalk";
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname2, join as join4, relative as relative2, resolve as resolve7, sep } from "node:path";
+import { dirname as dirname2, join as join4, relative as relative3, resolve as resolve7, sep } from "node:path";
 import * as ts from "typescript";
 import { pascalCase } from "@qualcomm-ui/utils/change-case";
 function extractPageId(filePath, routesDir) {
-  const relativePath = relative2(routesDir, filePath);
+  const relativePath = relative3(routesDir, filePath);
   const pathParts = relativePath.split(sep);
   if (pathParts.includes("demos")) {
     const demosIndex = pathParts.indexOf("demos");