export type QualityGateCategory =
  | "links"
  | "anchors"
  | "routes"
  | "assets"
  | "mdx"
  | "navigation"
  | "openapi"
  | "codeSamples"
  | "provenance"
  | "aiGrounding"
  | "content"
  | "search"
  | "llms"
  | "security"
  | "privacy"
  | "performance";

export type QualityGateResult = {
  gateId: string;
  category: QualityGateCategory;
  status: "pass" | "warning" | "fail" | "skipped";
  diagnostics: Diagnostic[];
  stats?: Record<string, number>;
};

export type QualityReport = {
  schemaVersion: "quality-report/v1";
  status: "pass" | "warning" | "fail";
  results: QualityGateResult[];
  summary: QualitySummary;
};

export type QualitySummary = {
  errors: number;
  warnings: number;
  info: number;
  skipped: number;
};

export type QualityGatePolicy = {
  gateId: string;
  enabled: boolean;
  failOn: Array<"error" | "warning">;
  mode: "off" | "warn" | "strict";
};

{
  "quality": {
    "mode": "strict",
    "gates": {
      "links.internal": "error",
      "links.external": "warning",
      "provenance.stale": "error",
      "content.headingHierarchy": "warning",
      "ai.unsupportedClaims": "error"
    }
  }
}

export type QualityGate = {
  id: string;
  category: QualityGateCategory;
  run(input: QualityGateInput): Promise<QualityGateResult>;
};

export type QualityGateInput = {
  projectRoot: string;
  config: NormalizedConfig;
  pageManifest: PageManifest;
  routeIndex: RouteIndex;
  compiledPages: CompiledPage[];
  nav: NavTree;
  assets: AssetManifest;
  knowledgeStore: KnowledgeStore;
  buildContext: BuildContext;
};

export async function runQualityGates(
  gates: QualityGate[],
  input: QualityGateInput,
  policy: QualityPolicy
): Promise<QualityReport> {
  const results: QualityGateResult[] = [];

  for (const gate of gates) {
    if (!isGateEnabled(gate.id, policy)) {
      results.push({
        gateId: gate.id,
        category: gate.category,
        status: "skipped",
        diagnostics: [],
      });
      continue;
    }

    const result = await gate.run(input);
    results.push(applyGatePolicy(result, policy));
  }

  return aggregateQualityReport(results);
}

export type LinkReference = {
  id: string;
  sourcePageId?: PageId;
  sourcePath: string;
  sourceBlockId?: string;
  href: string;
  text?: string;
  kind:
    | "markdown"
    | "mdxComponent"
    | "nav"
    | "redirect"
    | "asset"
    | "image"
    | "openapi"
    | "llms";
  location?: SourceLocation;
};

export type NormalizedLink = {
  original: LinkReference;
  target: LinkTarget;
};

export type LinkTarget =
  | { type: "internalRoute"; route: RoutePath; anchor?: string }
  | { type: "externalUrl"; url: string }
  | { type: "asset"; path: string }
  | { type: "mailto"; address: string }
  | { type: "tel"; value: string }
  | { type: "fragment"; anchor: string }
  | { type: "unknown"; reason: string };

