@xyd-js/plugin-docs 0.1.0-xyd.2 → 0.1.0-xyd.3

package/src/presets/docs/settings.ts

@@ -0,0 +1,75 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { createServer } from 'vite';
+
+import { Settings } from "@xyd-js/core";
+
+const extensions = ['tsx', 'ts', 'json'];
+
+/**
+ * Reads `xyd` settings from the current working directory.
+ * 
+ * This function searches for a file named 'xyd' with one of the supported extensions
+ * (tsx, jsx, js, ts, json) in the current working directory. If found, it loads the
+ * settings from that file.
+ * 
+ * For React-based settings files (tsx, jsx, js, ts), it uses Vite's SSR module loading
+ * to evaluate the file and extract the default export. For JSON files, it simply
+ * parses the JSON content.
+ * 
+ * @returns A Promise that resolves to:
+ *   - The Settings object if a valid settings file was found and loaded
+ *   - A string if the settings file contains a string value
+ *   - null if no settings file was found or an error occurred
+ * 
+ * @throws May throw errors if file reading or parsing fails
+ */
+export async function readSettings() {
+    const dirPath = process.cwd();
+    const baseFileName = 'docs';
+
+    let settingsFilePath = '';
+    let reactSettings = false;
+
+    try {
+        const files = await fs.readdir(dirPath);
+        const settingsFile = files.find(file => {
+            const ext = path.extname(file).slice(1);
+            return file.startsWith(baseFileName) && extensions.includes(ext);
+        });
+
+        if (settingsFile) {
+            settingsFilePath = path.join(dirPath, settingsFile);
+            reactSettings = path.extname(settingsFile) !== '.json';
+        } else {
+            console.error(`No settings file found.\nFile must be named 'docs' with one of the following extensions: ${extensions.join(', ')}`);
+            return null;
+        }
+    } catch (error) {
+        console.error(error);
+        return null;
+    }
+
+    if (reactSettings) {
+        const settingsPreview = await createServer({
+            optimizeDeps: {
+                include: ["react/jsx-runtime"],
+            },
+        });
+        const config = await settingsPreview.ssrLoadModule(settingsFilePath);
+        return config.default as Settings;
+    } else {
+        const rawJsonSettings = await fs.readFile(settingsFilePath, 'utf-8');
+        try {
+            let json = JSON.parse(rawJsonSettings) as Settings
+
+
+            return json
+        } catch (e) {
+            console.error(e)
+
+            return null
+        }
+    }
+}

package/src/presets/graphql/index.ts

@@ -0,0 +1,69 @@
+import { Settings } from "@xyd-js/core";
+import { gqlSchemaToReferences } from "@xyd-js/gql";
+import type { Reference } from "@xyd-js/uniform";
+
+import { Preset } from "../../types"
+import { UniformPreset } from "../uniform"
+
+interface graphqlPluginOptions {
+    urlPrefix?: string
+    root?: string
+    disableFSWrite?: boolean
+}
+
+function preset(
+    settings: Settings,
+    options: graphqlPluginOptions
+) {
+    return GraphQLUniformPreset.new(settings, options)
+}
+
+export const graphqlPreset = preset satisfies Preset<unknown>
+
+class GraphQLUniformPreset extends UniformPreset {
+    private constructor(
+        settings: Settings,
+        options: {
+            disableFSWrite?: boolean
+        }
+    ) {
+        super(
+            "graphql",
+            settings.api?.graphql || "",
+            settings?.navigation?.sidebar || [],
+            options.disableFSWrite
+        )
+
+        this.uniformRefResolver = this.uniformRefResolver.bind(this)
+    }
+
+    static new(
+        settings: Settings,
+        options: graphqlPluginOptions
+    ) {
+        return new GraphQLUniformPreset(settings, {
+            disableFSWrite: options.disableFSWrite
+        })
+            .urlPrefix(options.urlPrefix || "")
+            .newUniformPreset()(settings, "graphql")
+    }
+
+    protected override async uniformRefResolver(filePath: string): Promise<Reference[]> {
+        if (!filePath) {
+            return []
+        }
+
+        const resp = await gqlSchemaToReferences(filePath)
+
+        if ("__UNSAFE_route" in resp && typeof resp.__UNSAFE_route === "function") {
+            // If the route is a function, we need to call it to get the actual route
+            const route = resp.__UNSAFE_route();
+            if (route) {
+                this.fileRouting(filePath, route);
+            }
+        }
+
+        return resp
+    }
+}
+

