@jpeakai/mermaidjs-lint 0.2.0 → 0.3.0

package/src/parse/stats.ts

@@ -599,17 +599,20 @@ function adaptMindmap(db: AnyDb): Structure {
   return { nodeIds: labels, edges: Math.max(0, labels.length - 1), subgraphNames: [], maxDepth };
 }
 
+type QuadrantText = { text?: string } | string | undefined;
 interface QuadrantData {
-  quadrants?: Array<{ text?: { text?: string } | string }>;
+  quadrants?: Array<{ text?: QuadrantText }>;
+  points?: Array<{ text?: QuadrantText }>;
 }
+// A node is every plotted point, plus every quadrant that carries a label. The
+// four quadrant boxes are always drawn, so an unlabelled one adds nothing to
+// read, while every point is a mark the reader must place.
 function adaptQuadrantChart(db: AnyDb): Structure {
   const data = callGetter<QuadrantData | null>(db, "getQuadrantData");
-  const quadrants = data?.quadrants ?? [];
-  const labels = quadrants.map((q) => {
-    const t = q.text;
-    return typeof t === "string" ? t : (t?.text ?? "");
-  });
-  return { nodeIds: labels, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const textOf = (t: QuadrantText): string => (typeof t === "string" ? t : (t?.text ?? ""));
+  const quadrants = (data?.quadrants ?? []).map((q) => textOf(q.text)).filter((t) => t.trim() !== "");
+  const points = (data?.points ?? []).map((p, i) => textOf(p.text) || `point_${i}`);
+  return { nodeIds: [...quadrants, ...points], edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 
 function adaptRequirement(db: AnyDb): Structure {
@@ -639,36 +642,56 @@ function adaptSankey(db: AnyDb): Structure {
 interface StateNode {
   id?: string;
   type?: string;
+  isGroup?: boolean;
+  parentId?: string;
 }
 interface StateEdge {
   id1?: string;
   id2?: string;
 }
+// A composite state (`state A { ... }`) is a group that holds other states,
+// so it counts as a subgraph too, and its nesting depth is read from each
+// state's parentId chain. It stays a node as well, because it is drawn as a
+// labelled state.
 function adaptState(db: AnyDb): Structure {
   // stateDiagram db exposes data on direct properties.
   const nodes = (db.nodes as StateNode[] | undefined) ?? [];
   const edges = (db.edges as StateEdge[] | undefined) ?? [];
+  const groups = nodes.filter((n) => n.isGroup === true);
+  const parentOf = new Map(nodes.map((n) => [n.id ?? "", n.parentId]));
+  let maxDepth = 0;
+  for (const g of groups) {
+    let depth = 1;
+    const seen = new Set<string>();
+    for (let cur = g.parentId; cur && !seen.has(cur); cur = parentOf.get(cur)) {
+      seen.add(cur);
+      depth++;
+    }
+    maxDepth = Math.max(maxDepth, depth);
+  }
   return {
     nodeIds: nodes.map((n) => n.id ?? ""),
     edges: edges.length,
-    subgraphNames: [],
-    maxDepth: 0,
+    subgraphNames: groups.map((g) => g.id ?? ""),
+    maxDepth,
   };
 }
 
 interface TimelineTask {
   task?: string;
   section?: string;
+  events?: string[];
 }
 interface TimelineSection {
   sectionName?: string;
   section?: string;
 }
 function adaptTimeline(db: AnyDb): Structure {
+  // Every period and every event under it is a box on the page.
   const tasks = callGetter<TimelineTask[]>(db, "getTasks") ?? [];
   const sections = callGetter<TimelineSection[]>(db, "getSections") ?? [];
   return {
-    nodeIds: tasks.map((t) => t.task ?? ""),
+    nodeIds: tasks.flatMap((t) => [t.task ?? "", ...(t.events ?? []).map((e) => `${t.task ?? ""}: ${e}`)]),
     edges: 0,
     subgraphNames: sections.map((s) => s.sectionName ?? s.section ?? ""),
     maxDepth: sections.length > 0 ? 1 : 0,
@@ -714,11 +737,16 @@ function adaptVenn(db: AnyDb): Structure {
 
 interface XYChartData {
   xAxis?: { categories?: string[] };
+  plots?: Array<{ data?: unknown[] }>;
 }
+// A node is an x position: a category, or, on a numeric x-axis, a point of the
+// longest series.
 function adaptXychart(db: AnyDb): Structure {
   const data = callGetter<XYChartData | null>(db, "getXYChartData");
   const categories = data?.xAxis?.categories ?? [];
-  return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  if (categories.length > 0) return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const longest = Math.max(0, ...(data?.plots ?? []).map((p) => p.data?.length ?? 0));
+  return { nodeIds: Array.from({ length: longest }, (_, i) => `x_${i}`), edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 
 function subgraphNestingDepth(subGraphs: Array<{ id?: string; nodes?: string[] }>): number {

package/src/plugins/contract.ts

@@ -37,5 +37,7 @@ export interface Plugin {
 
 // A one-word category and a namespace or rule key, as they appear in an id.
 export const CATEGORY_WORD = /^[a-z]+$/;
-export const NAMESPACE = /^[a-z][a-z0-9-]*$/;
-export const RULE_KEY = /^[a-z][a-z0-9-]*$/;
+// Lower-case words joined by single hyphens: no leading, trailing or doubled
+// hyphen, so `house-` and `a-` are refused.
+export const NAMESPACE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const RULE_KEY = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;

package/src/plugins/discover.ts

@@ -4,14 +4,16 @@
 // names a config lists. A directory of node_modules is never scanned, so only
 // what the project chose to depend on can run.
 //
-// A declared package that is not installed is a failure the caller decides
-// how to treat, not an exception, so a lenient run can skip it and a
-// validating run can report every one. A malformed package.json throws.
+// A declared package that is not installed, or whose package.json is not a
+// JSON object, is a failure the caller decides how to treat, not an exception,
+// so a lenient run can skip it and a validating run can report every one. A
+// malformed project package.json throws PackageJsonError, except in a run with
+// plugins off, which loads no package it names.
 
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 import type { Config } from "../config.ts";
-import { PluginNotInstalledError } from "../errors.ts";
+import { PackageJsonError, PluginLoadError, PluginNotInstalledError, PluginSourceError } from "../errors.ts";
 
 export type SourceKind = "local" | "package" | "config";
 
@@ -23,10 +25,16 @@ export interface PluginSource {
   path: string;
 }
 
+export interface UnresolvedSource {
+  kind: SourceKind;
+  error: PluginLoadError;
+}
+
 export interface Discovery {
   sources: PluginSource[];
-  // Sources found but not resolvable, such as a declared package that is not installed.
-  failures: PluginNotInstalledError[];
+  // Sources found but not resolvable, such as a declared package that is not
+  // installed, each with the kind of source that named it.
+  failures: UnresolvedSource[];
 }
 
 export const LOCAL_RULES = join(".mermaidjs-lint", "rules");
@@ -49,7 +57,7 @@ const readJson = async (path: string): Promise<Record<string, unknown> | null> =
   } catch {
     // Reported below with the path.
   }
-  throw new Error(`${path} is not a JSON object`);
+  throw new PackageJsonError(path);
 };
 
 // Every extension a local rule may have. Whether the runtime can import a
@@ -101,15 +109,27 @@ const entryOf = (pkg: Record<string, unknown>): string => {
 export const resolvePackage = async (root: string, name: string): Promise<string> => {
   for (let dir = resolve(root); ; dir = dirname(dir)) {
     const folder = join(dir, "node_modules", name);
-    const pkg = await readJson(join(folder, "package.json"));
+    let pkg: Record<string, unknown> | null;
+    try {
+      pkg = await readJson(join(folder, "package.json"));
+    } catch (err) {
+      if (!(err instanceof PackageJsonError)) throw err;
+      throw new PluginSourceError(name, `its package.json at ${err.file} is not a JSON object`);
+    }
     if (pkg) return join(folder, entryOf(pkg));
     if (dirname(dir) === dir) break;
   }
   throw new PluginNotInstalledError(name, root);
 };
 
-const declaredPlugins = async (root: string): Promise<string[]> => {
-  const pkg = await readJson(join(root, "package.json"));
+const declaredPlugins = async (root: string, tolerateBadManifest: boolean): Promise<string[]> => {
+  let pkg: Record<string, unknown> | null;
+  try {
+    pkg = await readJson(join(root, "package.json"));
+  } catch (err) {
+    if (tolerateBadManifest && err instanceof PackageJsonError) return [];
+    throw err;
+  }
   if (!pkg) return [];
   const names = ["dependencies", "devDependencies", "optionalDependencies"].flatMap((field) => {
     const deps = pkg[field];
@@ -118,18 +138,21 @@ const declaredPlugins = async (root: string): Promise<string[]> => {
   return [...new Set(names)].filter((name) => PACKAGE_PATTERN.test(name)).sort();
 };
 
-export const discoverSources = async (root: string, config: Config): Promise<Discovery> => {
+// A run with plugins off loads nothing, so a malformed project package.json,
+// which could only name packages that run will not load, does not stop it.
+export const discoverSources = async (root: string, config: Config, pluginsOff = false): Promise<Discovery> => {
   const sources = await localSources(root);
-  const failures: PluginNotInstalledError[] = [];
+  const failures: UnresolvedSource[] = [];
   const add = async (kind: SourceKind, spec: string, resolveIt: () => Promise<string>): Promise<void> => {
     try {
       sources.push({ kind, spec, path: await resolveIt() });
     } catch (err) {
-      if (!(err instanceof PluginNotInstalledError)) throw err;
-      failures.push(err);
+      if (!(err instanceof PluginLoadError)) throw err;
+      failures.push({ kind, error: err });
     }
   };
-  for (const name of await declaredPlugins(root)) await add("package", name, () => resolvePackage(root, name));
+  for (const name of await declaredPlugins(root, pluginsOff))
+    await add("package", name, () => resolvePackage(root, name));
   for (const spec of config.plugins || []) {
     const path = spec.startsWith(".") || isAbsolute(spec);
     await add("config", spec, () => (path ? Promise.resolve(resolve(root, spec)) : resolvePackage(root, spec)));

package/src/plugins/index.ts

@@ -34,7 +34,7 @@ export interface PluginSet {
 }
 
 export const loadPlugins = async (root: string, config: Config, mode: PluginMode): Promise<PluginSet> => {
-  const { sources: found, failures: unresolved } = await discoverSources(root, config);
+  const { sources: found, failures: unresolved } = await discoverSources(root, config, mode === "off");
   const set: PluginSet = {
     rules: [],
     categories: new Map(BUILTIN_CATEGORIES),
@@ -42,14 +42,16 @@ export const loadPlugins = async (root: string, config: Config, mode: PluginMode
     skipped: [],
     failures: [],
   };
-  if (mode === "off") return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((e) => e.source)] };
+  if (mode === "off") {
+    return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((u) => u.error.source)] };
+  }
 
   // Strict stops at the first failure. The others record it and carry on.
   const settle = (error: PluginLoadError, kind: SourceKind): void => {
     if (mode === "strict") throw error;
     if (!set.failures.some((f) => f.source === error.source)) set.failures.push({ source: error.source, kind, error });
   };
-  for (const error of unresolved) settle(error, "package");
+  for (const { error, kind } of unresolved) settle(error, kind);
 
   const loaded: { plugin: Plugin; kind: SourceKind; spec: string }[] = [];
   const locals = found.filter((s) => s.kind === "local");

package/src/plugins/load.ts

@@ -49,6 +49,9 @@ const importModule = async (source: PluginSource, runtime?: RuntimeInfo): Promis
 
 const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]"]);
 
+// Option names every rule shares with the built-ins. See checkRule.
+const RESERVED_OPTIONS = ["preset", "profile"] as const;
+
 // Checks one rule's declaration and returns it, so a bad rule fails at load
 // rather than the first time it runs.
 const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
@@ -80,6 +83,18 @@ const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<str
     if (!valid) {
       throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
     }
+    // preset and profile keep their built-in meaning for every rule: the
+    // config checks the value against the built-in names, and --preset and
+    // --profile overwrite it. A rule may declare one to follow the run's
+    // setting, as a string, but cannot give the name another meaning.
+    for (const name of RESERVED_OPTIONS) {
+      if (name in options && (options as Record<string, unknown>)[name] !== "string") {
+        throw new PluginContractError(
+          spec,
+          `${where} declares option "${name}" as ${String((options as Record<string, unknown>)[name])}, but "${name}" is reserved for the built-in ${name}, which is a string set by --${name}; declare it as "string" to follow the run's ${name}, or pick another name`,
+        );
+      }
+    }
   }
   return raw as unknown as PluginRule;
 };
@@ -148,7 +163,23 @@ export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo):
   const categories: Record<string, string> = {};
   const owner: Record<string, string> = {};
   const loaded: { key: string; source: PluginSource; raw: unknown }[] = [];
+  // A rule's key is its file's base name, so two files with one base name
+  // (house-x.js and house-x.mjs) would claim one rule. Neither is imported,
+  // and the failure names both, rather than one silently replacing the other.
+  const keyOf = (source: PluginSource): string => basename(source.path, extname(source.path));
+  const byKey = new Map<string, PluginSource[]>();
+  for (const source of sources) byKey.set(keyOf(source), [...(byKey.get(keyOf(source)) ?? []), source]);
+  for (const [key, group] of byKey) {
+    if (group.length < 2) continue;
+    fail(
+      new PluginContractError(
+        (group[0] as PluginSource).spec,
+        `rule "${key}" is defined by more than one file: ${group.map((s) => s.spec).join(", ")}; each rule comes from exactly one file, so rename or remove all but one`,
+      ),
+    );
+  }
   for (const source of sources) {
+    if ((byKey.get(keyOf(source))?.length ?? 0) > 1) continue;
     try {
       const mod = await importModule(source, runtime);
       if (mod.default === undefined) {
@@ -166,7 +197,7 @@ export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo):
         categories[word] = description;
         owner[word] = source.spec;
       }
-      loaded.push({ key: basename(source.path, extname(source.path)), source, raw: mod.default });
+      loaded.push({ key: keyOf(source), source, raw: mod.default });
     } catch (err) {
       fail(err);
     }

package/src/project.ts

@@ -43,6 +43,8 @@ export interface SetupOptions {
 }
 
 export interface Setup {
+  // The project root the config and plugins were found from.
+  root: string;
   registry: Registry;
   skipped: string[];
   // Plugins left out because they failed. Empty unless the run was lenient or collecting.
@@ -84,5 +86,5 @@ export const setUp = async ({
     // rather than failing the run. A built-in id never is.
     ignoreUnknownPluginIds: mode !== "strict",
   });
-  return { registry, skipped: plugins.skipped, failures: plugins.failures };
+  return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };