functional-examples 0.0.0-alpha.1 → 0.0.0-alpha.2

package/README.md

@@ -24,27 +24,33 @@ yarn add functional-examples
 ### Scanning for Examples
 
 ```typescript
-import { scanExamples } from 'functional-examples';
+/**
+ * Basic example: Scanning for examples in a directory
+ */
+import { resolveConfig, scanExamples } from 'functional-examples';
 
-const { examples, errors } = await scanExamples('./examples');
+async function main() {
+  // Resolve config (auto-detects installed plugins)
+  const config = await resolveConfig({ root: './examples' });
 
-for (const example of examples) {
-  console.log(example.metadata.title);
-  console.log(example.files.map(f => f.path));
-}
-```
+  // Scan for examples
+  const result = await scanExamples(config);
 
-### Extracting Code Regions
+  console.log(`Found ${result.examples.length} examples:`);
+  for (const example of result.examples) {
+    console.log(`  - ${example.title} (${example.id})`);
+  }
 
-```typescript
-import { extractRegion, parseRegions } from 'functional-examples';
+  if (result.errors.length > 0) {
+    console.log(`\n${result.errors.length} errors occurred:`);
+    for (const error of result.errors) {
+      console.log(`  - ${error.path}: ${error.message}`);
+    }
+  }
+}
 
-// Extract a specific region
-const setupCode = extractRegion(code, 'setup', { extension: 'ts' });
+main().catch(console.error);
 
-// Get all regions
-const regions = parseRegions(code, { extension: 'py' });
-console.log(regions['main']?.content);
 ```
 
 ## Example Formats
@@ -64,7 +70,6 @@ examples/
 id: my-example
 title: My Example
 description: Demonstrates something useful
-entryPoint: main.ts
 ```
 
 ### File-based (YAML frontmatter)
@@ -97,24 +102,161 @@ Supports 30+ languages with automatic comment syntax detection.
 ## Custom Extractors
 
 ```typescript
-import { ExtractorRegistry, MetadataExtractor } from 'functional-examples';
+/**
+ * Custom TOML-based extractor example.
+ *
+ * This demonstrates how to create your own extractor that:
+ * 1. Scans for a specific file pattern (meta.toml)
+ * 2. Parses metadata from that file format
+ * 3. Claims files and returns Example objects
+ */
+import {
+  type Example,
+  type Extractor,
+  type ExtractorResult,
+} from 'functional-examples';
+import { readdirSync, type Dirent } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path, { join } from 'node:path';
+
+/**
+ * Metadata structure for TOML examples.
+ * You can define any shape that fits your use case.
+ */
+export interface TomlMetadata {
+  id: string;
+  title: string;
+  description?: string;
+  author?: string;
+}
 