package/src/presets/openapi/index.ts

@@ -0,0 +1,66 @@
+import {Settings} from "@xyd-js/core";
+import {deferencedOpenAPI, oapSchemaToReferences, getXDocs} from "@xyd-js/openapi";
+import type {Reference} from "@xyd-js/uniform";
+
+import {Preset} from "../../types"
+import {UniformPreset} from "../uniform"
+
+export interface openapiPresetOptions {
+    urlPrefix?: string
+    root?: string
+    disableFSWrite?: boolean
+}
+
+function preset(
+    settings: Settings,
+    options: openapiPresetOptions
+) {
+    return OpenAPIUniformPreset.new(settings, options)
+}
+
+export const openapiPreset = preset satisfies Preset<unknown>
+
+class OpenAPIUniformPreset extends UniformPreset {
+    private constructor(
+        settings: Settings,
+        options: {
+            disableFSWrite?: boolean
+        }
+    ) {
+        super(
+            "openapi",
+            settings.api?.openapi || "",
+            settings?.navigation?.sidebar || [],
+            options.disableFSWrite
+        )
+        this.uniformRefResolver = this.uniformRefResolver.bind(this)
+    }
+
+    static new(
+        settings: Settings,
+        options: openapiPresetOptions
+    ) {
+        return new OpenAPIUniformPreset(settings, {
+            disableFSWrite: options.disableFSWrite
+        })
+            .urlPrefix(options.urlPrefix || "")
+            .newUniformPreset()(settings, "openapi")
+    }
+
+    protected override async uniformRefResolver(filePath: string): Promise<Reference[]> {
+        if (!filePath) {
+            return []
+        }
+
+        const schema = await deferencedOpenAPI(filePath)
+        if (schema) {
+            const xdocs = getXDocs(schema)
+            if (xdocs?.route) {
+                this.fileRouting(filePath, xdocs.route)
+            }
+        }
+
+        return oapSchemaToReferences(schema)
+    }
+}
+

package/src/presets/sources/index.ts

@@ -0,0 +1,74 @@
+import path from "path";
+import fs from "fs/promises";
+
+import type {Reference} from "@xyd-js/uniform";
+import {Settings} from "@xyd-js/core";
+import {sourcesToUniformV2} from "@xyd-js/sources/ts"
+
+import {Preset} from "../../types"
+import {UniformPreset} from "../uniform"
+
+export interface sourcesPresetsOptions {
+    urlPrefix?: string
+    root?: string
+    disableFSWrite?: boolean    
+}
+
+function preset(
+    settings: Settings,
+    options: sourcesPresetsOptions
+) {
+    return SourceUniformPreset.new(settings, options)
+}
+
+export const sourcesPreset = preset satisfies Preset<unknown>
+
+class SourceUniformPreset extends UniformPreset {
+    private constructor(
+        settings: Settings,
+        options: {
+            disableFSWrite?: boolean
+        }
+    ) {
+        super(
+            "sources",
+            settings.api?.sources || "",
+            settings?.navigation?.sidebar || [],
+            options.disableFSWrite
+        )
+    }
+
+    static new(
+        settings: Settings,
+        options: sourcesPresetsOptions
+    ) {
+        return new SourceUniformPreset(settings, {
+            disableFSWrite: options.disableFSWrite
+        })
+            .urlPrefix(options.urlPrefix || "")
+            .sourceTheme(true)
+            .newUniformPreset()(settings, "sources")
+    }
+
+    // TODO: options to specify only specific packages?
+    protected override async uniformRefResolver(filePath: string): Promise<Reference[]> {
+        if (!filePath) {
+            return []
+        }
+
+        const packages = await fs.readdir(filePath)
+
+        const ref = await sourcesToUniformV2(
+            filePath,
+            packages.map(p => path.join(filePath, p))
+        )
+
+        if (!ref || !ref.references) {
+            console.error("Failed to generate documentation.", filePath)
+            return []
+        }
+
+        return ref.references
+    }
+}
+