@functional-examples/devkit 0.0.0-alpha.1

package/dist/glob/glob.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export declare function _resetGlobImportCache(): void;
+/**
+ * Options for the glob function.
+ */
+export interface GlobOptions {
+    /** Working directory for pattern resolution */
+    cwd?: string;
+    /** Patterns to exclude from results */
+    ignore?: string[];
+    /** Return absolute paths instead of relative */
+    absolute?: boolean;
+    /** Only return files (not directories) */
+    onlyFiles?: boolean;
+    /** Expand directory matches to their contents */
+    expandDirectories?: boolean;
+}
+/**
+ * Find files matching glob patterns.
+ *
+ * Thin wrapper around tinyglobby that normalizes input
+ * and provides a consistent interface across the monorepo.
+ *
+ * Requires the `tinyglobby` peer dependency to be installed.
+ *
+ * @param patterns - One or more glob patterns
+ * @param options - Glob options
+ * @returns Array of matching file paths
+ */
+export declare function glob(patterns: string | string[], options?: GlobOptions): Promise<string[]>;
+//# sourceMappingURL=glob.d.ts.map

package/dist/glob/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/glob/glob.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CACxB,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAInB"}

package/dist/glob/glob.js

@@ -0,0 +1,36 @@
+let tinyglobbyPromise = null;
+function importTinyglobby() {
+    if (!tinyglobbyPromise) {
+        tinyglobbyPromise = import('tinyglobby').catch(() => {
+            tinyglobbyPromise = null;
+            throw new Error('tinyglobby is required to use @functional-examples/devkit/glob. ' +
+                'Install it with: pnpm add tinyglobby');
+        });
+    }
+    return tinyglobbyPromise;
+}
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export function _resetGlobImportCache() {
+    tinyglobbyPromise = null;
+}
+/**
+ * Find files matching glob patterns.
+ *
+ * Thin wrapper around tinyglobby that normalizes input
+ * and provides a consistent interface across the monorepo.
+ *
+ * Requires the `tinyglobby` peer dependency to be installed.
+ *
+ * @param patterns - One or more glob patterns
+ * @param options - Glob options
+ * @returns Array of matching file paths
+ */
+export async function glob(patterns, options) {
+    const { glob: tinyGlob } = await importTinyglobby();
+    const patternArray = Array.isArray(patterns) ? patterns : [patterns];
+    return tinyGlob(patternArray, options);
+}
+//# sourceMappingURL=glob.js.map

package/dist/glob/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/glob/glob.ts"],"names":[],"mappings":"AAAA,IAAI,iBAAiB,GAAgD,IAAI,CAAC;AAE1E,SAAS,gBAAgB;IACvB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAClD,iBAAiB,GAAG,IAAI,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,kEAAkE;gBAChE,sCAAsC,CACzC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,iBAAiB,GAAG,IAAI,CAAC;AAC3B,CAAC;AAkBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,QAA2B,EAC3B,OAAqB;IAErB,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACpD,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACrE,OAAO,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/glob/index.d.ts

@@ -0,0 +1,3 @@
+export { glob, type GlobOptions } from './glob.js';
+export { isMatch, createMatcher } from './match.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/glob/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/glob/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/glob/index.js

@@ -0,0 +1,3 @@
+export { glob } from './glob.js';
+export { isMatch, createMatcher } from './match.js';
+//# sourceMappingURL=index.js.map

package/dist/glob/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/glob/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/glob/match.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export declare function _resetMatchImportCache(): void;
+/**
+ * Test whether a path matches one or more glob patterns.
+ *
+ * Requires the `picomatch` peer dependency to be installed.
+ *
+ * @param path - The path to test
+ * @param pattern - One or more glob patterns
+ * @returns True if the path matches any of the patterns
+ */
+export declare function isMatch(path: string, pattern: string | string[]): Promise<boolean>;
+/**
+ * Create a reusable matcher function from one or more glob patterns.
+ *
+ * Prefer this over repeated {@link isMatch} calls when matching
+ * many paths against the same pattern—the compiled matcher is
+ * significantly faster for repeated use.
+ *
+ * Requires the `picomatch` peer dependency to be installed.
+ *
+ * @param pattern - One or more glob patterns
+ * @returns A function that tests a path against the compiled patterns
+ */
+export declare function createMatcher(pattern: string | string[]): Promise<(path: string) => boolean>;
+//# sourceMappingURL=match.d.ts.map

