fix(louvain): demote native-path parity warning to debug (#989)

* fix(louvain): demote native-path parity warning to debug

Warning fired on every communities computation because DEFAULTS.community
in config.ts always populates maxLevels/maxLocalPasses/refinementTheta, so
the != null guard never gated anything in practice. The message is an
informational parity note (Leiden knobs ignored by native Louvain), not
user-actionable — debug is the right level.

docs check acknowledged: no language/architecture/feature changes.

Impact: 1 functions changed, 10 affected

* test(louvain): add regression guard for parity log level (#989)

Author: carlos-alm

src/graph/algorithms/louvain.ts

@@ -6,7 +6,7 @@
  * JS fallback: Leiden algorithm via `detectClusters` (always undirected, `directed: false`).
  */
 
-import { warn } from '../../infrastructure/logger.js';
+import { debug } from '../../infrastructure/logger.js';
 import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 import type { DetectClustersResult } from './leiden/index.js';
@@ -36,10 +36,8 @@ export function louvainCommunities(graph: CodeGraph, opts: LouvainOptions = {}):
 
   const native = loadNative();
   if (native?.louvainCommunities) {
-    // maxLevels, maxLocalPasses, and refinementTheta are Leiden-specific tuning knobs
-    // not supported by the Rust Louvain implementation. Warn callers who set them.
     if (opts.maxLevels != null || opts.maxLocalPasses != null || opts.refinementTheta != null) {
-      warn(
+      debug(
         'louvainCommunities: maxLevels/maxLocalPasses/refinementTheta are ignored by the native Rust path',
       );
     }

tests/graph/algorithms/louvain.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { louvainCommunities } from '../../../src/graph/algorithms/louvain.js';
 import { CodeGraph } from '../../../src/graph/model.js';
+import { setVerbose } from '../../../src/infrastructure/logger.js';
 
 describe('louvainCommunities', () => {
   it('returns empty for empty graph', () => {
@@ -45,4 +46,68 @@ describe('louvainCommunities', () => {
     expect(assignments.size).toBe(0);
     expect(modularity).toBe(0);
   });
+
+  describe('Leiden-knob parity logging', () => {
+    let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    });
+
+    afterEach(() => {
+      stderrSpy.mockRestore();
+      setVerbose(false);
+    });
+
+    function buildTwoClusterGraph(): CodeGraph {
+      const g = new CodeGraph();
+      g.addEdge('a', 'b');
+      g.addEdge('b', 'c');
+      g.addEdge('c', 'a');
+      g.addEdge('x', 'y');
+      g.addEdge('y', 'z');
+      g.addEdge('z', 'x');
+      g.addEdge('c', 'x');
+      return g;
+    }
+
+    // Regression guard: DEFAULTS.community always populates maxLevels/maxLocalPasses/
+    // refinementTheta, so forwarding config values used to emit `[codegraph WARN]` on
+    // every communities computation. Keep the parity note at debug level — never warn.
+    it('never emits the parity message at WARN level when config defaults are forwarded', () => {
+      const g = buildTwoClusterGraph();
+      louvainCommunities(g, {
+        maxLevels: 50,
+        maxLocalPasses: 20,
+        refinementTheta: 1.0,
+      });
+
+      const warnWrites = stderrSpy.mock.calls
+        .map(([chunk]) => (typeof chunk === 'string' ? chunk : (chunk?.toString?.() ?? '')))
+        .filter((line) => line.includes('[codegraph WARN]'));
+      expect(warnWrites).toEqual([]);
+    });
+
+    it('emits the parity message at DEBUG level when verbose is enabled and Leiden knobs are set', () => {
+      setVerbose(true);
+      const g = buildTwoClusterGraph();
+      louvainCommunities(g, {
+        maxLevels: 50,
+        maxLocalPasses: 20,
+        refinementTheta: 1.0,
+      });
+
+      const writes = stderrSpy.mock.calls
+        .map(([chunk]) => (typeof chunk === 'string' ? chunk : (chunk?.toString?.() ?? '')))
+        .join('');
+      // Message is only emitted on the native path. When native is unavailable we at
+      // least assert no WARN was emitted (covered by the previous test); when it is
+      // available, it must go through the DEBUG channel and never WARN.
+      expect(writes).not.toContain('[codegraph WARN]');
+      // Allow either outcome for DEBUG depending on engine availability.
+      if (writes.includes('maxLevels/maxLocalPasses/refinementTheta')) {
+        expect(writes).toContain('[codegraph DEBUG]');
+      }
+    });
+  });
 });