bc-atlas 0.5.0

package/src/docs/al-ui-source.js

@@ -0,0 +1,484 @@
+// Parses AL UI-test procedures into deterministic documentation data.
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Language, Parser } from "web-tree-sitter";
+
+const AL_TEST_PATTERN = /\[Test\](?:\s*\[[^\]]+\])*\s*procedure\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/giu;
+const TEST_PAGE_PATTERN =
+  /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*TestPage\s+(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))\s*;/gimu;
+const UI_OPERATION_PATTERN =
+  /^\s*([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\.(OpenNew|OpenEdit|OpenView|Close|New|Invoke|SetValue|GoToRecord)\((.*?)\);\s*$/gimu;
+const UI_OPERATION_DETECTOR =
+  /\.(?:OpenNew|OpenEdit|OpenView|Close|New|Invoke|SetValue|GoToRecord)\s*\(/iu;
+const GRAMMAR_PATH = fileURLToPath(
+  new URL("../../vendor/tree-sitter-al.wasm", import.meta.url)
+);
+let languagePromise;
+
+async function getLanguage() {
+  if (!languagePromise) {
+    languagePromise = (async () => {
+      await Parser.init();
+      return Language.load(GRAMMAR_PATH);
+    })();
+  }
+  return languagePromise;
+}
+
+function portablePath(filename) {
+  return filename.replaceAll("\\", "/");
+}
+
+function slug(value) {
+  return value
+    .replace(/([A-Z]+)([A-Z][a-z])/gu, "$1-$2")
+    .replace(/([a-z0-9])([A-Z])/gu, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-|-$/gu, "");
+}
+
+function sourceReference(filename, procedure) {
+  const relativePath = portablePath(path.relative(process.cwd(), filename));
+  return `${relativePath}#${procedure}`;
+}
+
+function splitReference(reference, procedure) {
+  if (procedure) return { filename: reference, procedure };
+  const separator = reference.lastIndexOf("#");
+  if (separator > 0 && reference.slice(0, separator).toLowerCase().endsWith(".al")) {
+    return {
+      filename: reference.slice(0, separator),
+      procedure: reference.slice(separator + 1)
+    };
+  }
+  return { filename: reference, procedure: undefined };
+}
+
+function taggedComments(source) {
+  const tags = new Map();
+  let current = [];
+  for (const line of source.split(/\r?\n/u)) {
+    const comment = line.match(/^\s*\/\/\s?(.*)$/u);
+    if (!comment) {
+      current = [];
+      continue;
+    }
+    const tagged = comment[1].match(/^\[([A-Z]+)\](?:\/\[([A-Z]+)\])?\s*(.*)$/u);
+    if (tagged) {
+      current = [tagged[1], tagged[2]].filter(Boolean);
+      for (const tag of current) {
+        const items = tags.get(tag) ?? [];
+        items.push(tagged[3].trim());
+        tags.set(tag, items);
+      }
+      continue;
+    }
+    if (!current.length || !comment[1].trim()) continue;
+    for (const tag of current) {
+      const items = tags.get(tag);
+      items[items.length - 1] = `${items.at(-1)} ${comment[1].trim()}`;
+    }
+  }
+  return tags;
+}
+
+function commentValues(comments, tag) {
+  return (comments.get(tag) ?? []).map((item) => item.trim()).filter(Boolean);
+}
+
+function humanizeIdentifier(value) {
+  return value
+    .replace(/^"|"$/gu, "")
+    .replaceAll("_", " ")
+    .replace(/([A-Z]+)([A-Z][a-z])/gu, "$1 $2")
+    .replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
+function singular(value) {
+  if (/ies$/iu.test(value)) return value.replace(/ies$/iu, "y");
+  if (/sses$/iu.test(value)) return value.replace(/es$/iu, "");
+  if (/s$/iu.test(value) && !/ss$/iu.test(value)) return value.slice(0, -1);
+  return value;
+}
+
+function exampleValue(argument) {
+  const value = argument.trim();
+  const alString = value.match(/^'(.*)'$/u);
+  if (alString) return { kind: "text", value: alString[1].replaceAll("''", "'") };
+  if (/^(true|false)$/iu.test(value)) {
+    return { kind: "boolean", value: value.toLowerCase() === "true" };
+  }
+  const enumValue = value.match(/::("[^"]+"|[A-Za-z_][A-Za-z0-9_]*)$/u);
+  if (enumValue) return { kind: "choice", value: humanizeIdentifier(enumValue[1]) };
+  if (/^-?\d+(?:\.\d+)?$/u.test(value)) return { kind: "text", value };
+  return { kind: "variable", value: humanizeIdentifier(value) };
+}
+
+function contextPrefix(parts) {
+  if (!parts.length) return "";
+  return `In the **${parts.map(humanizeIdentifier).join(" / ")}** section, `;
+}
+
+function contextual(parts, instruction) {
+  const prefix = contextPrefix(parts);
+  if (prefix) return `${prefix}${instruction}`;
+  return instruction.replace(/^[a-z]/u, (letter) => letter.toUpperCase());
+}
+
+function collectTestPages(source, initial = new Map()) {
+  const testPages = new Map(initial);
+  for (const match of source.matchAll(TEST_PAGE_PATTERN)) {
+    testPages.set(match[1], match[2] ?? humanizeIdentifier(match[3]));
+  }
+  return testPages;
+}
+
+function operationGuidance(match, page) {
+  const parts = match[1].split(".");
+  parts.shift();
+  const operation = match[2];
+  if (operation === "OpenNew") {
+    return {
+      instruction: `Open **${page}** and create a new record.`,
+      creationTarget: singular(page)
+    };
+  }
+  if (operation === "OpenEdit") {
+    return { instruction: `Open **${page}** in edit mode.` };
+  }
+  if (operation === "OpenView") return { instruction: `Open **${page}**.` };
+  if (operation === "GoToRecord") {
+    return {
+      instruction: "Open the record you want to work with.",
+      record: humanizeIdentifier(match[3])
+    };
+  }
+  if (operation === "Close") {
+    return {
+      instruction: `Finish the entry and close **${page}**. Business Central saves the changes.`
+    };
+  }
+  if (operation === "New") {
+    return { instruction: contextual(parts, "add a new line.") };
+  }
+  if (operation === "Invoke") {
+    const action = parts.pop();
+    return { instruction: contextual(parts, `choose **${humanizeIdentifier(action)}**.`) };
+  }
+  if (operation === "SetValue") {
+    const field = humanizeIdentifier(parts.pop());
+    const example = exampleValue(match[3]);
+    if (example.kind === "boolean") {
+      return {
+        instruction: contextual(parts, `turn **${field}** ${example.value ? "on" : "off"}.`)
+      };
+    }
+    if (example.kind === "choice") {
+      return {
+        instruction: contextual(parts, `in **${field}**, select **${example.value}**.`),
+        hasExample: true
+      };
+    }
+    if (example.kind === "text") {
+      return {
+        instruction: contextual(
+          parts,
+          `in **${field}**, enter a suitable value (for example, **${example.value}**).`
+        ),
+        hasExample: true
+      };
+    }
+    return {
+      instruction: contextual(parts, `enter the required value in **${field}**.`)
+    };
+  }
+  return undefined;
+}
+
+function repeatRanges(source) {
+  return [...source.matchAll(/\brepeat\b[\s\S]*?\buntil\b[^;]*;/giu)]
+    .map((match) => ({
+      start: match.index,
+      end: match.index + match[0].length
+    }));
+}
+
+function isConditionalOperation(source, range, operationIndex) {
+  const prefix = source.slice(range.start, operationIndex);
+  const boundary = Math.max(prefix.lastIndexOf(";"), prefix.lastIndexOf("repeat"));
+  return /\bif\b[\s\S]*\bthen\s*$/iu.test(prefix.slice(boundary + 1));
+}
+
+function lowerInstruction(value) {
+  return value
+    .replace(/\.$/u, "")
+    .replace(/^[A-Z]/u, (letter) => letter.toLowerCase());
+}
+
+function repeatedGuidance(source, range, operations) {
+  const record = operations.find(({ detail }) => detail.record)?.detail.record ?? "record";
+  const instructions = operations.map(({ detail, index }, itemIndex) => {
+    let instruction = lowerInstruction(detail.instruction);
+    if (isConditionalOperation(source, range, index)) {
+      instruction = `when applicable, ${instruction}`;
+    } else if (itemIndex === operations.length - 1 && operations.length > 1) {
+      instruction = `then ${instruction}`;
+    }
+    return instruction;
+  });
+  return `For each **${record}** record, ${instructions.join("; ")}.`;
+}
+
+function deriveGuidance(source, knownTestPages = new Map()) {
+  const testPages = collectTestPages(source, knownTestPages);
+
+  const steps = [];
+  let creationTarget;
+  let hasExamples = false;
+  const operations = [];
+  for (const match of source.matchAll(UI_OPERATION_PATTERN)) {
+    const root = match[1].split(".")[0];
+    const page = testPages.get(root);
+    if (!page) continue;
+    const detail = operationGuidance(match, page);
+    if (!detail) continue;
+    if (detail.creationTarget) creationTarget = detail.creationTarget;
+    if (detail.hasExample) hasExamples = true;
+    operations.push({ index: match.index, detail });
+  }
+
+  const ranges = repeatRanges(source);
+  const emittedRanges = new Set();
+  for (const operation of operations) {
+    const range = ranges.find(
+      ({ start, end }) => operation.index >= start && operation.index < end
+    );
+    if (!range) {
+      steps.push(operation.detail.instruction);
+      continue;
+    }
+    if (emittedRanges.has(range)) continue;
+    emittedRanges.add(range);
+    steps.push(repeatedGuidance(
+      source,
+      range,
+      operations.filter(({ index }) => index >= range.start && index < range.end)
+    ));
+  }
+
+  return {
+    steps,
+    hasExamples,
+    creationTarget,
+    title: creationTarget ? `Create a new ${creationTarget}` : undefined,
+    goal: creationTarget ? `Create a new ${creationTarget}.` : undefined
+  };
+}
+
+async function procedureSources(source) {
+  const language = await getLanguage();
+  const parser = new Parser();
+  parser.setLanguage(language);
+  const tree = parser.parse(source);
+  const procedures = new Map();
+  const visit = (node) => {
+    if (node.type === "procedure") {
+      const nameNode = node.childForFieldName("name");
+      if (nameNode) {
+        const name = source.slice(nameNode.startIndex, nameNode.endIndex).toLowerCase();
+        procedures.set(name, source.slice(node.startIndex, node.endIndex));
+      }
+    }
+    for (const child of node.namedChildren) visit(child);
+  };
+  visit(tree.rootNode);
+  return procedures;
+}
+
+function bareProcedureCalls(source) {
+  return [...source.matchAll(
+    /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\([^;]*\);\s*$/gimu
+  )];
+}
+
+function helperContainsUi(name, procedures, visiting = new Set(), depth = 0) {
+  if (depth >= 8 || visiting.has(name)) return false;
+  const source = procedures.get(name);
+  if (!source) return false;
+  if (UI_OPERATION_DETECTOR.test(source)) return true;
+  const next = new Set(visiting).add(name);
+  return bareProcedureCalls(source).some((match) =>
+    helperContainsUi(match[1].toLowerCase(), procedures, next, depth + 1)
+  );
+}
+
+function expandUiHelpers(source, procedures, visiting = new Set(), depth = 0) {
+  if (depth >= 8) return { source, expanded: [] };
+  const expanded = [];
+  const value = source.replace(
+    /^(\s*)([A-Za-z_][A-Za-z0-9_]*)\s*\([^;]*\);\s*$/gimu,
+    (statement, indentation, rawName) => {
+      const name = rawName.toLowerCase();
+      if (
+        visiting.has(name) ||
+        !procedures.has(name) ||
+        !helperContainsUi(name, procedures)
+      ) return statement;
+      const nested = expandUiHelpers(
+        procedures.get(name),
+        procedures,
+        new Set(visiting).add(name),
+        depth + 1
+      );
+      expanded.push(rawName, ...nested.expanded);
+      return nested.source
+        .split(/\r?\n/u)
+        .map((line) => `${indentation}${line}`)
+        .join("\n");
+    }
+  );
+  return { source: value, expanded: [...new Set(expanded)] };
+}
+
+function whenBlocks(source) {
+  const markers = [...source.matchAll(
+    /^\s*\/\/\s*\[WHEN\](?:\/\[THEN\])?\s*(.*)$/gimu
+  )].filter((match) => match[1].trim());
+  return markers.map((marker, index) => {
+    const afterMarker = marker.index + marker[0].length;
+    const nextMarker = source.slice(afterMarker).search(
+      /^\s*\/\/\s*\[(?:WHEN|THEN)\](?:\/\[[A-Z]+\])?/gimu
+    );
+    const end = nextMarker < 0 ? source.length : afterMarker + nextMarker;
+    return {
+      title: marker[1].trim(),
+      source: source.slice(afterMarker, end),
+      index
+    };
+  });
+}
+
+function guidePrerequisites(items, creationTarget) {
+  return items.map((item) => {
+    if (creationTarget && /^No .+ exists yet\.$/iu.test(item)) {
+      return `Make sure the ${creationTarget} you want to create does not already exist.`;
+    }
+    return item;
+  });
+}
+
+function guideExpectedResults(items, creationTarget) {
+  return items.map((item) => {
+    if (creationTarget && /^The .+ persisted with the values entered in the list\.$/iu.test(item)) {
+      return `The ${creationTarget} is saved with the values you entered.`;
+    }
+    return item;
+  });
+}
+
+async function parseAlUiTest(source, filename, requestedProcedure) {
+  const tests = [...source.matchAll(AL_TEST_PATTERN)];
+  if (!tests.length) throw new Error(`${path.basename(filename)} contains no [Test] procedures`);
+
+  const available = tests.map((match) => match[1]);
+  const selected = requestedProcedure
+    ? tests.find((match) => match[1].toLowerCase() === requestedProcedure.toLowerCase())
+    : tests.length === 1 ? tests[0] : undefined;
+  if (!selected) {
+    if (requestedProcedure) {
+      throw new Error(
+        `${path.basename(filename)} has no [Test] procedure ${requestedProcedure}; available: ${available.join(", ")}`
+      );
+    }
+    throw new Error(
+      `${path.basename(filename)} contains multiple [Test] procedures; select one with --procedure: ${available.join(", ")}`
+    );
+  }
+
+  const remainder = source.slice(selected.index);
+  const boundary = remainder.slice(selected[0].length)
+    .search(/\n {4}(?=#(?:end)?region\b|\[[A-Za-z])/u);
+  const end = boundary < 0
+    ? source.length
+    : selected.index + selected[0].length + boundary;
+  const sourceText = source.slice(selected.index, end).trim().replace(/\n\s*\}\s*$/u, "");
+  const comments = taggedComments(sourceText);
+  const scenarios = commentValues(comments, "SCENARIO");
+  if (!scenarios.length) {
+    throw new Error(`${selected[1]} must have a // [SCENARIO] comment`);
+  }
+
+  const goal = scenarios.join(" ").trim();
+  const expected = commentValues(comments, "THEN");
+  const procedures = await procedureSources(source);
+  const expanded = expandUiHelpers(sourceText, procedures);
+  const testPages = collectTestPages(expanded.source);
+  const guidance = deriveGuidance(expanded.source, testPages);
+  const guideSections = whenBlocks(sourceText).map((section) => {
+    const sectionExpansion = expandUiHelpers(section.source, procedures);
+    return {
+      title: section.title,
+      steps: deriveGuidance(sectionExpansion.source, testPages).steps,
+      expandedHelpers: sectionExpansion.expanded
+    };
+  });
+  const prerequisites = commentValues(comments, "GIVEN");
+  const permissions = [...new Set([
+    ...commentValues(comments, "PERMISSIONS"),
+    ...commentValues(comments, "PERMISSION")
+  ])];
+  const expectedResults = expected.length ? expected : [goal];
+  return {
+    id: slug(selected[1]),
+    title: guidance.title ?? goal.replace(/[.\s]+$/u, ""),
+    goal,
+    guideGoal: guidance.goal ?? goal,
+    guideSteps: guidance.steps,
+    guideSections,
+    expandedHelpers: expanded.expanded,
+    hasExampleValues: guidance.hasExamples,
+    permissions,
+    prerequisites,
+    guidePrerequisites: guidePrerequisites(prerequisites, guidance.creationTarget),
+    actions: commentValues(comments, "WHEN"),
+    expected: expectedResults,
+    guideExpected: guideExpectedResults(expectedResults, guidance.creationTarget),
+    features: commentValues(comments, "FEATURE"),
+    procedure: selected[1],
+    sourceText,
+    sourceHash: createHash("sha256").update(sourceText).digest("hex")
+  };
+}
+
+export async function loadAlUiTest(reference, options = {}) {
+  const selected = splitReference(reference, options.procedure);
+  const absolutePath = path.resolve(selected.filename);
+  if (path.extname(absolutePath).toLowerCase() !== ".al") {
+    throw new Error(`documentation source must be an AL UI-test file: ${absolutePath}`);
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(absolutePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") throw new Error(`AL UI-test source not found: ${absolutePath}`);
+    throw new Error(`cannot read AL UI-test source ${absolutePath}: ${error.message}`);
+  }
+
+  const value = await parseAlUiTest(content, absolutePath, selected.procedure);
+  return {
+    path: absolutePath,
+    relativePath: portablePath(path.relative(process.cwd(), absolutePath)),
+    reference: sourceReference(absolutePath, value.procedure),
+    value
+  };
+}
+
+export function generatedDocumentationPath(value, outputDirectory = "docs/generated") {
+  return path.resolve(outputDirectory, `${value.id}.md`);
+}

package/src/docs/cli.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { writeDocumentation } from "./markdown.js";
+import { loadAlUiTest } from "./al-ui-source.js";
+
+const HELP = `BC Atlas docs - generate Markdown from an AL UI test
+
+Usage:
+  bca docs generate [options] <ui-test.al>
+
+Options:
+      --procedure <name>     [Test] procedure to document
+      --output-dir <path>    Markdown output directory (default: docs/generated)
+  -h, --help                 Show help
+`;
+
+const OPTIONS = {
+  procedure: { type: "string" },
+  "output-dir": { type: "string" },
+  help: { type: "boolean", short: "h" }
+};
+
+export async function docsMain(args) {
+  if (args[0] === "--help" || args[0] === "-h") return console.log(HELP);
+  const command = args[0];
+  const { values, positionals } = parseArgs({
+    args: args.slice(1),
+    allowPositionals: true,
+    strict: true,
+    options: OPTIONS
+  });
+  if (values.help || !command) return console.log(HELP);
+  if (command !== "generate") throw new Error(`unknown docs command: ${command}`);
+  if (positionals.length !== 1) {
+    throw new Error("docs generate expects one AL UI-test file");
+  }
+
+  const source = await loadAlUiTest(positionals[0], {
+    procedure: values.procedure
+  });
+  const filename = await writeDocumentation(source, values["output-dir"]);
+  console.log(`wrote ${path.relative(process.cwd(), filename).replaceAll("\\", "/")}`);
+}
+
+export { HELP as DOCS_HELP };

package/src/docs/markdown.js

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { generatedDocumentationPath } from "./al-ui-source.js";
+
+function bullets(items) {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function renderDocumentation(source) {
+  const { value } = source;
+  const procedure = value.guideSteps.length ? value.guideSteps : value.actions;
+  const sourceFile = path.basename(source.path);
+  const beforeYouStart = [
+    ...value.permissions.map((permission) => `Required permission: **${permission}**`),
+    ...value.guidePrerequisites
+  ];
+  const lines = [
+    `<!-- Generated by BC Atlas docs from ${sourceFile}#${value.procedure}. Do not edit this file. -->`,
+    `<!-- Source SHA-256: ${value.sourceHash} -->`,
+    "",
+    `# ${value.title}`,
+    "",
+    `Use this guide to ${value.guideGoal.replace(/^[A-Z]/u, (letter) => letter.toLowerCase()).replace(/\.$/u, "")}.`,
+    ""
+  ];
+
+  if (beforeYouStart.length) {
+    lines.push("## Before you start", "", bullets(beforeYouStart), "");
+  }
+  if (procedure.length) {
+    lines.push("## Steps", "");
+    if (value.hasExampleValues) {
+      lines.push(
+        "> The values below are examples from the automated UI test. Use values appropriate for your environment.",
+        ""
+      );
+    }
+    if (value.guideSections?.length) {
+      for (const [index, section] of value.guideSections.entries()) {
+        lines.push(`${index + 1}. ${section.title}`);
+        for (const step of section.steps) lines.push(`   - ${step}`);
+      }
+      lines.push("");
+    } else {
+      lines.push(
+        ...procedure.map((action, index) => `${index + 1}. ${action}`),
+        ""
+      );
+    }
+  }
+  lines.push(
+    "## What should happen",
+    "",
+    bullets(value.guideExpected),
+    "",
+    "<details>",
+    "<summary>Source and verification</summary>",
+    "",
+    `- File: \`${sourceFile}\``,
+    `- Function: \`${value.procedure}\``,
+    `- Source SHA-256: \`${value.sourceHash}\``,
+    "",
+    "</details>",
+    ""
+  );
+  return lines.join("\n");
+}
+
+export async function writeDocumentation(source, outputDirectory) {
+  const filename = generatedDocumentationPath(
+    source.value,
+    outputDirectory ?? process.env.BC_DOCS_OUTPUT ?? "docs/generated"
+  );
+  await fs.mkdir(path.dirname(filename), { recursive: true });
+  await fs.writeFile(filename, renderDocumentation(source));
+  return filename;
+}

package/src/insights.js

@@ -0,0 +1,102 @@
+function wildcard(pattern) {
+  const escaped = String(pattern)
+    .replace(/[.+^${}()|[\]\\]/gu, "\\$&")
+    .replaceAll("**", "\u0000")
+    .replaceAll("*", ".*")
+    .replaceAll("\u0000", ".*");
+  return new RegExp(`^${escaped}$`, "iu");
+}
+
+function findCycles(objects, edges) {
+  const keys = new Set(objects.map(({ key }) => key));
+  const graph = new Map([...keys].map((key) => [key, []]));
+  for (const edge of edges) {
+    if (edge.to && keys.has(edge.from) && keys.has(edge.to)) {
+      graph.get(edge.from).push(edge.to);
+    }
+  }
+
+  let index = 0;
+  const stack = [];
+  const state = new Map();
+  const cycles = [];
+  function connect(key) {
+    const entry = { index, low: index, onStack: true };
+    index++;
+    state.set(key, entry);
+    stack.push(key);
+    for (const target of graph.get(key)) {
+      if (!state.has(target)) {
+        connect(target);
+        entry.low = Math.min(entry.low, state.get(target).low);
+      } else if (state.get(target).onStack) {
+        entry.low = Math.min(entry.low, state.get(target).index);
+      }
+    }
+    if (entry.low !== entry.index) return;
+    const component = [];
+    let current;
+    do {
+      current = stack.pop();
+      state.get(current).onStack = false;
+      component.push(current);
+    } while (current !== key);
+    if (component.length > 1 || graph.get(key).includes(key)) cycles.push(component.sort());
+  }
+  for (const key of keys) if (!state.has(key)) connect(key);
+  return cycles.sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+export function addInsights(model, forbidden = []) {
+  const degree = new Map(model.objects.map(({ key }) => [key, { incoming: 0, outgoing: 0 }]));
+  for (const edge of model.edges) {
+    if (degree.has(edge.from)) degree.get(edge.from).outgoing++;
+    if (edge.to && degree.has(edge.to)) degree.get(edge.to).incoming++;
+  }
+  const hubs = [...degree]
+    .map(([key, value]) => ({ key, ...value, total: value.incoming + value.outgoing }))
+    .filter(({ total }) => total > 0)
+    .sort((a, b) => b.total - a.total || a.key.localeCompare(b.key))
+    .slice(0, 10);
+  const orphans = [...degree]
+    .filter(([, value]) => value.incoming + value.outgoing === 0)
+    .map(([key]) => key)
+    .sort();
+  const diagnostics = [...model.diagnostics];
+  const byKey = new Map(model.objects.map((object) => [object.key, object]));
+
+  for (const rule of forbidden) {
+    if (!rule.from || !rule.to) continue;
+    const fromPattern = wildcard(rule.from);
+    const toPattern = wildcard(rule.to);
+    for (const edge of model.edges) {
+      const from = byKey.get(edge.from);
+      const to = byKey.get(edge.to);
+      if (!from || !to) continue;
+      const fromName = `${from.namespace}:${from.type}:${from.name}`;
+      const toName = `${to.namespace}:${to.type}:${to.name}`;
+      if (fromPattern.test(fromName) && toPattern.test(toName)) {
+        diagnostics.push({
+          severity: rule.severity ?? "warning",
+          code: "forbidden-dependency",
+          message: rule.message ?? `Forbidden dependency from ${fromName} to ${toName}`,
+          file: edge.location?.file ?? from.file,
+          line: edge.location?.line
+        });
+      }
+    }
+  }
+
+  return {
+    ...model,
+    diagnostics,
+    insights: {
+      unresolvedEdges: model.edges.filter(({ to }) => !to).length,
+      orphans,
+      hubs,
+      cycles: findCycles(model.objects, model.edges)
+    }
+  };
+}
+
+export const testing = { findCycles };