tecton 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gaurav2180
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+<p align="center"><img src="brand/tecton-banner.png" alt="Tecton: see every shift in your architecture before it becomes a crack" width="720"></p>
+
+# Tecton
+
+**See every shift in your architecture before it becomes a crack.**
+
+Tecton draws your project as a map of **modules** (folders) and the **dependencies** between them,
+compares it with a git branch, and checks **house rules** such as "components must not talk to the
+database directly". You get an interactive HTML page, an optional Markdown summary for pull requests,
+and a non-zero exit code when a change breaks a rule.
+
+- No dependencies. Needs Node 18+ and git.
+- Understands `import`, `export … from`, `require()`, `import()`, `tsconfig`/`jsconfig` path aliases
+  (like `@/components/...`), `index` files, `./file.js` → `file.ts`, and the `<script>` blocks of Vue and Svelte files.
+- Compares against the point where your branch split off, so work merged to `main` meanwhile
+  doesn't show up as your change.
+
+## Quick start
+
+```bash
+cd your-project
+npx tecton
+```
+
+That's it: no install, no config. Tecton maps your code, compares it with `main` (or `master`) and opens the report in your browser.
+The report goes to a temp folder, so nothing is added to your project. It works in a single app, in a monorepo (`apps/*` and `packages/*` become the parts), and without git (as a snapshot).
+
+When you want more:
+
+```bash
+npx tecton serve         # the same report, refreshed in your browser every time you save
+npx tecton init          # add tecton.config.json with your modules and a first rule, so CI can enforce it
+```
+
+In CI, or when output is piped, it writes `./tecton-report.html` and opens nothing (or pass `--out`). Use `--no-open` or `BROWSER=none` to skip the browser anywhere.
+
+## The report
+
+One self-contained HTML file (fonts included, works offline) laid out like a small SaaS app:
+
+- **Overview**: pass/fail status, counters, a breakdown of dependency changes, rule checks, a live map preview and files per module.
+- **Architecture**: a C4 container diagram read from your code. Users sit on top, your repo is a dashed system boundary holding its apps, databases (cylinders) and queues (pipes), and outside systems sit on the right. Every connector is labelled (`HTTP · API_URL`, `reads & writes · SQL`, `adds jobs`), queue traffic is dotted, and connectors from one app travel as a bundle. Pan, zoom, hover an app to trace its connections, and export as SVG. What it finds:
+  - **Apps**: every `package.json` (Next.js, Nuxt, SvelteKit, Express, Fastify, NestJS, Hono, Koa, …).
+  - **Entry points**:
+    - pages and API routes: Next.js app/pages router, Nuxt `pages/` and `server/api/`, SvelteKit `+page.svelte` / `+server.ts`
+    - HTTP endpoints, with their full path: Express/Koa/Hono routers mounted with `app.use('/api', router)`, even across files; Fastify `register(plugin, { prefix })` and `route({ method, url })`; Hono `basePath`/`route`; NestJS `@Controller` + `@Get` with `setGlobalPrefix`
+    - npm-script jobs
+    - **cron schedules** in plain words ("every day at 03:00"), from `node-cron`, `cron`, `node-schedule`, BullMQ repeatable jobs, NestJS `@Cron` and `vercel.json`
+  - **Data and queues**: SQLite, Postgres, MySQL, Mongo, Redis, Prisma, Drizzle, S3, …, plus **queues** (BullMQ, Bull and Bee-Queue by queue name; SQS, RabbitMQ, Kafka, Pub/Sub, Service Bus, QStash, Inngest, …). Connection strings in `.env.example` name the real engine (`DATABASE_URL=postgres://…` next to Prisma shows "PostgreSQL via Prisma").
+  - **Outside services**: hosts in URLs, SDKs such as Stripe, OpenAI and nodemailer, URLs in `.env.example`, and services that are only named by an env var (`FRAUD_CHECK_URL=` becomes "Fraud Check").
+  - App-to-app calls are found through env vars like `BACKEND_URL`. New or removed pieces are highlighted, and clicking anything shows every entry point and the exact lines behind it.
+- **Dependency map**: switch between **Changes / Before / After**. Boxes never move between views, so you can flip back and forth.
+  Green = new dependency, red dashed = removed, orange = breaks a rule. Numbers on arrows are how many imports.
+  - **Only changes** shows just the dependencies that moved.
+  - **Only touched** shows the modules whose files this change edits (marked with an indigo dot) and what they connect to: the PR at a glance.
+  - Click a box or arrow for its files and the exact `file:line` imports. Double-click a box to open its files.
+  - Also includes a minimap, zoom (scroll or pinch) and SVG export.
+- **Module pages**: open any module (from the Modules table, the map, or ⌘K) to see its **files and how they connect**. Its neighbouring modules appear as rounded boxes, and imports that break a rule are orange.
+  Click a file for everything it imports and everything that imports it, with line numbers. Toggle **Only changed files** to focus on the diff.
+- **Rule checks**: every rule with its status. Expand one to see each break and where it happens.
+- **Changes** and **Modules**: tables you can filter, search and sort. Modules can be narrowed to the ones this change touches.
+- **⌘K / Ctrl K** (or `/`): a command palette to jump to any module, file, dependency, rule, entry point or action.
+  Keys `1`–`6` switch pages, `F` fits the map, `Esc` closes things.
+- Light, dark and system themes. **Copy PR summary** puts the Markdown summary on your clipboard.
+
+The Geist fonts are embedded under the SIL Open Font License (`src/report/fonts/OFL-LICENSE.txt`).
+
+## Watch mode
+
+`tecton serve [dir]` starts a local server (default `http://127.0.0.1:4321`, or `--port`) and rebuilds the
+report whenever a source file, `package.json`, `tsconfig.json`, `tecton.config.json` or `.env.example` changes, and when you commit or switch branches.
+The open page reloads itself and keeps the page you were on. If something can't be read (a broken config, say), the last good report stays up and a small status pill shows the error.
+
+## Config (`tecton.config.json`)
+
+Projects set up with the old name keep working: `archdiff.config.json` is read if there's no `tecton.config.json`.
+
+```jsonc
+{
+  "root": "src",          // folder to analyse (default: "src" if it exists, else the project folder)
+  "depth": 1,             // 1 = src/components, src/lib...; 2 = src/features/cart, src/features/auth...
+  "cycles": "warn",       // flag modules that depend on each other in a loop: "warn" | "error" | "off"
+  "rules": [
+    // forbidden: "from" may not use anything in "to"
+    { "name": "UI must not touch the database", "from": "components", "to": ["db", "npm:pg"],
+      "message": "Call a service instead." },
+    // allow-list: "from" may only use these internal modules
+    { "name": "lib stays dependency-free", "from": "lib", "allow": [] },
+    // wildcards work, and "severity": "warn" reports without failing CI
+    { "name": "features stay independent", "from": "features/*", "to": ["features/*"], "severity": "warn" }
+  ],
+
+  // optional
+  "modules": { "ui": ["src/components", "src/app/**/_components/**"] }, // group folders by hand (first match wins)
+  "exclude": ["src/generated/**"],     // tests, stories and *.config.* files are skipped already
+  "aliases": { "~/": "src/" },         // extra import aliases beyond tsconfig "paths"
+  "externals": false,                  // true = draw every npm package; otherwise only ones named in rules
+  "base": "develop"                    // default branch to compare with
+}
+```
+
+Module names are folder paths under `root` (`components`, `features/cart`). npm packages are `npm:<name>`.
+A module can import itself freely; rules are about arrows between modules.
+
+## Command line
+
+```
+tecton [dir] [--base <ref>] [--head <ref>] [--out report.html] [--md summary.md] [--json data.json]
+             [--config file] [--no-merge-base] [--strict] [--no-open]
+tecton serve [dir] [--port 4321] [--base <ref>] [--no-open]
+tecton init [dir]
+tecton --version
+```
+
+Exit code: `1` if the change adds a rule break with severity `error` (`--strict`: any rule break), `2` for usage errors.
+Without git (or without a base branch) it shows a snapshot and fails on any rule break.
+
+## In CI
+
+### GitHub Action
+
+```yaml
+# .github/workflows/tecton.yml
+on: pull_request
+permissions: { contents: read, pull-requests: write }
+jobs:
+  architecture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - uses: gaurav2180/tecton@v0.4.0
+```
+
+The action compares the pull request with its base branch and does four things:
+
+1. Writes the Markdown summary (with a Mermaid diagram of only the parts that changed) to the job summary.
+2. Posts it as a PR comment and updates that comment on every push, so the PR doesn't collect a new comment each time.
+3. Uploads the HTML report as an artifact and links it from the comment.
+4. Fails the check if the change adds a rule break.
+
+Inputs: `working-directory`, `base`, `config`, `strict`, `comment`, `fail-on-break`, `upload-report`, `report-name`, `github-token`.
+Outputs: `new-breaks`, `failing`, `report-path`, `summary-path`. See [`action.yml`](action.yml) and [`examples/github-workflow.yml`](examples/github-workflow.yml).
+
+### Any other CI
+
+```bash
+npx tecton --base "origin/$BASE_BRANCH" --head HEAD --out tecton-report.html --md tecton.md
+```
+
+## Development
+
+The CLI is plain JavaScript on Node built-ins. The report's browser code lives in `src/report/client/` as ES modules, is typed with JSDoc against `src/types.d.ts`, and is bundled with esbuild into `src/report/dist/client.js`. That bundle is committed, so the CLI and the GitHub Action run straight from a checkout.
+
+```bash
+npm install            # dev tools only: esbuild, TypeScript, Playwright
+npm run dev            # rebuild the client bundle on change (use with: node bin/tecton.js serve <project>)
+npm run build          # build the bundle once; commit src/report/dist/client.js with your change
+npm run typecheck      # tsc over the CLI and the browser code
+npm test               # unit tests (no dependencies needed)
+npm run test:ui        # the report in a real browser: every page, light and dark, desktop and phone
+npm run check          # everything CI runs
+```
+
+The UI tests compare screenshots against baselines in `test/ui/__screenshots__/<platform>/`. After a deliberate visual change, run `npm run test:ui -- --update-snapshots` and review the new images before committing them.
+
+## Brand
+
+The logo files are in [`brand/`](brand/): the mark, lockups for light and dark, app icons, a favicon and a social banner. See `CLAUDE.md` for how to use them.
+
+## Limits (v0.4)
+
+- JS/TS, plus the `<script>` blocks of Vue and Svelte files. Imports inside templates aren't read.
+- Imports and routes are found with a careful text scan, not a full parser, so exotic code can occasionally be missed.
+  Router prefixes are followed through imports, `require()` and local variables, but not through routers built dynamically (for example in a loop).
+- The architecture view is heuristic. Queue names and cron expressions must be written as literals (or a constant in the same file). URLs built at run time from config show up only if they are named in `.env.example`.
+- Module diagrams are drawn for modules with up to 250 files. Bigger modules get the file table only.

