bc-atlas 0.8.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,137 @@ All notable changes to BC Atlas will be documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 follows [Semantic Versioning](https://semver.org/).
 
+## 0.11.0 - 2026-10-29
+
+### Changed
+
+- Dependency explorer: without an architecture, objects are colored and
+  grouped by their relation clusters (the clustering of the architecture
+  proposal) instead of one color per app. Clusters float like galaxies
+  around their app candidate and their app, clusters of one app candidate
+  share a family of colors, each cluster shows its name at its center, links
+  inside a cluster take its color, and links between groups are faint arcs.
+  Labels that would overlap a more important one are hidden. On a dark
+  background the graph glows (**Glow** turns it off); dense graphs get
+  fainter links and less glow.
+- Dependency explorer: a **Clusters** filter lists the clusters by app
+  candidate; **only** shows one cluster (or one app) and frames it, and so
+  does a click on a cluster name in the graph or in the legend, which lists
+  the largest clusters on screen. A second click or `Esc` shows all again.
+  Neighbors in other clusters stay visible in gray.
+- Dependency explorer: the glow fades when you zoom in close, so large
+  spheres no longer bloom into white discs.
+- The graph document (`bca export --view explorer --format json`) carries
+  the clusters: `clusters` with name, size, and app candidate, and `cluster`
+  on every workspace object.
+- Clustering by relations is about twice as fast (4.5 instead of 9 seconds for
+  the Base Application) with the same result, and the explorer and the
+  architecture proposal share it: after a saved file, only the apps and
+  modules whose objects or relations changed are clustered again.
+- The explorer's browser bundle (3d-force-graph with three.js and its bloom
+  pass) is built into `vendor/graph-viewer.js` (`npm run update:graph-vendor`);
+  3d-force-graph is no longer installed with the package.
+
+### Fixed
+
+- `bca docs set` and `unset` understand Microsoft's tags: `[SCENARIO 218101]`
+  and `[FEATURE] [A] [B]` are edited in place (the work item stays, one
+  feature of a list can be removed), setting `SCENARIO` again replaces the
+  line instead of adding a second one, and a value with a line break is
+  rejected instead of being written as AL code. Removing a feature that is
+  set for the whole codeunit says to change it in `OnRun`.
+- Markdown guides and test cases show the author's text as written: `<Posted>`,
+  `<b>`, `*now*`, `_done_`, and `|` are escaped instead of disappearing or
+  turning into formatting.
+
+## 0.10.0 - 2026-10-29
+
+The npm package skips 0.9.0 so it shares its version with the VS Code
+extension, whose previous release was 0.9.0.
+
+### Added
+
+- Shared core: objects that many components use but none owns (setup
+  tables, master data) form a component of their own instead of gluing the
+  others together.
+- App candidates and namespaces: components that are coupled more to each
+  other than to the rest could become one app together. Every proposed
+  component gets a role (app, component, shared core) and a suggested
+  namespace, in the JSON (`proposal.recommendations`), the reports, the
+  component's description, and the Architecture page.
+- `id:50100..50199` selects objects by ID range; proposals use it for code
+  without namespaces or functional folders.
+- A page per component (click it on the Architecture page): its role, layer,
+  the components it may use, suggested namespace, app candidate, and
+  selectors; the groups inside it (sub-domains clustered by coupling and
+  named after their namespace, folder, or shared words); a graph of its
+  objects with one island per group and, on request, its links to other
+  components in green (allowed) and red (wrong way); per other component
+  whether it may be used and how often it is; every object; and its work
+  items. Also in the exported app.
+- Dependencies between components, should vs. is: a map of the components in
+  their layers with green arrows for allowed and red arrows for wrong-way
+  dependencies, and a matrix that tints every pair by the rules and counts
+  today's object links in it.
+- `bca docs` turns more TestPage code into steps: `Field.Value :=`,
+  `Filter.SetFilter`, `GoToKey`, the `OK`, `Cancel`, `Yes`, and `No` buttons,
+  `First`/`Last`/`Next`/`Previous`, `Lookup`, `Drilldown`, `AssistEdit`,
+  `Page.Trap()` ("The ... page opens."), `asserterror` ("Business Central
+  shows an error message."), calls over several lines, and the pages and
+  confirmations a test answers in `[ModalPageHandler]`, `[PageHandler]`,
+  `[RequestPageHandler]`, and `[ConfirmHandler]` procedures ("If the ... page
+  opens, ...").
+
+### Changed
+
+- The architecture proposal comes from the relations, not from namespaces.
+  Relations are typed (structural, data, behavioral, loose, administrative)
+  and weighted; inside each app or module, the objects that are coupled more
+  to each other than to the rest form a component (the best of several
+  Louvain runs, refined object by object, with today's namespaces and
+  folders competing as candidates). It works the same for apps without
+  namespaces (type folders, ID blocks) and for a mix. `--group-by coupling`
+  is now the same as `auto`; `namespace` and `folder` let the structure
+  decide and place objects without one by their relations.
+- A page or query and its source table are a relation of their own
+  (`source`, weight 4) instead of a read.
+- VS Code and `bca export --view app` keep the parse results of every AL file
+  on disk (`BCA_CACHE_DIR`, default `<temp>/bc-atlas/parse`) and across
+  changes, so reopening a project or saving a file parses only what changed.
+  The Docs page and the explorer reuse them instead of parsing the app again.
+  On a 2,931-object app the overview opens in about 8 seconds instead of 15,
+  and the Docs page in about 11 instead of 25.
+- The npm package and the VS Code extension are released under one version
+  number from now on, starting with 0.10.0; `npm run version:set -- <version>`
+  sets both, and the tests and publish workflows refuse a mismatch.
+- Dependencies: zod 4.6.7, web-tree-sitter 0.27.1, and the MCP SDK 2.4.0.
+
+### Fixed
+
+- The report no longer writes an absolute path into README.md when a view has
+  too many nodes for the bundled SVG renderer: it keeps the view as D2, links
+  it relative to the README, removes an SVG left by an earlier run, and the
+  MCP report tool marks it `d2Only`.
+- Opening a scenario or use case on the Docs page no longer leaves the page
+  blank in VS Code (or loads the whole app into the frame in an exported
+  app): the guide is embedded through `srcdoc`, where `#links` resolve
+  against the host page, so it now scrolls to the target itself.
+- `bca docs` reads AL tests written the way Microsoft writes the Business
+  Central tests: `[SCENARIO 218101]` with a work item number (kept as a
+  reference), `[FEATURE] [Sales] [Invoice]` lists (`[UI]` and `[UT]` are left
+  out), the codeunit's `[FEATURE]` in its `OnRun` trigger, and `[VERIFY]` as
+  an expected result. Such test codeunits used to give no scenarios at all.
+- A documented test ends where its procedure ends: tags and TestPage calls of
+  helper procedures after it (and, for the last test, the codeunit's global
+  variables) no longer leak into its guide and its fingerprint.
+- Directory runs of `bca docs` leave out `[SCENARIO]` tests without any UI
+  step (unless they have a `[DOC-ID]`) and report how many; they used to
+  become empty guides.
+- Guides for descriptive scenarios ("Users can post ...") no longer read
+  "Use this guide to users can ...", empty values no longer show as `****`,
+  the note about example values only appears when the steps show any, and
+  test case tables keep the context of loops and dialogs in one row.
+
 ## 0.8.0 - 2026-10-29
 
 ### Added

package/README.md

@@ -44,7 +44,7 @@ In VS Code, install the **BC Atlas** extension and open an AL project:
 | **Export** | `bca export` | Everything the extension shows, as files: the BC Atlas pages as one offline HTML file to share (default), the Markdown report ([example](./examples/report/README.md)), the 3D explorer, one Markdown page per object, any of ten diagram views as D2, SVG, PNG, PDF, or JSON, with `--watch`. |
 | | `bca docs` | User guides and test cases from AL UI tests (`[SCENARIO]`, `[GIVEN]`, `[WHEN]`, `[THEN]`) as Markdown, HTML, DITA 1.3, or Azure DevOps CSV, with real captions and translations, a flow diagram per scenario, and BPMN 2.0 processes per use case. [Example](./examples/docs/index.md) |
 | **Integrate** | `bca run` | One entry point for Git hooks, schedules, and pipelines; verifies, stages, or publishes generated files. Also available as a [GitHub Action](./docs/automation-and-ci.md#github-actions). |
-| | `bca update` | "BC Atlas 0.8.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
+| | `bca update` | "BC Atlas 0.12.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
 | | `bca mcp` | A Model Context Protocol server for AI agents; `bca help --format json` is the versioned command contract. |
 
 Run `bca` for the same overview in your terminal and `bca help <command>` for

package/THIRD_PARTY_NOTICES.md

@@ -28,8 +28,9 @@ executable for PNG and PDF output.
 authors. Both licensed under the MIT License. Sources:
 <https://github.com/vasturiano/3d-force-graph>, <https://github.com/mrdoob/three.js>
 
-The 3d-force-graph browser bundle, which includes three.js, is embedded in the
-explorer HTML files written by `bca export` and shown by the VS Code extension.
+A browser bundle of 3d-force-graph and three.js (including its bloom pass),
+`vendor/graph-viewer.js`, is embedded in the explorer HTML files written by
+`bca export` and shown by the VS Code extension.
 
 ## graphology
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bc-atlas",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "BC Atlas maps Microsoft Dynamics 365 Business Central AL projects: architecture diagrams, health checks, reports, and documentation generated from source.",
   "homepage": "https://github.com/SchulzOli/BC-Atlas#readme",
   "bugs": {
@@ -36,7 +36,9 @@
     "update:grammar": "node ./scripts/update-grammar.js",
     "site:dev": "vitepress dev website",
     "site:build": "vitepress build website && node ./scripts/site-assets.js",
-    "site:preview": "vitepress preview website"
+    "site:preview": "vitepress preview website",
+    "version:set": "node ./scripts/set-version.js",
+    "update:graph-vendor": "node ./scripts/build-graph-vendor.js"
   },
   "keywords": [
     "al",
@@ -59,19 +61,21 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.3.0",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@terrastruct/d2": "^0.1.33",
-    "3d-force-graph": "^1.80.0",
     "fflate": "^0.8.3",
     "graphology": "^0.26.0",
     "graphology-communities-louvain": "^2.0.2",
     "graphology-metrics": "^2.4.1",
-    "web-tree-sitter": "^0.27.0",
-    "zod": "^4.6.5"
+    "web-tree-sitter": "^0.27.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.3.0",
+    "3d-force-graph": "^1.80.0",
+    "@modelcontextprotocol/client": "^2.4.0",
     "bpmn-moddle": "^10.3.1",
+    "esbuild": "^0.28.2",
+    "three": "^0.186.1",
     "vitepress": "2.0.0-alpha.20"
   }
 }

package/src/app/service.js

@@ -25,6 +25,11 @@ export function createService(workspace) {
     overview: () => workspace.overview(),
     health: () => workspace.healthReport(),
     architecture: (params) => workspace.architecture(architectureSettings(params)),
+    component: async ({ name, ...params } = {}) => {
+      const component = await workspace.component(String(name ?? ""), architectureSettings(params));
+      if (!component) throw new Error("component not found");
+      return component;
+    },
     objects: () => workspace.objects(),
     object: async ({ id } = {}) => {
       const object = await workspace.object(String(id ?? ""));

package/src/app/snapshot.js

@@ -39,9 +39,10 @@ function compactDetails(index) {
 
 export async function createSnapshot(workspace, { log = () => {}, history = false, last, title } = {}) {
   const overview = { ...await workspace.overview(), ...(title ? { title } : {}) };
-  const [health, architecture, index, docsHtml] = await Promise.all([
+  const [health, architecture, components, index, docsHtml] = await Promise.all([
     workspace.healthReport(),
     workspace.architecture(),
+    workspace.components(),
     workspace.objectIndex(),
     workspace.docsHtml()
   ]);
@@ -66,6 +67,7 @@ export async function createSnapshot(workspace, { log = () => {}, history = fals
     overview: { ...overview, live: false, root: undefined, projectRoot: undefined },
     health,
     architecture,
+    components,
     objects: index.list,
     nodes,
     details,

package/src/app/ui/app.css

@@ -214,6 +214,63 @@ details.steps ol, details.steps ul { margin: 6px 0 2px; padding-left: 18px; }
 .legend .bad::before { background: var(--error); }
 .controls { display: flex; gap: 12px; flex-wrap: wrap; align-items: flex-end; }
 
+/* Dependencies between components: green where allowed, red where against the architecture */
+.dependency-map { overflow: auto; margin-top: 8px; }
+.dependency-map svg { width: 100%; height: auto; display: block; margin: 0 auto; }
+.dependency-map .dep { fill: none; opacity: 0.75; transition: opacity 0.15s; }
+.dependency-map .dep.allowed, .dependency-map .tip.allowed { stroke: var(--ok); fill: var(--ok); }
+.dependency-map .dep.allowed { fill: none; }
+.dependency-map .dep.wrong, .dependency-map .tip.wrong { stroke: var(--error); fill: var(--error); }
+.dependency-map .dep.wrong { fill: none; }
+.dependency-map svg.focused .dep { opacity: 0.06; }
+.dependency-map svg.focused .dep.on { opacity: 1; }
+.dependency-map.hide-allowed .dep.allowed, .dependency-map.hide-wrong .dep.wrong { display: none; }
+.dependency-map .dep-node { cursor: pointer; }
+.dependency-map .dep-node rect { fill: var(--surface); stroke: var(--border-strong); }
+.dependency-map .dep-node.extractable rect { stroke: var(--ok); }
+.dependency-map .dep-node.blocked rect { stroke: var(--error); }
+.dependency-map .dep-node:hover rect { stroke-width: 2; }
+.dependency-map .dep-node text { fill: var(--text); font-size: 12.5px; font-weight: 600; }
+.dependency-map .dep-node .count { fill: var(--muted); font-weight: 400; }
+.dependency-map .layer-name { fill: var(--muted); font-size: 12px; }
+table.matrix { border-collapse: collapse; font-size: 12px; font-variant-numeric: tabular-nums; }
+table.matrix th { font-weight: 600; color: var(--muted); padding: 4px; text-align: center; position: sticky; top: 0; background: var(--surface); z-index: 1; }
+table.matrix th.row-head { text-align: left; white-space: nowrap; position: sticky; left: 0; padding-right: 10px; z-index: 0; }
+table.matrix td { min-width: 34px; height: 26px; text-align: center; border: 1px solid var(--surface); }
+table.matrix td.allowed { background: color-mix(in srgb, var(--ok) 16%, transparent); }
+table.matrix td.forbidden { background: color-mix(in srgb, var(--error) 6%, transparent); color: var(--muted); }
+table.matrix td.wrong { background: color-mix(in srgb, var(--error) 26%, transparent); color: var(--error); font-weight: 700; }
+table.matrix td.self { background: var(--surface-2); }
+.matrix-legend .swatch { margin-left: 4px; }
+.swatch { display: inline-block; width: 10px; height: 10px; border-radius: 3px; margin-right: 6px; vertical-align: -1px; }
+.swatch.allowed { background: color-mix(in srgb, var(--ok) 40%, transparent); }
+.swatch.forbidden { background: color-mix(in srgb, var(--error) 14%, transparent); }
+.swatch.wrong { background: color-mix(in srgb, var(--error) 60%, transparent); }
+
+/* Component page */
+.group-chips { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 10px; }
+.group-chips .swatch { margin-right: 0; }
+.toolbar.padded { padding: 10px 18px 6px; }
+.canvas.component-canvas { height: 66vh; min-height: 420px; background: var(--surface-2); }
+.component-graph .link { stroke: var(--muted); stroke-opacity: 0.28; stroke-width: 0.8; }
+.component-graph .ext { stroke-opacity: 0.55; }
+.component-graph .ext.allowed { stroke: var(--ok); }
+.component-graph .ext.wrong { stroke: var(--error); stroke-opacity: 0.75; }
+.component-graph .ext.in { stroke-dasharray: 5 4; }
+.component-graph .obj circle { stroke: var(--surface); stroke-width: 1.2; }
+.component-graph .obj circle.flagged { stroke: var(--error); stroke-width: 2.5; }
+.component-graph .obj:hover circle { stroke: var(--text); stroke-width: 2; }
+.component-graph .obj text { fill: var(--text); font-size: 10px; pointer-events: none; }
+.component-graph .island { fill-opacity: 0.07; stroke-opacity: 0.35; stroke-width: 1; stroke-dasharray: 4 4; }
+.component-graph .group-name { font-size: 15px; font-weight: 700; paint-order: stroke; stroke: var(--surface-2); stroke-width: 4px; pointer-events: none; }
+.component-graph .group-name .count { fill: var(--muted); font-weight: 400; }
+.component-graph .other circle { fill: var(--surface); stroke-width: 2.5; }
+.component-graph .other.allowed circle { stroke: var(--ok); }
+.component-graph .other.wrong circle { stroke: var(--error); }
+.component-graph .other text { fill: var(--text); font-size: 12px; font-weight: 600; paint-order: stroke; stroke: var(--surface); stroke-width: 3px; }
+.component-graph.focused [data-group], .component-graph.focused [data-groups] { opacity: 0.12; }
+.component-graph.focused .on { opacity: 1; }
+
 /* Diagrams */
 .diagram-layout { display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 18px; align-items: start; }
 .diagram-form { display: grid; gap: 12px; position: sticky; top: 90px; }