dialekt 0.1.0

package/src/index.ts

@@ -0,0 +1,56 @@
+export { defineConfig } from './config/define-config.js';
+export type { DialektConfig, ModelConfig, ChunkingConfig, RetryConfig } from './config/types.js';
+export type {
+  ResourceRef,
+  TranslationAdapter,
+  AdapterCapabilities,
+} from './adapter/types.js';
+export { AdapterReadError, AdapterWriteError } from './adapter/types.js';
+export { flattenObject, unflattenObject, diffKeys } from './keys/flatten.js';
+export { chunkKeys } from './translation/chunking.js';
+export { NodePlatformLayer } from './sdk/node-layer.js';
+export { readFileIfExists, writeFileEnsuringDir } from './sdk/file-io.js';
+export { readPhpArrayAsJson, PhpExecutionError } from './sdk/php-array-reader.js';
+export { resolveModel, UnknownProviderError } from './translation/model-registry.js';
+export type { TranslationContext, TranslationStrategy } from './translation/types.js';
+export { TranslationFailedError } from './translation/types.js';
+export { createOneShotStrategy } from './translation/one-shot-strategy.js';
+export { createToolLoopStrategy } from './translation/tool-loop-strategy.js';
+export { runTranslation } from './translation/orchestrator.js';
+export { buildSystemPrompt, buildUserPrompt } from './translation/prompt.js';
+export { computeMissingKeys } from './translation/missing-keys.js';
+export { loadConfig, ConfigLoadError } from './config/load-config.js';
+export {
+  detectFormat,
+  color,
+  glyphs,
+  drawTable,
+  banner,
+  sectionHeader,
+  success,
+  failure,
+  warning,
+  info,
+  keyValue,
+} from './cli/format.js';
+export type { OutputFormat } from './cli/format.js';
+export {
+  formatMissingKeys,
+  formatUnusedKeys,
+  formatValidate,
+  formatLanguages,
+  formatTranslate,
+  formatAdd,
+  formatBenchmark,
+  formatError,
+} from './cli/formatters.js';
+export type {
+  MissingKeyEntry,
+  UnusedKeyEntry,
+  ValidateEntry,
+  ValidateResult,
+  LanguageEntry,
+  TranslateResult,
+  AddResult,
+  BenchmarkEntry,
+} from './cli/formatters.js';

package/src/keys/flatten.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { flattenObject, unflattenObject, diffKeys } from './flatten.js';
+
+describe('flattenObject', () => {
+  it('flattens nested objects to dot-notation keys', () => {
+    expect(
+      flattenObject({
+        validation: { email: 'Email', nested: { deep: 'x' } },
+      }),
+    ).toEqual({ 'validation.email': 'Email', 'validation.nested.deep': 'x' });
+  });
+
+  it('returns {} for an empty object', () => {
+    expect(flattenObject({})).toEqual({});
+  });
+
+  it('preserves empty string values', () => {
+    expect(flattenObject({ a: '' })).toEqual({ a: '' });
+  });
+
+  it('handles deeply nested structures', () => {
+    expect(
+      flattenObject({ a: { b: { c: { d: { e: 'deep' } } } } }),
+    ).toEqual({ 'a.b.c.d.e': 'deep' });
+  });
+
+  it('ignores arrays (not flattened)', () => {
+    expect(flattenObject({ items: ['first', 'second'] })).toEqual({});
+  });
+
+  it('ignores mixed arrays and objects', () => {
+    expect(flattenObject({ items: [{ name: 'a' }, { name: 'b' }] })).toEqual({});
+  });
+
+  it('ignores null values', () => {
+    expect(flattenObject({ a: null })).toEqual({});
+  });
+
+  it('ignores numeric values', () => {
+    expect(flattenObject({ count: 42 })).toEqual({});
+  });
+
+  it('ignores boolean values', () => {
+    expect(flattenObject({ enabled: true })).toEqual({});
+  });
+
+  it('preserves unicode values', () => {
+    expect(flattenObject({ greeting: 'Héllo 🌍' })).toEqual({
+      greeting: 'Héllo 🌍',
+    });
+  });
+});
+
+describe('unflattenObject', () => {
+  it('rebuilds nested structure from dot-notation keys', () => {
+    expect(unflattenObject({ 'validation.email': 'Email' })).toEqual({
+      validation: { email: 'Email' },
+    });
+  });
+
+  it('round-trips with flattenObject', () => {
+    const original = { a: { b: { c: '1' }, d: '2' } };
+    expect(unflattenObject(flattenObject(original))).toEqual(original);
+  });
+
+  it('handles deeply nested keys', () => {
+    expect(
+      unflattenObject({ 'a.b.c.d.e': 'deep' }),
+    ).toEqual({ a: { b: { c: { d: { e: 'deep' } } } } });
+  });
+
+  it('treats numeric keys as object properties, not array indices', () => {
+    expect(unflattenObject({ 'items.0': 'first', 'items.1': 'second' })).toEqual({
+      items: { '0': 'first', '1': 'second' },
+    });
+  });
+
+  it('handles empty flat object', () => {
+    expect(unflattenObject({})).toEqual({});
+  });
+
+  it('handles single-level keys', () => {
+    expect(unflattenObject({ a: '1', b: '2' })).toEqual({ a: '1', b: '2' });
+  });
+});
+
+describe('diffKeys', () => {
+  it('returns keys present in source but missing in target', () => {
+    expect(diffKeys({ a: '1', b: '2' }, { a: '1' })).toEqual(['b']);
+  });
+
+  it('returns [] when target has all source keys', () => {
+    expect(diffKeys({ a: '1' }, { a: '1', b: '2' })).toEqual([]);
+  });
+
+  it('returns all keys when target is empty', () => {
+    expect(diffKeys({ a: '1', b: '2' }, {})).toEqual(['a', 'b']);
+  });
+
+  it('returns [] when source is empty', () => {
+    expect(diffKeys({}, { a: '1' })).toEqual([]);
+  });
+
+  it('handles keys with different values', () => {
+    expect(diffKeys({ a: '1' }, { a: '2' })).toEqual([]);
+  });
+
+  it('handles nested flattened keys', () => {
+    expect(diffKeys({ 'a.b': '1', 'a.c': '2' }, { 'a.b': '1' })).toEqual(['a.c']);
+  });
+});

