@tobi-or-not/docpress 0.6.1 → 0.7.1

package/types/src/lib/fetch.d.ts

@@ -1,6 +1,9 @@
 import type { GlobalOpts } from '../schemas/global.js';
 import type { FetchOpts, FetchOptsUser } from '../schemas/fetch.js';
 import { getInfos } from './git.js';
+/**
+ * Enhanced repository type with DocPress-specific metadata
+ */
 export type EnhancedRepository = Awaited<ReturnType<typeof getInfos>>['repos'][number] & {
     docpress: {
         branch: string;
@@ -11,14 +14,55 @@ export type EnhancedRepository = Awaited<ReturnType<typeof getInfos>>['repos'][n
         replace_url: string;
     };
 };
+/**
+ * Checks for the existence of documentation files in a repository
+ *
+ * @param repoOwner - Owner of the repository (username)
+ * @param repoName - Name of the repository
+ * @param branch - Branch to check for documentation
+ * @returns Object containing HTTP status codes for different documentation paths
+ */
 export declare function checkDoc(repoOwner: GlobalOpts['usernames'][number], repoName: string, branch: FetchOpts['branch']): Promise<{
     rootReadmeStatus: number;
     docsFolderStatus: number;
     docsReadmeStatus: number;
 }>;
+/**
+ * Fetches documentation from a user's repositories
+ *
+ * @param options - Options for fetching documentation
+ * @param options.username - GitHub username
+ * @param options.branch - Branch to use for documentation
+ * @param options.reposFilter - Optional filter for repositories
+ * @param options.token - GitHub API token
+ */
 export declare function fetchDoc({ username, branch, reposFilter, token }: FetchOptsUser): Promise<void>;
+/**
+ * Enhances repository information with DocPress metadata
+ *
+ * @param repos - List of repositories from Git provider
+ * @param branch - Branch to use for documentation
+ * @param reposFilter - Optional filter for repositories
+ * @returns Array of enhanced repositories with DocPress metadata
+ */
 export declare function enhanceRepositories(repos: Awaited<ReturnType<typeof getInfos>>['repos'], branch?: FetchOpts['branch'], reposFilter?: FetchOpts['reposFilter']): Promise<EnhancedRepository[]>;
+/**
+ * Determines which files to include in the sparse checkout based on repository structure
+ *
+ * @param repo - Repository information
+ * @param branch - Branch to check for documentation
+ * @returns Array of file patterns to include in sparse checkout
+ */
 export declare function getSparseCheckout(repo: Awaited<ReturnType<typeof getInfos>>['repos'][number], branch: FetchOpts['branch']): Promise<string[]>;
+/**
+ * Generates and saves user and repository information
+ *
+ * @param user - User information from Git provider
+ * @param repos - List of repositories from Git provider
+ * @param branch - Branch to use for documentation
+ * @param reposFilter - Optional filter for repositories
+ * @returns Object containing user and enhanced repository information
+ */
 export declare function generateInfos(user: Awaited<ReturnType<typeof getInfos>>['user'], repos: Awaited<ReturnType<typeof getInfos>>['repos'], branch?: FetchOpts['branch'], reposFilter?: FetchOpts['reposFilter']): Promise<{
     user: {
         login: string;
@@ -118,5 +162,18 @@ export declare function generateInfos(user: Awaited<ReturnType<typeof getInfos>>
     };
     repos: EnhancedRepository[];
 }>;
+/**
+ * Fetches documentation from repositories
+ *
+ * @param repos - List of enhanced repositories
+ * @param reposFilter - Optional filter for repositories
+ */
 export declare function getDoc(repos?: EnhancedRepository[], reposFilter?: FetchOpts['reposFilter']): Promise<void>;
+/**
+ * Determines if a repository should be filtered out based on filter rules
+ *
+ * @param repo - Repository information
+ * @param reposFilter - Optional filter for repositories
+ * @returns True if the repository should be filtered out, false otherwise
+ */
 export declare function isRepoFiltered(repo: EnhancedRepository | Awaited<ReturnType<typeof getInfos>>['repos'][number], reposFilter?: FetchOpts['reposFilter']): boolean;

package/types/src/lib/git.d.ts

@@ -1,6 +1,15 @@
 import type { GlobalOpts } from '../schemas/global.js';
 import type { FetchOpts } from '../schemas/fetch.js';
 import type { EnhancedRepository } from './fetch.js';
+/**
+ * Fetches user and repository information from GitHub
+ *
+ * @param options - Options for retrieving GitHub data
+ * @param options.username - GitHub username
+ * @param options.token - GitHub API token
+ * @param options.branch - Branch to use for documentation
+ * @returns Object containing user information, repositories, and branch
+ */
 export declare function getInfos({ username, token, branch }: Pick<FetchOpts, 'branch'> & Pick<GlobalOpts, 'token'> & {
     username: GlobalOpts['usernames'][number];
 }): Promise<{
@@ -232,6 +241,9 @@ export declare function getInfos({ username, token, branch }: Pick<FetchOpts, 'b
             advanced_security?: {
                 status?: "enabled" | "disabled";
             };
+            code_security?: {
+                status?: "enabled" | "disabled";
+            };
             dependabot_security_updates?: {
                 status?: "enabled" | "disabled";
             };
@@ -249,8 +261,16 @@ export declare function getInfos({ username, token, branch }: Pick<FetchOpts, 'b
             };
         } | null;
     }[];
-    branch: string | undefined;
+    branch: any;
 }>;
+/**
+ * Gets contributors for a repository
+ *
+ * @param options - Options for retrieving contributors
+ * @param options.repository - Repository information
+ * @param options.token - GitHub API token
+ * @returns Object with source repository and contributors list
+ */
 export declare function getContributors({ repository, token, }: {
     repository: EnhancedRepository;
     token: GlobalOpts['token'];
@@ -387,6 +407,10 @@ export declare function getContributors({ repository, token, }: {
         master_branch?: string;
         starred_at?: string;
         anonymous_access_enabled?: boolean;
+        code_search_index_status?: {
+            lexical_search_ok?: boolean;
+            lexical_commit_sha?: string;
+        };
     } | undefined;
     contributors: never[];
 } | {
@@ -522,7 +546,20 @@ export declare function getContributors({ repository, token, }: {
         master_branch?: string;
         starred_at?: string;
         anonymous_access_enabled?: boolean;
+        code_search_index_status?: {
+            lexical_search_ok?: boolean;
+            lexical_commit_sha?: string;
+        };
     };
     contributors: any[];
 }>;
+/**
+ * Clones a repository with sparse checkout
+ *
+ * @param name - Repository name
+ * @param url - Repository URL
+ * @param projectDir - Directory to clone into
+ * @param branch - Branch to clone
+ * @param includes - Patterns to include in sparse checkout
+ */
 export declare function cloneRepo(name: string, url: string, projectDir: string, branch: string, includes: string[]): Promise<void>;

package/types/src/lib/prepare.d.ts

@@ -4,36 +4,80 @@ import type { GlobalOpts } from '../schemas/global.js';
 import { getUserInfos } from '../utils/functions.js';
 import type { EnhancedRepository } from './fetch.js';
 import type { getInfos } from './git.js';
+/**
+ * Represents a navigation page item with text and link
+ */
 export interface Page {
     text: string;
     link: string;
 }
+/**
+ * Represents a sidebar project with nested items
+ */
 export interface SidebarProject {
     text: string;
     collapsed: boolean;
-    items: Page[];
+    items: (Page | SidebarProject)[];
 }
+/**
+ * Represents a feature to display on the index page
+ */
 export interface Feature {
     title: string;
     details: string;
     link: string;
 }
+/**
+ * Represents the structure of the VitePress index page
+ */
 export interface Index {
     layout: string;
     hero: {
         name: string;
         tagline?: string;
     };
+    /** List of features to display */
     features: Feature[];
 }
+/**
+ * Prepares the documentation structure for a user's repositories
+ *
+ * @param options - Options for documentation preparation
+ * @param options.extraHeaderPages - Array of paths to additional header pages
+ * @param options.extraPublicContent - Array of paths to additional public content
+ * @param options.extraTheme - Array of paths to additional theme files
+ * @param options.vitepressConfig - Path to the VitePress configuration file
+ * @param options.forks - Flag to include forked repositories
+ * @param options.token - GitHub token for API access
+ * @param options.username - GitHub username to fetch repositories for
+ * @param options.websiteTitle - Custom title for the documentation website
+ * @param options.websiteTagline - Custom tagline for the documentation website
+ */
 export declare function prepareDoc({ extraHeaderPages, extraPublicContent, extraTheme, vitepressConfig, forks, token, username, websiteTitle, websiteTagline }: Omit<PrepareOpts, 'usernames' | 'branch' | 'gitProvider' | 'reposFilter'> & {
     username: PrepareOpts['usernames'][number];
 }): Promise<void>;
+/**
+ * Adds a source reference section to a markdown file
+ *
+ * @param repoUrl - URL of the GitHub repository
+ * @param outputPath - Path to the markdown file where sources will be added
+ */
 export declare function addSources(repoUrl: string, outputPath: string): void;
+/**
+ * Information about website title and tagline
+ */
 export interface WebsiteInfos {
     title?: string;
     tagline?: string;
 }
+/**
+ * Generates the index page content for the documentation site
+ *
+ * @param features - Array of features to display on the homepage
+ * @param user - User information retrieved from GitHub
+ * @param websiteInfos - Custom title and tagline information
+ * @returns An object with index page configuration
+ */
 export declare function generateIndex(features: Feature[], user: ReturnType<typeof getUserInfos>, websiteInfos: WebsiteInfos): {
     layout: string;
     hero: {
@@ -42,13 +86,67 @@ export declare function generateIndex(features: Feature[], user: ReturnType<type
     };
     features: Feature[];
 };
+/**
+ * Generates feature cards for the homepage
+ *
+ * @param repoName - Name of the repository
+ * @param description - Description of the repository
+ * @param features - Optional existing features to append to
+ * @returns Array of feature objects for the homepage
+ */
 export declare function generateFeatures(repoName: string, description: string, features?: Feature[]): Feature[];
-export declare function generateSidebarProject(repoName: string, sidebarPages: Page[]): {
+/**
+ * Generates a sidebar project entry for the documentation navigation
+ *
+ * @param repoName - Name of the repository
+ * @param sidebarPages - Array of sidebar pages to include in this project
+ * @returns A sidebar project configuration object
+ */
+export declare function generateSidebarProject(repoName: string, sidebarPages: (SidebarProject | Page)[]): {
     text: string;
     collapsed: boolean;
-    items: Page[];
+    items: (SidebarProject | Page)[];
 };
+/**
+ * Generates sidebar page entries for the documentation navigation
+ *
+ * @param repoName - Name of the repository
+ * @param fileName - Name of the file
+ * @param sidebarPages - Optional existing sidebar pages to append to
+ * @returns Array of page objects for the sidebar
+ */
 export declare function generateSidebarPages(repoName: string, fileName: string, sidebarPages?: Page[]): Page[];
+/**
+ * Generates sidebar items from a repository's file structure
+ *
+ * @param repository - Repository information
+ * @param obj - Object representing the file tree structure
+ * @returns Array of sidebar items (projects and pages)
+ */
+export declare function generateSidebarItems(repository: EnhancedRepository, obj: any): (SidebarProject | Page)[];
+/**
+ * Builds a tree structure from an array of file paths
+ *
+ * @param files - Array of file paths to be organized into a tree
+ * @returns A nested object representing the directory structure
+ */
+export declare function buildTree(files: string[]): any;
+/**
+ * Flattens a nested tree structure into an array of file paths
+ *
+ * @param subtree - The tree object to flatten
+ * @param prefix - Optional path prefix to prepend to each result
+ * @returns An array of file paths
+ */
+export declare function flattenTree(subtree: any, prefix?: string): string[];
+/**
+ * Transforms repository data into documentation structure
+ *
+ * @param repositories - Array of enhanced repositories
+ * @param user - User information retrieved from GitHub
+ * @param websiteInfos - Custom title and tagline information
+ * @returns Object containing sidebar and index page configurations
+ */
 export declare function transformDoc(repositories: EnhancedRepository[], user: ReturnType<typeof getUserInfos>, websiteInfos: WebsiteInfos): {
     sidebar: SidebarProject[];
     index: {
@@ -60,13 +158,57 @@ export declare function transformDoc(repositories: EnhancedRepository[], user: R
         features: Feature[];
     };
 };
+/**
+ * Adds extra pages to the documentation from specified paths
+ *
+ * @param paths - Array of paths to markdown files
+ * @returns Array of navigation page objects
+ */
 export declare function addExtraPages(paths: string[]): Page[];
+/**
+ * Adds content from specified paths to a target directory
+ *
+ * @param paths - String or array of paths to content
+ * @param dir - Target directory to copy content to
+ * @param fn - Optional callback function to execute for each file
+ */
 export declare function addContent(paths: string | string[], dir: string, fn?: () => void): void;
+/**
+ * Creates a fork page to display external contributions
+ *
+ * @param forks - Array of repositories and contribution counts
+ */
 export declare function addForkPage(forks: {
     repository: Awaited<ReturnType<typeof getInfos>>['repos'][number];
     contributions: number;
 }[]): void;
+/**
+ * Processes forked repositories to generate contribution information
+ *
+ * @param repositories - Array of enhanced repositories
+ * @param username - GitHub username
+ * @param token - Optional GitHub API token
+ */
 export declare function processForks(repositories: EnhancedRepository[], username: GlobalOpts['usernames'][number], token?: GlobalOpts['token']): Promise<void>;
+/**
+ * Parses a VitePress configuration file
+ *
+ * @param path - Path to the VitePress config file
+ * @returns The parsed configuration object
+ */
 export declare function parseVitepressConfig(path: string): Promise<Partial<ReturnType<typeof defineConfig>>>;
+/**
+ * Parses a VitePress index file
+ *
+ * @param path - Path to the index file
+ * @returns The parsed index object
+ */
 export declare function parseVitepressIndex(path: string): Promise<Index>;
+/**
+ * Generates VitePress configuration and index files
+ *
+ * @param vitepressConfig - VitePress configuration object
+ * @param index - Index page configuration
+ * @returns The list of theme files that were generated
+ */
 export declare function generateVitepressFiles(vitepressConfig: Partial<ReturnType<typeof defineConfig>>, index: Index): void;

package/types/src/lib/vitepress.d.ts

@@ -1,3 +1,11 @@
 import type { defineConfig } from 'vitepress';
 import type { Page, SidebarProject } from './prepare.js';
+/**
+ * Generates VitePress configuration by merging default and custom configs
+ *
+ * @param sidebar - Sidebar configuration
+ * @param nav - Navigation configuration
+ * @param vitepressConfig - Optional custom VitePress configuration
+ * @returns Merged VitePress configuration
+ */
 export declare function getVitepressConfig(sidebar: SidebarProject[], nav: Page[], vitepressConfig?: ReturnType<typeof defineConfig>): Partial<ReturnType<typeof defineConfig>>;

package/types/src/schemas/build.d.ts

@@ -1,23 +1,7 @@
-export declare const buildOptsSchema: import("zod").ZodObject<Pick<import("zod").objectUtil.extendShape<{
-    usernames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    branch: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodString>>;
-    gitProvider: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodEnum<["github"]>>>;
-    reposFilter: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraHeaderPages: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraPublicContent: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraTheme: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    forks: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodBoolean>>;
-    vitepressConfig: import("zod").ZodOptional<import("zod").ZodAny>;
-    websiteTitle: import("zod").ZodOptional<import("zod").ZodString>;
-    websiteTagline: import("zod").ZodOptional<import("zod").ZodString>;
-}, {
-    config: import("zod").ZodOptional<import("zod").ZodString>;
-    token: import("zod").ZodOptional<import("zod").ZodString>;
-    usernames: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    reposFilter: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraHeaderPages: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraPublicContent: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraTheme: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    vitepressConfig: import("zod").ZodOptional<import("zod").ZodString>;
-}>, never>, "strip", import("zod").ZodTypeAny, {}, {}>;
-export type BuildOpts = Zod.infer<typeof buildOptsSchema>;
+import type { z } from 'zod';
+/**
+ * Schema for build command options
+ * Currently empty as build doesn't require specific options
+ */
+export declare const buildOptsSchema: z.ZodObject<{}, z.core.$strip>;
+export type BuildOpts = z.infer<typeof buildOptsSchema>;

package/types/src/schemas/fetch.d.ts

@@ -1,60 +1,25 @@
-export declare const fetchOptsSchema: import("zod").ZodEffects<import("zod").ZodObject<Pick<import("zod").objectUtil.extendShape<{
-    usernames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+import type { GlobalOpts } from './global.js';
+/**
+ * Schema for fetch command options
+ * Includes options related to Git repository fetching
+ */
+export declare const fetchOptsSchema: import("zod").ZodObject<{
+    usernames: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string[], string>>>;
     branch: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodString>>;
-    gitProvider: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodEnum<["github"]>>>;
-    reposFilter: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraHeaderPages: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraPublicContent: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    extraTheme: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-    forks: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodBoolean>>;
-    vitepressConfig: import("zod").ZodOptional<import("zod").ZodAny>;
-    websiteTitle: import("zod").ZodOptional<import("zod").ZodString>;
-    websiteTagline: import("zod").ZodOptional<import("zod").ZodString>;
-}, {
+    gitProvider: import("zod").ZodOptional<import("zod").ZodDefault<import("zod").ZodEnum<{
+        github: "github";
+    }>>>;
+    reposFilter: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string[], string>>>;
     config: import("zod").ZodOptional<import("zod").ZodString>;
     token: import("zod").ZodOptional<import("zod").ZodString>;
-    usernames: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    reposFilter: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraHeaderPages: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraPublicContent: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    extraTheme: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string[], string>>;
-    vitepressConfig: import("zod").ZodOptional<import("zod").ZodString>;
-}>, "usernames" | "branch" | "gitProvider" | "reposFilter" | "config" | "token">, "strip", import("zod").ZodTypeAny, {
-    usernames?: string[] | undefined;
-    branch?: string | undefined;
-    gitProvider?: "github" | undefined;
-    reposFilter?: string[] | undefined;
-    config?: string | undefined;
-    token?: string | undefined;
-}, {
-    usernames?: string | undefined;
-    branch?: string | undefined;
-    gitProvider?: "github" | undefined;
-    reposFilter?: string | undefined;
-    config?: string | undefined;
-    token?: string | undefined;
-}>, {
-    token: string | undefined;
-    usernames: string[];
-    branch?: string | undefined;
-    gitProvider?: "github" | undefined;
-    reposFilter?: string[] | undefined;
-    extraHeaderPages?: string[] | undefined;
-    extraPublicContent?: string[] | undefined;
-    extraTheme?: string[] | undefined;
-    forks?: boolean | undefined;
-    vitepressConfig?: any;
-    websiteTitle?: string | undefined;
-    websiteTagline?: string | undefined;
-}, {
-    usernames?: string | undefined;
-    branch?: string | undefined;
-    gitProvider?: "github" | undefined;
-    reposFilter?: string | undefined;
-    config?: string | undefined;
-    token?: string | undefined;
-}>;
-export type FetchOpts = Zod.infer<typeof fetchOptsSchema>;
+}, import("zod/v4/core").$strip>;
+/**
+ * Type for fetch options
+ */
+export type FetchOpts = GlobalOpts;
+/**
+ * Type for fetch options with username instead of usernames array
+ */
 export type FetchOptsUser = Omit<FetchOpts, 'usernames'> & {
     username: FetchOpts['usernames'][number];
 };