@venn-lang/cli 0.1.0

package/src/commands/check.ts

@@ -0,0 +1,143 @@
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createNodeHost } from "@venn-lang/contracts/node";
+import {
+  checkTypes,
+  type Document,
+  type FragmentDecl,
+  importedTypes,
+  isPackageSpecifier,
+  isValueImport,
+  type Problem,
+  parse,
+} from "@venn-lang/core";
+import {
+  buildRegistry,
+  checkDocument,
+  checkImports,
+  collectFragments,
+  createTypeCatalog,
+  resolveImports,
+} from "@venn-lang/runtime";
+import { allPlugins } from "@venn-lang/stdlib";
+import type { TypeSpec } from "@venn-lang/types";
+import { loadManifest } from "../manifest/index.js";
+import { reportProblems } from "../reporters/index.js";
+import { everySourceUnder } from "../run/collect-files.js";
+import { createNodeModuleIo } from "../run/node-io.js";
+import { loadDerivedTypes } from "../run/package-types.js";
+
+/**
+ * `venn check <file|folder>`: statically resolve actions, matchers, imports and
+ * types without running. A folder is walked.
+ *
+ * @returns 0 when nothing was found, 1 when problems were reported or the paths
+ * hold no `.vn` file.
+ */
+export async function checkCommand(args: { paths: readonly string[] }): Promise<number> {
+  const files = await everySourceUnder(args.paths);
+  if (files.length === 0) {
+    process.stderr.write(`No .vn files found at ${args.paths.join(", ")}\n`);
+    return 1;
+  }
+  // Gathered across every file and reported once: a project that checks clean
+  // should say so once, not once per file.
+  const found = await checkProblems(args.paths);
+  return found.problems.length > 0 ? report(found.problems) : ok(files.length);
+}
+
+/**
+ * The same walk without the printing, for whoever wants the answer rather than
+ * the report: `build` records the count, `check` prints the list.
+ */
+export async function checkProblems(
+  paths: readonly string[],
+): Promise<{ files: number; problems: Problem[] }> {
+  const files = await everySourceUnder(paths);
+  const problems: Problem[] = [];
+  for (const file of files) problems.push(...(await problemsIn(file)));
+  return { files: files.length, problems };
+}
+
+async function problemsIn(uri: string): Promise<Problem[]> {
+  const { ast, problems } = parse(await readFile(uri, "utf8"), { uri });
+  if (problems.length > 0) return problems;
+  const project = await loadManifest(uri);
+  const manifest = project?.manifest;
+  // Anchored where the manifest lives, not where the file does: a member of a
+  // workspace reads the aliases its root declared.
+  const io = createNodeModuleIo({
+    paths: manifest?.paths ?? {},
+    rootDir: project?.dir ?? dirname(uri),
+  });
+  const { fragments: imported, decos, modules } = await resolveImports({ document: ast, uri, io });
+  const registry = buildRegistry({ plugins: allPlugins, caps: createNodeHost().caps });
+  const found = checkDocument({
+    document: ast,
+    registry,
+    fragments: names(ast, imported),
+    env: declaredEnv(manifest),
+    uri,
+  });
+  const catalog = createTypeCatalog(allPlugins);
+  const graph = { modules, resolve: io.resolve };
+  // The imported names' types come from the files they were written in, so a
+  // wrong argument to an imported function is caught here rather than at run time.
+  const imports = importedTypes({
+    ...graph,
+    document: ast,
+    uri,
+    catalog,
+    packages: await packageTypesFor({ document: ast, root: project?.dir }),
+  });
+  return [
+    ...found,
+    ...checkImports({ document: ast, uri, graph }),
+    ...checkTypes(ast, { uri, catalog, decos, imports }).problems,
+  ];
+}
+
+/**
+ * The derived types of the packages this file imports.
+ *
+ * Read from `target/types/`, where the install wrote them. Absent means nobody
+ * has installed anything yet, so every imported name is `dynamic`, which is the
+ * truth about it rather than a failure.
+ */
+async function packageTypesFor(args: {
+  document: Document;
+  root?: string;
+}): Promise<Map<string, Record<string, TypeSpec>>> {
+  if (!args.root) return new Map();
+  const wanted = args.document.imports
+    .filter(isValueImport)
+    .map((decl) => decl.path)
+    .filter(isPackageSpecifier);
+  return wanted.length > 0 ? loadDerivedTypes({ root: args.root, packages: wanted }) : new Map();
+}
+
+/**
+ * Every variable any `[env.*]` section declares. Undefined without a manifest:
+ * with nothing to compare against, every `env.*` read would look undeclared.
+ */
+function declaredEnv(
+  manifest: { env: Record<string, Record<string, string>> } | undefined,
+): readonly string[] | undefined {
+  const sections = Object.values(manifest?.env ?? {});
+  return sections.length > 0 ? [...new Set(sections.flatMap(Object.keys))] : undefined;
+}
+
+function names(document: Document, imported: ReadonlyMap<string, FragmentDecl>): Set<string> {
+  return new Set([...collectFragments(document).keys(), ...imported.keys()]);
+}
+
+function report(problems: Problem[]): number {
+  reportProblems(problems);
+  return 1;
+}
+
+function ok(files: number): number {
+  const many = files === 1 ? "" : ` in ${files} files`;
+  process.stdout.write(`✓ no problems found${many}\n`);
+  return 0;
+}

