polen 0.11.0-next.17 → 0.11.0-next.18

package/build/api/examples/diagnostic/validator.js

@@ -1,12 +1,35 @@
 import { Catalog as SchemaCatalog } from '#lib/catalog/$';
 import { Document } from '#lib/document/$';
+import { Schema } from '#lib/schema/$';
 import { Version } from '#lib/version/$';
-import { Match } from 'effect';
-import { HashMap } from 'effect/Schema';
+import { Array, Either, Match, Schema as S } from 'effect';
 import { parse, specifiedRules, validate } from 'graphql';
 import { Example } from '../schemas/example/$.js';
 import { makeDiagnosticValidationError } from './diagnostic.js';
 // ============================================================================
+// Schemas
+// ============================================================================
+const GraphQLErrorData = S.Struct({
+    message: S.String,
+    locations: S.optional(S.Array(S.Struct({
+        line: S.Number,
+        column: S.Number,
+    }))),
+});
+// ============================================================================
+// Safe Parsing
+// ============================================================================
+/**
+ * Safely parse a GraphQL document without throwing.
+ * Returns an Either with the document on success or error on failure.
+ */
+const parseDocumentSafe = (content) => {
+    return Either.try({
+        try: () => parse(content),
+        catch: (error) => error,
+    });
+};
+// ============================================================================
 // Validation
 // ============================================================================
 /**
@@ -18,42 +41,60 @@ import { makeDiagnosticValidationError } from './diagnostic.js';
  */
 export const validateExamples = (examples, catalog) => {
     const diagnostics = [];
-    return Match.value(catalog).pipe(Match.tagsExhaustive({
-        CatalogVersioned: (versioned) => {
-            for (const example of examples) {
-                Match.value(example.document).pipe(Match.tagsExhaustive({
-                    DocumentVersioned: (doc) => {
-                        // Validate each version against its corresponding schema
-                        for (const schema of SchemaCatalog.Versioned.getAll(versioned)) {
-                            const content = Document.Versioned.getContentForVersion(doc, schema.version);
-                            if (content) {
-                                const versionStr = Version.encodeSync(schema.version);
-                                validateDocument(example.name, example.path, versionStr, content, schema.definition, diagnostics);
-                            }
-                        }
-                        return undefined;
+    Array.forEach(examples, (example) => {
+        if (example.document._tag === 'DocumentVersioned') {
+            // Versioned document: iterate all versions and let utility handle compatibility
+            const documentVersions = Document.Versioned.getAllVersions(example.document);
+            let versionMismatchDetected = false;
+            Array.forEach(documentVersions, (version) => {
+                // Skip remaining versions if we already detected a version mismatch
+                if (versionMismatchDetected)
+                    return;
+                const result = Document.resolveDocumentAndSchema(example.document, catalog, version);
+                Either.match(result, {
+                    onLeft: (error) => {
+                        // Pattern match on error types - all errors are now tagged
+                        Match.value(error).pipe(Match.when({ _tag: 'VersionCoverageMismatchError' }, (err) => {
+                            diagnostics.push(makeDiagnosticValidationError({
+                                message: `Example "${example.name}" has versioned content but catalog is unversioned`,
+                                example: { name: example.name, path: example.path },
+                                version: undefined,
+                                errors: [{ message: err.reason }],
+                            }));
+                            // Set flag to skip remaining versions - all will have same error
+                            versionMismatchDetected = true;
+                        }), Match.when({ _tag: 'VersionNotFoundInDocumentError' }, () => {
+                            // Skip silently - version not found in document
+                        }), Match.when({ _tag: 'VersionNotFoundInCatalogError' }, () => {
+                            // Skip silently - version not found in catalog
+                        }), Match.when({ _tag: 'EmptyCatalogError' }, () => {
+                            // Skip silently - catalog has no entries
+                        }), Match.exhaustive);
                     },
-                    DocumentUnversioned: (doc) => {
-                        const latestEntry = SchemaCatalog.Versioned.getLatestOrThrow(versioned);
-                        validateDocument(example.name, example.path, 'default', doc.document, latestEntry.definition, diagnostics);
-                        return undefined;
+                    onRight: ({ content, schema }) => {
+                        if (schema) {
+                            validateDocument(example, schema, content, diagnostics);
+                        }
                     },
-                }));
-            }
-            return diagnostics;
-        },
-        CatalogUnversioned: (unversioned) => {
-            // For unversioned catalog, only unversioned documents make sense
-            for (const example of examples) {
-                if (example.document._tag === 'DocumentUnversioned') {
-                    validateDocument(example.name, example.path, 'default', example.document.document, unversioned.schema.definition, diagnostics);
-                }
-                // Versioned/PartiallyVersioned documents with unversioned catalog don't make sense
-                // These should be caught by other diagnostics
-            }
-            return diagnostics;
-        },
-    }));
+                });
+            });
+        }
+        else {
+            // Unversioned document: call without version coverage
+            const result = Document.resolveDocumentAndSchema(example.document, catalog);
+            Either.match(result, {
+                onLeft: () => {
+                    // Resolution failed - skip silently
+                },
+                onRight: ({ content, schema }) => {
+                    if (schema) {
+                        validateDocument(example, schema, content, diagnostics);
+                    }
+                },
+            });
+        }
+    });
+    return diagnostics;
 };
 // ============================================================================
 // Helpers
@@ -61,55 +102,61 @@ export const validateExamples = (examples, catalog) => {
 /**
  * Validate a single document and add diagnostics if needed.
  */
-const validateDocument = (exampleName, examplePath, version, content, schema, diagnostics) => {
-    try {
-        // Parse the GraphQL document
-        const document = parse(content);
-        // Validate against the schema
-        const errors = validate(schema, document, specifiedRules);
-        if (errors.length > 0) {
-            diagnostics.push(makeDiagnosticValidationError({
-                message: formatValidationMessage(exampleName, version, errors),
-                example: { name: exampleName, path: examplePath },
-                version,
-                errors: errors.map(formatGraphQLError),
-            }));
-        }
+const validateDocument = (example, schema, content, diagnostics) => {
+    // Extract version from schema (undefined for unversioned)
+    const version = Schema.getVersion(schema);
+    // Parse the document safely
+    const parseResult = parseDocumentSafe(content);
+    if (Either.isLeft(parseResult)) {
+        // Handle parse errors
+        diagnostics.push(makeDiagnosticValidationError({
+            message: formatParseError(example.name, version),
+            example: { name: example.name, path: example.path },
+            version,
+            errors: [{ message: parseResult.left.message }],
+        }));
+        return;
     }
-    catch (parseError) {
-        // Parse errors are also validation errors
+    // Validate the parsed document against the schema
+    const errors = validate(schema.definition, parseResult.right, specifiedRules);
+    if (Array.isNonEmptyReadonlyArray(errors)) {
         diagnostics.push(makeDiagnosticValidationError({
-            message: `Example "${exampleName}" (${version}) has invalid GraphQL syntax`,
-            example: { name: exampleName, path: examplePath },
+            message: formatValidationMessage(example.name, version, errors),
+            example: { name: example.name, path: example.path },
             version,
-            errors: [{ message: String(parseError) }],
+            errors: errors.map(formatGraphQLError),
         }));
     }
 };
+/**
+ * Format a parse error message for an example.
+ */
+const formatParseError = (exampleId, version) => {
+    const versionStr = version ? ` (${Version.encodeSync(version)})` : '';
+    return `Example "${exampleId}"${versionStr} has invalid GraphQL syntax`;
+};
 /**
  * Format a validation message for an example.
  */
 const formatValidationMessage = (exampleId, version, errors) => {
-    const versionStr = version === 'default' ? '' : ` (${version})`;
+    const versionStr = version ? ` (${Version.encodeSync(version)})` : '';
     const errorCount = errors.length;
     const errorWord = errorCount === 1 ? 'error' : 'errors';
-    // Include the first error message for context
-    const firstError = errors[0];
-    const preview = firstError ? `: ${firstError.message}` : '';
+    // Include the first error message for context - always safe with NonEmptyArray
+    const firstError = Array.headNonEmpty(errors);
+    const preview = `: ${firstError.message}`;
     return `Example "${exampleId}"${versionStr} has ${errorCount} validation ${errorWord}${preview}`;
 };
 /**
  * Format a GraphQL error for diagnostic reporting.
  */
-const formatGraphQLError = (error) => ({
+const formatGraphQLError = (error) => GraphQLErrorData.make({
     message: error.message,
-    ...(error.locations
-        ? {
-            locations: error.locations.map(loc => ({
-                line: loc.line,
-                column: loc.column,
-            })),
-        }
-        : {}),
+    ...(error.locations && {
+        locations: error.locations.map(loc => ({
+            line: loc.line,
+            column: loc.column,
+        })),
+    }),
 });
 //# sourceMappingURL=validator.js.map

package/build/api/examples/diagnostic/validator.js.map

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

package/build/api/examples/filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/api/examples/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,OAAO,CAAC,OAAO,EAAE,EAC3B,WAAW,gBAAgB,GAAG,SAAS,KACtC,OAAO,CAAC,OAAO,EA6BjB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,aAAa,WAAW,EACxB,WAAW,gBAAgB,GAAG,SAAS,KACtC,OA2BF,CAAA"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/api/examples/filter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,OAAO,CAAC,OAAO,EAAE,EAC3B,WAAW,gBAAgB,GAAG,SAAS,KACtC,OAAO,CAAC,OAAO,EA6BjB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,aAAa,WAAW,EACxB,WAAW,gBAAgB,GAAG,SAAS,KACtC,OA6BF,CAAA"}

package/build/api/examples/filter.js

@@ -1,3 +1,4 @@
+import { HashSet } from 'effect';
 import { Example } from './schemas/example/$.js';
 /**
  * Filter examples based on the display configuration.
@@ -20,13 +21,13 @@ export const filterExamplesBySelection = (examples, selection) => {
     }
     // Handle include pattern
     if ('include' in selection) {
-        const includeSet = new Set(selection.include);
-        return examples.filter(example => includeSet.has(example.name));
+        const includeSet = HashSet.fromIterable(selection.include);
+        return examples.filter(example => HashSet.has(includeSet, example.name));
     }
     // Handle exclude pattern
     if ('exclude' in selection) {
-        const excludeSet = new Set(selection.exclude);
-        return examples.filter(example => !excludeSet.has(example.name));
+        const excludeSet = HashSet.fromIterable(selection.exclude);
+        return examples.filter(example => !HashSet.has(excludeSet, example.name));
     }
     // Fallback to all examples if selection pattern is not recognized
     return examples;
@@ -52,11 +53,13 @@ export const shouldDisplayExample = (exampleName, selection) => {
     }
     // Handle include pattern
     if ('include' in selection) {
-        return selection.include.includes(exampleName);
+        const includeSet = HashSet.fromIterable(selection.include);
+        return HashSet.has(includeSet, exampleName);
     }
     // Handle exclude pattern
     if ('exclude' in selection) {
-        return !selection.exclude.includes(exampleName);
+        const excludeSet = HashSet.fromIterable(selection.exclude);
+        return !HashSet.has(excludeSet, exampleName);
     }
     // Fallback to show if selection pattern is not recognized
     return true;

package/build/api/examples/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/api/examples/filter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAA2B,EAC3B,SAAuC,EACpB,EAAE;IACrB,yCAAyC;IACzC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAc,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,IAAmB,CAAC,CAAC,CAAA;IAChF,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAc,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,IAAmB,CAAC,CAAC,CAAA;IACjF,CAAC;IAED,kEAAkE;IAClE,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,WAAwB,EACxB,SAAuC,EAC9B,EAAE;IACX,0CAA0C;IAC1C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IAChD,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IACjD,CAAC;IAED,0DAA0D;IAC1D,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/api/examples/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAEhC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAA2B,EAC3B,SAAuC,EACpB,EAAE;IACrB,yCAAyC;IACzC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,IAAmB,CAAC,CAAC,CAAA;IACzF,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,IAAmB,CAAC,CAAC,CAAA;IAC1F,CAAC;IAED,kEAAkE;IAClE,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,WAAwB,EACxB,SAAuC,EAC9B,EAAE;IACX,0CAA0C;IAC1C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAA;IAC7C,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAA;IAC9C,CAAC;IAED,0DAA0D;IAC1D,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}

package/build/api/examples/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../../src/api/examples/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAKzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,MAAM,EAA2B,MAAM,QAAQ,CAAA;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAQ5D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAO9C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC,OAAO,CAAA;CACtC;AAyHD,eAAO,MAAM,IAAI,GACf,SAAS,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,KAC1C,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CA6LrD,CAAA"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../../src/api/examples/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAKzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAS,MAAM,EAA2B,MAAM,QAAQ,CAAA;AAE/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAO5D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAO9C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC,OAAO,CAAA;CACtC;AA2MD,eAAO,MAAM,IAAI,GACf,SAAS,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,KAC1C,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CA+HrD,CAAA"}

package/build/api/examples/scanner.js

@@ -1,13 +1,13 @@
 import { Catalog as SchemaCatalog } from '#lib/catalog/$';
 import { Document } from '#lib/document/$';
 import { EffectGlob } from '#lib/effect-glob/$';
-import { VersionCoverage } from '#lib/version-selection/$';
+import { VersionCoverage } from '#lib/version-coverage';
 import { Version } from '#lib/version/$';
 import { FileSystem } from '@effect/platform';
 import { Str } from '@wollybeard/kit';
-import { Effect, HashMap, HashSet, Match } from 'effect';
+import { Array, Effect, HashMap, HashSet, Match } from 'effect';
 import * as Path from 'node:path';
-import { makeDiagnosticDuplicateContent, makeDiagnosticMissingVersions, makeDiagnosticUnknownVersion, makeDiagnosticUnusedDefault, } from './diagnostic/diagnostic.js';
+import { makeDiagnosticDuplicateContent, makeDiagnosticMissingVersions, makeDiagnosticUnknownVersion, } from './diagnostic/diagnostic.js';
 import { validateExamples } from './diagnostic/validator.js';
 import { Catalog } from './schemas/catalog.js';
 import { Example } from './schemas/example/$.js';
@@ -20,7 +20,7 @@ const VERSIONED_FILE_PATTERN = Str.pattern(/^(?<name>.+?)\.(?<version>.+)$/);
 // ============================================================================
 // Helpers
 // ============================================================================
-const parseExampleFilename = (filename) => {
+const parseExampleFile = (filename) => {
     const parsed = Path.parse(filename);
     const base = parsed.name;
     // Try to match versioned pattern: <name>.<version>
@@ -29,26 +29,70 @@ const parseExampleFilename = (filename) => {
         const { name, version: versionStr } = match.groups;
         // Handle special 'default' keyword
         if (versionStr === 'default') {
-            return { name, version: 'default' };
+            return { type: 'default', name, file: filename };
         }
-        const decoded = Version.decodeSync(versionStr);
-        // Return canonical version string
-        return { name, version: Version.encodeSync(decoded) };
+        const version = Version.decodeSync(versionStr);
+        return { type: 'versioned', name, version, file: filename };
     }
     // No version found - this is an unversioned example
-    return { name: base, version: null };
+    return { type: 'unversioned', name: base, file: filename };
 };
 const groupExampleFiles = (files) => {
     const grouped = new Map();
     for (const file of files) {
-        const { name, version } = parseExampleFilename(file);
-        if (!grouped.has(name)) {
-            grouped.set(name, new Map());
+        const parsed = parseExampleFile(file);
+        if (!grouped.has(parsed.name)) {
+            grouped.set(parsed.name, {
+                versioned: new Map(),
+            });
+        }
+        const group = grouped.get(parsed.name);
+        switch (parsed.type) {
+            case 'unversioned':
+                group.unversioned = parsed.file;
+                break;
+            case 'versioned':
+                group.versioned.set(parsed.version, parsed.file);
+                break;
+            case 'default':
+                group.default = parsed.file;
+                break;
         }
-        grouped.get(name).set(version, file);
     }
     return grouped;
 };
+/**
+ * Resolve .default files into proper version coverage.
+ * This erases the .default convention and converts it to semantic version sets.
+ */
+const resolveDefaultFiles = (grouped, schemaVersions) => {
+    const resolved = new Map();
+    for (const [name, group] of grouped) {
+        let versionDocuments = HashMap.empty();
+        // Add explicit versions
+        for (const [version, file] of group.versioned) {
+            versionDocuments = HashMap.set(versionDocuments, version, file);
+        }
+        // Handle default file if present
+        if (group.default) {
+            // Determine which versions the default covers
+            const explicitVersions = HashSet.fromIterable(group.versioned.keys());
+            const defaultVersions = schemaVersions.filter(v => !HashSet.has(explicitVersions, v));
+            if (defaultVersions.length > 0) {
+                // Create version coverage for default
+                const defaultCoverage = defaultVersions.length === 1
+                    ? defaultVersions[0] // Single version
+                    : HashSet.fromIterable(defaultVersions); // Version set
+                versionDocuments = HashMap.set(versionDocuments, defaultCoverage, group.default);
+            }
+        }
+        resolved.set(name, {
+            versionDocuments,
+            ...(group.unversioned ? { unversioned: group.unversioned } : {}),
+        });
+    }
+    return resolved;
+};
 const lintFileLayout = (example, schemaCatalog) => {
     // Extract schema versions from catalog if provided
     const schemaVersions = schemaCatalog
@@ -59,7 +103,7 @@ const lintFileLayout = (example, schemaCatalog) => {
         DocumentVersioned: (doc) => {
             // Get all versions covered by this document
             const coveredVersions = Document.Versioned.getAllVersions(doc);
-            const missingVersions = schemaVersions.filter(sv => !coveredVersions.some(cv => Version.equivalence(sv, cv)));
+            const missingVersions = Array.filter(schemaVersions, sv => !Array.some(coveredVersions, cv => Version.equivalence(sv, cv)));
             if (missingVersions.length > 0) {
                 diagnostics.push(makeDiagnosticMissingVersions({
                     message: `Versioned example must provide documents for all schema versions`,
@@ -69,7 +113,7 @@ const lintFileLayout = (example, schemaCatalog) => {
                 }));
             }
             // Check for duplicate content between selections
-            const entries = Array.from(HashMap.entries(doc.versionDocuments));
+            const entries = [...HashMap.entries(doc.versionDocuments)];
             const duplicates = [];
             for (let i = 0; i < entries.length; i++) {
                 for (let j = i + 1; j < entries.length; j++) {
@@ -105,27 +149,32 @@ export const scan = (options) => Effect.gen(function* () {
     const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
     const pattern = `**/*.{${extensions.join(',')}}`;
     const files = options.files ?? (yield* EffectGlob.glob(pattern, { cwd: options.dir }));
+    // Get schema versions upfront for default file resolution
+    const schemaVersions = options.schemaCatalog
+        ? SchemaCatalog.fold((versioned) => SchemaCatalog.Versioned.getVersions(versioned), () => [])(options.schemaCatalog)
+        : [];
     // Group files by example
     const groupedFiles = groupExampleFiles(files);
+    // Resolve .default files into proper version coverage immediately
+    const resolvedFiles = resolveDefaultFiles(groupedFiles, schemaVersions);
     // Process each example group
     const examples = [];
     const diagnostics = [];
-    for (const [name, versions] of groupedFiles) {
-        // Check if this is a versioned or unversioned example
-        const hasMultipleVersions = versions.size > 1;
-        const hasUnversionedFile = versions.has(null);
-        const hasDefaultFile = versions.has('default');
-        const hasOnlyDefaultFile = hasDefaultFile && versions.size === 1;
+    for (const [name, resolved] of resolvedFiles) {
         // Determine the base path for this example
-        const firstFilePath = Array.from(versions.values())[0];
-        const basePath = versions.size === 1
-            ? firstFilePath
-            : Path.dirname(firstFilePath);
+        const firstFile = resolved.unversioned
+            || (HashMap.size(resolved.versionDocuments) > 0
+                ? HashMap.values(resolved.versionDocuments).next().value
+                : undefined);
+        if (!firstFile)
+            continue; // No files for this example
+        const basePath = HashMap.size(resolved.versionDocuments) > 1 || resolved.unversioned
+            ? Path.dirname(firstFile)
+            : firstFile;
         let example;
-        if (hasUnversionedFile && versions.size === 1) {
+        if (resolved.unversioned) {
             // Unversioned example - single file with no version
-            const filePath = versions.get(null);
-            const fullPath = Path.join(options.dir, filePath);
+            const fullPath = Path.join(options.dir, resolved.unversioned);
             const document = yield* fs.readFileString(fullPath);
             example = Example.make({
                 name,
@@ -135,90 +184,31 @@ export const scan = (options) => Effect.gen(function* () {
                 }),
             });
         }
-        else if (hasOnlyDefaultFile) {
-            // Only default file - create versioned document with all schema versions as a set
-            const filePath = versions.get('default');
-            const fullPath = Path.join(options.dir, filePath);
-            const documentContent = yield* fs.readFileString(fullPath);
-            // Get all schema versions to map to this default document
-            const schemaVersions = options.schemaCatalog
-                ? SchemaCatalog.fold((versioned) => SchemaCatalog.Versioned.getVersions(versioned), () => [])(options.schemaCatalog)
-                : [];
-            if (schemaVersions.length > 0) {
-                // Create a version set for all schema versions
-                const versionSet = HashSet.fromIterable(schemaVersions);
-                let versionDocuments = HashMap.empty();
-                versionDocuments = HashMap.set(versionDocuments, versionSet, documentContent);
-                example = Example.make({
-                    name,
-                    path: basePath,
-                    document: Document.Versioned.make({
-                        versionDocuments,
-                    }),
-                });
-            }
-            else {
-                // No schema versions, treat as unversioned
-                example = Example.make({
-                    name,
-                    path: basePath,
-                    document: Document.Unversioned.make({
-                        document: documentContent,
-                    }),
-                });
-            }
-        }
-        else {
-            // Versioned example - multiple files or versioned files
+        else if (HashMap.size(resolved.versionDocuments) > 0) {
+            // Versioned example - read all version documents
             let versionDocuments = HashMap.empty();
-            let defaultDocument;
-            let explicitVersions = HashSet.empty(); // Track which versions have explicit files
             const unknownVersions = [];
-            // Get available schema versions if catalog is provided
-            const schemaVersions = options.schemaCatalog
-                ? SchemaCatalog.fold((versioned) => SchemaCatalog.Versioned.getVersions(versioned), () => [])(options.schemaCatalog)
-                : [];
-            // Create HashSet for O(1) lookups
             const schemaVersionsSet = HashSet.fromIterable(schemaVersions);
-            // Read content for each version
-            for (const [version, filePath] of versions) {
-                const fullPath = Path.join(options.dir, filePath);
-                const fileContent = yield* fs.readFileString(fullPath);
-                if (version === 'default') {
-                    defaultDocument = fileContent;
-                }
-                else if (version !== null) {
-                    // Parse the version string
-                    const parsedVersion = Version.decodeSync(version);
-                    // Check if this version exists in the schema
-                    const versionExists = HashSet.has(schemaVersionsSet, parsedVersion);
+            for (const [versionCoverage, filePath] of HashMap.entries(resolved.versionDocuments)) {
+                // Check if version is known (only for single versions, not sets)
+                if (Version.is(versionCoverage)) {
+                    const versionExists = HashSet.has(schemaVersionsSet, versionCoverage);
                     if (options.schemaCatalog && schemaVersions.length > 0 && !versionExists) {
-                        unknownVersions.push(parsedVersion);
+                        unknownVersions.push(versionCoverage);
                         // Create diagnostic for unknown version
                         diagnostics.push(makeDiagnosticUnknownVersion({
-                            message: `Example "${name}" specifies version "${version}" which does not exist in the schema`,
+                            message: `Example "${name}" specifies version "${Version.encodeSync(versionCoverage)}" which does not exist in the schema`,
                             example: { name, path: basePath },
-                            version: parsedVersion,
+                            version: versionCoverage,
                             availableVersions: schemaVersions,
                         }));
                         // Skip this version - don't include it in the example
                         continue;
                     }
-                    // We already have parsedVersion from above
-                    versionDocuments = HashMap.set(versionDocuments, parsedVersion, fileContent);
-                    explicitVersions = HashSet.add(explicitVersions, parsedVersion);
-                }
-            }
-            if (defaultDocument) {
-                // If we have a default, determine which versions it applies to
-                const defaultVersions = schemaVersions.filter(v => !HashSet.has(explicitVersions, v));
-                if (defaultVersions.length > 0) {
-                    // Create a version set for the default document
-                    const defaultVersionSet = defaultVersions.length === 1
-                        ? defaultVersions[0] // Single version
-                        : HashSet.fromIterable(defaultVersions); // Version set
-                    versionDocuments = HashMap.set(versionDocuments, defaultVersionSet, defaultDocument);
                 }
+                const fullPath = Path.join(options.dir, filePath);
+                const fileContent = yield* fs.readFileString(fullPath);
+                versionDocuments = HashMap.set(versionDocuments, versionCoverage, fileContent);
             }
             if (HashMap.size(versionDocuments) > 0) {
                 // Create versioned document
@@ -234,10 +224,6 @@ export const scan = (options) => Effect.gen(function* () {
                 // All versions were unknown, skip this example entirely
                 continue;
             }
-            else {
-                // No versions at all - shouldn't happen
-                continue;
-            }
         }
         if (example) {
             examples.push(example);