package/src/keys/flatten.ts

@@ -0,0 +1,41 @@
+export function flattenObject(
+  input: Readonly<Record<string, unknown>>,
+  prefix = '',
+): Record<string, string> {
+  const output: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input)) {
+    const fullKey = prefix === '' ? key : `${prefix}.${key}`;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      Object.assign(output, flattenObject(value as Record<string, unknown>, fullKey));
+    } else if (typeof value === 'string') {
+      output[fullKey] = value;
+    }
+  }
+  return output;
+}
+
+export function unflattenObject(
+  input: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  for (const [dottedKey, value] of Object.entries(input)) {
+    const segments = dottedKey.split('.');
+    let cursor = output;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i]!;
+      if (typeof cursor[segment] !== 'object' || cursor[segment] === null) {
+        cursor[segment] = {};
+      }
+      cursor = cursor[segment] as Record<string, unknown>;
+    }
+    cursor[segments[segments.length - 1]!] = value;
+  }
+  return output;
+}
+
+export function diffKeys(
+  source: Readonly<Record<string, string>>,
+  target: Readonly<Record<string, string>>,
+): string[] {
+  return Object.keys(source).filter((key) => !(key in target));
+}

package/src/sdk/file-io.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Layer } from 'effect';
+import { FileSystem, Path } from '@effect/platform';
+import { readFileIfExists, writeFileEnsuringDir } from './file-io.js';
+
+function makeFsLayer(files: Record<string, string>) {
+  const stub = FileSystem.makeNoop({
+    exists: (path) => Effect.succeed(path in files),
+    readFileString: (path) =>
+      path in files
+        ? Effect.succeed(files[path]!)
+        : Effect.fail(
+            new Error(`ENOENT: ${path}`) as never,
+          ),
+    writeFileString: (path, content) => {
+      files[path] = content;
+      return Effect.void;
+    },
+    makeDirectory: () => Effect.void,
+  });
+  return Layer.succeed(FileSystem.FileSystem, stub);
+}
+
+describe('readFileIfExists', () => {
+  it('returns content when file exists', async () => {
+    const files = { '/a/b.txt': 'hello' };
+    const program = readFileIfExists('/a/b.txt').pipe(
+      Effect.provide(makeFsLayer(files)),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBe('hello');
+  });
+
+  it('returns null when file does not exist', async () => {
+    const program = readFileIfExists('/a/missing.txt').pipe(
+      Effect.provide(makeFsLayer({})),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBeNull();
+  });
+
+  it('returns null for empty file system', async () => {
+    const program = readFileIfExists('/any/path.txt').pipe(
+      Effect.provide(makeFsLayer({})),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBeNull();
+  });
+
+  it('returns content for deeply nested path', async () => {
+    const files = { '/very/deep/nested/file.txt': 'deep content' };
+    const program = readFileIfExists('/very/deep/nested/file.txt').pipe(
+      Effect.provide(makeFsLayer(files)),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBe('deep content');
+  });
+
+  it('handles unicode content', async () => {
+    const files = { '/unicode.txt': 'Héllo 🌍 — 日本語' };
+    const program = readFileIfExists('/unicode.txt').pipe(
+      Effect.provide(makeFsLayer(files)),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBe('Héllo 🌍 — 日本語');
+  });
+
+  it('handles empty string content', async () => {
+    const files = { '/empty.txt': '' };
+    const program = readFileIfExists('/empty.txt').pipe(
+      Effect.provide(makeFsLayer(files)),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toBe('');
+  });
+});
+
+describe('writeFileEnsuringDir', () => {
+  it('writes content and creates parent directories', async () => {
+    const files: Record<string, string> = {};
+    const program = writeFileEnsuringDir('/a/b/c.txt', 'content').pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/a/b/c.txt']).toBe('content');
+  });
+
+  it('overwrites existing file', async () => {
+    const files: Record<string, string> = { '/existing.txt': 'old' };
+    const program = writeFileEnsuringDir('/existing.txt', 'new').pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/existing.txt']).toBe('new');
+  });
+
+  it('handles deeply nested paths', async () => {
+    const files: Record<string, string> = {};
+    const program = writeFileEnsuringDir('/a/b/c/d/e.txt', 'nested').pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/a/b/c/d/e.txt']).toBe('nested');
+  });
+
+  it('handles empty content', async () => {
+    const files: Record<string, string> = {};
+    const program = writeFileEnsuringDir('/empty.txt', '').pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/empty.txt']).toBe('');
+  });
+
+  it('handles unicode content', async () => {
+    const files: Record<string, string> = {};
+    const content = 'Héllo 🌍 — 日本語';
+    const program = writeFileEnsuringDir('/unicode.txt', content).pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/unicode.txt']).toBe(content);
+  });
+
+  it('handles paths with spaces', async () => {
+    const files: Record<string, string> = {};
+    const program = writeFileEnsuringDir('/path with spaces/file.txt', 'content').pipe(
+      Effect.provide(makeFsLayer(files)),
+      Effect.provide(Path.layer),
+    );
+    await Effect.runPromise(program);
+    expect(files['/path with spaces/file.txt']).toBe('content');
+  });
+});

package/src/sdk/file-io.ts

@@ -0,0 +1,21 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+
+export function readFileIfExists(path: string) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const exists = yield* fs.exists(path);
+    if (!exists) return null;
+    return yield* fs.readFileString(path);
+  });
+}
+
+export function writeFileEnsuringDir(path: string, content: string) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path_ = yield* Path.Path;
+    const dir = path_.dirname(path);
+    yield* fs.makeDirectory(dir, { recursive: true });
+    yield* fs.writeFileString(path, content);
+  });
+}