package/src/commands/deps.ts

@@ -0,0 +1,228 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { addDependency, removeDependency } from "@venn-lang/contracts";
+import { createNodeFs, createNodeSpawn } from "@venn-lang/contracts/node";
+import {
+  describeDrift,
+  isSafeSpec,
+  join,
+  MANIFEST_FILE,
+  managerCommand,
+  type Package,
+  type Project,
+  type ProxiedVerb,
+  packageJsonFor,
+  readLockfile,
+  targetDir,
+  verifyLock,
+  writeLockfile,
+} from "@venn-lang/project";
+import { selectPackages, unknownPackage } from "../project/index.js";
+import { deriveTypes } from "../run/package-types.js";
+
+export interface DepsArgs {
+  verb: ProxiedVerb;
+  /** `--frozen`: install, then refuse anything the lock did not record. */
+  frozen?: boolean;
+  /** Specs such as `zod`, `zod@^4` or `@types/node`, passed through untouched. */
+  packages: readonly string[];
+  dev?: boolean;
+  packageName?: string;
+}
+
+/**
+ * `venn add · remove · update · install`: the four verbs, run underneath by
+ * whichever package manager `[tooling]` names.
+ *
+ * The manifest is edited first and the manager is run second, against a
+ * `package.json` generated into `target/`. That ordering is what makes
+ * `venn.toml` the source rather than a copy: whatever the tool decides, the
+ * file a person reads was written from what they asked for.
+ */
+export async function depsCommand(args: DepsArgs): Promise<number> {
+  const selection = await selectPackages({ from: process.cwd(), packageName: args.packageName });
+  if (!selection) {
+    process.stderr.write("VN2101 · no venn.toml here, or in any folder above it.\n");
+    return 1;
+  }
+  if (args.packageName && selection.packages.length === 0) {
+    process.stderr.write(unknownPackage(selection.project, args.packageName));
+    return 1;
+  }
+  const unsafe = args.packages.filter((spec) => !isSafeSpec(spec));
+  if (unsafe.length > 0) {
+    process.stderr.write(`VN2105 · not a package name: ${unsafe.join(", ")}\n`);
+    return 1;
+  }
+  const target = selection.packages[0] ?? holder(selection.project);
+  if (!target) {
+    process.stderr.write("VN2104 · no package here to add a dependency to.\n");
+    return 1;
+  }
+  await editManifest({ ...args, dir: target.dir });
+  // Read again: the manifest just changed, and the project in hand was read
+  // before it did, so installing from that one would install what the file
+  // asked for before the command ran.
+  const after = await selectPackages({ from: process.cwd() });
+  if (!after) return 1;
+  const code = await install(after.project, args.frozen === true);
+  if (code !== 0) return code;
+  await pinResolved({ ...args, dir: target.dir, root: after.project.root });
+  return 0;
+}
+
+/**
+ * Write back the version that was actually resolved.
+ *
+ * `venn add zod` asks for whatever is newest, and a manifest left reading
+ * `zod = "latest"` pins nothing a reader can act on. `^` because asking for the
+ * newest means this version and the compatible ones after it.
+ */
+async function pinResolved(args: DepsArgs & { dir: string; root: string }): Promise<void> {
+  const asked = args.packages.filter((spec) => spec.indexOf("@", 1) < 0);
+  if (args.verb !== "add" || asked.length === 0) return;
+  const lock = await readLockfile({ fs: createNodeFs(), root: args.root });
+  const path = join(args.dir, MANIFEST_FILE);
+  let text = await readFile(path, "utf8");
+  for (const name of asked) {
+    const found = lock?.packages.find((one) => one.name === name);
+    if (found) {
+      text = addDependency({
+        text,
+        name,
+        version: `^${found.version}`,
+        table: args.dev ? "dev-dependencies" : undefined,
+      });
+    }
+  }
+  await writeFile(path, text, "utf8");
+}
+
+/**
+ * What is installed, against what the lock recorded.
+ *
+ * A lock nobody checks is decoration. Verifying it turns "the registry answered
+ * differently today" into something a build refuses to start with, rather than
+ * something found in production.
+ */
+async function checkAgainstLock(root: string): Promise<number> {
+  const fs = createNodeFs();
+  const lock = await readLockfile({ fs, root });
+  if (!lock) {
+    process.stderr.write("VN2106 · --frozen, but there is no venn.lock to check against.\n");
+    return 1;
+  }
+  const drift = await verifyLock({ fs, root, lock });
+  if (drift.length === 0) return 0;
+  const lines = describeDrift(drift);
+  process.stderr.write(`VN2107 · what is installed is not what the lock says.\n${lines}\n`);
+  return 1;
+}
+
+/** A workspace root that is not itself a package cannot hold a dependency. */
+function holder(project: Project): Package | undefined {
+  return project.packages.find((one) => one.dir === project.root);
+}
+
+/**
+ * The manifest, rewritten where it stands.
+ *
+ * `update` and `install` change nothing here: they are about what is on disk,
+ * not about what was asked for.
+ */
+async function editManifest(args: DepsArgs & { dir: string }): Promise<void> {
+  if (args.verb === "update" || args.verb === "install") return;
+  const path = join(args.dir, MANIFEST_FILE);
+  let text = await readFile(path, "utf8");
+  const table = args.dev ? "dev-dependencies" : undefined;
+  for (const spec of args.packages) {
+    const { name, version } = split(spec);
+    text =
+      args.verb === "add"
+        ? addDependency({ text, name, version, table })
+        : removeDependency({ text, name, table });
+  }
+  await writeFile(path, text, "utf8");
+}
+
+/**
+ * `zod@^4`: the name, and what was asked for.
+ *
+ * A scope starts with `@` and is not a version, so the separator is looked for
+ * after the first character.
+ */
+function split(spec: string): { name: string; version: string } {
+  const at = spec.indexOf("@", 1);
+  if (at < 0) return { name: spec, version: "latest" };
+  return { name: spec.slice(0, at), version: spec.slice(at + 1) };
+}
+
+/**
+ * Generate the `package.json` the manager reads, run it there, and record what
+ * came out. The manager writes `node_modules` beside the file it was pointed
+ * at, so pointing it at `target/` puts them where Node will look for them.
+ */
+async function install(project: Project, frozen: boolean): Promise<number> {
+  const fs = createNodeFs();
+  const dir = targetDir(project.root);
+  const members = project.packages.map((one) => one.manifest);
+  const json = packageJsonFor({ manifest: project.rootManifest, members });
+  await fs.write(join(dir, "package.json"), new TextEncoder().encode(json));
+  const code = await run({ manager: project.rootManifest.tooling.manager, dir });
+  if (code !== 0) return code;
+  // Under `--frozen` the lock is the input, not the output: writing it first
+  // and then checking against what was just written is a check that cannot fail.
+  if (frozen) return checkAgainstLock(project.root);
+  const lock = await writeLockfile({
+    fs,
+    root: project.root,
+    manager: project.rootManifest.tooling.manager,
+  });
+  process.stdout.write(`locked ${lock.packages.length} package(s)\n`);
+  await reportTypes(project.root, asked(project));
+  return 0;
+}
+
+/** The packages the project asked for by name, not everything that came with them. */
+function asked(project: Project): string[] {
+  const all = project.packages.flatMap((one) => [
+    ...one.manifest.dependencies,
+    ...one.manifest.devDependencies,
+  ]);
+  return [...new Set(all.filter((dep) => dep.path === undefined).map((dep) => dep.name))];
+}
+
+/**
+ * Derive the types each package publishes, and say how much came across.
+ *
+ * A measured number rather than a claim: "94% of exports typed" can be checked
+ * and driven up, where "fully compatible" would be false for any package built
+ * on conditional types.
+ */
+async function reportTypes(root: string, packages: readonly string[]): Promise<void> {
+  if (packages.length === 0) return;
+  const found = await deriveTypes({ root, packages });
+  for (const one of found) {
+    const pct = one.total === 0 ? 0 : Math.round((one.typed / one.total) * 100);
+    const detail = one.total === 0 ? "no types published" : `${pct}% of ${one.total} exports typed`;
+    process.stdout.write(`  ${one.name}: ${detail}
+`);
+  }
+}
+
+async function run(args: { manager: string; dir: string }): Promise<number> {
+  const spec = managerCommand({
+    manager: args.manager as never,
+    verb: "install",
+    platform: process.platform,
+  });
+  const handle = createNodeSpawn().spawn({
+    command: spec.command,
+    args: spec.args,
+    cwd: args.dir,
+    shell: spec.shell,
+    onOutput: (chunk) => process.stdout.write(chunk),
+  });
+  const result = await handle.wait();
+  if (result.code !== 0) process.stderr.write(`\n${args.manager} exited with ${result.code}\n`);
+  return result.code;
+}

