@specglass/core 0.0.4 → 0.0.6

package/dist/content/mdx-loader.js

@@ -54,13 +54,16 @@ export function defineDocsCollection(options) {
 export function getSlugFromFilePath(filePath) {
     // Normalize path separators
     let slug = filePath.replace(/\\/g, "/");
-    // Strip leading content/ prefix
+    // Strip leading content/ and/or docs/ prefixes.
+    // In monorepo context, entry.id is "content/docs/getting-started.mdx".
+    // When consumed via npm, the glob loader produces "docs/getting-started.mdx".
     slug = slug.replace(/^content\//, "");
+    slug = slug.replace(/^docs\//, "");
     // Strip file extension (.mdx or .md)
     slug = slug.replace(/\.(mdx|md)$/, "");
     // Handle index files — map to parent directory
     slug = slug.replace(/\/index$/, "");
-    // Handle root index (just "index" after stripping content/)
+    // Handle root index (just "index" after stripping prefixes)
     if (slug === "index") {
         return "";
     }

package/dist/index.d.ts

@@ -19,10 +19,14 @@ export type { NavigationWatcherOptions } from "./navigation/watcher.js";
 export { SpecglassError } from "./errors/specglass-error.js";
 export { parseOpenApiSpec } from "./openapi/parser.js";
 export { transformSpec } from "./openapi/transformer.js";
-export { buildEndpointSlug, buildEndpointId } from "./openapi/utils.js";
+export { buildEndpointSlug, buildErrorEndpointSlug, buildEndpointId } from "./openapi/utils.js";
 export type { ApiEndpoint, ApiEndpointError, ApiExample, ApiMediaType, ApiParameter, ApiRequestBody, ApiResponse, ApiSchema, ApiSecurityRequirement, ParsedOpenApiSpec, } from "./openapi/types.js";
 export { loadOpenApiContent, } from "./content/openapi-loader.js";
 export type { OpenApiLoaderConfig, OpenApiContentEntry, OpenApiLoaderResult, } from "./content/openapi-loader.js";
 export { generateExampleValue, extractMediaTypeExample, } from "./openapi/example-generator.js";
 export { generateCurlExample, generatePythonExample, generateNodeExample, buildRequestUrl, } from "./openapi/code-generator.js";
 export type { CodeExampleOptions } from "./openapi/code-generator.js";
+export { runValidators, toSpecglassError, type ValidationResult, type ValidationSeverity, type ValidatorContext, type Validator, } from "./validation/index.js";
+export { validateLinks } from "./validation/link-validator.js";
+export { validateFrontmatter } from "./validation/frontmatter-validator.js";
+export { validateSpecDrift } from "./validation/spec-drift-validator.js";

package/dist/index.js

@@ -21,8 +21,13 @@ export { SpecglassError } from "./errors/specglass-error.js";
 // OpenAPI
 export { parseOpenApiSpec } from "./openapi/parser.js";
 export { transformSpec } from "./openapi/transformer.js";
-export { buildEndpointSlug, buildEndpointId } from "./openapi/utils.js";
+export { buildEndpointSlug, buildErrorEndpointSlug, buildEndpointId } from "./openapi/utils.js";
 export { loadOpenApiContent, } from "./content/openapi-loader.js";
 // OpenAPI example generation
 export { generateExampleValue, extractMediaTypeExample, } from "./openapi/example-generator.js";
 export { generateCurlExample, generatePythonExample, generateNodeExample, buildRequestUrl, } from "./openapi/code-generator.js";
+// Validation
+export { runValidators, toSpecglassError, } from "./validation/index.js";
+export { validateLinks } from "./validation/link-validator.js";
+export { validateFrontmatter } from "./validation/frontmatter-validator.js";
+export { validateSpecDrift } from "./validation/spec-drift-validator.js";

package/dist/integration.js

@@ -194,6 +194,10 @@ export const specglassIntegration = defineIntegration({
                             rehypePlugins: [rehypeCodeBlocks],
                         },
                     });
+                    params.injectRoute({
+                        pattern: "/",
+                        entrypoint: "@specglass/core/pages/index.astro",
+                    });
                     params.injectRoute({
                         pattern: "/[...slug]",
                         entrypoint: "@specglass/core/pages/[...slug].astro",

package/dist/navigation/builder.d.ts

@@ -7,6 +7,19 @@ import type { NavigationTree } from "../types/navigation.js";
  *   "api-reference"   → "Api Reference"
  */
 export declare function toTitleCase(kebab: string): string;
+/**
+ * Normalize a directory or file name into a URL-safe slug segment.
+ *
+ * Matches Astro glob loader behavior:
+ *   - lowercases the name
+ *   - replaces whitespace runs with a single hyphen
+ *
+ * Examples:
+ *   "Prompt Optimization" → "prompt-optimization"
+ *   "Introduction"        → "introduction"
+ *   "getting-started"     → "getting-started"
+ */
+export declare function slugify(name: string): string;
 /**
  * Build a navigation tree by recursively walking a content directory.
  *

package/dist/navigation/builder.js

@@ -14,6 +14,21 @@ export function toTitleCase(kebab) {
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(" ");
 }
+/**
+ * Normalize a directory or file name into a URL-safe slug segment.
+ *
+ * Matches Astro glob loader behavior:
+ *   - lowercases the name
+ *   - replaces whitespace runs with a single hyphen
+ *
+ * Examples:
+ *   "Prompt Optimization" → "prompt-optimization"
+ *   "Introduction"        → "introduction"
+ *   "getting-started"     → "getting-started"
+ */
+export function slugify(name) {
+    return name.toLowerCase().replace(/\s+/g, "-");
+}
 /**
  * Build a navigation tree by recursively walking a content directory.
  *
@@ -87,10 +102,12 @@ async function buildItems(dirPath, slugPrefix) {
         }
         // Check if entry matches a directory
         if (dirs.includes(entry.key)) {
-            const children = await buildItems(join(dirPath, entry.key), slugPrefix ? `${slugPrefix}/${entry.key}` : entry.key);
+            const dirSlug = slugify(entry.key);
+            const fullSlug = slugPrefix ? `${slugPrefix}/${dirSlug}` : dirSlug;
+            const children = await buildItems(join(dirPath, entry.key), fullSlug);
             result.push({
                 title: entry.title,
-                slug: slugPrefix ? `${slugPrefix}/${entry.key}` : entry.key,
+                slug: fullSlug,
                 type: "section",
                 children,
                 ...(entry.collapsed !== undefined && { collapsed: entry.collapsed }),
@@ -101,10 +118,10 @@ async function buildItems(dirPath, slugPrefix) {
         // Check if entry matches a file
         const matchingFile = files.find((f) => parse(f).name === entry.key);
         if (matchingFile) {
-            const baseName = parse(matchingFile).name;
+            const fileSlug = slugify(parse(matchingFile).name);
             result.push({
                 title: entry.title,
-                slug: slugPrefix ? `${slugPrefix}/${baseName}` : baseName,
+                slug: slugPrefix ? `${slugPrefix}/${fileSlug}` : fileSlug,
                 type: "page",
                 ...(entry.icon !== undefined && { icon: entry.icon }),
             });
@@ -117,19 +134,22 @@ async function buildItems(dirPath, slugPrefix) {
         .sort();
     for (const file of unlistedFiles) {
         const baseName = parse(file).name;
+        const fileSlug = slugify(baseName);
         result.push({
             title: toTitleCase(baseName),
-            slug: slugPrefix ? `${slugPrefix}/${baseName}` : baseName,
+            slug: slugPrefix ? `${slugPrefix}/${fileSlug}` : fileSlug,
             type: "page",
         });
     }
     // Append unlisted directories alphabetically
     const unlistedDirs = dirs.filter((d) => !listedKeys.has(d)).sort();
     for (const dir of unlistedDirs) {
-        const children = await buildItems(join(dirPath, dir), slugPrefix ? `${slugPrefix}/${dir}` : dir);
+        const dirSlug = slugify(dir);
+        const fullSlug = slugPrefix ? `${slugPrefix}/${dirSlug}` : dirSlug;
+        const children = await buildItems(join(dirPath, dir), fullSlug);
         result.push({
             title: toTitleCase(dir),
-            slug: slugPrefix ? `${slugPrefix}/${dir}` : dir,
+            slug: fullSlug,
             type: "section",
             children,
         });
@@ -146,7 +166,8 @@ async function buildAlphabetical(files, dirs, dirPath, slugPrefix) {
     ].sort((a, b) => a.name.localeCompare(b.name));
     const result = [];
     for (const entry of allEntries) {
-        const slug = slugPrefix ? `${slugPrefix}/${entry.name}` : entry.name;
+        const entrySlug = slugify(entry.name);
+        const slug = slugPrefix ? `${slugPrefix}/${entrySlug}` : entrySlug;
         if (entry.isDir) {
             const children = await buildItems(join(dirPath, entry.name), slug);
             result.push({

package/dist/openapi/code-generator.js

@@ -190,10 +190,12 @@ export function generatePythonExample(endpoint, options = DEFAULT_OPTIONS) {
  * Convert JSON string to Python dict syntax (True/False/None).
  */
 function pythonifyJson(json) {
+    // Only replace JSON values (not strings containing these words).
+    // Match `: true`, `: false`, `: null` when followed by comma, newline, or end-of-object/array.
     return json
-        .replace(/: true/g, ": True")
-        .replace(/: false/g, ": False")
-        .replace(/: null/g, ": None");
+        .replace(/: true(?=[,\n\r\s}\]]|$)/g, ": True")
+        .replace(/: false(?=[,\n\r\s}\]]|$)/g, ": False")
+        .replace(/: null(?=[,\n\r\s}\]]|$)/g, ": None");
 }
 /* ------------------------------------------------------------------ */
 /*  Node.js Generator                                                  */

