@hegemonart/get-design-done 1.52.0 → 1.53.0

package/scripts/lib/mappers/incremental-discover.d.cts

@@ -0,0 +1,133 @@
+// scripts/lib/mappers/incremental-discover.d.cts — types for incremental-discover.cjs (Phase 53 DISC-01).
+//
+// Mirrors the .d.cts sidecar convention used by concurrency-tuner.cjs so the
+// .ts explore-parallel-runner can import planIncremental without a TS7016
+// implicit-any. The runtime module is dep-free CJS (it dynamic-import()s the
+// .mjs batchers + the .ts fingerprint engine internally).
+
+/** A community batch (the A-subsystem `computeBatches` shape). */
+export interface Batch {
+  id: string;
+  members: string[];
+  mergeable: boolean;
+  kind: 'code' | 'token' | 'motion' | 'a11y' | 'misc';
+  source: 'louvain' | 'fallback' | 'subsplit' | 'merge';
+}
+
+/** A single per-node fingerprint-compare entry fed to the classifier. */
+export interface CompareResult {
+  id: string;
+  type?: string;
+  change: 'NONE' | 'COSMETIC' | 'STRUCTURAL';
+}
+
+/** The change-classifier result (sdk/fingerprint/classify.cjs). */
+export interface Classification {
+  action: 'SKIP' | 'PARTIAL_UPDATE' | 'ARCHITECTURE_UPDATE' | 'FULL_UPDATE';
+  structuralCount: number;
+  pct: number;
+  dirChanged: boolean;
+  majorRestructure: boolean;
+  affectedBatchHints: string[];
+  reason: string;
+  thresholds: { fullFileCount: number; fullPct: number; archPctMax: number };
+}
+
+/** A per-node fingerprint pair plus its node type, as persisted to the store. */
+export interface StoredFingerprint {
+  full: string;
+  structural: string;
+  type?: string;
+}
+
+/** The neighborMap sidecar for one batch (neighbor-map.mjs shape). */
+export interface NeighborMap {
+  batchId: string | null;
+  neighbors: Record<string, unknown[]>;
+  truncated: Record<string, { omitted: number }>;
+}
+
+/** Options bag for planIncremental. */
+export interface PlanIncrementalOptions {
+  /** The `--full` opt-out: force a FULL re-map regardless of the classifier. */
+  forceFull?: boolean;
+  /** Forwarded to computeBatches (resolution, maxCommunitySize, configCwd, …). */
+  computeBatchesOpts?: unknown;
+  /** buildNeighborMap cap (default 50). */
+  neighborCap?: number;
+  /** Forwarded into classify's projectStats.thresholds. */
+  thresholds?: unknown;
+  /** Force the bootstrap signal off when the store had a snapshot but it was empty. */
+  hadPriorBaseline?: boolean;
+}
+
+/** The incremental plan returned by planIncremental. */
+export interface IncrementalPlan {
+  action: 'SKIP' | 'PARTIAL_UPDATE' | 'ARCHITECTURE_UPDATE' | 'FULL_UPDATE';
+  batches: Batch[];
+  batchesToMap: Batch[];
+  neighborMaps: Record<string, NeighborMap>;
+  fingerprints: Record<string, StoredFingerprint>;
+  compareResults: CompareResult[];
+  classification: Classification;
+  method: 'louvain' | 'count-fallback';
+  modularity: number | null;
+}
+
+/** A DirShape derived from node-id provenance. */
+export interface DirShape {
+  dirs: string[];
+  counts: Record<string, number>;
+  layerHist: Record<string, number>;
+}
+
+/**
+ * Plan an incremental discover/explore cycle: compute community batches, run the
+ * change classifier against the prior fingerprint snapshot, and elect which
+ * batches to re-map (SKIP=[], PARTIAL=affected, FULL=all). Async (it
+ * dynamic-import()s the .mjs batchers + the .ts fingerprint engine).
+ */
+export function planIncremental(args: {
+  graph: unknown;
+  prevFingerprints?: unknown;
+  opts?: PlanIncrementalOptions;
+}): Promise<IncrementalPlan>;
+
+/** Pure batch-selection matrix: SKIP→[], FULL→all, PARTIAL/ARCH→hint intersection. */
+export function selectBatches(
+  batches: Batch[],
+  action: string,
+  affectedBatchHints: string[],
+): Batch[];
+
+/** Derive the current DirShape (+ totalFiles) from a graph's file-nodes. */
+export function deriveDirShape(
+  graph: unknown,
+): DirShape & { totalFiles: number };
+
+/** Reconstruct the prior DirShape from a prevFingerprints map (null when empty). */
+export function derivePrevDirShape(
+  prevFingerprints: unknown,
+): DirShape | null;
+
+/** Build current fingerprints + the compareResults change set for a graph. */
+export function buildCompareResults(
+  graph: unknown,
+  prevFingerprints: unknown,
+  fingerprint: (input: unknown, type: string) => { full: string; structural: string },
+  compareFingerprints: (
+    a: { full: string; structural: string } | null,
+    b: { full: string; structural: string } | null,
+  ) => string,
+): { fingerprints: Record<string, StoredFingerprint>; compareResults: CompareResult[] };
+
+/** Project one fingerprintable node into its per-type fingerprint input. */
+export function projectNode(node: unknown, fpType: string, idx: unknown): unknown;
+
+/** Build the once-per-graph relationship index used by projectNode. */
+export function indexForProjection(
+  graph: unknown,
+): { byId: Map<string, unknown>; tokensOf: Map<string, Set<string>>; variantsOf: Map<string, Set<string>> };
+
+/** The graph node `type` values that are independently fingerprinted. */
+export const FINGERPRINTABLE: Map<string, string>;

