@fraczak/k 6.10.2 → 6.10.4

package/codecs/README.md

@@ -1,35 +1,36 @@
 # K Codecs
 
-This directory is being rewritten around a new codec design:
+This directory is centered on the codec design:
 
 ```text
 abstract pattern graph + prefix-free tree encoding
 ```
 
-The default concrete format is now the binary encoding of a `$pattern` value,
-using the `$pattern` type from [`../core.k`](../core.k), immediately followed by
-the binary encoding of the value under that decoded pattern.
+The default concrete format is now the binary encoding of a `$pattern`
+value, using the `$pattern` type from [`../core.k`](../core.k),
+immediately followed by the binary encoding of the value under that
+decoded pattern.
 
-`core.k` is not loaded automatically as a library when user programs run. The
-codec only depends on the canonical `$pattern` definition from that file as the
-schema for the leading pattern value.
+`core.k` is not loaded automatically as a library when user programs
+run. The codec only depends on the canonical `$pattern` definition from
+that file as the schema for the leading pattern value.
 
 There is no separate JSON container format.
 
 ## Objectives
 
-The rewrite is guided by two hard requirements:
+The design is guided by two hard requirements:
 
 1. compactness close to the structural lower bound,
 2. efficient `k` projections, especially `.field` and `/tag`.
 
-The current target architecture is the pattern graph plus prefix-free value-tree
-stream described here and in
+The current target architecture is the pattern graph plus prefix-free
+value-tree stream described here and in
 [`POLYMORPHIC_BINARY_FORMAT.md`](./POLYMORPHIC_BINARY_FORMAT.md).
 
 ## Core Idea
 
-The semantic object serialized by the new codec is:
+The semantic object serialized by the codec is:
 
 ```text
 (P, v)
@@ -40,10 +41,11 @@ where:
 - `P` is an abstract rooted pattern graph,
 - `v` is a value tree compatible with `P`.
 
-The same pair is now the in-memory runtime model as well. Decoding a stream
-attaches `P` to the resulting `Value` as `value.pattern`; evaluation propagates
-that pattern through projections and constructors; encoding a `Value` uses its
-carried pattern unless an explicit pattern is supplied.
+The same pair is the in-memory runtime model as well. Decoding a stream
+attaches `P` to the resulting `Value` as `value.pattern`; evaluation
+propagates that pattern through projections and constructors; encoding
+a `Value` uses its carried pattern unless an explicit pattern is
+supplied.
 
 The base value encoding is:
 
@@ -52,9 +54,9 @@ The base value encoding is:
 - interpreted relative to the pattern graph,
 - free of repeated field names and tag names in the value payload.
 
-The base codec does **not** perform DAG compression. If sharing is desired, it
-should happen as a higher-level transform, not inside the primitive value
-format.
+The base codec does **not** perform DAG compression. If sharing is
+desired, it should happen as a higher-level transform, not inside the
+primitive value format.
 
 ## Wire Format
 
@@ -64,9 +66,9 @@ The default transport format is:
 encode($pattern_value : $pattern) encode(value : decoded_pattern)
 ```
 
-`$pattern_value` is a normal k value whose shape is defined in `core.k`. After
-that value is decoded, it becomes the pattern used to decode the remaining
-value payload.
+`$pattern_value` is a normal k value whose shape is defined in `core.k`.
+After that value is decoded, it becomes the pattern used to decode the
+remaining value payload.
 
 The runtime boundary is therefore:
 
