@venn-lang/contracts 0.1.0

package/src/ports/manifest-provider/edit/edit-dependency.ts

@@ -0,0 +1,82 @@
+import { keyOf, tableSpan } from "./table-span.js";
+
+/** What to change, and in which table. */
+export interface DependencyEdit {
+  /** The manifest as written. */
+  text: string;
+  name: string;
+  /** Defaults to {@link DEPENDENCIES}. Pass `"dev-dependencies"` for the other. */
+  table?: string;
+}
+
+/** The table an edit touches unless told otherwise. */
+export const DEPENDENCIES = "dependencies";
+
+/**
+ * The manifest with one dependency written in, everything else untouched.
+ *
+ * Entries are kept in name order, so two people adding two packages produce two
+ * one-line diffs rather than a conflict. A name already there is replaced where
+ * it stands, because an upgrade should not move the line.
+ *
+ * @returns the whole manifest as text. A missing table is appended at the end.
+ */
+export function addDependency(args: DependencyEdit & { version: string }): string {
+  const table = args.table ?? DEPENDENCIES;
+  const lines = args.text.split("\n");
+  const entry = `${args.name} = "${args.version}"`;
+  const span = tableSpan(lines, table);
+  if (!span) return appended(args.text, table, entry);
+  const at = lines.findIndex((line, index) => inside(span, index) && keyOf(line) === args.name);
+  if (at >= 0) return replaced(lines, at, entry);
+  return replaced(lines, insertionPoint(lines, span, args.name), entry, "insert");
+}
+
+/**
+ * The manifest without that dependency.
+ *
+ * @returns the text unchanged when the name is not there: absent is already the
+ * wanted state.
+ */
+export function removeDependency(args: DependencyEdit): string {
+  const table = args.table ?? DEPENDENCIES;
+  const lines = args.text.split("\n");
+  const span = tableSpan(lines, table);
+  if (!span) return args.text;
+  const at = lines.findIndex((line, index) => inside(span, index) && keyOf(line) === args.name);
+  if (at < 0) return args.text;
+  return [...lines.slice(0, at), ...lines.slice(at + 1)].join("\n");
+}
+
+function inside(span: { from: number; to: number }, index: number): boolean {
+  return index >= span.from && index < span.to;
+}
+
+/** Where the name belongs, in order, among the entries already there. */
+function insertionPoint(
+  lines: readonly string[],
+  span: { from: number; to: number },
+  name: string,
+): number {
+  for (let at = span.from; at < span.to; at++) {
+    const key = keyOf(lines[at] ?? "");
+    if (key && key > name) return at;
+  }
+  return span.to;
+}
+
+function replaced(
+  lines: readonly string[],
+  at: number,
+  entry: string,
+  how: "replace" | "insert" = "replace",
+): string {
+  const after = how === "insert" ? lines.slice(at) : lines.slice(at + 1);
+  return [...lines.slice(0, at), entry, ...after].join("\n");
+}
+
+/** A table the manifest does not have yet, written at the end where it reads. */
+function appended(text: string, table: string, entry: string): string {
+  const body = text.endsWith("\n") ? text : `${text}\n`;
+  return `${body}\n[${table}]\n${entry}\n`;
+}

package/src/ports/manifest-provider/edit/index.ts

@@ -0,0 +1,7 @@
+export {
+  addDependency,
+  DEPENDENCIES,
+  type DependencyEdit,
+  removeDependency,
+} from "./edit-dependency.js";
+export { keyOf, type TableSpan, tableSpan } from "./table-span.js";

package/src/ports/manifest-provider/edit/table-span.ts

