@archora/core 1.1.0 → 2.0.0

package/src/analyzer/__tests__/metrics.test.ts

@@ -56,4 +56,43 @@ describe('computeMetrics', () => {
     expect(m['c']!.depth).toBe(2);
     expect(m['d']!.depth).toBe(3);
   });
+
+  it('collapses an SCC so cycle members share one condensation depth', () => {
+    // a -> b -> c -> b  (b,c form a cycle), then c -> d.
+    const modules = [mod('a'), mod('b'), mod('c'), mod('d')];
+    const edges = [edge('a', 'b'), edge('b', 'c'), edge('c', 'b'), edge('c', 'd')];
+    const cycles = detectCycles(modules, edges);
+    const m = computeMetrics({ modules, edges, cycles, entries: ['a'] });
+    expect(m['a']!.depth).toBe(0);
+    // b and c are one condensed node -> equal depth, exactly one hop past `a`.
+    expect(m['b']!.depth).toBe(1);
+    expect(m['c']!.depth).toBe(1);
+    // d sits one hop past the condensed {b,c}.
+    expect(m['d']!.depth).toBe(2);
+  });
+
+  it('takes the longest path to a node reachable by two routes (diamond)', () => {
+    // a -> b -> d and a -> c -> d, plus a long leg a -> b -> e -> d.
+    const modules = [mod('a'), mod('b'), mod('c'), mod('d'), mod('e')];
+    const edges = [
+      edge('a', 'b'),
+      edge('a', 'c'),
+      edge('b', 'd'),
+      edge('c', 'd'),
+      edge('b', 'e'),
+      edge('e', 'd'),
+    ];
+    const m = computeMetrics({ modules, edges, cycles: [], entries: ['a'] });
+    expect(m['d']!.depth).toBe(3); // a -> b -> e -> d is the longest route
+  });
+
+  it('weights hotness by file size at equal coupling (sizeFactor)', () => {
+    // c1 and c2 are symmetric (both imported by `a`, both import `z`) so their
+    // coupling is identical; only the file size differs.
+    const modules = [mod('a'), mod('c1', 10), mod('c2', 5000), mod('z')];
+    const edges = [edge('a', 'c1'), edge('a', 'c2'), edge('c1', 'z'), edge('c2', 'z')];
+    const m = computeMetrics({ modules, edges, cycles: [], entries: ['a'] });
+    expect(m['c1']!.couplingScore).toBe(m['c2']!.couplingScore);
+    expect(m['c2']!.hotnessScore).toBeGreaterThan(m['c1']!.hotnessScore);
+  });
 });

