@functional-examples/yaml-manifest 0.0.0-alpha.1

package/dist/extractor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Meta.yml extractor for multi-file examples
+ *
+ * Receives candidates (files and directories) and looks for meta.yml files.
+ * Each folder with meta.yml is treated as a multi-file example,
+ * where all files in the folder belong to that example.
+ */
+import type { Extractor } from '@functional-examples/devkit';
+/**
+ * Options for creating a meta.yml extractor
+ */
+export interface MetaYmlExtractorOptions {
+    /**
+     * Name of the metadata file to look for.
+     * @default 'meta.yml'
+     */
+    metaFileName?: string;
+    /**
+     * Files to exclude from the example (besides the meta file).
+     * @default []
+     */
+    excludeFiles?: string[];
+    /**
+     * Patterns to exclude from file collection within examples.
+     * @default ['node_modules/**', '.git/**']
+     */
+    excludePatterns?: string[];
+}
+/**
+ * Create a meta.yml extractor.
+ *
+ * Scans for directories containing meta.yml files. Each such directory
+ * is treated as a multi-file example with all its contents.
+ *
+ * @example
+ * ```typescript
+ * import { createMetaYmlExtractor } from '@functional-examples/yaml-manifest';
+ *
+ * const extractor = createMetaYmlExtractor({
+ *   metaFileName: 'meta.yaml', // use different filename
+ * });
+ *
+ * // Use with scanExamples
+ * import { scanExamples } from 'functional-examples';
+ *
+ * const result = await scanExamples({
+ *   root: './examples',
+ *   extractors: [extractor],
+ * });
+ * ```
+ */
+export declare function createMetaYmlExtractor(opts?: MetaYmlExtractorOptions): Extractor;
+//# sourceMappingURL=extractor.d.ts.map

package/dist/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAGV,SAAS,EAIV,MAAM,6BAA6B,CAAC;AAMrC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,CAAC,EAAE,uBAAuB,GAC7B,SAAS,CA+FX"}

package/dist/extractor.js

@@ -0,0 +1,156 @@
+/**
+ * Meta.yml extractor for multi-file examples
+ *
+ * Receives candidates (files and directories) and looks for meta.yml files.
+ * Each folder with meta.yml is treated as a multi-file example,
+ * where all files in the folder belong to that example.
+ */
+import { parseYaml } from '@functional-examples/devkit';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+const DEFAULT_OPTIONS = {
+    metaFileName: 'meta.yml',
+    excludeFiles: [],
+    excludePatterns: ['node_modules/**', '.git/**'],
+};
+/**
+ * Create a meta.yml extractor.
+ *
+ * Scans for directories containing meta.yml files. Each such directory
+ * is treated as a multi-file example with all its contents.
+ *
+ * @example
+ * ```typescript
+ * import { createMetaYmlExtractor } from '@functional-examples/yaml-manifest';
+ *
+ * const extractor = createMetaYmlExtractor({
+ *   metaFileName: 'meta.yaml', // use different filename
+ * });
+ *
+ * // Use with scanExamples
+ * import { scanExamples } from 'functional-examples';
+ *
+ * const result = await scanExamples({
+ *   root: './examples',
+ *   extractors: [extractor],
+ * });
+ * ```
+ */
+export function createMetaYmlExtractor(opts) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    async function extractFromManifest(metaPath, exampleDir) {
+        const metaContent = await readFile(metaPath, 'utf-8');
+        const metadata = (await parseYaml(metaContent));
+        const dirName = path.basename(exampleDir);
+        const id = metadata.id ?? dirName;
+        const files = await collectFiles(exampleDir, [...options.excludeFiles, options.metaFileName], options.excludePatterns);
+        const claimedFiles = [metaPath, ...files.map((f) => f.absolutePath)];
+        return {
+            example: {
+                id,
+                title: metadata.title ?? dirName,
+                description: metadata.description,
+                rootPath: exampleDir,
+                files,
+                metadata,
+                extractorName: 'meta-yml',
+            },
+            claimedFiles,
+        };
+    }
+    return {
+        name: 'meta-yml',
+        async extract(candidates, extractorOpts) {
+            const examples = [];
+            const errors = [];
+            const claimedFiles = new Set();
+            // Track processed directories to avoid duplicate extraction
+            // (when both directory and meta file are candidates)
+            const processedDirs = new Set();
+            for (const candidate of candidates) {
+                if (extractorOpts.signal?.aborted)
+                    break;
+                const fullPath = path.join(candidate.parentPath, candidate.name);
+                // File candidate: check if it's our meta file
+                if (candidate.isFile() && candidate.name === options.metaFileName) {
+                    const exampleDir = path.dirname(fullPath);
+                    // Skip if we already processed this directory
+                    if (processedDirs.has(exampleDir))
+                        continue;
+                    try {
+                        const result = await extractFromManifest(fullPath, exampleDir);
+                        examples.push(result.example);
+                        result.claimedFiles.forEach((f) => claimedFiles.add(f));
+                        processedDirs.add(exampleDir);
+                    }
+                    catch (error) {
+                        errors.push({
+                            path: fullPath,
+                            message: error.message,
+                            cause: error,
+                        });
+                    }
+                    continue;
+                }
+                // Directory candidate: look for meta file inside
+                if (candidate.isDirectory()) {
+                    // Skip if we already processed this directory
+                    if (processedDirs.has(fullPath))
+                        continue;
+                    const metaPath = path.join(fullPath, options.metaFileName);
+                    try {
+                        const result = await extractFromManifest(metaPath, fullPath);
+                        examples.push(result.example);
+                        result.claimedFiles.forEach((f) => claimedFiles.add(f));
+                        processedDirs.add(fullPath);
+                    }
+                    catch {
+                        // No meta file in this directory, skip silently
+                    }
+                }
+            }
+            return { examples, errors, claimedFiles };
+        },
+    };
+}
+/**
+ * Recursively collect all files in a directory
+ */
+async function collectFiles(dir, excludeNames, excludePatterns) {
+    const files = [];
+    async function walk(currentDir, baseDir) {
+        const entries = await readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            // Skip excluded files by name
+            if (excludeNames.includes(entry.name))
+                continue;
+            const fullPath = path.join(currentDir, entry.name);
+            const relativePath = path.relative(baseDir, fullPath);
+            // Check exclude patterns
+            if (excludePatterns.some((pattern) => {
+                // Simple glob matching
+                const regex = new RegExp(pattern
+                    .replace(/\*\*/g, '<<GLOBSTAR>>')
+                    .replace(/\*/g, '[^/]*')
+                    .replace(/<<GLOBSTAR>>/g, '.*'));
+                return regex.test(relativePath);
+            })) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(fullPath, baseDir);
+            }
+            else {
+                const raw = await readFile(fullPath, 'utf-8');
+                files.push({
+                    absolutePath: fullPath,
+                    relativePath,
+                    raw,
+                });
+            }
+        }
+    }
+    await walk(dir, dir);
+    return files;
+}
+//# sourceMappingURL=extractor.js.map