@@ -0,0 +1,39 @@
+/** Where a table's entries live in a manifest's lines. */
+export interface TableSpan {
+  /** The line holding `[name]`. */
+  header: number;
+  /** First line after the header, and the line after the table's last entry. */
+  from: number;
+  to: number;
+}
+
+/**
+ * Where a `[table]` is written, or undefined when the file has none.
+ *
+ * Found by reading lines rather than by re-serialising the parse tree. A
+ * manifest carries its author's comments, blank lines and chosen order, and
+ * rebuilding it from a tree would throw all of that away.
+ */
+export function tableSpan(lines: readonly string[], name: string): TableSpan | undefined {
+  const header = lines.findIndex((line) => line.trim() === `[${name}]`);
+  if (header < 0) return undefined;
+  let to = header + 1;
+  for (let at = header + 1; at < lines.length; at++) {
+    if (lines[at]?.trimStart().startsWith("[")) break;
+    if (lines[at]?.trim() !== "") to = at + 1;
+  }
+  return { header, from: header + 1, to };
+}
+
+/** The key a `key = value` line writes, or undefined for a comment or a blank. */
+export function keyOf(line: string): string | undefined {
+  const text = line.trim();
+  if (text === "" || text.startsWith("#") || text.startsWith("[")) return undefined;
+  const equals = text.indexOf("=");
+  return equals < 0
+    ? undefined
+    : text
+        .slice(0, equals)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+}

package/src/ports/manifest-provider/index.ts

@@ -0,0 +1,31 @@
+export { defaultManifest } from "./default-manifest.js";
+export {
+  addDependency,
+  DEPENDENCIES,
+  type DependencyEdit,
+  removeDependency,
+} from "./edit/index.js";
+export { ManifestProviderPort } from "./manifest.port.js";
+export type { FormatSettings, Manifest, ManifestProvider } from "./manifest.types.js";
+export { createMemoryManifest } from "./memory-manifest.js";
+export type {
+  BuildTarget,
+  Dependency,
+  PackageInfo,
+  PackageManagerName,
+  Profile,
+  TargetKind,
+  ToolingSettings,
+  WorkspaceSettings,
+} from "./project.types.js";
+export {
+  BIN_DIR,
+  DEFAULT_PROFILES,
+  LIB_ROOT,
+  MAIN_ROOT,
+  readInheritable,
+} from "./read/index.js";
+export { type AliasTarget, resolveAlias } from "./resolve-alias.js";
+export { parseToml } from "./toml/index.js";
+export { tomlDocs } from "./toml-docs.js";
+export { createTomlManifest } from "./toml-manifest.js";

package/src/ports/manifest-provider/manifest.port.ts

@@ -0,0 +1,16 @@
+import type { Port } from "../../port/index.js";
+import type { ManifestProvider } from "./manifest.types.js";
+
+/**
+ * The {@link ManifestProvider} contract. Implementations: `toml-manifest`,
+ * `memory-manifest`.
+ *
+ * Requires nothing: reading the file is the caller's job, and what arrives here
+ * is already text.
+ */
+export const ManifestProviderPort: Port<ManifestProvider> = {
+  id: "venn.port.manifest",
+  version: 1,
+  requires: [],
+  methods: ["load"],
+};

package/src/ports/manifest-provider/manifest.types.ts

@@ -0,0 +1,54 @@
+import type {
+  BuildTarget,
+  Dependency,
+  PackageInfo,
+  Profile,
+  ToolingSettings,
+  WorkspaceSettings,
+} from "./project.types.js";
+
+/** A parsed `venn.toml`: the project manifest the LSP and the runner read. */
+export interface Manifest {
+  name: string;
+  version: string;
+  /** `[package]` in full. `name` and `version` above are the short way in. */
+  package: PackageInfo;
+  /** `[lib]` and `[[bin]]`, in the order they were written. */
+  targets: readonly BuildTarget[];
+  dependencies: readonly Dependency[];
+  devDependencies: readonly Dependency[];
+  /** `[patch]`: a version this project insists on, wherever it is asked for. */
+  patch: readonly Dependency[];
+  /** `[profile.<name>]`, keyed by name. `dev` and `release` are built in. */
+  profiles: Record<string, Profile>;
+  tooling: ToolingSettings;
+  /** `[workspace]`, or absent when this manifest is a plain package. */
+  workspace?: WorkspaceSettings;
+  /** `[env.<name>]` sections, mapping an environment to its variables. */
+  env: Record<string, Record<string, string>>;
+  /**
+   * `[env] files`: which dotenv files to read, in order, later winning.
+   * `${name}` stands for the selected environment. Empty means the convention.
+   */
+  envFiles: readonly string[];
+  /** `[paths]`, mapping an `#alias` to a directory. */
+  paths: Record<string, string>;
+  /** `[format]`: how `venn fmt` and the editor format this project. */
+  format: FormatSettings;
+}
+
+/** The `[format]` table. Absent keys fall back to the language defaults. */
+export interface FormatSettings {
+  indent?: number;
+  tabs?: boolean;
+  organize?: boolean;
+  sort?: boolean;
+}
+
+/**
+ * Produces a {@link Manifest}. Implementations: `toml-manifest` parses one,
+ * `memory-manifest` returns a preset.
+ */
+export interface ManifestProvider {
+  load(): Manifest;
+}

