@amritk/generate-examples 0.5.2 → 0.5.4

package/AI.md

@@ -0,0 +1,37 @@
+# @amritk/generate-examples — notes for AI coding agents
+
+Programmatic API: turn a JSON Schema into test data — a fast-check arbitrary
+(`FooArbitrary`) and a concrete example value (`fooExample`) per node, plus
+types. Full reference is [README.md](./README.md).
+
+> Pre-alpha: APIs and generated output change pre-1.0.
+
+## Minimal example
+
+```ts
+import { buildExampleSchema } from '@amritk/generate-examples'
+
+const schema = {
+  type: 'object',
+  properties: { id: { type: 'string', format: 'uuid' }, age: { type: 'integer', minimum: 0 } },
+  required: ['id'],
+} as const
+
+const files = await buildExampleSchema(schema, 'User') // → user.ts, index.ts
+```
+
+## Gotchas — where agents fail
+
+1. **Generated arbitrary files `import * as fc from 'fast-check'`** — `fast-check`
+   (`>=3`) is an **optional peer dependency** consumers must install. The static
+   `fooExample` values have no runtime deps.
+2. **`generateArbitrary` / `generateExampleConst` return source-code STRINGS**;
+   **`deriveExample` returns an actual runtime VALUE.** Easy to confuse.
+3. **A static example constrained only by `pattern` may not match the pattern** —
+   use the arbitrary when pattern fidelity matters.
+4. **Unsupported keywords degrade silently:** `fc.anything()` in arbitraries,
+   `null` in static examples — no error thrown.
+
+Exports: `buildExampleSchema`, `generateArbitrary`, `generateExampleConst`,
+`deriveExample`, `serializeValue`, `GeneratedFile`. Only the `.` entry.
+Install: `bun add @amritk/generate-examples`.

package/dist/generators/build-schema.js

@@ -1,52 +1,25 @@
-import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel';
-import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
-import { findSchemaCycles } from './find-schema-cycles.js';
-import { generateExampleFile } from './generate-files.js';
-/**
- * Builds all TypeScript example files from a JSON Schema by traversing all
- * `$ref` / `$dynamicRef` references recursively (via the shared
- * `@amritk/helpers/walk-ref-graph` walker).
- *
- * Each generated file exports:
- * - A TypeScript type definition
- * - A `fast-check` arbitrary (`FooArbitrary`) that produces schema-valid values
- * - A concrete example value (`fooExample`)
- *
- * An `index.ts` re-exports everything. The generated output imports `fast-check`,
- * which consumers must install as a (dev) dependency.
- *
- * @param rootSchema - The root JSON Schema to build from
- * @param rootTypeName - The name for the root type (e.g. "Document")
- * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`)
- * @returns An array of generated TypeScript files
- *
- * @example
- * ```typescript
- * const files = await buildExampleSchema(schema, 'Document')
- * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'index.ts', ... }]
- * ```
- */
-export const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = '') => {
-    const files = [];
-    // Cross-file `$ref` cycles (A→B→A across modules) must emit lazy references
-    // for their cycle edges; eager top-level references would crash with a
-    // circular-ESM TDZ error at import. Detect the cycles up front so each file
-    // knows which siblings to defer.
-    const cycles = findSchemaCycles(rootSchema, rootTypeName, typeSuffix);
-    walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
-        // `index` is reserved for the barrel below, so never let a definition of
-        // that name overwrite it.
-        if (node.filename === 'index')
-            return;
-        const lazyRefFilenames = cycles.get(node.filename);
-        const content = generateExampleFile(node.schema, node.typeName, {
-            rootSchema: node.rootSchema,
-            typeSuffix,
-            ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
-            ...(lazyRefFilenames !== undefined ? { lazyRefFilenames } : {}),
-        });
-        files.push({ filename: `${node.filename}.ts`, content });
+import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
+import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
+import { findSchemaCycles } from "./find-schema-cycles.js";
+import { generateExampleFile } from "./generate-files.js";
+const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = "") => {
+  const files = [];
+  const cycles = findSchemaCycles(rootSchema, rootTypeName, typeSuffix);
+  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+    if (node.filename === "index")
+      return;
+    const lazyRefFilenames = cycles.get(node.filename);
+    const content = generateExampleFile(node.schema, node.typeName, {
+      rootSchema: node.rootSchema,
+      typeSuffix,
+      ...node.ref !== void 0 ? { selfRef: node.ref } : {},
+      ...lazyRefFilenames !== void 0 ? { lazyRefFilenames } : {}
     });
-    files.push({ filename: 'index.ts', content: generateIndexBarrel(files) });
-    return files;
+    files.push({ filename: `${node.filename}.ts`, content });
+  });
+  files.push({ filename: "index.ts", content: generateIndexBarrel(files) });
+  return files;
+};
+export {
+  buildExampleSchema
 };

package/dist/generators/collect-example-imports.js

@@ -1,100 +1,70 @@
-import { refToFilename } from '@amritk/helpers/ref-to-filename';
-import { refToName } from '@amritk/helpers/ref-to-name';
-import { resolveRef } from '@amritk/helpers/resolve-ref';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject, } from '@amritk/helpers/schema-guards';
-/**
- * Generates an import statement for a single $ref, importing both the generated
- * type and its arbitrary from the ref's generated file.
- */
+import { refToFilename } from "@amritk/helpers/ref-to-filename";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { resolveRef } from "@amritk/helpers/resolve-ref";
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject } from "@amritk/helpers/schema-guards";
 const buildImport = (ref, suffix) => {
-    const filename = refToFilename(ref);
-    const typeName = refToName(ref, suffix);
-    // `.js` extension so the emitted import resolves under Node ESM, not only Bun.
-    return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
+  const filename = refToFilename(ref);
+  const typeName = refToName(ref, suffix);
+  return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
 };
