@specglass/core 0.0.2

package/dist/navigation/index.js

@@ -0,0 +1,6 @@
+// Navigation — public API
+export { buildNavigationTree, toTitleCase } from "./builder.js";
+export { parseMetaJson } from "./meta-parser.js";
+export { metaJsonSchema, metaJsonEntryValueSchema, metaJsonEntryObjectSchema, } from "./meta-schema.js";
+export { createNavigationWatcher, isNavigationRelevant, } from "./watcher.js";
+//# sourceMappingURL=index.js.map

package/dist/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,cAAc,CAAC"}

package/dist/navigation/meta-parser.d.ts

@@ -0,0 +1,9 @@
+import type { MetaJsonEntry } from "../types/navigation.js";
+/**
+ * Parse a `_meta.json` file from the given directory.
+ *
+ * @param dirPath - Absolute path to the directory containing `_meta.json`
+ * @returns Ordered array of `MetaJsonEntry`, or `null` if file is missing or invalid
+ */
+export declare function parseMetaJson(dirPath: string): Promise<MetaJsonEntry[] | null>;
+//# sourceMappingURL=meta-parser.d.ts.map

package/dist/navigation/meta-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-parser.d.ts","sourceRoot":"","sources":["../../src/navigation/meta-parser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,wBAAwB,CAAC;AAqBhF;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAqCjC"}

package/dist/navigation/meta-parser.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { metaJsonSchema } from "./meta-schema.js";
+/**
+ * Normalize a raw `_meta.json` entry value into a `MetaJsonEntry`.
+ *
+ * String values are shorthand for `{ title: "value" }`.
+ */
+function normalizeEntry(key, value) {
+    if (typeof value === "string") {
+        return { key, title: value };
+    }
+    return {
+        key,
+        title: value.title,
+        ...(value.collapsed !== undefined && { collapsed: value.collapsed }),
+        ...(value.icon !== undefined && { icon: value.icon }),
+        ...(value.href !== undefined && { href: value.href }),
+        ...(value.hidden !== undefined && { hidden: value.hidden }),
+    };
+}
+/**
+ * Parse a `_meta.json` file from the given directory.
+ *
+ * @param dirPath - Absolute path to the directory containing `_meta.json`
+ * @returns Ordered array of `MetaJsonEntry`, or `null` if file is missing or invalid
+ */
+export async function parseMetaJson(dirPath) {
+    const filePath = join(dirPath, "_meta.json");
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch {
+        // File doesn't exist — not an error, just no meta
+        return null;
+    }
+    // Empty file → empty array (valid but no entries)
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        console.warn(`[specglass] Invalid JSON in ${filePath} — falling back to alphabetical order`);
+        return null;
+    }
+    const result = metaJsonSchema.safeParse(parsed);
+    if (!result.success) {
+        console.warn(`[specglass] Invalid _meta.json schema in ${filePath} — falling back to alphabetical order`);
+        return null;
+    }
+    // Preserve JSON key order (Object.entries preserves insertion order)
+    return Object.entries(result.data).map(([key, value]) => normalizeEntry(key, value));
+}
+//# sourceMappingURL=meta-parser.js.map

package/dist/navigation/meta-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-parser.js","sourceRoot":"","sources":["../../src/navigation/meta-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAW,EAAE,KAAyB;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO;QACL,GAAG;QACH,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACpE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe;IAEf,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAE7C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kDAAkD;IAClD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,+BAA+B,QAAQ,uCAAuC,CAAC,CAAC;QAC7F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CACV,4CAA4C,QAAQ,uCAAuC,CAC5F,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qEAAqE;IACrE,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACtD,cAAc,CAAC,GAAG,EAAE,KAA2B,CAAC,CACjD,CAAC;AACJ,CAAC"}

package/dist/navigation/meta-schema.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * Zod schema for the object form of a `_meta.json` entry value.
+ *
+ * Supports: `title` (required), `collapsed`, `icon`, `href`, `hidden`.
+ */
+export declare const metaJsonEntryObjectSchema: z.ZodObject<{
+    title: z.ZodString;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}>;
+/**
+ * Zod schema for a single `_meta.json` entry value.
+ *
+ * - String values are shorthand for `{ title: "value" }`
+ * - Object values provide extended configuration
+ */
+export declare const metaJsonEntryValueSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    title: z.ZodString;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}>]>;
+/**
+ * Zod schema for a complete `_meta.json` file.
+ *
+ * The file is a flat key-value object where keys are filenames
+ * (without extension) and values are either strings or config objects.
+ */
+export declare const metaJsonSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodObject<{
+    title: z.ZodString;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}, {
+    title: string;
+    href?: string | undefined;
+    collapsed?: boolean | undefined;
+    icon?: string | undefined;
+    hidden?: boolean | undefined;
+}>]>>;
+export type MetaJsonSchemaInput = z.input<typeof metaJsonSchema>;
+//# sourceMappingURL=meta-schema.d.ts.map

