Function proposeParameterizedHelper

src/codegraph/helper-extract.ts:236–294

(members: FunctionUnit[], helperName = 'extractedHelper')

 * rather than proposing something wrong. PURE.
 */
export function proposeParameterizedHelper(members: FunctionUnit[], helperName = 'extractedHelper'): ParamProposal {
  const decline = (reason: string): ParamProposal => ({ ok: false, reason, helperName, params: [], sketch: '', calls: [] });
  if (members.length < 2) return decline('need at least two functions');

  // Neutralize each function's own name, and strip comments BEFORE aligning: two bodies that
  // differ only in comments are the same code (dogfooding caught 100%-similar pairs declining
  // as "structurally divergent" purely because their comments tokenized differently).
  let bodies = members.map(m => stripComments(m.body).replace(new RegExp(`\\b${m.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'), helperName));
  let toks = bodies.map(b => rawTokens(b));
  let dropped: string[] | undefined;
  if (toks.some(t => t.length !== toks[0]!.length)) {
    // Mixed structural variants in one cluster (e.g. a Number family + a BigInt family): keep the
    // LARGEST same-token-count subset and report the rest as dropped, instead of declining outright.
    const byCount = new Map<number, number[]>();
    toks.forEach((t, i) => { const k = t.length; if (!byCount.has(k)) byCount.set(k, []); byCount.get(k)!.push(i); });
    const best = [...byCount.values()].sort((a, b) => b.length - a.length)[0]!;
    if (best.length < 2) return decline('bodies do not align structurally (token counts differ) — too divergent to parameterize mechanically');
    dropped = members.filter((_, i) => !best.includes(i)).map(m => m.name);
    members = best.map(i => members[i]!);
    bodies = best.map(i => bodies[i]!);
    toks = best.map(i => toks[i]!);
  }

  // Positions where members disagree, grouped by their value-vector (co-varying positions = one param).
  const n = toks[0]!.length;
  const groups = new Map<string, number[]>();
  for (let p = 0; p < n; p++) {
    const values = toks.map(t => t[p]!.text);
    if (values.every(v => v === values[0])) continue;
    const key = JSON.stringify(values);
    if (!groups.has(key)) groups.set(key, []);
    groups.get(key)!.push(p);
  }
  if (groups.size === 0) return decline('bodies are identical — use consolidate-dupes, no parameter needed');
  if (groups.size > 4) return decline(`${groups.size} independently-varying parts — too many to parameterize cleanly`);

  // Name each parameter from context when possible (`kind: "min"` → param `kind`), else p1/p2….
  const used = new Set<string>();
  const params: { name: string; values: string[]; positions: number[] }[] = [];
  for (const [key, positions] of groups) {
    const first = positions[0]!;
    const ref = toks[0]!;
    let name = ref[first - 1]?.text === ':' && /^[A-Za-z_$][\w$]*$/.test(ref[first - 2]?.text ?? '') ? ref[first - 2]!.text : `p${params.length + 1}`;
    while (used.has(name)) name = `${name}_`;
    used.add(name);
    params.push({ name, values: JSON.parse(key), positions });
  }

  // Sketch: reference body with each varying token replaced by its parameter name (right-to-left).
  let sketch = bodies[0]!;
  const subs = params.flatMap(p => p.positions.map(pos => ({ pos, name: p.name })))
    .sort((a, b) => toks[0]![b.pos]!.start - toks[0]![a.pos]!.start);
  for (const s of subs) {
    const t = toks[0]![s.pos]!;
    sketch = sketch.slice(0, t.start) + s.name + sketch.slice(t.start + t.text.length);
  }
  const calls = members.map((m, i) => ({ member: m.name, args: params.map(p => p.values[i]!) }));
  return { ok: true, helperName, params: params.map(({ name, values }) => ({ name, values })), sketch, calls, dropped };