@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/graph/category-clusters.ts

@@ -0,0 +1,194 @@
+import type { FeaturePoint3D } from "./feature-3d.js";
+import type { FeatureMapEdgeV1, FeatureMapNodeV1 } from "./feature-model.js";
+
+export type CategoryClusterDimension = "code" | "test" | "owner" | "intent" | "unmapped";
+export type CategoryClusterNode = Pick<FeatureMapNodeV1, "id" | "kind"> &
+  Partial<Pick<FeatureMapNodeV1, "label" | "path" | "details" | "status">>;
+
+export interface CategoryClusterGroup {
+  id: string;
+  kind: "category" | "shared" | "unassigned";
+  label: string;
+  center: FeaturePoint3D;
+  memberIds: string[];
+}
+
+export interface CategoryClusterLayout {
+  positions: Record<string, FeaturePoint3D>;
+  groups: CategoryClusterGroup[];
+  memberships: Record<string, string[]>;
+  description: string;
+}
+
+/** Self-contained browser geometry; context paths are declarations, never inferred ownership. */
+export function createCategoryClusterLayout(
+  nodes: readonly CategoryClusterNode[],
+  edges: readonly Pick<FeatureMapEdgeV1, "from" | "to" | "kind">[],
+  dimension: CategoryClusterDimension,
+): CategoryClusterLayout {
+  const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  const descriptions: Record<CategoryClusterDimension, string> = {
+    code: "Code areas use repository-relative directories. Other nodes show declared feature context.",
+    test: "Test areas use repository-relative directories. Other nodes show declared feature context.",
+    owner:
+      "Ownership groups use declared roles and feature scopes. They do not establish file ownership.",
+    intent:
+      "Vision / Spec groups use source paths and declared feature scopes, not semantic similarity.",
+    unmapped:
+      "Unassigned files use repository-relative directories. Declared context stays separate.",
+  };
+  if (!Object.hasOwn(descriptions, dimension)) throw new RangeError("Unknown grouping category.");
+  const ordered = [...nodes].sort((a, b) => compare(a.id, b.id));
+  const byId = new Map(ordered.map((node) => [node.id, node]));
+  const features = new Set(
+    ordered.filter((node) => node.kind === "feature").map((node) => node.id),
+  );
+  const memberships: Record<string, string[]> = Object.create(null) as Record<string, string[]>;
+  const positions: Record<string, FeaturePoint3D> = Object.create(null) as Record<
+    string,
+    FeaturePoint3D
+  >;
+  const buckets = new Map<string, { label: string; sortKey: string; memberIds: string[] }>();
+  const anchorBuckets = new Map<string, string>();
+  const featureBuckets = new Map([...features].map((id) => [id, new Set<string>()]));
+  const linkedFeatures = new Map(ordered.map((node) => [node.id, new Set<string>()]));
+  const compatible: Record<FeatureMapNodeV1["kind"], readonly FeatureMapEdgeV1["kind"][]> = {
+    feature: [],
+    code: ["code", "test"],
+    test: ["code", "test"],
+    owner: ["ownership"],
+    intent: ["intent"],
+    unmapped: [],
+  };
+  const targetRelations: Record<CategoryClusterDimension, FeatureMapEdgeV1["kind"] | null> = {
+    code: "code",
+    test: "test",
+    owner: "ownership",
+    intent: "intent",
+    unmapped: null,
+  };
+
+  for (const node of ordered) {
+    const roles = node.details?.["roles"];
+    const hasRole = (role: string): boolean =>
+      (node.kind === "code" || node.kind === "test") &&
+      Array.isArray(roles) &&
+      roles.includes(role);
+    const anchor =
+      dimension === "code"
+        ? node.kind === "code" || node.kind === "unmapped" || hasRole("code")
+        : dimension === "test"
+          ? node.kind === "test" || hasRole("test")
+          : node.kind === dimension;
+    if (!anchor) continue;
+    let key: string;
+    let label: string;
+    if (dimension === "owner") {
+      key = node.id;
+      label = node.label || node.id;
+      if (node.status === "missing") label += " (missing ownership)";
+    } else if (dimension === "intent") {
+      key = node.path || "(no source path)";
+      label = node.path || "Intent without a source path";
+    } else if (!node.path) {
+      key = "(no source path)";
+      label = "Files without a source path";
+    } else {
+      const directories = node.path.replaceAll("\\", "/").split("/").slice(0, -1);
+      key = directories.slice(0, 2).join("/") || ".";
+      label = key === "." ? "Repository root" : key;
+    }
+    const id = dimension !== "owner" && !node.path ? `missing:${dimension}` : `${dimension}:${key}`;
+    if (!buckets.has(id)) buckets.set(id, { label, sortKey: key, memberIds: [] });
+    anchorBuckets.set(node.id, id);
+  }
+
+  if (dimension !== "unmapped") {
+    for (const edge of edges) {
+      const fromFeature = features.has(edge.from);
+      const toFeature = features.has(edge.to);
+      if (fromFeature === toFeature) continue;
+      const feature = fromFeature ? edge.from : edge.to;
+      const member = byId.get(fromFeature ? edge.to : edge.from);
+      if (!member || !compatible[member.kind].includes(edge.kind)) continue;
+      linkedFeatures.get(member.id)!.add(feature);
+      const bucket = anchorBuckets.get(member.id);
+      if (bucket !== undefined && edge.kind === targetRelations[dimension])
+        featureBuckets.get(feature)!.add(bucket);
+    }
+  }
+
+  const shared: string[] = [];
+  const outside: string[] = [];
+  for (const node of ordered) {
+    const anchor = anchorBuckets.get(node.id);
+    const categories =
+      anchor !== undefined
+        ? [anchor]
+        : [
+            ...new Set(
+              (node.kind === "feature" ? [node.id] : [...linkedFeatures.get(node.id)!]).flatMap(
+                (id) => [...featureBuckets.get(id)!],
+              ),
+            ),
+          ].sort(compare);
+    memberships[node.id] = categories;
+    if (categories.length === 1) buckets.get(categories[0]!)!.memberIds.push(node.id);
+    else if (categories.length > 1) shared.push(node.id);
+    else outside.push(node.id);
+  }
+
+  const primary = [...buckets].sort(
+    ([a, first], [b, second]) => compare(first.sortKey, second.sortKey) || compare(a, b),
+  );
+  const columns = Math.max(1, Math.ceil(Math.sqrt(primary.length * 1.3)));
+  const rows = Math.ceil(primary.length / columns);
+  const stepX = Math.min(140, 700 / Math.max(1, columns - 1));
+  const stepY = Math.min(110, 400 / Math.max(1, rows - 1));
+  const radius = primary.length === 1 ? 140 : Math.min(50, Math.min(stepX, stepY) * 0.4);
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+  const groups: CategoryClusterGroup[] = [];
+
+  function placeMembers(ids: readonly string[], center: FeaturePoint3D, extent: number): void {
+    ids.forEach((id, index) => {
+      const orbit = extent * (0.12 + 0.88 * Math.sqrt((index + 0.5) / ids.length));
+      const kind = byId.get(id)!.kind;
+      const depth = kind === "test" ? 1 : kind === "owner" ? 0.5 : kind === "intent" ? -0.5 : -1;
+      positions[id] = {
+        x: center.x + Math.cos(index * goldenAngle) * orbit,
+        y: center.y + Math.sin(index * goldenAngle) * orbit,
+        z: center.z + extent * (depth * 0.2 + ((index % 7) - 3) * 0.035),
+      };
+    });
+  }
+
+  primary.forEach(([id, bucket], index) => {
+    const row = Math.floor(index / columns);
+    const rowSize = Math.min(columns, primary.length - row * columns);
+    const center = {
+      x: ((index % columns) - (rowSize - 1) / 2) * stepX,
+      y: -65 + (row - (rows - 1) / 2) * stepY,
+      z: ((index % 3) - 1) * 12,
+    };
+    placeMembers(bucket.memberIds, center, radius);
+    groups.push({ id, kind: "category", label: bucket.label, center, memberIds: bucket.memberIds });
+  });
+
+  function addContext(kind: "shared" | "unassigned", label: string, ids: string[], x: number) {
+    if (ids.length === 0) return;
+    const center = primary.length === 0 ? { x: 0, y: 0, z: 0 } : { x, y: 270, z: 0 };
+    const extent = primary.length === 0 ? 190 : Math.min(85, 65 + Math.sqrt(ids.length) * 0.75);
+    placeMembers(ids, center, extent);
+    groups.push({ id: `context:${dimension}:${kind}`, kind, label, center, memberIds: ids });
+  }
+  const outsideLabels: Record<CategoryClusterDimension, string> = {
+    code: "Outside declared code context",
+    test: "Outside declared test context",
+    owner: "No declared ownership context",
+    intent: "No declared vision / spec context",
+    unmapped: "Declared context",
+  };
+  addContext("shared", "Shared context", shared, -175);
+  addContext("unassigned", outsideLabels[dimension], outside, 175);
+  return { positions, groups, memberships, description: descriptions[dimension] };
+}