package/dist/glob/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/glob/match.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GACzB,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAGpC"}

package/dist/glob/match.js

@@ -0,0 +1,50 @@
+let picomatchPromise = null;
+function importPicomatch() {
+    if (!picomatchPromise) {
+        picomatchPromise = import('picomatch')
+            .then((mod) => (mod.default ?? mod))
+            .catch(() => {
+            picomatchPromise = null;
+            throw new Error('picomatch is required to use @functional-examples/devkit/glob. ' +
+                'Install it with: pnpm add picomatch');
+        });
+    }
+    return picomatchPromise;
+}
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export function _resetMatchImportCache() {
+    picomatchPromise = null;
+}
+/**
+ * Test whether a path matches one or more glob patterns.
+ *
+ * Requires the `picomatch` peer dependency to be installed.
+ *
+ * @param path - The path to test
+ * @param pattern - One or more glob patterns
+ * @returns True if the path matches any of the patterns
+ */
+export async function isMatch(path, pattern) {
+    const picomatch = await importPicomatch();
+    return picomatch.isMatch(path, pattern);
+}
+/**
+ * Create a reusable matcher function from one or more glob patterns.
+ *
+ * Prefer this over repeated {@link isMatch} calls when matching
+ * many paths against the same pattern—the compiled matcher is
+ * significantly faster for repeated use.
+ *
+ * Requires the `picomatch` peer dependency to be installed.
+ *
+ * @param pattern - One or more glob patterns
+ * @returns A function that tests a path against the compiled patterns
+ */
+export async function createMatcher(pattern) {
+    const picomatch = await importPicomatch();
+    return picomatch(pattern);
+}
+//# sourceMappingURL=match.js.map

package/dist/glob/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/glob/match.ts"],"names":[],"mappings":"AAEA,IAAI,gBAAgB,GAAyC,IAAI,CAAC;AAElE,SAAS,eAAe;IACtB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,MAAM,CAAC,WAAW,CAAC;aACnC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAyB,CAAC;aAC3D,KAAK,CAAC,GAAG,EAAE;YACV,gBAAgB,GAAG,IAAI,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,iEAAiE;gBAC/D,qCAAqC,CACxC,CAAC;QACJ,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAY,EACZ,OAA0B;IAE1B,MAAM,SAAS,GAAG,MAAM,eAAe,EAAE,CAAC;IAC1C,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAA0B;IAE1B,MAAM,SAAS,GAAG,MAAM,eAAe,EAAE,CAAC;IAC1C,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { TypeGuard } from './types/guards.js';
+export type { BaseMetadata, Config, ConfigValidationError, ConfigWithRoot, Example, ExampleFile, ExampleMetadata, ExampleMetadataRegistry, Extractor, ExtractorConfig, ExtractorConfigOrFunction, ExtractorError, ExtractorFactory, ExtractorOptions, ExtractorReference, ExtractorResult, FileContentsParser, FileParseContext, GenerateConfig, JSONSchemaObject, ParsedRegion, PathMapping, Plugin, PluginCommands, PluginRegistryInterface, PluginSchemaEntry, PluginSchemas, PluginValidatorEntry, PluginValidators, ResolvedConfig, ScanConfig, ScannedExample, ValidationError, ValidationResult, } from './types/index.js';
+export { createMatcher, glob, isMatch, type GlobOptions, } from './glob/index.js';
+export { JsonParseError, parseJson, tryParseJson } from './json/index.js';
+export { parseYaml, tryParseYaml, YamlParseError } from './yaml/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EACV,YAAY,EACZ,MAAM,EACN,qBAAqB,EACrB,cAAc,EACd,OAAO,EACP,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,SAAS,EACT,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,MAAM,EACN,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,IAAI,EACJ,OAAO,EACP,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createMatcher, glob, isMatch, } from './glob/index.js';
+export { JsonParseError, parseJson, tryParseJson } from './json/index.js';
+export { parseYaml, tryParseYaml, YamlParseError } from './yaml/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuCA,OAAO,EACL,aAAa,EACb,IAAI,EACJ,OAAO,GAER,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/json/errors.d.ts

