@marlinjai/clearify 1.11.2 → 1.13.0

package/README.md

@@ -14,6 +14,7 @@ An open-source documentation site generator. Turn markdown into beautiful docs.
 - **OpenAPI API Reference** — custom-built renderer for OpenAPI specs with code examples, schema viewer, and full design system integration
 - **Multi-section support** — pill-based section switcher (e.g. public docs + internal docs)
 - **Auto changelog** — drop a `CHANGELOG.md` in your project root, it appears as `/changelog`
+- **README as landing page** — optionally include your project's `README.md` as the docs overview page
 
 ## Quick Start
 

package/dist/config-schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "siteUrl": {
+      "type": "string"
+    },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "primaryColor": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "light",
+            "dark",
+            "auto"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "logo": {
+      "type": "object",
+      "properties": {
+        "light": {
+          "type": "string"
+        },
+        "dark": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "links": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "docsDir": {
+            "type": "string"
+          },
+          "basePath": {
+            "type": "string"
+          },
+          "draft": {
+            "type": "boolean"
+          },
+          "sitemap": {
+            "type": "boolean"
+          },
+          "exclude": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "git": {
+            "type": "object",
+            "properties": {
+              "repo": {
+                "type": "string"
+              },
+              "ref": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "sparse": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "repo"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "label",
+          "docsDir"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "hub": {
+      "type": "object",
+      "properties": {
+        "projects": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "href": {
+                "type": "string"
+              },
+              "repo": {
+                "type": "string"
+              },
+              "status": {
+                "default": "active",
+                "type": "string",
+                "enum": [
+                  "active",
+                  "beta",
+                  "planned",
+                  "deprecated"
+                ]
+              },
+              "icon": {
+                "type": "string"
+              },
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "group": {
+                "type": "string"
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "link",
+                  "embed",
+                  "inject"
+                ]
+              },
+              "git": {
+                "type": "object",
+                "properties": {
+                  "repo": {
+                    "type": "string"
+                  },
+                  "ref": {
+                    "type": "string"
+                  },
+                  "path": {
+                    "type": "string"
+                  },
+                  "sparse": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "repo"
+                ],
+                "additionalProperties": false
+              },
+              "embedSections": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "all"
+                  },
+                  {
+                    "type": "string",
+                    "const": "public"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "injectInto": {
+                "type": "string"
+              },
+              "docsPath": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "name",
+              "description",
+              "status"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "scan": {
+          "type": "string"
+        },
+        "cacheDir": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "projects"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$id": "https://docs.lumitra.co/schemas/clearify-data.json",
+  "title": "Clearify Data Config"
+}

package/dist/node/{chunk-PVTUVUBK.js → chunk-2WML2D77.js}

@@ -6,7 +6,7 @@ import {
 import { z } from "zod";
 import { resolve, basename, dirname } from "path";
 import { pathToFileURL } from "url";
-import { existsSync, readFileSync, rmSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, rmSync, symlinkSync, readdirSync, statSync } from "fs";
 import { tmpdir } from "os";
 import { randomBytes } from "crypto";
 var NavigationItemSchema = z.lazy(
@@ -51,13 +51,15 @@ var HubProjectSchema = z.object({
   icon: z.string().optional(),
   tags: z.array(z.string()).optional(),
   group: z.string().optional(),
-  mode: z.enum(["link", "embed"]).optional(),
+  mode: z.enum(["link", "embed", "inject"]).optional(),
   git: RemoteGitSourceSchema.optional(),
   embedSections: z.union([
     z.literal("all"),
     z.literal("public"),
     z.array(z.string())
-  ]).optional()
+  ]).optional(),
+  injectInto: z.string().optional(),
+  docsPath: z.string().optional()
 });
 var HubProjectPartialSchema = z.object({
   description: z.string(),
@@ -98,8 +100,55 @@ var ClearifyConfigSchema = z.object({
   hub: HubConfigSchema,
   hubProject: HubProjectPartialSchema,
   customCss: z.string().optional(),
-  headTags: z.array(z.string()).optional()
+  headTags: z.array(z.string()).optional(),
+  includeReadme: z.boolean().default(false)
 });
+var ClearifyDataSchema = z.object({
+  name: z.string().optional(),
+  siteUrl: z.string().optional(),
+  theme: z.object({
+    primaryColor: z.string().optional(),
+    mode: z.enum(["light", "dark", "auto"]).optional()
+  }).optional(),
+  logo: z.object({
+    light: z.string().optional(),
+    dark: z.string().optional()
+  }).optional(),
+  links: z.record(z.string(), z.string()).optional(),
+  sections: z.array(SectionConfigSchema).optional(),
+  hub: HubConfigSchema
+});
+function deepMergeJsonWins(base, json) {
+  const result = { ...base };
+  for (const key of Object.keys(json)) {
+    const jsonVal = json[key];
+    if (jsonVal === void 0) continue;
+    const baseVal = base[key];
+    if (baseVal !== null && jsonVal !== null && typeof baseVal === "object" && typeof jsonVal === "object" && !Array.isArray(baseVal) && !Array.isArray(jsonVal)) {
+      result[key] = deepMergeJsonWins(baseVal, jsonVal);
+    } else {
+      result[key] = jsonVal;
+    }
+  }
+  return result;
+}
+function loadDataConfig(root) {
+  const dataPath = resolve(root, "clearify.data.json");
+  if (!existsSync(dataPath)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(dataPath, "utf-8"));
+    return ClearifyDataSchema.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function writeDataConfig(root, data) {
+  const validated = ClearifyDataSchema.parse(data);
+  const dataPath = resolve(root, "clearify.data.json");
+  const tmpPath = dataPath + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(validated, null, 2) + "\n", "utf-8");
+  renameSync(tmpPath, dataPath);
+}
 var defaultConfig = {
   name: "Documentation",
   docsDir: "./docs",
@@ -176,20 +225,24 @@ async function loadUserConfig(root) {
     "clearify.config.js",
     "clearify.config.mjs"
   ];
+  let tsConfig = {};
   for (const file of configFiles) {
     const configPath = resolve(root, file);
     if (existsSync(configPath)) {
       try {
         if (file.endsWith(".ts")) {
-          return await loadTsConfig(configPath);
+          tsConfig = await loadTsConfig(configPath);
+        } else {
+          const mod = await import(pathToFileURL(configPath).href);
+          tsConfig = mod.default ?? mod;
         }
-        const mod = await import(pathToFileURL(configPath).href);
-        return mod.default ?? mod;
+        break;
       } catch {
       }
     }
   }
-  return {};
+  const jsonData = loadDataConfig(root);
+  return deepMergeJsonWins(tsConfig, jsonData);
 }
 function resolveConfig(userConfig = {}, root) {
   const parsed = ClearifyConfigSchema.parse(userConfig);
@@ -247,8 +300,43 @@ async function resolveSections(config, root) {
     }
   ];
 }
+function buildStagingOverlay(stagingDir, originalDir, injections) {
+  if (existsSync(stagingDir)) {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  const ancestorDirs = /* @__PURE__ */ new Set();
+  for (const targetRelPath of injections.keys()) {
+    const parts = targetRelPath.split("/");
+    for (let i = 1; i <= parts.length; i++) {
+      ancestorDirs.add(parts.slice(0, i).join("/"));
+    }
+  }
+  function mirrorDir(srcDir, destDir, relPrefix) {
+    if (!existsSync(srcDir)) return;
+    const entries = readdirSync(srcDir);
+    for (const entry of entries) {
+      const srcPath = resolve(srcDir, entry);
+      const destPath = resolve(destDir, entry);
+      const relPath = relPrefix ? `${relPrefix}/${entry}` : entry;
+      if (ancestorDirs.has(relPath) && statSync(srcPath).isDirectory()) {
+        mkdirSync(destPath, { recursive: true });
+        mirrorDir(srcPath, destPath, relPath);
+      } else {
+        symlinkSync(srcPath, destPath);
+      }
+    }
+  }
+  mirrorDir(originalDir, stagingDir, "");
+  for (const [relPath, sourcePath] of injections) {
+    const destPath = resolve(stagingDir, relPath);
+    const parentDir = dirname(destPath);
+    mkdirSync(parentDir, { recursive: true });
+    symlinkSync(sourcePath, destPath);
+  }
+}
 async function scanHubProjects(config, root) {
-  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed")) {
+  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed" || p.mode === "inject")) {
     return config;
   }
   const scannedProjects = [];
@@ -320,10 +408,69 @@ async function scanHubProjects(config, root) {
       );
     }
   }
-  const finalSections = [...config.sections ?? [], ...embedSections];
+  const injectionsBySection = /* @__PURE__ */ new Map();
+  for (const project of merged) {
+    if (project.mode !== "inject" || !project.git) continue;
+    const cacheDir = config.hub?.cacheDir ? resolve(root, config.hub.cacheDir) : resolve(root, "node_modules/.cache/clearify-remote");
+    try {
+      const { resolveRemoteSource } = await import("./core/remote.js");
+      const { localPath, cached } = await resolveRemoteSource(project.git, cacheDir);
+      const docsPath = project.docsPath ?? "docs";
+      const absoluteDocsPath = resolve(localPath, docsPath);
+      if (!existsSync(absoluteDocsPath)) {
+        console.warn(
+          `  \u26A0 Hub inject "${project.name}": docs path "${docsPath}" not found in cloned repo.`
+        );
+        continue;
+      }
+      const targetLabel = project.injectInto;
+      if (!targetLabel) {
+        console.warn(`  \u26A0 Hub inject "${project.name}": missing injectInto field.`);
+        continue;
+      }
+      if (!injectionsBySection.has(targetLabel)) {
+        injectionsBySection.set(targetLabel, /* @__PURE__ */ new Map());
+      }
+      const slugifiedName = slugify(project.name);
+      const relPath = project.group ? `projects/${project.group}/${slugifiedName}` : `projects/${slugifiedName}`;
+      injectionsBySection.get(targetLabel).set(relPath, absoluteDocsPath);
+      console.log(
+        `  Hub inject "${project.name}": ${cached ? "cached" : "cloned"} \u2192 ${relPath}`
+      );
+    } catch (err) {
+      console.warn(
+        `  \u26A0 Hub inject "${project.name}" failed:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+  let modifiedSections = config.sections ? [...config.sections] : void 0;
+  if (injectionsBySection.size > 0 && modifiedSections) {
+    for (const [sectionLabel, injections] of injectionsBySection) {
+      const sectionIdx = modifiedSections.findIndex((s) => s.label === sectionLabel);
+      if (sectionIdx === -1) {
+        console.warn(`  \u26A0 Hub inject: target section "${sectionLabel}" not found.`);
+        continue;
+      }
+      const section = modifiedSections[sectionIdx];
+      const sectionId = slugify(section.label);
+      const originalDocsDir = section.docsDir.startsWith("/") ? section.docsDir : resolve(root, section.docsDir);
+      const stagingDir = resolve(root, `node_modules/.cache/clearify-inject/${sectionId}`);
+      buildStagingOverlay(stagingDir, originalDocsDir, injections);
+      modifiedSections[sectionIdx] = {
+        ...section,
+        docsDir: stagingDir
+      };
+      console.log(
+        `  Hub inject: staging overlay for "${sectionLabel}" \u2192 ${stagingDir}`
+      );
+    }
+  }
+  const finalSections = [...modifiedSections ?? config.sections ?? [], ...embedSections];
+  const sectionsChanged = embedSections.length > 0 || injectionsBySection.size > 0;
   return {
     ...config,
-    ...embedSections.length > 0 ? { sections: finalSections } : {},
+    ...sectionsChanged ? { sections: finalSections } : {},
     hub: {
       ...config.hub,
       projects: merged
@@ -332,6 +479,10 @@ async function scanHubProjects(config, root) {
 }
 
 export {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
+  loadDataConfig,
+  writeDataConfig,
   defaultConfig,
   loadUserConfig,
   resolveConfig,

package/dist/node/{chunk-QTGT76RY.js → chunk-CTL4YL7C.js}

@@ -133,9 +133,30 @@ function buildRoutes(docs, sectionId) {
     ...sectionId ? { sectionId } : {}
   }));
 }
+function extractReadmeTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : "Overview";
+}
 function buildSectionData(section, rootFiles, customNavigation) {
   const docs = scanDocs(section.docsDir, section.exclude, section.basePath);
   if (section.basePath === "/") {
+    if (rootFiles?.readmePath && existsSync(rootFiles.readmePath)) {
+      const hasIndex = docs.some((d) => d.routePath === "/");
+      if (!hasIndex) {
+        const content = readFileSync(rootFiles.readmePath, "utf-8");
+        const { data } = matter(content);
+        const title = extractReadmeTitle(content);
+        docs.unshift({
+          filePath: rootFiles.readmePath,
+          routePath: "/",
+          frontmatter: {
+            title: data.title ?? title,
+            description: data.description ?? "Project overview",
+            order: -1
+          }
+        });
+      }
+    }
     if (rootFiles?.changelogPath && existsSync(rootFiles.changelogPath)) {
       const content = readFileSync(rootFiles.changelogPath, "utf-8");
       const { data } = matter(content);