package/src/ports/manifest-provider/memory-manifest.ts

@@ -0,0 +1,14 @@
+import { defaultManifest } from "./default-manifest.js";
+import type { Manifest, ManifestProvider } from "./manifest.types.js";
+
+/**
+ * The double: a preset manifest, with no file involved.
+ *
+ * Takes only what the caller cares about. The rest is what a project that
+ * declared nothing would get, which is exactly what the real provider gives a
+ * `venn.toml` silent on those tables.
+ */
+export function createMemoryManifest(args: { manifest: Partial<Manifest> }): ManifestProvider {
+  const manifest: Manifest = defaultManifest(args.manifest);
+  return { load: () => manifest };
+}

package/src/ports/manifest-provider/project.types.ts

@@ -0,0 +1,94 @@
+/**
+ * What a manifest declares about the project itself, as against how it runs.
+ *
+ * The shape follows Cargo's, because the questions are the same and an answer
+ * the reader already knows beats a better one they must learn. Where Cargo has
+ * something this does not, the gap is noted so it reads as a decision.
+ */
+
+/** `[package]`: who this is. */
+export interface PackageInfo {
+  name: string;
+  /**
+   * What `[package] version` said, and nothing when it said nothing.
+   *
+   * Optional so "not written" stays distinguishable from "written as 0.0.0": a
+   * workspace member inherits the first and keeps the second. `Manifest.version`
+   * is the resolved value, with the default already applied.
+   */
+  version?: string;
+  description?: string;
+  license?: string;
+  authors: readonly string[];
+  /** `[package] edition`: which language revision this was written against. */
+  edition?: string;
+}
+
+/** What a project builds. A server is a `bin` that does not end. */
+export type TargetKind = "lib" | "bin" | "test";
+
+/** `[lib]` or one entry of `[[bin]]`: a thing to build, and where it starts. */
+export interface BuildTarget {
+  kind: TargetKind;
+  /** The name it is known by; a `bin`'s name is what `venn run --bin` takes. */
+  name: string;
+  /** The `.vn` file this target starts from, relative to the manifest. */
+  path: string;
+}
+
+/** One entry of `[dependencies]` / `[dev-dependencies]`. */
+export interface Dependency {
+  name: string;
+  /** A semver range, or absent when the version comes from elsewhere. */
+  version?: string;
+  /** `{ path = "../other" }`: a sibling in this workspace or on disk. */
+  path?: string;
+  /** `{ workspace = true }`: take the version the workspace pinned. */
+  fromWorkspace: boolean;
+  /** `{ optional = true }`: resolved and locked, installed only on demand. */
+  optional: boolean;
+}
+
+/**
+ * `[profile.dev]` and `[profile.release]`: how a build is made.
+ *
+ * One key, because one key is what a build does today. Settings about generated
+ * code, such as `sourceMap` and `minify`, arrive with the compiler: declaring
+ * them now would read as a contract and honour nothing.
+ */
+export interface Profile {
+  /** Whether a problem stops the build instead of only being reported. */
+  strict?: boolean;
+}
+
+/**
+ * Which package manager runs underneath `venn add` and `venn remove`.
+ *
+ * The interface is ours, the resolution is not: resolving versions well is
+ * years of work against three moving targets.
+ */
+export type PackageManagerName = "pnpm" | "npm" | "bun" | "yarn";
+
+/** The `[tooling]` table. */
+export interface ToolingSettings {
+  manager: PackageManagerName;
+}
+
+/**
+ * `[workspace]`: a root that owns members, one lockfile and one `target/`.
+ *
+ * `[features]` is deliberately absent. It is the most intricate part of Cargo,
+ * it rests on conditional compilation this language does not have, and half of
+ * it would be worse than none.
+ */
+export interface WorkspaceSettings {
+  /** Path globs naming the members, e.g. `["packages/*"]`. */
+  members: readonly string[];
+  exclude: readonly string[];
+  /** Which members a command with no target acts on. Empty means all of them. */
+  defaultMembers: readonly string[];
+  /** `[workspace.package]`: metadata a member may inherit. */
+  package: Partial<PackageInfo>;
+  /** `[workspace.dependencies]`: the versions `{ workspace = true }` takes. */
+  dependencies: readonly Dependency[];
+}

