@backthread/extractor 0.1.0

package/dist/cluster/louvain.d.ts

@@ -0,0 +1,88 @@
+import type { EdgeKind, NormalizedGraph } from '../graph/types.js';
+import type { OverrideMap } from './overrides.js';
+import type { WorkspaceLayout, WorkspacePackage } from './workspaces.js';
+export interface ClusteredModule {
+    id: string;
+    kind: 'internal' | 'external';
+    fileIds: string[];
+    externalSpecifier?: string;
+    fileCount: number;
+    loc: number;
+    degree: number;
+    godNode: boolean;
+    /**
+     * Workspace package slug this module belongs to ( Stage C). Set only
+     * for non-root packages under per-package clustering; additive — absent in
+     * single-package runs and on external/forced modules.
+     */
+    packageId?: string;
+    /**
+     * the owning workspace package's name + role, carried so the
+     * subsystem partition (cluster/subsystem.ts) can build ONE subsystem box per
+     * package, labeled app/lib/tooling. Set together with `packageId`; absent on
+     * root-scope / external / forced modules.
+     */
+    packageName?: string | null;
+    packageRole?: WorkspacePackage['role'];
+}
+export interface ModuleEdge {
+    source: string;
+    target: string;
+    weight: number;
+    kinds: EdgeKind[];
+}
+export interface ClusterResult {
+    modules: ClusteredModule[];
+    /** fileId → moduleId — the join key the changelog uses (per PR × touched module). */
+    fileModuleMap: Record<string, string>;
+    moduleEdges: ModuleEdge[];
+}
+export declare class PackagePartitionCache {
+    private entries;
+    private dirty;
+    /**
+     * Mark the packages owning these paths dirty — call with each checkpoint's
+     * diff paths BEFORE clustering that checkpoint. Conservative on purpose:
+     * any touched path (source or not) dirties its owning package; a non-source
+     * path costs at most one redundant re-cluster of a small subgraph.
+     */
+    invalidatePaths(paths: readonly string[], layout: WorkspaceLayout): void;
+    /**
+     * Drop everything — call on a full re-extract, a workspace-layout change
+     * (a diff touching isWorkspaceManifestPath), or an overrides change (slugs
+     * and forced membership both feed the stored partitions).
+     */
+    invalidateAll(): void;
+    /**
+     * The cluster-layer read: a stored partition is reusable ONLY when the
+     * package is clean AND its member set is unchanged (`memberKey` = sorted
+     * '\n'-join of member fileIds — the same key clusterGraph computes).
+     */
+    lookup(slug: string, memberKey: string): Record<string, number> | null;
+    /** The cluster-layer write after a (re-)cluster; clears the dirty mark. */
+    store(slug: string, memberKey: string, communities: Record<string, number>): void;
+}
+export interface ClusterOptions {
+    /**
+     * Workspace layout (detectWorkspaceLayout). ≥2 packages ⇒ per-package
+     * clustering: Louvain within packages only, manifest boundaries between
+     * them, workspace-name externals remapped to entry modules.
+     */
+    layout?: WorkspaceLayout;
+    /**
+     * The prior extraction's cluster modules (ExtractionCache.modules) →
+     * module-id stabilization: fresh modules that substantially overlap a prior
+     * module (Jaccard ≥ 0.5 on file sets) adopt its id, so the changelog join
+     * key survives re-clusters and the enrich set-diff reuses prior labels.
+     */
+    priorModules?: ReadonlyArray<Pick<ClusteredModule, 'id' | 'kind' | 'fileIds'>>;
+    /** In-boot warm partition reuse across the merge-walk's checkpoints. */
+    partitionCache?: PackagePartitionCache;
+}
+export declare function clusterGraph(graph: NormalizedGraph, overrides?: OverrideMap, opts?: ClusterOptions): ClusterResult;
+export declare function stabilizeModuleIds(modules: ClusteredModule[], fileModuleMap: Record<string, string>, priorModules: ReadonlyArray<Pick<ClusteredModule, 'id' | 'kind' | 'fileIds'>>, opts?: {
+    forcedIds?: ReadonlySet<string>;
+}): void;
+export declare function detectGodNodes(nodes: string[], adjacency: Map<string, Set<string>>): Set<string>;
+export declare function betweenness(nodes: string[], adjacency: Map<string, Set<string>>): Map<string, number>;
+//# sourceMappingURL=louvain.d.ts.map

package/dist/cluster/louvain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"louvain.d.ts","sourceRoot":"","sources":["../../src/cluster/louvain.ts"],"names":[],"mappings":"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"}