`eng`

Dependency graph engine - extract use declarations from ilusm source, deduplicate the module list, emit a Graphviz DOT dependency graph, read declared dependencies from ilusm.pkg.json, read the resolved load order from ilusm.lock.json, and rename module identifiers in source text.

Load with: use eng

What this module does

eng is used by the ilusm build system to reason about module dependencies. Given the text of a source file, it can extract every use declaration to find what the file depends on. It can then render those dependencies as a Graphviz digraph for visualisation.

It also reads the project manifest (ilusm.pkg.json) and lock file (ilusm.lock.json) to obtain declared and resolved dependency lists. The refactoring helper engrf does a simple string-replace of a module name throughout source text.

Quick example

use eng

src = fs.rd("src/app.ilu")

# Count uses and defs
prn(engme(src))  # {ln:200, use:5, def:12}

# List unique dependencies
deps = engus(src)
prn(deps)  # ["trl", "txt", "wf", "jsn", "fs"]

# Graphviz DOT
dot = engdo("app", deps)
fs.wr("deps.dot", dot)
# digraph deps { "app" -> "trl"; "app" -> "txt"; ... }

# From the lock file (resolved order)
order = engpk(".")
prn(order)

Functions

Source analysis

engme(source)

Counts lines, use statements, and def statements in a source string. Returns {ln, use, def}. Useful for quick source-file metrics.

engus(source)

Extracts all unique module names referenced by use statements in the source string. Handles both bare names (use txt) and quoted names (use "txt"). Returns a deduplicated list of module name strings.

Graph output

engdo(root, mods)

Produces a Graphviz DOT string representing root's direct dependencies. Each module in mods becomes an edge "root" -> "mod". Output is a complete digraph deps { ... } block ready to pipe to dot -Tpng.

Manifest and lockfile

engpk(root)

Reads the declared dependency names from ilusm.pkg.json in the root directory using pkm. Returns a list of dependency name strings, or [] if the manifest is absent or unreadable.

engpk(root) (lockfile variant)

Reads the resolved load order from ilusm.lock.json. Returns the order array if present, or [].

Refactoring

engrf(source, old_name, new_name)

Replaces all occurrences of the string old_name with new_name in the source text using txt.rep. Useful for renaming a module reference across a file.

Notes

Dependency extraction is purely text-based (not AST-based) - it finds any line starting with use .
Requires trl, txt, pkm, and eru.