[Quickstart](/quickstart)
[Section](#configure-openapi)
[External](https://example.com)

![Logo](/assets/logo.svg)

<Card title="Quickstart" href="/quickstart" />

export type ComponentLinkExtractor = {
  componentName: string;
  extractLinks(node: MdxJsxElementNode): LinkReference[];
};

export type ComponentSpec = {
  name: string;
  linkProps?: string[];
};

export function normalizeLinkReference(
  ref: LinkReference,
  page: CompiledPage,
  config: NormalizedConfig
): NormalizedLink {
  const href = ref.href.trim();

  if (href.startsWith("#")) {
    return {
      original: ref,
      target: { type: "fragment", anchor: href.slice(1) },
    };
  }

  if (href.startsWith("mailto:")) {
    return { original: ref, target: { type: "mailto", address: href.slice("mailto:".length) } };
  }

  if (href.startsWith("tel:")) {
    return { original: ref, target: { type: "tel", value: href.slice("tel:".length) } };
  }

  if (/^https?:\/\//.test(href)) {
    return { original: ref, target: { type: "externalUrl", url: href } };
  }

  if (href.startsWith("/")) {
    const { route, anchor } = splitRouteAnchor(href);
    return { original: ref, target: { type: "internalRoute", route, anchor } };
  }

  if (isAssetLike(href)) {
    return { original: ref, target: { type: "asset", path: resolveRelativeAsset(page.route, href) } };
  }

  const { route, anchor } = splitRouteAnchor(resolveRelativeRoute(page.route, href));
  return { original: ref, target: { type: "internalRoute", route, anchor } };
}

export function checkInternalRoute(
  link: NormalizedLink,
  routeIndex: RouteIndex
): Diagnostic[] {
  if (link.target.type !== "internalRoute") return [];

  const route = routeIndex.get(link.target.route);

  if (!route) {
    return [{
      code: "link.internal.routeNotFound",
      severity: "error",
      category: "links",
      message: `Internal link points to missing route: ${link.target.route}.`,
      location: link.original.location,
      hint: "Update the href or add a page for this route.",
    }];
  }

  if (link.target.anchor && !route.anchors.has(link.target.anchor)) {
    return [{
      code: "link.internal.anchorNotFound",
      severity: "error",
      category: "links",
      message: `Internal link points to missing anchor: #${link.target.anchor}.`,
      location: link.original.location,
      hint: `Available anchors include: ${[...route.anchors].slice(0, 5).join(", ")}`,
    }];
  }

  return [];
}

export function headingToAnchor(text: string): string {
  return slugifyHeading(text);
}

export type RouteRecord = {
  route: RoutePath;
  pageId: PageId;
  sourcePath: string;
  anchors: Set<string>;
};

warning content.heading.duplicateAnchor
Multiple headings produce anchor #configuration.

## Configure OpenAPI {#configure-openapi}

export type AnchorAlias = {
  pageId: PageId;
  alias: string;
  targetAnchor: string;
};

{
  "redirects": [
    { "from": "/old-quickstart", "to": "/quickstart" }
  ]
}

export function detectRedirectLoops(redirects: RedirectRule[]): Diagnostic[] {
  const map = new Map(redirects.map((r) => [r.from, r.to]));

  const diagnostics: Diagnostic[] = [];

  for (const redirect of redirects) {
    const seen = new Set<string>();
    let current = redirect.from;

    while (map.has(current)) {
      if (seen.has(current)) {
        diagnostics.push({
          code: "redirect.loop",
          severity: "error",
          category: "routes",
          message: `Redirect loop detected starting at ${redirect.from}.`,
        });
        break;
      }

      seen.add(current);
      current = map.get(current)!;
    }
  }

  return diagnostics;
}

error asset.missing
Image /assets/architecture.svg was referenced but not found.

warning asset.image.missingAlt
Image is missing alt text.

{
  "quality": {
    "externalLinks": {
      "mode": "fast",
      "timeoutMs": 5000,
      "maxConcurrency": 8,
      "retry": 1,
      "allowlist": ["https://github.com/**"],
      "ignore": ["https://localhost/**"]
    }
  }
}

export type ExternalLinkCheckResult = {
  url: string;
  status:
    | "ok"
    | "redirect"
    | "broken"
    | "timeout"
    | "skipped"
    | "blocked"
    | "unknown";
  statusCode?: number;
  finalUrl?: string;
  error?: string;
  checkedAt: string;
};

warning link.external.redirect
External link redirects from A to B.

error link.external.broken
External link returned 404.

export type ExternalLinkCacheEntry = {
  url: string;
  result: ExternalLinkCheckResult;
  expiresAt: string;
};

{
  "quality": {
    "externalLinks": {
      "cacheTtlHours": 24
    }
  }
}

export async function runLinkChecker(input: LinkCheckerInput): Promise<QualityGateResult> {
  const refs = extractAllLinks(input.compiledPages, input.nav);
  const normalized = refs.map((ref) => normalizeLinkReference(ref, pageForRef(ref), input.config));

  const diagnostics = [
    ...normalized.flatMap((link) => checkInternalRoute(link, input.routeIndex)),
    ...normalized.flatMap((link) => checkAssetLink(link, input.assets)),
    ...await checkExternalLinks(normalized, input.config),
  ];

  return {
    gateId: "links",
    category: "links",
    status: diagnostics.some((d) => d.severity === "error") ? "fail" : "pass",
    diagnostics,
    stats: {
      links: refs.length,
      internal: normalized.filter((l) => l.target.type === "internalRoute").length,
      external: normalized.filter((l) => l.target.type === "externalUrl").length,
    },
  };
}

error nav.page.notFound
Navigation references missing page: /reference/configuration.

warning nav.group.tooLarge
Navigation group "API Reference" has 213 direct children.

export function checkFrontmatter(page: CompiledPage): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];

  if (!page.frontmatter.title) {
    diagnostics.push({
      code: "frontmatter.title.missing",
      severity: "error",
      category: "content",
      message: "Page frontmatter is missing title.",
      location: { path: page.sourcePath },
    });
  }

  if (!page.frontmatter.description) {
    diagnostics.push({
      code: "frontmatter.description.missing",
      severity: "warning",
      category: "content",
      message: "Page frontmatter is missing description.",
      location: { path: page.sourcePath },
    });
  }

  return diagnostics;
}

