@lukoweb/apitogo 0.2.23 → 0.2.24

package/src/config/v2/layout.ts

@@ -1,237 +1,237 @@
-import type { Dirent } from "node:fs";
-import { mkdir, readdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import type { StatePaths } from "./paths.js";
-import type { Layout } from "./schema.js";
-
-export type LayoutDetection = { layout: Layout; reason: string };
-
-/** Folders never searched for source files or docs: dependencies, build output, VCS and our own folders. */
-const IGNORED_DIRS = new Set([
-  "node_modules",
-  ".git",
-  "dist",
-  "build",
-  "bin",
-  "obj",
-  "out",
-  "coverage",
-  ".next",
-  ".turbo",
-  ".cache",
-  ".apitogo",
-  "apitogo",
-  "vendor",
-  "__pycache__",
-  ".venv",
-  "venv",
-]);
-
-/** Manifests that identify a project (Reference, section 3.5). */
-const PROJECT_MANIFESTS = new Set([
-  "package.json",
-  "go.mod",
-  "pyproject.toml",
-  "requirements.txt",
-  "Pipfile",
-  "pom.xml",
-  "build.gradle",
-  "build.gradle.kts",
-  "Gemfile",
-  "composer.json",
-  "Cargo.toml",
-  "mix.exs",
-  "deno.json",
-]);
-const PROJECT_MANIFEST_SUFFIXES = [".csproj", ".fsproj", ".sln"];
-
-const SOURCE_EXTENSIONS = new Set([
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".mjs",
-  ".cjs",
-  ".py",
-  ".cs",
-  ".go",
-  ".java",
-  ".kt",
-  ".rb",
-  ".php",
-  ".rs",
-  ".ex",
-  ".swift",
-]);
-
-/** How deep, and how many entries, the source-file search may look. Detection is a hint, not a crawl. */
-const SOURCE_SEARCH_DEPTH = 3;
-const SOURCE_SEARCH_BUDGET = 3000;
-
-async function readEntries(dir: string): Promise<Dirent[]> {
-  try {
-    return await readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-}
-
-const toPosix = (value: string) => value.split(path.sep).join("/");
-
-async function findSourceFile(root: string): Promise<string | undefined> {
-  let budget = SOURCE_SEARCH_BUDGET;
-
-  async function search(
-    dir: string,
-    depth: number,
-  ): Promise<string | undefined> {
-    const entries = await readEntries(dir);
-    for (const entry of entries) {
-      if (budget-- <= 0) return undefined;
-      if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
-        return toPosix(path.relative(root, path.join(dir, entry.name)));
-      }
-    }
-    if (depth >= SOURCE_SEARCH_DEPTH) return undefined;
-    for (const entry of entries) {
-      if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) continue;
-      const found = await search(path.join(dir, entry.name), depth + 1);
-      if (found) return found;
-    }
-    return undefined;
-  }
-
-  return search(root, 0);
-}
-
-/**
- * Chooses the layout for `init` (Reference, section 3.5): an empty directory, or one with only VCS files, trivial
- * files and documentation, is `standalone`; a recognisable project (a manifest or source files) is `embedded`.
- */
-export async function detectLayout(dir: string): Promise<LayoutDetection> {
-  const entries = await readEntries(dir);
-  if (entries.length === 0) {
-    return { layout: "standalone", reason: "the directory is empty" };
-  }
-
-  const manifest = entries.find(
-    (entry) =>
-      entry.isFile() &&
-      (PROJECT_MANIFESTS.has(entry.name) ||
-        PROJECT_MANIFEST_SUFFIXES.some((suffix) =>
-          entry.name.endsWith(suffix),
-        )),
-  );
-  if (manifest) {
-    return {
-      layout: "embedded",
-      reason: `it contains a project (${manifest.name})`,
-    };
-  }
-
-  const source = await findSourceFile(dir);
-  if (source) {
-    return {
-      layout: "embedded",
-      reason: `it contains source code (${source})`,
-    };
-  }
-
-  return {
-    layout: "standalone",
-    reason: "it holds only documentation and trivial files, no project",
-  };
-}
-
-export type DocsCandidate = {
-  kind: "folder" | "file";
-  /** Path relative to the project directory, POSIX separators. */
-  path: string;
-  /** What goes into `portal.docs.content`: the docs are referenced in place, never moved or copied. */
-  glob: string;
-  fileCount: number;
-};
-
-const DOCS_FOLDER_NAMES = new Set(["docs", "doc", "documentation", "pages"]);
-const DOCS_EXTENSIONS = new Set([".md", ".mdx"]);
-/** Root markdown files that are project metadata, not documentation. */
-const NOT_DOCS = /^(readme|license|licence|changelog)(\.|$)/i;
-const DOCS_SEARCH_DEPTH = 2;
-const OWN_PAGES_FOLDER = "portal/pages";
-
-async function countDocs(dir: string): Promise<number> {
-  let count = 0;
-  for (const entry of await readEntries(dir)) {
-    if (entry.isDirectory()) {
-      if (!IGNORED_DIRS.has(entry.name))
-        count += await countDocs(path.join(dir, entry.name));
-    } else if (
-      entry.isFile() &&
-      DOCS_EXTENSIONS.has(path.extname(entry.name))
-    ) {
-      count += 1;
-    }
-  }
-  return count;
-}
-
-/**
- * Finds existing documentation: folders named `docs`, `doc`, `documentation` or `pages` (at the top or one level
- * down) that hold `.md` or `.mdx` files, and loose markdown files at the top that are not README, LICENSE or
- * CHANGELOG. Nothing is moved: each candidate becomes a glob.
- */
-export async function detectExistingDocs(
-  dir: string,
-): Promise<DocsCandidate[]> {
-  const candidates: DocsCandidate[] = [];
-
-  async function scan(current: string, depth: number) {
-    for (const entry of await readEntries(current)) {
-      const relative = toPosix(
-        path.relative(dir, path.join(current, entry.name)),
-      );
-      if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue;
-        if (relative === OWN_PAGES_FOLDER) continue; // the portal's own default pages folder is already covered by the defaults
-        if (DOCS_FOLDER_NAMES.has(entry.name.toLowerCase())) {
-          const fileCount = await countDocs(path.join(current, entry.name));
-          if (fileCount > 0) {
-            candidates.push({
-              kind: "folder",
-              path: relative,
-              glob: `${relative}/**/*.{md,mdx}`,
-              fileCount,
-            });
-          }
-        } else if (depth < DOCS_SEARCH_DEPTH - 1) {
-          await scan(path.join(current, entry.name), depth + 1);
-        }
-      } else if (
-        depth === 0 &&
-        entry.isFile() &&
-        DOCS_EXTENSIONS.has(path.extname(entry.name)) &&
-        !NOT_DOCS.test(entry.name)
-      ) {
-        candidates.push({
-          kind: "file",
-          path: relative,
-          glob: relative,
-          fileCount: 1,
-        });
-      }
-    }
-  }
-
-  await scan(dir, 0);
-  return candidates.sort((a, b) => a.path.localeCompare(b.path));
-}
-
-/**
- * Creates the generated-state directory: itself, its own `.gitignore` containing `*`, and the `generated/` and
- * `build/` folders. Never reads or edits the tenant's root `.gitignore`. Safe to call again.
- */
-export async function ensureStateDir(state: StatePaths): Promise<void> {
-  await mkdir(state.generatedDir, { recursive: true });
-  await mkdir(state.buildDir, { recursive: true });
-  await writeFile(state.gitignore, "*\n");
-}
+import type { Dirent } from "node:fs";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { StatePaths } from "./paths.js";
+import type { Layout } from "./schema.js";
+
+export type LayoutDetection = { layout: Layout; reason: string };
+
+/** Folders never searched for source files or docs: dependencies, build output, VCS and our own folders. */
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "bin",
+  "obj",
+  "out",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".apitogo",
+  "apitogo",
+  "vendor",
+  "__pycache__",
+  ".venv",
+  "venv",
+]);
+
+/** Manifests that identify a project (Reference, section 3.5). */
+const PROJECT_MANIFESTS = new Set([
+  "package.json",
+  "go.mod",
+  "pyproject.toml",
+  "requirements.txt",
+  "Pipfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "Gemfile",
+  "composer.json",
+  "Cargo.toml",
+  "mix.exs",
+  "deno.json",
+]);
+const PROJECT_MANIFEST_SUFFIXES = [".csproj", ".fsproj", ".sln"];
+
+const SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".cs",
+  ".go",
+  ".java",
+  ".kt",
+  ".rb",
+  ".php",
+  ".rs",
+  ".ex",
+  ".swift",
+]);
+
+/** How deep, and how many entries, the source-file search may look. Detection is a hint, not a crawl. */
+const SOURCE_SEARCH_DEPTH = 3;
+const SOURCE_SEARCH_BUDGET = 3000;
+
+async function readEntries(dir: string): Promise<Dirent[]> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+const toPosix = (value: string) => value.split(path.sep).join("/");
+
+async function findSourceFile(root: string): Promise<string | undefined> {
+  let budget = SOURCE_SEARCH_BUDGET;
+
+  async function search(
+    dir: string,
+    depth: number,
+  ): Promise<string | undefined> {
+    const entries = await readEntries(dir);
+    for (const entry of entries) {
+      if (budget-- <= 0) return undefined;
+      if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        return toPosix(path.relative(root, path.join(dir, entry.name)));
+      }
+    }
+    if (depth >= SOURCE_SEARCH_DEPTH) return undefined;
+    for (const entry of entries) {
+      if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) continue;
+      const found = await search(path.join(dir, entry.name), depth + 1);
+      if (found) return found;
+    }
+    return undefined;
+  }
+
+  return search(root, 0);
+}
+
+/**
+ * Chooses the layout for `init` (Reference, section 3.5): an empty directory, or one with only VCS files, trivial
+ * files and documentation, is `standalone`; a recognisable project (a manifest or source files) is `embedded`.
+ */
+export async function detectLayout(dir: string): Promise<LayoutDetection> {
+  const entries = await readEntries(dir);
+  if (entries.length === 0) {
+    return { layout: "standalone", reason: "the directory is empty" };
+  }
+
+  const manifest = entries.find(
+    (entry) =>
+      entry.isFile() &&
+      (PROJECT_MANIFESTS.has(entry.name) ||
+        PROJECT_MANIFEST_SUFFIXES.some((suffix) =>
+          entry.name.endsWith(suffix),
+        )),
+  );
+  if (manifest) {
+    return {
+      layout: "embedded",
+      reason: `it contains a project (${manifest.name})`,
+    };
+  }
+
+  const source = await findSourceFile(dir);
+  if (source) {
+    return {
+      layout: "embedded",
+      reason: `it contains source code (${source})`,
+    };
+  }
+
+  return {
+    layout: "standalone",
+    reason: "it holds only documentation and trivial files, no project",
+  };
+}
+
+export type DocsCandidate = {
+  kind: "folder" | "file";
+  /** Path relative to the project directory, POSIX separators. */
+  path: string;
+  /** What goes into `portal.docs.content`: the docs are referenced in place, never moved or copied. */
+  glob: string;
+  fileCount: number;
+};
+
+const DOCS_FOLDER_NAMES = new Set(["docs", "doc", "documentation", "pages"]);
+const DOCS_EXTENSIONS = new Set([".md", ".mdx"]);
+/** Root markdown files that are project metadata, not documentation. */
+const NOT_DOCS = /^(readme|license|licence|changelog)(\.|$)/i;
+const DOCS_SEARCH_DEPTH = 2;
+const OWN_PAGES_FOLDER = "portal/pages";
+
+async function countDocs(dir: string): Promise<number> {
+  let count = 0;
+  for (const entry of await readEntries(dir)) {
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRS.has(entry.name))
+        count += await countDocs(path.join(dir, entry.name));
+    } else if (
+      entry.isFile() &&
+      DOCS_EXTENSIONS.has(path.extname(entry.name))
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Finds existing documentation: folders named `docs`, `doc`, `documentation` or `pages` (at the top or one level
+ * down) that hold `.md` or `.mdx` files, and loose markdown files at the top that are not README, LICENSE or
+ * CHANGELOG. Nothing is moved: each candidate becomes a glob.
+ */
+export async function detectExistingDocs(
+  dir: string,
+): Promise<DocsCandidate[]> {
+  const candidates: DocsCandidate[] = [];
+
+  async function scan(current: string, depth: number) {
+    for (const entry of await readEntries(current)) {
+      const relative = toPosix(
+        path.relative(dir, path.join(current, entry.name)),
+      );
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name)) continue;
+        if (relative === OWN_PAGES_FOLDER) continue; // the portal's own default pages folder is already covered by the defaults
+        if (DOCS_FOLDER_NAMES.has(entry.name.toLowerCase())) {
+          const fileCount = await countDocs(path.join(current, entry.name));
+          if (fileCount > 0) {
+            candidates.push({
+              kind: "folder",
+              path: relative,
+              glob: `${relative}/**/*.{md,mdx}`,
+              fileCount,
+            });
+          }
+        } else if (depth < DOCS_SEARCH_DEPTH - 1) {
+          await scan(path.join(current, entry.name), depth + 1);
+        }
+      } else if (
+        depth === 0 &&
+        entry.isFile() &&
+        DOCS_EXTENSIONS.has(path.extname(entry.name)) &&
+        !NOT_DOCS.test(entry.name)
+      ) {
+        candidates.push({
+          kind: "file",
+          path: relative,
+          glob: relative,
+          fileCount: 1,
+        });
+      }
+    }
+  }
+
+  await scan(dir, 0);
+  return candidates.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Creates the generated-state directory: itself, its own `.gitignore` containing `*`, and the `generated/` and
+ * `build/` folders. Never reads or edits the tenant's root `.gitignore`. Safe to call again.
+ */
+export async function ensureStateDir(state: StatePaths): Promise<void> {
+  await mkdir(state.generatedDir, { recursive: true });
+  await mkdir(state.buildDir, { recursive: true });
+  await writeFile(state.gitignore, "*\n");
+}