-/**
- * Recursively collects every `$ref` string reachable through the schema surface
- * that the type and arbitrary generators traverse. A generated file's single
- * import block must cover every ref those generators emit, so this walks the
- * *same* nested surface `arbitraryExpr` (generate-arbitrary.ts) descends into —
- * combinator branches, object `properties`/`patternProperties`/
- * `additionalProperties`, and array `items`/`prefixItems` (both the single-schema
- * and tuple array forms) — not just the top level. Missing any of these emits a
- * bare `XxxArbitrary` identifier (or a bare `Xxx` type) with no matching import,
- * producing TypeScript that fails to compile.
- *
- * `$ref` nodes short-circuit (matching `arbitraryExpr`, which resolves a `$ref`
- * and ignores sibling keywords), so recursion is bounded by the schema's own
- * structural nesting and cannot loop on a self-referential ref.
- */
 const collectRefs = (schema) => {
-    if (!isSchemaObject(schema))
-        return [];
-    if (hasRef(schema))
-        return [schema.$ref];
-    const refs = [];
-    const visit = (sub) => {
-        refs.push(...collectRefs(sub));
-    };
-    if (hasOneOf(schema))
-        schema.oneOf.forEach(visit);
-    if (hasAnyOf(schema))
-        schema.anyOf.forEach(visit);
-    if (hasAllOf(schema))
-        schema.allOf.forEach(visit);
-    if (hasProperties(schema))
-        Object.values(schema.properties).forEach(visit);
-    const raw = schema;
-    const patternProperties = raw['patternProperties'];
-    if (typeof patternProperties === 'object' && patternProperties !== null) {
-        Object.values(patternProperties).forEach(visit);
-    }
-    if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
-        visit(schema.additionalProperties);
-    }
-    const prefixItems = raw['prefixItems'];
-    if (Array.isArray(prefixItems))
-        prefixItems.forEach(visit);
-    const items = raw['items'];
-    // `items` is either a tuple (draft-07 array form) or a single item schema.
-    if (Array.isArray(items))
-        items.forEach(visit);
-    else if (isSchemaObject(items))
-        visit(items);
-    return refs;
+  if (!isSchemaObject(schema))
+    return [];
+  if (hasRef(schema))
+    return [schema.$ref];
+  const refs = [];
+  const visit = (sub) => {
+    refs.push(...collectRefs(sub));
+  };
+  if (hasOneOf(schema))
+    schema.oneOf.forEach(visit);
+  if (hasAnyOf(schema))
+    schema.anyOf.forEach(visit);
+  if (hasAllOf(schema))
+    schema.allOf.forEach(visit);
+  if (hasProperties(schema))
+    Object.values(schema.properties).forEach(visit);
+  const raw = schema;
+  const patternProperties = raw["patternProperties"];
+  if (typeof patternProperties === "object" && patternProperties !== null) {
+    Object.values(patternProperties).forEach(visit);
+  }
+  if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
+    visit(schema.additionalProperties);
+  }
+  const prefixItems = raw["prefixItems"];
+  if (Array.isArray(prefixItems))
+    prefixItems.forEach(visit);
+  const items = raw["items"];
+  if (Array.isArray(items))
+    items.forEach(visit);
+  else if (isSchemaObject(items))
+    visit(items);
+  return refs;
 };
-/**
- * Collects import statements for all $ref dependencies of a schema. Each import
- * brings in both the generated TypeScript type and the arbitrary for that ref.
- *
- * @example
- * ```typescript
- * const schema = { properties: { address: { $ref: '#/$defs/address' } } }
- * collectExampleImports(schema)
- * // ["import { type Address, AddressArbitrary } from './address'"]
- * ```
- */
-export const collectExampleImports = (schema, options) => {
-    const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
-    const rootSchema = options?.rootSchema;
-    const typeSuffix = options?.typeSuffix ?? '';
-    const refs = collectRefs(schema);
-    const seen = new Set();
-    const imports = [];
-    for (const ref of refs) {
-        const filename = refToFilename(ref);
-        if (seen.has(filename))
-            continue;
-        if (selfFilename && filename === selfFilename)
-            continue;
-        // Skip refs that don't resolve in this schema (external / never generated)
-        if (rootSchema) {
-            const resolved = resolveRef(ref, rootSchema);
-            if (!resolved)
-                continue;
-        }
-        seen.add(filename);
-        imports.push(buildImport(ref, typeSuffix));
+const collectExampleImports = (schema, options) => {
+  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
+  const rootSchema = options?.rootSchema;
+  const typeSuffix = options?.typeSuffix ?? "";
+  const refs = collectRefs(schema);
+  const seen = /* @__PURE__ */ new Set();
+  const imports = [];
+  for (const ref of refs) {
+    const filename = refToFilename(ref);
+    if (seen.has(filename))
+      continue;
+    if (selfFilename && filename === selfFilename)
+      continue;
+    if (rootSchema) {
+      const resolved = resolveRef(ref, rootSchema);
+      if (!resolved)
+        continue;
     }
-    return imports;
+    seen.add(filename);
+    imports.push(buildImport(ref, typeSuffix));
+  }
+  return imports;
+};
+export {
+  collectExampleImports
 };