package/dist/navigation/meta-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-schema.d.ts","sourceRoot":"","sources":["../../src/navigation/meta-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;EAMpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;IAGnC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;KAAiD,CAAC;AAE7E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/navigation/meta-schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Zod schema for the object form of a `_meta.json` entry value.
+ *
+ * Supports: `title` (required), `collapsed`, `icon`, `href`, `hidden`.
+ */
+export const metaJsonEntryObjectSchema = z.object({
+    title: z.string(),
+    collapsed: z.boolean().optional(),
+    icon: z.string().optional(),
+    href: z.string().optional(),
+    hidden: z.boolean().optional(),
+});
+/**
+ * Zod schema for a single `_meta.json` entry value.
+ *
+ * - String values are shorthand for `{ title: "value" }`
+ * - Object values provide extended configuration
+ */
+export const metaJsonEntryValueSchema = z.union([
+    z.string(),
+    metaJsonEntryObjectSchema,
+]);
+/**
+ * Zod schema for a complete `_meta.json` file.
+ *
+ * The file is a flat key-value object where keys are filenames
+ * (without extension) and values are either strings or config objects.
+ */
+export const metaJsonSchema = z.record(z.string(), metaJsonEntryValueSchema);
+//# sourceMappingURL=meta-schema.js.map

package/dist/navigation/meta-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-schema.js","sourceRoot":"","sources":["../../src/navigation/meta-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC9C,CAAC,CAAC,MAAM,EAAE;IACV,yBAAyB;CAC1B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC"}

package/dist/navigation/watcher.d.ts

@@ -0,0 +1,44 @@
+import type { NavigationTree } from "../types/navigation.js";
+/**
+ * Options for creating a navigation file watcher.
+ */
+export interface NavigationWatcherOptions {
+    /** Absolute path to the content directory to watch. */
+    contentDir: string;
+    /** Callback invoked with the new navigation tree when relevant files change. */
+    onNavigationUpdate: (tree: NavigationTree) => void;
+    /** Debounce window in milliseconds. Defaults to 100. */
+    debounceMs?: number;
+}
+/**
+ * Check whether a file change should trigger a navigation rebuild.
+ *
+ * Navigation-relevant changes are:
+ * - Addition or removal of `.mdx` / `.md` files
+ * - Modification of `_meta.json` files
+ *
+ * @param filePath - Absolute path of the changed file
+ * @param contentDir - Absolute path of the watched content directory
+ * @returns `true` if the change should trigger a navigation rebuild
+ */
+export declare function isNavigationRelevant(filePath: string, contentDir: string): boolean;
+/**
+ * Create a navigation watcher that rebuilds the navigation tree
+ * when relevant content files change.
+ *
+ * The watcher debounces rapid file system events (e.g., git checkout)
+ * to avoid redundant rebuilds.
+ *
+ * @param options - Configuration for the watcher
+ * @returns A cleanup function that stops the watcher's debounce timer
+ */
+export declare function createNavigationWatcher(options: NavigationWatcherOptions): {
+    /**
+     * Call this when a file system event occurs.
+     * The watcher will check relevance and debounce before triggering a rebuild.
+     */
+    handleFileChange: (filePath: string) => void;
+    /** Stop any pending debounced rebuild. */
+    cleanup: () => void;
+};
+//# sourceMappingURL=watcher.d.ts.map

package/dist/navigation/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/navigation/watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,kBAAkB,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACnD,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAmBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG;IAC1E;;;OAGG;IACH,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAkCA"}

package/dist/navigation/watcher.js

