@amritk/mjst 0.2.1 → 0.3.0

package/README.md

@@ -69,7 +69,8 @@ npx mjst --config ./mjst.config.json
 | 🔨 | `build` | `--build` | `boolean` | — | `false` | Compile the generated TypeScript files to .js and .d.ts output. A temporary tsconfig is written to the output directory, tsc is invoked, and the intermediate .ts source files are removed when compilation succeeds. |
 | ⚠️ | `logWarnings` | `--log-warnings` | `boolean` | — | `false` | Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime. |
 | 🚫 | `strict` | `--strict` | `boolean` | — | `false` | Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. Unknown extra keys are still allowed. |
-| ⚙️ | `config` | `--config <path>` | `string` | — | — | Path to a JSON config file. Keys match the option names in this schema (schema, outDir, typesOnly, build, logWarnings, strict). CLI flags take precedence over config file values. |
+| 🧰 | `helpers` | `--helpers <mode>` | `string` | — | — | Controls how generated parsers reference their runtime helpers. 'package' emits imports from @amritk/helpers (requires it to be installed in the consumer project). 'embedded' ships the helper source under outDir/_helpers/ so the output is self-contained. When omitted, the CLI auto-detects: it picks 'package' if @amritk/helpers resolves from outDir, otherwise 'embedded'. |
+| ⚙️ | `config` | `--config <path>` | `string` | — | — | Path to a JSON config file. Keys match the option names in this schema (schema, outDir, typesOnly, build, logWarnings, strict, helpers). CLI flags take precedence over config file values. |
 <!-- config-table-end -->
 
 ---

package/dist/cli-config.d.ts

@@ -28,4 +28,14 @@ export type CliConfig = {
      * instead of coercing invalid input to default values.
      */
     readonly strict?: boolean;
+    /**
+     * Controls how generated parsers reference their runtime helpers.
+     * - `'package'`: emit `import ... from '@amritk/helpers/...'`.
+     * - `'embedded'`: ship the helper source under `outDir/_helpers/` and emit
+     *   relative imports so the output directory is self-contained.
+     *
+     * When omitted, the CLI auto-detects: it picks `'package'` if `@amritk/helpers`
+     * resolves from outDir, otherwise falls back to `'embedded'`.
+     */
+    readonly helpers?: 'package' | 'embedded';
 };

package/dist/cli.js

@@ -2,12 +2,14 @@
 
 // src/cli.ts
 import { execFile } from "node:child_process";
-import { mkdir, readFile as readFile2, unlink, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { mkdir, readFile as readFile3, unlink, writeFile } from "node:fs/promises";
+import { dirname as dirname2, join, resolve as resolve3 } from "node:path";
 import { promisify } from "node:util";
 
 // ../generate-parsers/dist/index.js
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolvePath } from "node:path";
 var isSchemaObject = (schema) => {
   return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
 };
@@ -783,21 +785,43 @@ var generateTypeDefinition = (schema, typeName) => {
   }
   return "export type " + typeName + " = unknown;";
 };
