@docuify/engine/dist/core/engine.mjs

A flexible, pluggable engine for building and transforming documentation content from source files.

// lib/base/basePlugin.ts
var BasePlugin = class {
};

// lib/base/baseSource.ts
var BaseSource = class {
};

// lib/utils/build_tree.ts
var idCounter = 0;
function generateId() {
  return `node-${idCounter++}`;
}
function createFolderNode(name, fullPath, parentId) {
  return {
    id: generateId(),
    name,
    fullPath,
    type: "folder",
    parentId,
    children: []
  };
}
function createFileNode(file, name, fullPath, parentId) {
  const nodeId = generateId();
  const transformQueue = [];
  const getRawContent = file.loadContent;
  async function transformContent(rawContent) {
    let result = rawContent;
    for (const transformFunction of transformQueue) {
      result = await transformFunction(result);
    }
    return result;
  }
  async function loadContent() {
    if (!getRawContent) {
      throw new Error(`No content getter for ${file.path}`);
    }
    const raw = await getRawContent();
    return transformContent(raw);
  }
  return {
    id: nodeId,
    name,
    fullPath,
    type: "file",
    parentId,
    extension: file.extension,
    metadata: file.metadata ? { ...file.metadata } : void 0,
    // For inspection or debugging purposes — it's like peeking under the hood.
    _contentTransformQueue: transformQueue,
    // All the file's special powers are grouped here. Transform, load, mutate!
    actions: {
      useTransform: (fn) => {
        transformQueue.push(fn);
      },
      transformContent,
      loadContent
    }
  };
}
function buildTree(sourceFiles) {
  const root = {
    id: generateId(),
    name: "root",
    // Root node — the top of the tree. No parents. Just responsibilities.
    fullPath: ".",
    type: "folder",
    children: []
  };
  for (const file of sourceFiles) {
    const parts = file.path.split("/");
    let current = root;
    for (let i = 0; i < parts.length; i++) {
      const part = parts[i];
      const isLast = i === parts.length - 1;
      if (!current.children) {
        current.children = [];
      }
      let found = current.children.find((child) => child.name === part);
      if (!found) {
        const fullPath = parts.slice(0, i + 1).join("/");
        const newNode = isLast && file.type === "file" ? createFileNode(file, part, fullPath, current.id) : createFolderNode(part, fullPath, current.id);
        current.children.push(newNode);
        found = newNode;
      }
      current = found;
    }
  }
  return root;
}

// lib/utils/flatten_tree.ts
function flattenTree(tree) {
  const flat = [];
  const walk = (node) => {
    flat.push(node);
    if (node.children) {
      for (const child of node.children) {
        walk(child);
      }
    }
    delete node.children;
  };
  walk(tree);
  return flat;
}

// lib/utils/walk_tree_with_plugins.ts
async function walkTreeWithPlugins(root, plugins) {
  const state = {};
  let currentRoot = root;
  for (const plugin of plugins) {
    if (plugin.applyBefore) {
      const result = await plugin.applyBefore(currentRoot, state);
      if (result) currentRoot = result;
    }
  }
  async function walk(node, ancestors = [], index) {
    const context = {
      parent: ancestors[ancestors.length - 1],
      ancestors,
      index,
      visit: (child, ctx) => walk(child, ctx.ancestors, ctx.index),
      state
    };
    for (const plugin of plugins) {
      if (plugin.onVisit) {
        await plugin.onVisit(node, context);
      }
    }
    if (node.children) {
      for (let i = 0; i < node.children.length; i++) {
        await walk(node.children[i], [...ancestors, node], i);
      }
    }
  }
  await walk(currentRoot);
  for (const plugin of plugins) {
    if (plugin.applyAfter) {
      const result = await plugin.applyAfter(currentRoot, state);
      if (result) currentRoot = result;
    }
  }
  return currentRoot;
}

// lib/core/query_context.ts
import isMatch from "lodash/isMatch";
var QueryContext = class {
  flatNodes;
  constructor(flatNodes) {
    this.flatNodes = flatNodes;
  }
  /**
   * Filters nodes by a deep partial `where` clause.
   * Returns a new array of matching nodes (immutable).
   */
  findMany(where) {
    if (!where) return this.flatNodes;
    return this.flatNodes.filter((node) => isMatch(node, where));
  }
  /**
   * Finds the first node matching `where`.
   * Returns undefined if none found.
   */
  findFirst(where) {
    if (!where) return this.flatNodes[0];
    return this.flatNodes.find((node) => isMatch(node, where));
  }
  /**
   * Loads content from a given node if possible.
   * Throws if the node has no loadContent action or is not a file.
   * Returns loaded content as string.
   */
  async loadContent(node) {
    if (node.type !== "file") {
      throw new Error("loadContent only supported for file nodes");
    }
    if (!node.actions?.loadContent) {
      throw new Error(`Node at ${node.fullPath} has no content loader`);
    }
    return await node.actions.loadContent();
  }
};