export function checkHeadingHierarchy(page: CompiledPage): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];
  let previousLevel = 1;

  for (const heading of page.headings) {
    if (heading.level > previousLevel + 1) {
      diagnostics.push({
        code: "content.heading.skippedLevel",
        severity: "warning",
        category: "content",
        message: `Heading jumps from H${previousLevel} to H${heading.level}.`,
        location: heading.location,
      });
    }

    previousLevel = heading.level;
  }

  return diagnostics;
}

warning content.section.empty
Section "Troubleshooting" has no content.

export function checkHowToPattern(page: CompiledPage): Diagnostic[] {
  const headings = page.headings.map((h) => h.text.toLowerCase());
  const hasVerify = headings.some((h) => h.includes("verify") || h.includes("validate"));

  if (!hasVerify) {
    return [{
      code: "content.howTo.missingVerification",
      severity: "warning",
      category: "content",
      message: "How-to page should include a verification section.",
      location: { path: page.sourcePath },
    }];
  }

  return [];
}

export function checkDuplicateTitles(pages: CompiledPage[]): Diagnostic[] {
  const byTitle = new Map<string, CompiledPage[]>();

  for (const page of pages) {
    const key = normalizeTitleKey(page.frontmatter.title);
    byTitle.set(key, [...(byTitle.get(key) ?? []), page]);
  }

  return [...byTitle.entries()].flatMap(([title, group]) => {
    if (group.length <= 1) return [];

    return [{
      code: "content.title.duplicate",
      severity: "warning",
      category: "content",
      message: `Multiple pages use similar title: ${title}.`,
      hint: group.map((p) => p.route).join(", "),
    }];
  });
}

export async function runStaleProvenanceGate(input: QualityGateInput): Promise<QualityGateResult> {
  const stale = await findStalePages(input.knowledgeStore);

  const diagnostics = stale.map((item) => ({
    code: "provenance.page.stale",
    severity: item.public ? "error" : "warning",
    category: "provenance",
    message: `Page ${item.route} is stale: ${item.reason}.`,
    location: { path: item.sourcePath },
  }));

  return gateResult("provenance.stale", "provenance", diagnostics);
}

error ai.claim.unsupported
Generated claim in block "build-output" is unsupported by evidence.

error ai.review.required
AI-generated page requires human review before publishing.

error api.operationRef.notFound
ApiOperation component references unknown operationId createUser.

error codeSample.secret.detected
Code sample contains secret-like value.

warning codeSample.notVerified
Code sample was generated but not execution-verified.

error security.secretLike
Page contains a secret-like token.

error security.publicOutput.privateArtifact
Public build output includes private DocForge artifact.

error privacy.internalArtifactPublished
Internal artifact GET /internal/reindex is included in public documentation.

warning search.page.missing
Public page /quickstart has no search document.

warning search.index.tooLarge
Search index is 18 MB, exceeding configured budget of 10 MB.

error llms.privatePageIncluded
llms.txt includes hidden/internal page /internal/runbooks.

warning llms.export.tooLarge
llms-full.txt exceeds configured size budget.

{
  "quality": {
    "budgets": {
      "maxSearchIndexBytes": 10485760,
      "maxPageHtmlBytes": 524288,
      "maxAssetBytes": 2097152
    }
  }
}

warning performance.page.tooLarge
Page /api-reference/big-schema is 1.2 MB.

Broken link.

error link.internal.routeNotFound docs/guides/openapi.mdx:42:12
Internal link points to missing route: /reference/openapi-config

Hint:
Use /reference/configuration#openapi or create a page at /reference/openapi-config.

export function suggestRoutes(missing: RoutePath, routeIndex: RouteIndex): RoutePath[] {
  return [...routeIndex.routes()]
    .map((route) => ({ route, score: similarity(missing, route) }))
    .sort((a, b) => b.score - a.score)
    .slice(0, 5)
    .map((item) => item.route);
}

Did you mean:
- /reference/configuration
- /guides/openapi-reference

