homarr/apps/docs/scripts/verify-algolia-search.mjs

const APP_ID = "N69WSPZTID";
const API_KEY = "b2b00f4ed8ca3dc87b5d211c55121416";
const DOCSEARCH_INDEX = "Docusaurus";
const MARKDOWN_INDEX = "markdown";
const MIN_DOCSEARCH_HITS = 100;
const MIN_MARKDOWN_HITS = 10;

const DOCSEARCH_FACETS = ["docusaurus_tag", "language", "lang", "version", "type"];

const SEARCH_CASES = [
  { term: "docker", minHits: 1 },
  { term: "coolify", minHits: 1 },
  { term: "jellyseerr", minHits: 1 },
  { term: "keyboard shortcuts", minHits: 1 },
  { term: "version 0.12", minHits: 1 },
];

const STALE_URL_PATTERN = /\/docs\/(next|\d+(?:\.\d+)+)\//;

async function algoliaQuery(index, body) {
  const response = await fetch(`https://${APP_ID}-dsn.algolia.net/1/indexes/${index}/query`, {
    method: "POST",
    headers: {
      "X-Algolia-Application-Id": APP_ID,
      "X-Algolia-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`Algolia query on "${index}" failed: HTTP ${response.status}`);
  }

  return response.json();
}

function reportLine(ok, message) {
  const prefix = ok ? "OK" : "FAIL";
  console.log(`${prefix}: ${message}`);
  return ok;
}

async function resolveDocsearchIndex() {
  const candidates = [DOCSEARCH_INDEX, `${DOCSEARCH_INDEX}.tmp`];

  for (const index of candidates) {
    const result = await algoliaQuery(index, { query: "", hitsPerPage: 0 });
    const hitCount = result.nbHits ?? 0;
    if (hitCount >= MIN_DOCSEARCH_HITS) {
      return { index, hitCount };
    }
  }

  const fallback = await algoliaQuery(DOCSEARCH_INDEX, { query: "", hitsPerPage: 0 });
  return { index: DOCSEARCH_INDEX, hitCount: fallback.nbHits ?? 0 };
}

async function resolveMarkdownIndex() {
  const candidates = [MARKDOWN_INDEX, `${MARKDOWN_INDEX}.tmp`];

  for (const index of candidates) {
    const result = await algoliaQuery(index, { query: "", hitsPerPage: 0 });
    const hitCount = result.nbHits ?? 0;
    if (hitCount >= MIN_MARKDOWN_HITS) {
      return { index, hitCount };
    }
  }

  const fallback = await algoliaQuery(MARKDOWN_INDEX, { query: "", hitsPerPage: 0 });
  return { index: MARKDOWN_INDEX, hitCount: fallback.nbHits ?? 0 };
}

async function verifyDocsearchIndex(index, hitCount) {
  let ok = reportLine(
    hitCount >= MIN_DOCSEARCH_HITS,
    `index "${index}" has ${hitCount} records (need >= ${MIN_DOCSEARCH_HITS})`,
  );

  const sample = await algoliaQuery(index, {
    query: "docker",
    hitsPerPage: 1,
    attributesToRetrieve: DOCSEARCH_FACETS,
  });

  const record = sample.hits?.[0] ?? {};
  const recordFields = ["docusaurus_tag", "language", "lang", "version", "type"];
  for (const field of recordFields) {
    const present = record[field] !== undefined && record[field] !== null;
    ok = reportLine(present, `records include "${field}"`) && ok;
  }

  for (const searchCase of SEARCH_CASES) {
    const result = await algoliaQuery(index, {
      query: searchCase.term,
      hitsPerPage: 5,
      attributesToRetrieve: ["url"],
    });

    const caseHits = result.nbHits ?? 0;
    ok =
      reportLine(
        caseHits >= searchCase.minHits,
        `"${searchCase.term}" returns ${caseHits} hits (need >= ${searchCase.minHits})`,
      ) && ok;

    const staleUrls = (result.hits ?? []).map((hit) => hit.url).filter((url) => STALE_URL_PATTERN.test(url));

    ok =
      reportLine(
        staleUrls.length === 0,
        `"${searchCase.term}" has no stale versioned URLs (${staleUrls.length} stale)`,
      ) && ok;
  }

  return ok;
}

async function verifyMarkdownIndex(index, hitCount) {
  let ok = reportLine(
    hitCount >= MIN_MARKDOWN_HITS,
    `markdown index "${index}" has ${hitCount} records (need >= ${MIN_MARKDOWN_HITS})`,
  );

  const coolify = await algoliaQuery(index, {
    query: "coolify",
    hitsPerPage: 3,
    attributesToRetrieve: ["url", "title", "heading", "text"],
  });

  ok =
    reportLine((coolify.nbHits ?? 0) >= 1, `markdown index "${index}" returns coolify (${coolify.nbHits ?? 0} hits)`) &&
    ok;

  const sample = coolify.hits?.[0];
  ok = reportLine(Boolean(sample?.text?.length), `markdown records include chunked text content`) && ok;

  return ok;
}

async function main() {
  console.log("Verifying Algolia DocSearch + markdown indices...\n");

  const docsearch = await resolveDocsearchIndex();
  console.log(`Using DocSearch index: ${docsearch.index}\n`);
  const docsearchOk = await verifyDocsearchIndex(docsearch.index, docsearch.hitCount);

  console.log("");
  const markdown = await resolveMarkdownIndex();
  console.log(`Using markdown index: ${markdown.index}\n`);
  const markdownOk = await verifyMarkdownIndex(markdown.index, markdown.hitCount);

  const allOk = docsearchOk && markdownOk;
  console.log("");
  console.log(
    allOk
      ? "All checks passed."
      : "Some checks failed — ensure the crawler config in docsearch.config.js is applied and a full recrawl has finished.",
  );
  process.exit(allOk ? 0 : 1);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});