@specglass/core 0.0.4 → 0.0.6

package/dist/validation/link-validator.js

@@ -0,0 +1,490 @@
+/**
+ * Link validator — checks internal and external links across MDX/MD content.
+ *
+ * Internal broken links are reported as errors.
+ * External unreachable links are reported as warnings (prevents flaky CI).
+ *
+ * Composable: `(context: ValidatorContext) => Promise<ValidationResult[]>`
+ */
+import { readFile, readdir, stat, access } from "node:fs/promises";
+import { join, dirname, resolve, basename, relative } from "node:path";
+// --- Error codes ---
+export const LINK_INTERNAL_BROKEN = "LINK_INTERNAL_BROKEN";
+export const LINK_INTERNAL_ANCHOR_BROKEN = "LINK_INTERNAL_ANCHOR_BROKEN";
+export const LINK_EXTERNAL_UNREACHABLE = "LINK_EXTERNAL_UNREACHABLE";
+/**
+ * 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 function extractLinks(content) {
+    const links = [];
+    const lines = content.split("\n");
+    // Markdown links: [text](url) — but NOT image definitions ![alt](url)
+    // Also captures nested content like [text `code`](url)
+    const markdownLinkRegex = /(?<!!)\[(?:[^\]]*)\]\(([^)]+)\)/g;
+    // HTML links: <a href="url"> or <a href='url'>
+    const htmlLinkRegex = /<a\s[^>]*href=["']([^"']+)["'][^>]*>/gi;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNum = i + 1;
+        const line = lines[i];
+        let match;
+        // Reset lastIndex for each line
+        markdownLinkRegex.lastIndex = 0;
+        while ((match = markdownLinkRegex.exec(line)) !== null) {
+            const target = match[1].trim();
+            if (target && !target.startsWith("mailto:") && !target.startsWith("tel:")) {
+                links.push({
+                    target,
+                    line: lineNum,
+                    isExternal: isExternalLink(target),
+                });
+            }
+        }
+        htmlLinkRegex.lastIndex = 0;
+        while ((match = htmlLinkRegex.exec(line)) !== null) {
+            const target = match[1].trim();
+            if (target && !target.startsWith("mailto:") && !target.startsWith("tel:")) {
+                links.push({
+                    target,
+                    line: lineNum,
+                    isExternal: isExternalLink(target),
+                });
+            }
+        }
+    }
+    // Filter out links inside fenced code blocks
+    return filterCodeBlockLinks(content, links);
+}
+/**
+ * Filter out links that appear inside fenced code blocks (``` ... ```).
+ */
+function filterCodeBlockLinks(content, links) {
+    const lines = content.split("\n");
+    const inCodeBlock = new Set();
+    let insideCode = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trimStart();
+        if (trimmed.startsWith("```")) {
+            insideCode = !insideCode;
+            inCodeBlock.add(i + 1);
+            continue;
+        }
+        if (insideCode) {
+            inCodeBlock.add(i + 1);
+        }
+    }
+    return links.filter((link) => !inCodeBlock.has(link.line));
+}
+/** Check if a URL is external (http:// or https://). */
+export function isExternalLink(target) {
+    return target.startsWith("http://") || target.startsWith("https://");
+}
+// --- Internal link resolution ---
+/**
+ * Resolve and validate all internal links in a single file.
+ */
+export async function resolveInternalLinks(links, sourceFilePath, contentDir, knownPages) {
+    const results = [];
+    const internalLinks = links.filter((l) => !l.isExternal);
+    for (const link of internalLinks) {
+        const { target, line } = link;
+        // Anchor-only links (#heading-id) — check heading in same file
+        if (target.startsWith("#")) {
+            const anchorResult = await checkAnchorInFile(target.slice(1), sourceFilePath, line);
+            if (anchorResult) {
+                results.push(anchorResult);
+            }
+            continue;
+        }
+        // Split path and anchor (only at first #)
+        const hashIndex = target.indexOf("#");
+        const linkPath = hashIndex >= 0 ? target.slice(0, hashIndex) : target;
+        const anchor = hashIndex >= 0 ? target.slice(hashIndex + 1) : undefined;
+        // Resolve the page path
+        const resolved = resolvePagePath(linkPath, sourceFilePath, contentDir);
+        // Check if the resolved file exists
+        const fileExists = await checkFileExists(resolved, contentDir, knownPages);
+        if (!fileExists.exists) {
+            const suggestion = findSuggestion(linkPath, knownPages);
+            results.push({
+                code: LINK_INTERNAL_BROKEN,
+                message: `Broken internal link: "${target}"`,
+                filePath: sourceFilePath,
+                line,
+                severity: "error",
+                hint: suggestion
+                    ? `Did you mean "${suggestion}"?`
+                    : `Link target "${linkPath}" does not match any known page. Available pages: ${knownPages.slice(0, 5).join(", ")}${knownPages.length > 5 ? "..." : ""}`,
+            });
+            continue;
+        }
+        // If there's an anchor, check it in the target file
+        if (anchor) {
+            const targetFilePath = fileExists.resolvedPath;
+            const anchorResult = await checkAnchorInFile(anchor, targetFilePath, line, sourceFilePath);
+            if (anchorResult) {
+                results.push(anchorResult);
+            }
+        }
+    }
+    return results;
+}
+/** Resolve a link path to an absolute file path. */
+export function resolvePagePath(linkPath, sourceFilePath, contentDir) {
+    // Strip leading slash for absolute links
+    if (linkPath.startsWith("/")) {
+        return join(contentDir, linkPath.slice(1));
+    }
+    // Relative links resolve against source file's directory
+    return resolve(dirname(sourceFilePath), linkPath);
+}
+/**
+ * Check if a resolved path corresponds to an existing content file.
+ * Handles extension normalization (.mdx/.md), index files, and trailing slashes.
+ */
+export async function checkFileExists(resolvedPath, contentDir, _knownPages) {
+    // Normalize: strip trailing slash
+    const normalized = resolvedPath.replace(/\/$/, "");
+    // Try exact path first
+    const candidates = [
+        normalized,
+        `${normalized}.mdx`,
+        `${normalized}.md`,
+        join(normalized, "index.mdx"),
+        join(normalized, "index.md"),
+    ];
+    // If path already has extension, it's already covered by the candidates list above
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return { exists: true, resolvedPath: candidate };
+        }
+        catch {
+            // noop
+        }
+    }
+    // Also check against knownPages slugs
+    const relPath = relative(contentDir, normalized);
+    const normalizedSlug = relPath
+        .replace(/\\/g, "/")
+        .replace(/\.(mdx|md)$/, "")
+        .replace(/\/index$/, "");
+    for (const page of _knownPages) {
+        const normalizedPage = page.replace(/\.(mdx|md)$/, "").replace(/\/index$/, "");
+        if (normalizedPage === normalizedSlug) {
+            // Find the actual file
+            for (const fileExt of [".mdx", ".md"]) {
+                const filePath = join(contentDir, `${page}${page.endsWith(fileExt) ? "" : fileExt}`);
+                try {
+                    await access(filePath);
+                    return { exists: true, resolvedPath: filePath };
+                }
+                catch {
+                    // noop
+                }
+            }
+            // Matched slug but can't find file — still consider it existing
+            return { exists: true, resolvedPath: join(contentDir, page) };
+        }
+    }
+    return { exists: false };
+}
+/**
+ * Check if a heading anchor exists in a markdown file.
+ * Extracts headings and converts them to slug IDs.
+ */
+export async function checkAnchorInFile(anchor, filePath, sourceLine, sourceFilePath) {
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch {
+        // File doesn't exist — handled elsewhere
+        return null;
+    }
+    const headingIds = extractHeadingIds(content);
+    if (!headingIds.includes(anchor)) {
+        return {
+            code: LINK_INTERNAL_ANCHOR_BROKEN,
+            message: `Broken anchor link: "#${anchor}" not found in ${basename(filePath)}`,
+            filePath: sourceFilePath || filePath,
+            line: sourceLine,
+            severity: "error",
+            hint: headingIds.length > 0
+                ? `Available anchors: ${headingIds.slice(0, 5).join(", ")}${headingIds.length > 5 ? "..." : ""}`
+                : `No headings found in ${basename(filePath)}`,
+        };
+    }
+    return null;
+}
+/**
+ * Extract heading IDs from markdown content.
+ * Converts headings to GitHub-style slug IDs.
+ * Filters out headings that appear inside fenced code blocks.
+ */
+export function extractHeadingIds(content) {
+    const lines = content.split("\n");
+    const headingRegex = /^#{1,6}\s+(.+)$/;
+    const ids = [];
+    let insideCode = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            insideCode = !insideCode;
+            continue;
+        }
+        if (insideCode)
+            continue;
+        const match = headingRegex.exec(line);
+        if (match) {
+            ids.push(headingToSlug(match[1].trim()));
+        }
+    }
+    return ids;
+}
+/**
+ * Convert a heading text to a GitHub-style anchor slug.
+ * e.g., "Getting Started" → "getting-started"
+ */
+export function headingToSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "") // Remove non-word chars except spaces and hyphens
+        .replace(/\s+/g, "-") // Replace spaces with hyphens
+        .replace(/-+/g, "-") // Collapse multiple hyphens
+        .replace(/^-|-$/g, ""); // Trim leading/trailing hyphens
+}
+// --- External link checking ---
+/** URLs to skip during external checking (dev/test/example URLs). */
+const SKIP_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "0.0.0.0",
+    "example.com",
+    "example.org",
+    "example.net",
+]);
+/** Maximum concurrent external link checks. */
+const MAX_CONCURRENT = 5;
+/** Timeout per external link check (ms). */
+const EXTERNAL_TIMEOUT_MS = 10_000;
+/**
+ * Check external links for reachability via HTTP HEAD requests.
+ * Failures are reported as warnings, not errors.
+ */
+export async function checkExternalLinks(links, sourceFilePath) {
+    const externalLinks = links.filter((l) => l.isExternal);
+    if (externalLinks.length === 0)
+        return [];
+    // Deduplicate by target URL (keep first occurrence for line number)
+    const uniqueLinks = new Map();
+    for (const link of externalLinks) {
+        if (!uniqueLinks.has(link.target)) {
+            uniqueLinks.set(link.target, link);
+        }
+    }
+    const results = [];
+    const entries = [...uniqueLinks.values()];
+    // Process in batches with bounded concurrency
+    for (let i = 0; i < entries.length; i += MAX_CONCURRENT) {
+        const batch = entries.slice(i, i + MAX_CONCURRENT);
+        const batchResults = await Promise.allSettled(batch.map((link) => checkSingleExternalLink(link, sourceFilePath)));
+        for (const result of batchResults) {
+            if (result.status === "fulfilled" && result.value) {
+                results.push(result.value);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Check a single external link via HTTP HEAD request.
+ * Returns a ValidationResult for unreachable links, null for valid ones.
+ */
+export async function checkSingleExternalLink(link, sourceFilePath) {
+    // Skip dev/test URLs
+    try {
+        const url = new URL(link.target);
+        if (SKIP_HOSTS.has(url.hostname)) {
+            return null;
+        }
+    }
+    catch {
+        return {
+            code: LINK_EXTERNAL_UNREACHABLE,
+            message: `Invalid URL: "${link.target}"`,
+            filePath: sourceFilePath,
+            line: link.line,
+            severity: "warning",
+            hint: "URL could not be parsed",
+        };
+    }
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), EXTERNAL_TIMEOUT_MS);
+        try {
+            const response = await fetch(link.target, {
+                method: "HEAD",
+                signal: controller.signal,
+                redirect: "follow",
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                return null; // Link is valid
+            }
+            // Some servers reject HEAD — retry with GET
+            if (response.status === 405) {
+                const getResponse = await fetch(link.target, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(EXTERNAL_TIMEOUT_MS),
+                    redirect: "follow",
+                });
+                if (getResponse.ok) {
+                    return null;
+                }
+            }
+            return {
+                code: LINK_EXTERNAL_UNREACHABLE,
+                message: `External link unreachable: "${link.target}" (HTTP ${response.status})`,
+                filePath: sourceFilePath,
+                line: link.line,
+                severity: "warning",
+                hint: `Server returned HTTP ${response.status}. This may be temporary.`,
+            };
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            throw err;
+        }
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+            code: LINK_EXTERNAL_UNREACHABLE,
+            message: `External link unreachable: "${link.target}"`,
+            filePath: sourceFilePath,
+            line: link.line,
+            severity: "warning",
+            hint: `Request failed: ${errorMessage}. This may be a network issue.`,
+        };
+    }
+}
+// --- Suggestion engine ---
+/**
+ * Find a suggested page for a broken internal link.
+ * Simple string distance comparison against known pages.
+ */
+export function findSuggestion(brokenPath, knownPages) {
+    if (knownPages.length === 0)
+        return null;
+    // Normalize the broken path
+    const normalized = brokenPath
+        .replace(/^\//, "")
+        .replace(/\.(mdx|md)$/, "")
+        .replace(/\/index$/, "")
+        .replace(/\/$/, "");
+    // Find the closest match
+    let bestMatch = null;
+    let bestScore = Infinity;
+    for (const page of knownPages) {
+        const normalizedPage = page
+            .replace(/\.(mdx|md)$/, "")
+            .replace(/\/index$/, "");
+        const distance = levenshtein(normalized, normalizedPage);
+        // Only suggest if reasonably close (within 3 edits)
+        if (distance < bestScore && distance <= 3) {
+            bestScore = distance;
+            bestMatch = `/${normalizedPage}`;
+        }
+    }
+    return bestMatch;
+}
+/** Simple Levenshtein distance implementation. */
+export function levenshtein(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+// --- Content discovery ---
+/**
+ * Recursively discover all .md/.mdx files in a directory.
+ */
+export async function discoverContentFiles(dir) {
+    const files = [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith("_") || entry.startsWith("."))
+            continue;
+        const fullPath = join(dir, entry);
+        const info = await stat(fullPath);
+        if (info.isDirectory()) {
+            const subFiles = await discoverContentFiles(fullPath);
+            files.push(...subFiles);
+        }
+        else if (entry.endsWith(".mdx") || entry.endsWith(".md")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Build the list of known page slugs from the content directory.
+ */
+export function buildKnownPages(contentFiles, contentDir) {
+    return contentFiles.map((f) => {
+        const rel = relative(contentDir, f).replace(/\\/g, "/");
+        return rel.replace(/\.(mdx|md)$/, "").replace(/\/index$/, "");
+    });
+}
+// --- Main validator entry point ---
+/**
+ * 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 async function validateLinks(context) {
+    const { contentDir, skipExternal } = context;
+    // Discover all content files
+    const contentFiles = await discoverContentFiles(contentDir);
+    const knownPages = context.knownPages.length > 0
+        ? context.knownPages
+        : buildKnownPages(contentFiles, contentDir);
+    const allResults = [];
+    for (const filePath of contentFiles) {
+        const content = await readFile(filePath, "utf-8");
+        const links = extractLinks(content);
+        if (links.length === 0)
+            continue;
+        // Internal link validation
+        const internalResults = await resolveInternalLinks(links, filePath, contentDir, knownPages);
+        allResults.push(...internalResults);
+        // External link validation (unless skipped)
+        if (!skipExternal) {
+            const externalResults = await checkExternalLinks(links, filePath);
+            allResults.push(...externalResults);
+        }
+    }
+    return allResults;
+}

package/dist/validation/spec-drift-validator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * OpenAPI spec drift detection validator.
+ *
+ * Compares the current OpenAPI specification against a previously saved
+ * baseline snapshot to detect drift: added endpoints, removed endpoints,
+ * changed parameters, and modified response schemas.
+ *
+ * Follows the composable validator pattern established by `validateLinks`
+ * (Story 6.1) and `validateFrontmatter` (Story 6.2).
+ *
+ * @module
+ */
+import type { ParsedOpenApiSpec, ApiEndpoint } from "../openapi/types.js";
+import type { ValidationResult, ValidatorContext } from "./types.js";
+export declare const SPEC_DRIFT_ENDPOINT_ADDED = "SPEC_DRIFT_ENDPOINT_ADDED";
+export declare const SPEC_DRIFT_ENDPOINT_REMOVED = "SPEC_DRIFT_ENDPOINT_REMOVED";
+export declare const SPEC_DRIFT_PARAMETER_CHANGED = "SPEC_DRIFT_PARAMETER_CHANGED";
+export declare const SPEC_DRIFT_RESPONSE_CHANGED = "SPEC_DRIFT_RESPONSE_CHANGED";
+export declare const SPEC_DRIFT_REQUEST_BODY_CHANGED = "SPEC_DRIFT_REQUEST_BODY_CHANGED";
+export declare const SPEC_DRIFT_UNREACHABLE = "SPEC_DRIFT_UNREACHABLE";
+export declare const SPEC_DRIFT_PARSE_ERROR = "SPEC_DRIFT_PARSE_ERROR";
+/** Fingerprint for a single endpoint, enabling efficient diffing. */
+export interface EndpointFingerprint {
+    operationId?: string;
+    /** Sorted array of "name:in:type" strings for parameters. */
+    parameters: string[];
+    /** Sorted content types accepted in request body. */
+    requestBodyContentTypes: string[];
+    /** Sorted response status codes. */
+    responseStatusCodes: string[];
+    deprecated: boolean;
+}
+/** A serializable snapshot of an OpenAPI spec for baseline comparison. */
+export interface SpecSnapshot {
+    specPath: string;
+    version: string;
+    generatedAt: string;
+    endpoints: Record<string, EndpointFingerprint>;
+}
+/** A single drift change detected between baseline and current spec. */
+export interface DriftChange {
+    type: "added" | "removed" | "parameter-changed" | "response-changed" | "request-body-changed";
+    endpointKey: string;
+    details: string;
+}
+/**
+ * Build an endpoint fingerprint key: "METHOD /path".
+ */
+export declare function endpointKey(endpoint: ApiEndpoint): string;
+/**
+ * Create a fingerprint for a single endpoint.
+ */
+export declare function fingerprintEndpoint(endpoint: ApiEndpoint): EndpointFingerprint;
+/**
+ * Create a baseline snapshot from a parsed OpenAPI specification.
+ */
+export declare function createSnapshot(spec: ParsedOpenApiSpec, specPath: string): SpecSnapshot;
+/**
+ * Resolve the baseline file path for a given spec path.
+ * Baseline is stored at `<projectRoot>/.specglass/openapi-baseline-<specName>.json`.
+ * We use the spec filename (without extension) as the disambiguator.
+ */
+export declare function resolveBaselinePath(projectRoot: string, specPath: string): string;
+/**
+ * Load a previously saved baseline snapshot from disk.
+ * Returns null if no baseline exists (first run).
+ */
+export declare function loadBaseline(baselinePath: string): Promise<SpecSnapshot | null>;
+/**
+ * Save a baseline snapshot to disk.
+ * Creates parent directories if they don't exist.
+ */
+export declare function saveBaseline(snapshot: SpecSnapshot, baselinePath: string): Promise<void>;
+/**
+ * Compare two snapshots and detect all drift changes.
+ */
+export declare function detectDrift(baseline: SpecSnapshot, current: SpecSnapshot): DriftChange[];
+/**
+ * Map drift changes to ValidationResult objects.
+ */
+export declare function driftToValidationResults(changes: DriftChange[], specPath: string): ValidationResult[];
+/**
+ * Spec drift validator — composable validator for OpenAPI spec drift detection.
+ *
+ * @param context - Validator context with `specPaths` and `projectRoot`
+ * @returns Array of validation results for detected drift
+ */
+export declare function validateSpecDrift(context: ValidatorContext): Promise<ValidationResult[]>;