tecton 0.4.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "tecton",
+  "version": "0.4.0",
+  "description": "Tecton: see every shift in your architecture before it becomes a crack. Architecture diagrams, before/after diffs and boundary rules for JS/TS codebases.",
+  "homepage": "https://github.com/gaurav2180/tecton#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gaurav2180/tecton.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gaurav2180/tecton/issues"
+  },
+  "author": "gaurav2180",
+  "type": "module",
+  "bin": {
+    "tecton": "bin/tecton.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/report/client",
+    "brand/tecton-favicon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "dev": "node scripts/build.js --watch",
+    "check:bundle": "node scripts/build.js --check",
+    "typecheck": "tsc -p tsconfig.json && tsc -p src/report/client/tsconfig.json",
+    "test": "node test/run.js",
+    "test:ui": "playwright test",
+    "check": "npm run check:bundle && npm run typecheck && npm test && npm run test:ui",
+    "prepublishOnly": "npm run check:bundle && npm run typecheck && npm test"
+  },
+  "keywords": [
+    "architecture",
+    "dependency-graph",
+    "dependencies",
+    "diagram",
+    "boundaries",
+    "lint",
+    "monorepo",
+    "typescript",
+    "javascript",
+    "ci",
+    "pull-request",
+    "github-action"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.3",
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/diff.js

@@ -0,0 +1,93 @@
+// Comparing two snapshots: what appeared, what disappeared, which rule breaks are new.
+import { nameMatches } from './graph.js';
+import { packagesNamedInRules } from './rules.js';
+
+/** @returns {import('./types.js').Status} */
+const status = (inBase, inCur) => (inBase && inCur ? 'same' : inCur ? 'added' : 'removed');
+
+/**
+ * @param {import('./types.js').Graph} base
+ * @param {import('./types.js').Graph} cur
+ * @param {import('./types.js').Violation[]} baseViol
+ * @param {import('./types.js').Violation[]} curViol
+ * @param {import('./types.js').Config} cfg
+ * @returns {{ nodes: import('./types.js').MapNode[], edges: import('./types.js').MapEdge[], violations: import('./types.js').Violation[], summary: import('./types.js').Summary }}
+ */
+export function diffGraphs(base, cur, baseViol, curViol, cfg) {
+  const showPkg = (name) => cfg.externals === true
+    || packagesNamedInRules(cfg).some((p) => nameMatches(p, name));
+
+  // ---- dependencies (arrows) ----
+  const edges = [];
+  const keys = new Set([...base.edges.keys(), ...cur.edges.keys()]);
+  for (const key of keys) {
+    const b = base.edges.get(key);
+    const c = cur.edges.get(key);
+    const e = c || b;
+    if (e.external && !showPkg(e.to)) continue;
+    const st = status(!!b, !!c);
+    edges.push({
+      id: key, from: e.from, to: e.to, external: e.external, status: st,
+      countBase: b ? b.count : 0, countCur: c ? c.count : 0,
+      imports: (c || b).imports,
+      addedImports: st === 'same' ? newEvidence(b.imports, c.imports) : [],
+    });
+  }
+
+  // ---- modules (boxes) ----
+  const nodes = [];
+  const names = new Set([...base.modules.keys(), ...cur.modules.keys()]);
+  for (const e of edges) { if (e.external) { names.add(e.from); names.add(e.to); } }
+  for (const name of names) {
+    const external = name.startsWith('npm:');
+    const b = base.modules.get(name);
+    const c = cur.modules.get(name);
+    let inBase = !!b; let inCur = !!c;
+    if (external) {
+      inBase = edges.some((e) => e.to === name && e.status !== 'added');
+      inCur = edges.some((e) => e.to === name && e.status !== 'removed');
+    }
+    const bf = new Set(b ? b.files : []);
+    const cf = new Set(c ? c.files : []);
+    nodes.push({
+      id: name, external, status: status(inBase, inCur),
+      filesBase: bf.size, filesCur: cf.size,
+      files: [...new Set([...bf, ...cf])].sort().map((f) => ({ path: f, status: status(bf.has(f), cf.has(f)) })),
+    });
+  }
+
+  // ---- rule breaks ----
+  const baseIds = new Set(baseViol.map((v) => v.id));
+  const curIds = new Set(curViol.map((v) => v.id));
+  /** @type {import('./types.js').Violation[]} */
+  const violations = [
+    ...curViol.map((v) => ({ ...v, status: baseIds.has(v.id) ? /** @type {const} */ ('existing') : /** @type {const} */ ('new') })),
+    ...baseViol.filter((v) => !curIds.has(v.id)).map((v) => ({ ...v, status: /** @type {const} */ ('fixed') })),
+  ];
+  const order = { new: 0, existing: 1, fixed: 2 };
+  violations.sort((a, b) => order[a.status] - order[b.status] || (a.severity === 'error' ? -1 : 1) - (b.severity === 'error' ? -1 : 1));
+
+  const count = (arr, st) => arr.filter((x) => x.status === st).length;
+  const summary = {
+    modules: { added: count(nodes.filter((n) => !n.external), 'added'), removed: count(nodes.filter((n) => !n.external), 'removed'), total: cur.modules.size },
+    deps: {
+      added: count(edges, 'added'), removed: count(edges, 'removed'),
+      changed: edges.filter((e) => e.status === 'same' && e.countBase !== e.countCur).length,
+      total: edges.filter((e) => e.status !== 'removed').length,
+    },
+    violations: {
+      newErrors: violations.filter((v) => v.status === 'new' && v.severity === 'error').length,
+      newWarnings: violations.filter((v) => v.status === 'new' && v.severity !== 'error').length,
+      existing: count(violations, 'existing'),
+      fixed: count(violations, 'fixed'),
+    },
+    files: { base: base.stats.files, cur: cur.stats.files },
+  };
+  return { nodes, edges, violations, summary };
+}
+
+function newEvidence(before, after) {
+  const k = (x) => `${x.file}>${x.target}`;
+  const seen = new Set(before.map(k));
+  return after.filter((x) => !seen.has(k(x)));
+}

package/src/graph.js

@@ -0,0 +1,130 @@
+// Turning files + imports into a module-level map ("which part of the app uses which").
+import path from 'node:path';
+import { extractImports, loadAliases, makeResolver, codeOf } from './scan.js';
+
+const MAX_EVIDENCE = 60;
+
+export function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      if (glob[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } else { re += '.*'; i += 1; }
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** Match a module name against a rule pattern. `*` matches anything (including "/"). */
+export function nameMatches(pattern, name) {
+  if (pattern === name) return true;
+  if (!pattern.includes('*')) return false;
+  const re = new RegExp(`^${pattern.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+  return re.test(name);
+}
+
+const WORKSPACE_DIRS = /^(apps|packages|libs|services|modules|projects|workspaces|sites|tools|plugins)$/;
+
+const DEFAULT_EXCLUDE = ['**/*.test.*', '**/*.spec.*', '**/__tests__/**', '**/__mocks__/**',
+  '**/*.stories.*', '**/*.config.*'];
+
+/** Decide which module each file belongs to. */
+export function makeGrouper(cfg, files) {
+  const hasSrc = files.some((f) => f.startsWith('src/'));
+  const root = (cfg.root ?? (hasSrc ? 'src' : '')).replace(/^\.\/?/, '').replace(/\/$/, '');
+  const depth = cfg.depth ?? 1;
+  // zero config in a monorepo: apps/web and packages/ui are the parts, not "apps" and "packages"
+  const depthFor = (dirs) => (cfg.depth == null && !root && WORKSPACE_DIRS.test(dirs[0]) && dirs.length > 1 ? 2 : depth);
+  const exclude = [...DEFAULT_EXCLUDE, ...(cfg.exclude || [])].map(globToRegex);
+
+  const explicit = [];
+  const mods = cfg.modules || {};
+  for (const [name, pats] of Object.entries(mods)) {
+    for (const p of [].concat(pats)) {
+      if (/[*?]/.test(p)) { explicit.push({ name, re: globToRegex(p) }); continue; }
+      // a plain path means that exact file, or everything inside that folder
+      const clean = p.replace(/^\.\//, '').replace(/\/$/, '');
+      explicit.push({ name, re: globToRegex(clean) }, { name, re: globToRegex(`${clean}/**`) });
+    }
+  }
+
+  return {
+    root,
+    moduleOf(file) {
+      if (exclude.some((re) => re.test(file))) return null;
+      for (const m of explicit) if (m.re.test(file)) return m.name;
+      if (cfg.modules && cfg.onlyListedModules) return null;
+      let rel = file;
+      if (root) {
+        if (!file.startsWith(`${root}/`)) return null; // e.g. top-level config files
+        rel = file.slice(root.length + 1);
+      }
+      const dirs = path.posix.dirname(rel).split('/').filter((s) => s && s !== '.');
+      return dirs.length ? dirs.slice(0, depthFor(dirs)).join('/') : '(root)';
+    },
+  };
+}
+
+/**
+ * Build the module graph for one snapshot of the code.
+ * Returns { modules: Map<name,{files}>, edges: Map<key,{from,to,external,imports}>, stats }.
+ */
+/**
+ * @param {import('./types.js').Source} source
+ * @param {import('./types.js').Config} cfg
+ * @returns {import('./types.js').Graph}
+ */
+export function buildGraph(source, cfg) {
+  const fileSet = new Set(source.files);
+  const resolve = makeResolver(fileSet, loadAliases(source, cfg.aliases));
+  const grouper = makeGrouper(cfg, source.files);
+
+  const modules = new Map();
+  const edges = new Map();
+  const stats = { files: 0, imports: 0, unresolved: 0 };
+  const moduleOf = new Map();
+  const fileDeps = new Map(); // file -> Map<target file, first line>, for the per-file drill-down
+
+  for (const f of source.files) {
+    const m = grouper.moduleOf(f);
+    if (!m) continue;
+    moduleOf.set(f, m);
+    if (!modules.has(m)) modules.set(m, { files: [] });
+    modules.get(m).files.push(f);
+  }
+
+  for (const [file, from] of moduleOf) {
+    const text = codeOf(file, source.read(file));
+    if (text == null) continue;
+    stats.files++;
+    const deps = new Map();
+    fileDeps.set(file, deps);
+    for (const { spec, line } of extractImports(text)) {
+      const r = resolve(file, spec);
+      let to;
+      let target;
+      if (r.kind === 'file') {
+        to = moduleOf.get(r.file);
+        target = r.file;
+        if (!to) continue; // imports something outside the analysed area (tests, configs)
+        if (r.file !== file && !deps.has(r.file)) deps.set(r.file, line);
+      } else if (r.kind === 'package') {
+        to = `npm:${r.pkg}`;
+        target = r.pkg;
+      } else {
+        if (r.kind === 'unresolved') stats.unresolved++;
+        continue;
+      }
+      stats.imports++;
+      if (to === from) continue;
+      const key = `${from}→${to}`;
+      if (!edges.has(key)) edges.set(key, { from, to, external: to.startsWith('npm:'), imports: [], count: 0 });
+      const e = edges.get(key);
+      e.count++;
+      if (e.imports.length < MAX_EVIDENCE) e.imports.push({ file, line, spec, target });
+    }
+  }
+  return { modules, edges, stats, root: grouper.root, moduleOf, fileDeps };
+}

package/src/layout.js

@@ -0,0 +1,191 @@
+// A small, deterministic layered layout (Sugiyama-style), computed on base ∪ current so that
+// switching between the Base / Current / Diff views never moves anything.
+
+const NODE_H = 46;
+const ROW_GAP = 86;
+const COL_GAP = 36;
+const DUMMY_W = 14;
+
+export function nodeWidth(label) {
+  // icon (34px) + text (~7.3px per char at 13px Geist semibold) + right padding
+  return Math.max(120, Math.round(label.length * 7.3) + 56);
+}
+
+export function layout(nodes, edges) {
+  const ids = nodes.map((n) => n.id).sort();
+  const metaLen = (n) => (n.external ? 11 : (n.filesBase !== n.filesCur ? `${n.filesBase} → ${n.filesCur} files` : `${n.filesCur || n.filesBase || 0} files`).length);
+  // box must fit the name (13px sans) and the file-count line (10.5px mono, ~6.4px per char)
+  const width = new Map(nodes.map((n) => [n.id, Math.max(nodeWidth((n.label || n.id).replace(/^npm:/, '')), n.filesCur === undefined ? 0 : Math.round(36 + metaLen(n) * 6.4 + 16))]));
+
+  // 1. Break loops: walk the graph depth-first; any arrow pointing back up the walk is flipped for layout.
+  const succ = new Map(ids.map((i) => [i, []]));
+  for (const e of edges) succ.get(e.from).push(e);
+  for (const list of succ.values()) list.sort((a, b) => (a.to < b.to ? -1 : 1));
+  const state = new Map();
+  const flipped = new Set();
+  const dfs = (v) => {
+    state.set(v, 1);
+    for (const e of succ.get(v)) {
+      const s = state.get(e.to);
+      if (s === 1) flipped.add(e.id);
+      else if (!s) dfs(e.to);
+    }
+    state.set(v, 2);
+  };
+  for (const v of ids) if (!state.get(v)) dfs(v);
+  const dag = edges.map((e) => (flipped.has(e.id) ? { id: e.id, u: e.to, v: e.from } : { id: e.id, u: e.from, v: e.to }));
+
+  // 2. Rows: users on top, things being used underneath (longest path).
+  const preds = new Map(ids.map((i) => [i, []]));
+  const outs = new Map(ids.map((i) => [i, []]));
+  for (const d of dag) { preds.get(d.v).push(d.u); outs.get(d.u).push(d.v); }
+  const indeg = new Map(ids.map((i) => [i, preds.get(i).length]));
+  const topo = [];
+  const queue = ids.filter((i) => indeg.get(i) === 0);
+  while (queue.length) {
+    queue.sort();
+    const v = queue.shift();
+    topo.push(v);
+    for (const w of outs.get(v)) { indeg.set(w, indeg.get(w) - 1); if (indeg.get(w) === 0) queue.push(w); }
+  }
+  const layer = new Map();
+  for (const v of topo) layer.set(v, Math.max(0, ...preds.get(v).map((u) => layer.get(u) + 1)));
+  // pull pure "users" down next to what they use, so arrows stay short
+  for (const v of [...topo].reverse()) {
+    if (preds.get(v).length === 0 && outs.get(v).length) layer.set(v, Math.min(...outs.get(v).map((w) => layer.get(w))) - 1);
+  }
+  const minL = Math.min(0, ...layer.values());
+  for (const v of ids) layer.set(v, layer.get(v) - minL);
+
+  // 3. Long arrows get invisible waypoints on each row they cross.
+  const allLayer = new Map(layer);
+  const chains = new Map(); // edge id -> [u, dummies..., v]
+  const segs = [];
+  for (const d of dag) {
+    const chain = [d.u];
+    for (let l = layer.get(d.u) + 1; l < layer.get(d.v); l++) {
+      const dummy = `\u0000${d.id}#${l}`;
+      allLayer.set(dummy, l);
+      width.set(dummy, DUMMY_W);
+      chain.push(dummy);
+    }
+    chain.push(d.v);
+    chains.set(d.id, chain);
+    for (let i = 0; i + 1 < chain.length; i++) segs.push([chain[i], chain[i + 1]]);
+  }
+  const up = new Map([...allLayer.keys()].map((k) => [k, []]));
+  const down = new Map([...allLayer.keys()].map((k) => [k, []]));
+  for (const [a, b] of segs) { down.get(a).push(b); up.get(b).push(a); }
+
+  // 4. Order within each row to reduce crossings (barycenter sweeps, keep the best).
+  const nLayers = Math.max(0, ...allLayer.values()) + 1;
+  let rows = Array.from({ length: nLayers }, () => []);
+  // initial order: breadth-first from the top, alphabetical tie-break
+  const placed = new Set();
+  const bfs = [...allLayer.keys()].filter((k) => up.get(k).length === 0).sort();
+  while (bfs.length) {
+    const v = bfs.shift();
+    if (placed.has(v)) continue;
+    placed.add(v);
+    rows[allLayer.get(v)].push(v);
+    for (const w of [...down.get(v)].sort()) if (!placed.has(w)) bfs.push(w);
+  }
+  for (const k of [...allLayer.keys()].sort()) if (!placed.has(k)) rows[allLayer.get(k)].push(k);
+
+  const crossings = (rs) => {
+    let total = 0;
+    for (let l = 0; l + 1 < rs.length; l++) {
+      const pos = new Map(rs[l + 1].map((v, i) => [v, i]));
+      const list = [];
+      rs[l].forEach((v, i) => down.get(v).forEach((w) => list.push([i, pos.get(w)])));
+      for (let a = 0; a < list.length; a++) {
+        for (let b = a + 1; b < list.length; b++) {
+          if ((list[a][0] - list[b][0]) * (list[a][1] - list[b][1]) < 0) total++;
+        }
+      }
+    }
+    return total;
+  };
+  const reorder = (rs, l, neighbours, ref) => {
+    const pos = new Map(rs[ref].map((v, i) => [v, i]));
+    const bc = new Map(rs[l].map((v, i) => {
+      const ns = neighbours.get(v).filter((w) => pos.has(w));
+      return [v, ns.length ? ns.reduce((s, w) => s + pos.get(w), 0) / ns.length : i];
+    }));
+    rs[l] = [...rs[l]].sort((a, b) => bc.get(a) - bc.get(b) || rs[l].indexOf(a) - rs[l].indexOf(b));
+  };
+  let best = rows.map((r) => [...r]);
+  let bestC = crossings(best);
+  for (let iter = 0; iter < 16 && bestC > 0; iter++) {
+    if (iter % 2 === 0) for (let l = 1; l < nLayers; l++) reorder(rows, l, up, l - 1);
+    else for (let l = nLayers - 2; l >= 0; l--) reorder(rows, l, down, l + 1);
+    const c = crossings(rows);
+    if (c < bestC) { bestC = c; best = rows.map((r) => [...r]); }
+  }
+  rows = best;
+
+  // 5. Horizontal positions: start packed, then nudge each box toward its neighbours.
+  const x = new Map();
+  for (const row of rows) {
+    let cur = 0;
+    for (const v of row) { x.set(v, cur + width.get(v) / 2); cur += width.get(v) + COL_GAP; }
+    const shift = (cur - COL_GAP) / 2;
+    for (const v of row) x.set(v, x.get(v) - shift);
+  }
+  const settle = (row, want) => {
+    const gap = (a, b) => (width.get(a) + width.get(b)) / 2 + (a.startsWith('\u0000') || b.startsWith('\u0000') ? 10 : COL_GAP);
+    const L = row.map((v) => want.get(v));
+    for (let i = 1; i < row.length; i++) L[i] = Math.max(L[i], L[i - 1] + gap(row[i - 1], row[i]));
+    const R = row.map((v) => want.get(v));
+    for (let i = row.length - 2; i >= 0; i--) R[i] = Math.min(R[i], R[i + 1] - gap(row[i], row[i + 1]));
+    row.forEach((v, i) => x.set(v, (L[i] + R[i]) / 2));
+    // averaging can re-introduce overlaps; one last left-to-right pass fixes them
+    for (let i = 1; i < row.length; i++) {
+      const min = x.get(row[i - 1]) + gap(row[i - 1], row[i]);
+      if (x.get(row[i]) < min) x.set(row[i], min);
+    }
+  };
+  for (let iter = 0; iter < 10; iter++) {
+    const order = iter % 2 === 0 ? rows.map((_, i) => i) : rows.map((_, i) => rows.length - 1 - i);
+    for (const l of order) {
+      const nb = iter % 2 === 0 ? up : down;
+      const want = new Map(rows[l].map((v) => {
+        const ns = [...nb.get(v), ...(iter > 5 ? (nb === up ? down : up).get(v) : [])];
+        return [v, ns.length ? ns.reduce((s, w) => s + x.get(w), 0) / ns.length : x.get(v)];
+      }));
+      settle(rows[l], want);
+    }
+  }
+
+  // 6. Coordinates and arrow waypoints.
+  const y = (l) => l * (NODE_H + ROW_GAP);
+  const minX = Math.min(...[...x.entries()].map(([v, cx]) => cx - width.get(v) / 2), 0);
+  const pos = {};
+  for (const id of ids) {
+    const w = width.get(id);
+    pos[id] = { x: x.get(id) - w / 2 - minX, y: y(layer.get(id)), w, h: NODE_H };
+  }
+  const pairs = new Set(edges.map((e) => `${e.from}→${e.to}`));
+  const routes = {};
+  for (const e of edges) {
+    let chain = chains.get(e.id);
+    const pts = chain.map((v, i) => {
+      const cx = x.get(v) - minX;
+      const cy = y(allLayer.get(v));
+      if (i === 0) return [cx, cy + NODE_H];
+      if (i === chain.length - 1) return [cx, cy];
+      return [cx, cy + NODE_H / 2];
+    });
+    if (flipped.has(e.id)) pts.reverse();
+    // two-way dependency between the same pair: offset so both arrows are visible
+    if (pairs.has(`${e.to}→${e.from}`)) {
+      const off = e.from < e.to ? -7 : 7;
+      pts.forEach((p) => { p[0] += off; });
+    }
+    routes[e.id] = pts.map(([a, b]) => [Math.round(a * 10) / 10, Math.round(b * 10) / 10]);
+    chain = null;
+  }
+  const W = Math.max(0, ...Object.values(pos).map((p) => p.x + p.w));
+  const H = Math.max(0, ...Object.values(pos).map((p) => p.y + p.h));
+  return { pos, routes, width: W, height: H, crossings: bestC };
+}