@@ -74,25 +76,28 @@ The runtime boundary is therefore:
 binary pattern+value stream <-> Value(pattern, tree)
 ```
 
-At the command-line boundary, `k-parse` and `k-print` use a JSON-like textual
-notation for k values. That notation is documented in
-[`../DOCS/TEXTUAL_VALUES.md`](../DOCS/TEXTUAL_VALUES.md). It is a readable
-notation for k values, not a separate JSON container format.
+At the command-line boundary, `k-parse` and `k-print` use a JSON-like
+textual notation for k values. That notation is documented in
+[`../DOCS/TEXTUAL_VALUES.md`](../DOCS/TEXTUAL_VALUES.md). It is a
+readable notation for k values, not a separate JSON container format.
 
 For the codec architecture and specification, see
 [`../DOCS/CODEC_ARCHITECTURE.md`](../DOCS/CODEC_ARCHITECTURE.md).
-For the contributor-facing guide to writing a new external codec module, see
-[`../DOCS/CODECS.md`](../DOCS/CODECS.md).
+For the contributor-facing guide to writing a new external codec module,
+see [`../DOCS/CODECS.md`](../DOCS/CODECS.md).
+For the broader view of all artifacts and compilation targets, see
+[`../DOCS/FILE_FORMATS.md`](../DOCS/FILE_FORMATS.md).
 
-`k.mjs` is only the command-line adapter for that boundary. The operational
-runtime sees and preserves the pattern on the `Value` itself.
+`k.mjs` is only the command-line adapter for that boundary. The
+operational runtime sees and preserves the pattern on the `Value`
+itself.
 
 ## Command-Line Tools
 
-Installed codec binaries use the `k-` prefix followed by the source basename
-without `.mjs`. Source names that already include `k-`, such as
-`k-parse.mjs`, keep that name. Every installed codec binary supports `-h` and
-`--help`.
+Installed codec binaries use the `k-` prefix followed by the source
+basename without `.mjs`. Source names that already include `k-`, such
+as `k-parse.mjs`, keep that name. Every installed codec binary supports
+`-h` and `--help`.
 
 | Binary | Source | Purpose |
 | --- | --- | --- |
@@ -108,8 +113,8 @@ without `.mjs`. Source names that already include `k-`, such as
 
 ## Pattern Graph Representation
 
-For documentation and tests, a pattern graph may be shown as a property-list
-style vector of nodes:
+For documentation and tests, a pattern graph may be shown as a
+property-list style vector of nodes:
 
 ```text
 [kind, edges]
@@ -145,22 +150,23 @@ Canonical rules:
 - edge labels are unique within a node,
 - `"any"` must have no outgoing edges.
 
-This JSON-like graph is only a readable notation. The wire representation is
-the ordinary k `$pattern` value from `core.k`.
+This JSON-like graph is only a readable notation. The wire
+representation is the ordinary k `$pattern` value from `core.k`.
 
-For pattern export, see [`../DOCS/PATTERNS.md`](../DOCS/PATTERNS.md) and the
-repository helper `patterns/from-k.mjs`.
+For pattern export, see [`../DOCS/PATTERNS.md`](../DOCS/PATTERNS.md) and
+the repository helper `patterns/from-k.mjs`.
 
 ## Witness-Derived Patterns
 
-When `k-parse` is used without an explicit input pattern or type, the wire
-pattern is derived from the parsed value tree.
+When `k-parse` is used without an explicit input pattern or type, the
+wire pattern is derived from the parsed value tree.
 
 - An empty textual node is a closed product: `{}`.
 - A textual node with multiple children is a closed product.
-- A textual node with one child is interpreted as an open union by default.
-- An explicit product input pattern may force such a node to be treated as a
-  singleton product instead.
+- A textual node with one child is interpreted as an open union by
+  default.
+- An explicit product input pattern may force such a node to be
+  treated as a singleton product instead.
 
 For example, parsing:
 
@@ -179,18 +185,20 @@ without an input pattern derives:
 ]
 ```
 
-During this construction, finite closed pattern subtrees are hash-consed from
-the leaves upward. The starting closed leaf is `["closed-product", []]`. Two
-closed nodes collapse only when they have the same closed kind, the same labels,
-and the same already-collapsed child targets. Open nodes keep their identity,
-and recursive closed nodes are not collapsed by this witness-tree rule.
+During this construction, finite closed pattern subtrees are hash-consed
+from the leaves upward. The starting closed leaf is `["closed-product",
+[]]`. Two closed nodes collapse only when they have the same closed
+kind, the same labels, and the same already-collapsed child targets.
+Open nodes keep their identity, and recursive closed nodes are not
+collapsed by this witness-tree rule.
 
-This is canonicalization of the pattern graph carried in the wire stream. It is
-not DAG compression of the value payload.
+This is canonicalization of the pattern graph carried in the wire
+stream. It is not DAG compression of the value payload.
 
 ## Prefix-Free Value Encoding
 
-The value payload is a bitstream interpreted relative to the pattern graph.
+The value payload is a bitstream interpreted relative to the pattern
+graph.
 
 Base rules:
 
@@ -209,25 +217,27 @@ width = ceil(log2(cardinality))
 emit tag ordinal in width bits
 ```
 
