Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

20.0 KB
Raw Blame
import type { IncomingMessage, ServerResponse } from 'node:http';
import type { Hocuspocus } from '@hocuspocus/server';
import {
  BacklinkCountsSuccessSchema,
  BacklinksSuccessSchema,
  DeadLinksSuccessSchema,
  EmptyRequestSchema,
  ForwardLinksSuccessSchema,
  HubsSuccessSchema,
  LinkGraphSuccessSchema,
  OrphansSuccessSchema,
  SuggestLinksSuccessSchema,
  TagsForNameSuccessSchema,
  TagsListSuccessSchema,
} from '@inkeep/open-knowledge-core';
import { parseSkillBundleDocAnyScope } from '../backlink-index.ts';
import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import {
  type DerivedDocumentIndexApiPort,
  type DerivedGraphNode,
  isDerivedOrphanMode,
  isLocalTargetIndexNotReadyError,
} from '../derived-document-index.ts';
import type { FileIndexEntry } from '../file-watcher.ts';
import { toForwardLinkLocalTargets } from '../local-target-assessment.ts';
import type { FrontmatterMetadata } from '../page-identity.ts';
import { isInternalBundleSkillName } from '../skill-bundles.ts';
import { SuggestLinksTargetNotFoundError, suggestLinks } from '../suggest-links.ts';
import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { withValidation } from './request-validation.ts';
import { successResponse } from './success-response.ts';

export interface LinkGraphRouteDeps {
  hocuspocus: Hocuspocus;
  derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;
  getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
  isSafeDocName: (docName: string) => boolean;
  readPageTitleForDocName: (docName: string) => string;
  readPageTitleForLinkedDocName: (docName: string, admitted: Set<string>) => string;
  readFrontmatterMetadataForLinkedDocName: (
    docName: string,
    admitted: Set<string>,
  ) => FrontmatterMetadata;
  collectAdmittedDocNames: () => Promise<Set<string>>;
  resolveAlias: (docName: string) => string;
  respondToDerivedIndexQueryFailure: (
    res: ServerResponse,
    err: unknown,
    options: { handler: string; failureTitle: string },
  ) => void;
}