package/dist/openapi/example-generator.js

@@ -21,7 +21,14 @@ export function generateExampleValue(schema, depth = 0) {
     if (depth > MAX_DEPTH) {
         return getTypeDefault(schema.type);
     }
-    // 1. Prefer enum first value
+    // 1. Prefer spec-provided example values (AC6)
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    if (schema.examples && Array.isArray(schema.examples) && schema.examples.length > 0) {
+        return schema.examples[0];
+    }
+    // 2. Prefer enum first value
     if (schema.enum && schema.enum.length > 0) {
         return schema.enum[0];
     }

package/dist/openapi/types.d.ts

@@ -16,6 +16,10 @@ export interface ApiSchema {
     required?: string[];
     enum?: unknown[];
     description?: string;
+    /** Spec-provided example value for this schema */
+    example?: unknown;
+    /** Spec-provided array of example values for this schema */
+    examples?: unknown[];
     /** Original $ref path, preserved for display (e.g., "#/components/schemas/Pet") */
     ref?: string;
     allOf?: ApiSchema[];

package/dist/openapi/utils.d.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import type { ApiEndpoint } from "./types.js";
+import type { ApiEndpoint, ApiEndpointError } from "./types.js";
 /**
  * Build a URL-friendly slug for an API endpoint.
  *
@@ -17,6 +17,18 @@ import type { ApiEndpoint } from "./types.js";
  * // → "pets/get-pets-petId"
  */
 export declare function buildEndpointSlug(endpoint: ApiEndpoint): string;
+/**
+ * Build a URL-friendly slug for an errored API endpoint.
+ *
+ * Uses `_unsupported/` prefix to avoid collisions with valid endpoint slugs.
+ *
+ * Format: `_unsupported/{method}-{sanitized-path}`
+ *
+ * @example
+ * buildErrorEndpointSlug({ method: "get", path: "/pets/{petId}", reason: "...", rawSpec: {} })
+ * // → "_unsupported/get-pets-petId"
+ */
+export declare function buildErrorEndpointSlug(error: ApiEndpointError): string;
 /**
  * Build a unique identifier for an endpoint (used for active-state matching).
  *

package/dist/openapi/utils.js

@@ -23,6 +23,24 @@ export function buildEndpointSlug(endpoint) {
         .replace(/[{}]/g, "");
     return `${tag}/${endpoint.method}-${sanitizedPath}`;
 }
+/**
+ * Build a URL-friendly slug for an errored API endpoint.
+ *
+ * Uses `_unsupported/` prefix to avoid collisions with valid endpoint slugs.
+ *
+ * Format: `_unsupported/{method}-{sanitized-path}`
+ *
+ * @example
+ * buildErrorEndpointSlug({ method: "get", path: "/pets/{petId}", reason: "...", rawSpec: {} })
+ * // → "_unsupported/get-pets-petId"
+ */
+export function buildErrorEndpointSlug(error) {
+    const sanitizedPath = error.path
+        .replace(/^\//, "")
+        .replace(/\//g, "-")
+        .replace(/[{}]/g, "");
+    return `_unsupported/${error.method}-${sanitizedPath}`;
+}
 /**
  * Build a unique identifier for an endpoint (used for active-state matching).
  *

package/dist/validation/frontmatter-validator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Frontmatter validator — validates MDX/MD file frontmatter against the content schema.
+ *
+ * Composable validator following the pattern established in link-validator.ts.
+ * Reuses the existing `frontmatterSchema` Zod schema from content/frontmatter-schema.ts.
+ *
+ * Error codes:
+ *   FRONTMATTER_MISSING_FIELD — Required field not present
+ *   FRONTMATTER_TYPE_MISMATCH — Field present but wrong type
+ *   FRONTMATTER_UNKNOWN_FIELD — Field not in schema (warning)
+ *   FRONTMATTER_PARSE_ERROR   — YAML block is malformed
+ *   FRONTMATTER_INVALID       — Catch-all for other Zod issues
+ */
+import type { ValidationResult, ValidatorContext } from "./types.js";
+/**
+ * Extract raw frontmatter string from file content.
+ *
+ * Frontmatter is the YAML block between the first pair of `---` delimiters
+ * at the top of the file.
+ *
+ * @returns The raw YAML string, or null if no frontmatter block found.
+ */
+export declare function extractFrontmatterRaw(content: string): string | null;
+/**
+ * Parse a raw YAML string into a plain object.
+ *
+ * Uses js-yaml (available as transitive dependency) for YAML parsing.
+ *
+ * @throws Error with a descriptive message if YAML is malformed.
+ */
+export declare function parseFrontmatterYaml(raw: string): Record<string, unknown>;
+/**
+ * Detect unknown frontmatter fields not in the schema.
+ *
+ * Fields starting with `_` (Astro internals) are ignored.
+ * Unknown fields are reported as warnings, not errors.
+ */
+export declare function detectUnknownFields(frontmatter: Record<string, unknown>, filePath: string): ValidationResult[];
+/**
+ * Validate a single file's frontmatter against the schema.
+ *
+ * Returns an array of ValidationResult for all issues found.
+ */
+export declare function validateSingleFile(filePath: string): Promise<ValidationResult[]>;
+/**
+ * Composable frontmatter validator.
+ *
+ * Discovers all MDX/MD files in the content directory and validates
+ * each file's frontmatter against the Zod content schema.
+ *
+ * @param context - Validator context with contentDir
+ * @returns Array of ValidationResult for all frontmatter issues
+ */
+export declare function validateFrontmatter(context: ValidatorContext): Promise<ValidationResult[]>;

package/dist/validation/frontmatter-validator.js

@@ -0,0 +1,197 @@
+/**
+ * Frontmatter validator — validates MDX/MD file frontmatter against the content schema.
+ *
+ * Composable validator following the pattern established in link-validator.ts.
+ * Reuses the existing `frontmatterSchema` Zod schema from content/frontmatter-schema.ts.
+ *
+ * Error codes:
+ *   FRONTMATTER_MISSING_FIELD — Required field not present
+ *   FRONTMATTER_TYPE_MISMATCH — Field present but wrong type
+ *   FRONTMATTER_UNKNOWN_FIELD — Field not in schema (warning)
+ *   FRONTMATTER_PARSE_ERROR   — YAML block is malformed
+ *   FRONTMATTER_INVALID       — Catch-all for other Zod issues
+ */
+import { readFile } from "node:fs/promises";
+import yaml from "js-yaml";
+import { frontmatterSchema } from "../content/frontmatter-schema.js";
+import { discoverContentFiles } from "./link-validator.js";
+/**
+ * Known frontmatter schema keys, derived from the Zod schema shape.
+ * Keys starting with `_` (Astro internals like `_id`, `_collection`) are always allowed.
+ */
+const KNOWN_KEYS = new Set(Object.keys(frontmatterSchema.shape));
+/**
+ * Extract raw frontmatter string from file content.
+ *
+ * Frontmatter is the YAML block between the first pair of `---` delimiters
+ * at the top of the file.
+ *
+ * @returns The raw YAML string, or null if no frontmatter block found.
+ */
+export function extractFrontmatterRaw(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return match ? match[1] : null;
+}
+/**
+ * Parse a raw YAML string into a plain object.
+ *
+ * Uses js-yaml (available as transitive dependency) for YAML parsing.
+ *
+ * @throws Error with a descriptive message if YAML is malformed.
+ */
+export function parseFrontmatterYaml(raw) {
+    const parsed = yaml.load(raw);
+    if (parsed === null || parsed === undefined) {
+        return {};
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Frontmatter must be a YAML mapping, not a scalar or list");
+    }
+    return parsed;
+}
+/**
+ * Map a single Zod issue to a ValidationResult.
+ */
+function zodIssueToResult(issue, filePath) {
+    const fieldPath = issue.path.join(".") || "unknown";
+    // Missing required field
+    if (issue.code === "invalid_type" && issue.received === "undefined") {
+        const hint = fieldPath === "title"
+            ? 'Field \'title\' is required — add `title: "Page Title"` to your frontmatter'
+            : `Field '${fieldPath}' is required`;
+        return {
+            code: "FRONTMATTER_MISSING_FIELD",
+            message: `Missing required field '${fieldPath}' in ${filePath}`,
+            filePath,
+            line: 1,
+            severity: "error",
+            hint,
+        };
+    }
+    // Type mismatch
+    if (issue.code === "invalid_type") {
+        return {
+            code: "FRONTMATTER_TYPE_MISMATCH",
+            message: `Type mismatch for field '${fieldPath}' in ${filePath}: expected ${issue.expected}, got ${issue.received}`,
+            filePath,
+            line: 1,
+            severity: "error",
+            hint: `Field '${fieldPath}' expected type '${issue.expected}', got '${issue.received}'`,
+        };
+    }
+    // Catch-all for other Zod issues
+    return {
+        code: "FRONTMATTER_INVALID",
+        message: `Invalid field '${fieldPath}' in ${filePath}: ${issue.message}`,
+        filePath,
+        line: 1,
+        severity: "error",
+        hint: `Field '${fieldPath}': ${issue.message}`,
+    };
+}
+/**
+ * Detect unknown frontmatter fields not in the schema.
+ *
+ * Fields starting with `_` (Astro internals) are ignored.
+ * Unknown fields are reported as warnings, not errors.
+ */
+export function detectUnknownFields(frontmatter, filePath) {
+    const results = [];
+    for (const key of Object.keys(frontmatter)) {
+        if (key.startsWith("_"))
+            continue;
+        if (!KNOWN_KEYS.has(key)) {
+            results.push({
+                code: "FRONTMATTER_UNKNOWN_FIELD",
+                message: `Unknown frontmatter field '${key}' in ${filePath}`,
+                filePath,
+                line: 1,
+                severity: "warning",
+                hint: `Consider moving to \`custom.${key}\` for forward compatibility`,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Validate a single file's frontmatter against the schema.
+ *
+ * Returns an array of ValidationResult for all issues found.
+ */
+export async function validateSingleFile(filePath) {
+    const results = [];
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch {
+        results.push({
+            code: "FRONTMATTER_PARSE_ERROR",
+            message: `Cannot read file: ${filePath}`,
+            filePath,
+            line: 1,
+            severity: "error",
+            hint: "Verify the file exists and is readable",
+        });
+        return results;
+    }
+    // Extract frontmatter block
+    const raw = extractFrontmatterRaw(content);
+    if (raw === null) {
+        // No frontmatter block — report missing required title
+        results.push({
+            code: "FRONTMATTER_MISSING_FIELD",
+            message: `No frontmatter block found in ${filePath}`,
+            filePath,
+            line: 1,
+            severity: "error",
+            hint: 'Add a frontmatter block with at least `title`: `---\ntitle: "Page Title"\n---`',
+        });
+        return results;
+    }
+    // Parse YAML
+    let parsed;
+    try {
+        parsed = parseFrontmatterYaml(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown YAML parse error";
+        results.push({
+            code: "FRONTMATTER_PARSE_ERROR",
+            message: `Malformed frontmatter in ${filePath}: ${message}`,
+            filePath,
+            line: 1,
+            severity: "error",
+            hint: "Fix the YAML syntax in the frontmatter block",
+        });
+        return results;
+    }
+    // Validate against Zod schema
+    const zodResult = frontmatterSchema.safeParse(parsed);
+    if (!zodResult.success) {
+        for (const issue of zodResult.error.issues) {
+            results.push(zodIssueToResult(issue, filePath));
+        }
+    }
+    // Detect unknown fields (even if Zod validation passed due to .passthrough())
+    results.push(...detectUnknownFields(parsed, filePath));
+    return results;
+}
+/**
+ * Composable frontmatter validator.
+ *
+ * Discovers all MDX/MD files in the content directory and validates
+ * each file's frontmatter against the Zod content schema.
+ *
+ * @param context - Validator context with contentDir
+ * @returns Array of ValidationResult for all frontmatter issues
+ */
+export async function validateFrontmatter(context) {
+    const files = await discoverContentFiles(context.contentDir);
+    const results = [];
+    for (const filePath of files) {
+        const fileResults = await validateSingleFile(filePath);
+        results.push(...fileResults);
+    }
+    return results;
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Validation runner — collects results from composable validators.
+ *
+ * Usage:
+ *   const results = await runValidators([validateLinks, validateFrontmatter], context);
+ */
+import type { ValidationResult, ValidatorContext, Validator } from "./types.js";
+export { type ValidationResult, type ValidationSeverity, type ValidatorContext, type Validator, toSpecglassError } from "./types.js";
+export { validateFrontmatter } from "./frontmatter-validator.js";
+export { validateSpecDrift } from "./spec-drift-validator.js";
+/**
+ * Run multiple validators and collect all results.
+ *
+ * Each validator runs independently and returns its findings.
+ * Results are concatenated in validator order.
+ */
+export declare function runValidators(validators: Validator[], context: ValidatorContext): Promise<ValidationResult[]>;

package/dist/validation/index.js

@@ -0,0 +1,17 @@
+export { toSpecglassError } from "./types.js";
+export { validateFrontmatter } from "./frontmatter-validator.js";
+export { validateSpecDrift } from "./spec-drift-validator.js";
+/**
+ * Run multiple validators and collect all results.
+ *
+ * Each validator runs independently and returns its findings.
+ * Results are concatenated in validator order.
+ */
+export async function runValidators(validators, context) {
+    const results = [];
+    for (const validator of validators) {
+        const findings = await validator(context);
+        results.push(...findings);
+    }
+    return results;
+}

package/dist/validation/link-validator.d.ts

@@ -0,0 +1,84 @@
+import type { ValidationResult, ValidatorContext } from "./types.js";
+export declare const LINK_INTERNAL_BROKEN = "LINK_INTERNAL_BROKEN";
+export declare const LINK_INTERNAL_ANCHOR_BROKEN = "LINK_INTERNAL_ANCHOR_BROKEN";
+export declare const LINK_EXTERNAL_UNREACHABLE = "LINK_EXTERNAL_UNREACHABLE";
+/** A link extracted from source content. */
+export interface ExtractedLink {
+    /** The raw href/URL from the link. */
+    target: string;
+    /** 1-indexed line number in the source file. */
+    line: number;
+    /** Whether this is an external (http/https) link. */
+    isExternal: boolean;
+}
+/**
+ * Extract all links from MDX/MD content string.
+ *
+ * Finds both markdown links `[text](url)` and HTML `<a href="url">` links.
+ * Returns line numbers for each extracted link.
+ */
+export declare function extractLinks(content: string): ExtractedLink[];
+/** Check if a URL is external (http:// or https://). */
+export declare function isExternalLink(target: string): boolean;
+/**
+ * Resolve and validate all internal links in a single file.
+ */
+export declare function resolveInternalLinks(links: ExtractedLink[], sourceFilePath: string, contentDir: string, knownPages: string[]): Promise<ValidationResult[]>;
+/** Resolve a link path to an absolute file path. */
+export declare function resolvePagePath(linkPath: string, sourceFilePath: string, contentDir: string): string;
+/**
+ * Check if a resolved path corresponds to an existing content file.
+ * Handles extension normalization (.mdx/.md), index files, and trailing slashes.
+ */
+export declare function checkFileExists(resolvedPath: string, contentDir: string, _knownPages: string[]): Promise<{
+    exists: boolean;
+    resolvedPath?: string;
+}>;
+/**
+ * Check if a heading anchor exists in a markdown file.
+ * Extracts headings and converts them to slug IDs.
+ */
+export declare function checkAnchorInFile(anchor: string, filePath: string, sourceLine: number, sourceFilePath?: string): Promise<ValidationResult | null>;
+/**
+ * Extract heading IDs from markdown content.
+ * Converts headings to GitHub-style slug IDs.
+ * Filters out headings that appear inside fenced code blocks.
+ */
+export declare function extractHeadingIds(content: string): string[];
+/**
+ * Convert a heading text to a GitHub-style anchor slug.
+ * e.g., "Getting Started" → "getting-started"
+ */
+export declare function headingToSlug(text: string): string;
+/**
+ * Check external links for reachability via HTTP HEAD requests.
+ * Failures are reported as warnings, not errors.
+ */
+export declare function checkExternalLinks(links: ExtractedLink[], sourceFilePath: string): Promise<ValidationResult[]>;
+/**
+ * Check a single external link via HTTP HEAD request.
+ * Returns a ValidationResult for unreachable links, null for valid ones.
+ */
+export declare function checkSingleExternalLink(link: ExtractedLink, sourceFilePath: string): Promise<ValidationResult | null>;
+/**
+ * Find a suggested page for a broken internal link.
+ * Simple string distance comparison against known pages.
+ */
+export declare function findSuggestion(brokenPath: string, knownPages: string[]): string | null;
+/** Simple Levenshtein distance implementation. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Recursively discover all .md/.mdx files in a directory.
+ */
+export declare function discoverContentFiles(dir: string): Promise<string[]>;
+/**
+ * Build the list of known page slugs from the content directory.
+ */
+export declare function buildKnownPages(contentFiles: string[], contentDir: string): string[];
+/**
+ * Link validator — the composable validator function for link checking.
+ *
+ * @param context - Validator context with contentDir and options
+ * @returns Array of validation results (errors for internal, warnings for external)
+ */
+export declare function validateLinks(context: ValidatorContext): Promise<ValidationResult[]>;