package/sdk/cli/index.js

@@ -527,6 +527,329 @@ var require_concurrency_tuner = __commonJS({
   }
 });
 
+// scripts/lib/mappers/incremental-discover.cjs
+var require_incremental_discover = __commonJS({
+  "scripts/lib/mappers/incremental-discover.cjs"(exports2, module2) {
+    "use strict";
+    var path = require("node:path");
+    var fs = require("node:fs");
+    var { pathToFileURL } = require("node:url");
+    function pkgRoot() {
+      let dir = __dirname;
+      for (let i = 0; i < 10; i += 1) {
+        if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+      return process.cwd();
+    }
+    var ROOT = pkgRoot();
+    var MAPPERS_DIR = path.join(ROOT, "scripts", "lib", "mappers");
+    var SDK_FP_DIR = path.join(ROOT, "sdk", "fingerprint");
+    var _classify = null;
+    function classify(...args) {
+      if (!_classify) _classify = require(path.join(SDK_FP_DIR, "classify.cjs")).classify;
+      return _classify(...args);
+    }
+    var _batchMod = null;
+    var _neighborMod = null;
+    var _fpMod = null;
+    async function loadBatchMod() {
+      if (!_batchMod) {
+        _batchMod = await import(pathToFileURL(path.join(MAPPERS_DIR, "compute-batches.mjs")).href);
+      }
+      return _batchMod;
+    }
+    async function loadNeighborMod() {
+      if (!_neighborMod) {
+        _neighborMod = await import(pathToFileURL(path.join(MAPPERS_DIR, "neighbor-map.mjs")).href);
+      }
+      return _neighborMod;
+    }
+    async function loadFingerprintMod() {
+      if (!_fpMod) {
+        _fpMod = await import(pathToFileURL(path.join(SDK_FP_DIR, "index.ts")).href);
+      }
+      return _fpMod;
+    }
+    function nodeList(graph) {
+      return Array.isArray(graph && graph.nodes) ? graph.nodes : [];
+    }
+    function edgeList(graph) {
+      return Array.isArray(graph && graph.edges) ? graph.edges : [];
+    }
+    var STRUCTURAL_EDGE_TYPES = /* @__PURE__ */ new Set([
+      "composes",
+      "extends",
+      "depends-on",
+      "consumes-context",
+      "provides-context"
+    ]);
+    var FINGERPRINTABLE = /* @__PURE__ */ new Map([
+      ["component", "component"],
+      ["token", "token"],
+      ["motion-fragment", "motion"]
+    ]);
+    function indexForProjection(graph) {
+      const byId = /* @__PURE__ */ new Map();
+      for (const n of nodeList(graph)) {
+        if (n && typeof n.id === "string") byId.set(n.id, n);
+      }
+      const tokensOf = /* @__PURE__ */ new Map();
+      const variantsOf = /* @__PURE__ */ new Map();
+      const ensure = (map, id) => {
+        let s = map.get(id);
+        if (!s) {
+          s = /* @__PURE__ */ new Set();
+          map.set(id, s);
+        }
+        return s;
+      };
+      const typeOf = (id) => byId.get(id) && byId.get(id).type;
+      const nameOf = (id) => {
+        const node = byId.get(id);
+        return node && typeof node.name === "string" ? node.name : id;
+      };
+      for (const e of edgeList(graph)) {
+        if (!e || typeof e.source !== "string" || typeof e.target !== "string") continue;
+        const sType = typeOf(e.source);
+        const tType = typeOf(e.target);
+        if (e.type === "uses-token") {
+          if (sType === "component" && tType === "token") ensure(tokensOf, e.source).add(e.target);
+          else if (tType === "component" && sType === "token") ensure(tokensOf, e.target).add(e.source);
+        } else if (e.type === "extends") {
+          if (tType === "component" && (sType === "variant" || sType === "state")) {
+            ensure(variantsOf, e.target).add(nameOf(e.source));
+          } else if (sType === "component" && (tType === "variant" || tType === "state")) {
+            ensure(variantsOf, e.source).add(nameOf(e.target));
+          }
+        } else if (STRUCTURAL_EDGE_TYPES.has(e.type)) {
+          if (sType === "component" && tType === "state") ensure(variantsOf, e.source).add(nameOf(e.target));
+          else if (tType === "component" && sType === "state") ensure(variantsOf, e.target).add(nameOf(e.source));
+        }
+      }
+      return { byId, tokensOf, variantsOf };
+    }
+    function strArray(v) {
+      if (!Array.isArray(v)) return [];
+      const out = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const x of v) {
+        const s = typeof x === "string" ? x : x && typeof x.name === "string" ? x.name : null;
+        if (s != null && !seen.has(s)) {
+          seen.add(s);
+          out.push(s);
+        }
+      }
+      out.sort();
+      return out;
+    }
+    function propShape(props) {
+      if (!Array.isArray(props)) return [];
+      const out = [];
+      for (const p of props) {
+        if (typeof p === "string") {
+          out.push({ name: p, type: "" });
+        } else if (p && typeof p === "object" && typeof p.name === "string") {
+          out.push({
+            name: p.name,
+            type: typeof p.type === "string" ? p.type : "",
+            ...typeof p.optional === "boolean" ? { optional: p.optional } : {}
+          });
+        }
+      }
+      return out;
+    }
+    function projectNode(node, fpType, idx) {
+      if (fpType === "component") {
+        const usedTokens = idx.tokensOf.has(node.id) ? [...idx.tokensOf.get(node.id)].sort() : [];
+        const variantsFromGraph = idx.variantsOf.has(node.id) ? [...idx.variantsOf.get(node.id)] : [];
+        const variantsFromNode = strArray(node.exported_variants || node.variants);
+        const exportedVariants = [.../* @__PURE__ */ new Set([...variantsFromGraph, ...variantsFromNode])].sort();
+        return {
+          component_signature: {
+            name: typeof node.name === "string" ? node.name : node.id,
+            members: strArray(node.members)
+          },
+          props_shape: propShape(node.props),
+          used_tokens: usedTokens,
+          exported_variants: exportedVariants
+        };
+      }
+      if (fpType === "token") {
+        return {
+          token_name: typeof node.name === "string" ? node.name : node.id,
+          token_value: node.value === void 0 ? null : typeof node.value === "object" ? JSON.stringify(node.value) : node.value,
+          token_type: typeof node.subtype === "string" ? node.subtype : typeof node.token_type === "string" ? node.token_type : "",
+          ...typeof node.subtype === "string" ? { subtype: node.subtype } : {},
+          ...typeof node.theme_scope === "string" ? { theme_scope: node.theme_scope } : {}
+        };
+      }
+      return {
+        animation_target: typeof node.name === "string" ? node.name : node.id,
+        ...Number.isFinite(node.duration_ms) ? { duration_ms: node.duration_ms } : {},
+        ...typeof node.easing === "string" ? { easing: node.easing } : {}
+      };
+    }
+    function idNamespace(id) {
+      if (typeof id !== "string") return "unknown";
+      const i = id.indexOf(":");
+      return i > 0 ? id.slice(0, i) : id;
+    }
+    function isFileNode(node) {
+      return !!node && FINGERPRINTABLE.has(node.type);
+    }
+    function deriveDirShape(graph) {
+      const counts = {};
+      const layerHist = {};
+      let totalFiles = 0;
+      for (const n of nodeList(graph)) {
+        if (!isFileNode(n)) continue;
+        totalFiles += 1;
+        const ns = idNamespace(n.id);
+        let dir = ns;
+        if (n.type === "token" && typeof n.subtype === "string" && n.subtype.length) {
+          dir = `token:${n.subtype}`;
+        }
+        counts[dir] = (counts[dir] || 0) + 1;
+        layerHist[ns] = (layerHist[ns] || 0) + 1;
+      }
+      const dirs = Object.keys(counts).sort();
+      return { dirs, counts, layerHist, totalFiles };
+    }
+    function derivePrevDirShape(prevFingerprints) {
+      const fps = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const ids = Object.keys(fps);
+      if (ids.length === 0) return null;
+      const counts = {};
+      const layerHist = {};
+      for (const id of ids) {
+        const ns = idNamespace(id);
+        let dir = ns;
+        if (ns === "token") {
+          const parts = id.split(":");
+          if (parts.length >= 3 && parts[1]) dir = `token:${parts[1]}`;
+        }
+        counts[dir] = (counts[dir] || 0) + 1;
+        layerHist[ns] = (layerHist[ns] || 0) + 1;
+      }
+      return { dirs: Object.keys(counts).sort(), counts, layerHist };
+    }
+    function asFingerprint(v) {
+      if (v == null) return null;
+      if (typeof v === "string") return { full: v, structural: v };
+      if (typeof v === "object" && typeof v.full === "string") {
+        return { full: v.full, structural: typeof v.structural === "string" ? v.structural : v.full };
+      }
+      return null;
+    }
+    function buildCompareResults(graph, prevFingerprints, fingerprint, compareFingerprints) {
+      const idx = indexForProjection(graph);
+      const prev = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const fingerprints = {};
+      const compareResults = [];
+      const currentIds = /* @__PURE__ */ new Set();
+      for (const node of nodeList(graph)) {
+        if (!node || typeof node.id !== "string") continue;
+        const fpType = FINGERPRINTABLE.get(node.type);
+        if (!fpType) continue;
+        currentIds.add(node.id);
+        let fp;
+        try {
+          fp = fingerprint(projectNode(node, fpType, idx), fpType);
+        } catch {
+          compareResults.push({ id: node.id, type: node.type, change: "STRUCTURAL" });
+          continue;
+        }
+        fingerprints[node.id] = { full: fp.full, structural: fp.structural, type: node.type };
+        const before = asFingerprint(prev[node.id]);
+        const change = compareFingerprints(before, { full: fp.full, structural: fp.structural });
+        compareResults.push({ id: node.id, type: node.type, change });
+      }
+      for (const id of Object.keys(prev)) {
+        if (currentIds.has(id)) continue;
+        const before = asFingerprint(prev[id]);
+        const change = compareFingerprints(before, null);
+        const t = prev[id] && typeof prev[id] === "object" && typeof prev[id].type === "string" ? prev[id].type : idNamespace(id);
+        compareResults.push({ id, type: t, change });
+      }
+      return { fingerprints, compareResults };
+    }
+    function selectBatches(batches, action, affectedBatchHints) {
+      const all = Array.isArray(batches) ? batches : [];
+      if (action === "SKIP") return [];
+      if (action === "FULL_UPDATE") return all.slice();
+      const hints = new Set(Array.isArray(affectedBatchHints) ? affectedBatchHints : []);
+      if (hints.size === 0) return [];
+      const out = [];
+      for (const b of all) {
+        const members = Array.isArray(b && b.members) ? b.members : [];
+        if (members.some((m) => hints.has(m))) out.push(b);
+      }
+      return out;
+    }
+    async function planIncremental2(args) {
+      const { graph, prevFingerprints, opts } = args && typeof args === "object" ? args : {};
+      const o = opts && typeof opts === "object" ? opts : {};
+      const prev = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const { computeBatches } = await loadBatchMod();
+      const { batches, modularity, method } = computeBatches(graph, o.computeBatchesOpts);
+      const { fingerprint, compareFingerprints } = await loadFingerprintMod();
+      const { fingerprints, compareResults } = buildCompareResults(
+        graph,
+        prev,
+        fingerprint,
+        compareFingerprints
+      );
+      const currDirShape = deriveDirShape(graph);
+      let prevDirShape = derivePrevDirShape(prev);
+      if (o.hadPriorBaseline === false) prevDirShape = null;
+      const projectStats = {
+        totalFiles: currDirShape.totalFiles,
+        prevDirShape,
+        currDirShape: { dirs: currDirShape.dirs, counts: currDirShape.counts, layerHist: currDirShape.layerHist },
+        ...o.thresholds && typeof o.thresholds === "object" ? { thresholds: o.thresholds } : {}
+      };
+      const classification = classify(compareResults, projectStats);
+      const effectiveAction = o.forceFull ? "FULL_UPDATE" : classification.action;
+      const batchesToMap = selectBatches(batches, effectiveAction, classification.affectedBatchHints);
+      const neighborMaps = {};
+      if (batchesToMap.length > 0) {
+        const { buildNeighborMap } = await loadNeighborMod();
+        const cap = Number.isInteger(o.neighborCap) && o.neighborCap >= 0 ? o.neighborCap : 50;
+        for (const b of batchesToMap) {
+          if (b && typeof b.id === "string") {
+            neighborMaps[b.id] = buildNeighborMap(b, graph, { cap });
+          }
+        }
+      }
+      return {
+        action: effectiveAction,
+        batches,
+        batchesToMap,
+        neighborMaps,
+        fingerprints,
+        compareResults,
+        classification,
+        method,
+        modularity
+      };
+    }
+    module2.exports = {
+      planIncremental: planIncremental2,
+      // exported for the wiring layer + tests (pure helpers, no side effects).
+      selectBatches,
+      deriveDirShape,
+      derivePrevDirShape,
+      buildCompareResults,
+      projectNode,
+      indexForProjection,
+      FINGERPRINTABLE
+    };
+  }
+});
+
 // sdk/cli/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -5560,6 +5883,7 @@ var import_node_path14 = require("node:path");
 // scripts/lib/explore-parallel-runner/index.ts
 var import_node_path12 = require("node:path");
 var import_concurrency_tuner = __toESM(require_concurrency_tuner());
