human-to-code 0.0.1 → 0.1.2

package/src/config.ts

@@ -1,186 +0,0 @@
-/**
- * Structured config loader.
- *
- * Config is deterministic JSON (`human-to-code.config.json`), never parsed by
- * an LLM — see plan §1.7 / §2. A hand-rolled validator keeps the tool
- * dependency-free and gives precise error messages.
- */
-
-import { readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type {
-  Config,
-  ProviderConfig,
-  ProviderName,
-  TargetLanguage,
-} from "./types.ts";
-
-export const CONFIG_FILENAME = "human-to-code.config.json";
-
-const LANGUAGES: readonly TargetLanguage[] = [
-  "typescript",
-  "javascript",
-  "python",
-];
-
-const PROVIDERS: readonly ProviderName[] = [
-  "openai",
-  "anthropic",
-  "ollama",
-  "grok",
-  "gemini",
-];
-
-/**
- * Current, non-dated default model per provider. The Anthropic default is the
- * current flagship — the README's `claude-3-5-sonnet-20241022` is retired.
- */
-const DEFAULT_MODEL: Record<ProviderName, string> = {
-  anthropic: "claude-opus-4-8",
-  openai: "gpt-4o",
-  ollama: "llama3.2",
-  grok: "grok-4.1",
-  gemini: "gemini-2.5-pro",
-};
-
-/** The current default model id for a provider. */
-export function defaultModelFor(name: ProviderName): string {
-  return DEFAULT_MODEL[name];
-}
-
-export const DEFAULT_CONFIG: Config = {
-  language: "typescript",
-  filesToIgnore: ["node_modules", ".git", "dist"],
-  allowNonHumanFiles: false,
-  provider: {
-    name: "anthropic",
-    model: DEFAULT_MODEL.anthropic,
-  },
-};
-
-/** Thrown for any malformed config; message is safe to show the user. */
-export class ConfigError extends Error {}
-
-function isObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-function validateProvider(raw: unknown): ProviderConfig {
-  if (!isObject(raw)) {
-    throw new ConfigError("`provider` must be an object.");
-  }
-  const name = raw.name;
-  if (typeof name !== "string" || !PROVIDERS.includes(name as ProviderName)) {
-    throw new ConfigError(
-      `\`provider.name\` must be one of: ${PROVIDERS.join(", ")}.`,
-    );
-  }
-  const providerName = name as ProviderName;
-
-  let model = raw.model;
-  if (model === undefined) {
-    model = DEFAULT_MODEL[providerName];
-  } else if (typeof model !== "string" || model.length === 0) {
-    throw new ConfigError("`provider.model` must be a non-empty string.");
-  }
-
-  const provider: ProviderConfig = { name: providerName, model: model as string };
-
-  if (raw.baseUrl !== undefined) {
-    if (typeof raw.baseUrl !== "string") {
-      throw new ConfigError("`provider.baseUrl` must be a string.");
-    }
-    // Enforce TLS — a bad base URL can serve poisoned strict (plan §3.7).
-    if (!raw.baseUrl.startsWith("https://")) {
-      throw new ConfigError("`provider.baseUrl` must use https://.");
-    }
-    provider.baseUrl = raw.baseUrl;
-  }
-
-  return provider;
-}
-
-/** Validate an already-parsed object into a fully-defaulted Config. */
-export function validateConfig(raw: unknown): Config {
-  if (!isObject(raw)) {
-    throw new ConfigError("Config root must be a JSON object.");
-  }
-
-  const config: Config = {
-    ...DEFAULT_CONFIG,
-    provider: { ...DEFAULT_CONFIG.provider },
-  };
-
-  if (raw.language !== undefined) {
-    if (
-      typeof raw.language !== "string" ||
-      !LANGUAGES.includes(raw.language as TargetLanguage)
-    ) {
-      throw new ConfigError(
-        `\`language\` must be one of: ${LANGUAGES.join(", ")}.`,
-      );
-    }
-    config.language = raw.language as TargetLanguage;
-  }
-
-  if (raw.filesToIgnore !== undefined) {
-    if (
-      !Array.isArray(raw.filesToIgnore) ||
-      !raw.filesToIgnore.every((f) => typeof f === "string")
-    ) {
-      throw new ConfigError("`filesToIgnore` must be an array of strings.");
-    }
-    config.filesToIgnore = raw.filesToIgnore as string[];
-  }
-
-  if (raw.allowNonHumanFiles !== undefined) {
-    if (typeof raw.allowNonHumanFiles !== "boolean") {
-      throw new ConfigError("`allowNonHumanFiles` must be a boolean.");
-    }
-    config.allowNonHumanFiles = raw.allowNonHumanFiles;
-  }
-
-  if (raw.provider !== undefined) {
-    config.provider = validateProvider(raw.provider);
-  }
-
-  return config;
-}
-
-/**
- * Load config from `<root>/human-to-code.config.json`. Returns the defaults
- * (with a flag) when no config file exists so first-run works with zero setup.
- */
-export async function loadConfig(
-  root: string,
-): Promise<{ config: Config; fromFile: boolean }> {
-  const path = join(root, CONFIG_FILENAME);
-  if (!existsSync(path)) {
-    return {
-      config: { ...DEFAULT_CONFIG, provider: { ...DEFAULT_CONFIG.provider } },
-      fromFile: false,
-    };
-  }
-
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch (err) {
-    throw new ConfigError(`Could not read ${CONFIG_FILENAME}: ${String(err)}`);
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    throw new ConfigError(`${CONFIG_FILENAME} is not valid JSON: ${String(err)}`);
-  }
-
-  return { config: validateConfig(parsed), fromFile: true };
-}
-
-/** Serialize the default config for `--init`. */
-export function defaultConfigJson(): string {
-  return JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n";
-}

package/src/discovery.ts

@@ -1,186 +0,0 @@
-/**
- * File discovery for the deterministic core.
- *
- * Responsibilities (plan §3.3–3.4):
- *  - Walk the project, classifying .human / .strict.human / config / secrets.
- *  - Apply a name-based ignore denylist + best-effort .gitignore.
- *  - Never follow symlinks (traversal safety).
- *  - Provide a git-tracked-secrets check so the CLI can refuse to run.
- *
- * Discovery is side-effect free; the CLI decides what to do with the result.
- */
-
-import { readdir } from "node:fs/promises";
-import { spawnSync } from "node:child_process";
-import { relative, resolve, sep } from "node:path";
-import { CONFIG_FILENAME } from "./config.ts";
-import type { DiscoveryResult, SourceFile, SourceKind } from "./types.ts";
-
-const SECRETS_FILENAME = "secrets.human";
-const HUMAN_CONFIG_FILENAME = "config.human";
-const STRICT_SUFFIX = ".strict.human";
-const HUMAN_SUFFIX = ".human";
-
-/** Names always skipped regardless of config. */
-const ALWAYS_IGNORE = new Set([".git", "node_modules", CONFIG_FILENAME]);
-
-function toPosix(p: string): string {
-  return sep === "/" ? p : p.split(sep).join("/");
-}
-
-function classify(basename: string): SourceKind | null {
-  if (basename === SECRETS_FILENAME) return "secrets";
-  if (basename === HUMAN_CONFIG_FILENAME) return "config";
-  if (basename.endsWith(STRICT_SUFFIX)) return "strict";
-  // A plain .human file that is not one of the special files above.
-  if (basename.endsWith(HUMAN_SUFFIX)) return "human";
-  return null;
-}
-
-function strictSiblingOf(relPath: string): string {
-  // foo.human -> foo.strict.human
-  return relPath.slice(0, -HUMAN_SUFFIX.length) + STRICT_SUFFIX;
-}
-
-/**
- * Recursively collect candidate files. Directories/files whose basename is in
- * `ignore` are skipped. Symlinks are never followed.
- */
-async function walk(
-  root: string,
-  dir: string,
-  ignore: Set<string>,
-  out: SourceFile[],
-  counters: { ignored: number },
-): Promise<void> {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    const abs = resolve(dir, entry.name);
-
-    if (entry.isSymbolicLink()) {
-      counters.ignored++;
-      continue; // traversal safety — never follow symlinks
-    }
-
-    if (ignore.has(entry.name)) {
-      counters.ignored++;
-      continue;
-    }
-
-    if (entry.isDirectory()) {
-      await walk(root, abs, ignore, out, counters);
-      continue;
-    }
-
-    if (!entry.isFile()) continue;
-
-    const kind = classify(entry.name);
-    if (kind === null) {
-      // Not a file we track; not counted as "ignored" for reporting.
-      continue;
-    }
-
-    const relPath = toPosix(relative(root, abs));
-    const file: SourceFile = { absPath: abs, relPath, kind };
-    if (kind === "human") {
-      file.strictSibling = strictSiblingOf(relPath);
-    }
-    out.push(file);
-  }
-}
-
-/** Return the subset of relPaths that git considers ignored (best effort). */
-function gitIgnored(root: string, relPaths: string[]): Set<string> {
-  if (relPaths.length === 0) return new Set();
-  const inRepo = spawnSync(
-    "git",
-    ["-C", root, "rev-parse", "--is-inside-work-tree"],
-    { encoding: "utf8" },
-  );
-  if (inRepo.status !== 0 || inRepo.stdout.trim() !== "true") return new Set();
-
-  const res = spawnSync("git", ["-C", root, "check-ignore", "--stdin"], {
-    input: relPaths.join("\n"),
-    encoding: "utf8",
-  });
-  // Exit 0 => some ignored, 1 => none ignored, other => error (treat as none).
-  if (res.status !== 0 && res.status !== 1) return new Set();
-  return new Set(
-    res.stdout
-      .split("\n")
-      .map((l) => l.trim())
-      .filter(Boolean),
-  );
-}
-
-/**
- * Discover and classify all source files under `rootInput`.
- *
- * @param rootInput  directory to scan
- * @param extraIgnore  config.filesToIgnore (name-based denylist)
- */
-export async function discover(
-  rootInput: string,
-  extraIgnore: string[] = [],
-): Promise<DiscoveryResult> {
-  const root = resolve(rootInput);
-  const ignore = new Set<string>([...ALWAYS_IGNORE, ...extraIgnore]);
-
-  const found: SourceFile[] = [];
-  const counters = { ignored: 0 };
-  await walk(root, root, ignore, found, counters);
-
-  // Best-effort .gitignore filtering on top of the name denylist.
-  const ignored = gitIgnored(
-    root,
-    found.map((f) => f.relPath),
-  );
-  const kept = found.filter((f) => {
-    // Secrets are always surfaced (so we can enforce safety), even if ignored.
-    if (f.kind === "secrets") return true;
-    if (ignored.has(f.relPath)) {
-      counters.ignored++;
-      return false;
-    }
-    return true;
-  });
-
-  const result: DiscoveryResult = {
-    root,
-    human: kept.filter((f) => f.kind === "human"),
-    strict: kept.filter((f) => f.kind === "strict"),
-    ignoredCount: counters.ignored,
-  };
-  const secrets = kept.find((f) => f.kind === "secrets");
-  if (secrets) result.secrets = secrets;
-  return result;
-}
-
-/**
- * Refuse to run if `secrets.human` is tracked by git — a committed secrets file
- * is the mistake we most want to prevent (plan §3.3). No-op outside a git repo.
- * @returns an error message if unsafe, otherwise null.
- */
-export function secretsTrackedError(secret: SourceFile): string | null {
-  if (secret.kind !== "secrets") return null;
-  const root = resolve(secret.absPath, "..");
-  const res = spawnSync(
-    "git",
-    ["-C", root, "ls-files", "--error-unmatch", secret.relPath],
-    { encoding: "utf8" },
-  );
-  if (res.status === 0) {
-    return (
-      `Refusing to run: ${secret.relPath} is tracked by git. ` +
-      `Remove it with \`git rm --cached ${secret.relPath}\` and add it to .gitignore. ` +
-      `Prefer environment variables or your OS keychain for provider credentials.`
-    );
-  }
-  return null;
-}