-var collectHelpers = (parserFunction) => {
+var PACKAGE_IMPORTS = {
+  "is-object": "import { isObject } from '@amritk/helpers/is-object';",
+  "validate-array": "import { validateArray } from '@amritk/helpers/validate-array';",
+  "validate-record": "import { validateRecord } from '@amritk/helpers/validate-record';",
+  "has-ref": "import { hasRef } from '@amritk/helpers/schema-guards';"
+};
+var EMBEDDED_IMPORTS = {
+  "is-object": "import { isObject } from './_helpers/is-object';",
+  "validate-array": "import { validateArray } from './_helpers/validate-array';",
+  "validate-record": "import { validateRecord } from './_helpers/validate-record';",
+  "has-ref": "import { hasRef } from './_helpers/has-ref';"
+};
+var collectHelpers = (parserFunction, mode) => {
   const imports = [];
+  const used = new Set;
+  const table = mode === "embedded" ? EMBEDDED_IMPORTS : PACKAGE_IMPORTS;
   if (parserFunction.includes("validateArray")) {
-    imports.push("import { validateArray } from '@amritk/helpers/validate-array';");
+    imports.push(table["validate-array"]);
+    used.add("validate-array");
   }
   if (parserFunction.includes("validateRecord")) {
-    imports.push("import { validateRecord } from '@amritk/helpers/validate-record';");
+    imports.push(table["validate-record"]);
+    used.add("validate-record");
+    used.add("is-object");
   }
   if (parserFunction.includes("isObject")) {
-    imports.push("import { isObject } from '@amritk/helpers/is-object';");
+    imports.push(table["is-object"]);
+    used.add("is-object");
   }
   if (parserFunction.includes("hasRef(")) {
-    imports.push("import { hasRef } from '@amritk/helpers/schema-guards';");
+    imports.push(table["has-ref"]);
+    used.add("has-ref");
   }
-  return imports;
+  return { imports, used };
+};
+var hasRef = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "$ref" in value && typeof value.$ref === "string";
 };
 var isSchemaObject3 = (schema) => {
   return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
@@ -880,9 +904,6 @@ var hasMinProperties = (schema) => {
 var hasMaxProperties = (schema) => {
   return isSchemaObject3(schema) && "maxProperties" in schema && typeof schema.maxProperties === "number";
 };
-var hasRef = (schema) => {
-  return isSchemaObject3(schema) && "$ref" in schema && typeof schema.$ref === "string";
-};
 var getImportPathForFilename = (filename) => `./${filename}`;
 var collectImports = (schema, options) => {
   const typesOnly = options?.typesOnly === true;
@@ -2379,6 +2400,7 @@ var generateFile = (schema, typeName, options) => {
   const typesOnly = options?.typesOnly === true;
   const selfRef = options?.selfRef;
   const rootSchema = options?.rootSchema;
+  const helpersMode = options?.helpersMode ?? "package";
   const typeDefinition = generateTypeDefinition(schema, typeName);
   if (typesOnly) {
     const imports2 = collectImports(schema, { typesOnly: true, selfRef, rootSchema });
@@ -2393,7 +2415,7 @@ var generateFile = (schema, typeName, options) => {
 
 `;
     }
-    return result2 + typeDefinition;
+    return { content: result2 + typeDefinition, usedHelpers: new Set };
   }
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
@@ -2404,7 +2426,8 @@ var generateFile = (schema, typeName, options) => {
   const combinedFunctions = `${shapeValidator}
 
 ${parserFunction}`;
-  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...collectHelpers(combinedFunctions)];
+  const helpers = collectHelpers(combinedFunctions, helpersMode);
+  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...helpers.imports];
   let result = "";
   if (imports.length > 0) {
     result += imports[0];
@@ -2416,9 +2439,15 @@ ${parserFunction}`;
 
 `;
   }
-  return result + typeDefinition + `
+  return { content: result + typeDefinition + `
 
-` + combinedFunctions;
+` + combinedFunctions, usedHelpers: helpers.used };
+};
+var readHelperSource = async (helper) => {
+  const require2 = createRequire(import.meta.url);
+  const helpersPkgPath = require2.resolve("@amritk/helpers/package.json");
+  const helpersRoot = dirname(helpersPkgPath);
+  return readFile(resolvePath(helpersRoot, "src", `${helper}.ts`), "utf-8");
 };
 var extractDynamicAnchorDefs = (schema) => {
   const refs = [];
@@ -2439,18 +2468,20 @@ var extractDynamicAnchorDefs = (schema) => {
   }
   return refs;
 };
-var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict) => {
+var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package") => {
   rootSchema = upgradeDraft07Schema(rootSchema);
   const files = [];
   const processedRefs = new Set;
   const processedFilenames = new Set;
   const refsToProcess = [];
+  const usedHelpers = new Set;
   const dynamicRefMap = buildDynamicRefMap(rootSchema);
   const processedRootSchema = resolveDynamicRefs(rootSchema, dynamicRefMap);
   const extendedRootSchema = extensions ? applySchemaExtensions(processedRootSchema, rootTypeName.toLowerCase(), extensions) : processedRootSchema;
-  const rootContent = generateFile(extendedRootSchema, rootTypeName, {
+  const rootResult = generateFile(extendedRootSchema, rootTypeName, {
     typesOnly: typesOnly ?? false,
     rootSchema,
+    helpersMode,
     ...logWarnings !== undefined ? { logWarnings } : {},
     ...strict !== undefined ? { strict } : {}
   });
@@ -2458,8 +2489,10 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
   processedFilenames.add(rootFilename);
   files.push({
     filename: `${rootFilename}.ts`,
-    content: rootContent
+    content: rootResult.content
   });
+  for (const helper of rootResult.usedHelpers)
+    usedHelpers.add(helper);
   const rootRefs = extractRefs(rootSchema);
   refsToProcess.push(...rootRefs);
   const dynamicAnchorRefs = extractDynamicAnchorDefs(rootSchema);
@@ -2479,10 +2512,11 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
     const filename = refToFilename(ref);
     const processedSchema = resolveDynamicRefs(resolvedSchema, dynamicRefMap);
     const extendedSchema = extensions ? applySchemaExtensions(processedSchema, filename, extensions) : processedSchema;
-    const content = generateFile(extendedSchema, typeName, {
+    const fileResult = generateFile(extendedSchema, typeName, {
       typesOnly: typesOnly ?? false,
       selfRef: ref,
       rootSchema,
+      helpersMode,
       ...logWarnings !== undefined ? { logWarnings } : {},
       ...strict !== undefined ? { strict } : {}
     });
@@ -2490,9 +2524,11 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
       processedFilenames.add(filename);
       files.push({
         filename: `${filename}.ts`,
-        content
+        content: fileResult.content
       });
     }
+    for (const helper of fileResult.usedHelpers)
+      usedHelpers.add(helper);
     const nestedRefs = extractRefs(resolvedSchema);
     for (const nestedRef of nestedRefs) {
       if (!processedRefs.has(nestedRef)) {
@@ -2500,9 +2536,15 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
       }
     }
   }
+  if (helpersMode === "embedded" && !typesOnly) {
+    for (const helper of usedHelpers) {
+      const source = await readHelperSource(helper);
+      files.push({ filename: `_helpers/${helper}.ts`, content: source });
+    }
+  }
   const TYPE_EXPORT_RE = /^export type (\w+)/gm;
   const CONST_EXPORT_RE = /^export const (\w+)/gm;
-  const sortedFiles = [...files].sort((a, b) => a.filename.localeCompare(b.filename));
+  const sortedFiles = [...files].filter((f) => !f.filename.startsWith("_helpers/")).sort((a, b) => a.filename.localeCompare(b.filename));
   let indexContent = "";
   for (const file of sortedFiles) {
     const moduleName = file.filename.replace(/\.ts$/, "");
@@ -2533,12 +2575,25 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
   return files;
 };
 
-// src/load-config.ts
-import { readFile } from "node:fs/promises";
+// src/detect-helpers-mode.ts
+import { createRequire as createRequire2 } from "node:module";
 import { resolve } from "node:path";
+var detectHelpersMode = (outputDir) => {
+  const req = createRequire2(resolve(outputDir, "noop.js"));
+  try {
+    req.resolve("@amritk/helpers/is-object");
+    return "package";
+  } catch {
+    return "embedded";
+  }
+};
+
+// src/load-config.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
 var loadConfig = async (configPath) => {
-  const absolutePath = resolve(configPath);
-  const raw = await readFile(absolutePath, "utf-8");
+  const absolutePath = resolve2(configPath);
+  const raw = await readFile2(absolutePath, "utf-8");
   const parsed = JSON.parse(raw);
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error(`Config file must be a JSON object: ${configPath}`);
@@ -2557,6 +2612,11 @@ var loadConfig = async (configPath) => {
 // src/parse-cli-args.ts
 var parseCliArgs = (args) => {
   const config = {};
+  const parseHelpersValue = (value) => {
+    if (value === "package" || value === "embedded")
+      return value;
+    return;
+  };
   for (let i = 0;i < args.length; i++) {
     const arg = args[i];
     if (!arg) {
@@ -2578,6 +2638,10 @@ var parseCliArgs = (args) => {
         config.logWarnings = value !== "false";
       } else if (key === "strict") {
         config.strict = value !== "false";
+      } else if (key === "helpers") {
+        const parsed = parseHelpersValue(value);
+        if (parsed)
+          config.helpers = parsed;
       }
       continue;
     }
@@ -2601,6 +2665,15 @@ var parseCliArgs = (args) => {
       config.logWarnings = true;
     } else if (arg === "--strict") {
       config.strict = true;
+    } else if (arg === "--helpers") {
+      const value = args[i + 1];
+      if (value && !value.startsWith("--")) {
+        const parsed = parseHelpersValue(value);
+        if (parsed) {
+          config.helpers = parsed;
+          i++;
+        }
+      }
     }
   }
   return config;
@@ -2634,21 +2707,21 @@ var run = async () => {
     console.error("Error: --outDir is required. Provide an output directory for generated files.");
     process.exit(1);
   }
-  const schemaPath = resolve2(config.schema);
-  const raw = await readFile2(schemaPath, "utf-8");
+  const schemaPath = resolve3(config.schema);
+  const raw = await readFile3(schemaPath, "utf-8");
   const schema = JSON.parse(raw);
-  const files = await buildSchema(schema, "Document", undefined, config.typesOnly, config.logWarnings, config.strict);
-  const outputDir = resolve2(config.outDir);
+  const outputDir = resolve3(config.outDir);
   await mkdir(outputDir, { recursive: true });
+  const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
+  console.log(`Helpers mode: ${helpersMode}${config.helpers ? " (explicit)" : " (auto-detected)"}`);
+  const files = await buildSchema(schema, "Document", undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode);
   for (const file of files) {
     const filePath = join(outputDir, file.filename);
-    await mkdir(dirname(filePath), { recursive: true });
+    await mkdir(dirname2(filePath), { recursive: true });
     await writeFile(filePath, file.content, "utf-8");
     console.log(`Generated: ${file.filename}`);
   }
   if (config.build) {
-    const helpersDir = resolve2(dirname(fileURLToPath(import.meta.url)), "../../helpers/dist");
-    const helpersRelative = relative(outputDir, helpersDir);
     const tsconfigContent = JSON.stringify({
       compilerOptions: {
         target: "ESNext",
@@ -2656,10 +2729,7 @@ var run = async () => {
         moduleResolution: "bundler",
         declaration: true,
         emitDeclarationOnly: config.typesOnly,
-        skipLibCheck: true,
-        paths: {
-          "@amritk/helpers/*": [`${helpersRelative}/*`]
-        }
+        skipLibCheck: true
       },
       include: ["./**/*.ts"]
     }, null, 2);

package/dist/detect-helpers-mode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Detects whether `@amritk/helpers` is resolvable from the consumer's output
+ * directory using standard Node module resolution (walks up `node_modules`).
+ *
+ * Returns `'package'` when generated parsers can safely
+ * `import { ... } from '@amritk/helpers/...'` at runtime, or `'embedded'`
+ * when the helper sources need to be shipped alongside the generated files
+ * for the output to be self-contained.
+ */
+export declare const detectHelpersMode: (outputDir: string) => "package" | "embedded";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,8 @@
     "mjst": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -42,7 +43,8 @@
   },
   "dependencies": {
     "@amritk/generate-parsers": "workspace:*",
-    "@amritk/generate-markdown": "workspace:*"
+    "@amritk/generate-markdown": "workspace:*",
+    "@amritk/helpers": "workspace:*"
   },
   "devDependencies": {
     "json-schema-typed": "catalog:"

package/src/cli-config.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration for the CLI tool.
+ * These properties map 1:1 with CLI flags and config file keys.
+ */
+export type CliConfig = {
+  /** Path to the JSON Schema file to process. */
+  readonly schema: string
+  /** Output directory for generated TypeScript files. */
+  readonly outDir: string
+  /**
+   * When true, only generate TypeScript type definitions without parser functions.
+   * Useful when you only need the type shapes and do not need runtime validation.
+   */
+  readonly typesOnly?: boolean
+  /**
+   * When true, compile the generated TypeScript files to .js and .d.ts output.
+   * The .ts source files are removed after compilation.
+   */
+  readonly build?: boolean
+  /**
+   * When true, the generated parsers emit a console.warn for every input key
+   * that is not declared in the schema's properties.
+   */
+  readonly logWarnings?: boolean
+  /**
+   * When true, the generated parsers throw on type/shape mismatches
+   * (wrong type, missing required property, enum/pattern/min/max violations)
+   * instead of coercing invalid input to default values.
+   */
+  readonly strict?: boolean
+  /**
+   * Controls how generated parsers reference their runtime helpers.
+   * - `'package'`: emit `import ... from '@amritk/helpers/...'`.
+   * - `'embedded'`: ship the helper source under `outDir/_helpers/` and emit
+   *   relative imports so the output directory is self-contained.
+   *
+   * When omitted, the CLI auto-detects: it picks `'package'` if `@amritk/helpers`
+   * resolves from outDir, otherwise falls back to `'embedded'`.
+   */
+  readonly helpers?: 'package' | 'embedded'
+}

package/src/cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process'
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { buildSchema } from '@amritk/generate-parsers'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+const execFileAsync = promisify(execFile)
+
+import { detectHelpersMode } from './detect-helpers-mode'
+import { loadConfig } from './load-config'
+import { parseCliArgs } from './parse-cli-args'
+
+/**
+ * Extracts the --config flag value from process args before full parsing.
+ * We need this early so we can load the config file first, then overlay CLI flags.
+ */
+const extractConfigPath = (args: readonly string[]): string | undefined => {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--config' && args[i + 1] && !args[i + 1]?.startsWith('--')) {
+      return args[i + 1]
+    }
+
+    if (arg?.startsWith('--config=')) {
+      return arg.slice('--config='.length)
+    }
+  }
+
+  return undefined
+}
+
+const run = async (): Promise<void> => {
+  // Skip the first two args (node executable and script path)
+  const args = process.argv.slice(2)
+
+  const configPath = extractConfigPath(args)
+
+  // Start with config file values if provided, then overlay CLI flags on top
+  const fileConfig = configPath ? await loadConfig(configPath) : {}
+  const cliConfig = parseCliArgs(args)
+  const config = { ...fileConfig, ...cliConfig }
+
+  if (!config.schema) {
+    console.error('Error: --schema is required. Provide a path to a JSON Schema file.')
+    process.exit(1)
+  }
+
+  if (!config.outDir) {
+    console.error('Error: --outDir is required. Provide an output directory for generated files.')
+    process.exit(1)
+  }
+
+  const schemaPath = resolve(config.schema)
+  const raw = await readFile(schemaPath, 'utf-8')
+  const schema: unknown = JSON.parse(raw)
+
+  const outputDir = resolve(config.outDir)
+  await mkdir(outputDir, { recursive: true })
+
+  const helpersMode = config.helpers ?? detectHelpersMode(outputDir)
+  console.log(`Helpers mode: ${helpersMode}${config.helpers ? ' (explicit)' : ' (auto-detected)'}`)
+
+  const files = await buildSchema(
+    schema as JSONSchema,
+    'Document',
+    undefined,
+    config.typesOnly,
+    config.logWarnings,
+    config.strict,
+    helpersMode,
+  )
+
+  for (const file of files) {
+    const filePath = join(outputDir, file.filename)
+    // Create subdirectories if the filename contains a path
+    await mkdir(dirname(filePath), { recursive: true })
+    await writeFile(filePath, file.content, 'utf-8')
+    console.log(`Generated: ${file.filename}`)
+  }
+
+  if (config.build) {
+    // Write a minimal tsconfig so tsc can compile the generated files without
+    // inheriting settings like allowImportingTsExtensions that block emission.
+    // In 'package' mode tsc finds @amritk/helpers via the consumer's node_modules.
+    // In 'embedded' mode the helpers live under ./_helpers and need no resolution.
+    const tsconfigContent = JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          declaration: true,
+          emitDeclarationOnly: config.typesOnly,
+          skipLibCheck: true,
+        },
+        include: ['./**/*.ts'],
+      },
+      null,
+      2,
+    )
+
+    const tsconfigPath = join(outputDir, '.tsconfig-mjst-build.json')
+    await writeFile(tsconfigPath, tsconfigContent, 'utf-8')
+
+    try {
+      await execFileAsync('npx', ['tsc', '--project', tsconfigPath])
+    } catch {
+      throw new Error('TypeScript compilation failed. Check the generated files for errors.')
+    } finally {
+      await unlink(tsconfigPath)
+    }
+
+    // Remove the intermediate .ts files now that .js and .d.ts have been produced
+    for (const file of files) {
+      await unlink(join(outputDir, file.filename))
+      const jsFilename = file.filename.replace(/\.ts$/, '.js')
+      const dtsFilename = file.filename.replace(/\.ts$/, '.d.ts')
+      console.log(`Built: ${jsFilename}`)
+      console.log(`Built: ${dtsFilename}`)
+    }
+
+    console.log(`\nTotal files built: ${files.length * 2}`)
+  } else {
+    console.log(`\nTotal files generated: ${files.length}`)
+  }
+}
+
+run().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/src/detect-helpers-mode.test.ts

