@amritk/mjst 0.1.0 → 0.3.0

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.1.0",
+  "version": "0.3.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -27,8 +27,12 @@
     "mjst": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "bun run --conditions=development ./src/cli.ts",
     "start": "bun run ./src/cli.ts",
@@ -39,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' })
+  })
+})