package/src/sdk/node-layer.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { Effect } from 'effect';
+import { FileSystem } from '@effect/platform/FileSystem';
+import { Path } from '@effect/platform/Path';
+import { CommandExecutor } from '@effect/platform/CommandExecutor';
+import { NodePlatformLayer } from './node-layer.js';
+
+describe('NodePlatformLayer', () => {
+  it('provides a working FileSystem service', async () => {
+    const program = Effect.gen(function* () {
+      const fs = yield* FileSystem;
+      return yield* fs.exists(process.cwd());
+    });
+    const result = await Effect.runPromise(Effect.provide(program, NodePlatformLayer));
+    expect(result).toBe(true);
+  });
+
+  it('provides a working Path service', async () => {
+    const program = Effect.gen(function* () {
+      const path = yield* Path;
+      return path.join('a', 'b');
+    });
+    const result = await Effect.runPromise(Effect.provide(program, NodePlatformLayer));
+    expect(result).toContain('a');
+    expect(result).toContain('b');
+  });
+
+  it('provides a working CommandExecutor service', async () => {
+    const program = Effect.gen(function* () {
+      const executor = yield* CommandExecutor;
+      return executor !== undefined;
+    });
+    const result = await Effect.runPromise(Effect.provide(program, NodePlatformLayer));
+    expect(result).toBe(true);
+  });
+
+  it('can read a real file', async () => {
+    const program = Effect.gen(function* () {
+      const fs = yield* FileSystem;
+      return yield* fs.readFileString(process.cwd() + '/package.json');
+    });
+    const result = await Effect.runPromise(Effect.provide(program, NodePlatformLayer));
+    expect(result).toContain('name');
+  });
+
+  it('reports missing files correctly', async () => {
+    const program = Effect.gen(function* () {
+      const fs = yield* FileSystem;
+      return yield* fs.exists('/nonexistent/path/that/should/not/exist');
+    });
+    const result = await Effect.runPromise(Effect.provide(program, NodePlatformLayer));
+    expect(result).toBe(false);
+  });
+});