package/src/ports/manifest-provider/read/index.ts

@@ -0,0 +1,15 @@
+export { readDependencies } from "./read-dependencies.js";
+export { readInheritable, readPackage } from "./read-package.js";
+export { DEFAULT_PROFILES, readProfiles } from "./read-profiles.js";
+export { BIN_DIR, LIB_ROOT, MAIN_ROOT, readTargets } from "./read-targets.js";
+export { readTooling } from "./read-tooling.js";
+export { readWorkspace } from "./read-workspace.js";
+export {
+  asBoolean,
+  asList,
+  asNumber,
+  asRecord,
+  asRecords,
+  asString,
+  asStringMap,
+} from "./scalars.js";

package/src/ports/manifest-provider/read/read-dependencies.ts

@@ -0,0 +1,27 @@
+import type { Dependency } from "../project.types.js";
+import { asBoolean, asRecord, asString } from "./scalars.js";
+
+/**
+ * A dependency table, in either spelling TOML allows.
+ *
+ * `zod = "^4"` and `zod = { version = "^4", optional = true }` say the same
+ * thing about the version, so both read into one shape rather than two the rest
+ * of the code would have to keep apart.
+ */
+export function readDependencies(value: unknown): Dependency[] {
+  return Object.entries(asRecord(value)).map(([name, spec]) => readOne(name, spec));
+}
+
+function readOne(name: string, spec: unknown): Dependency {
+  if (typeof spec === "string") {
+    return { name, version: spec, fromWorkspace: false, optional: false };
+  }
+  const table = asRecord(spec);
+  return {
+    name,
+    version: asString(table.version),
+    path: asString(table.path),
+    fromWorkspace: asBoolean(table.workspace) ?? false,
+    optional: asBoolean(table.optional) ?? false,
+  };
+}

package/src/ports/manifest-provider/read/read-package.ts

@@ -0,0 +1,32 @@
+import type { PackageInfo } from "../project.types.js";
+import { asList, asRecord, asString } from "./scalars.js";
+
+/** `[package]`: who this is. A missing table reads as a nameless package. */
+export function readPackage(data: Record<string, unknown>): PackageInfo {
+  const table = asRecord(data.package);
+  return {
+    name: String(table.name ?? ""),
+    version: asString(table.version),
+    description: asString(table.description),
+    license: asString(table.license),
+    authors: asList(table.authors),
+    edition: asString(table.edition),
+  };
+}
+
+/**
+ * The same table, reduced to what a member may inherit from its workspace.
+ *
+ * A name is never inherited, being the one thing that must differ between two
+ * members, so `[workspace.package]` carrying one is read as carrying none.
+ */
+export function readInheritable(data: Record<string, unknown>): Partial<PackageInfo> {
+  const table = asRecord(data);
+  const found: Partial<PackageInfo> = {};
+  for (const key of ["version", "description", "license", "edition"] as const) {
+    const value = asString(table[key]);
+    if (value !== undefined) found[key] = value;
+  }
+  const authors = asList(table.authors);
+  return authors.length > 0 ? { ...found, authors } : found;
+}

package/src/ports/manifest-provider/read/read-profiles.ts

