@dogsbay/detect 0.2.0-beta.131 → 0.2.0-beta.133

package/README.md

@@ -18,8 +18,12 @@ detect(["README.md", "docs/gitbook/SUMMARY.md", "docs/gitbook/.gitbook/assets/a.
   choices to offer (`spaces`, `versions`, `locales`) and whether the browser converts with
   less fidelity than the CLI.
 
-Path detectors so far: GitBook. Other formats are detected on disk by the CLI, in the same
-order, until their browser import lands.
+Path detectors so far: GitBook, VitePress (`.vitepress/config.*` or
+`.vitepress/config/index.*`, outside `node_modules`; the shallowest project wins, then `docs/`,
+`site/`, `website/`) and Docusaurus (`docusaurus.config.{js,ts,mjs,cjs}` outside `node_modules`
+and hidden folders; the shallowest wins, then `website/`, `docs/`, `site/`; its instances and
+versions come from `@dogsbay/format-docusaurus/migrate`'s `docusaurusChoices`). Other formats are detected on disk by the CLI, in the same order, until
+their browser import lands.
 
 ## License
 

package/dist/docusaurus.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Docusaurus from paths. A `docusaurus.config.{js,ts,mjs,cjs}` is the marker (the CLI's
+ * `detectSource` looks for the same names); the project root is the folder holding it. Which
+ * docs instances and versions it has is in the config, which `@dogsbay/format-docusaurus/migrate`
+ * reads (`docusaurusChoices`): detection stays on paths alone.
+ */
+import type { Detection } from "./types.js";
+/** The config file names, in the order Docusaurus (and the CLI) look for them. */
+export declare const DOCUSAURUS_CONFIGS: string[];
+/** Project roots among `paths`: the folders holding a Docusaurus config, best first. */
+export declare function docusaurusRoots(paths: string[]): string[];
+/** Find a Docusaurus project among `paths` (a repo's whole tree, or one folder's listing). */
+export declare function detectDocusaurus(paths: string[]): Detection | undefined;

package/dist/docusaurus.js

@@ -0,0 +1,51 @@
+import { depthOf, within } from "./paths.js";
+/** The config file names, in the order Docusaurus (and the CLI) look for them. */
+export const DOCUSAURUS_CONFIGS = ["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs", "docusaurus.config.cjs"];
+/** Folders of a Docusaurus project that hold no docs pages of the default instance's kind. */
+const NOT_DOCS = new Set(["node_modules", "src", "static", "blog", "i18n", "build"]);
+/** Where a repo usually keeps its site, preferred among folders at the same depth. */
+const PREFERRED = ["website", "docs", "site"];
+/** Project roots among `paths`: the folders holding a Docusaurus config, best first. */
+export function docusaurusRoots(paths) {
+    const roots = new Set();
+    for (const p of paths) {
+        const slash = p.lastIndexOf("/");
+        if (!DOCUSAURUS_CONFIGS.includes(p.slice(slash + 1)))
+            continue;
+        const root = slash < 0 ? "" : p.slice(0, slash);
+        // Not inside node_modules or a hidden folder (a vendored copy, a template in a cache)
+        if (root.split("/").some((s) => s === "node_modules" || s.startsWith(".")))
+            continue;
+        roots.add(root);
+    }
+    const rank = (r) => {
+        const i = PREFERRED.indexOf(r.slice(r.lastIndexOf("/") + 1));
+        return i < 0 ? PREFERRED.length : i;
+    };
+    return [...roots].sort((a, b) => depthOf(a) - depthOf(b) || rank(a) - rank(b) || a.localeCompare(b));
+}
+/** Find a Docusaurus project among `paths` (a repo's whole tree, or one folder's listing). */
+export function detectDocusaurus(paths) {
+    const [found] = docusaurusRoots(paths);
+    // No config: a `sidebars*.js` at the top beside Markdown is a docs folder, as the CLI's
+    // `detectSource` reads it — but it is a weaker signal, so "low"
+    const bare = found === undefined && paths.some((p) => /^sidebars[^/]*\.(js|ts|cjs|mjs)$/.test(p)) && paths.some((p) => /\.mdx?$/i.test(p));
+    if (found === undefined && !bare)
+        return undefined;
+    const root = found ?? "";
+    // An estimate from paths: Markdown outside the folders that are not docs. The count of one
+    // instance is in the config, which the import reads: on pan.dev this says ~10,000 (9,500
+    // files under openapi-specs/) for 673 pages imported.
+    let pages = 0;
+    for (const p of paths) {
+        if (!within(p, root) || !/\.mdx?$/i.test(p))
+            continue;
+        const segs = (root ? p.slice(root.length + 1) : p).split("/");
+        if (segs.slice(0, -1).some((s) => NOT_DOCS.has(s) || s.startsWith(".") || s.endsWith("versioned_docs")))
+            continue;
+        if (segs.some((s) => s.startsWith("_")))
+            continue; // partials, as the import skips them
+        pages++;
+    }
+    return { format: "docusaurus", root, confidence: bare ? "low" : "high", pages, fidelity: "full" };
+}

package/dist/index.d.ts

@@ -2,7 +2,9 @@ import { type FormatName } from "./order.js";
 import type { Detection, ReadText } from "./types.js";
 export { FORMAT_ORDER, type FormatName } from "./order.js";
 export type { Detection, ReadText } from "./types.js";
+export { detectDocusaurus, docusaurusRoots, DOCUSAURUS_CONFIGS } from "./docusaurus.js";
 export { detectGitbook, gitbookSpaces, gitbookVisible } from "./gitbook.js";
+export { detectVitepress, vitepressConfigPath, vitepressPage, vitepressRoots, VITEPRESS_SKIP_DIRS } from "./vitepress.js";
 export { dirOf, isPlainPath, joinPath, normalizePath, within } from "./paths.js";
 /** The formats with a path detector, by name. */
 export declare const PATH_DETECTORS: Partial<Record<FormatName, (paths: string[], read?: ReadText) => Detection | undefined>>;

package/dist/index.js

@@ -3,17 +3,24 @@
  * dependencies: the playground runs it on a repo's tree before loading any importer, and the
  * dogsbay CLI takes its format order from here (`FORMAT_ORDER`).
  *
- * Formats get a path detector here as their browser import lands (GitBook first); until then
+ * Formats get a path detector here as their browser import lands (GitBook, VitePress,
+ * Docusaurus); until then
  * the CLI keeps detecting them on disk, in this same order.
  */
+import { detectDocusaurus } from "./docusaurus.js";
 import { detectGitbook } from "./gitbook.js";
+import { detectVitepress } from "./vitepress.js";
 import { FORMAT_ORDER } from "./order.js";
 export { FORMAT_ORDER } from "./order.js";
+export { detectDocusaurus, docusaurusRoots, DOCUSAURUS_CONFIGS } from "./docusaurus.js";
 export { detectGitbook, gitbookSpaces, gitbookVisible } from "./gitbook.js";
+export { detectVitepress, vitepressConfigPath, vitepressPage, vitepressRoots, VITEPRESS_SKIP_DIRS } from "./vitepress.js";
 export { dirOf, isPlainPath, joinPath, normalizePath, within } from "./paths.js";
 /** The formats with a path detector, by name. */
 export const PATH_DETECTORS = {
+    docusaurus: (paths) => detectDocusaurus(paths),
     gitbook: detectGitbook,
+    vitepress: (paths) => detectVitepress(paths),
 };
 /** The first format, in `FORMAT_ORDER`, whose path detector claims `paths`. */
 export function detect(paths, read) {

package/dist/vitepress.d.ts

@@ -0,0 +1,18 @@
+/**
+ * VitePress from paths. `.vitepress/config.*` (or the split layout `.vitepress/config/index.*`)
+ * is the only unambiguous marker: requiring it is what keeps VitePress from claiming a
+ * plain-Markdown, MkDocs or GitBook corpus. The project root is the folder holding `.vitepress`.
+ * `@dogsbay/format-vitepress` finds its config through `vitepressConfigPath`, so detection and
+ * import cannot disagree.
+ */
+import type { Detection } from "./types.js";
+/** Folders a VitePress project keeps beside its pages, never pages themselves. */
+export declare const VITEPRESS_SKIP_DIRS: Set<string>;
+/** The config file of the project at `root`, as VitePress looks for it; undefined if none. */
+export declare function vitepressConfigPath(paths: Iterable<string>, root: string): string | undefined;
+/** Project roots among `paths`: the folders holding a `.vitepress` with a config, best first. */
+export declare function vitepressRoots(paths: string[]): string[];
+/** Is `path` (relative to a project root) a page VitePress would build, before its config is read? */
+export declare function vitepressPage(rel: string): boolean;
+/** Find a VitePress project among `paths` (a repo's whole tree, or one folder's listing). */
+export declare function detectVitepress(paths: string[]): Detection | undefined;

package/dist/vitepress.js

@@ -0,0 +1,60 @@
+import { depthOf, joinPath, within } from "./paths.js";
+const CONFIG_EXTS = [".ts", ".mts", ".mjs", ".js", ".cts", ".cjs"];
+/** Folders a VitePress project keeps beside its pages, never pages themselves. */
+export const VITEPRESS_SKIP_DIRS = new Set([".vitepress", "node_modules", "public", "dist", ".git", "cache", ".cache"]);
+/** Where a repo usually keeps its docs, preferred among folders at the same depth. */
+const PREFERRED = ["docs", "site", "website"];
+/** The config file of the project at `root`, as VitePress looks for it; undefined if none. */
+export function vitepressConfigPath(paths, root) {
+    const all = paths instanceof Set ? paths : new Set(paths);
+    const vp = joinPath(root, ".vitepress");
+    for (const ext of CONFIG_EXTS)
+        if (all.has(`${vp}/config${ext}`))
+            return `${vp}/config${ext}`;
+    for (const ext of CONFIG_EXTS)
+        if (all.has(`${vp}/config/index${ext}`))
+            return `${vp}/config/index${ext}`;
+    return undefined;
+}
+/** Project roots among `paths`: the folders holding a `.vitepress` with a config, best first. */
+export function vitepressRoots(paths) {
+    const all = new Set(paths);
+    const roots = new Set();
+    for (const p of paths) {
+        const m = /(^|\/)\.vitepress\/config(\/index)?\.[cm]?[jt]s$/.exec(p);
+        if (!m)
+            continue;
+        const root = p.slice(0, m.index);
+        // Not inside node_modules or another hidden folder (a vendored copy, a cache)
+        if (root.split("/").some((s) => s === "node_modules" || (s.startsWith(".") && s !== "")))
+            continue;
+        if (vitepressConfigPath(all, root))
+            roots.add(root);
+    }
+    const rank = (r) => {
+        const i = PREFERRED.indexOf(r.slice(r.lastIndexOf("/") + 1));
+        return i < 0 ? PREFERRED.length : i;
+    };
+    return [...roots].sort((a, b) => depthOf(a) - depthOf(b) || rank(a) - rank(b) || a.localeCompare(b));
+}
+/** Is `path` (relative to a project root) a page VitePress would build, before its config is read? */
+export function vitepressPage(rel) {
+    const segs = rel.split("/");
+    if (segs.slice(0, -1).some((s) => VITEPRESS_SKIP_DIRS.has(s) || s.startsWith(".")))
+        return false;
+    return /\.md$/i.test(segs[segs.length - 1]);
+}
+/** Find a VitePress project among `paths` (a repo's whole tree, or one folder's listing). */
+export function detectVitepress(paths) {
+    const [root] = vitepressRoots(paths);
+    if (root === undefined)
+        return undefined;
+    let pages = 0;
+    for (const p of paths) {
+        if (!within(p, root))
+            continue;
+        if (vitepressPage(root ? p.slice(root.length + 1) : p))
+            pages++;
+    }
+    return { format: "vitepress", root, confidence: "high", pages, fidelity: "full" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/detect",
-  "version": "0.2.0-beta.131",
+  "version": "0.2.0-beta.133",
   "description": "Which documentation tool made this folder: the import formats' detection order (shared by the dogsbay CLI and the playground) and detectors that read paths only, with no Node and no dependencies",
   "type": "module",
   "main": "dist/index.js",