-This is the simplest canonical prefix-free choice encoding. It is not the final
-word on compression, but it gives a regular and compact base encoding that can
-later be refined without changing the abstract pattern/value model.
+This is the simplest canonical prefix-free choice encoding. It is not
+the final word on compression, but it gives a regular and compact base
+encoding that can later be refined without changing the abstract
+pattern/value model.
 
 ## Projections
 
 The base tree encoding is chosen so that:
 
 - `/tag` only needs to read the union choice at the current node,
-- `.field` follows canonical product order and may later be accelerated by
-  higher-level indexes if necessary.
+- `.field` follows canonical product order and may later be accelerated
+  by higher-level indexes if necessary.
 
-In the materialized runtime, projections also project the carried pattern:
-`.field` returns the subpattern at that product field, and `/tag` returns the
-subpattern at that union tag. If no carried subpattern is available, later
-encoding can still derive a witness pattern from the result tree.
+In the materialized runtime, projections also project the carried
+pattern: `.field` returns the subpattern at that product field, and
+`/tag` returns the subpattern at that union tag. If no carried subpattern
+is available, later encoding can still derive a witness pattern from
+the result tree.
 
-The primitive codec stays minimal. Projection indexes, framing, or sharing
-schemes are explicitly separate concerns.
+The primitive codec stays minimal. Projection indexes, framing, or
+sharing schemes are explicitly separate concerns.
 
 ## Design Boundary
 
@@ -240,17 +250,18 @@ The new codec work is split into layers:
 
 ## Files
 
+- [`../DOCS/FILE_FORMATS.md`](../DOCS/FILE_FORMATS.md):
+  comprehensive guide to file formats and compilation pipelines.
 - [`../DOCS/CODEC_ARCHITECTURE.md`](../DOCS/CODEC_ARCHITECTURE.md):
   comprehensive architecture specification for k codecs.
 - [`../DOCS/CODECS.md`](../DOCS/CODECS.md):
   practical guide to writing, running, and testing codecs.
 - [`POLYMORPHIC_BINARY_FORMAT.md`](./POLYMORPHIC_BINARY_FORMAT.md):
-  main design document for the new pattern-plus-prefix-tree codec.
+  main design document for the pattern-plus-prefix-tree codec.
 - [`BINARY_FORMAT.md`](./BINARY_FORMAT.md):
   notes on future binary packaging of the same abstract semantics.
 
 ## Status
 
-The active command-line pipeline emits and consumes the self-hosted binary
-pattern+value stream.
-
+The active command-line pipeline emits and consumes the self-hosted
+binary pattern+value stream.

package/core.k

@@ -39,11 +39,11 @@ concat_ = ${bits x, bits y}
 -- successor (increment by 1)
 succ = {inv x, _ y} _inc;
 
-_inc = ${bits x, bits y} <
-    {.x /0 x, .y |1 y} concat_,
-    {.x /1 x, .y |0 y} _inc,
-    .y |1
->;
+_inc = ?{X x, X y} 
+<
+    {.x </0,/_|_> x, .y |1 y} concat_,
+    {.x /1 x, .y |0 y} _inc
+> ?X;
 
 -- constants
 2 = 1 succ;

package/objects/README.md

@@ -1,29 +1,36 @@
 # objects/
 
-CLI tools for compiling and inspecting k object files (`.ko`) and library files (`.klib`).
+CLI tools for compiling and inspecting k object files (`.ko`), library
+files (`.klib`), and polymorphic kVM template files (`.kvm`).
 
 ## Tools
 
 ### `k-compile`
 