package/src/commands/fmt.ts

@@ -0,0 +1,55 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { formatOptionsFrom, formatText } from "@venn-lang/core";
+import { loadManifest } from "../manifest/index.js";
+import { dim, green, yellow } from "../reporters/colors.js";
+import { everySourceUnder } from "../run/collect-files.js";
+
+/** Everything `venn fmt` accepts. */
+export interface FmtOptions {
+  paths: readonly string[];
+  check?: boolean;
+}
+
+/**
+ * `venn fmt <file|folder>`: format in place, or with `--check` report what would
+ * change and fail, which is what CI wants.
+ *
+ * @returns 0 when nothing needs changing, 1 under `--check` when a file would
+ * change or when the paths hold no `.vn` file.
+ */
+export async function fmtCommand(options: FmtOptions): Promise<number> {
+  const files = await everySourceUnder(options.paths);
+  if (files.length === 0) {
+    process.stderr.write(`No .vn files found at ${options.paths.join(", ")}\n`);
+    return 1;
+  }
+  const changed: string[] = [];
+  for (const file of files) {
+    if (await reformat(file, options.check === true)) changed.push(file);
+  }
+  return report(changed, files.length, options.check === true);
+}
+
+async function reformat(file: string, check: boolean): Promise<boolean> {
+  const source = await readFile(file, "utf8");
+  const found = await loadManifest(file);
+  const formatted = formatText(source, formatOptionsFrom(found?.manifest.format));
+  if (formatted === source) return false;
+  if (!check) await writeFile(file, formatted, "utf8");
+  return true;
+}
+
+function report(changed: readonly string[], total: number, check: boolean): number {
+  for (const file of changed) {
+    process.stdout.write(`  ${check ? yellow("~") : green("✓")} ${shorten(file)}\n`);
+  }
+  const verb = check ? "would change" : "formatted";
+  process.stdout.write(`\n ${dim(verb)}  ${changed.length}/${total}\n`);
+  return check && changed.length > 0 ? 1 : 0;
+}
+
+function shorten(file: string): string {
+  const path = relative(process.cwd(), file);
+  return path && !path.startsWith("..") ? path.replace(/\\/g, "/") : file;
+}