package/src/sdk/node-layer.ts

@@ -0,0 +1,10 @@
+import { NodeContext } from '@effect/platform-node';
+import { Layer } from 'effect';
+
+/**
+ * The only file in this package (besides cli/main.ts) permitted to know
+ * this is running on Node.js. Provides FileSystem, Path, and
+ * CommandExecutor. Swapping to Bun/Deno later means swapping this one
+ * import for @effect/platform-bun's equivalent — nothing else changes.
+ */
+export const NodePlatformLayer = NodeContext.layer;

package/src/sdk/php-array-reader.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Either } from 'effect';
+import { CommandExecutor, Command } from '@effect/platform';
+import { NodePlatformLayer } from './node-layer.js';
+import { readPhpArrayAsJson, PhpExecutionError } from './php-array-reader.js';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+function hasPhpBinary(): boolean {
+  try {
+    execSync('php -v', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('readPhpArrayAsJson', () => {
+  const testDir = join(tmpdir(), `dialekt-php-test-${Date.now()}`);
+
+  it.skipIf(!hasPhpBinary())('reads a PHP array file as JSON', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'test.php');
+    writeFileSync(filePath, "<?php return ['email' => 'Email address'];");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({ email: 'Email address' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('returns PhpExecutionError for a nonexistent file', async () => {
+    const program = Effect.provide(readPhpArrayAsJson('/nonexistent/file.php'), NodePlatformLayer);
+    const exit = await Effect.runPromise(Effect.either(program)) as Either.Either<unknown, PhpExecutionError>;
+    if (exit._tag === 'Left') {
+      expect(exit.left._tag).toBe('PhpExecutionError');
+      expect(exit.left.path).toBe('/nonexistent/file.php');
+    } else {
+      throw new Error('Expected Left');
+    }
+  });
+
+  it.skipIf(!hasPhpBinary())('reads nested PHP arrays', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'nested.php');
+    writeFileSync(filePath, "<?php return ['validation' => ['email' => 'Email address', 'required' => 'Required field']];");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({
+      validation: { email: 'Email address', required: 'Required field' },
+    });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('reads PHP arrays with numeric keys as JS arrays', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'numeric.php');
+    writeFileSync(filePath, "<?php return ['first', 'second', 'third'];");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual(['first', 'second', 'third']);
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('reads PHP arrays with unicode values', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'unicode.php');
+    writeFileSync(filePath, "<?php return ['greeting' => 'Héllo 🌍 — 日本語'];");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({ greeting: 'Héllo 🌍 — 日本語' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('reads empty PHP array as empty JS array', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'empty.php');
+    writeFileSync(filePath, "<?php return [];");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual([]);
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('returns PhpExecutionError for malformed PHP', async () => {
+    mkdirSync(testDir, { recursive: true });
+    const filePath = join(testDir, 'bad.php');
+    writeFileSync(filePath, "<?php this is not valid php");
+
+    const program = Effect.provide(readPhpArrayAsJson(filePath), NodePlatformLayer);
+    const exit = await Effect.runPromise(Effect.either(program)) as Either.Either<unknown, PhpExecutionError>;
+    expect(exit._tag).toBe('Left');
+    if (exit._tag === 'Left') {
+      expect(exit.left._tag).toBe('PhpExecutionError');
+    }
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('is skipped when php is unavailable', () => {
+    expect(hasPhpBinary()).toBe(true); // meta-test: if php IS available, this proves skipIf works
+  });
+});

package/src/sdk/php-array-reader.ts

@@ -0,0 +1,26 @@
+import { Command } from '@effect/platform';
+import type { CommandExecutor } from '@effect/platform/CommandExecutor';
+import { Effect, Data } from 'effect';
+
+export class PhpExecutionError extends Data.TaggedError('PhpExecutionError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {}
+
+const DUMP_SCRIPT =
+  "echo json_encode(is_array($v = require $argv[1]) ? $v : [], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);";
+
+export function readPhpArrayAsJson(
+  absolutePath: string,
+): Effect.Effect<Record<string, unknown>, PhpExecutionError, CommandExecutor> {
+  return Effect.gen(function* () {
+    const cmd = Command.make('php', '-r', DUMP_SCRIPT, '--', absolutePath);
+    const output = yield* Command.string(cmd).pipe(
+      Effect.mapError((cause) => new PhpExecutionError({ path: absolutePath, cause })),
+    );
+    return yield* Effect.try({
+      try: () => JSON.parse(output) as Record<string, unknown>,
+      catch: (cause) => new PhpExecutionError({ path: absolutePath, cause }),
+    });
+  });
+}