package/dist/extractor.js.map

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

package/dist/extractor.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @functional-examples/yaml-manifest
+ *
+ * YAML manifest plugin for multi-file examples.
+ *
+ * @example
+ * ```typescript
+ * import { createYamlManifestPlugin } from '@functional-examples/yaml-manifest';
+ * import { scanExamples } from 'functional-examples';
+ *
+ * const result = await scanExamples({
+ *   root: './examples',
+ *   plugins: [createYamlManifestPlugin()],
+ * });
+ * ```
+ */
+import type { Plugin } from '@functional-examples/devkit';
+import { createMetaYmlExtractor, type MetaYmlExtractorOptions } from './extractor.js';
+export { createMetaYmlExtractor, type MetaYmlExtractorOptions, } from './extractor.js';
+export declare const createYamlManifestExtractor: typeof createMetaYmlExtractor;
+export type YamlManifestExtractorOptions = MetaYmlExtractorOptions;
+/**
+ * Create a YAML manifest plugin for functional-examples.
+ *
+ * This plugin scans for directories containing meta.yml files,
+ * treating each as a multi-file example.
+ *
+ * Unlike language plugins, this has no extensions (not file-type specific)
+ * and no fileContentsParser (manifest is separate from content).
+ */
+export declare function createYamlManifestPlugin(options?: MetaYmlExtractorOptions): Plugin;
+//# 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":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,EAC7B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,2BAA2B,+BAAyB,CAAC;AAClE,MAAM,MAAM,4BAA4B,GAAG,uBAAuB,CAAC;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAOR"}

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * @functional-examples/yaml-manifest
+ *
+ * YAML manifest plugin for multi-file examples.
+ *
+ * @example
+ * ```typescript
+ * import { createYamlManifestPlugin } from '@functional-examples/yaml-manifest';
+ * import { scanExamples } from 'functional-examples';
+ *
+ * const result = await scanExamples({
+ *   root: './examples',
+ *   plugins: [createYamlManifestPlugin()],
+ * });
+ * ```
+ */
+import { createMetaYmlExtractor, } from './extractor.js';
+// Re-export for backward compatibility
+export { createMetaYmlExtractor, } from './extractor.js';
+// New name alias
+export const createYamlManifestExtractor = createMetaYmlExtractor;
+/**
+ * Create a YAML manifest plugin for functional-examples.
+ *
+ * This plugin scans for directories containing meta.yml files,
+ * treating each as a multi-file example.
+ *
+ * Unlike language plugins, this has no extensions (not file-type specific)
+ * and no fileContentsParser (manifest is separate from content).
+ */
+export function createYamlManifestPlugin(options) {
+    return {
+        name: 'yaml-manifest',
+        extractor: createMetaYmlExtractor(options),
+        // No extensions - not file-type specific
+        // No fileContentsParser - manifest is separate from content
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AAExB,uCAAuC;AACvC,OAAO,EACL,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AAExB,iBAAiB;AACjB,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAGlE;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAiC;IAEjC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,SAAS,EAAE,sBAAsB,CAAC,OAAO,CAAC;QAC1C,yCAAyC;QACzC,4DAA4D;KAC7D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@functional-examples/yaml-manifest",
+  "version": "0.0.0-alpha.1",
+  "description": "YAML manifest plugin for multi-file examples in functional-examples",
+  "author": {
+    "name": "Craigory Coppola",
+    "url": "https://craigory.dev"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.7.1",
+    "@functional-examples/devkit": "0.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.8",
+    "typescript": "^5.7.2",
+    "vitest": "^1.3.1",
+    "@functional-examples/devkit": "0.0.0-alpha.1"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "homepage": "https://craigory.dev/functional-examples",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentEnder/functional-examples.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AgentEnder/functional-examples/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint ."
+  }
+}