@venn-lang/project 0.1.0

package/src/scaffold/scaffold.ts

@@ -0,0 +1,61 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: ${name} is Venn's own interpolation inside a generated file, not a JavaScript template.
+import { TARGET_DIR } from "../target/index.js";
+import type { ScaffoldFile, ScaffoldRequest } from "./scaffold.types.js";
+
+/**
+ * The files a new project starts as.
+ *
+ * Pure: it says what should exist and the caller writes it, so `--dry-run`, the
+ * tests and the disk all see one answer. What is generated is deliberately
+ * small, because a starting point that has to be deleted before it can be used
+ * is worse than one that is missing something.
+ *
+ * @returns The manifest, a source file for anything that is not a workspace,
+ * and a `.gitignore` unless a workspace above already owns one.
+ */
+export function scaffold(request: ScaffoldRequest): ScaffoldFile[] {
+  const files = [{ path: "venn.toml", content: manifestFor(request) }];
+  if (request.kind !== "workspace") files.push(sourceFor(request));
+  // One `target/` per workspace means one line ignoring it, at the root that
+  // owns it. A member repeating that would be ignoring something it has not got.
+  if (!request.insideWorkspace) files.push(ignoreFile());
+  return files;
+}
+
+/** A member leaves out what it inherits; writing it down would only shadow it. */
+function manifestFor(request: ScaffoldRequest): string {
+  if (request.kind === "workspace") return workspaceManifest();
+  const version = request.insideWorkspace ? [] : ['version = "0.1.0"'];
+  return ["[package]", `name = "${request.name}"`, ...version, "", "[dependencies]", ""].join("\n");
+}
+
+function workspaceManifest(): string {
+  return [
+    "[workspace]",
+    'members = ["packages/*"]',
+    "",
+    "# Metadata a member inherits by leaving it out.",
+    "[workspace.package]",
+    'version = "0.1.0"',
+    "",
+    "# Versions a member takes with `dep = { workspace = true }`.",
+    "[workspace.dependencies]",
+    "",
+  ].join("\n");
+}
+
+/** A library exports; a program runs. Each starts as the smallest of itself. */
+function sourceFor(request: ScaffoldRequest): ScaffoldFile {
+  if (request.kind === "lib") {
+    return {
+      path: "src/lib.vn",
+      content: ["pub fn greet(name: string) -> string {", '  "Hello, ${name}"', "}", ""].join("\n"),
+    };
+  }
+  return { path: "src/main.vn", content: `print "Hello from ${request.name}"\n` };
+}
+
+/** Everything derived lives in one directory, so ignoring it is one line. */
+function ignoreFile(): ScaffoldFile {
+  return { path: ".gitignore", content: `${TARGET_DIR}/\n` };
+}

package/src/scaffold/scaffold.types.ts

@@ -0,0 +1,23 @@
+/** What kind of thing is being started. */
+export type ScaffoldKind = "lib" | "bin" | "workspace";
+
+/** What to start, and what the surroundings already provide. */
+export interface ScaffoldRequest {
+  kind: ScaffoldKind;
+  /** The package name, which is also the directory when one is created. */
+  name: string;
+  /**
+   * Whether a workspace above will claim this package as a member.
+   *
+   * Changes what is written rather than only where: a member leaves out what it
+   * would inherit and carries no ignore file, because the root already owns the
+   * one `target/` there is.
+   */
+  insideWorkspace?: boolean;
+}
+
+/** One file to write, its path relative to the directory being started. */
+export interface ScaffoldFile {
+  path: string;
+  content: string;
+}

package/src/target/build-record.ts