package/src/commands/index.ts

@@ -0,0 +1,2 @@
+export { runCommand } from "./run.js";
+export { verifyPluginCommand } from "./verify-plugin.js";

package/src/commands/inside-workspace.ts

@@ -0,0 +1,20 @@
+import { createNodeFs } from "@venn-lang/contracts/node";
+import { ancestors, matchesMember, readManifest, relativeTo } from "@venn-lang/project";
+
+/**
+ * Whether a workspace above this path will claim it as a member.
+ *
+ * Asked before the directory exists, so the member globs are matched as text
+ * rather than expanded against the disk. The nearest workspace answers: a root
+ * whose `members` do not name this path is not this path's root, and creating a
+ * package it will not pick up should not produce a manifest that waits on it.
+ */
+export async function insideWorkspace(dir: string): Promise<boolean> {
+  const fs = createNodeFs();
+  for (const above of ancestors(dir).slice(1)) {
+    const manifest = await readManifest({ fs, dir: above });
+    if (!manifest?.workspace) continue;
+    return matchesMember({ path: relativeTo(dir, above), patterns: manifest.workspace.members });
+  }
+  return false;
+}

package/src/commands/list.ts

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { type Document, type FlowDecl, isFlowDecl, parse } from "@venn-lang/core";
+import { matchesTitle } from "@venn-lang/runtime";
+import { bold, cyan, dim } from "../reporters/colors.js";
+import { collectSourceFiles } from "../run/collect-files.js";
+import { stepTitlesOf } from "../run/step-titles.js";
+
+/** Everything `venn list` accepts. */
+export interface ListOptions {
+  file: string;
+  flow?: string;
+  step?: string;
+}
+
+/**
+ * `venn list <file|directory>`: what would run, without running it.
+ *
+ * @returns 0, or 1 when the path holds no `.vn` file.
+ */
+export async function listCommand(options: ListOptions): Promise<number> {
+  const files = await collectSourceFiles(resolve(options.file));
+  if (files.length === 0) {
+    process.stderr.write(`No .vn files found at ${options.file}\n`);
+    return 1;
+  }
+  for (const file of files) await listFile(file, options);
+  return 0;
+}
+
+async function listFile(file: string, options: ListOptions): Promise<void> {
+  const { ast } = parse(await readFile(file, "utf8"), { uri: file });
+  const flows = ast.decls.filter(isFlowDecl).filter((f) => matchesTitle(f.title, options.flow));
+  if (flows.length === 0) return;
+  write(`\n${cyan(shorten(file))}`);
+  for (const flow of flows) writeFlow(flow, ast, options.step);
+}
+
+function writeFlow(flow: FlowDecl, document: Document, step: string | undefined): void {
+  write(`  ${dim("❯")} ${bold(flow.title)}`);
+  for (const title of stepTitlesOf(flow, document)) {
+    if (matchesTitle(title, step)) write(`    ${dim("•")} ${title}`);
+  }
+}
+
+function shorten(file: string): string {
+  const path = relative(process.cwd(), file);
+  return path && !path.startsWith("..") ? path.replace(/\\/g, "/") : file;
+}
+
+function write(text: string): void {
+  process.stdout.write(`${text}\n`);
+}