@@ -0,0 +1,32 @@
+import type { Profile } from "../project.types.js";
+import { asBoolean, asRecord } from "./scalars.js";
+
+/**
+ * What each build is for, and what that costs.
+ *
+ * `dev` reports what it finds and carries on, because a project being worked on
+ * is half-written most of the time. `release` refuses to build over a problem.
+ * Neither has to be written in a manifest for the defaults to apply.
+ */
+export const DEFAULT_PROFILES: Readonly<Record<string, Profile>> = {
+  dev: { strict: false },
+  release: { strict: true },
+};
+
+/** `[profile.<name>]`, merged over {@link DEFAULT_PROFILES}. */
+export function readProfiles(data: Record<string, unknown>): Record<string, Profile> {
+  const out: Record<string, Profile> = { ...DEFAULT_PROFILES };
+  for (const [name, table] of Object.entries(asRecord(data.profile))) {
+    out[name] = { ...out[name], ...readProfile(asRecord(table)) };
+  }
+  return out;
+}
+
+function readProfile(table: Record<string, unknown>): Profile {
+  const found: Profile = {};
+  for (const key of ["strict"] as const) {
+    const value = asBoolean(table[key]);
+    if (value !== undefined) found[key] = value;
+  }
+  return found;
+}

package/src/ports/manifest-provider/read/read-targets.ts

@@ -0,0 +1,37 @@
+import type { BuildTarget } from "../project.types.js";
+import { asRecord, asRecords, asString } from "./scalars.js";
+
+/** Where a `lib` target starts when the manifest does not say. */
+export const LIB_ROOT = "src/lib.vn";
+/** Where the default `bin` target starts when the manifest does not say. */
+export const MAIN_ROOT = "src/main.vn";
+/** Where additional `bin` targets are looked for by convention. */
+export const BIN_DIR = "src/bin";
+
+/**
+ * `[lib]` and `[[bin]]`: what this package builds.
+ *
+ * Only what the manifest *declares*. The conventional roots are filled in by
+ * whoever can look at the disk, because a convention is a claim about files
+ * existing and this reader is pure. A manifest declaring nothing is the common
+ * case, not an empty one.
+ */
+export function readTargets(data: Record<string, unknown>, packageName: string): BuildTarget[] {
+  const found: BuildTarget[] = [];
+  if (data.lib !== undefined) found.push(readLib(asRecord(data.lib), packageName));
+  for (const entry of asRecords(data.bin)) found.push(readBin(entry, packageName));
+  return found;
+}
+
+function readLib(table: Record<string, unknown>, packageName: string): BuildTarget {
+  return {
+    kind: "lib",
+    name: asString(table.name) ?? packageName,
+    path: asString(table.path) ?? LIB_ROOT,
+  };
+}
+
+function readBin(table: Record<string, unknown>, packageName: string): BuildTarget {
+  const name = asString(table.name) ?? packageName;
+  return { kind: "bin", name, path: asString(table.path) ?? `${BIN_DIR}/${name}.vn` };
+}

package/src/ports/manifest-provider/read/read-tooling.ts

@@ -0,0 +1,15 @@
+import type { PackageManagerName, ToolingSettings } from "../project.types.js";
+import { asRecord, asString } from "./scalars.js";
+
+const MANAGERS = new Set<string>(["pnpm", "npm", "bun", "yarn"]);
+
+/**
+ * `[tooling]`: which package manager runs underneath.
+ *
+ * An unrecognised name falls back to pnpm rather than failing, so a manifest
+ * written against a newer toolchain still opens.
+ */
+export function readTooling(data: Record<string, unknown>): ToolingSettings {
+  const name = asString(asRecord(data.tooling).manager);
+  return { manager: name && MANAGERS.has(name) ? (name as PackageManagerName) : "pnpm" };
+}

package/src/ports/manifest-provider/read/read-workspace.ts

@@ -0,0 +1,22 @@
+import type { WorkspaceSettings } from "../project.types.js";
+import { readDependencies } from "./read-dependencies.js";
+import { readInheritable } from "./read-package.js";
+import { asList, asRecord } from "./scalars.js";
+
+/**
+ * `[workspace]`, or undefined when the manifest is a plain package.
+ *
+ * A root may also be a package, so `[workspace]` and `[package]` are read
+ * separately and never merged.
+ */
+export function readWorkspace(data: Record<string, unknown>): WorkspaceSettings | undefined {
+  if (data.workspace === undefined) return undefined;
+  const table = asRecord(data.workspace);
+  return {
+    members: asList(table.members),
+    exclude: asList(table.exclude),
+    defaultMembers: asList(table["default-members"]),
+    package: readInheritable(asRecord(table.package)),
+    dependencies: readDependencies(table.dependencies),
+  };
+}