-Compiles `.k` source into an executable object file (`.ko`), library file
-(`.klib`), or polymorphic kVM backend artifact (`.kvm`). Output format is
-inferred from the output extension, or from `--format`.
+Compiles `.k` source into an executable object file (`.ko`), library
+file (`.klib`), or polymorphic kVM backend artifact (`.kvm`). Output
+format is inferred from the output extension, or from `--format`.
 
 ```bash
-k-compile [--lib lib-file] [--export spec]... [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
+k-compile [--lib lib-file] [--export spec]... \
+  [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
 ```
 
-Existing input paths are read as files. A non-existing input with `.k`, `.ko`,
-or `.klib` extension is reported as a missing file; otherwise it is compiled as
-inline k source, in the same style as `k.mjs`.
+Existing input paths are read as files. A non-existing input with `.k`,
+`.ko`, or `.klib` extension is reported as a missing file; otherwise it
+is compiled as inline k source, in the same style as `k.mjs`.
 
-`.kvm` is a polymorphic kVM template artifact (`layer: "KVM-P"`). It carries the
-relational function definitions, their principal input/output pattern graphs, and
-lowered kVM instruction streams ready for runtime specialization when enveloped
-values arrive. Specialization occurs when functions are invoked on concrete values,
-eliminating the need for ahead-of-time input pattern or input type flags. Names from
-a `--lib` dependency can be imported into the entry scope using `--export (oldname:)?newname`.
+`.kvm` is a polymorphic kVM template artifact (`layer: "KVM-P"`). It
+carries relational function definitions, principal pattern graphs,
+and lowered kVM instruction streams ready for runtime specialization
+when enveloped values arrive (`specializeKVM`).
+
+When linking a `--lib` dependency, all relations are loaded under their
+canonical content-addressed hashes (`@hash`). To use human-readable
+alias names in an expression or script, explicitly map them into the
+local scope using `--export <alias>` or
+`--export <libAlias>:<localAlias>`.
+Alternatively, canonical `@hash` names may always be referenced directly.
 
 ### `k-decompile`
 
@@ -35,9 +42,9 @@ k-decompile [object-file [k-file]]
 
 ### `k-extract-aliases`
 
-Extracts metadata aliases from a `.ko` or `.klib` as a valid k definition
-snippet. Output is grouped by metadata type (`code`, then `rel`), then sorted by
-alias name and `compiledAt`.
+Extracts metadata aliases from a `.ko` or `.klib` as a valid k
+definition snippet. Output is grouped by metadata type (`code`, then
+`rel`), then sorted by alias name and `compiledAt`.
 
 ```bash
 k-extract-aliases [object-file [k-file]]
@@ -45,15 +52,16 @@ k-extract-aliases [object-file [k-file]]
 
 ### `k-inspect-object`
 
-Inspects a `.ko` or `.klib`. By default it prints a compact object summary.
-With `--kir`, it prints the current KIR-P export used by backend experiments.
+Inspects a `.ko` or `.klib`. By default it prints a compact object
+summary. With `--kir`, it prints the current KIR-P export used by
+backend experiments.
 
 ```bash
 k-inspect-object [--summary | --kir] [object-file]
 ```
 
-For scripts that only need KIR-P export, `k-kir [object-file]` is the direct
-exporter backed by `kir.mjs`.
+For scripts that only need KIR-P export, `k-kir [object-file]` is the
+direct exporter backed by `kir.mjs`.
 
 ### `k-validate-object`
 
@@ -64,29 +72,41 @@ Validates a `.ko` or `.klib` object and its derived KIR-P export. With
 k-validate-object [--kir] [input-file]
 ```
 
-The installed names are `k-` plus the source basename without `.mjs`. Every
-installed object binary supports `-h` and `--help`.
+The installed names are `k-` plus the source basename without `.mjs`.
+Every installed object binary supports `-h` and `--help`.
 
 ## Current Format Notes
 