-class TomlExtractor implements MetadataExtractor {
-  readonly name = 'toml';
+/**
+ * Create a custom extractor that reads TOML metadata files.
+ *
+ * Extractors implement a candidate-based pattern: they're called with
+ * pre-filtered candidates (files and directories) and decide which to handle.
+ */
+export function createTomlExtractor(): Extractor<TomlMetadata> {
+  return {
+    name: 'toml-extractor',
+
+    async extract(
+      candidates: Dirent[]
+    ): Promise<ExtractorResult<TomlMetadata>> {
+      const examples: Example<TomlMetadata>[] = [];
+      const claimedFiles = new Set<string>();
+      const errors: { path: string; message: string }[] = [];
+
+      // Find meta.toml files from candidates
+      const tomlFiles: string[] = [];
+
+      for (const candidate of candidates) {
+        const fullPath = path.join(candidate.parentPath, candidate.name);
+
+        if (candidate.isFile()) {
+          // Direct file candidate: check if it's a meta.toml
+          if (candidate.name === 'meta.toml') {
+            tomlFiles.push(fullPath);
+          }
+        } else if (candidate.isDirectory()) {
+          // Directory candidate: look for meta.toml inside
+          const metaPath = path.join(fullPath, 'meta.toml');
+          try {
+            await readFile(metaPath, 'utf-8');
+            tomlFiles.push(metaPath);
+          } catch {
+            // No meta.toml in this directory, skip
+          }
+        }
+      }
+
+      for (const tomlFile of tomlFiles) {
+        try {
+          const content = await readFile(tomlFile, 'utf-8');
+          const metadata = parseSimpleToml(content);
+
+          const exampleDir = path.dirname(tomlFile);
+
+          // Collect all files in the example directory
+          const files = collectExampleFiles(exampleDir);
+
+          // Claim all files
+          for (const file of files) {
+            claimedFiles.add(file);
+          }
+
+          examples.push({
+            id: metadata.id,
+            title: metadata.title,
+            description: metadata.description,
+            rootPath: exampleDir,
+            files: files.map((f) => ({
+              absolutePath: f,
+              relativePath: path.relative(exampleDir, f),
+            })),
+            metadata,
+            extractorName: 'toml-extractor',
+          });
+        } catch (err) {
+          errors.push({
+            path: tomlFile,
+            message: `Failed to parse: ${(err as Error).message}`,
+          });
+        }
+      }
+
+      return { examples, errors, claimedFiles };
+    },
+  };
+}
 
-  canExtract(context) {
-    return context.entries?.includes('meta.toml') ?? false;
+/**
+ * Simplified TOML parser for demonstration.
+ * In production, use a proper TOML library like @iarna/toml.
+ */
+function parseSimpleToml(content: string): TomlMetadata {
+  const lines = content.split('\n');
+  const result: Record<string, string> = {};
+
+  for (const line of lines) {
+    // Match: key = "value"
+    const match = line.match(/^(\w+)\s*=\s*"(.*)"/);
+    if (match) {
+      result[match[1]] = match[2];
+    }
   }
 
-  async extract(context) {
-    // Custom extraction logic
+  if (!result['id'] || !result['title']) {
+    throw new Error('TOML must have id and title fields');
   }
+
+  return {
+    id: result['id'],
+    title: result['title'],
+    description: result['description'],
+    author: result['author'],
+  };
 }
 
-const registry = new ExtractorRegistry()
-  .register(new TomlExtractor());
+function collectExampleFiles(root: string) {
+  if (root.endsWith('node_modules')) {
+    return [];
+  }
+
+  let files: string[] = [];
+  const entries = readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      files = files.concat(
+        collectExampleFiles(join(entry.parentPath, entry.name))
+      );
+    } else {
+      files.push(join(entry.parentPath, entry.name));
+    }
+  }
+  return files;
+}
 
-const scanner = new ExampleScanner({ extractors: registry });
 ```
 
 ## API Reference

package/README.md.template

@@ -0,0 +1,106 @@
+# functional-examples
+
+A language-agnostic library for treating code examples as first-class citizens.
+
+## Features
+
+- **Pluggable metadata extraction**: YAML frontmatter and meta.yml built-in
+- **Language-aware region parsing**: Extracts code regions with comment-style detection
+- **Flexible scanning**: Directory-based and file-based example discovery
+- **Type-safe API**: Full TypeScript support with generic metadata types
+
+## Installation
+
+```bash
+npm install functional-examples
+# or
+pnpm add functional-examples
+# or
+yarn add functional-examples
+```
+
+## Quick Start
+
+### Scanning for Examples
+
+<%= example('basic-usage').file('scan.ts') %>
+
+## Example Formats
+
+### Directory-based (meta.yml)
+
+```
+examples/
+  my-example/
+    meta.yml
+    main.ts
+    helper.ts
+```
+
+**meta.yml:**
+```yaml
+id: my-example
+title: My Example
+description: Demonstrates something useful
+```
+
+### File-based (YAML frontmatter)
+
+```typescript
+// ---
+// title: My Example
+// description: A single-file example
+// ---
+
+console.log('Hello, world!');
+```
+
+## Region Markers
+
+Mark regions in your code for extraction:
+
+```typescript
+// #region setup
+const db = createDatabase();
+// #endregion setup
+
+// #region main
+await db.query('SELECT * FROM users');
+// #endregion main
+```
+
+Supports 30+ languages with automatic comment syntax detection.
+
+## Custom Extractors
+
+<%= example('custom-extractor').file('toml-extractor.ts') %>
+
+## API Reference
+
+### Scanner
+
+- `scanExamples(directory, options?)` - Scan a directory for examples
+- `ExampleScanner` - Class for customized scanning
+
+### Extractors
+
+- `createDefaultRegistry()` - Create registry with built-in extractors
+- `YamlFrontmatterExtractor` - Single-file YAML frontmatter
+- `MetaYmlExtractor` - Directory-based meta.yml
+
+### Regions
+
+- `parseRegions(code, options?)` - Parse all regions
+- `extractRegion(code, regionId, options?)` - Extract single region
+- `stripRegionMarkers(code, options?)` - Remove all markers
+- `listRegions(code, options?)` - List region IDs
+- `LANGUAGE_CONFIGS` - Language comment syntax mappings
+
+### File Helpers
+
+- `readExampleFile(path, options?)` - Read file with optional region
+- `readExampleFiles(directory, files)` - Read multiple files
+
+## License
+
+MIT

package/dist/cli/commands/scan.d.ts

@@ -9,7 +9,7 @@ export declare const scanCommand: import("cli-forge").CLI<{
 } & {} & {
     config?: string;
 } & {} & {
-    format?: "yaml" | "json" | "table";
+    format?: "json" | "table" | "yaml";
 } & {} & {
     output?: string;
 } & {} & {

package/dist/cli/commands/validate.d.ts

@@ -1,10 +1,10 @@
 /**
- * Validate command - validate configuration file
+ * Validate command - validate configuration and example metadata
  */
 export declare const validateCommand: import("cli-forge").CLI<{
     unmatched: string[];
     '--'?: string[];
 } & {
     strict?: boolean;
-} & {}, Promise<void>, {}, undefined>;
+} & {}, Promise<any>, {}, undefined>;
 //# sourceMappingURL=validate.d.ts.map

package/dist/cli/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,eAAO,MAAM,eAAe;;;;;qCAkE1B,CAAC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,eAAO,MAAM,eAAe;;;;;oCAsJ1B,CAAC"}

package/dist/cli/commands/validate.js

@@ -1,11 +1,14 @@
 /**
- * Validate command - validate configuration file
+ * Validate command - validate configuration and example metadata
  */
 import { cli } from 'cli-forge';
 import { resolveConfig } from '../../config/resolver.js';
 import { validateConfig } from '../../config/validator.js';
+import { scanExamples } from '../../scanner/index.js';
+import { mergeMetadataSchemas } from '../../schema/merger.js';
+import { createSchemaValidator } from '../../schema/validator.js';
 export const validateCommand = cli('validate', {
-    description: 'Validate the configuration file',
+    description: 'Validate configuration and example metadata',
     builder: (cmd) => cmd.option('strict', {
         type: 'boolean',
         description: 'Treat warnings as errors',
@@ -22,44 +25,108 @@ export const validateCommand = cli('validate', {
         }
         console.log(`Validating: ${configPath}`);
         console.log('');
-        const errors = validateConfig(config);
-        if (errors.length > 0) {
+        // Phase 1: Validate config structure
+        const configErrors = validateConfig(config);
+        if (configErrors.length > 0) {
             console.error('Configuration errors:');
-            for (const error of errors) {
+            for (const error of configErrors) {
                 console.error(`  - ${error.path}: ${error.message}`);
             }
             process.exit(1);
         }
+        let resolved;
         try {
-            const resolved = await resolveConfig(config);
-            console.log('Configuration is valid!');
+            resolved = await resolveConfig(config);
+        }
+        catch (error) {
+            console.error('Failed to resolve configuration:');
+            console.error(`  ${error.message}`);
+            return void process.exit(1);
+        }
+        console.log('Configuration is valid!');
+        console.log('');
+        console.log(`Extractors: ${resolved.extractors.length}`);
+        for (const extractor of resolved.extractors) {
+            console.log(`  - ${extractor.name}`);
+        }
+        if (resolved.pathMappings.length > 0) {
             console.log('');
-            console.log(`Extractors: ${resolved.extractors.length}`);
-            for (const extractor of resolved.extractors) {
-                console.log(`  - ${extractor.name}`);
+            console.log(`Path mappings: ${resolved.pathMappings.length}`);
+            for (const mapping of resolved.pathMappings) {
+                console.log(`  - ${mapping.pattern} -> ${mapping.extractor}`);
             }
-            if (resolved.pathMappings.length > 0) {
-                console.log('');
-                console.log(`Path mappings: ${resolved.pathMappings.length}`);
-                for (const mapping of resolved.pathMappings) {
-                    console.log(`  - ${mapping.pattern} -> ${mapping.extractor}`);
-                }
-            }
-            console.log('');
-            console.log('Scan config:');
-            console.log(`  include: ${resolved.scan.include.join(', ') || '(all)'}`);
-            console.log(`  exclude: ${resolved.scan.exclude.join(', ') || '(none)'}`);
-            if (resolved.extractors.length === 0 && options.strict) {
+        }
+        console.log('');
+        console.log('Scan config:');
+        console.log(`  include: ${resolved.scan.include.join(', ') || '(all)'}`);
+        console.log(`  exclude: ${resolved.scan.exclude.join(', ') || '(none)'}`);
+        if (resolved.extractors.length === 0) {
+            if (options.strict) {
                 console.error('');
                 console.error('Warning: No extractors could be loaded.');
                 process.exit(1);
             }
+            return;
         }
-        catch (error) {
-            console.error('Failed to resolve configuration:');
-            console.error(`  ${error.message}`);
+        // Phase 2: Scan examples and validate metadata
+        console.log('');
+        console.log('Scanning examples...');
+        const scanResult = await scanExamples(resolved);
+        console.log(`Found ${scanResult.examples.length} example(s) in ${scanResult.stats.durationMs}ms`);
+        if (scanResult.examples.length === 0) {
+            if (options.strict) {
+                console.error('');
+                console.error('Warning: No examples found.');
+                process.exit(1);
+            }
+            return;
+        }
+        // Phase 3: Validate metadata against the combined schema
+        const pluginSchemas = resolved.registry.getSchemas();
+        const mergedSchema = mergeMetadataSchemas({
+            configSchema: resolved.metadata,
+            pluginSchemas,
+        });
+        delete mergedSchema['$schema'];
+        const validateSchema = createSchemaValidator(mergedSchema);
+        let metadataErrorCount = 0;
+        const exampleErrors = [];
+        for (const example of scanResult.examples) {
+            const result = validateSchema(example.metadata);
+            if (!result.success) {
+                const messages = result.errors.map((e) => `${e.path || '(root)'}: ${e.message}`);
+                exampleErrors.push({ displayPath: example.displayPath, messages });
+                metadataErrorCount += messages.length;
+            }
+        }
+        // Report scan-level errors (extractor failures, conflicts, etc.)
+        if (scanResult.errors.length > 0) {
+            console.error('');
+            console.error(`Scan errors (${scanResult.errors.length}):`);
+            for (const error of scanResult.errors) {
+                console.error(`  ${error.path}:`);
+                console.error(`    ${error.message}`);
+            }
+        }
+        // Report metadata validation errors
+        if (exampleErrors.length > 0) {
+            console.error('');
+            console.error(`Metadata validation errors (${metadataErrorCount} across ${exampleErrors.length} example(s)):`);
+            for (const { displayPath, messages } of exampleErrors) {
+                console.error(`  ${displayPath}:`);
+                for (const msg of messages) {
+                    console.error(`    - ${msg}`);
+                }
+            }
+        }
+        const totalErrors = scanResult.errors.length + metadataErrorCount;
+        if (totalErrors > 0) {
+            console.error('');
+            console.error(`Validation failed with ${totalErrors} error(s).`);
             process.exit(1);
         }
+        console.log('');
+        console.log('All examples pass metadata validation!');
     },
 });
 //# sourceMappingURL=validate.js.map

package/dist/cli/commands/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,aAAa,EAAkB,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC,UAAU,EAAE;IAC7C,WAAW,EAAE,iCAAiC;IAC9C,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CACf,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE;QACnB,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,0BAA0B;QACvC,OAAO,EAAE,KAAK;KACf,CAAC;IACJ,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,OAA8D,CAAC;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC;QACnC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC;QAE/B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;YAC5C,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,eAAe,UAAU,EAAE,CAAC,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEhB,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QAEtC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;YACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,OAAO,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACvD,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAE7C,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;YACvC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,eAAe,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YACzD,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;gBAC5C,OAAO,CAAC,GAAG,CAAC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YACvC,CAAC;YAED,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChB,OAAO,CAAC,GAAG,CAAC,kBAAkB,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC9D,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;oBAC5C,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,OAAO,OAAO,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;gBAChE,CAAC;YACH,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,cAAc,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;YACzE,OAAO,CAAC,GAAG,CAAC,cAAc,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC;YAE1E,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACvD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClB,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;gBACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;YAClD,OAAO,CAAC,KAAK,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -17,7 +17,7 @@ declare const app: import("cli-forge").CLI<{
 } & {} & {
     config?: string;
 } & {} & {
-    format?: "yaml" | "json" | "table";
+    format?: "table" | "json" | "yaml";
 } & {} & {
     output?: string;
 } & {} & {
@@ -39,7 +39,7 @@ declare const app: import("cli-forge").CLI<{
     '--'?: string[];
 } & {
     strict?: boolean;
-} & {}, Promise<void>, {}, undefined>, import("cli-forge").CLI<{
+} & {}, Promise<any>, {}, undefined>, import("cli-forge").CLI<{
     unmatched: string[];
     '--'?: string[];
 } & {
@@ -53,7 +53,7 @@ declare const app: import("cli-forge").CLI<{
     unmatched: string[];
     '--'?: string[];
 } & {
-    format?: "ts" | "json";
+    format?: "json" | "ts";
 } & {} & {
     output?: string;
 } & {} & {

package/dist/config/resolver.d.ts

@@ -1,27 +1,27 @@
 /**
- * Configuration resolver - converts config references to actual extractors
+ * Configuration resolver - converts config references to actual plugins/extractors
  */
 import type { ResolvedConfig } from '../types/index.js';
 import type { ConfigWithRoot } from './types.js';
 export type { ConfigValidationError, ResolvedConfig } from '../types/index.js';
 /**
- * Resolve a configuration to actual extractor instances.
+ * Resolve a configuration to actual plugin and extractor instances.
  *
- * If no extractors are specified, attempts to auto-detect installed extractors.
+ * Plugin resolution follows this priority:
+ * 1. If `config.plugins` contains Plugin instances (from TS configs), use directly
+ * 2. If `config.plugins` contains string/tuple references (from JSON configs),
+ *    resolve them by dynamically importing the package and calling its factory
+ * 3. If no plugins specified at all, auto-detect installed plugin packages
  *
  * @example
  * ```typescript
  * import { resolveConfig } from 'functional-examples';
  *
- * // Auto-detect extractors
- * const config = await resolveConfig({});
+ * // Auto-detect plugins from installed packages
+ * const config = await resolveConfig({ root: './examples' });
  *
  * // Use with scanExamples
- * const result = await scanExamples({
- *   root: './examples',
- *   extractors: config.extractors,
- *   pathMappings: config.pathMappings,
- * });
+ * const result = await scanExamples(config);
  * ```
  */
 export declare function resolveConfig<TMetadata = Record<string, unknown>>(config: ConfigWithRoot<TMetadata>): Promise<ResolvedConfig<TMetadata>>;

package/dist/config/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/config/resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAIV,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAkB/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CA0EpC"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/config/resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAKV,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAmB/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CA0EpC"}