@specglass/core 0.0.4 → 0.0.6

package/dist/validation/spec-drift-validator.js

@@ -0,0 +1,276 @@
+/**
+ * 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 { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, dirname, join, parse as parsePath } from "node:path";
+import { parseOpenApiSpec } from "../openapi/parser.js";
+import { SpecglassError } from "../errors/specglass-error.js";
+// ─── Error codes ─────────────────────────────────────────────────────
+export const SPEC_DRIFT_ENDPOINT_ADDED = "SPEC_DRIFT_ENDPOINT_ADDED";
+export const SPEC_DRIFT_ENDPOINT_REMOVED = "SPEC_DRIFT_ENDPOINT_REMOVED";
+export const SPEC_DRIFT_PARAMETER_CHANGED = "SPEC_DRIFT_PARAMETER_CHANGED";
+export const SPEC_DRIFT_RESPONSE_CHANGED = "SPEC_DRIFT_RESPONSE_CHANGED";
+export const SPEC_DRIFT_REQUEST_BODY_CHANGED = "SPEC_DRIFT_REQUEST_BODY_CHANGED";
+export const SPEC_DRIFT_UNREACHABLE = "SPEC_DRIFT_UNREACHABLE";
+export const SPEC_DRIFT_PARSE_ERROR = "SPEC_DRIFT_PARSE_ERROR";
+// ─── Baseline snapshot directory ─────────────────────────────────────
+const BASELINE_DIR = ".specglass";
+// ─── Snapshot creation (Task 1) ──────────────────────────────────────
+/**
+ * Build an endpoint fingerprint key: "METHOD /path".
+ */
+export function endpointKey(endpoint) {
+    return `${endpoint.method.toUpperCase()} ${endpoint.path}`;
+}
+/**
+ * Create a fingerprint for a single endpoint.
+ */
+export function fingerprintEndpoint(endpoint) {
+    return {
+        operationId: endpoint.operationId,
+        parameters: endpoint.parameters
+            .map((p) => `${p.name}:${p.in}:${p.schema.type ?? "unknown"}`)
+            .sort(),
+        requestBodyContentTypes: endpoint.requestBody
+            ? Object.keys(endpoint.requestBody.content).sort()
+            : [],
+        responseStatusCodes: endpoint.responses
+            .map((r) => r.statusCode)
+            .sort(),
+        deprecated: endpoint.deprecated,
+    };
+}
+/**
+ * Create a baseline snapshot from a parsed OpenAPI specification.
+ */
+export function createSnapshot(spec, specPath) {
+    const endpoints = {};
+    for (const ep of spec.endpoints) {
+        endpoints[endpointKey(ep)] = fingerprintEndpoint(ep);
+    }
+    return {
+        specPath,
+        version: spec.info.version,
+        generatedAt: new Date().toISOString(),
+        endpoints,
+    };
+}
+// ─── Baseline persistence (Task 2) ──────────────────────────────────
+/**
+ * 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 function resolveBaselinePath(projectRoot, specPath) {
+    const specName = parsePath(specPath).name;
+    return join(projectRoot, BASELINE_DIR, `openapi-baseline-${specName}.json`);
+}
+/**
+ * Load a previously saved baseline snapshot from disk.
+ * Returns null if no baseline exists (first run).
+ */
+export async function loadBaseline(baselinePath) {
+    if (!existsSync(baselinePath)) {
+        return null;
+    }
+    try {
+        const raw = await readFile(baselinePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        // Only treat JSON parse failures as "no baseline" — re-throw I/O errors
+        if (error instanceof SyntaxError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Save a baseline snapshot to disk.
+ * Creates parent directories if they don't exist.
+ */
+export async function saveBaseline(snapshot, baselinePath) {
+    await mkdir(dirname(baselinePath), { recursive: true });
+    await writeFile(baselinePath, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+// ─── Drift detection (Task 3) ───────────────────────────────────────
+/**
+ * Compare two snapshots and detect all drift changes.
+ */
+export function detectDrift(baseline, current) {
+    const changes = [];
+    const baselineKeys = new Set(Object.keys(baseline.endpoints));
+    const currentKeys = new Set(Object.keys(current.endpoints));
+    // Detect added endpoints
+    for (const key of currentKeys) {
+        if (!baselineKeys.has(key)) {
+            changes.push({
+                type: "added",
+                endpointKey: key,
+                details: `New endpoint added: ${key}`,
+            });
+        }
+    }
+    // Detect removed endpoints
+    for (const key of baselineKeys) {
+        if (!currentKeys.has(key)) {
+            changes.push({
+                type: "removed",
+                endpointKey: key,
+                details: `Endpoint removed: ${key}`,
+            });
+        }
+    }
+    // Detect changes in shared endpoints
+    for (const key of currentKeys) {
+        if (!baselineKeys.has(key))
+            continue;
+        const base = baseline.endpoints[key];
+        const curr = current.endpoints[key];
+        // Parameter changes
+        const baseParams = base.parameters.join(",");
+        const currParams = curr.parameters.join(",");
+        if (baseParams !== currParams) {
+            const added = curr.parameters.filter((p) => !base.parameters.includes(p));
+            const removed = base.parameters.filter((p) => !curr.parameters.includes(p));
+            const parts = [];
+            if (added.length > 0)
+                parts.push(`added: ${added.join(", ")}`);
+            if (removed.length > 0)
+                parts.push(`removed: ${removed.join(", ")}`);
+            changes.push({
+                type: "parameter-changed",
+                endpointKey: key,
+                details: `Parameters changed on ${key}: ${parts.join("; ")}`,
+            });
+        }
+        // Response status code changes
+        const baseResponses = base.responseStatusCodes.join(",");
+        const currResponses = curr.responseStatusCodes.join(",");
+        if (baseResponses !== currResponses) {
+            const added = curr.responseStatusCodes.filter((r) => !base.responseStatusCodes.includes(r));
+            const removed = base.responseStatusCodes.filter((r) => !curr.responseStatusCodes.includes(r));
+            const parts = [];
+            if (added.length > 0)
+                parts.push(`added status codes: ${added.join(", ")}`);
+            if (removed.length > 0)
+                parts.push(`removed status codes: ${removed.join(", ")}`);
+            changes.push({
+                type: "response-changed",
+                endpointKey: key,
+                details: `Response schema changed on ${key}: ${parts.join("; ")}`,
+            });
+        }
+        // Request body content type changes
+        const baseContentTypes = base.requestBodyContentTypes.join(",");
+        const currContentTypes = curr.requestBodyContentTypes.join(",");
+        if (baseContentTypes !== currContentTypes) {
+            changes.push({
+                type: "request-body-changed",
+                endpointKey: key,
+                details: `Request body content types changed on ${key}: was [${base.requestBodyContentTypes.join(", ")}], now [${curr.requestBodyContentTypes.join(", ")}]`,
+            });
+        }
+    }
+    return changes;
+}
+// ─── DriftChange → ValidationResult mapping (Task 3.6) ──────────────
+const DRIFT_TYPE_TO_CODE = {
+    added: SPEC_DRIFT_ENDPOINT_ADDED,
+    removed: SPEC_DRIFT_ENDPOINT_REMOVED,
+    "parameter-changed": SPEC_DRIFT_PARAMETER_CHANGED,
+    "response-changed": SPEC_DRIFT_RESPONSE_CHANGED,
+    "request-body-changed": SPEC_DRIFT_REQUEST_BODY_CHANGED,
+};
+const DRIFT_TYPE_TO_HINT = {
+    added: "A new endpoint was added to the spec. Run `ndocs build` to generate its documentation.",
+    removed: "An endpoint was removed from the spec. Remove or redirect its documentation page.",
+    "parameter-changed": "Endpoint parameters have changed. Verify the documentation still matches the API.",
+    "response-changed": "Response schema has changed. Update example responses and status code documentation.",
+    "request-body-changed": "Request body content types have changed. Update request documentation and examples.",
+};
+/**
+ * Map drift changes to ValidationResult objects.
+ */
+export function driftToValidationResults(changes, specPath) {
+    return changes.map((change) => ({
+        code: DRIFT_TYPE_TO_CODE[change.type],
+        message: change.details,
+        filePath: specPath,
+        severity: "warning",
+        hint: DRIFT_TYPE_TO_HINT[change.type],
+    }));
+}
+// ─── Composable validator entry point (Task 5) ──────────────────────
+/**
+ * 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 async function validateSpecDrift(context) {
+    const specPaths = context.specPaths ?? [];
+    const projectRoot = context.projectRoot ?? context.contentDir;
+    if (specPaths.length === 0) {
+        return [];
+    }
+    const results = [];
+    for (const rawSpecPath of specPaths) {
+        // Remote specs (URLs) must not be resolved as filesystem paths
+        const isUrl = rawSpecPath.startsWith("http://") || rawSpecPath.startsWith("https://");
+        const specPath = isUrl ? rawSpecPath : resolve(projectRoot, rawSpecPath);
+        const baselinePath = resolveBaselinePath(projectRoot, rawSpecPath);
+        // Parse current spec — catch unreachable/parse errors (Task 4)
+        let spec;
+        try {
+            spec = await parseOpenApiSpec(specPath);
+        }
+        catch (error) {
+            const message = error instanceof SpecglassError
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            // Distinguish unreachable (file not found, network error) from parse errors
+            const isUnreachable = /not found|ENOENT|EACCES|fetch failed|unreachable|network/i.test(message);
+            const code = isUnreachable ? SPEC_DRIFT_UNREACHABLE : SPEC_DRIFT_PARSE_ERROR;
+            results.push({
+                code,
+                message: `Spec drift check failed for ${rawSpecPath}: ${message}`,
+                filePath: specPath,
+                severity: "error",
+                hint: code === SPEC_DRIFT_UNREACHABLE
+                    ? "Check that the spec file exists and is accessible."
+                    : "Check that the file is valid YAML/JSON and conforms to OpenAPI 3.x",
+            });
+            continue;
+        }
+        // Create snapshot from current spec
+        const currentSnapshot = createSnapshot(spec, rawSpecPath);
+        // Load baseline
+        const baseline = await loadBaseline(baselinePath);
+        if (baseline === null) {
+            // First run — save baseline silently (AC 3)
+            await saveBaseline(currentSnapshot, baselinePath);
+            continue;
+        }
+        // Detect drift
+        const changes = detectDrift(baseline, currentSnapshot);
+        if (changes.length > 0) {
+            results.push(...driftToValidationResults(changes, specPath));
+        }
+        // Always update baseline after comparison
+        await saveBaseline(currentSnapshot, baselinePath);
+    }
+    return results;
+}

package/dist/validation/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Validation types — shared interfaces for the composable validator pattern.
+ *
+ * Each validator is a function that takes a ValidatorContext and returns
+ * an array of ValidationResult objects. Validators are composable and
+ * independently runnable (e.g., via `ndocs check --links-only`).
+ */
+import { SpecglassError } from "../errors/specglass-error.js";
+/** Severity level for validation findings. */
+export type ValidationSeverity = "error" | "warning";
+/** A single validation finding with actionable context. */
+export interface ValidationResult {
+    /** Namespaced error code (e.g., LINK_INTERNAL_BROKEN, FRONTMATTER_MISSING_TITLE). */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Absolute path to the source file containing the issue. */
+    filePath: string;
+    /** Line number in source file (1-indexed). */
+    line?: number;
+    /** Severity: 'error' blocks CI, 'warning' is informational. */
+    severity: ValidationSeverity;
+    /** Actionable remediation hint (e.g., "Did you mean /getting-started?"). */
+    hint?: string;
+}
+/**
+ * Convert a ValidationResult to a SpecglassError.
+ * Bridges the validation subsystem with the core error convention.
+ */
+export declare function toSpecglassError(result: ValidationResult): SpecglassError;
+/** Context passed to every validator. */
+export interface ValidatorContext {
+    /** Absolute path to the content directory root. */
+    contentDir: string;
+    /** All known page slugs for internal link resolution. */
+    knownPages: string[];
+    /** Whether to skip external link checks (--no-external flag). */
+    skipExternal?: boolean;
+    /** OpenAPI spec paths (relative to projectRoot) for drift detection. */
+    specPaths?: string[];
+    /** Project root directory for resolving spec paths and baseline storage. */
+    projectRoot?: string;
+}
+/** A composable validator function. */
+export type Validator = (context: ValidatorContext) => Promise<ValidationResult[]>;

package/dist/validation/types.js

@@ -0,0 +1,15 @@
+/**
+ * Validation types — shared interfaces for the composable validator pattern.
+ *
+ * Each validator is a function that takes a ValidatorContext and returns
+ * an array of ValidationResult objects. Validators are composable and
+ * independently runnable (e.g., via `ndocs check --links-only`).
+ */
+import { SpecglassError } from "../errors/specglass-error.js";
+/**
+ * Convert a ValidationResult to a SpecglassError.
+ * Bridges the validation subsystem with the core error convention.
+ */
+export function toSpecglassError(result) {
+    return new SpecglassError(result.message, result.code, result.filePath, result.line, result.hint);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specglass/core",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Astro integration, config system, content collections, and OpenAPI spec parsing for Specglass",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "zod": "^3.23"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "astro": "^5.17",
     "pagefind": "^1.4.0",
     "typescript": "^5.5",

package/src/pages/api-reference/[...slug].astro

@@ -3,9 +3,10 @@
  * API Reference route page.
  * Generates one page per endpoint from the virtual:specglass/openapi-data module.
  * Maps parsed OpenAPI data into ApiReferencePage layout props.
+ * Also generates fallback pages for errored endpoints (FR40).
  */
-import type { ParsedOpenApiSpec, ApiEndpoint } from "@specglass/core";
-import { buildEndpointSlug } from "@specglass/core";
+import type { ParsedOpenApiSpec, ApiEndpoint, ApiEndpointError } from "@specglass/core";
+import { buildEndpointSlug, buildErrorEndpointSlug } from "@specglass/core";
 import { config } from "virtual:specglass/config";
 import { navigation } from "virtual:specglass/navigation";
 import { openApiData } from "virtual:specglass/openapi-data";
@@ -16,24 +17,37 @@ export async function getStaticPaths() {
   const paths: Array<{
     params: { slug: string | undefined };
     props: {
-      endpoint: ApiEndpoint;
+      endpoint?: ApiEndpoint;
+      endpointError?: ApiEndpointError;
       allEndpoints: ApiEndpoint[];
+      allErrors: ApiEndpointError[];
       specInfo: ParsedOpenApiSpec["info"];
       securitySchemes: ParsedOpenApiSpec["securitySchemes"];
     };
   }> = [];
 
   for (const spec of allSpecs) {
+    const sharedProps = {
+      allEndpoints: spec.endpoints,
+      allErrors: spec.errors,
+      specInfo: spec.info,
+      securitySchemes: spec.securitySchemes,
+    };
+
     for (const endpoint of spec.endpoints) {
       const slug = buildEndpointSlug(endpoint);
       paths.push({
         params: { slug },
-        props: {
-          endpoint,
-          allEndpoints: spec.endpoints,
-          specInfo: spec.info,
-          securitySchemes: spec.securitySchemes,
-        },
+        props: { endpoint, ...sharedProps },
+      });
+    }
+
+    // Fallback pages for errored endpoints (FR40)
+    for (const error of spec.errors) {
+      const slug = buildErrorEndpointSlug(error);
+      paths.push({
+        params: { slug },
+        props: { endpointError: error, ...sharedProps },
       });
     }
 
@@ -41,12 +55,7 @@ export async function getStaticPaths() {
     if (spec.endpoints.length > 0) {
       paths.push({
         params: { slug: undefined },
-        props: {
-          endpoint: spec.endpoints[0],
-          allEndpoints: spec.endpoints,
-          specInfo: spec.info,
-          securitySchemes: spec.securitySchemes,
-        },
+        props: { endpoint: spec.endpoints[0], ...sharedProps },
       });
     }
   }
@@ -54,14 +63,16 @@ export async function getStaticPaths() {
   return paths;
 }
 
-const { endpoint, allEndpoints, specInfo, securitySchemes } = Astro.props;
+const { endpoint, endpointError, allEndpoints, allErrors, specInfo, securitySchemes } = Astro.props;
 ---
 
 <ApiReferencePage
   endpoint={endpoint}
+  endpointError={endpointError}
   navigation={navigation}
   config={config}
   allEndpoints={allEndpoints}
+  allErrors={allErrors ?? []}
   specInfo={specInfo}
   securitySchemes={securitySchemes}
 />

package/src/pages/index.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * Root index — redirects to the first page in the navigation tree.
+ *
+ * Since there is no content at `/`, this page finds the first navigable
+ * page and redirects the user there. Falls back to `/getting-started`
+ * if the navigation tree is empty (shouldn't happen in practice).
+ */
+import { navigation } from "virtual:specglass/navigation";
+import type { NavItem } from "@specglass/core";
+
+function findFirstPage(items: NavItem[]): string | null {
+  for (const item of items) {
+    if (item.type === "page" && item.slug) {
+      return `/${item.slug}`;
+    }
+    if (item.type === "section" && item.children) {
+      const found = findFirstPage(item.children);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+const target = findFirstPage(navigation.items) ?? "/getting-started";
+return Astro.redirect(target);
+---