package/src/ports/manifest-provider/read/scalars.ts

@@ -0,0 +1,35 @@
+// Reading a parsed TOML value as the shape the manifest expects. None of these
+// throw: a malformed table reads as an empty one, so one bad line never stops a
+// project from opening.
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+export function asStringMap(value: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, item] of Object.entries(asRecord(value))) out[key] = String(item);
+  return out;
+}
+
+export function asList(value: unknown): readonly string[] {
+  return Array.isArray(value) ? value.map(String) : [];
+}
+
+export function asRecords(value: unknown): readonly Record<string, unknown>[] {
+  return Array.isArray(value) ? value.map(asRecord) : [];
+}
+
+export function asString(value: unknown): string | undefined {
+  return value === undefined || value === null ? undefined : String(value);
+}
+
+export function asNumber(value: unknown): number | undefined {
+  const parsed = Number(value);
+  return value === undefined || Number.isNaN(parsed) ? undefined : parsed;
+}
+
+export function asBoolean(value: unknown): boolean | undefined {
+  if (value === undefined) return undefined;
+  return value === true || value === "true";
+}

package/src/ports/manifest-provider/read-run-settings.ts

@@ -0,0 +1,38 @@
+import type { FormatSettings, Manifest } from "./manifest.types.js";
+import { asBoolean, asList, asNumber, asRecord, asStringMap } from "./read/index.js";
+
+type RunSettings = Pick<Manifest, "env" | "envFiles" | "paths" | "format">;
+
+/**
+ * How the project runs, as against what it is: environments, path aliases and
+ * formatting.
+ */
+export function readRunSettings(data: Record<string, unknown>): RunSettings {
+  return {
+    env: readEnv(data.env),
+    envFiles: asList(asRecord(data.env).files),
+    paths: asStringMap(data.paths),
+    format: readFormat(data.format),
+  };
+}
+
+function readFormat(value: unknown): FormatSettings {
+  const table = asRecord(value);
+  return {
+    indent: asNumber(table.indent),
+    tabs: asBoolean(table.tabs),
+    organize: asBoolean(table.organize),
+    sort: asBoolean(table.sort),
+  };
+}
+
+/** `files` configures where to read from; every other key names an environment. */
+const RESERVED = new Set(["files"]);
+
+function readEnv(value: unknown): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  for (const [name, vars] of Object.entries(asRecord(value))) {
+    if (!RESERVED.has(name)) out[name] = asStringMap(vars);
+  }
+  return out;
+}

package/src/ports/manifest-provider/resolve-alias.ts

@@ -0,0 +1,22 @@
+/** Where a `#alias/…` specifier points. */
+export interface AliasTarget {
+  /** The directory `[paths]` maps the alias to. */
+  dir: string;
+  /** What followed the alias, with the separating slash removed. */
+  rest: string;
+}
+
+/**
+ * Split a `#alias/rest` import specifier against `[paths]` from `venn.toml`.
+ *
+ * @returns undefined when the specifier names no configured alias, which the
+ * caller reads as a relative or bare path.
+ */
+export function resolveAlias(args: {
+  spec: string;
+  paths: Record<string, string>;
+}): AliasTarget | undefined {
+  const alias = Object.keys(args.paths).find((key) => args.spec.startsWith(`${key}/`));
+  if (!alias) return undefined;
+  return { dir: args.paths[alias] as string, rest: args.spec.slice(alias.length + 1) };
+}

package/src/ports/manifest-provider/toml/index.ts

@@ -0,0 +1,3 @@
+export { parseToml } from "./parse-toml.js";
+export { type Cursor, cursor, readValue } from "./read-value.js";
+export { enterSection, enterTableArray } from "./sections.js";