export function createLinkGraphRoutes(deps: LinkGraphRouteDeps): ApiRouteGroup {
  const {
    hocuspocus,
    derivedDocumentIndex,
    getFileIndex,
    isSafeDocName,
    readPageTitleForDocName,
    readPageTitleForLinkedDocName,
    readFrontmatterMetadataForLinkedDocName,
    collectAdmittedDocNames,
    resolveAlias,
    respondToDerivedIndexQueryFailure,
  } = deps;

  const handleBacklinks = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'backlinks' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const docName = url.searchParams.get('docName');
        if (!docName) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
            handler: 'backlinks',
          });
          return;
        }
        if (!isSafeDocName(docName)) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
            handler: 'backlinks',
          });
          return;
        }
        const backlinks = (await derivedDocumentIndex.getBacklinks(docName)).map((entry) => ({
          source: entry.source,
          anchor: entry.anchor,
          title: readPageTitleForDocName(entry.source),
          snippet: entry.snippet,
        }));
        successResponse(
          res,
          200,
          BacklinksSuccessSchema,
          { docName, backlinks },
          { handler: 'backlinks' },
        );
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'backlinks',
          failureTitle: 'Failed to read backlinks.',
        });
      }
    },
    { handler: 'backlinks', method: 'GET', skipBodyParse: true },
  );

  const handleBacklinkCounts = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'backlink-counts' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const raw = url.searchParams.get('docNames');
        if (!raw) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docNames parameter.', {
            handler: 'backlink-counts',
          });
          return;
        }
        const docNames = raw
          .split(',')
          .map((docName) => docName.trim())
          .filter((docName) => docName && isSafeDocName(docName));
        const counts = await derivedDocumentIndex.getBacklinkCounts(docNames);
        successResponse(
          res,
          200,
          BacklinkCountsSuccessSchema,
          { counts },
          { handler: 'backlink-counts' },
        );
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'backlink-counts',
          failureTitle: 'Failed to read backlink counts.',
        });
      }
    },
    { handler: 'backlink-counts', method: 'GET', skipBodyParse: true },
  );

  const handleForwardLinks = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'forward-links' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const docName = url.searchParams.get('docName');
        if (!docName) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
            handler: 'forward-links',
          });
          return;
        }
        if (!isSafeDocName(docName)) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
            handler: 'forward-links',
          });
          return;
        }
        const admitted = await collectAdmittedDocNames();
        const forwardLinks = (await derivedDocumentIndex.getForwardLinkEntries(docName)).map(
          (entry) =>
            entry.kind === 'doc'
              ? {
                  kind: 'doc' as const,
                  docName: entry.target,
                  anchor: entry.anchor,
                  title: readPageTitleForLinkedDocName(entry.target, admitted),
                  snippet: entry.snippet,
                }
              : {
                  kind: 'external' as const,
                  url: entry.url,
                  title: entry.label ?? entry.url,
                  snippet: entry.snippet,
                },
        );
        let localTargets: ReturnType<typeof toForwardLinkLocalTargets> | undefined;
        try {
          const localTargetSources = await derivedDocumentIndex.getLocalTargetAssessmentsForSources(
            [docName],
          );
          localTargets = toForwardLinkLocalTargets(
            localTargetSources.flatMap((entry) => entry.assessments),
          );
        } catch (error) {
          if (!isLocalTargetIndexNotReadyError(error)) throw error;
        }
        successResponse(
          res,
          200,
          ForwardLinksSuccessSchema,
          { docName, forwardLinks, ...(localTargets ? { localTargets } : {}) },
          { handler: 'forward-links' },
        );
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'forward-links',
          failureTitle: 'Failed to read forward links.',
        });
      }
    },
    { handler: 'forward-links', method: 'GET', skipBodyParse: true },
  );

  const handleLinkGraph = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'link-graph' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const docName = url.searchParams.get('docName');
        if (docName && !isSafeDocName(docName)) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
            handler: 'link-graph',
          });
          return;
        }

        const rawDegrees = url.searchParams.get('degrees');
        if (rawDegrees && !docName) {
          errorResponse(
            res,
            400,
            'urn:ok:error:invalid-request',
            'docName is required when degrees is provided.',
            { handler: 'link-graph' },
          );
          return;
        }

        let nodes: DerivedGraphNode[];
        let links: Array<{ source: string; target: string }>;

        if (rawDegrees && docName) {
          const degrees = Number.parseInt(rawDegrees, 10);
          if (!Number.isFinite(degrees) || degrees < 0) {
            errorResponse(
              res,
              400,
              'urn:ok:error:invalid-request',
              'degrees must be a non-negative integer.',
              { handler: 'link-graph' },
            );
            return;
          }

          ({ nodes, links } = await derivedDocumentIndex.getLinkGraphNeighborhood(
            docName,
            degrees,
          ));
        } else {
          ({ nodes, links } = await derivedDocumentIndex.getLinkGraph());
        }

        const admitted = await collectAdmittedDocNames();
        const enrichedNodes = nodes.map((node) => {
          if (node.kind === 'doc') {
            const meta = readFrontmatterMetadataForLinkedDocName(node.docName, admitted);
            const bundle = parseSkillBundleDocAnyScope(node.docName);
            return {
              id: node.id,
              kind: 'doc' as const,
              docName: node.docName,
              anchor: node.anchor ?? null,
              label: readPageTitleForLinkedDocName(node.docName, admitted),
              cluster: meta.cluster ?? null,
              category: meta.category ?? null,
              tags: meta.tags ?? null,
              ...(bundle !== null && isInternalBundleSkillName(bundle.name)
                ? { managed: true as const }
                : {}),
            };
          }
          return {
            id: node.id,
            kind: 'external' as const,
            url: node.url,
            label: node.label ?? node.url,
          };
        });
        successResponse(
          res,
          200,
          LinkGraphSuccessSchema,
          { nodes: enrichedNodes, links },
          { handler: 'link-graph' },
        );
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'link-graph',
          failureTitle: 'Failed to read link graph.',
        });
      }
    },
    { handler: 'link-graph', method: 'GET', skipBodyParse: true },
  );

  const handleDeadLinks = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'dead-links' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const sourceDocNames = url.searchParams.getAll('sourceDocName');
        if (sourceDocNames.some((docName) => docName.length === 0 || !isSafeDocName(docName))) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourceDocName.', {
            handler: 'dead-links',
          });
          return;
        }

        const sourceDocNameFilter = sourceDocNames.length
          ? [...new Set(sourceDocNames.map((docName) => resolveAlias(docName)))]
          : undefined;
        const deadLinks = await derivedDocumentIndex.getDeadLinks(
          await collectAdmittedDocNames(),
          sourceDocNameFilter,
        );

        successResponse(
          res,
          200,
          DeadLinksSuccessSchema,
          {
            deadLinks: deadLinks.map((entry) => ({
              target: entry.target,
              sources: entry.sources.map((sourceEntry) => ({
                source: sourceEntry.source,
                title: readPageTitleForDocName(sourceEntry.source),
                snippet: sourceEntry.snippet,
              })),
            })),
          },
          { handler: 'dead-links' },
        );
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'dead-links',
          failureTitle: 'Failed to read dead links.',
        });
      }
    },
    { handler: 'dead-links', method: 'GET', skipBodyParse: true },
  );

  const handleOrphans = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'orphans' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const mode = url.searchParams.get('mode') ?? 'both';
        if (!isDerivedOrphanMode(mode)) {
          errorResponse(
            res,
            400,
            'urn:ok:error:invalid-request',
            'Invalid orphan mode. Allowed values: incoming, outgoing, both.',
            { handler: 'orphans' },
          );
          return;
        }

        const orphans = (
          await derivedDocumentIndex.getOrphans([...getFileIndex().keys()], mode)
        ).map((docName) => ({
          docName,
          title: readPageTitleForDocName(docName),
        }));
        successResponse(res, 200, OrphansSuccessSchema, { orphans }, { handler: 'orphans' });
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'orphans',
          failureTitle: 'Failed to read orphan pages.',
        });
      }
    },
    { handler: 'orphans', method: 'GET', skipBodyParse: true },
  );

  const handleHubs = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:backlink-index-not-configured',
          'Backlink index is not configured.',
          { handler: 'hubs' },
        );
        return;
      }
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const rawLimit = url.searchParams.get('limit');
        const parsed = rawLimit ? Number.parseInt(rawLimit, 10) : 20;
        const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 20;
        const admitted = await collectAdmittedDocNames();
        const hubs = (await derivedDocumentIndex.getHubs(limit)).map((hub) => ({
          docName: hub.docName,
          title: readPageTitleForLinkedDocName(hub.docName, admitted),
          count: hub.count,
        }));
        successResponse(res, 200, HubsSuccessSchema, { hubs }, { handler: 'hubs' });
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'hubs',
          failureTitle: 'Failed to read hub pages.',
        });
      }
    },
    { handler: 'hubs', method: 'GET', skipBodyParse: true },
  );

  const handleSuggestLinks = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      try {
        const url = new URL(req.url ?? '', 'http://localhost');
        const docName = url.searchParams.get('docName');
        if (!docName) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
            handler: 'suggest-links',
          });
          return;
        }
        if (!isSafeDocName(docName)) {
          errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
            handler: 'suggest-links',
          });
          return;
        }
        if (isSystemDoc(docName) || isConfigDoc(docName)) {
          errorResponse(
            res,
            400,
            'urn:ok:error:reserved-doc-name',
            `'${docName}' is a reserved document name.`,
            { handler: 'suggest-links' },
          );
          return;
        }

        const result = await suggestLinks({
          hocuspocus,
          fileIndex: getFileIndex(),
          docName,
        });
        successResponse(res, 200, SuggestLinksSuccessSchema, result, { handler: 'suggest-links' });
      } catch (error) {
        if (error instanceof SuggestLinksTargetNotFoundError) {
          errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Page not found.', {
            handler: 'suggest-links',
            cause: error,
          });
          return;
        }
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to suggest links.', {
          handler: 'suggest-links',
          cause: error,
        });
      }
    },
    { handler: 'suggest-links', method: 'GET', skipBodyParse: true },
  );

  const handleTagsList = withValidation(
    EmptyRequestSchema,
    async (_req, res) => {
      if (!derivedDocumentIndex) {
        errorResponse(
          res,
          503,
          'urn:ok:error:tag-index-not-configured',
          'Tag index not configured.',
          { handler: 'tags-list' },
        );
        return;
      }
      try {
        const tags = await derivedDocumentIndex.getAllTags();
        successResponse(res, 200, TagsListSuccessSchema, { tags }, { handler: 'tags-list' });
      } catch (e) {
        respondToDerivedIndexQueryFailure(res, e, {
          handler: 'tags-list',
          failureTitle: 'Failed to read tags.',
        });
      }
    },
    { handler: 'tags-list', method: 'GET', skipBodyParse: true },
  );

  async function handleTagsForName(
    req: IncomingMessage,
    res: ServerResponse,
    rawName: string,
  ): Promise<void> {
    if (req.method !== 'GET') {
      errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
        handler: 'tags-for-name',
        extraHeaders: { Allow: 'GET' },
      });
      return;
    }
    if (!derivedDocumentIndex) {
      errorResponse(
        res,
        503,
        'urn:ok:error:tag-index-not-configured',
        'Tag index not configured.',
        { handler: 'tags-for-name' },
      );
      return;
    }
    let name: string;
    try {
      name = decodeURIComponent(rawName);
    } catch (uriErr) {
      errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid tag name encoding.', {
        handler: 'tags-for-name',
        cause: uriErr,
      });
      return;
    }
    if (!name) {
      errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing tag name.', {
        handler: 'tags-for-name',
      });
      return;
    }
    try {
      const docs = (await derivedDocumentIndex.getDocsForTagWithMatches(name)).map(
        ({ docName, matchingTags }) => ({
          docName,
          title: readPageTitleForDocName(docName),
          matchingTags,
          snippet: null,
        }),
      );
      successResponse(
        res,
        200,
        TagsForNameSuccessSchema,
        { name, docs },
        {
          handler: 'tags-for-name',
        },
      );
    } catch (e) {
      respondToDerivedIndexQueryFailure(res, e, {
        handler: 'tags-for-name',
        failureTitle: 'Failed to read tag membership.',
      });
    }
  }

  const routes = {
    '/api/backlinks': handleBacklinks,
    '/api/backlink-counts': handleBacklinkCounts,
    '/api/forward-links': handleForwardLinks,
    '/api/link-graph': handleLinkGraph,
    '/api/dead-links': handleDeadLinks,
    '/api/orphans': handleOrphans,
    '/api/hubs': handleHubs,
    '/api/tags': handleTagsList,
    '/api/suggest-links': handleSuggestLinks,
  } satisfies ApiRouteRecord;

  return createApiRouteGroup(routes, {
    dynamic: {
      prefix: '/api/tags/',
      template: '/api/tags/:name',
      dispatch: (rawName) =>
        rawName ? (req, res) => handleTagsForName(req, res, rawName) : undefined,
    },
  });
}