feat(laymos): within-layer module groups + module-tile highlight fix

[kishorenuma]

Why

The module view removes file-level noise, but a layer with twenty modules is still twenty boxes — the flat list overwhelms. Layers don't have this problem because a layer never floats alone: it lives inside a Layer Graph, the handful-sized bundle a reader actually scans. Modules had no equivalent tier. This PR adds one, and fixes a graph-repaint bug found along the way.

Module Groups — a within-layer disclosure tier

A Module Group is a named, described cluster of sibling modules that all live in the same layer. It is to modules what a Layer Graph is to layers, scoped to a single layer so it nests instead of forming a second hierarchy:

Layer  →  Group  →  Module  →  file evidence

Design write-up: devtools/laymos/docs/adr/0020-module-groups.md.

Config API

Mirrors the moduleRules convention — members reuse values already declared in modules, so a module is never declared twice:

const orders = module('src/domain/orders', { description: 'Order rules' });
const cart   = module('src/domain/cart',   { description: 'Cart rules' });

export default defineConfig({
  // …graphs…
  modules: [orders, cart],
  moduleGroups: [
    group('orders', [orders, cart], { description: 'Order lifecycle' }),
  ],
});

Invariants (both are config errors when broken)

• Same layer — every member resolves (by longest layer prefix) to one layer. This is what makes a group nest under its layer lane rather than cut across layers.
• At most one group per module — groups partition a layer's modules, exactly as layers partition files and modules stay flat.

Plus: unique group names, non-empty description, non-empty membership, and members must reuse declared modules values. Groups are purely organizational — they impose no import rule; canImport/canImportedBy stay module-level.

Rendering — progressive disclosure (collapse to a node)

This is the point of the tier, so the UI treats it as one:

• A group collapses to a single node by default. A crowded layer reads as a handful of group nodes (plus any ungrouped module tiles), not every module at once.
• Click a group to expand it into a labeled band of its member tiles; click the header to collapse again. Same collapse/expand affordance the layer lanes already have.
• Edges follow the disclosure. A selected module's edges route into a collapsed group node and fan out to the individual members once it's expanded (endpointId resolves layer → group → module). Selecting a module dims unrelated groups and highlights related ones.
• Layer width is unchanged, so lanes stay put across expand/collapse; only height reflects what's open. Configs without groups render exactly as before.

Try it in cosmos → laymos-modules → grouped architecture (a dense report whose application and domain layers are grouped, with an ungrouped tail in application and untouched entry/platform).

Where it flows

• laymos — group() builder + ModuleGroup type + validation.
• Report — an always-present moduleGroups registry (name → { description, modules }), empty when unused. The group's layer is inferred by consumers, the way a module's layer already is.
• Frontend — the model exposes groups / groupByModule and layers carry groupNames; the packed layout collapses/expands groups per the above.

Bug fix: graph didn't repaint until a drag

Clicking a module updated the selection and recomputed the layout, but the canvas — the appearing edges and the node highlighting — didn't repaint until an unrelated pan or drag "revealed" the already-computed state.

Root cause: the graph passed derived nodes/edges to <ReactFlow> as read-only props, so xyflow synced them into its store through a post-paint effect and could leave the canvas a commit behind each state change until a viewport event flushed it.

Fix: make it a properly controlled flow. A small useFlowElements hook owns xyflow's node/edge state (useNodesState/useEdgesState), pushes each new computed layout in a useLayoutEffect (pre-paint), and wires onNodesChange/onEdgesChange. The computed layout stays the single source of truth; xyflow now repaints selection state on the same commit as the click. (The module tiles also read selected/related/dimmed from node data — xyflow's reactive channel — rather than from React context.)

Considered & rejected

• Nesting modules inside modules — true hierarchy, but breaks the flat-partition invariant that longest-prefix ownership, coverage, and rule evaluation rely on.
• Cross-layer "feature" grouping — matches the "connected for a feature" intent, but then layers and features are two hierarchies over the same modules and the picture can only show one. A within-layer group is the smallest change that removes the overwhelm while keeping every invariant; a cross-layer feature tag stays additive later.

Testing

• laymos: pnpm build && pnpm lint (format + eslint + tsc + CLI self-lint) and pnpm test — 83 passed, incl. 6 group-validation cases and a report-emission case.
• frontend: vitest on laymos-modules — 29 passed, incl. model group tests and layout tests that lock collapse, expand, and edge-into-group routing; laymos-layers 21 passed; vp check clean on touched files.

Note: the grouped geometry and the repaint timing are verified by construction + the layout tests rather than visually (no UI in the build env) — the cosmos "grouped architecture" fixture makes it a quick check.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 978a3da

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9039c6b82e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Count each intra-group violation once

When a violating file import connects two modules in the same group, this sum counts the violation once for each endpoint because incidentViolations increments both edge.from and edge.to. The group header therefore displays 2 violations for a single invalid import; derive the group total directly from the violating file edges touching its members, deduplicating edges whose endpoints are both inside the group.

Useful? React with 👍 / 👎.