@@ -0,0 +1,45 @@
+import type { FileSystem } from "@venn-lang/contracts";
+import { join } from "../paths/index.js";
+import { outputDir, type ProfileName } from "./layout.js";
+
+/** One target a build covered, and where it starts. */
+export interface BuiltTarget {
+  package: string;
+  kind: string;
+  name: string;
+  /** The entry file, relative to the workspace root. */
+  path: string;
+}
+
+/** What one build covered, and how it went. */
+export interface BuildRecord {
+  profile: ProfileName;
+  targets: readonly BuiltTarget[];
+  /** How many `.vn` files were read, and how many problems were found. */
+  files: number;
+  problems: number;
+}
+
+/** The record's name, inside the profile's output directory. */
+export const RECORD_FILE = "build.json";
+
+/**
+ * Writes what a build produced, where that build's outputs go.
+ *
+ * It answers "what does this project build, and did it hold together", and it
+ * is what an incremental build compares against once there is generated code to
+ * skip.
+ *
+ * @returns The path written.
+ * @throws Whatever the file system raises when the write fails.
+ */
+export async function writeBuildRecord(args: {
+  fs: FileSystem;
+  root: string;
+  record: BuildRecord;
+}): Promise<string> {
+  const path = join(outputDir({ root: args.root, profile: args.record.profile }), RECORD_FILE);
+  const text = `${JSON.stringify(args.record, null, 2)}\n`;
+  await args.fs.write(path, new TextEncoder().encode(text));
+  return path;
+}

package/src/target/index.ts

@@ -0,0 +1,15 @@
+export {
+  type BuildRecord,
+  type BuiltTarget,
+  RECORD_FILE,
+  writeBuildRecord,
+} from "./build-record.js";
+export {
+  modulesDir,
+  nativeModulesDir,
+  outputDir,
+  type ProfileName,
+  TARGET_DIR,
+  TARGET_LAYOUT,
+  targetDir,
+} from "./layout.js";

package/src/target/layout.ts

@@ -0,0 +1,50 @@
+import { join } from "../paths/index.js";
+
+/**
+ * Where everything a build produces or fetches goes.
+ *
+ * One directory at the workspace root holds every derived thing, the way
+ * Cargo's `target/` does, so deleting it costs time and nothing else.
+ *
+ * The dependencies live inside it, and that placement is load-bearing rather
+ * than tidiness: Node resolves a package by walking up from the importing file
+ * looking for `node_modules`, and built output sits in `target/debug` or
+ * `target/release`, one level below `target/node_modules`. The ordinary
+ * resolver finds them with no loader and no symlink. Moving the output out of
+ * `target/` breaks that quietly.
+ */
+export const TARGET_DIR = "target";
+
+/** The names inside `target/`. */
+export const TARGET_LAYOUT = {
+  /** What the package manager installs, and what Node's resolver will find. */
+  modules: "node_modules",
+  /** Compiled addons, kept apart because they are per-platform, not per-project. */
+  native: "native_modules",
+  /** Built output, one directory per profile. */
+  debug: "debug",
+  release: "release",
+} as const;
+
+/** Which build profile an output directory belongs to. */
+export type ProfileName = "debug" | "release";
+
+/** The `target/` of a project, given its root. */
+export function targetDir(root: string): string {
+  return join(root, TARGET_DIR);
+}
+
+/** Where the package manager installs, and where Node's resolver will look. */
+export function modulesDir(root: string): string {
+  return join(targetDir(root), TARGET_LAYOUT.modules);
+}
+
+/** Where compiled addons go, kept apart because they are per-platform. */
+export function nativeModulesDir(root: string): string {
+  return join(targetDir(root), TARGET_LAYOUT.native);
+}
+
+/** Where a build of this profile is written. */
+export function outputDir(args: { root: string; profile: ProfileName }): string {
+  return join(targetDir(args.root), TARGET_LAYOUT[args.profile]);
+}

package/src/workspace/index.ts

@@ -0,0 +1,2 @@
+export { inherit } from "./inherit.js";
+export { memberDirs } from "./member-dirs.js";

package/src/workspace/inherit.ts