package/bin/tecton.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+// Tecton — draw a JS/TS codebase as a map of modules, compare it with a git branch, and check house rules.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { workingTreeSource, gitRefSource, gitInfo, refExists, git, parseJsonc, isCode, isExtra } from '../src/scan.js';
+import { buildGraph, makeGrouper } from '../src/graph.js';
+import { evaluate } from '../src/rules.js';
+import { diffGraphs } from '../src/diff.js';
+import { layout } from '../src/layout.js';
+import { detectSystem, diffSystems } from '../src/system.js';
+import { toHtml, toMarkdown } from '../src/report.js';
+
+/** @typedef {import('../src/types.js').Graph} Graph @typedef {import('../src/types.js').Source} Source @typedef {import('../src/types.js').FileGraph} FileGraph */
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+const HELP = `Tecton — see every shift in your architecture before it becomes a crack
+
+Usage
+  tecton [dir] [options]      map the code, compare it with main, check rules and open the report
+  tecton serve [dir]          open the report in your browser and refresh it whenever a file changes
+  tecton init [dir]           create tecton.config.json with your modules and an example rule
+
+Options
+  --base <ref>        what to compare against (default: main, then master)
+  --head <ref>        compare a commit instead of the files on disk (e.g. HEAD in CI)
+  --no-merge-base     compare with the tip of --base instead of where your branch split off
+  --out <file>        write the HTML report here (default: a temp file that opens in your browser;
+                      ./tecton-report.html in CI or when output is not a terminal)
+  --md <file>         also write a Markdown summary with a Mermaid diagram (for PR comments)
+  --json <file>       also write the raw data as JSON
+  --config <file>     config path (default: <dir>/tecton.config.json)
+  --no-open           don't open the report in the browser
+  --strict            fail on any rule break, not only new ones
+  --port <n>          serve: port to listen on (default: 4321)
+  -v, --version       print the version
+  -h, --help          show this help
+
+Exit code is 1 when the change introduces a new rule break (severity "error"), so it can gate CI.
+`;
+
+const tty = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = c(1); const dim = c(2); const red = c(31); const green = c(32); const yellow = c(33); const cyan = c(36);
+
+class UsageError extends Error {}
+const fail = (msg) => { throw new UsageError(msg); };
+
+function parseArgs(argv) {
+  const o = { _: [], mergeBase: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const val = () => { const v = argv[++i]; if (v === undefined) fail(`${a} needs a value`); return v; };
+    if (a === '-h' || a === '--help') o.help = true;
+    else if (a === '-v' || a === '--version') o.version = true;
+    else if (a === '--base') o.base = val();
+    else if (a === '--head') o.head = val();
+    else if (a === '--out') o.out = val();
+    else if (a === '--md') o.md = val();
+    else if (a === '--json') o.json = val();
+    else if (a === '--config') o.config = val();
+    else if (a === '--port') { o.port = Number(val()); if (!Number.isInteger(o.port) || o.port < 0 || o.port > 65535) fail('--port needs a number'); }
+    else if (a === '--open') o.open = true;
+    else if (a === '--no-open') o.open = false;
+    else if (a === '--strict') o.strict = true;
+    else if (a === '--no-merge-base') o.mergeBase = false;
+    else if (a.startsWith('-')) fail(`unknown option ${a}`);
+    else o._.push(a);
+  }
+  return o;
+}
+
+function loadConfig(dir, file) {
+  let p = file ? path.resolve(file) : path.join(dir, 'tecton.config.json');
+  // projects set up before the rename keep working
+  if (!file && !fs.existsSync(p) && fs.existsSync(path.join(dir, 'archdiff.config.json'))) p = path.join(dir, 'archdiff.config.json');
+  if (!fs.existsSync(p)) { if (file) fail(`config not found: ${p}`); return { cfg: {}, path: null }; }
+  try { return { cfg: parseJsonc(fs.readFileSync(p, 'utf8')), path: p }; } catch (e) { return fail(`could not read ${p}: ${e.message}`); }
+}
+
+function pickBase(dir, opts, cfg) {
+  if (!gitInfo(dir)) return null;
+  const candidates = opts.base ? [opts.base] : cfg.base ? [cfg.base] : ['main', 'master', 'origin/main', 'origin/master'];
+  const ref = candidates.find((r) => refExists(dir, r));
+  if (!ref) { if (opts.base) fail(`git ref not found: ${opts.base}`); return null; }
+  let commit = ref;
+  let label = ref;
+  if (opts.mergeBase) {
+    try {
+      const head = opts.head || 'HEAD';
+      const mb = git(dir, ['merge-base', ref, head]).trim();
+      const tip = git(dir, ['rev-parse', ref]).trim();
+      commit = mb;
+      if (mb !== tip) label = `${ref} (where your branch split off, ${mb.slice(0, 7)})`;
+    } catch { /* unrelated histories or no HEAD yet: use the tip */ }
+  }
+  return { ref: commit, label };
+}
+
+function init(dir) {
+  const target = path.join(dir, 'tecton.config.json');
+  if (fs.existsSync(target)) fail(`${target} already exists`);
+  const src = workingTreeSource(dir);
+  const grouper = makeGrouper({}, src.files);
+  const mods = [...new Set(src.files.map((f) => grouper.moduleOf(f)).filter(Boolean))].sort();
+  const pick = (...names) => names.find((n) => mods.includes(n));
+  const ui = pick('components', 'ui', 'app', 'pages', 'views');
+  const data = pick('db', 'database', 'prisma', 'models', 'repositories', 'server');
+  const rules = [];
+  if (ui && data) rules.push({ name: `${ui} must not talk to ${data} directly`, from: ui, to: [data], message: 'Go through a service/API layer instead.' });
+  else rules.push({ name: 'example: replace with your own rule', from: mods[0] || 'components', to: [mods[1] || 'db'] });
+  const cfg = { root: grouper.root, depth: 1, cycles: 'warn', rules };
+  fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(`${green('created')} ${target}`);
+  console.log(`modules found under ${bold(grouper.root || '.')}: ${mods.map(cyan).join(', ') || dim('(none)')}`);
+  console.log(dim('Edit "rules" to describe what may depend on what, then run: tecton'));
+}
+
+function openFile(target) {
+  if (process.env.BROWSER === 'none') return; // the usual way to say "don't open a browser"
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', target] : [target];
+  try { spawn(cmd, args, { stdio: 'ignore', detached: true }).unref(); } catch { /* ignore */ }
+}
+
+/**
+ * Files inside modules, with how they changed, plus file → file imports. Feeds the per-module drill-down
+ * and the "touched in this change" filter. Kept compact: files = [path, module, status, edited], deps = [from, to, status, line].
+ * @param {Graph} prev
+ * @param {Graph} cur
+ * @param {Source | null} baseSrc
+ * @param {Source} curSrc
+ * @returns {FileGraph}
+ */
+function fileLevel(prev, cur, baseSrc, curSrc) {
+  const same = (a, b) => a != null && b != null && a.replace(/\r\n/g, '\n') === b.replace(/\r\n/g, '\n');
+  const all = [...new Set([...prev.moduleOf.keys(), ...cur.moduleOf.keys()])].sort();
+  const idx = new Map(all.map((f, i) => [f, i]));
+  const files = all.map((f) => {
+    const inB = prev.moduleOf.has(f); const inC = cur.moduleOf.has(f);
+    const st = inB && inC ? 's' : inC ? 'a' : 'r';
+    const edited = baseSrc ? (st !== 's' || !same(baseSrc.read(f), curSrc.read(f))) : false;
+    return /** @type {FileGraph['files'][number]} */ ([f, cur.moduleOf.get(f) || prev.moduleOf.get(f), st, edited ? 1 : 0]);
+  });
+  /** @type {Map<string, FileGraph['deps'][number]>} */
+  const deps = new Map();
+  const add = (g, st) => {
+    for (const [from, targets] of g.fileDeps) {
+      for (const [to, line] of targets) {
+        if (!idx.has(from) || !idx.has(to)) continue;
+        const k = `${from}>${to}`;
+        const had = deps.get(k);
+        if (had) had[2] = 's'; else deps.set(k, [idx.get(from), idx.get(to), st, line]);
+      }
+    }
+  };
+  add(cur, prev === cur ? 's' : 'a');
+  if (prev !== cur) add(prev, 'r');
+  return { files, deps: [...deps.values()].sort((a, b) => a[0] - b[0] || a[1] - b[1]) };
+}
+
+/** Read the code (and the base), compare, check rules and build the report model. */
+function analyze(dir, opts) {
+  const { cfg } = loadConfig(dir, opts.config);
+  const t0 = Date.now();
+  if (opts.head && !gitInfo(dir)) fail('--head needs a git repository');
+  const curSrc = opts.head ? gitRefSource(dir, opts.head) : workingTreeSource(dir);
+  const base = pickBase(dir, opts, cfg);
+  const baseSrc = base ? gitRefSource(dir, base.ref) : null;
+
+  const cur = buildGraph(curSrc, cfg);
+  const prev = baseSrc ? buildGraph(baseSrc, cfg) : cur;
+  if (!cur.modules.size) fail(`no JS/TS files found under ${path.join(dir, cur.root)} (set "root" in tecton.config.json)`);
+  const curViol = evaluate(cur, cfg);
+  const baseViol = baseSrc ? evaluate(prev, cfg) : curViol;
+  const d = diffGraphs(prev, cur, baseViol, curViol, cfg);
+
+  const sysCur = detectSystem(curSrc, cur, { project: path.basename(dir), aliases: cfg.aliases });
+  const sysBase = baseSrc ? detectSystem(baseSrc, prev, { project: path.basename(dir), aliases: cfg.aliases }) : sysCur;
+  const system = diffSystems(sysBase, sysCur);
+
+  const files = fileLevel(prev, cur, baseSrc, curSrc);
+  const touched = new Map();
+  for (const [, mod, , edited] of files.files) if (edited) touched.set(mod, (touched.get(mod) || 0) + 1);
+
+  const lay = layout(d.nodes, d.edges);
+  /** @type {import('../src/types.js').ReportModel} */
+  const model = {
+    project: path.basename(dir),
+    curLabel: opts.head ? opts.head : 'your working copy',
+    baseLabel: base ? base.label : null,
+    hasBase: !!base,
+    ruleCount: (cfg.rules || []).length,
+    generatedAt: new Date().toISOString(),
+    width: lay.width, height: lay.height,
+    summary: { ...d.summary, touched: { files: files.files.filter((f) => f[3]).length, modules: touched.size } },
+    nodes: d.nodes.map((n) => ({ ...n, pos: lay.pos[n.id], touched: touched.get(n.id) || 0 })),
+    edges: d.edges.map((e) => ({ ...e, points: lay.routes[e.id] })),
+    violations: d.violations,
+    rules: [
+      ...(cfg.rules || []).map((r, i) => ({
+        key: r.name || `rule ${i + 1}`, kind: 'rule', from: r.from, to: r.to ? [].concat(r.to) : null,
+        allow: r.allow ? [].concat(r.allow) : null, severity: r.severity || 'error', message: r.message || null,
+      })),
+      ...((cfg.cycles ?? 'warn') !== 'off' ? [{ key: 'No circular dependencies', kind: 'cycle', severity: cfg.cycles ?? 'warn', message: 'Modules should not depend on each other in a loop.' }] : []),
+    ],
+    files,
+    version: VERSION,
+    system,
+  };
+  model.markdown = toMarkdown(model);
+  const failing = d.violations.filter((v) => v.severity === 'error' && v.status !== 'fixed'
+    && (opts.strict || !base || v.status === 'new')).length;
+  return { model, d, base, ms: Date.now() - t0, failing };
+}
+
+function printSummary({ d, base, ms }, opts) {
+  const S = d.summary;
+  console.log(`${bold('tecton')} ${dim(`${S.files.cur} files · ${S.modules.total} modules · ${S.deps.total} dependencies · ${ms}ms`)}`);
+  if (base) {
+    console.log(`compared with ${cyan(base.label)}: modules ${green(`+${S.modules.added}`)}/${red(`−${S.modules.removed}`)}, dependencies ${green(`+${S.deps.added}`)}/${red(`−${S.deps.removed}`)}`);
+    for (const e of d.edges.filter((x) => x.status !== 'same')) {
+      console.log(`  ${e.status === 'added' ? green('+') : red('−')} ${e.from} → ${e.to}`);
+    }
+  } else {
+    console.log(dim('no git base found; showing a snapshot only'));
+  }
+  const relevant = d.violations.filter((v) => (base ? v.status !== 'existing' : true) || opts.strict);
+  for (const v of relevant) {
+    const where = v.kind === 'cycle' ? v.members.join(' ⇄ ') : `${v.from} → ${v.to}`;
+    const tag = v.status === 'fixed' ? green('fixed') : v.severity === 'error' ? red(base ? 'NEW' : 'ERROR') : yellow('warn');
+    const ev = v.imports[0] ? dim(` (${v.imports[0].file}:${v.imports[0].line})`) : '';
+    console.log(`  ${tag} ${v.rule}: ${where}${ev}`);
+  }
+  const existing = d.violations.filter((v) => v.status === 'existing').length;
+  if (base && existing && !opts.strict) console.log(dim(`  ${existing} rule break(s) already existed before this change`));
+}
+
+/** Run by a person (not CI, not piped)? Then the report opens in the browser by default. */
+const interactive = () => !!process.stdout.isTTY && !process.env.CI;
+
+function report(dir, opts) {
+  const res = analyze(dir, opts);
+  // a person at a terminal just wants to see it: open it, and keep it out of their project folder.
+  // CI and scripts get a predictable file and no browser.
+  const open = opts.open ?? interactive();
+  const out = opts.out ? path.resolve(opts.out)
+    : open ? path.join(os.tmpdir(), 'tecton', `${res.model.project.replace(/[^\w.-]+/g, '-') || 'report'}.html`)
+      : path.resolve('tecton-report.html');
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, toHtml(res.model));
+  if (opts.md) fs.writeFileSync(path.resolve(opts.md), res.model.markdown);
+  if (opts.json) fs.writeFileSync(path.resolve(opts.json), JSON.stringify(res.model, null, 2));
+  printSummary(res, opts);
+  console.log(`report: ${out}`);
+  if (open) { openFile(out); console.log(dim('opening it in your browser (--no-open to skip)')); }
+  if (!res.model.ruleCount && !opts.config) console.log(dim('tip: add rules ("components must not use db") with: tecton init'));
+  return res.failing ? 1 : 0;
+}
+
+// ------------------------------------------------------------------ tecton serve
+const WATCHED_NAMES = new Set(['package.json', 'tsconfig.json', 'jsconfig.json', 'tecton.config.json', 'archdiff.config.json']);
+const IGNORED_DIRS = /(^|\/)(node_modules|dist|build|out|\.next|\.nuxt|coverage|\.turbo|\.vercel|\.cache|\.output|\.svelte-kit)(\/|$)/;
+/** Does a change to this path (relative to the project) change the report? Commits and branch switches count too. */
+const relevant = (rel) => {
+  if (rel === '.git/HEAD' || rel.startsWith('.git/refs/heads/')) return true;
+  if (rel.startsWith('.git/') || IGNORED_DIRS.test(rel)) return false;
+  return isCode(rel) || isExtra(rel) || WATCHED_NAMES.has(path.posix.basename(rel));
+};
+
+// Added to the served page only: reloads on change and shows a small "live" pill.
+const LIVE_SNIPPET = `<script>(() => {
+  const pill = document.createElement('div');
+  pill.setAttribute('role', 'status');
+  pill.style.cssText = 'position:fixed;right:14px;bottom:14px;z-index:90;display:flex;align-items:center;gap:7px;padding:6px 11px;border-radius:999px;font:500 12px/1 Geist,system-ui,sans-serif;background:var(--surface,#fff);color:var(--text-2,#444);border:1px solid var(--border,#E6E3DC);box-shadow:0 4px 14px rgba(16,16,24,.08)';
+  const dot = document.createElement('i');
+  dot.style.cssText = 'width:7px;height:7px;border-radius:50%;background:#16A34A';
+  const txt = document.createElement('span');
+  pill.append(dot, txt);
+  const set = (color, t) => { dot.style.background = color; txt.textContent = t; };
+  set('#16A34A', 'Live');
+  document.addEventListener('DOMContentLoaded', () => document.body.appendChild(pill));
+  const es = new EventSource('/__tecton/events');
+  es.addEventListener('building', () => set('#5B5BD6', 'Updating…'));
+  es.addEventListener('reload', () => location.reload());
+  es.addEventListener('failed', (e) => set('#DC2626', 'Update failed: ' + e.data));
+  es.onerror = () => set('#8C8A85', 'Disconnected');
+  es.onopen = () => set('#16A34A', 'Live');
+})();</script>`;
+
+function serve(dir, opts) {
+  const clients = new Set();
+  const send = (event, data = '') => { for (const res of clients) res.write(`event: ${event}\ndata: ${String(data).replace(/\n/g, ' ')}\n\n`); };
+  let html = null;
+  let building = false;
+  let again = false;
+
+  const rebuild = (why) => {
+    if (building) { again = true; return; }
+    building = true;
+    send('building');
+    const t = new Date().toTimeString().slice(0, 8);
+    try {
+      const res = analyze(dir, opts);
+      html = toHtml(res.model).replace('</body>', `${LIVE_SNIPPET}\n</body>`);
+      const S = res.d.summary;
+      const status = res.failing ? red(`${res.failing} rule break${res.failing === 1 ? '' : 's'}`) : green('rules pass');
+      console.log(`${dim(t)} ${why ? `${cyan('↻')} ${dim(why)} · ` : ''}${S.modules.total} modules · ${S.deps.total} dependencies · ${status} ${dim(`${res.ms}ms`)}`);
+      send('reload');
+    } catch (e) {
+      console.error(`${dim(t)} ${red('update failed:')} ${e.message}`);
+      send('failed', e.message);
+      if (!html) html = `<!doctype html><meta charset="utf-8"><title>Tecton</title><body style="font:14px system-ui;padding:40px"><h1>Tecton could not read this project</h1><pre>${e.message.replace(/[<&]/g, (ch) => (ch === '<' ? '&lt;' : '&amp;'))}</pre>${LIVE_SNIPPET}</body>`;
+    }
+    building = false;
+    if (again) { again = false; setTimeout(() => rebuild('more changes'), 50); }
+  };
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://x');
+    if (url.pathname === '/__tecton/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      res.write('retry: 1000\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    if (url.pathname === '/' || url.pathname === '/index.html') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(html);
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('not found');
+  });
+  // keep the event streams alive through proxies and sleeping laptops
+  setInterval(() => { for (const r of clients) r.write(': ping\n\n'); }, 25000).unref();
+
+  rebuild(null);
+
+  // watch the folder; fall back to polling where recursive watching is unsupported
+  let timer = null;
+  const changed = new Set();
+  const schedule = (rel) => {
+    changed.add(rel);
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const list = [...changed]; changed.clear();
+      rebuild(list.length === 1 ? list[0] : `${list.length} files changed`);
+    }, 200);
+  };
+  const gi = gitInfo(dir);
+  try {
+    fs.watch(dir, { recursive: true }, (_ev, name) => {
+      if (!name) return;
+      const rel = name.split(path.sep).join('/');
+      if (relevant(rel)) schedule(rel);
+    });
+    // the repo's .git may sit above the analysed folder
+    if (gi && gi.prefix) fs.watch(path.join(gi.top, '.git'), { recursive: true }, (_ev, name) => { if (name && relevant(`.git/${name.split(path.sep).join('/')}`)) schedule('git'); });
+  } catch {
+    let last = null;
+    const signature = () => {
+      const src = workingTreeSource(dir);
+      const stat = (f) => { try { const s = fs.statSync(path.join(dir, f)); return `${f}:${s.mtimeMs}:${s.size}`; } catch { return f; } };
+      const head = gi ? stat(path.relative(dir, path.join(gi.top, '.git', 'HEAD'))) : '';
+      return [...src.files, ...src.manifests, ...(src.extras || []), 'tecton.config.json'].map(stat).join('|') + head;
+    };
+    setInterval(() => { const s = signature(); if (last !== null && s !== last) schedule('files changed'); last = s; }, 1000).unref();
+    console.log(dim('(recursive file watching is not available here; checking for changes every second)'));
+  }
+
+  const host = '127.0.0.1';
+  let port = opts.port ?? 4321;
+  const tries = opts.port == null ? 10 : 1;
+  let attempt = 0;
+  server.on('error', (/** @type {NodeJS.ErrnoException} */ e) => {
+    if (e.code === 'EADDRINUSE' && ++attempt < tries) { port++; server.listen(port, host); return; }
+    console.error(red(`tecton: could not listen on ${host}:${port}: ${e.message}`));
+    process.exit(2);
+  });
+  server.on('listening', () => {
+    const link = `http://${host}:${port}/`;
+    console.log(`${bold('tecton serve')} ${cyan(link)} ${dim(`watching ${dir} · Ctrl+C to stop`)}`);
+    if (opts.open ?? interactive()) openFile(link);
+  });
+  server.listen(port, host);
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { process.stdout.write(HELP); return 0; }
+  if (opts.version) { console.log(VERSION); return 0; }
+  const cmd = opts._[0];
+  if (cmd === 'init') { init(path.resolve(opts._[1] || '.')); return 0; }
+  if (cmd === 'serve') {
+    const dir = path.resolve(opts._[1] || '.');
+    if (!fs.existsSync(dir)) fail(`folder not found: ${dir}`);
+    serve(dir, opts);
+    return undefined; // keeps running
+  }
+  const dir = path.resolve(cmd || '.');
+  if (!fs.existsSync(dir)) fail(`folder not found: ${dir}`);
+  return report(dir, opts);
+}
+
+try {
+  const code = main();
+  if (code !== undefined) process.exitCode = code;
+} catch (e) {
+  if (!(e instanceof UsageError)) throw e;
+  console.error(red(`tecton: ${e.message}`));
+  process.exitCode = 2;
+}

package/brand/tecton-favicon.svg

@@ -0,0 +1,2 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><style>.a{fill:#0E0F13}.b{fill:#5B5BD6}@media (prefers-color-scheme:dark){.a{fill:#FAFAF7}.b{fill:#7C7FF2}}</style>
+<rect class="a" x="4" y="13" width="27" height="14" rx="3"/><rect class="b" x="33" y="7" width="27" height="14" rx="3"/><rect class="a" x="24" y="29" width="16" height="31" rx="3"/></svg>