@@ -0,0 +1,45 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import { detectHelpersMode } from './detect-helpers-mode'
+
+describe('detect-helpers-mode', () => {
+  let tmpRoot: string
+
+  beforeAll(async () => {
+    tmpRoot = await mkdtemp(join(tmpdir(), 'mjst-detect-'))
+  })
+
+  afterAll(async () => {
+    await rm(tmpRoot, { recursive: true, force: true })
+  })
+
+  it("returns 'package' when @amritk/helpers is resolvable from outDir", async () => {
+    const outDir = join(tmpRoot, 'with-helpers/out')
+    const helpersPkgDir = join(tmpRoot, 'with-helpers/node_modules/@amritk/helpers')
+    await mkdir(outDir, { recursive: true })
+    await mkdir(helpersPkgDir, { recursive: true })
+    await writeFile(join(helpersPkgDir, 'is-object.js'), 'export const isObject = () => true\n', 'utf-8')
+    await writeFile(
+      join(helpersPkgDir, 'package.json'),
+      JSON.stringify({
+        name: '@amritk/helpers',
+        version: '0.0.0',
+        type: 'module',
+        exports: { './is-object': './is-object.js' },
+      }),
+      'utf-8',
+    )
+
+    expect(detectHelpersMode(outDir)).toBe('package')
+  })
+
+  it("returns 'embedded' when @amritk/helpers cannot be resolved from outDir", async () => {
+    const outDir = join(tmpRoot, 'no-helpers/out')
+    await mkdir(outDir, { recursive: true })
+
+    expect(detectHelpersMode(outDir)).toBe('embedded')
+  })
+})