package/src/analyzer/__tests__/nuxtComposableAutoImport.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import { analyze } from '../index';
+import { createInMemoryFileSource } from '../sources/inMemoryFileSource';
+
+const nuxtProject = (files: Record<string, string>) =>
+  createInMemoryFileSource('/p', {
+    'package.json': JSON.stringify({ dependencies: { nuxt: '^3.0.0' } }),
+    'tsconfig.json': '{}',
+    'app.vue': `<template><NuxtPage /></template>`,
+    ...files,
+  });
+
+describe('buildGraph: Nuxt auto-import composable resolution', () => {
+  it('emits an auto-import edge from a page using a composable by filename convention', async () => {
+    const src = nuxtProject({
+      'pages/index.vue': `<script setup lang="ts">
+const n = useCounter();
+</script>
+<template><div>{{ n }}</div></template>`,
+      'composables/useCounter.ts': `export default function useCounter() { return 0; }`,
+    });
+    const result = await analyze(src);
+    const edge = result.edges.find(
+      (e) => e.from === 'pages/index.vue' && e.to === 'composables/useCounter.ts',
+    );
+    expect(edge).toBeDefined();
+    expect(edge?.kind).toBe('auto-import');
+  });
+
+  it('resolves a composable by its named export, not just the filename', async () => {
+    const src = nuxtProject({
+      'pages/index.vue': `<script setup lang="ts">
+const s = useSession();
+</script>
+<template><div /></template>`,
+      'composables/auth.ts': `export function useSession() { return null; }`,
+    });
+    const result = await analyze(src);
+    const edge = result.edges.find(
+      (e) => e.from === 'pages/index.vue' && e.to === 'composables/auth.ts',
+    );
+    expect(edge?.kind).toBe('auto-import');
+    expect(edge?.specifier).toBe('useSession');
+  });
+
+  it('does NOT duplicate the edge when the composable is already statically imported', async () => {
+    const src = nuxtProject({
+      'pages/index.vue': `<script setup lang="ts">
+import { useCounter } from '~/composables/useCounter';
+const n = useCounter();
+</script>
+<template><div /></template>`,
+      'composables/useCounter.ts': `export function useCounter() { return 0; }`,
+      'tsconfig.json': JSON.stringify({
+        compilerOptions: { baseUrl: '.', paths: { '~/*': ['./*'] } },
+      }),
+    });
+    const result = await analyze(src);
+    const edges = result.edges.filter(
+      (e) => e.from === 'pages/index.vue' && e.to === 'composables/useCounter.ts',
+    );
+    expect(edges).toHaveLength(1);
+    expect(edges[0]?.kind).toBe('static');
+  });
+
+  it('does NOT create an edge for an identifier with no matching composable (Nuxt built-ins)', async () => {
+    const src = nuxtProject({
+      'pages/index.vue': `<script setup lang="ts">
+const r = useRoute();
+const f = useFetch('/api/x');
+</script>
+<template><div /></template>`,
+      'composables/useCounter.ts': `export function useCounter() { return 0; }`,
+    });
+    const result = await analyze(src);
+    const autoImports = result.edges.filter(
+      (e) => e.from === 'pages/index.vue' && e.kind === 'auto-import',
+    );
+    expect(autoImports).toEqual([]);
+  });
+
+  it('does not emit a self-edge when a composable calls a sibling-named helper in its own file', async () => {
+    const src = nuxtProject({
+      'composables/useCounter.ts': `export function useCounter() { return useCounter; }`,
+    });
+    const result = await analyze(src);
+    const selfEdges = result.edges.filter(
+      (e) => e.from === 'composables/useCounter.ts' && e.to === 'composables/useCounter.ts',
+    );
+    expect(selfEdges).toEqual([]);
+  });
+});
+
+describe('buildGraph: plain Vue (non-Nuxt) does not guess auto-import composables', () => {
+  it('does not create composable auto-import edges without Nuxt (documented limitation)', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/App.vue': `<script setup lang="ts">
+const n = useCounter();
+</script>
+<template><div /></template>`,
+      'src/composables/useCounter.ts': `export function useCounter() { return 0; }`,
+    });
+    const result = await analyze(src);
+    const autoImports = result.edges.filter((e) => e.kind === 'auto-import');
+    expect(autoImports).toEqual([]);
+  });
+});

package/src/analyzer/__tests__/reactParser.test.ts

@@ -33,6 +33,28 @@ describe('reactParser (via registry, framework=react)', () => {
     expect(specs).toEqual(expect.arrayContaining(['./A', './B']));
   });
 
+  it('captures next/dynamic(() => import(...)) as a dynamic edge', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import dynamic from 'next/dynamic';
+       const Chart = dynamic(() => import('./widgets/Chart'));
+       export const App = () => null;`,
+    );
+    const dynamic = file.imports.filter((i) => i.kind === 'dynamic');
+    expect(dynamic.map((i) => i.specifier)).toContain('./widgets/Chart');
+  });
+
+  it('captures next/dynamic with an options object as a dynamic edge', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import dynamic from 'next/dynamic';
+       const Map = dynamic(() => import('./widgets/Map'), { ssr: false });
+       export const App = () => null;`,
+    );
+    const dynamic = file.imports.filter((i) => i.kind === 'dynamic');
+    expect(dynamic.map((i) => i.specifier)).toContain('./widgets/Map');
+  });
+
   it('captures static imports of JSX components', () => {
     const file = parseReact(
       'src/App.tsx',

package/src/analyzer/__tests__/recommendations.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { computeRecommendations } from '../recommendations';
 import type { Cycle, DependencyEdge, ModuleMetrics, ModuleNode } from '../types';
+import type { TemporalCoupling } from '../../git/types';
 
 function module(id: string, overrides: Partial<ModuleNode> = {}): ModuleNode {
   return {
@@ -168,4 +169,70 @@ describe('computeRecommendations', () => {
     const r = recs.find((x) => x.kind === 'unused-utility')!;
     expect(r.params.name).toBe('dead.ts');
   });
+
+  it('only surfaces hidden cross-boundary temporal couplings, ranked, capped at 10', () => {
+    function coupling(
+      a: string,
+      b: string,
+      hidden: boolean,
+      crossBoundary: boolean,
+      risk: number,
+    ): TemporalCoupling {
+      return {
+        a,
+        b,
+        coOccurrences: 5,
+        scoreA: 0.8,
+        scoreB: 0.8,
+        score: 0.8,
+        hidden,
+        crossBoundary,
+        risk,
+      };
+    }
+    const temporalCoupling: TemporalCoupling[] = [
+      coupling('features/a.ts', 'entities/b.ts', true, true, 0.9),
+      coupling('features/c.ts', 'shared/d.ts', true, true, 0.7),
+      coupling('shared/x.ts', 'shared/y.ts', true, false, 0.95), // same group: dropped
+      coupling('features/e.ts', 'entities/f.ts', false, true, 0.95), // visible: dropped
+    ];
+    const recs = computeRecommendations({
+      modules: [],
+      edges: [],
+      metrics: {},
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+      temporalCoupling,
+    });
+    const temporal = recs.filter((r) => r.kind === 'temporal-coupling');
+    expect(temporal).toHaveLength(2);
+    // Input order is risk-sorted by the detector and preserved.
+    expect(temporal[0]!.modules).toEqual(['features/a.ts', 'entities/b.ts']);
+    expect(temporal[1]!.modules).toEqual(['features/c.ts', 'shared/d.ts']);
+  });
+
+  it('caps temporal-coupling recommendations at 10', () => {
+    const temporalCoupling: TemporalCoupling[] = Array.from({ length: 15 }, (_, i) => ({
+      a: `features/a${i}.ts`,
+      b: `entities/b${i}.ts`,
+      coOccurrences: 5,
+      scoreA: 0.8,
+      scoreB: 0.8,
+      score: 0.8,
+      hidden: true,
+      crossBoundary: true,
+      risk: 1 - i * 0.01,
+    }));
+    const recs = computeRecommendations({
+      modules: [],
+      edges: [],
+      metrics: {},
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+      temporalCoupling,
+    });
+    expect(recs.filter((r) => r.kind === 'temporal-coupling')).toHaveLength(10);
+  });
 });

package/src/analyzer/__tests__/resolve.test.ts

@@ -14,6 +14,33 @@ describe('resolve', () => {
     expect(aliases).toEqual([{ prefix: '@', targets: ['src'] }]);
   });
 
+  it('resolves a tsconfig wildcard whose target has an interior star to the package index', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'tsconfig.json': JSON.stringify({
+        compilerOptions: {
+          baseUrl: '.',
+          paths: { '@x/*': ['pkgs/*/src'], '@x/legacy': ['pkgs/legacy/src'] },
+        },
+      }),
+      'pkgs/foo/src/index.ts': 'export const foo = 1;',
+      'pkgs/legacy/src/index.ts': 'export const legacy = 1;',
+      'src/main.ts': "import { foo } from '@x/foo';",
+    });
+    const project: ProjectRef = {
+      id: 'p',
+      name: 'p',
+      rootPath: '/p',
+      detectedFramework: 'unknown',
+      tsconfigPath: 'tsconfig.json',
+    };
+    const r = createResolver(src, { aliases: await loadAliases(src, project) });
+    // `@x/*` -> `pkgs/*/src`: the captured `foo` is substituted at the star,
+    // then directory->index resolution lands on the package index file.
+    expect(await r.resolve('@x/foo', 'src/main.ts')).toBe('pkgs/foo/src/index.ts');
+    // an exact tsconfig path (no star) shadows the wildcard for its own key.
+    expect(await r.resolve('@x/legacy', 'src/main.ts')).toBe('pkgs/legacy/src/index.ts');
+  });
+
   it('resolves @/ alias to src/*.ts and *.vue', async () => {
     const src = await createNodeFsFileSource({ rootPath: fixturePath('sample-vue-app') });
     const r = createResolver(src, { aliases: parseTsconfigPaths(await src.read('tsconfig.json')) });
@@ -43,6 +70,33 @@ describe('resolve', () => {
     expect(await r.resolve('@/lib/util', 'src/main.js')).toBe('src/lib/util.js');
   });
 
+  it('resolves an alias whose target is itself an alias (alias chain)', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'src/a/foo.ts': 'export const x = 1;',
+      'src/entry.ts': "import { x } from '@b/foo';",
+    });
+    const r = createResolver(src, {
+      aliases: [
+        { prefix: '@b', targets: ['@a'] },
+        { prefix: '@a', targets: ['src/a'] },
+      ],
+    });
+    expect(await r.resolve('@b/foo', 'src/entry.ts')).toBe('src/a/foo.ts');
+  });
+
+  it('does not loop on a cyclic alias chain', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'src/entry.ts': "import { x } from '@x/foo';",
+    });
+    const r = createResolver(src, {
+      aliases: [
+        { prefix: '@x', targets: ['@y'] },
+        { prefix: '@y', targets: ['@x'] },
+      ],
+    });
+    expect(await r.resolve('@x/foo', 'src/entry.ts')).toBeNull();
+  });
+
   it('resolves relative imports', async () => {
     const src = await createNodeFsFileSource({ rootPath: fixturePath('sample-cycles') });
     const r = createResolver(src, { aliases: [] });

package/src/analyzer/__tests__/rsc.test.ts

@@ -7,7 +7,11 @@ import { analyze } from '../index';
 import { createInMemoryFileSource } from '../sources/inMemoryFileSource';
 import type { DependencyEdge, ModuleNode } from '../types';
 
-function mod(id: string, runtime: ModuleNode['runtime'] = 'shared'): ModuleNode {
+function mod(
+  id: string,
+  runtime: ModuleNode['runtime'] = 'shared',
+  opts: { isServerActions?: boolean } = {},
+): ModuleNode {
   return {
     id,
     absPath: id,
@@ -17,6 +21,7 @@ function mod(id: string, runtime: ModuleNode['runtime'] = 'shared'): ModuleNode
     exports: [],
     isInfra: false,
     runtime,
+    ...(opts.isServerActions ? { isServerActions: true } : {}),
   };
 }
 
@@ -43,6 +48,26 @@ describe('classifyModuleRuntime', () => {
     ).toBe('server');
   });
 
+  it("importing the 'server-only' package marks the module server (any framework)", () => {
+    expect(
+      classifyModuleRuntime({
+        relPath: 'lib/secret.ts',
+        framework: 'unknown',
+        importsServerOnly: true,
+      }),
+    ).toBe('server');
+  });
+
+  it("importing the 'client-only' package marks the module client", () => {
+    expect(
+      classifyModuleRuntime({
+        relPath: 'lib/browser.ts',
+        framework: 'next',
+        importsClientOnly: true,
+      }),
+    ).toBe('client');
+  });
+
   it('Next App Router defaults to server, pages/api server-only', () => {
     expect(classifyModuleRuntime({ relPath: 'app/page.tsx', framework: 'next' })).toBe('server');
     expect(classifyModuleRuntime({ relPath: 'pages/api/hello.ts', framework: 'next' })).toBe(
@@ -98,6 +123,90 @@ describe('detectRscLeaks', () => {
     expect(leaks[0]?.edge?.to).toBe('lib/db.ts');
   });
 
+  it("does not flag a client importing a 'use server' Server Actions module", () => {
+    // The ubiquitous Next.js app-router pattern: a client component imports
+    // server actions (forms/mutations). Next compiles them into RPC references;
+    // nothing server-only ships to the browser, so this is not a leak.
+    const modules = [
+      mod('components/cart/modal.tsx', 'client'),
+      mod('components/cart/actions.ts', 'server', { isServerActions: true }),
+    ];
+    const edges = [edge('components/cart/modal.tsx', 'components/cart/actions.ts')];
+    expect(detectRscLeaks({ modules, edges })).toHaveLength(0);
+  });
+
+  it("still flags client -> server-only when the server module is not 'use server'", () => {
+    const modules = [
+      mod('app/Form.tsx', 'client'),
+      mod('lib/secret.ts', 'server'), // server via server-only / convention, no 'use server'
+    ];
+    const edges = [edge('app/Form.tsx', 'lib/secret.ts')];
+    const leaks = detectRscLeaks({ modules, edges });
+    expect(leaks).toHaveLength(1);
+    expect(leaks[0]?.edge?.to).toBe('lib/secret.ts');
+  });
+
+  it("does not flag a transitive client -> shared -> 'use server' actions chain", () => {
+    const modules = [
+      mod('app/Form.tsx', 'client'),
+      mod('lib/index.ts', 'shared'), // barrel
+      mod('lib/actions.ts', 'server', { isServerActions: true }),
+    ];
+    const edges = [edge('app/Form.tsx', 'lib/index.ts'), edge('lib/index.ts', 'lib/actions.ts')];
+    expect(detectRscLeaks({ modules, edges })).toHaveLength(0);
+  });
+
+  it("flags a client component importing a module poisoned with 'server-only'", async () => {
+    const fs = createInMemoryFileSource('/repo', {
+      'package.json': JSON.stringify({ dependencies: { next: '^14.0.0' } }),
+      'app/Form.tsx':
+        "'use client';\nimport { getSecret } from '../lib/secret';\nexport default function F(){ return getSecret(); }\n",
+      'lib/secret.ts': "import 'server-only';\nexport const getSecret = () => 1;\n",
+    });
+    const scan = await analyze(fs);
+    const leaks = scan.contractViolations.filter((v) => v.kind === 'rsc-leak');
+    expect(
+      leaks.some((l) => l.edge?.from === 'app/Form.tsx' && l.edge?.to === 'lib/secret.ts'),
+    ).toBe(true);
+  });
+
+  it('flags a transitive leak: client -> shared barrel -> server', () => {
+    const modules = [
+      mod('app/Form.tsx', 'client'),
+      mod('lib/index.ts', 'shared'), // barrel
+      mod('lib/db.ts', 'server'),
+    ];
+    const edges = [
+      edge('app/Form.tsx', 'lib/index.ts'), // client -> shared (legal alone)
+      edge('lib/index.ts', 'lib/db.ts'), // shared re-exports server
+    ];
+    const leaks = detectRscLeaks({ modules, edges });
+    const transitive = leaks.find(
+      (l) => l.edge?.from === 'app/Form.tsx' && l.edge?.to === 'lib/db.ts',
+    );
+    expect(transitive).toBeDefined();
+    expect(transitive?.kind).toBe('rsc-leak');
+  });
+
+  it('does not flag a client -> shared chain that never reaches a server module', () => {
+    const modules = [
+      mod('app/Form.tsx', 'client'),
+      mod('lib/index.ts', 'shared'),
+      mod('lib/util.ts', 'shared'),
+    ];
+    const edges = [edge('app/Form.tsx', 'lib/index.ts'), edge('lib/index.ts', 'lib/util.ts')];
+    expect(detectRscLeaks({ modules, edges })).toHaveLength(0);
+  });
+
+  it('does not double-report when a client directly imports a server module', () => {
+    const modules = [mod('app/Form.tsx', 'client'), mod('lib/db.ts', 'server')];
+    const edges = [edge('app/Form.tsx', 'lib/db.ts')];
+    const leaks = detectRscLeaks({ modules, edges }).filter(
+      (l) => l.edge?.from === 'app/Form.tsx' && l.edge?.to === 'lib/db.ts',
+    );
+    expect(leaks).toHaveLength(1);
+  });
+
   it('does not flag type-only edges or shared modules', () => {
     const modules = [mod('a.ts', 'client'), mod('b.ts', 'server'), mod('shared.ts', 'shared')];
     const edges = [
@@ -110,14 +219,14 @@ describe('detectRscLeaks', () => {
 });
 
 describe('rsc-leak end-to-end', () => {
-  it('surfaces client->server import as a contract violation in analyze()', async () => {
+  it('surfaces client->server-only import as a contract violation in analyze()', async () => {
     const fs = createInMemoryFileSource('/repo', {
       'package.json': JSON.stringify({ name: 'x' }),
       'app/page.tsx':
         "import { db } from '../lib/db';\nexport default function P(){ return db; }\n",
       'app/Form.tsx':
         "'use client';\nimport { db } from '../lib/db';\nexport default function F(){ return db; }\n",
-      'lib/db.ts': "'use server';\nexport const db = 1;\n",
+      'lib/db.ts': "import 'server-only';\nexport const db = 1;\n",
     });
 
     const scan = await analyze(fs);
@@ -127,4 +236,25 @@ describe('rsc-leak end-to-end', () => {
       true,
     );
   });
+
+  it("does not flag a client importing a 'use server' actions module in analyze()", async () => {
+    // Mirrors vercel/commerce: components/cart/modal.tsx ('use client') imports
+    // components/cart/actions.ts ('use server'). This must not be an rsc-leak.
+    const fs = createInMemoryFileSource('/repo', {
+      'package.json': JSON.stringify({ dependencies: { next: '^14.0.0' } }),
+      'components/cart/modal.tsx':
+        "'use client';\nimport { addItem } from './actions';\nexport default function M(){ return addItem; }\n",
+      'components/cart/actions.ts': "'use server';\nexport async function addItem(){ return 1; }\n",
+    });
+
+    const scan = await analyze(fs);
+    const leaks = scan.contractViolations.filter((v) => v.kind === 'rsc-leak');
+    expect(
+      leaks.some(
+        (l) =>
+          l.edge?.from === 'components/cart/modal.tsx' &&
+          l.edge?.to === 'components/cart/actions.ts',
+      ),
+    ).toBe(false);
+  });
 });

package/src/analyzer/archDebt.ts

@@ -8,20 +8,39 @@ interface Inputs {
   hotZoneCount: number;
 }
 
-// composite arch-debt 0..100 (higher = worse).
-// weights: cycles 35 / layers 30 / coupling 20 / hot zones 15. each saturates.
+// Composite **heuristic summary** arch-debt 0..100 (higher = worse). Not a
+// measurement but a weighted index of four proven components. Weights are ordered
+// by structural severity and cost-to-fix (not data-calibrated — that needs a
+// labeled corpus, see block A of the plan):
+//   - cycles 0.35   — heaviest and most expensive to fix, breaks isolation.
+//   - layers 0.30   — architectural erosion, but more local than a cycle.
+//   - coupling 0.20 — a continuous soft signal (instability), not a bug per se.
+//   - hotZones 0.15 — derived signal, partly overlaps coupling → lowest.
+// Sum = 1.0. Each component saturates, normalized to project size. Surfaced in
+// UI/reports as a "grade summary", not as a precise metric.
+const DEBT_WEIGHTS = { cycles: 0.35, layers: 0.3, coupling: 0.2, hotZones: 0.15 } as const;
+
+// Saturation divisors: the share of project modules at which a component nears
+// saturation. cycles: ~5% of modules in cycles is already "bad"; layers stricter (~3%).
+const CYCLE_SATURATION_RATIO = 0.05;
+const LAYER_SATURATION_RATIO = 0.03;
+
+// Letter-grade thresholds (score → grade). Ordinal cut-offs of the heuristic
+// summary: <15 A (healthy) … ≥70 F (systemic debt).
+const GRADE_THRESHOLDS = { A: 15, B: 30, C: 50, D: 70 } as const;
+
 export function computeArchDebt(inputs: Inputs): ArchDebt {
   const realModules = inputs.modules.filter((m) => !m.isInfra);
   const moduleCount = Math.max(1, realModules.length);
 
   const cycleWeight = inputs.cycles.reduce((acc, c) => acc + (c.severity === 'direct' ? 2 : 1), 0);
-  const cycleScore = saturate(cycleWeight / Math.max(1, moduleCount * 0.05));
+  const cycleScore = saturate(cycleWeight / Math.max(1, moduleCount * CYCLE_SATURATION_RATIO));
 
   const violationWeight = inputs.layerViolations.reduce(
     (acc, v) => acc + (v.severity === 'error' ? 3 : 1),
     0,
   );
-  const layerScore = saturate(violationWeight / Math.max(1, moduleCount * 0.03));
+  const layerScore = saturate(violationWeight / Math.max(1, moduleCount * LAYER_SATURATION_RATIO));
 
   const hotScore = saturate((inputs.hotZoneCount * 10) / moduleCount);
 
@@ -36,7 +55,11 @@ export function computeArchDebt(inputs: Inputs): ArchDebt {
   const couplingScore = instCount > 0 ? instSum / instCount : 0;
 
   const score = clamp(
-    100 * (cycleScore * 0.35 + layerScore * 0.3 + hotScore * 0.15 + couplingScore * 0.2),
+    100 *
+      (cycleScore * DEBT_WEIGHTS.cycles +
+        layerScore * DEBT_WEIGHTS.layers +
+        hotScore * DEBT_WEIGHTS.hotZones +
+        couplingScore * DEBT_WEIGHTS.coupling),
   );
 
   return {
@@ -60,9 +83,9 @@ function clamp(x: number): number {
 }
 
 function gradeOf(score: number): ArchDebt['grade'] {
-  if (score < 15) return 'A';
-  if (score < 30) return 'B';
-  if (score < 50) return 'C';
-  if (score < 70) return 'D';
+  if (score < GRADE_THRESHOLDS.A) return 'A';
+  if (score < GRADE_THRESHOLDS.B) return 'B';
+  if (score < GRADE_THRESHOLDS.C) return 'C';
+  if (score < GRADE_THRESHOLDS.D) return 'D';
   return 'F';
 }