package/src/commands/new.ts

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { createNodeFs } from "@venn-lang/contracts/node";
+import {
+  MANIFEST_FILE,
+  normalise,
+  type ScaffoldFile,
+  type ScaffoldKind,
+  scaffold,
+} from "@venn-lang/project";
+import { insideWorkspace } from "./inside-workspace.js";
+
+export interface NewArgs {
+  /** Where the project goes. For `init` this is the directory it is run in. */
+  dir: string;
+  name: string;
+  kind: ScaffoldKind;
+  /** Print what would be written and write nothing. */
+  dryRun?: boolean;
+}
+
+/**
+ * `venn new <name>` and `venn init`: start a project.
+ *
+ * Refuses to write over a manifest that is already there. Starting a project on
+ * top of one that exists is never what was meant, and the cost of being wrong
+ * about that is somebody's work.
+ */
+export async function newCommand(args: NewArgs): Promise<number> {
+  // Rooted at the directory being created, so every path below is relative to
+  // it. The file system joins its root onto what it is given, so an absolute
+  // path would write one path inside another.
+  const dir = normalise(resolve(args.dir));
+  const fs = createNodeFs({ root: dir });
+  if (await fs.exists(MANIFEST_FILE)) {
+    process.stderr.write(`VN2102 · there is already a ${MANIFEST_FILE} in ${dir}\n`);
+    return 1;
+  }
+  const files = scaffold({
+    kind: args.kind,
+    name: args.name,
+    insideWorkspace: args.kind === "workspace" ? false : await insideWorkspace(dir),
+  });
+  if (args.dryRun) return describe(files, dir);
+  const encoder = new TextEncoder();
+  for (const file of files) await fs.write(file.path, encoder.encode(file.content));
+  return announce(args, dir, files);
+}
+
+function describe(files: readonly ScaffoldFile[], dir: string): number {
+  process.stdout.write(`would write into ${dir}:\n`);
+  for (const file of files) process.stdout.write(`  ${file.path}\n`);
+  return 0;
+}
+
+const NEXT: Record<ScaffoldKind, string> = {
+  lib: "write src/lib.vn, and `pub` what others should reach",
+  bin: "venn run src/main.vn",
+  workspace: "venn new packages/api --bin",
+};
+
+function announce(args: NewArgs, dir: string, files: readonly ScaffoldFile[]): number {
+  process.stdout.write(`created ${args.kind} ${args.name} in ${dir}\n`);
+  for (const file of files) process.stdout.write(`  ${file.path}\n`);
+  process.stdout.write(`\nnext:  ${NEXT[args.kind]}\n`);
+  return 0;
+}