package/src/detect-helpers-mode.ts

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+
+/**
+ * Detects whether `@amritk/helpers` is resolvable from the consumer's output
+ * directory using standard Node module resolution (walks up `node_modules`).
+ *
+ * Returns `'package'` when generated parsers can safely
+ * `import { ... } from '@amritk/helpers/...'` at runtime, or `'embedded'`
+ * when the helper sources need to be shipped alongside the generated files
+ * for the output to be self-contained.
+ */
+export const detectHelpersMode = (outputDir: string): 'package' | 'embedded' => {
+  const req = createRequire(resolve(outputDir, 'noop.js'))
+  try {
+    req.resolve('@amritk/helpers/is-object')
+    return 'package'
+  } catch {
+    return 'embedded'
+  }
+}

package/src/load-config.test.ts

@@ -0,0 +1,69 @@
+import { writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { loadConfig } from './load-config'
+
+describe('load-config', () => {
+  it('loads schema and outDir from a JSON config file', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify({ schema: 'my-schema.json', outDir: 'output' }))
+
+    const result = await loadConfig(configPath)
+
+    expect(result).toEqual({
+      schema: 'my-schema.json',
+      outDir: 'output',
+    })
+  })
+
+  it('returns partial config when only some keys are present', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify({ schema: 'my-schema.json' }))
+
+    const result = await loadConfig(configPath)
+
+    expect(result).toEqual({
+      schema: 'my-schema.json',
+    })
+  })
+
+  it('ignores non-string values for known keys', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify({ schema: 123, outDir: true }))
+
+    const result = await loadConfig(configPath)
+
+    expect(result).toEqual({})
+  })
+
+  it('throws for non-object config files', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify([1, 2, 3]))
+
+    await expect(loadConfig(configPath)).rejects.toThrow('Config file must be a JSON object')
+  })
+
+  it('throws for missing config files', async () => {
+    await expect(loadConfig('/nonexistent/config.json')).rejects.toThrow()
+  })
+
+  it('loads strict boolean from config file', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify({ schema: 's.json', outDir: 'o', strict: true }))
+
+    const result = await loadConfig(configPath)
+
+    expect(result).toEqual({ schema: 's.json', outDir: 'o', strict: true })
+  })
+
+  it('ignores non-boolean strict value', async () => {
+    const configPath = join(tmpdir(), `test-config-${Date.now()}.json`)
+    await writeFile(configPath, JSON.stringify({ schema: 's.json', strict: 'yes' }))
+
+    const result = await loadConfig(configPath)
+
+    expect(result).toEqual({ schema: 's.json' })
+  })
+})

