Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

6.9 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import "server-only";
import type { AdvancedIndex } from "fumadocs-core/search/server";
import { apiModules } from "@/lib/api-data";
import {
  getDefinitionText,
  getTermText,
  glossaryEntries,
  termSlug,
} from "@carbon/content/glossary";
import { changelogSource, guideSource, source } from "@/lib/source";
import { operationLabel, toolModules } from "@/lib/tools-data";

const GLOSSARY_URL = "/docs/glossary";

/* One Orama index over all four doc surfaces. Each entry is `tag`ged so the single
 * /api/search endpoint can be filtered per surface (the header's All/Guide/Reference/
 * API/Data API pills map to these tags — `tools` is the Carbon API operation catalog,
 * `resources` is the PostgREST Data API). MDX pages reuse the `structuredData` the
 * fumadocs-mdx pipeline already produces (the same field createFromSource read); the
 * generated API/MCP data is shaped into structuredData by hand so column- and
 * parameter-level matches still land the right page. */

type StructuredData = AdvancedIndex["structuredData"];

// Structural shape shared by both MDX loaders' pages — enough to index, no more.
interface IndexablePage {
  url: string;
  data: { title?: string; description?: string; structuredData?: StructuredData };
}

function mdxIndexes(pages: IndexablePage[], tag: string, crumb: string): AdvancedIndex[] {
  return pages.map((page) => ({
    id: page.url,
    url: page.url,
    title: page.data.title ?? page.url,
    description: page.data.description,
    tag,
    breadcrumbs: [crumb],
    structuredData: page.data.structuredData ?? { headings: [], contents: [] },
  }));
}

function toolParamNames(schema: unknown): string[] {
  if (schema && typeof schema === "object" && "properties" in schema) {
    const props = (schema as { properties?: unknown }).properties;
    if (props && typeof props === "object") return Object.keys(props as Record<string, unknown>);
  }
  return [];
}

/**
 * Most operation descriptions are generated by de-camelCasing the function name
 * (`getActiveEmployeeAbilities` -> "get active employee abilities"), so they restate
 * the title and are worth neither the index space nor the result row. Only the
 * handful of hand-written ones say something new.
 */
function isGeneratedDescription(toolName: string, description: string): boolean {
  const fn = toolName.slice(toolName.indexOf("_") + 1);
  const decamelized = fn
    .replace(/([A-Z])/g, " $1")
    .trim()
    .toLowerCase();
  return description.trim().toLowerCase() === decamelized;
}

function toolIndexes(): AdvancedIndex[] {
  return toolModules.flatMap((mod) =>
    mod.tools.map((tool) => {
      const params = toolParamNames(tool.schema);
      const generated = isGeneratedDescription(tool.name, tool.description);
      const contents: StructuredData["contents"] = [];

      // A real description earns a line; a de-camelCased name does not — the title
      // already says it, twice over in the result row.
      if (!generated) {
        contents.push({ heading: undefined, content: tool.description });
      }
      if (params.length) {
        contents.push({
          heading: undefined,
          content: `Parameters: ${params.join(", ")}.`,
        });
      }
      // The full callable name stays searchable, so "items_getMaterial" still hits
      // even though the title shows the short label.
      contents.push({ heading: undefined, content: tool.name });

      return {
        id: `/api/operations/${tool.slug}`,
        url: `/api/operations/${tool.slug}`,
        title: operationLabel(tool.name, mod.slug),
        // Classification is the one fact the title does not carry; the module is
        // already in the breadcrumbs.
        description: generated ? tool.classification : tool.description,
        tag: "tools",
        breadcrumbs: ["API", mod.name],
        structuredData: { headings: [], contents },
      };
    }),
  );
}


function resourceIndexes(): AdvancedIndex[] {
  return apiModules.flatMap((mod) =>
    mod.resources.map((r) => {
      // Endpoint titles become headings whose ids match the page's <section id> anchors,
      // so a heading hit deep-links straight to "List customers" etc.
      const headings: StructuredData["headings"] = r.endpoints.map((e) => ({
        id: e.id,
        content: e.title,
      }));
      // Every field name across the resource's endpoints — a search for a column lands here.
      const fields = Array.from(
        new Set(r.endpoints.flatMap((e) => e.attributes.map((a) => a.name))),
      );
      const contents: StructuredData["contents"] = [
        {
          heading: undefined,
          content: `The ${r.name} ${r.kind} (${r.table}) in the ${mod.name} module.`,
        },
        ...r.endpoints.map((e) => ({
          heading: e.title,
          content: `${e.method} ${e.path} — ${e.description}`,
        })),
      ];
      if (fields.length) {
        contents.push({ heading: undefined, content: `Fields: ${fields.join(", ")}.` });
      }
      return {
        id: `/api/data/${mod.slug}/${r.slug}`,
        url: `/api/data/${mod.slug}/${r.slug}`,
        title: r.name,
        description: r.description,
        tag: "resources",
        breadcrumbs: ["Data API", mod.name],
        structuredData: { headings, contents },
      };
    }),
  );
}

/* The Glossary page renders its terms through the <Glossary> React component, so the
 * MDX pipeline's structuredData captures only the page intro. Build the term index by
 * hand from lib/glossary.ts: every term becomes a heading (id = its row anchor, so a hit
 * deep-links to the term) and its definition the content. */
function glossaryIndex(page: IndexablePage): AdvancedIndex {
  const entries = glossaryEntries();
  return {
    id: page.url,
    url: page.url,
    title: page.data.title ?? "Glossary",
    description: page.data.description,
    tag: "docs",
    breadcrumbs: ["Glossary"],
    structuredData: {
      headings: entries.map((e) => {
        const term = getTermText(e);
        return { id: termSlug(term), content: term };
      }),
      contents: entries.map((e) => ({
        heading: termSlug(getTermText(e)),
        content: getDefinitionText(e),
      })),
    },
  };
}

export function buildSearchIndexes(): AdvancedIndex[] {
  const docsPages = source.getPages() as IndexablePage[];
  const glossaryPage = docsPages.find((p) => p.url === GLOSSARY_URL);
  const otherDocs = docsPages.filter((p) => p.url !== GLOSSARY_URL);

  return [
    ...mdxIndexes(otherDocs, "docs", "Reference"),
    ...(glossaryPage ? [glossaryIndex(glossaryPage)] : []),
    ...mdxIndexes(guideSource.getPages(), "guide", "Guide"),
    // No pill of its own; entries show under All.
    ...mdxIndexes(changelogSource.getPages(), "changelog", "Changelog"),
    ...resourceIndexes(),
    ...toolIndexes(),
  ];
}