package/src/index.ts

@@ -1,22 +0,0 @@
-/** Public API surface for programmatic use. */
-
-export type {
-  Config,
-  ProviderConfig,
-  ProviderName,
-  TargetLanguage,
-  SourceFile,
-  SourceKind,
-  DiscoveryResult,
-} from "./types.ts";
-
-export {
-  loadConfig,
-  validateConfig,
-  defaultConfigJson,
-  DEFAULT_CONFIG,
-  CONFIG_FILENAME,
-  ConfigError,
-} from "./config.ts";
-
-export { discover, secretsTrackedError } from "./discovery.ts";

package/src/types.ts

@@ -1,74 +0,0 @@
-/**
- * Shared types for human-to-code.
- *
- * The pipeline is:  .human --(LLM)--> .strict.human --(deterministic)--> code
- * These types describe the deterministic core (config + discovery) only; the
- * strict DSL and code generators are added in later build steps.
- */
-
-export type TargetLanguage = "typescript" | "javascript" | "python";
-
-export type ProviderName =
-  | "openai"
-  | "anthropic"
-  | "ollama"
-  | "grok"
-  | "gemini";
-
-export interface ProviderConfig {
-  /** Which LLM provider drives the human -> strict step. */
-  name: ProviderName;
-  /** Model id. Configurable; defaults are current, not dated snapshots. */
-  model: string;
-  /** Optional override endpoint (e.g. Ollama Cloud). Must be https. */
-  baseUrl?: string;
-}
-
-export interface Config {
-  /** Target language for the deterministic code generator. */
-  language: TargetLanguage;
-  /** Glob-free directory/file names to skip during discovery (a denylist). */
-  filesToIgnore: string[];
-  /**
-   * If true, non-.human files carrying `@Human:` directives may also be
-   * processed. Off by default — it widens the surface area (see plan §1.6).
-   */
-  allowNonHumanFiles: boolean;
-  /** Provider used only for the human -> strict step. */
-  provider: ProviderConfig;
-}
-
-/** Classification of a source file found during discovery. */
-export type SourceKind =
-  /** A hand-written or generated strict IR file: `foo.strict.human`. */
-  | "strict"
-  /** A natural-language source file: `foo.human` (not `.strict.human`). */
-  | "human"
-  /** Reserved special files, never compiled and never sent to a provider. */
-  | "config"
-  | "secrets";
-
-export interface SourceFile {
-  /** Absolute path. */
-  absPath: string;
-  /** Path relative to the discovery root, using forward slashes. */
-  relPath: string;
-  kind: SourceKind;
-  /**
-   * For a `.human` file, the sibling `.strict.human` path that would take
-   * precedence if it exists. Undefined for non-human kinds.
-   */
-  strictSibling?: string;
-}
-
-export interface DiscoveryResult {
-  root: string;
-  /** Natural-language sources eligible for the human -> strict step. */
-  human: SourceFile[];
-  /** Strict IR sources (hand-written ones take precedence over generated). */
-  strict: SourceFile[];
-  /** The secrets file, if present. Never compiled, never sent to a provider. */
-  secrets?: SourceFile;
-  /** Files skipped by ignore rules, for reporting under --dry-run. */
-  ignoredCount: number;
-}