package/src/load-config.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import type { CliConfig } from './cli-config'
+
+/**
+ * Loads a JSON config file and returns the relevant CLI config properties.
+ * The config file should have the same keys as the CLI flags (schema, outDir).
+ */
+export const loadConfig = async (configPath: string): Promise<Partial<CliConfig>> => {
+  const absolutePath = resolve(configPath)
+  const raw = await readFile(absolutePath, 'utf-8')
+  const parsed: unknown = JSON.parse(raw)
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Config file must be a JSON object: ${configPath}`)
+  }
+
+  const obj = parsed as Record<string, unknown>
+
+  return {
+    ...(typeof obj['schema'] === 'string' && { schema: obj['schema'] }),
+    ...(typeof obj['outDir'] === 'string' && { outDir: obj['outDir'] }),
+    ...(typeof obj['typesOnly'] === 'boolean' && { typesOnly: obj['typesOnly'] }),
+    ...(typeof obj['build'] === 'boolean' && { build: obj['build'] }),
+    ...(typeof obj['logWarnings'] === 'boolean' && { logWarnings: obj['logWarnings'] }),
+    ...(typeof obj['strict'] === 'boolean' && { strict: obj['strict'] }),
+  }
+}

package/src/parse-cli-args.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseCliArgs } from './parse-cli-args'
+
+describe('parse-cli-args', () => {
+  it('parses --schema and --outDir with space-separated values', () => {
+    const result = parseCliArgs(['--schema', 'path/to/schema.json', '--outDir', 'dist'])
+
+    expect(result).toEqual({
+      schema: 'path/to/schema.json',
+      outDir: 'dist',
+    })
+  })
+
+  it('parses --schema and --outDir with equals syntax', () => {
+    const result = parseCliArgs(['--schema=path/to/schema.json', '--outDir=dist'])
+
+    expect(result).toEqual({
+      schema: 'path/to/schema.json',
+      outDir: 'dist',
+    })
+  })
+
+  it('returns empty object when no flags are provided', () => {
+    const result = parseCliArgs([])
+
+    expect(result).toEqual({})
+  })
+
+  it('ignores unknown flags', () => {
+    const result = parseCliArgs(['--unknown', 'value', '--schema', 'schema.json'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+    })
+  })
+
+  it('handles only --schema without --outDir', () => {
+    const result = parseCliArgs(['--schema', 'schema.json'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+    })
+  })
+
+  it('handles only --outDir without --schema', () => {
+    const result = parseCliArgs(['--outDir', 'output'])
+
+    expect(result).toEqual({
+      outDir: 'output',
+    })
+  })
+
+  it('does not treat a flag as a value for the previous flag', () => {
+    const result = parseCliArgs(['--schema', '--outDir', 'output'])
+
+    expect(result).toEqual({
+      outDir: 'output',
+    })
+  })
+
+  it('handles equals syntax with empty value', () => {
+    const result = parseCliArgs(['--schema=', '--outDir=dist'])
+
+    expect(result).toEqual({
+      schema: '',
+      outDir: 'dist',
+    })
+  })
+
+  it('parses --types-only boolean flag', () => {
+    const result = parseCliArgs(['--types-only'])
+
+    expect(result).toEqual({
+      typesOnly: true,
+    })
+  })
+
+  it('parses --types-only=true with equals syntax', () => {
+    const result = parseCliArgs(['--types-only=true'])
+
+    expect(result).toEqual({
+      typesOnly: true,
+    })
+  })
+
+  it('parses --types-only=false with equals syntax', () => {
+    const result = parseCliArgs(['--types-only=false'])
+
+    expect(result).toEqual({
+      typesOnly: false,
+    })
+  })
+
+  it('parses --types-only alongside other flags', () => {
+    const result = parseCliArgs(['--schema', 'schema.json', '--outDir', 'dist', '--types-only'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+      outDir: 'dist',
+      typesOnly: true,
+    })
+  })
+
+  it('parses --build boolean flag', () => {
+    const result = parseCliArgs(['--build'])
+
+    expect(result).toEqual({
+      build: true,
+    })
+  })
+
+  it('parses --build=true with equals syntax', () => {
+    const result = parseCliArgs(['--build=true'])
+
+    expect(result).toEqual({
+      build: true,
+    })
+  })
+
+  it('parses --build=false with equals syntax', () => {
+    const result = parseCliArgs(['--build=false'])
+
+    expect(result).toEqual({
+      build: false,
+    })
+  })
+
+  it('parses --build alongside other flags', () => {
+    const result = parseCliArgs(['--schema', 'schema.json', '--outDir', 'dist', '--build'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+      outDir: 'dist',
+      build: true,
+    })
+  })
+
+  it('parses --log-warnings boolean flag', () => {
+    const result = parseCliArgs(['--log-warnings'])
+
+    expect(result).toEqual({
+      logWarnings: true,
+    })
+  })
+
+  it('parses --log-warnings=true with equals syntax', () => {
+    const result = parseCliArgs(['--log-warnings=true'])
+
+    expect(result).toEqual({
+      logWarnings: true,
+    })
+  })
+
+  it('parses --log-warnings=false with equals syntax', () => {
+    const result = parseCliArgs(['--log-warnings=false'])
+
+    expect(result).toEqual({
+      logWarnings: false,
+    })
+  })
+
+  it('parses --log-warnings alongside other flags', () => {
+    const result = parseCliArgs(['--schema', 'schema.json', '--outDir', 'dist', '--log-warnings'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+      outDir: 'dist',
+      logWarnings: true,
+    })
+  })
+
+  it('parses --strict boolean flag', () => {
+    const result = parseCliArgs(['--strict'])
+
+    expect(result).toEqual({
+      strict: true,
+    })
+  })
+
+  it('parses --strict=true with equals syntax', () => {
+    const result = parseCliArgs(['--strict=true'])
+
+    expect(result).toEqual({
+      strict: true,
+    })
+  })
+
+  it('parses --strict=false with equals syntax', () => {
+    const result = parseCliArgs(['--strict=false'])
+
+    expect(result).toEqual({
+      strict: false,
+    })
+  })
+
+  it('parses --strict alongside other flags', () => {
+    const result = parseCliArgs(['--schema', 'schema.json', '--outDir', 'dist', '--strict'])
+
+    expect(result).toEqual({
+      schema: 'schema.json',
+      outDir: 'dist',
+      strict: true,
+    })
+  })
+
+  it('parses --helpers package with space-separated value', () => {
+    const result = parseCliArgs(['--helpers', 'package'])
+    expect(result).toEqual({ helpers: 'package' })
+  })
+
+  it('parses --helpers=embedded with equals syntax', () => {
+    const result = parseCliArgs(['--helpers=embedded'])
+    expect(result).toEqual({ helpers: 'embedded' })
+  })
+
+  it('ignores invalid --helpers values', () => {
+    const result = parseCliArgs(['--helpers', 'bogus', '--schema', 's.json'])
+    expect(result).toEqual({ schema: 's.json' })
+  })
+
+  it('ignores invalid --helpers=foo values', () => {
+    const result = parseCliArgs(['--helpers=foo', '--schema', 's.json'])
+    expect(result).toEqual({ schema: 's.json' })
+  })
+})

package/src/parse-cli-args.ts

@@ -0,0 +1,97 @@
+import type { CliConfig } from './cli-config'
+
+/**
+ * Parses command-line arguments into a partial CLI config.
+ * Supports --schema, --outDir, and --types-only flags with either `--flag value` or `--flag=value` syntax.
+ * Only returns the flags that were explicitly provided so we can layer them on top of config file values.
+ */
+export const parseCliArgs = (args: readonly string[]): Partial<CliConfig> => {
+  // Use a mutable local type for building, then return as Partial<CliConfig>
+  const config: {
+    schema?: string
+    outDir?: string
+    typesOnly?: boolean
+    build?: boolean
+    logWarnings?: boolean
+    strict?: boolean
+    helpers?: 'package' | 'embedded'
+  } = {}
+
+  const parseHelpersValue = (value: string): 'package' | 'embedded' | undefined => {
+    if (value === 'package' || value === 'embedded') return value
+    return undefined
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (!arg) {
+      continue
+    }
+
+    // Handle --flag=value syntax
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const equalsIndex = arg.indexOf('=')
+      const key = arg.slice(2, equalsIndex)
+      const value = arg.slice(equalsIndex + 1)
+
+      if (key === 'schema') {
+        config.schema = value
+      } else if (key === 'outDir') {
+        config.outDir = value
+      } else if (key === 'types-only') {
+        // Accept --types-only=false to explicitly opt out, otherwise treat as true
+        config.typesOnly = value !== 'false'
+      } else if (key === 'build') {
+        config.build = value !== 'false'
+      } else if (key === 'log-warnings') {
+        config.logWarnings = value !== 'false'
+      } else if (key === 'strict') {
+        config.strict = value !== 'false'
+      } else if (key === 'helpers') {
+        const parsed = parseHelpersValue(value)
+        if (parsed) config.helpers = parsed
+      }
+
+      continue
+    }
+
+    // Handle --flag value syntax
+    if (arg === '--schema') {
+      const value = args[i + 1]
+
+      if (value && !value.startsWith('--')) {
+        config.schema = value
+        i++
+      }
+    } else if (arg === '--outDir') {
+      const value = args[i + 1]
+
+      if (value && !value.startsWith('--')) {
+        config.outDir = value
+        i++
+      }
+    } else if (arg === '--types-only') {
+      // Boolean flag: presence alone enables it, no value needed
+      config.typesOnly = true
+    } else if (arg === '--build') {
+      config.build = true
+    } else if (arg === '--log-warnings') {
+      config.logWarnings = true
+    } else if (arg === '--strict') {
+      config.strict = true
+    } else if (arg === '--helpers') {
+      const value = args[i + 1]
+
+      if (value && !value.startsWith('--')) {
+        const parsed = parseHelpersValue(value)
+        if (parsed) {
+          config.helpers = parsed
+          i++
+        }
+      }
+    }
+  }
+
+  return config
+}