@archora/core 1.1.0 → 2.0.0

package/src/analyzer/recommendations.ts

@@ -43,10 +43,10 @@ export function computeRecommendations(inputs: {
    */
   bundleBloat?: BundleBloat[];
   /**
-   * Temporal couplings. Only the subset already filtered by
-   * the detector lands here — we further narrow to "hidden" couplings
-   * (no static edge between the pair), since visible ones duplicate signal
-   * the dependency graph already exposes.
+   * Temporal couplings (already risk-sorted by the detector). We narrow to
+   * pairs that are BOTH hidden (no static edge — visible ones duplicate the
+   * dependency graph) AND cross-boundary (different top-level groups), the only
+   * intersection worth a recommendation. Same-group co-change is batch-PR noise.
    */
   temporalCoupling?: TemporalCoupling[];
 }): Recommendation[] {
@@ -250,14 +250,18 @@ export function computeRecommendations(inputs: {
     }
   }
 
-  // 8. temporal coupling: only the *hidden* couplings — pairs
-  // that change together a lot AND have no static edge. The dependency
-  // graph already shows the rest. Weight scales with score: a 0.9 score
-  // pair ranks alongside a god-module rec, a 0.5 pair sits below cycle
-  // breaks. Cap at 8 to keep the panel readable on big histories.
+  // 8. temporal coupling: only the couplings that are BOTH hidden (no static
+  // edge — the dependency graph already shows the rest) AND cross-boundary
+  // (the two modules live in different top-level groups). That intersection is
+  // the actionable "missing abstraction / leaky boundary" smell; everything
+  // else is same-folder co-change a batch PR produces by the dozen. The raw
+  // list is risk-sorted, so the filter keeps the highest-risk pairs first.
+  // Cap at 10 to keep the panel readable on big histories.
   if (inputs.temporalCoupling && inputs.temporalCoupling.length > 0) {
-    const hidden = inputs.temporalCoupling.filter((c) => c.hidden).slice(0, 8);
-    for (const c of hidden) {
+    const couplings = inputs.temporalCoupling
+      .filter((c) => c.hidden && c.crossBoundary)
+      .slice(0, 10);
+    for (const c of couplings) {
       out.push({
         id: `temporal:${c.a}\x00${c.b}`,
         kind: 'temporal-coupling',
@@ -271,8 +275,9 @@ export function computeRecommendations(inputs: {
           // Round to 2 decimals so i18n templates render `0.83` not `0.8333…`.
           score: Math.round(c.score * 100) / 100,
         },
-        // 0.5 .. 0.85 — same band as misplaced-by-layer / cycle-break candidates.
-        weight: 0.5 + Math.min(0.35, c.score * 0.4),
+        // 0.5 .. 0.9 — driven by risk (strength + evidence + hidden + cross-boundary),
+        // so a cross-boundary missing-abstraction outranks a same-folder pair.
+        weight: 0.5 + Math.min(0.4, c.risk * 0.45),
       });
     }
   }
@@ -393,12 +398,21 @@ function bundleParams(b: BundleBloat): Recommendation['params'] {
   if (b.detail?.sizeBytes !== undefined) p['sizeBytes'] = b.detail.sizeBytes;
   if (b.detail?.chunkCount !== undefined) p['chunkCount'] = b.detail.chunkCount;
   if (b.detail?.sharePercent !== undefined) p['sharePercent'] = b.detail.sharePercent;
+  if (b.detail?.moduleCount !== undefined) p['moduleCount'] = b.detail.moduleCount;
   return p;
 }
 
 function bundleWeight(b: BundleBloat): number {
   // duplicates feel more actionable than just-large chunks; weight them up.
-  const base = b.kind === 'duplicate' ? 0.85 : b.kind === 'heavy-chunk' ? 0.7 : 0.6;
+  // barrel-leak is a concrete, fixable tree-shaking miss - rank near duplicates.
+  const base =
+    b.kind === 'duplicate'
+      ? 0.85
+      : b.kind === 'barrel-leak'
+        ? 0.8
+        : b.kind === 'heavy-chunk'
+          ? 0.7
+          : 0.6;
   const bump = b.severity === 'high' ? 0.1 : b.severity === 'medium' ? 0.05 : 0;
   return Math.min(0.95, base + bump);
 }

package/src/analyzer/resolve.ts

@@ -184,9 +184,20 @@ export function parseTsconfigPaths(content: string): PathAlias[] {
   const baseUrl = (opts.baseUrl ?? '.').replace(/\/+$/u, '');
   const aliases: PathAlias[] = [];
   for (const [key, list] of Object.entries(opts.paths)) {
-    const prefix = trimSuffix(key, '/*');
-    const targets = list.map((t) => joinPosix(baseUrl, trimSuffix(t, '/*')));
-    aliases.push({ prefix, targets });
+    if (key.endsWith('/*')) {
+      // `@x/*`: prefix-strip + suffix-append. Targets keep an interior `*`
+      // (e.g. `packages/*/src`) so the captured suffix is substituted at the
+      // star instead of being appended to a directory that does not exist.
+      const prefix = trimSuffix(key, '/*');
+      const targets = list.map((t) =>
+        t.includes('*') ? joinPosixKeepStar(baseUrl, trimSuffix(t, '/*')) : joinPosix(baseUrl, t),
+      );
+      aliases.push({ prefix, targets });
+      continue;
+    }
+    // exact tsconfig path (no wildcard): `vue` -> `packages/vue/src`.
+    const targets = list.map((t) => joinPosix(baseUrl, t));
+    aliases.push({ prefix: key, targets, exact: true });
   }
   aliases.sort((a, b) => b.prefix.length - a.prefix.length);
   return aliases;
@@ -199,6 +210,25 @@ export interface Resolver {
 
 export function createResolver(source: FileSource, config: ResolverConfig): Resolver {
   const cache = new Map<string, string | null>();
+  // Resolve an alias whose target is itself an alias (alias→alias chain).
+  // `visited` guards against cyclic aliases (@x→@y→@x).
+  const resolveAliased = async (spec: string, visited: Set<string>): Promise<string | null> => {
+    if (visited.has(spec)) return null;
+    visited.add(spec);
+    const aliased = applyAlias(spec, config.aliases);
+    if (aliased.length === 0) return null;
+    for (const candidate of aliased) {
+      const found = await tryFile(source, candidate);
+      if (found) return found;
+    }
+    for (const candidate of aliased) {
+      if (isBare(candidate) && hasAliasCandidate(candidate, config.aliases)) {
+        const chained = await resolveAliased(candidate, visited);
+        if (chained) return chained;
+      }
+    }
+    return null;
+  };
   return {
     hasLocalCandidate(specifier): boolean {
       return hasAliasCandidate(specifier, config.aliases);
@@ -207,20 +237,9 @@ export function createResolver(source: FileSource, config: ResolverConfig): Reso
       const cacheKey = `${fromRel}\u0001${specifier}`;
       if (cache.has(cacheKey)) return cache.get(cacheKey) ?? null;
       if (isBare(specifier)) {
-        const aliased = applyAlias(specifier, config.aliases);
-        if (aliased.length === 0) {
-          cache.set(cacheKey, null);
-          return null;
-        }
-        for (const candidate of aliased) {
-          const found = await tryFile(source, candidate);
-          if (found) {
-            cache.set(cacheKey, found);
-            return found;
-          }
-        }
-        cache.set(cacheKey, null);
-        return null;
+        const found = await resolveAliased(specifier, new Set());
+        cache.set(cacheKey, found);
+        return found;
       }
 
       const fromDir = posixDirname(fromRel);
@@ -255,7 +274,13 @@ export function applyAlias(spec: string, aliases: PathAlias[]): string[] {
     const isWildcard = alias.prefix.length > 0;
     if (isWildcard && (spec === alias.prefix || spec.startsWith(`${alias.prefix}/`))) {
       const suffix = spec.slice(alias.prefix.length).replace(/^\//u, '');
-      return alias.targets.map((t) => (suffix ? joinPosix(t, suffix) : t));
+      return alias.targets.map((t) =>
+        t.includes('*')
+          ? normalizePosix(t.replace('*', suffix))
+          : suffix
+            ? joinPosix(t, suffix)
+            : t,
+      );
     }
     if (alias.prefix === '' && !isWildcard) {
       return alias.targets.map((t) => joinPosix(t, spec));
@@ -294,6 +319,14 @@ function joinPosix(...parts: string[]): string {
   return normalizePosix(filtered.join('/'));
 }
 
+// Like joinPosix but preserves an interior `*` segment (tsconfig `paths`
+// substitution target such as `packages/*/src`). normalizePosix would drop
+// nothing for `*`, but the `*` must survive joining with baseUrl untouched.
+function joinPosixKeepStar(base: string, target: string): string {
+  if (!base || base === '.') return target;
+  return `${base}/${target}`.replace(/\/+/gu, '/');
+}
+
 function posixDirname(p: string): string {
   const i = p.lastIndexOf('/');
   return i === -1 ? '' : p.slice(0, i);

package/src/analyzer/rsc.ts

@@ -6,14 +6,15 @@
 //      conventions (Next app/, Nuxt server/, SvelteKit `+server.ts`/
 //      `*.server.*`).
 //   2. `detectRscLeaks` - emits a `ContractViolation` (`kind: 'rsc-leak'`)
-//      for every static edge crossing a hard boundary (server importing
-//      client, client importing server-only).
+//      for every client->server boundary crossing: a direct edge, and a
+//      transitive one (client -> shared chain -> server), the classic
+//      barrel/re-export leak that fails the Next build.
 //
-// Directives win over conventions. A `'use client'` file in `app/` is
-// client. `server-only` / `client-only` packages are not modeled separately
-// here - the directive system covers the same cases for first-party code,
-// and we don't have a way to type-check third-party code without doing real
-// resolution.
+// Runtime classification precedence: directives (`'use client'` / `'use server'`)
+// win, then the `server-only` / `client-only` packages (Next's own poison-package
+// enforcement - an explicit, framework-independent runtime declaration), then
+// framework folder conventions. Passing server-only *data* as props into a client
+// component needs data-flow analysis and is out of scope (would be high-FP).
 
 import type { ContractViolation } from './contracts';
 import type { DependencyEdge, ModuleId, ModuleNode, ModuleRuntime, ParsedFile } from './types';
@@ -23,6 +24,10 @@ export interface ClassifyRuntimeInput {
   relPath: string;
   framework: Framework;
   directives?: ParsedFile['directives'];
+  /** File imports the `server-only` package (Next's poison package — throws if bundled for the client). */
+  importsServerOnly?: boolean;
+  /** File imports the `client-only` package. */
+  importsClientOnly?: boolean;
 }
 
 export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntime {
@@ -32,9 +37,14 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
     if (input.directives.includes('use client')) return 'client';
   }
 
+  // 2. `server-only` / `client-only` packages — an explicit runtime declaration,
+  //    framework-independent (this is Next RSC's own enforcement mechanism, not a convention).
+  if (input.importsServerOnly) return 'server';
+  if (input.importsClientOnly) return 'client';
+
   const path = input.relPath.replace(/\\/gu, '/');
 
-  // 2. SvelteKit conventions (work for any framework value because users
+  // 3. SvelteKit conventions (work for any framework value because users
   //    pin them by file name, not framework detection):
   //    - `+server.ts` / `+server.js` -> endpoint, server only
   //    - `*.server.ts` (and `+page.server.ts`, `+layout.server.ts`) -> server
@@ -45,7 +55,7 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
   if (/\.client\.[mc]?[jt]sx?$/u.test(path)) return 'client';
   if (/(^|\/)\+(?:page|layout)\.svelte$/u.test(path)) return 'client';
 
-  // 3. Framework-specific folder conventions.
+  // 4. Framework-specific folder conventions.
   if (input.framework === 'next') {
     // Next App Router: `app/` files are server components by default.
     // The 'use client' directive (handled above) opts a tree into client.
@@ -65,6 +75,19 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
   return 'shared';
 }
 
+/**
+ * A `'use server'` directive marks a Next.js Server Actions module: it is
+ * server runtime, but it is *meant* to be imported from client components
+ * (forms/mutations), so a client->this edge is not an `rsc-leak`. Distinct from
+ * server-only modules (`server-only` package / server component / endpoint
+ * conventions), whose import from a client is a real leak. Directives win over
+ * conventions in `classifyModuleRuntime`, so the directive is an authoritative
+ * reason here.
+ */
+export function isServerActionsModule(directives?: ParsedFile['directives']): boolean {
+  return !!directives && directives.includes('use server');
+}
+
 export interface DetectRscLeaksInput {
   modules: ModuleNode[];
   edges: DependencyEdge[];
@@ -80,14 +103,20 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
 
   const out: ContractViolation[] = [];
   let serial = 0;
+  const directLeaks = new Set<string>();
 
   for (const e of input.edges) {
     if (e.kind === 'type-only') continue;
     const from = moduleById.get(e.from);
     const to = moduleById.get(e.to);
     if (!from || !to) continue;
+    // Server Actions (`'use server'`) are server runtime but designed to be
+    // imported from client components — that edge is the intended Next.js
+    // pattern, not a leak.
+    if (to.isServerActions) continue;
     const leak = classifyLeak(from.runtime ?? 'shared', to.runtime ?? 'shared');
     if (!leak) continue;
+    directLeaks.add(`${from.id}->${to.id}`);
     out.push({
       id: `rsc-leak:${serial++}:${e.from}\u0001${e.to}`,
       kind: 'rsc-leak',
@@ -98,6 +127,58 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
       edge: { from: from.id, to: to.id, specifier: e.specifier },
     });
   }
+
+  // Transitive leaks: a client module pulls server-only code through a chain of
+  // shared modules (the classic barrel/re-export leak — in Next this is a build
+  // error, since the shared chain plus the server code lands in the client bundle).
+  // Walk from each client module through shared intermediates only; sink = server.
+  // Direct client→server edges are already handled above.
+  const adj = new Map<ModuleId, ModuleId[]>();
+  for (const e of input.edges) {
+    if (e.kind === 'type-only') continue;
+    let bucket = adj.get(e.from);
+    if (!bucket) {
+      bucket = [];
+      adj.set(e.from, bucket);
+    }
+    bucket.push(e.to);
+  }
+  const rt = (id: ModuleId): ModuleRuntime => moduleById.get(id)?.runtime ?? 'shared';
+  const seenTransitive = new Set<string>();
+  for (const c of input.modules) {
+    if ((c.runtime ?? 'shared') !== 'client') continue;
+    const visitedShared = new Set<ModuleId>();
+    const queue: ModuleId[] = [];
+    for (const to of adj.get(c.id) ?? []) {
+      if (rt(to) === 'shared' && !visitedShared.has(to)) {
+        visitedShared.add(to);
+        queue.push(to);
+      }
+    }
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      for (const to of adj.get(node) ?? []) {
+        const toRt = rt(to);
+        if (toRt === 'server' && !moduleById.get(to)?.isServerActions) {
+          const key = `${c.id}->${to}`;
+          if (directLeaks.has(key) || seenTransitive.has(key)) continue;
+          seenTransitive.add(key);
+          out.push({
+            id: `rsc-leak:${serial++}:${key}`,
+            kind: 'rsc-leak',
+            ruleName: 'rsc-leak',
+            severity: 'error',
+            message: `client module "${c.id}" transitively imports server-only "${to}" through shared module(s)`,
+            modules: [c.id, to],
+            edge: { from: c.id, to, specifier: to },
+          });
+        } else if (toRt === 'shared' && !visitedShared.has(to)) {
+          visitedShared.add(to);
+          queue.push(to);
+        }
+      }
+    }
+  }
   return out;
 }
 

package/src/analyzer/sources/browserFsAccessFileSource.ts

@@ -8,7 +8,7 @@ export interface BrowserFsAccessFileSourceOptions {
   rootHandle: FileSystemDirectoryHandle;
   rootName?: string;
   onProgress?: (visited: number) => void;
-  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  /** If true (default) - skip test/storybook/cypress/playwright directories. */
   skipTestLikeDirs?: boolean;
   /** Read `.gitignore` from root and filter the listing. Default: true. */
   respectGitignore?: boolean;

package/src/analyzer/sources/nodeFsFileSource.ts

@@ -10,7 +10,7 @@ export interface NodeFsFileSourceOptions {
   rootPath: string;
   respectGitignore?: boolean;
   extraIgnore?: string[];
-  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  /** If true (default) - skip test/storybook/cypress/playwright directories. */
   skipTestLikeDirs?: boolean;
 }
 

package/src/analyzer/sources/tauriFileSource.ts

@@ -8,9 +8,9 @@ export interface TauriFileSourceOptions {
   rootPath: string;
   rootName?: string;
   invoke: TauriInvoke;
-  /** Дополнительные ignore-globs (gitignore-синтаксис), напр. ['*.test.ts']. */
+  /** Extra ignore globs (gitignore syntax), e.g. ['*.test.ts']. */
   extraIgnoreGlobs?: string[];
-  /** Жёсткий лимит размера читаемого файла, байт. По умолчанию 2 МБ. */
+  /** Hard limit on the size of a file to read, in bytes. Default 2 MB. */
   maxFileBytes?: number;
 }
 

package/src/analyzer/types.ts

@@ -65,7 +65,24 @@ export interface ModuleNode {
    * Defaults to `'shared'` when nothing pins it down.
    */
   runtime?: ModuleRuntime;
+  /**
+   * Module is server because of a `'use server'` directive — a Next.js Server
+   * Actions module, designed to be imported and called from client components
+   * (Next compiles the exports into RPC references; nothing server-only ships).
+   * A client->server-actions edge is the intended pattern and is NOT an
+   * `rsc-leak`, unlike client->server-only (`server-only` package / server
+   * component / endpoint conventions). Set only when `'use server'` is the
+   * classification reason.
+   */
+  isServerActions?: boolean;
   isGenerated?: boolean;
+  /**
+   * Re-export barrel (e.g. `index.ts` re-exporting every sibling). High fan-out
+   * is its purpose, not a risk — so barrels are excluded from hot zones and
+   * "split this module" advice. Detected post-graph, where parsed export facts
+   * and the fan-out metric are both available.
+   */
+  isBarrel?: boolean;
 }
 
 export type ModuleRuntime = 'server' | 'client' | 'shared';
@@ -401,6 +418,11 @@ export interface ParsedFile {
   directives?: ('use server' | 'use client')[];
   /** PascalCase component tags from <template>, resolved against the component registry in buildGraph. */
   templateRefs?: string[];
+  /**
+   * Identifiers called as a function (`foo(...)`, not `obj.foo(...)`).
+   * Used to resolve Nuxt auto-import composables in buildGraph.
+   */
+  callIdentifiers?: string[];
 }
 
 export type SignalSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical';

package/src/cache/index.ts

@@ -30,10 +30,25 @@ import { incrementalAnalyze } from '../analyzer/incremental';
 import { discoverFiles } from '../analyzer/discover';
 
 /**
- * Bump whenever the on-disk shape of `ScanResult` or the manifest changes.
- * A mismatch causes `loadCache` to treat the entry as missing.
+ * Bump whenever the on-disk shape of `ScanResult`/manifest changes, OR whenever
+ * the analyzer's OUTPUT semantics change (new/changed findings, ranking, or
+ * filtering) — otherwise a warm cache keyed only on source+tool version serves
+ * stale results that don't reflect the improved analysis. A mismatch causes
+ * `loadCache` to treat the entry as missing.
+ *
+ * v3: barrel modules excluded from hot zones; temporal-coupling findings limited
+ *     to hidden cross-boundary pairs.
+ * v4: tsconfig path wildcards with an interior star (key @x/* mapping to target
+ *     pkgs/[star]/src) now resolve, so cross-package edges that were previously
+ *     dropped appear in the graph.
+ * v5: timer-cleanup memory risk no longer flags bare fire-and-forget setTimeout
+ *     calls; only captured (stored/returned/passed) timer handles without
+ *     clearTimeout are reported, reducing false positives.
+ * v7: modules carry `isServerActions`; `rsc-leak` no longer flags client
+ *     imports of `'use server'` Server Actions modules (the intended Next.js
+ *     pattern), only client->server-only imports.
  */
-export const CACHE_FORMAT_VERSION = 2;
+export const CACHE_FORMAT_VERSION = 7;
 
 /**
  * Marker used inside `node_modules/.cache/archora/`. Also the directory

package/src/diff/__tests__/diffScans.test.ts

@@ -1,6 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import { diffScans } from '../diffScans';
-import type { Cycle, ModuleNode, ScanResult } from '../../analyzer/types';
+import type {
+  ContractViolation,
+  Cycle,
+  LayerViolation,
+  ModuleNode,
+  ScanResult,
+} from '../../analyzer/types';
 
 function mod(id: string, overrides: Partial<ModuleNode> = {}): ModuleNode {
   return {
@@ -24,6 +30,33 @@ function cycle(id: string, modules: string[]): Cycle {
   };
 }
 
+function layerViolation(edgeId: string, overrides: Partial<LayerViolation> = {}): LayerViolation {
+  return {
+    edgeId,
+    from: 'src/a.ts',
+    to: 'src/b.ts',
+    fromLayer: 'features',
+    toLayer: 'app',
+    severity: 'error',
+    ...overrides,
+  };
+}
+
+function contractViolation(
+  id: string,
+  overrides: Partial<ContractViolation> = {},
+): ContractViolation {
+  return {
+    id,
+    kind: 'boundary',
+    ruleName: 'no-cross-layer',
+    severity: 'error',
+    message: 'boundary violation',
+    modules: ['src/a.ts'],
+    ...overrides,
+  };
+}
+
 function scan(overrides: Partial<ScanResult>): ScanResult {
   return {
     project: { id: 'p', name: 'p', rootPath: '/p', detectedFramework: 'unknown' },
@@ -98,6 +131,36 @@ describe('diffScans', () => {
       changedModules: 0,
       newCycles: 0,
       resolvedCycles: 0,
+      newLayerViolations: 0,
+      newContractViolations: 0,
     });
   });
+
+  it('diffs layer violations by edgeId', () => {
+    const shared = layerViolation('edge:a→b');
+    const prev = scan({
+      layerViolations: [shared, layerViolation('edge:c→d')],
+    });
+    const next = scan({
+      layerViolations: [shared, layerViolation('edge:e→f')],
+    });
+    const d = diffScans(prev, next);
+    expect(d.newLayerViolations.map((v) => v.edgeId)).toEqual(['edge:e→f']);
+    expect(d.resolvedLayerViolations.map((v) => v.edgeId)).toEqual(['edge:c→d']);
+    expect(d.summary.newLayerViolations).toBe(1);
+  });
+
+  it('diffs contract violations by id', () => {
+    const shared = contractViolation('boundary:auth:0');
+    const prev = scan({
+      contractViolations: [shared, contractViolation('boundary:payment:0')],
+    });
+    const next = scan({
+      contractViolations: [shared, contractViolation('boundary:cart:0')],
+    });
+    const d = diffScans(prev, next);
+    expect(d.newContractViolations.map((v) => v.id)).toEqual(['boundary:cart:0']);
+    expect(d.resolvedContractViolations.map((v) => v.id)).toEqual(['boundary:payment:0']);
+    expect(d.summary.newContractViolations).toBe(1);
+  });
 });

package/src/diff/diffScans.ts

@@ -1,4 +1,4 @@
-import type { Cycle, ScanResult } from '../analyzer/types';
+import type { ContractViolation, Cycle, LayerViolation, ScanResult } from '../analyzer/types';
 import type { ChangedModule, ScanDiff } from './types';
 
 // module id = project-relative path; cycle id = sorted member set.
@@ -35,6 +35,30 @@ export function diffScans(prev: ScanResult, next: ScanResult): ScanDiff {
     if (!nextCyclesByKey.has(key)) resolvedCycles.push(cycle);
   }
 
+  const prevLayerByEdge = new Map(prev.layerViolations.map((v) => [v.edgeId, v]));
+  const nextLayerByEdge = new Map(next.layerViolations.map((v) => [v.edgeId, v]));
+
+  const newLayerViolations: LayerViolation[] = [];
+  for (const [edgeId, v] of nextLayerByEdge) {
+    if (!prevLayerByEdge.has(edgeId)) newLayerViolations.push(v);
+  }
+  const resolvedLayerViolations: LayerViolation[] = [];
+  for (const [edgeId, v] of prevLayerByEdge) {
+    if (!nextLayerByEdge.has(edgeId)) resolvedLayerViolations.push(v);
+  }
+
+  const prevContractById = new Map(prev.contractViolations.map((v) => [v.id, v]));
+  const nextContractById = new Map(next.contractViolations.map((v) => [v.id, v]));
+
+  const newContractViolations: ContractViolation[] = [];
+  for (const [id, v] of nextContractById) {
+    if (!prevContractById.has(id)) newContractViolations.push(v);
+  }
+  const resolvedContractViolations: ContractViolation[] = [];
+  for (const [id, v] of prevContractById) {
+    if (!nextContractById.has(id)) resolvedContractViolations.push(v);
+  }
+
   return {
     projectId: next.project.id,
     projectName: next.project.name,
@@ -45,12 +69,18 @@ export function diffScans(prev: ScanResult, next: ScanResult): ScanDiff {
     changedModules,
     newCycles,
     resolvedCycles,
+    newLayerViolations,
+    resolvedLayerViolations,
+    newContractViolations,
+    resolvedContractViolations,
     summary: {
       addedModules: addedModules.length,
       removedModules: removedModules.length,
       changedModules: changedModules.length,
       newCycles: newCycles.length,
       resolvedCycles: resolvedCycles.length,
+      newLayerViolations: newLayerViolations.length,
+      newContractViolations: newContractViolations.length,
     },
   };
 }

package/src/diff/types.ts

@@ -1,4 +1,10 @@
-import type { Cycle, ModuleId, ModuleNode } from '../analyzer/types';
+import type {
+  ContractViolation,
+  Cycle,
+  LayerViolation,
+  ModuleId,
+  ModuleNode,
+} from '../analyzer/types';
 
 export interface ScanDiff {
   /** Project id and name from the *current* (newer) scan, for display. */
@@ -20,6 +26,16 @@ export interface ScanDiff {
   /** Cycles that disappeared in `next`. */
   resolvedCycles: Cycle[];
 
+  /** Layer violations whose `edgeId` is absent from `prev`. */
+  newLayerViolations: LayerViolation[];
+  /** Layer violations whose `edgeId` was present in `prev` but not in `next`. */
+  resolvedLayerViolations: LayerViolation[];
+
+  /** Contract violations whose `id` is absent from `prev`. */
+  newContractViolations: ContractViolation[];
+  /** Contract violations whose `id` was present in `prev` but not in `next`. */
+  resolvedContractViolations: ContractViolation[];
+
   /** Aggregate counts for quick rendering at the top of a diff view. */
   summary: ScanDiffSummary;
 }
@@ -36,4 +52,6 @@ export interface ScanDiffSummary {
   changedModules: number;
   newCycles: number;
   resolvedCycles: number;
+  newLayerViolations: number;
+  newContractViolations: number;
 }

package/src/git/__tests__/computeTemporalCoupling.test.ts

@@ -122,4 +122,28 @@ describe('computeTemporalCoupling', () => {
     expect(out[0]?.a).toBe('src/c.ts');
     expect(out[1]?.hidden).toBe(false);
   });
+
+  it('ranks a cross-boundary hidden coupling above an equally-strong same-folder one', () => {
+    const modules = ['features/auth/a.ts', 'entities/user/b.ts', 'shared/x.ts', 'shared/y.ts'].map(
+      mod,
+    );
+    const h = history([
+      commit('1', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('2', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('3', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('4', ['shared/x.ts', 'shared/y.ts']),
+      commit('5', ['shared/x.ts', 'shared/y.ts']),
+      commit('6', ['shared/x.ts', 'shared/y.ts']),
+    ]);
+    const out = computeTemporalCoupling({ modules, edges: NO_EDGES, history: h });
+    expect(out).toHaveLength(2);
+    // Both are hidden, score 1.0, 3 co-occurrences — only the boundary differs.
+    const cross = out.find((c) => c.a === 'entities/user/b.ts' || c.b === 'entities/user/b.ts');
+    const same = out.find((c) => c.a === 'shared/x.ts' && c.b === 'shared/y.ts');
+    expect(cross?.crossBoundary).toBe(true);
+    expect(same?.crossBoundary).toBe(false);
+    expect(cross!.risk).toBeGreaterThan(same!.risk);
+    expect(out[0]).toBe(cross); // cross-boundary ranks first
+    expect(cross!.risk).toBeLessThanOrEqual(1);
+  });
 });