+var import_incremental_discover = __toESM(require_incremental_discover());
 
 // scripts/lib/explore-parallel-runner/mappers.ts
 var import_node_fs12 = require("node:fs");
@@ -5903,6 +6227,47 @@ async function run3(opts) {
   const concurrency = opts.concurrency ?? (0, import_concurrency_tuner.resolveConcurrency)();
   const logger = getLogger().child("explore.runner");
   const outputPath = (0, import_node_path12.resolve)(cwd, ".design/DESIGN-PATTERNS.md");
+  let batching = void 0;
+  if (opts.incremental && opts.incremental.graph !== void 0 && opts.incremental.graph !== null) {
+    try {
+      const plan = await (0, import_incremental_discover.planIncremental)({
+        graph: opts.incremental.graph,
+        prevFingerprints: opts.incremental.prevFingerprints,
+        opts: {
+          ...opts.incremental.forceFull !== void 0 ? { forceFull: opts.incremental.forceFull } : {},
+          ...opts.incremental.computeBatchesOpts !== void 0 ? { computeBatchesOpts: opts.incremental.computeBatchesOpts } : {},
+          ...opts.incremental.neighborCap !== void 0 ? { neighborCap: opts.incremental.neighborCap } : {},
+          ...opts.incremental.thresholds !== void 0 ? { thresholds: opts.incremental.thresholds } : {}
+        }
+      });
+      batching = Object.freeze({
+        action: plan.action,
+        method: plan.method,
+        modularity: plan.modularity,
+        batches: Object.freeze(plan.batches.map((b) => Object.freeze({
+          id: b.id,
+          members: Object.freeze([...b.members]),
+          mergeable: b.mergeable,
+          kind: b.kind,
+          source: b.source
+        }))),
+        batchesToMap: Object.freeze(plan.batchesToMap.map((b) => b.id)),
+        neighborMaps: Object.freeze({ ...plan.neighborMaps }),
+        classification: Object.freeze({ ...plan.classification })
+      });
+      logger.info("explore.runner.batching", {
+        action: plan.action,
+        method: plan.method,
+        batch_count: plan.batches.length,
+        batches_to_map: plan.batchesToMap.length,
+        structural_count: plan.classification.structuralCount
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn("explore.runner.batching_failed", { message });
+      batching = void 0;
+    }
+  }
   logger.info("explore.runner.started", {
     mapper_count: specs.length,
     concurrency
@@ -5924,7 +6289,8 @@ async function run3(opts) {
       }),
       parallel_count: 0,
       serial_count: 0,
-      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 }
+      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      ...batching !== void 0 ? { batching } : {}
     });
   }
   const safeSpecs = [];
@@ -6040,7 +6406,8 @@ async function run3(opts) {
       input_tokens: totalInput,
       output_tokens: totalOutput,
       usd_cost: totalCost
-    }
+    },
+    ...batching !== void 0 ? { batching } : {}
   });
 }