-- `.klib` files are plain UTF-8 JSON, not binary containers.
-- `.ko` files use the `KOBJ\n` binary header followed by a JSON payload.
+- For full specifications, see
+  [`DOCS/FILE_FORMATS.md`](../DOCS/FILE_FORMATS.md).
+- Both `.ko` and `.klib` are ahead-of-time (AOT) type-checked artifacts.
+  Parsing, relation expansion, type derivation, and constraint
+  convergence are completed in advance.
+- `.klib` files are plain UTF-8 JSON, not binary containers
+  (`main: null`).
+- `.ko` files use the `KOBJ\n` binary header followed by a JSON payload
+  (`main: "__main__"`).
 - There is no object payload version field in either format.
 - `typeDerivation` belongs only to relations and currently stores only
   `status`.
 - Source `start` / `end` ranges live on `meta[hash].origins[]` entries.
-- Origin entries do not have `kind`; the metadata entry has `type: "code"` or
-  `type: "rel"`.
-- Stored relation bodies do not include generated input/output boundary filters.
-- KIR-P is available as an inspection/export contract; it does not change the
-  stored `.ko` or `.klib` payload.
-- `.kvm` is not a canonical source/object format; it is a polymorphic backend
-  template artifact (`layer: "KVM-P"`), lowered from KIR-P for runtime execution
-  and JIT specialization.
+- Origin entries do not have `kind`; the metadata entry has `type: "code"`
+  or `type: "rel"`.
+- Stored relation bodies do not include generated input/output filters.
+- KIR-P is available as an inspection/export contract; it does not change
+  the stored `.ko` or `.klib` payload.
+- `.kvm` is a polymorphic backend template artifact (`layer: "KVM-P"`),
+  lowered from KIR-P for runtime execution and JIT specialization.
 
 ## Further reading
 
