docs - clarify how to use

[revelt]

hi Jonathan,

Thank you for making this program. I'm having trouble getting any picture out of it.

Considering npm script:

"graph": "lerna-dependency-graph -f 'png' -o './graph.png'"

gives error:

All I'm asking the CLI is, produce me a png in the root. It should work, shouldn't it? Maybe some settings are missing but if so, should they be set automatically as defaults?

Thank you for any help.

[revelt]

sorry, false alarm, graphviz was not in PATH!
Solved!

[KoltesDigital]

You're welcome, glad it helps. Actually I don't use it haha!

[y-nk]

@KoltesDigital is there anyway we include graphviz in the deps so that we don't need to install it on the side?

[KoltesDigital]

Actually someone had the same problem some days ago too. I agreed to clarify the error message.

There's one way to include dot within the package: by doing a native module, i.e. C++ code which links with the graphviz library, if ever it exists. I don't want to go that way. For now, graphviz is in a way a peer dependency, it has to be side installed, and this project can be seen as a plugin for graphviz as it offers a "loader for a graph source that graphviz doesn't recognize natively" (namely a Lerna monorepo). The benefit for plugins as peer dependencies is that the host has it own life, e.g. it can be updated without impacting the plugins. The latest version of Graphviz has been released six days ago, I can't keep track of that and release a new version every time they do. In this case, I admit that npm/yarn doesn't warn about the missing peer dependency and it's sad. As a side note, compiling a native module also requires programs that Node package managers can't handle, a least a toolchain like MSVC on Windows.

Second side note, both the nodejs and the python wrappers for graphviz require that it is independently installed, whereby they could have embedded it, they chose not to do it, I think for the same reasons.

[y-nk]

btw if one is interested into a non graphviz dependent output, you can run this:

#!/usr/bin/env node

const ORG = "@myorg/";

const { execSync } = require("child_process");
const { Buffer } = require("buffer");

const IMAGE_URL = "https://mermaid.ink/img/__base64__";
const JSON_SHELL = {
  code: "",
  mermaid: {
    theme: "default"
  },
  updateDiagram:false,
  updateEditor:false,
  autoSync:true,
}

// lerna does not have any documented nodejs api, so we have to use subprocesses
const getGraphNodes = async (since = false) => {
  let output;

  try {
    output = execSync(`npx lerna list ${since ? "--since" : ""} --all --long --include-dependencies --graph --loglevel=silent`);
  } catch (error) {
    console.info(`No local packages have been found.`);
    process.exit(0);
  }

  return JSON.parse(output.toString());
}

const getUrl = (code) => {
  const payload = { ...JSON_SHELL, code };
  const b64Encoded = Buffer.from(JSON.stringify(payload)).toString("base64");

  return IMAGE_URL.replace("__base64__", b64Encoded);
}

const main = async (since) => {
  const graphNodes = (await getGraphNodes(since)) || {};

  const ids = Object
    .keys(graphNodes)
    .map((name) => `  ${name.replace(ORG, "")}(["${name}"])`);

  const links = Object
    .entries(graphNodes)
    .map(([name, deps]) => ([
      name.replace(ORG, ""),
      deps.filter(dep => dep.startsWith(ORG))
          .map(dep => dep.replace(ORG, ""))
    ]))
    .filter(([_, deps]) => !!deps.length)
    .map(([from, tos]) => tos.map(to => `  ${from}-->${to}`))
    .flat();

  const code = ["flowchart TB", ...ids, ...links].join("\n")
  console.log(getUrl(code));
}

const [since] = process.argv.slice(2);
main(since === "since");

which will output a mermaid link to a png which reflect your deps. i didn't debug it with a complex monorepo, but it seems ok so far.