package/src/commands/graph/feature-3d.ts

@@ -0,0 +1,141 @@
+import type { FeatureMapEdgeV1, FeatureMapNodeV1 } from "./feature-model.js";
+
+export interface FeaturePoint3D {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface FeatureCamera3D {
+  yaw: number;
+  pitch: number;
+}
+
+/** Stable spatial grouping follows declared edges. Distance is a layout choice, not evidence. */
+export function createFeatureWoolLayout(
+  nodes: readonly Pick<FeatureMapNodeV1, "id" | "kind">[],
+  edges: readonly Pick<FeatureMapEdgeV1, "from" | "to">[],
+): Record<string, FeaturePoint3D> {
+  const positions: Record<string, FeaturePoint3D> = Object.create(null) as Record<
+    string,
+    FeaturePoint3D
+  >;
+  const ordered = [...nodes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const features = ordered.filter((node) => node.kind === "feature");
+  const featureIds = new Set(features.map((node) => node.id));
+  const adjacency = new Map<string, Set<string>>();
+  for (const edge of edges) {
+    if (featureIds.has(edge.from)) {
+      if (!adjacency.has(edge.to)) adjacency.set(edge.to, new Set());
+      adjacency.get(edge.to)!.add(edge.from);
+    }
+    if (featureIds.has(edge.to)) {
+      if (!adjacency.has(edge.from)) adjacency.set(edge.from, new Set());
+      adjacency.get(edge.from)!.add(edge.to);
+    }
+  }
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+  function sphere(index: number, count: number, radius: number): FeaturePoint3D {
+    const y = 1 - (2 * (index + 0.5)) / Math.max(1, count);
+    const ring = Math.sqrt(Math.max(0, 1 - y * y));
+    return {
+      x: Math.cos(index * goldenAngle) * ring * radius,
+      y: y * radius,
+      z: Math.sin(index * goldenAngle) * ring * radius,
+    };
+  }
+  features.forEach((node, index) => {
+    positions[node.id] =
+      features.length === 1 ? { x: 0, y: 0, z: 0 } : sphere(index, features.length, 200);
+  });
+  const other = ordered.filter((node) => node.kind !== "feature");
+  other.forEach((node, index) => {
+    const linked = [...(adjacency.get(node.id) ?? [])].sort();
+    if (linked.length === 0) {
+      positions[node.id] = sphere(index, other.length, 335 + (index % 7) * 5);
+      return;
+    }
+    const center = { x: 0, y: 0, z: 0 };
+    for (const id of linked) {
+      const point = positions[id]!;
+      center.x += point.x / linked.length;
+      center.y += point.y / linked.length;
+      center.z += point.z / linked.length;
+    }
+    const radius = node.kind === "code" ? 88 : node.kind === "test" ? 118 : 150;
+    const offset = sphere(index, other.length, radius + (index % 11) * 2);
+    positions[node.id] = {
+      x: center.x + offset.x,
+      y: center.y + offset.y,
+      z: center.z + offset.z,
+    };
+  });
+  return positions;
+}
+
+/** Rotate in world space, then project with a camera outside every bounded layout point. */
+export function projectFeaturePoint(
+  point: FeaturePoint3D,
+  camera: FeatureCamera3D,
+): { x: number; y: number; depth: number; scale: number } {
+  const cosYaw = Math.cos(camera.yaw);
+  const sinYaw = Math.sin(camera.yaw);
+  const x = point.x * cosYaw + point.z * sinYaw;
+  const z = point.z * cosYaw - point.x * sinYaw;
+  const cosPitch = Math.cos(camera.pitch);
+  const sinPitch = Math.sin(camera.pitch);
+  const y = point.y * cosPitch - z * sinPitch;
+  const depth = point.y * sinPitch + z * cosPitch;
+  const scale = 1000 / (1000 - depth);
+  return { x: 650 + x * scale, y: 410 + y * scale, depth, scale };
+}
+
+/** Sample a cubic thread in 3D before projection; rotation changes the whole thread. */
+export function createFeatureThread(
+  from: FeaturePoint3D,
+  to: FeaturePoint3D,
+  camera: FeatureCamera3D,
+  winding: number,
+  grouping = 0,
+): string {
+  const twist = Math.max(-1, Math.min(1, winding)) * 90;
+  const a = { x: from.x * 0.35 + twist, y: from.y * 0.35 - twist, z: from.z * 0.35 + twist };
+  const b = { x: to.x * 0.35 - twist, y: to.y * 0.35 + twist, z: to.z * 0.35 - twist };
+  const amount = Number.isFinite(grouping) ? Math.max(0, Math.min(1, grouping)) : 0;
+  if (amount > 0) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dz = to.z - from.z;
+    const length = Math.hypot(dx, dy, dz);
+    const bend = Math.max(-1, Math.min(1, winding)) * Math.min(24, length * 0.12);
+    const normal = Math.hypot(dx, dy) || 1;
+    const offset = { x: (-dy / normal) * bend, y: (dx / normal) * bend, z: bend * 0.35 };
+    const localA = {
+      x: from.x + dx / 3 + offset.x,
+      y: from.y + dy / 3 + offset.y,
+      z: from.z + dz / 3 + offset.z,
+    };
+    const localB = {
+      x: from.x + (dx * 2) / 3 + offset.x,
+      y: from.y + (dy * 2) / 3 + offset.y,
+      z: from.z + (dz * 2) / 3 + offset.z,
+    };
+    for (const coordinate of ["x", "y", "z"] as const) {
+      a[coordinate] += (localA[coordinate] - a[coordinate]) * amount;
+      b[coordinate] += (localB[coordinate] - b[coordinate]) * amount;
+    }
+  }
+  const parts: string[] = [];
+  for (let i = 0; i <= 18; i += 1) {
+    const t = i / 18;
+    const s = 1 - t;
+    const point = {
+      x: s ** 3 * from.x + 3 * s ** 2 * t * a.x + 3 * s * t ** 2 * b.x + t ** 3 * to.x,
+      y: s ** 3 * from.y + 3 * s ** 2 * t * a.y + 3 * s * t ** 2 * b.y + t ** 3 * to.y,
+      z: s ** 3 * from.z + 3 * s ** 2 * t * a.z + 3 * s * t ** 2 * b.z + t ** 3 * to.z,
+    };
+    const projected = projectFeaturePoint(point, camera);
+    parts.push(`${i === 0 ? "M" : "L"}${projected.x.toFixed(2)},${projected.y.toFixed(2)}`);
+  }
+  return parts.join(" ");
+}

package/src/commands/graph/feature-clusters.ts

@@ -0,0 +1,125 @@
+import type { FeaturePoint3D } from "./feature-3d.js";
+import type { FeatureMapEdgeV1, FeatureMapNodeV1 } from "./feature-model.js";
+
+export interface FeatureClusterGroup {
+  id: string;
+  kind: "feature" | "shared" | "unassigned";
+  featureId?: string;
+  center: FeaturePoint3D;
+  memberIds: string[];
+}
+
+export interface FeatureClusterLayout {
+  positions: Record<string, FeaturePoint3D>;
+  groups: FeatureClusterGroup[];
+  memberships: Record<string, string[]>;
+}
+
+/** Declared membership determines each island; spatial distance proves nothing beyond layout. */
+export function createFeatureClusterLayout(
+  nodes: readonly Pick<FeatureMapNodeV1, "id" | "kind">[],
+  edges: readonly Pick<FeatureMapEdgeV1, "from" | "to" | "kind">[],
+): FeatureClusterLayout {
+  const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  const ordered = [...nodes].sort((a, b) => compare(a.id, b.id));
+  const byId = new Map(ordered.map((node) => [node.id, node]));
+  const features = ordered.filter((node) => node.kind === "feature");
+  const featureIds = new Set(features.map((node) => node.id));
+  const linked = new Map(ordered.map((node) => [node.id, new Set<string>()]));
+  const relations: Record<FeatureMapNodeV1["kind"], readonly FeatureMapEdgeV1["kind"][]> = {
+    feature: [],
+    code: ["code", "test"],
+    test: ["code", "test"],
+    owner: ["ownership"],
+    intent: ["intent"],
+    unmapped: [],
+  };
+  for (const edge of edges) {
+    const fromFeature = featureIds.has(edge.from);
+    const toFeature = featureIds.has(edge.to);
+    if (fromFeature === toFeature) continue;
+    const member = byId.get(fromFeature ? edge.to : edge.from);
+    if (!member || !relations[member.kind].includes(edge.kind)) continue;
+    linked.get(member.id)!.add(fromFeature ? edge.from : edge.to);
+  }
+
+  const positions: Record<string, FeaturePoint3D> = Object.create(null) as Record<
+    string,
+    FeaturePoint3D
+  >;
+  const memberships: Record<string, string[]> = Object.create(null) as Record<string, string[]>;
+  const exclusive = new Map(features.map((feature) => [feature.id, [] as string[]]));
+  const shared: string[] = [];
+  const unassigned: string[] = [];
+  for (const node of ordered) {
+    const ids = node.kind === "feature" ? [node.id] : [...linked.get(node.id)!].sort(compare);
+    memberships[node.id] = ids;
+    if (node.kind === "feature") continue;
+    if (ids.length === 1) exclusive.get(ids[0]!)!.push(node.id);
+    else if (ids.length > 1) shared.push(node.id);
+    else unassigned.push(node.id);
+  }
+
+  const columns = Math.max(1, Math.ceil(Math.sqrt(features.length * 1.3)));
+  const rows = Math.ceil(features.length / columns);
+  const stepX = Math.min(140, 700 / Math.max(1, columns - 1));
+  const stepY = Math.min(110, 400 / Math.max(1, rows - 1));
+  const featureRadius = features.length === 1 ? 140 : Math.min(50, Math.min(stepX, stepY) * 0.4);
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+  const groups: FeatureClusterGroup[] = [];
+
+  function placeMembers(
+    ids: readonly string[],
+    center: FeaturePoint3D,
+    radius: number,
+    anchored: boolean,
+  ): void {
+    ids.forEach((id, index) => {
+      const fraction = Math.sqrt((index + 0.5) / ids.length);
+      const orbit = radius * ((anchored ? 0.62 : 0.12) + (anchored ? 0.38 : 0.88) * fraction);
+      const node = byId.get(id)!;
+      const depth =
+        node.kind === "test" ? 1 : node.kind === "owner" ? 0.5 : node.kind === "intent" ? -0.5 : -1;
+      positions[id] = {
+        x: center.x + Math.cos(index * goldenAngle) * orbit,
+        y: center.y + Math.sin(index * goldenAngle) * orbit,
+        z: center.z + radius * (depth * 0.2 + ((index % 7) - 3) * 0.035),
+      };
+    });
+  }
+
+  features.forEach((feature, index) => {
+    const row = Math.floor(index / columns);
+    const rowSize = Math.min(columns, features.length - row * columns);
+    const center = {
+      x: ((index % columns) - (rowSize - 1) / 2) * stepX,
+      y: -45 + (row - (rows - 1) / 2) * stepY,
+      z: ((index % 3) - 1) * 12,
+    };
+    const members = exclusive.get(feature.id)!;
+    positions[feature.id] = { ...center };
+    placeMembers(members, center, featureRadius, true);
+    groups.push({
+      id: `feature:${feature.id}`,
+      kind: "feature",
+      featureId: feature.id,
+      center,
+      memberIds: [feature.id, ...members],
+    });
+  });
+
+  function addContextGroup(
+    kind: "shared" | "unassigned",
+    ids: string[],
+    x: number,
+    z: number,
+  ): void {
+    if (ids.length === 0) return;
+    const center = features.length === 0 ? { x: 0, y: 0, z: 0 } : { x, y: 285, z };
+    placeMembers(ids, center, features.length === 0 ? 190 : 70, false);
+    groups.push({ id: kind, kind, center, memberIds: [...ids] });
+  }
+  addContextGroup("shared", shared, -175, 35);
+  addContextGroup("unassigned", unassigned, 175, -35);
+  return { positions, groups, memberships };
+}