-- [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) — object file format and pattern encoding
-- [DOCS/KIR_V1.md](../DOCS/KIR_V1.md) — KIR-P inspection/export contract for backends
-- [DOCS/TYPE_DERIVATION.md](../DOCS/TYPE_DERIVATION.md) — type derivation (what compilation skips when loading a `.ko`/`.klib`)
-- [DOCS/CONVERGENCE.md](../DOCS/CONVERGENCE.md) — convergence strategies for type inference
+- [DOCS/FILE_FORMATS.md](../DOCS/FILE_FORMATS.md) — guide to
+  .k, .ko, .klib, and .kvm formats
+- [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) —
+  object file format and pattern encoding
+- [DOCS/KIR_V1.md](../DOCS/KIR_V1.md) — KIR-P inspection/export contract
+  for backends
+- [DOCS/TYPE_DERIVATION.md](../DOCS/TYPE_DERIVATION.md) — type
+  derivation (what compilation skips when loading a `.ko`/`.klib`)
+- [DOCS/CONVERGENCE.md](../DOCS/CONVERGENCE.md) — convergence strategies
+  for type inference

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.10.2",
+    "version": "6.10.4",
     "description": "k — a language for composing first-order partial functions over algebraic data types (products and tagged unions); includes runtime, type derivation, REPL, and codec toolchain",
     "main": "index.mjs",
     "exports": {
@@ -20,6 +20,7 @@
         "perf:ieee": "node scripts/perf-ieee.mjs",
         "perf:ieee:full": "node scripts/perf-ieee.mjs --full",
         "perf:int": "node scripts/perf-int.mjs",
+        "perf:mult": "node scripts/perf-multiplication.mjs",
         "perf:poly": "node scripts/perf-poly.mjs",
         "perf:poly:trace": "node scripts/perf-poly.mjs --trace",
         "perf:idempotency": "node scripts/benchmark-idempotency.mjs",

package/scripts/benchmark-idempotency.mjs

@@ -14,6 +14,33 @@ const DEFAULT_EXAMPLES = [
   "Examples/ieee.k"
 ];
 
+function printHelp() {
+  console.log(
+`Usage: node scripts/benchmark-idempotency.mjs [options] [files...]
+
+Measures compile and decompile round-trip idempotency performance
+for K source files through the .klib object format.
+
+Arguments:
+  example.k ...
+      One or more .k source files to benchmark.
+      (default: Examples/nat.k Examples/byte.k Examples/bnat.k
+                Examples/arithmetics.k Examples/ieee.k)
+
+Options:
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  K_BENCH_ITERATIONS
+      Number of round-trip benchmark iterations (default: 5).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 const iterations = Number(process.env.K_BENCH_ITERATIONS || 5);
 const examples = process.argv.slice(2);
 const benchmarkExamples = examples.length > 0 ? examples : DEFAULT_EXAMPLES;

package/scripts/benchmark.mjs

@@ -733,7 +733,58 @@ function printSummary(document) {
   console.log("=============================================================\n");
 }
 
+function printHelp() {
+  console.log(`Usage: node scripts/benchmark.mjs [options]
+
+Unified Multi-Backend Benchmark Suite.
+Runs comprehensive arithmetic and IEEE benchmarks across Native JS,
+kVM, KIR-P, Wasm, and LLVM-JIT execution engines.
+
+Options:
+  --worker
+      Internal flag: execute an isolated benchmark worker job.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BENCHMARK_CASES
+      Comma-separated benchmark cases to run (default: all).
+      Cases: ieee.add, ieee.sub, ieee.mul, ieee.div,
+             int.times.220d, int.gcd.90d, int.factorial.101,
+             int.factorial.242, int.factorial.1174
+  BENCHMARK_MODES
+      Comma-separated execution modes to run (default: all).
+      Modes: Native JS (Envelope-Aware), Native JS (Envelope-Free),
+             kVM Interpreter (Env-Free), KIR-P Export,
+             k-wasm, k-llvm-jit
+  BENCHMARK_SAMPLES
+      Number of measurement samples per benchmark (default: 3).
+  BENCHMARK_TIMEOUT_MS
+      Timeout per benchmark job in milliseconds (default: 120000).
+  BENCHMARK_JOBS
+      Maximum parallel worker concurrency (default: 1).
+  BENCHMARK_STRICT
+      Exit with non-zero exit code if any case fails ('1' to enable).
+  K_LLVM_RUNTIME_MODE
+      Default LLVM runtime compilation mode (default: fast).
+  K_LLVM_IEEE_RUNTIME_MODE
+      LLVM runtime mode for IEEE benchmarks (default: compact).
+  K_LLVM_CLANG_OPT
+      Clang optimization flag for LLVM (default: -O3).
+  K_LLVM_IEEE_CLANG_OPT
+      Clang optimization flag for IEEE LLVM (default: -O0).
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  K_BENCHMARK_RESULT_PATH
+      Custom destination file path for benchmark results JSON.`);
+}
+
 async function main() {
+  if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    printHelp();
+    return;
+  }
+
   if (process.env.K_BENCHMARK_WORKER === "1" || process.argv.includes("--worker")) {
     await workerMain();
     return;

package/scripts/build-repl-html.mjs

@@ -10,6 +10,23 @@ const __dirname = path.dirname(__filename);
 const projectRoot = path.resolve(__dirname, "..");
 const workspaceRoot = path.resolve(projectRoot, "..");
 
+function printHelp() {
+  console.log(`Usage: node scripts/build-repl-html.mjs [options]
+
+Builds the standalone, self-contained K web REPL (repl.html).
+Bundles browser shims, virtual file system (core.k, Examples, Wasm),
+and UI components into a single zero-dependency HTML file.
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 console.log("=== Building Self-Contained K REPL HTML ===");
 
 // 1. Node shims plugin for esbuild

package/scripts/generate-dependency-graph.mjs

@@ -8,7 +8,31 @@ import { execSync } from "node:child_process";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const root = path.resolve(__dirname, "..");
-const outPath = path.join(root, "DOCS", "dependency-graph.md");
+
+function printHelp() {
+  console.log(
+`Usage: node scripts/generate-dependency-graph.mjs [options] [out]
+
+Generates a Mermaid dependency diagram from tracked ESM imports.
+
+Arguments:
+  out-file
+      Destination markdown file path.
+      (default: DOCS/dependency-graph.md)
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
+const outPath = process.argv[2]
+  ? path.resolve(root, process.argv[2])
+  : path.join(root, "DOCS", "dependency-graph.md");
 
 function getTrackedMjsFiles() {
   const raw = execSync("git ls-files '*.mjs'", {