@pieceful/ravel 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 James Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pieceful/ravel",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Ravel command-line interface.",
+  "license": "MIT",
+  "author": "James Taylor",
+  "repository": { "type": "git", "url": "git+https://github.com/jostylr/ravel.git", "directory": "packages/cli" },
+  "bugs": { "url": "https://github.com/jostylr/ravel/issues" },
+  "homepage": "https://github.com/jostylr/ravel#readme",
+  "engines": { "node": ">=22" },
+  "keywords": ["ravel", "literate-programming", "cli", "build"],
+  "publishConfig": { "access": "public" },
+  "bin": {
+    "ravel": "./src/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": ["src", "LICENSE"],
+  "dependencies": {
+    "@pieceful/ravel-core": "0.1.0",
+    "@pieceful/ravel-host-node": "0.1.0"
+  }
+}

package/src/.gitkeep

@@ -0,0 +1 @@
+

package/src/index.js

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+import { cleanManagedArtifacts, createOutputBackup, loadBuildInput, planDeliverables, planOutputBackup, planStaleDeliverables, refreshStaleArtifacts, writeBuildArtifacts, writeGraph } from "@pieceful/ravel-host-node";
+import {
+  createDeliverableProvenanceMap,
+  explainGeneratedOffset,
+  generatedRangesForSource,
+  transformGraph
+} from "@pieceful/ravel-core";
+import { existsSync, realpathSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const EXIT_SOURCE = 1;
+const EXIT_USAGE = 2;
+const EXIT_INTERNAL = 3;
+const RAVEL_VERSION = "0.1.0";
+const valueOptions = new Set([
+  "--config",
+  "--out-dir",
+  "--document",
+  "--mode",
+  "--provenance",
+  "--generated-offset",
+  "--source-uri",
+  "--source-offset"
+]);
+const booleanOptions = new Set(["--json", "--dry-run", "--debug", "--chunks", "--trace", "--clean"]);
+
+const usage = () => {
+  console.error("Usage: ravel check <map.json|document.md> [--config <run.toml>] [--document <name>] [--mode <opt-in|primary>] [--json]");
+  console.error("       ravel                 # builds ./ravel.toml when it exists");
+  console.error("       ravel build <map.json|document.md> --out-dir <directory> [--document <name>] [--mode <opt-in|primary>] [--graph <program.json>] [--backup [file.zip]] [--clean] [--dry-run] [--json]");
+  console.error("       ravel build --config <run.toml> [--out-dir <directory>] [--graph <program.json>] [--backup [file.zip]] [--clean] [--dry-run] [--json]");
+  console.error("       ravel inspect <map.json|document.md> [--config <run.toml>] [--document <name>] [--mode <opt-in|primary>] [--chunks|--graph|--trace] [--json]");
+  console.error("       ravel inspect <input> --provenance <deliverable> [--generated-offset <offset> | --source-uri <uri> --source-offset <offset>] [--json]");
+  console.error("       ravel refresh <output-directory> [--dry-run] [--json]");
+};
+
+const formatDiagnostic = (entry) => {
+  const source = entry.source;
+  const start = source?.range?.start;
+  const location = source?.uri
+    ? source.uri + (start ? ":" + (start.line + 1) + ":" + (start.column + 1) : "")
+    : "ravel";
+  return location + " " + (entry.severity ?? "error") + "[" + (entry.code ?? "RV900") + "]: " + entry.message;
+};
+
+const printDiagnostics = (diagnostics, json) => {
+  if (json) console.error(JSON.stringify(diagnostics, null, 2));
+  else for (const diagnostic of diagnostics) console.error(formatDiagnostic(diagnostic));
+};
+
+const parseArguments = (argumentsValue) => {
+  const command = argumentsValue[0];
+  const options = {};
+  const positional = [];
+  for (let index = 1; index < argumentsValue.length; index += 1) {
+    const argument = argumentsValue[index];
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
+      continue;
+    }
+    if (argument === "--backup") {
+      if (Object.hasOwn(options, argument)) return { error: "Option may be specified only once: " + argument };
+      const following = argumentsValue[index + 1];
+      if (following && !following.startsWith("--") && extname(following).toLowerCase() === ".zip") {
+        options[argument] = following;
+        index += 1;
+      } else {
+        options[argument] = true;
+      }
+      continue;
+    }
+    if (booleanOptions.has(argument) || (argument === "--graph" && command === "inspect")) {
+      if (options[argument]) return { error: "Option may be specified only once: " + argument };
+      options[argument] = true;
+      continue;
+    }
+    if (!valueOptions.has(argument) && !(argument === "--graph" && command === "build")) {
+      return { error: "Unknown option: " + argument };
+    }
+    const value = argumentsValue[index + 1];
+    if (!value || value.startsWith("--")) return { error: "Option requires a value: " + argument };
+    if (Object.hasOwn(options, argument)) return { error: "Option may be specified only once: " + argument };
+    options[argument] = value;
+    index += 1;
+  }
+  if (positional.length > 1) return { error: "Expected at most one input path." };
+  if (options["--config"] && positional.length) return { error: "Use either an input path or --config, not both." };
+  return { command, options, input: options["--config"] ?? positional[0] };
+};
+
+const sortedEntries = (value) => Object.entries(value ?? []).sort(([left], [right]) => left.localeCompare(right));
+
+class CliUsageError extends Error {}
+
+const inspectProgram = (program, options) => {
+  if (options["--provenance"]) {
+    const deliverable = program.deliverables[options["--provenance"]];
+    if (!deliverable) {
+      throw new CliUsageError("Unknown deliverable for --provenance: " + options["--provenance"]);
+    }
+    const map = createDeliverableProvenanceMap(deliverable);
+    const generatedOffset = options["--generated-offset"];
+    if (generatedOffset !== undefined) {
+      const offset = Number(generatedOffset);
+      const explanation = explainGeneratedOffset(program, deliverable.name, offset);
+      return {
+        version: program.version,
+        view: "provenance",
+        deliverable: { name: deliverable.name, from: deliverable.from },
+        query: { kind: "generated-offset", offset },
+        match: explanation?.segment ?? null,
+        definition: explanation?.definition ?? null,
+        references: explanation?.references ?? [],
+        dependencyPath: explanation?.dependencyPath ?? []
+      };
+    }
+    if (options["--source-uri"] !== undefined) {
+      const uri = options["--source-uri"];
+      const offset = Number(options["--source-offset"]);
+      return {
+        version: program.version,
+        view: "provenance",
+        deliverable: { name: deliverable.name, from: deliverable.from },
+        query: { kind: "source-offset", uri, offset },
+        matches: generatedRangesForSource(map, uri, offset)
+      };
+    }
+    return {
+      version: program.version,
+      view: "provenance",
+      deliverable: { name: deliverable.name, from: deliverable.from },
+      map
+    };
+  }
+  if (options["--chunks"]) {
+    return {
+      version: program.version,
+      view: "chunks",
+      chunks: sortedEntries(program.chunks).map(([id, chunk]) => ({
+        id,
+        name: chunk.name,
+        identity: chunk.identity,
+        metadata: chunk.metadata,
+        generated: chunk.generated,
+        dependencies: chunk.dependencies,
+        references: chunk.references
+      }))
+    };
+  }
+  if (options["--graph"]) {
+    return {
+      version: program.version,
+      view: "graph",
+      chunks: sortedEntries(program.chunks).map(([id, chunk]) => ({ id, dependencies: chunk.dependencies })),
+      deliverables: Object.values(program.deliverables).sort((left, right) => left.name.localeCompare(right.name)).map((deliverable) => ({
+        name: deliverable.name,
+        from: deliverable.from,
+        dependencies: deliverable.dependencies
+      }))
+    };
+  }
+  if (options["--trace"]) {
+    return { version: program.version, view: "trace", chunks: Object.fromEntries(sortedEntries(program.trace?.chunks)) };
+  }
+  return program;
+};
+
+const printInspectResult = (result, json) => {
+  if (json || !result.view) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.view === "chunks") {
+    console.log("Ravel chunks:");
+    for (const chunk of result.chunks) {
+      const suffix = chunk.generated ? " (generated)" : "";
+      console.log("  " + chunk.id + suffix + (chunk.dependencies.length ? " → " + chunk.dependencies.join(", ") : ""));
+    }
+    return;
+  }
+  if (result.view === "graph") {
+    console.log("Ravel dependency graph (dependent ← dependency):");
+    for (const chunk of result.chunks) console.log("  " + chunk.id + " ← " + (chunk.dependencies.length ? chunk.dependencies.join(", ") : "(none)"));
+    if (result.deliverables.length) {
+      console.log("Deliverables:");
+      for (const deliverable of result.deliverables) console.log("  " + deliverable.name + " ← " + deliverable.from);
+    }
+    return;
+  }
+  if (result.view === "provenance") {
+    console.log("Ravel provenance for " + result.deliverable.name + " ← " + result.deliverable.from + ":");
+    const printVia = (segment) => {
+      for (const step of segment.via ?? []) {
+        if (step.kind === "reference") console.log("    via " + step.from + " → " + step.to);
+        else console.log("    via " + step.kind + (step.name ? " " + step.name : ""));
+      }
+    };
+    const printSegment = (segment) => {
+      if (!segment) {
+        console.log("  (no matching generated segment)");
+        return;
+      }
+      const source = segment.source;
+      const start = source?.range?.start;
+      const location = source
+        ? source.uri + (start ? ":" + (start.line + 1) + ":" + (start.column + 1) : "")
+        : "(generated)";
+      console.log(
+        "  " + segment.generated.start + ".." + segment.generated.end +
+        " ← " + location + " [" + segment.precision + ", " + segment.chunk + "]"
+      );
+      printVia(segment);
+    };
+    if (result.query?.kind === "generated-offset") {
+      console.log("Generated offset " + result.query.offset + ":");
+      printSegment(result.match);
+      if (result.dependencyPath.length) {
+        console.log("  dependency path: " + result.dependencyPath.join(" → "));
+      }
+    } else if (result.query?.kind === "source-offset") {
+      console.log("Source offset " + result.query.uri + ":" + result.query.offset + ":");
+      if (!result.matches.length) console.log("  (no generated ranges)");
+      for (const match of result.matches) {
+        console.log(
+          "  " + match.generated.start + ".." + match.generated.end +
+          (match.generatedOffset === undefined ? "" : " (exact offset " + match.generatedOffset + ")") +
+          " [" + match.precision + ", " + match.chunk + "]"
+        );
+        printVia(match);
+      }
+    } else {
+      for (const segment of result.map.segments) printSegment(segment);
+    }
+    return;
+  }
+  console.log("Ravel evaluation trace:");
+  for (const [id, entries] of Object.entries(result.chunks)) {
+    console.log("  " + id + ": " + entries.map((entry) => entry.stage).join(" → "));
+  }
+};
+
+const printBuildResult = (result, json) => {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.dryRun) {
+    console.log("Ravel build plan for " + result.outputDirectory + ":");
+    for (const deliverable of result.deliverables) console.log("  " + deliverable.path + " ← " + deliverable.from);
+    console.log("  manifest: " + result.manifest);
+  } else {
+    console.log("Ravel wrote " + result.written.length + " deliverable" + (result.written.length === 1 ? "" : "s") + " to " + result.outputDirectory + ".");
+    for (const deliverable of result.deliverables) console.log("  " + deliverable.path + " ← " + deliverable.from);
+    console.log("Manifest: " + result.manifest);
+  }
+  if (result.stale?.length) {
+    console.log("Stale managed outputs retained:");
+    for (const deliverable of result.stale) console.log("  " + deliverable.path + " ← " + (deliverable.from ?? "previous build"));
+  }
+  if (result.removed?.length) {
+    console.log((result.dryRun ? "Managed outputs that would be removed:" : "Managed outputs removed:"));
+    for (const deliverable of result.removed) console.log("  " + deliverable.path + " ← " + (deliverable.from ?? "previous build"));
+  }
+  if (result.backup) {
+    const action = result.dryRun ? "Backup plan" : "Backup";
+    const count = result.backup.files?.length;
+    console.log(action + ": " + result.backup.path + (count === undefined ? "" : " (" + count + " files)"));
+  }
+};
+
+const printRefreshResult = (result, json) => {
+  if (json) {
+    console.log(JSON.stringify({ ok: true, command: "refresh", ...result }, null, 2));
+    return;
+  }
+  const action = result.dryRun ? "would remove" : "removed";
+  console.log("Ravel refresh " + action + " " + result.removed.length + " stale managed output" + (result.removed.length === 1 ? "" : "s") + ".");
+  for (const deliverable of result.removed) console.log("  " + deliverable.path + " ← " + (deliverable.from ?? "previous build"));
+};
+
+const invokedAsCli = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  }
+})();
+
+if (invokedAsCli) {
+const rawArguments = process.argv.slice(2);
+const argumentsValue = rawArguments.length === 0 && existsSync("ravel.toml")
+  ? ["build", "--config", "ravel.toml"]
+  : rawArguments;
+const command = argumentsValue[0];
+if (command === "--help" || command === "-h" || argumentsValue.includes("--help")) {
+  usage();
+  process.exitCode = 0;
+} else if (command === "--version" || command === "-v") {
+  console.log(RAVEL_VERSION);
+  process.exitCode = 0;
+} else {
+  const parsed = parseArguments(argumentsValue);
+  const json = parsed.options?.["--json"] === true;
+  const debug = parsed.options?.["--debug"] === true;
+  const supported = new Set(["build", "inspect", "check", "refresh"]);
+  if (!supported.has(parsed.command) || parsed.error || !parsed.input) {
+    if (parsed.error) console.error("ravel usage error: " + parsed.error);
+    usage();
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.options["--dry-run"] && !new Set(["build", "refresh"]).has(parsed.command)) {
+    console.error("ravel usage error: --dry-run is available only with build or refresh.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.options["--clean"] && parsed.command !== "build") {
+    console.error("ravel usage error: --clean is available only with build.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.options["--backup"] && parsed.command !== "build") {
+    console.error("ravel usage error: --backup is available only with build.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.options["--out-dir"] && parsed.command !== "build") {
+    console.error("ravel usage error: --out-dir is available only with build.");
+    process.exitCode = EXIT_USAGE;
+  } else if ((parsed.options["--chunks"] || parsed.options["--trace"]) && parsed.command !== "inspect") {
+    console.error("ravel usage error: --chunks and --trace are available only with inspect.");
+    process.exitCode = EXIT_USAGE;
+  } else if (["--provenance", "--generated-offset", "--source-uri", "--source-offset"]
+    .some((option) => parsed.options[option] !== undefined) && parsed.command !== "inspect") {
+    console.error("ravel usage error: provenance options are available only with inspect.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.command === "inspect" && ["--chunks", "--graph", "--trace", "--provenance"].filter((option) => parsed.options[option]).length > 1) {
+    console.error("ravel usage error: choose only one inspect view.");
+    process.exitCode = EXIT_USAGE;
+  } else if ((parsed.options["--generated-offset"] !== undefined ||
+      parsed.options["--source-uri"] !== undefined ||
+      parsed.options["--source-offset"] !== undefined) && parsed.options["--provenance"] === undefined) {
+    console.error("ravel usage error: offset queries require --provenance <deliverable>.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.options["--generated-offset"] !== undefined &&
+      (parsed.options["--source-uri"] !== undefined || parsed.options["--source-offset"] !== undefined)) {
+    console.error("ravel usage error: choose either a generated-offset or source-offset provenance query.");
+    process.exitCode = EXIT_USAGE;
+  } else if ((parsed.options["--source-uri"] === undefined) !== (parsed.options["--source-offset"] === undefined)) {
+    console.error("ravel usage error: --source-uri and --source-offset must be used together.");
+    process.exitCode = EXIT_USAGE;
+  } else if (["--generated-offset", "--source-offset"].some((option) =>
+    parsed.options[option] !== undefined && !/^(?:0|[1-9][0-9]*)$/.test(parsed.options[option]))) {
+    console.error("ravel usage error: provenance offsets must be non-negative integers.");
+    process.exitCode = EXIT_USAGE;
+  } else if (parsed.command === "refresh" && ["--config", "--document", "--mode", "--chunks", "--trace"].some((option) => parsed.options[option])) {
+    console.error("ravel usage error: refresh accepts only an output directory, --dry-run, and --json.");
+    process.exitCode = EXIT_USAGE;
+  } else {
+    try {
+      if (parsed.command === "refresh") {
+        printRefreshResult(await refreshStaleArtifacts(parsed.input, {
+          rootDirectory: parsed.input,
+          dryRun: parsed.options["--dry-run"] === true
+        }), json);
+        process.exitCode = 0;
+      } else {
+      const loaded = await loadBuildInput(parsed.input, {
+        document: parsed.options["--document"],
+        mode: parsed.options["--mode"]
+      });
+      const program = transformGraph(loaded.pretransform);
+      const errors = program.diagnostics.filter((entry) => entry.severity === "error");
+      if (errors.length) {
+        printDiagnostics(program.diagnostics, json);
+        process.exitCode = EXIT_SOURCE;
+      } else if (parsed.command === "check") {
+        if (json) console.log(JSON.stringify({ ok: true, command: "check", diagnostics: program.diagnostics }, null, 2));
+        else console.log("Ravel check passed.");
+      } else if (parsed.command === "inspect") {
+        printInspectResult(inspectProgram(program, parsed.options), json);
+      } else {
+        const outputDirectory = parsed.options["--out-dir"] ?? loaded.outputDirectory;
+        if (!outputDirectory) throw new Error("build requires --out-dir or build.out_dir in the TOML config.");
+        const plan = planDeliverables(program, outputDirectory);
+        const rootDirectory = parsed.options["--out-dir"] ?? loaded.rootDirectory;
+        const configuredClean = loaded.buildOptions?.clean === true;
+        const configuredBackup = loaded.buildOptions?.backup ?? false;
+        const clean = parsed.options["--clean"] === true || configuredClean;
+        const backupSetting = parsed.options["--backup"] ?? configuredBackup;
+        const stale = await planStaleDeliverables(program, outputDirectory, { rootDirectory });
+        const backupOptions = {
+          outputRootDirectory: rootDirectory,
+          backupRootDirectory: loaded.rootDirectory,
+          ...(typeof backupSetting === "string" ? { backupPath: backupSetting } : {})
+        };
+        const backup = backupSetting
+          ? parsed.options["--dry-run"]
+            ? await planOutputBackup(outputDirectory, backupOptions)
+            : await createOutputBackup(outputDirectory, backupOptions)
+          : null;
+        const cleanup = clean
+          ? await cleanManagedArtifacts(outputDirectory, { rootDirectory, dryRun: parsed.options["--dry-run"] === true })
+          : { removed: [] };
+        const retainedStale = clean ? [] : stale;
+        if (parsed.options["--dry-run"]) {
+          printBuildResult({ ok: true, command: "build", dryRun: true, clean, ...plan, stale: retainedStale, removed: cleanup.removed, ...(backup ? { backup } : {}) }, json);
+        } else {
+          const artifacts = await writeBuildArtifacts(program, outputDirectory, { rootDirectory, stale: retainedStale });
+          if (parsed.options["--graph"]) await writeGraph(program, parsed.options["--graph"], { rootDirectory: loaded.rootDirectory });
+          printBuildResult({
+            ok: true,
+            command: "build",
+            outputDirectory: plan.outputDirectory,
+            written: artifacts.written,
+            manifest: artifacts.manifest.path,
+            deliverables: plan.deliverables,
+            stale: retainedStale,
+            removed: cleanup.removed,
+            ...(backup ? { backup } : {}),
+            clean,
+            chunks: Object.keys(program.chunks).sort()
+          }, json);
+        }
+      }
+      }
+    } catch (error) {
+      if (error instanceof CliUsageError) {
+        console.error("ravel usage error: " + error.message);
+        process.exitCode = EXIT_USAGE;
+      } else if (Array.isArray(error?.diagnostics)) {
+        printDiagnostics(error.diagnostics, json);
+        process.exitCode = EXIT_SOURCE;
+      } else if (json) {
+        console.error(JSON.stringify([{ code: "RV900", severity: "error", message: error?.message ?? String(error) }], null, 2));
+        process.exitCode = EXIT_INTERNAL;
+      } else {
+        console.error("ravel error: " + (error?.message ?? String(error)));
+        if (debug && error?.stack) console.error(error.stack);
+        process.exitCode = EXIT_INTERNAL;
+      }
+    }
+  }
+}
+}