@@ -0,0 +1,41 @@
+export interface JsonParseErrorOptions {
+    content: string;
+    error: Error;
+    filePath?: string;
+}
+export interface FormattedJsonError {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Converts a character offset in a string to 1-based line and column numbers.
+ */
+export declare function positionToLineColumn(content: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Attempts to extract line/column information from a JSON parse error.
+ *
+ * Checks for:
+ * 1. json5-style errors with `lineNumber`/`columnNumber` properties
+ * 2. Node.js JSON.parse errors with "at line X column Y"
+ * 3. Node.js JSON.parse errors with "at position N" (converted via positionToLineColumn)
+ */
+export declare function extractErrorPosition(error: Error, content?: string): {
+    line?: number;
+    column?: number;
+};
+/**
+ * Builds a code frame showing context around an error location.
+ *
+ * Shows approximately 2 lines before and after the error line,
+ * with a `>` marker on the error line and a `^` pointer at the column.
+ */
+export declare function buildCodeFrame(content: string, line: number, column?: number): string;
+/**
+ * Formats a JSON parse error into a readable message with code frame.
+ */
+export declare function formatJsonError(options: JsonParseErrorOptions): FormattedJsonError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/json/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/json/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQlC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAgCpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAyBR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,qBAAqB,GAC7B,kBAAkB,CA2BpB"}

package/dist/json/errors.js

@@ -0,0 +1,102 @@
+/**
+ * Converts a character offset in a string to 1-based line and column numbers.
+ */
+export function positionToLineColumn(content, offset) {
+    const clamped = Math.max(0, Math.min(offset, content.length));
+    const before = content.slice(0, clamped);
+    const lines = before.split('\n');
+    return {
+        line: lines.length,
+        column: lines[lines.length - 1].length + 1,
+    };
+}
+/**
+ * Attempts to extract line/column information from a JSON parse error.
+ *
+ * Checks for:
+ * 1. json5-style errors with `lineNumber`/`columnNumber` properties
+ * 2. Node.js JSON.parse errors with "at line X column Y"
+ * 3. Node.js JSON.parse errors with "at position N" (converted via positionToLineColumn)
+ */
+export function extractErrorPosition(error, content) {
+    // json5 errors have lineNumber and columnNumber
+    const errorRecord = error;
+    if (typeof errorRecord['lineNumber'] === 'number' &&
+        typeof errorRecord['columnNumber'] === 'number') {
+        return {
+            line: errorRecord['lineNumber'],
+            column: errorRecord['columnNumber'],
+        };
+    }
+    const message = error.message;
+    // Node.js "at line X column Y"
+    const lineColMatch = message.match(/at line (\d+) column (\d+)/);
+    if (lineColMatch) {
+        return {
+            line: parseInt(lineColMatch[1], 10),
+            column: parseInt(lineColMatch[2], 10),
+        };
+    }
+    // Node.js "at position N"
+    const posMatch = message.match(/at position (\d+)/);
+    if (posMatch && content) {
+        const offset = parseInt(posMatch[1], 10);
+        return positionToLineColumn(content, offset);
+    }
+    return {};
+}
+/**
+ * Builds a code frame showing context around an error location.
+ *
+ * Shows approximately 2 lines before and after the error line,
+ * with a `>` marker on the error line and a `^` pointer at the column.
+ */
+export function buildCodeFrame(content, line, column) {
+    const lines = content.split('\n');
+    const startLine = Math.max(1, line - 2);
+    const endLine = Math.min(lines.length, line + 2);
+    const gutterWidth = String(endLine).length;
+    const frameLines = [];
+    for (let i = startLine; i <= endLine; i++) {
+        const lineContent = lines[i - 1];
+        const lineNum = String(i).padStart(gutterWidth);
+        if (i === line) {
+            frameLines.push(`> ${lineNum} | ${lineContent}`);
+            if (column !== undefined) {
+                const padding = ' '.repeat(gutterWidth + 4 + column - 1);
+                frameLines.push(`${padding}^`);
+            }
+        }
+        else {
+            frameLines.push(`  ${lineNum} | ${lineContent}`);
+        }
+    }
+    return frameLines.join('\n');
+}
+/**
+ * Formats a JSON parse error into a readable message with code frame.
+ */
+export function formatJsonError(options) {
+    const { content, error, filePath } = options;
+    const { line, column } = extractErrorPosition(error, content);
+    let location = '';
+    if (filePath) {
+        location = filePath;
+        if (line !== undefined) {
+            location += `:${line}`;
+            if (column !== undefined) {
+                location += `:${column}`;
+            }
+        }
+    }
+    const header = location
+        ? `Failed to parse JSON (${location}): ${error.message}`
+        : `Failed to parse JSON: ${error.message}`;
+    let message = header;
+    if (line !== undefined) {
+        const frame = buildCodeFrame(content, line, column);
+        message += '\n\n' + frame;
+    }
+    return { message, line, column };
+}
+//# sourceMappingURL=errors.js.map

package/dist/json/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/json/errors.ts"],"names":[],"mappings":"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"}

package/dist/json/index.d.ts

@@ -0,0 +1,3 @@
+export { positionToLineColumn, extractErrorPosition, buildCodeFrame, formatJsonError, type JsonParseErrorOptions, type FormattedJsonError, } from './errors.js';
+export { JsonParseError, parseJson, tryParseJson, } from './parse.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/json/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/json/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/json/index.js

@@ -0,0 +1,3 @@
+export { positionToLineColumn, extractErrorPosition, buildCodeFrame, formatJsonError, } from './errors.js';
+export { JsonParseError, parseJson, tryParseJson, } from './parse.js';
+//# sourceMappingURL=index.js.map

package/dist/json/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/json/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,eAAe,GAGhB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/json/parse.d.ts

@@ -0,0 +1,45 @@
+import { type FormattedJsonError } from './errors.js';
+/**
+ * Error thrown when JSON parsing fails across all available parsers.
+ */
+export declare class JsonParseError extends Error {
+    readonly line?: number;
+    readonly column?: number;
+    readonly filePath?: string;
+    constructor(formatted: FormattedJsonError, filePath?: string);
+}
+/**
+ * Resets the cached import promises. Used for testing only.
+ * @internal
+ */
+export declare function _resetImportCache(): void;
+/**
+ * Parses a JSON string with progressive fallbacks:
+ * 1. Standard JSON.parse
+ * 2. jsonc-parser (handles comments and trailing commas)
+ * 3. json5 (handles extended JSON5 syntax)
+ *
+ * If all parsers fail, throws a {@link JsonParseError} with a formatted
+ * code frame showing the error location.
+ *
+ * @param content - The JSON string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns The parsed value
+ */
+export declare function parseJson<T = unknown>(content: string, filePath?: string): Promise<T>;
+/**
+ * Wraps {@link parseJson} in a try/catch, returning a discriminated union
+ * indicating success or failure.
+ *
+ * @param content - The JSON string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns A result object with either `{ success: true, data }` or `{ success: false, error }`
+ */
+export declare function tryParseJson<T = unknown>(content: string, filePath?: string): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: JsonParseError;
+}>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/json/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/json/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,MAAM;CAO7D;AAoBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAmDZ;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC,CAgBjF"}

package/dist/json/parse.js

@@ -0,0 +1,122 @@
+import { formatJsonError } from './errors.js';
+/**
+ * Error thrown when JSON parsing fails across all available parsers.
+ */
+export class JsonParseError extends Error {
+    line;
+    column;
+    filePath;
+    constructor(formatted, filePath) {
+        super(formatted.message);
+        this.name = 'JsonParseError';
+        this.line = formatted.line;
+        this.column = formatted.column;
+        this.filePath = filePath;
+    }
+}
+let jsoncParserPromise = null;
+let json5Promise = null;
+function tryImportJsoncParser() {
+    if (!jsoncParserPromise) {
+        jsoncParserPromise = import('jsonc-parser').catch(() => null);
+    }
+    return jsoncParserPromise;
+}
+function tryImportJson5() {
+    if (!json5Promise) {
+        json5Promise = import('json5').catch(() => null);
+    }
+    return json5Promise;
+}
+/**
+ * Resets the cached import promises. Used for testing only.
+ * @internal
+ */
+export function _resetImportCache() {
+    jsoncParserPromise = null;
+    json5Promise = null;
+}
+/**
+ * Parses a JSON string with progressive fallbacks:
+ * 1. Standard JSON.parse
+ * 2. jsonc-parser (handles comments and trailing commas)
+ * 3. json5 (handles extended JSON5 syntax)
+ *
+ * If all parsers fail, throws a {@link JsonParseError} with a formatted
+ * code frame showing the error location.
+ *
+ * @param content - The JSON string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns The parsed value
+ */
+export async function parseJson(content, filePath) {
+    // 1. Try standard JSON.parse
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        // Fall through to JSONC
+    }
+    // Track the best error for final reporting
+    let bestError;
+    // 2. Try jsonc-parser
+    const jsoncParser = await tryImportJsoncParser();
+    if (jsoncParser) {
+        const errors = [];
+        const result = jsoncParser.parse(content, errors, {
+            allowTrailingComma: true,
+        });
+        if (errors.length === 0) {
+            return result;
+        }
+        // Store JSONC error info for later
+        const firstError = errors[0];
+        bestError = new Error(`JSONC parse error at offset ${firstError.offset} (length ${firstError.length})`);
+    }
+    // 3. Try json5
+    const json5 = await tryImportJson5();
+    if (json5) {
+        try {
+            return json5.parse(content);
+        }
+        catch (e) {
+            bestError = e instanceof Error ? e : new Error(String(e));
+        }
+    }
+    // 4. Nothing worked - build the best error we can
+    if (!bestError) {
+        // Re-run JSON.parse to capture the original error
+        try {
+            JSON.parse(content);
+        }
+        catch (e) {
+            bestError = e instanceof Error ? e : new Error(String(e));
+        }
+    }
+    const error = bestError ?? new Error('Failed to parse JSON');
+    const formatted = formatJsonError({ content, error, filePath });
+    throw new JsonParseError(formatted, filePath);
+}
+/**
+ * Wraps {@link parseJson} in a try/catch, returning a discriminated union
+ * indicating success or failure.
+ *
+ * @param content - The JSON string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns A result object with either `{ success: true, data }` or `{ success: false, error }`
+ */
+export async function tryParseJson(content, filePath) {
+    try {
+        const data = await parseJson(content, filePath);
+        return { success: true, data };
+    }
+    catch (e) {
+        const error = e instanceof JsonParseError
+            ? e
+            : new JsonParseError({
+                message: e instanceof Error ? e.message : String(e),
+            }, filePath);
+        return { success: false, error };
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/json/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/json/parse.ts"],"names":[],"mappings":"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"}

package/dist/types/guards.d.ts

@@ -0,0 +1,2 @@
+export type TypeGuard<T> = (val: unknown) => val is T;
+//# sourceMappingURL=guards.d.ts.map

package/dist/types/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/types/guards.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,CAAC"}

package/dist/types/guards.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guards.js.map

package/dist/types/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/types/guards.ts"],"names":[],"mappings":""}