@@ -0,0 +1,60 @@
+import type { Dependency, Manifest, PackageInfo } from "@venn-lang/contracts";
+
+/**
+ * A member manifest with what the workspace root supplies filled in.
+ *
+ * Two things are inherited and they work differently. `[workspace.package]` is
+ * a default: the member's own value wins wherever it wrote one. A dependency
+ * marked `{ workspace = true }` is a request, so the root's answer replaces
+ * whatever was there. Writing both a version and `workspace = true` is a
+ * contradiction, and the request is the deliberate half.
+ *
+ * @param args.from The workspace root's manifest. A root with no `[workspace]`
+ * table supplies nothing, and the member is returned untouched.
+ * @returns The merged manifest. The member's own `name` always survives.
+ */
+export function inherit(args: { manifest: Manifest; from: Manifest }): Manifest {
+  const shared = args.from.workspace;
+  if (!shared) return args.manifest;
+  const pkg = withDefaults(args.manifest.package, shared.package);
+  return {
+    ...args.manifest,
+    name: pkg.name,
+    version: pkg.version ?? args.manifest.version,
+    package: pkg,
+    dependencies: pinned(args.manifest.dependencies, shared.dependencies),
+    devDependencies: pinned(args.manifest.devDependencies, shared.dependencies),
+    ...settings(args.manifest, args.from),
+  };
+}
+
+/**
+ * The environments and path aliases a member gets from its root.
+ *
+ * A workspace almost always wants `[env.staging]` and `#shared` written once.
+ * The alternative, every member repeating every variable, drifts silently until
+ * two members disagree about a URL. A member that writes its own key wins, per
+ * key rather than per table.
+ */
+function settings(own: Manifest, root: Manifest): Pick<Manifest, "env" | "paths"> {
+  const env: Record<string, Record<string, string>> = { ...root.env };
+  for (const [name, vars] of Object.entries(own.env)) env[name] = { ...env[name], ...vars };
+  return { env, paths: { ...root.paths, ...own.paths } };
+}
+
+/** The member's own value wins; the root fills only what was left unsaid. */
+function withDefaults(own: PackageInfo, shared: Partial<PackageInfo>): PackageInfo {
+  const merged = { ...own };
+  for (const [key, value] of Object.entries(shared) as [keyof PackageInfo, never][]) {
+    if (merged[key] === undefined || merged[key] === "") merged[key] = value;
+  }
+  return { ...merged, name: own.name };
+}
+
+function pinned(deps: readonly Dependency[], shared: readonly Dependency[]): readonly Dependency[] {
+  return deps.map((dep) => {
+    if (!dep.fromWorkspace) return dep;
+    const found = shared.find((one) => one.name === dep.name);
+    return found ? { ...found, optional: dep.optional, fromWorkspace: true } : dep;
+  });
+}

package/src/workspace/member-dirs.ts

@@ -0,0 +1,34 @@
+import type { FileSystem, WorkspaceSettings } from "@venn-lang/contracts";
+import { expandMembers } from "../glob/index.js";
+import { isInside, join, normalise } from "../paths/index.js";
+
+/**
+ * The directories a workspace's members occupy, exclusions already applied.
+ *
+ * @returns The member directories, normalised. One holding no `venn.toml` is
+ * dropped rather than reported: a glob describes a shape, and `packages/*`
+ * catching a `dist` folder on the way past is the glob working, not the
+ * workspace being wrong.
+ */
+export async function memberDirs(args: {
+  fs: FileSystem;
+  root: string;
+  workspace: WorkspaceSettings;
+}): Promise<string[]> {
+  const matched = await expandMembers({
+    fs: args.fs,
+    root: args.root,
+    patterns: args.workspace.members,
+  });
+  const excluded = args.workspace.exclude.map((path) => normalise(join(args.root, path)));
+  const kept = matched.filter((dir) => !excluded.some((one) => isInside(dir, one)));
+  return withManifest(args.fs, kept);
+}
+
+async function withManifest(fs: FileSystem, dirs: readonly string[]): Promise<string[]> {
+  const found: string[] = [];
+  for (const dir of dirs) {
+    if (await fs.exists(join(dir, "venn.toml"))) found.push(normalise(dir));
+  }
+  return found;
+}