@@ -0,0 +1,81 @@
+import { basename, extname } from "node:path";
+import { buildNavigationTree } from "./builder.js";
+/**
+ * File extensions that are considered navigation-relevant content files.
+ */
+const CONTENT_EXTENSIONS = new Set([".mdx", ".md"]);
+/**
+ * Filename that controls navigation ordering and metadata.
+ */
+const META_FILE = "_meta.json";
+/**
+ * Check whether a file change should trigger a navigation rebuild.
+ *
+ * Navigation-relevant changes are:
+ * - Addition or removal of `.mdx` / `.md` files
+ * - Modification of `_meta.json` files
+ *
+ * @param filePath - Absolute path of the changed file
+ * @param contentDir - Absolute path of the watched content directory
+ * @returns `true` if the change should trigger a navigation rebuild
+ */
+export function isNavigationRelevant(filePath, contentDir) {
+    // Must be within the content directory (ensure trailing slash to prevent
+    // sibling directory matches, e.g., docs-backup/ matching docs/)
+    const normalizedDir = contentDir.endsWith("/")
+        ? contentDir
+        : contentDir + "/";
+    if (!filePath.startsWith(normalizedDir)) {
+        return false;
+    }
+    const name = basename(filePath);
+    // _meta.json changes always affect navigation
+    if (name === META_FILE) {
+        return true;
+    }
+    // Content file additions/removals affect navigation
+    return CONTENT_EXTENSIONS.has(extname(name));
+}
+/**
+ * Create a navigation watcher that rebuilds the navigation tree
+ * when relevant content files change.
+ *
+ * The watcher debounces rapid file system events (e.g., git checkout)
+ * to avoid redundant rebuilds.
+ *
+ * @param options - Configuration for the watcher
+ * @returns A cleanup function that stops the watcher's debounce timer
+ */
+export function createNavigationWatcher(options) {
+    const { contentDir, onNavigationUpdate, debounceMs = 100 } = options;
+    let debounceTimer = null;
+    function scheduleRebuild() {
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(async () => {
+            debounceTimer = null;
+            try {
+                const tree = await buildNavigationTree(contentDir);
+                onNavigationUpdate(tree);
+            }
+            catch {
+                // If the build fails (e.g., directory temporarily missing during git operations),
+                // silently ignore — the next change will trigger another rebuild.
+            }
+        }, debounceMs);
+    }
+    function handleFileChange(filePath) {
+        if (isNavigationRelevant(filePath, contentDir)) {
+            scheduleRebuild();
+        }
+    }
+    function cleanup() {
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+    }
+    return { handleFileChange, cleanup };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/navigation/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/navigation/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAcnD;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,SAAS,GAAG,YAAY,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,UAAkB;IAElB,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,aAAa,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC5C,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC;IACrB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEhC,8CAA8C;IAC9C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oDAAoD;IACpD,OAAO,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IASvE,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;IACrE,IAAI,aAAa,GAAyC,IAAI,CAAC;IAE/D,SAAS,eAAe;QACtB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;QACD,aAAa,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YACpC,aAAa,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;gBACnD,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,kFAAkF;gBAClF,kEAAkE;YACpE,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC;IAED,SAAS,gBAAgB,CAAC,QAAgB;QACxC,IAAI,oBAAoB,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YAC/C,eAAe,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,SAAS,OAAO;QACd,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5B,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC"}

package/dist/openapi/parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OpenAPI spec parser wrapping @redocly/openapi-core.
+ *
+ * Resolves $ref pointers via Redocly's `bundle()`, producing a fully
+ * dereferenced document ready for transformation. Supports OpenAPI 3.0
+ * and 3.1 specifications.
+ *
+ * @module
+ */
+import type { ParsedOpenApiSpec } from "./types.js";
+/**
+ * Parse an OpenAPI spec file and produce a structured `ParsedOpenApiSpec`.
+ *
+ * 1. Validates the file exists on disk
+ * 2. Uses `@redocly/openapi-core` `bundle()` to resolve `$ref` pointers
+ * 3. Detects OpenAPI version (3.0 or 3.1)
+ * 4. Passes the parsed document to the transformer
+ *
+ * @param specPath - Absolute or relative path to an OpenAPI YAML/JSON spec
+ * @returns Parsed and transformed spec data
+ * @throws {SpecglassError} If the file is missing, unparseable, or not an OpenAPI document
+ */
+export declare function parseOpenApiSpec(specPath: string): Promise<ParsedOpenApiSpec>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/openapi/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/openapi/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,CAAC,CAgD5B"}

package/dist/openapi/parser.js

@@ -0,0 +1,53 @@
+/**
+ * OpenAPI spec parser wrapping @redocly/openapi-core.
+ *
+ * Resolves $ref pointers via Redocly's `bundle()`, producing a fully
+ * dereferenced document ready for transformation. Supports OpenAPI 3.0
+ * and 3.1 specifications.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { bundle, createConfig } from "@redocly/openapi-core";
+import { SpecglassError } from "../errors/specglass-error.js";
+import { transformSpec } from "./transformer.js";
+/**
+ * Parse an OpenAPI spec file and produce a structured `ParsedOpenApiSpec`.
+ *
+ * 1. Validates the file exists on disk
+ * 2. Uses `@redocly/openapi-core` `bundle()` to resolve `$ref` pointers
+ * 3. Detects OpenAPI version (3.0 or 3.1)
+ * 4. Passes the parsed document to the transformer
+ *
+ * @param specPath - Absolute or relative path to an OpenAPI YAML/JSON spec
+ * @returns Parsed and transformed spec data
+ * @throws {SpecglassError} If the file is missing, unparseable, or not an OpenAPI document
+ */
+export async function parseOpenApiSpec(specPath) {
+    // Detect if path is a remote URL
+    const isUrl = specPath.startsWith("http://") || specPath.startsWith("https://");
+    const ref = isUrl ? specPath : resolve(specPath);
+    // Pre-check: for local files, does the file exist?
+    if (!isUrl && !existsSync(ref)) {
+        throw new SpecglassError(`OpenAPI spec file not found: ${specPath}`, "OPENAPI_PARSE_ERROR", ref, undefined, "Check that the file path is correct and the file exists.");
+    }
+    let parsed;
+    try {
+        const config = await createConfig({});
+        const result = await bundle({ ref, config });
+        parsed = result.bundle.parsed;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown parsing error";
+        throw new SpecglassError(`Failed to parse OpenAPI spec: ${message}`, "OPENAPI_PARSE_ERROR", ref, undefined, "Check that the file is valid YAML/JSON and conforms to OpenAPI 3.x");
+    }
+    // Validate this is actually an OpenAPI document
+    const openapiVersion = parsed?.openapi;
+    if (typeof openapiVersion !== "string" || !openapiVersion.startsWith("3.")) {
+        throw new SpecglassError(`File is not an OpenAPI 3.x specification: ${specPath}`, "OPENAPI_PARSE_ERROR", ref, undefined, `Expected an "openapi" field starting with "3." but got ${JSON.stringify(openapiVersion)}. ` +
+            "Ensure the file is a valid OpenAPI 3.0 or 3.1 specification.");
+    }
+    return transformSpec(parsed);
+}
+//# sourceMappingURL=parser.js.map

package/dist/openapi/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/openapi/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB;IAEhB,iCAAiC;IACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjD,mDAAmD;IACnD,IAAI,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,cAAc,CACtB,gCAAgC,QAAQ,EAAE,EAC1C,qBAAqB,EACrB,GAAG,EACH,SAAS,EACT,0DAA0D,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,MAA+B,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAiC,CAAC;IAC3D,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;QACnE,MAAM,IAAI,cAAc,CACtB,iCAAiC,OAAO,EAAE,EAC1C,qBAAqB,EACrB,GAAG,EACH,SAAS,EACT,oEAAoE,CACrE,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,MAAM,cAAc,GAAG,MAAM,EAAE,OAAO,CAAC;IACvC,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,cAAc,CACtB,6CAA6C,QAAQ,EAAE,EACvD,qBAAqB,EACrB,GAAG,EACH,SAAS,EACT,0DAA0D,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI;YAC1F,8DAA8D,CACjE,CAAC;IACJ,CAAC;IAED,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/dist/openapi/transformer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenAPI document transformer.
+ *
+ * Converts a raw (dereferenced) OpenAPI document into the typed
+ * `ParsedOpenApiSpec` data model. Each operation is transformed into
+ * an `ApiEndpoint`; failures on individual endpoints produce
+ * `ApiEndpointError` objects instead of aborting the entire spec (FR40).
+ *
+ * @module
+ */
+import type { ParsedOpenApiSpec } from "./types.js";
+/**
+ * Transform a raw dereferenced OpenAPI document into a `ParsedOpenApiSpec`.
+ *
+ * @param document - The parsed OpenAPI document from @redocly/openapi-core
+ * @returns Structured spec with endpoints, errors, security schemes, and servers
+ */
+export declare function transformSpec(document: Record<string, unknown>): ParsedOpenApiSpec;
+//# sourceMappingURL=transformer.d.ts.map

package/dist/openapi/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../../src/openapi/transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EASV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAcpB;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,iBAAiB,CA+CnB"}