// lib/utils/walk_tree.ts
function walkTree(node, visitor) {
  visitor(node);
  if (node.type === "folder" && node.children?.length) {
    for (const child of node.children) {
      walkTree(child, visitor);
    }
  }
}

// lib/utils/preload.ts
async function preloadFiles(files, concurrency = 10, keepContent = false) {
  const fileList = files.filter(
    (f) => f.type === "file" && typeof f.actions?.loadContent === "function"
  );
  let index = 0;
  const worker = async () => {
    while (index < fileList.length) {
      const currentIndex = index++;
      const file = fileList[currentIndex];
      try {
        await file.actions?.loadContent?.();
      } catch (err) {
        console.warn(
          `[docuify] Failed to preload content for: ${file.path}`,
          err
        );
      }
    }
  };
  const workers = Array.from({ length: concurrency }, () => worker());
  await Promise.all(workers);
}
async function preloadFlatNodesContent(nodes, concurrency = 10, keepContent = false) {
  await preloadFiles(nodes, concurrency, keepContent);
}
async function preloadTreeContent(tree, concurrency = 10, keepContent = false) {
  const files = [];
  walkTree(tree, (node) => {
    if (node.type === "file") {
      files.push(node);
    }
  });
  await preloadFiles(files, concurrency, keepContent);
}

// lib/core/engine.ts
var DocuifyEngine = class {
  config;
  tree;
  constructor(config) {
    if (!config.source) {
      throw new Error("DocuifyEngine requires a source. It's the whole point.");
    }
    this.config = {
      ...config,
      plugins: config.plugins || []
      // If no plugins are passed, we still dance alone.
    };
  }
  get buildResult() {
    const pluginNames = this.config.plugins.map((p) => p.name);
    return {
      head: {},
      // Reserved for future lore: commit hashes, timestamps, secrets...
      tree: this.tree,
      foot: {
        source: this.config.source.name,
        pluginNames
      }
    };
  }
  /**
   * Builds the Docuify tree from the source.
   * Filters are applied here. Lazy loading is respected.
   */
  async treeBuilder() {
    const rawFiles = await this.config.source.fetch();
    const filteredFiles = this.config.filter ? rawFiles.filter(this.config.filter) : rawFiles;
    this.tree = buildTree(filteredFiles);
    return this.tree;
  }
  /**
   * Applies plugins to the tree. Plugins may mutate nodes, extract metadata, or summon demons.
   */
  async applyPlugins() {
    this.tree = await walkTreeWithPlugins(this.tree, this.config.plugins);
    return this.tree;
  }
  /**
   * Returns the current Docuify tree.
   * Caution: this may return undefined if `buildTree` hasn’t run.
   */
  getTree() {
    return this.tree;
  }
  /**
   * One-click build: fetches source, builds tree, runs plugins.
   * Think of it like `npm run build`, but for trees.
   */
  async buildTree() {
    await this.treeBuilder();
    await this.applyPlugins();
    if (!this.config.disableContentPreload) {
      await preloadTreeContent(this.tree);
    }
    return this.buildResult;
  }
  /**
   * Flattens the tree and returns only file nodes.
   * Ideal for querying, indexing, or just skipping the forest to find your leaf.
   */
  async buildFlat() {
    await this.treeBuilder();
    await this.applyPlugins();
    const flatNodes = flattenTree(this.tree).filter(
      (node) => node.type === "file"
    );
    if (!this.config.disableContentPreload) {
      await preloadFlatNodesContent(flatNodes);
    }
    return {
      head: {},
      nodes: flatNodes,
      foot: {
        source: this.config.source.name,
        pluginNames: this.config.plugins.map((p) => p.name)
      }
    };
  }
  use(base) {
    if (base && base instanceof BasePlugin) {
      this.config.plugins.push(base);
    }
    if (base && base instanceof BaseSource) {
      this.config.source = base;
    }
  }
  async query() {
    const { nodes } = await this.buildFlat();
    return new QueryContext(nodes);
  }
};
export {
  DocuifyEngine
};