docforge check
docforge check --format json
docforge check --format ndjson
docforge check --strict
docforge check --only links
docforge check --only provenance

Quality check failed

Errors:
- link.internal.routeNotFound docs/guides/openapi.mdx:42
- ai.claim.unsupported docs/guides/build.mdx:block build-output

Warnings:
- content.howTo.missingVerification docs/guides/openapi.mdx

docforge check

--strict
--only links,content,provenance
--changed
--format human|json|ndjson
--external-links off|syntax|fast|full
--fail-on-warning

docforge check --changed

.docforge/reports/
  quality-report.json
  link-report.json
  provenance-report.json

CREATE TABLE quality_runs (
  id TEXT PRIMARY KEY,
  started_at TEXT NOT NULL,
  ended_at TEXT,
  status TEXT NOT NULL,
  config_hash TEXT NOT NULL,
  report_json TEXT NOT NULL
);

{
  "quality": {
    "profile": "balanced"
  }
}

{
  "quality": {
    "coverage": {
      "apiEndpoint": 1.0,
      "cliCommand": 1.0,
      "configField": 0.95,
      "publicExport": 0.8
    }
  }
}

error coverage.apiEndpoint.belowThreshold
API endpoint documentation coverage is 96%, below required 100%.

export function qualityReportToWorkflowDecision(report: QualityReport): WorkflowDecision {
  if (report.status === "fail") {
    return {
      status: "fail",
      blockers: report.results.flatMap((r) => r.diagnostics.filter((d) => d.severity === "error")),
      warnings: report.results.flatMap((r) => r.diagnostics.filter((d) => d.severity === "warning")),
    };
  }

  return {
    status: report.status === "warning" ? "warning" : "pass",
    blockers: [],
    warnings: report.results.flatMap((r) => r.diagnostics.filter((d) => d.severity === "warning")),
  };
}

fixtures/link-checker/
  internal-ok/
  internal-missing-route/
  internal-missing-anchor/
  relative-link/
  asset-missing/
  external-syntax-invalid/
  redirect-loop/

it("reports missing internal route", async () => {
  const result = await runLinkCheckerFixture("internal-missing-route");

  expect(result.diagnostics).toContainEqual(
    expect.objectContaining({
      code: "link.internal.routeNotFound",
      severity: "error",
    })
  );
});

fixtures/quality/
  stale-generated-page/
  unsupported-ai-claim/
  secret-in-code-block/
  quickstart-missing-verify/
  public-output-leaks-docforge/
  search-missing-page/
  llms-includes-hidden-page/

it("fails strict quality report for unsupported AI claim", async () => {
  const report = await runQualityFixture("unsupported-ai-claim", strictPolicy());

  expect(report.status).toBe("fail");
});

export type HttpLinkClient = {
  check(url: string, options: LinkCheckOptions): Promise<ExternalLinkCheckResult>;
};

it("reports 404 external link", async () => {
  const client = new FakeLinkClient({
    "https://example.com/missing": { status: "broken", statusCode: 404 },
  });

  const result = await checkExternalLinks(links, config, client);

  expect(result.diagnostics[0].code).toBe("link.external.broken");
});

packages/quality-gates/
  src/
    policy.ts
    runner.ts
    report.ts
    diagnostics.ts
    gates/
      links/
        extract.ts
        normalize.ts
        internal.ts
        external.ts
        assets.ts
        redirects.ts
      content/
        frontmatter.ts
        headings.ts
        page-kind.ts
        duplicates.ts
      navigation.ts
      provenance.ts
      ai-grounding.ts
      openapi.ts
      code-samples.ts
      search.ts
      llms.ts
      security.ts
      privacy.ts
      performance.ts
    reporters/
      human.ts
      json.ts
      ndjson.ts
    __tests__/
      link-internal.test.ts
      link-external.test.ts
      content.test.ts
      provenance.test.ts
      runner.test.ts

load config
scan/index
compile MDX
build route/nav/page manifests
generate virtual pages
run quality gates
if pass:
  render static site
  build search/llms
  run output quality gates
write manifest

Quality warnings:
- Missing anchor #configure-openapi
- Page is stale because config schema changed

export async function runAiGroundingGate(input: QualityGateInput): Promise<QualityGateResult> {
  const diagnostics = await input.knowledgeStore.reviews.listBlockingIssues();

  return gateResult("ai.grounding", "aiGrounding", diagnostics);
}

Docs quality score: 82

Errors:
- 2 broken internal links
- 1 unsupported AI claim

Warnings:
- 3 pages missing descriptions
- 1 external link timeout