magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

MGS7001: unresolvable buzz import

The knowledge-graph builder walks every .buzz source and records an imports edge per import statement. When an import path resolves to a scanned workspace file, the edge is EXTRACTED (confidence 1.0). When it does not, the builder keeps the import as an INFERRED edge to a literal import:<path> node and tags that node with this code, so the ambiguity stays visible instead of being silently dropped.

Built-in magus and magus/* imports are stdlib modules, not files; they are expected to be unresolvable and are NOT flagged. This code is reserved for a path that looks workspace-relative (e.g. spells/foo) but matches no scanned .buzz file.

Why

The graph is deterministic and derived: every edge is rebuildable from workspace sources. An import that points nowhere is not an error in the build - the buzz program may still run (the file could be generated later, or the import could be dead) - but it is genuinely ambiguous for graph purposes, because there is no file node to link to. Recording it as an inferred edge to the literal, tagged with this code, keeps the graph honest: an agent querying the import node sees that magus could not resolve it, rather than assuming a resolved dependency that does not exist.

Resolution

  • If the import is a typo or points at a moved file, fix the path so it names a real .buzz source; the edge upgrades to extracted on the next build.
  • If the import is intentionally dynamic or points at a generated file, no action is needed - the inferred edge is the correct representation.
  • To find every flagged import: magus query kind:import, then magus explain the ones whose diagnostic attribute is MGS7001.
MGS7001knowledge graphbuzzimportextractioninferred
Last updated (b022d75e)
Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.