package/test/config.test.ts

@@ -1,97 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtemp, writeFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  validateConfig,
-  loadConfig,
-  ConfigError,
-  DEFAULT_CONFIG,
-  CONFIG_FILENAME,
-} from "../src/config.ts";
-
-test("validateConfig fills defaults from an empty object", () => {
-  const c = validateConfig({});
-  assert.equal(c.language, "typescript");
-  assert.equal(c.provider.name, "anthropic");
-  assert.equal(c.provider.model, "claude-opus-4-8");
-  assert.equal(c.allowNonHumanFiles, false);
-});
-
-test("validateConfig accepts a valid language", () => {
-  assert.equal(validateConfig({ language: "python" }).language, "python");
-});
-
-test("validateConfig rejects an unknown language", () => {
-  assert.throws(() => validateConfig({ language: "rust" }), ConfigError);
-});
-
-test("provider model defaults per provider", () => {
-  const c = validateConfig({ provider: { name: "openai" } });
-  assert.equal(c.provider.model, "gpt-4o");
-});
-
-test("validateConfig rejects an unknown provider", () => {
-  assert.throws(
-    () => validateConfig({ provider: { name: "cohere" } }),
-    ConfigError,
-  );
-});
-
-test("baseUrl must be https", () => {
-  assert.throws(
-    () =>
-      validateConfig({
-        provider: { name: "ollama", baseUrl: "http://ollama.com" },
-      }),
-    ConfigError,
-  );
-  const ok = validateConfig({
-    provider: { name: "ollama", baseUrl: "https://ollama.com" },
-  });
-  assert.equal(ok.provider.baseUrl, "https://ollama.com");
-});
-
-test("validateConfig rejects non-object root", () => {
-  assert.throws(() => validateConfig([]), ConfigError);
-  assert.throws(() => validateConfig("nope"), ConfigError);
-});
-
-test("loadConfig returns defaults when no file exists", async () => {
-  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
-  try {
-    const { config, fromFile } = await loadConfig(dir);
-    assert.equal(fromFile, false);
-    assert.deepEqual(config, DEFAULT_CONFIG);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-});
-
-test("loadConfig reads and validates a config file", async () => {
-  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
-  try {
-    await writeFile(
-      join(dir, CONFIG_FILENAME),
-      JSON.stringify({ language: "javascript", provider: { name: "gemini" } }),
-    );
-    const { config, fromFile } = await loadConfig(dir);
-    assert.equal(fromFile, true);
-    assert.equal(config.language, "javascript");
-    assert.equal(config.provider.name, "gemini");
-    assert.equal(config.provider.model, "gemini-2.5-pro");
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-});
-
-test("loadConfig surfaces invalid JSON as ConfigError", async () => {
-  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
-  try {
-    await writeFile(join(dir, CONFIG_FILENAME), "{ not json ");
-    await assert.rejects(() => loadConfig(dir), ConfigError);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-});

package/test/discovery.test.ts

@@ -1,91 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtemp, mkdir, writeFile, symlink, rm } from "node:fs/promises";
-import { spawnSync } from "node:child_process";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { discover, secretsTrackedError } from "../src/discovery.ts";
-
-async function makeFixture(): Promise<string> {
-  const root = await mkdtemp(join(tmpdir(), "h2c-disc-"));
-  await writeFile(join(root, "a.human"), "print hello");
-  await writeFile(join(root, "a.strict.human"), "fn printHello");
-  await writeFile(join(root, "b.human"), "print bye"); // no strict sibling
-  await writeFile(join(root, "secrets.human"), "API Key: sk-x");
-  await writeFile(join(root, "config.human"), "Language: typescript");
-  await writeFile(join(root, "human-to-code.config.json"), "{}");
-  await mkdir(join(root, "node_modules"));
-  await writeFile(join(root, "node_modules", "dep.human"), "ignored");
-  await mkdir(join(root, "sub"));
-  await writeFile(join(root, "sub", "c.human"), "nested");
-  try {
-    await symlink(join(root, "sub"), join(root, "linkdir"), "dir");
-  } catch {
-    // symlinks may be unavailable; the rest of the assertions still hold.
-  }
-  return root;
-}
-
-test("discover classifies files and applies ignore rules", async () => {
-  const root = await makeFixture();
-  try {
-    const r = await discover(root, ["node_modules", ".git", "dist"]);
-
-    const humanPaths = r.human.map((f) => f.relPath).sort();
-    assert.deepEqual(humanPaths, ["a.human", "b.human", "sub/c.human"]);
-
-    assert.deepEqual(
-      r.strict.map((f) => f.relPath),
-      ["a.strict.human"],
-    );
-
-    // node_modules/dep.human is ignored.
-    assert.ok(!humanPaths.includes("node_modules/dep.human"));
-
-    // The symlinked dir must not be followed (no duplicate c.human).
-    assert.ok(!humanPaths.includes("linkdir/c.human"));
-
-    // secrets.human is surfaced separately, never as a human source.
-    assert.ok(r.secrets);
-    assert.equal(r.secrets?.relPath, "secrets.human");
-
-    // strictSibling wiring.
-    const a = r.human.find((f) => f.relPath === "a.human");
-    assert.equal(a?.strictSibling, "a.strict.human");
-    const b = r.human.find((f) => f.relPath === "b.human");
-    assert.equal(b?.strictSibling, "b.strict.human");
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});
-
-test("secretsTrackedError returns null when not in a git repo", async () => {
-  const root = await makeFixture();
-  try {
-    const r = await discover(root, ["node_modules"]);
-    assert.ok(r.secrets);
-    assert.equal(secretsTrackedError(r.secrets!), null);
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});
-
-test("secretsTrackedError refuses when secrets.human is git-tracked", async () => {
-  const root = await makeFixture();
-  try {
-    assert.equal(
-      spawnSync("git", ["-C", root, "init", "-q"]).status,
-      0,
-      "git init failed",
-    );
-    // Staging is enough for `git ls-files` to consider it tracked.
-    spawnSync("git", ["-C", root, "add", "secrets.human"]);
-
-    const r = await discover(root, ["node_modules"]);
-    assert.ok(r.secrets);
-    const msg = secretsTrackedError(r.secrets!);
-    assert.ok(msg && msg.includes("Refusing to run"));
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "esnext",
-    "module": "nodenext",
-    "moduleResolution": "nodenext",
-    "lib": ["esnext"],
-    "types": ["node"],
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "verbatimModuleSyntax": true,
-    "allowImportingTsExtensions": true,
-    "noEmit": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src", "test"]
-}