@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/watch/delta.ts

@@ -0,0 +1,186 @@
+/**
+ * Deltas mit RICHTUNG — der eigentliche Zweck des Waechters.
+ *
+ * vision.md §1b: eine Aenderung, die Komplexitaet senkt, wird als
+ * Verbesserung AUSGEWIESEN und nicht nur stillschweigend hingenommen; eine
+ * Verschlechterung wird mit ihrer Beitragsstelle benannt. Eine nackte Zahl
+ * leistet weder das eine noch das andere.
+ *
+ * Fuer alle vier Metriken gilt dieselbe Leserichtung: kleiner ist einfacher.
+ * Ein negatives Delta heisst deshalb `"abgebaut"`, ein positives
+ * `"aufgebaut"`.
+ *
+ * ## Was diese Datei NICHT behauptet
+ *
+ * vision.md §1b macht die Qualitaetsaussage von drei Bedingungen abhaengig
+ * (unveraenderte oeffentliche Symboloberflaeche, unveraenderte Testergebnisse,
+ * keine neuen Abhaengigkeitskanten). Der Waechter misst hier NUR die
+ * Komplexitaet. `"abgebaut"` heisst also "die Komplexitaet ist gefallen" und
+ * ausdruecklich NICHT "die Aenderung war eine Verbesserung" — das waere ein
+ * Beweis, den eine statische Messung nicht fuehren kann.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import type { FileReadingV1, ScopeReadingV1 } from "./analyze.js";
+import {
+  METRIC_KEYS,
+  zeroMetricValues,
+  type ComplexityDirection,
+  type MetricDeltaV1,
+  type MetricKey,
+  type MetricValues,
+  type ScopeDeltaV1,
+} from "./events.js";
+
+/** Kleiner ist einfacher: negatives Delta = abgebaut. */
+export function directionOf(delta: number): ComplexityDirection {
+  if (delta < 0) return "abgebaut";
+  if (delta > 0) return "aufgebaut";
+  return "unveraendert";
+}
+
+/** Die Lesart, in der ein Metrikwert entstanden ist (siehe `analyze.ts`). */
+export function readingOf(metric: MetricKey): "execution_unit" | "file_chunks" {
+  return metric === "semantic" ? "file_chunks" : "execution_unit";
+}
+
+/**
+ * Deltas je Metrik zwischen zwei Messungen derselben Datei. `previous` fehlt
+ * bei einer neu hinzugekommenen Datei, `current` bei einer geloeschten — in
+ * beiden Faellen wird die fehlende Seite als 0 gelesen, damit das Delta die
+ * tatsaechliche Wirkung auf die Gesamtlage beschreibt.
+ */
+export function metricDeltas(
+  previous: FileReadingV1 | undefined,
+  current: FileReadingV1 | undefined,
+): MetricDeltaV1[] {
+  return METRIC_KEYS.map((metric) => {
+    const before = previous === undefined ? null : previous.totals[metric];
+    const after = current === undefined ? null : current.totals[metric];
+    const delta = (after ?? 0) - (before ?? 0);
+    return {
+      metric,
+      reading: readingOf(metric),
+      previous: before,
+      current: after,
+      delta,
+      direction: directionOf(delta),
+    };
+  });
+}
+
+/**
+ * Deltas je Scope, ueber `metrics_scope_id` aggregiert und ueber den
+ * stabilen `matchKey` zwischen den Staenden zugeordnet (siehe
+ * `ScopeReadingV1.matchKey`: die eindeutige `metrics_scope_id` ist
+ * byte-range-basiert und ueber zwei Staende hinweg absichtlich nicht stabil).
+ *
+ * Nur Scopes, die in der Lesart `"execution_unit"` ein Summand sind, kommen
+ * vor — sonst zaehlte dieselbe Aenderung zweimal, einmal an der Closure und
+ * einmal an ihrer umschliessenden Funktion.
+ *
+ * Sortierung: Betrag absteigend, bei Gleichstand Metrik-Reihenfolge, dann
+ * Codepoint-Ordnung des Labels. Nie `localeCompare`.
+ */
+export function scopeDeltas(
+  previous: FileReadingV1 | undefined,
+  current: FileReadingV1 | undefined,
+  limit: number,
+): ScopeDeltaV1[] {
+  const before = indexSelected(previous);
+  const after = indexSelected(current);
+  const keys = new Set<string>([...before.keys(), ...after.keys()]);
+  const deltas: ScopeDeltaV1[] = [];
+
+  for (const key of keys) {
+    const from = before.get(key);
+    const to = after.get(key);
+    for (const metric of METRIC_KEYS) {
+      if (metric === "semantic") continue; // semantische Ladung ist keine Scope-Groesse
+      const previousValue = from === undefined ? null : from.values[metric];
+      const currentValue = to === undefined ? null : to.values[metric];
+      const delta = (currentValue ?? 0) - (previousValue ?? 0);
+      if (delta === 0) continue;
+      const anchor = to ?? from;
+      if (anchor === undefined) continue;
+      deltas.push({
+        metricsScopeId: anchor.metricsScopeId,
+        label: anchor.label,
+        kind: anchor.kind,
+        line: anchor.line,
+        metric,
+        previous: previousValue,
+        current: currentValue,
+        delta,
+        direction: directionOf(delta),
+      });
+    }
+  }
+
+  deltas.sort(
+    (a, b) =>
+      Math.abs(b.delta) - Math.abs(a.delta) ||
+      METRIC_KEYS.indexOf(a.metric) - METRIC_KEYS.indexOf(b.metric) ||
+      compareCodepoints(a.label, b.label) ||
+      a.line - b.line,
+  );
+  return deltas.slice(0, limit);
+}
+
+function indexSelected(reading: FileReadingV1 | undefined): Map<string, ScopeReadingV1> {
+  const map = new Map<string, ScopeReadingV1>();
+  if (reading === undefined) return map;
+  for (const scope of reading.scopes) {
+    if (!scope.selected) continue;
+    map.set(scope.matchKey, scope);
+  }
+  return map;
+}
+
+/**
+ * Gesamtrichtung einer Aenderung ueber alle vier Metriken.
+ *
+ * ENTSCHEIDUNG: gezaehlt werden die Metriken, nicht die Betraege — die vier
+ * Metriken haben keine gemeinsame Einheit (ein semantisches Delta von 240
+ * geschaetzten Tokens ist nicht mit 13 kognitiven Punkten verrechenbar), eine
+ * Summe ueber sie waere eine erfundene Zahl. Ueberwiegt keine Richtung, ist
+ * das Urteil `"unveraendert"` — das ist ehrlicher als eine Scheinpraezision.
+ */
+export function verdictOf(deltas: readonly MetricDeltaV1[]): ComplexityDirection {
+  let down = 0;
+  let up = 0;
+  for (const delta of deltas) {
+    if (delta.direction === "abgebaut") down++;
+    if (delta.direction === "aufgebaut") up++;
+  }
+  if (down > up) return "abgebaut";
+  if (up > down) return "aufgebaut";
+  return "unveraendert";
+}
+
+/**
+ * Gesamtrichtung einer Netto-Bilanz. Zaehlt wie `verdictOf` die Metriken,
+ * nicht die Betraege — aus demselben Grund: die vier haben keine gemeinsame
+ * Einheit.
+ */
+export function netDirectionOf(net: MetricValues): ComplexityDirection {
+  let down = 0;
+  let up = 0;
+  for (const metric of METRIC_KEYS) {
+    if (net[metric] < 0) down++;
+    if (net[metric] > 0) up++;
+  }
+  if (down > up) return "abgebaut";
+  if (up > down) return "aufgebaut";
+  return "unveraendert";
+}
+
+/** Addiert Metrikwerte (fuer die Netto-Bilanz der Sitzung). */
+export function addMetricValues(
+  base: MetricValues,
+  deltas: readonly MetricDeltaV1[],
+): MetricValues {
+  const next: Record<MetricKey, number> = { ...zeroMetricValues(), ...base };
+  for (const delta of deltas) next[delta.metric] += delta.delta;
+  return next;
+}

package/src/commands/watch/events.ts

@@ -0,0 +1,235 @@
+/**
+ * Die Ereignisse des Komplexitaetswaechters — der Strom, den `untangle watch`
+ * ausgibt (vision.md §1b "Ratsche", §1d "Auffindbarkeit ist selbst ein
+ * Qualitaetssignal").
+ *
+ * Diese Datei fixiert die FORM des Stroms; `render.ts` fixiert nur seine
+ * Darstellung. Beide Ausgabewege (Text, JSON) speisen sich aus denselben
+ * Werten, damit die maschinenlesbare Ausgabe nie etwas anderes behauptet als
+ * die lesbare.
+ *
+ * ENTSCHEIDUNG (E4 an der Oberflaeche): `WatchUnanalyzedEventV1` ist ein
+ * ERSTKLASSIGES Stromereignis, kein Log-Rauschen. Eine Datei, die der
+ * Waechter nicht messen konnte, MUSS im selben Strom auftauchen wie eine, die
+ * er messen konnte — sonst liest der Nutzer aus dem Schweigen "nichts
+ * passiert", und genau das waere schlimmer als kein Waechter.
+ */
+import type { SkipLedgerEntryV1 } from "@untangle-code/domain";
+
+/**
+ * Die vier Metriken des Waechters (vision.md §1b: "strukturell, semantisch,
+ * cyclomatic, cognitive").
+ *
+ * Reihenfolge ist normativ: sie ist die Ausgabereihenfolge in JEDER
+ * Darstellung, damit zwei Laeufe zeilenweise vergleichbar bleiben.
+ */
+export const METRIC_KEYS = ["structural", "semantic", "cyclomatic", "cognitive"] as const;
+export type MetricKey = (typeof METRIC_KEYS)[number];
+
+/** Metrikwerte einer Messung, immer vollstaendig — kein Feld fehlt je. */
+export type MetricValues = Readonly<Record<MetricKey, number>>;
+
+/**
+ * Die Richtung einer Aenderung. Fuer ALLE vier Metriken gilt: kleiner ist
+ * einfacher, also bedeutet ein negatives Delta abgebaute Komplexitaet. Eine
+ * nackte Zahl hilft niemandem — die Richtung ist der Teil, der die Aussage
+ * traegt.
+ */
+export type ComplexityDirection = "abgebaut" | "aufgebaut" | "unveraendert";
+
+/**
+ * Welche Lesart einer Scope-Summe hinter einem Metrikwert steht
+ * (`packages/complexity/src/scope-aggregate.ts`). Eine Zahl ohne Lesart waere
+ * bedeutungslos, deshalb reist sie mit.
+ *
+ * - `"execution_unit"` — Summe ueber die aeussersten Ausfuehrungseinheiten,
+ *   jede genau einmal, verschachtelte Closures darin enthalten. Die Vorgabe
+ *   fuer strukturell/cyclomatic/cognitive.
+ * - `"file_chunks"` — die semantische Ladung wird nicht ueber Scopes
+ *   summiert, sondern ueber die Chunks der Datei (siehe `analyze.ts`).
+ */
+export type MetricReadingKind = "execution_unit" | "file_chunks";
+
+/** Ein Delta EINER Metrik, mit Richtung. */
+export interface MetricDeltaV1 {
+  metric: MetricKey;
+  reading: MetricReadingKind;
+  /** Wert vor der Aenderung; `null` bei einer neu hinzugekommenen Datei. */
+  previous: number | null;
+  /** Wert nach der Aenderung; `null` bei einer geloeschten Datei. */
+  current: number | null;
+  /** `current - previous`, mit fehlender Seite als 0 gelesen. */
+  delta: number;
+  direction: ComplexityDirection;
+}
+
+/** Ein Delta EINES Scopes — die Stelle, an der der Preis entsteht. */
+export interface ScopeDeltaV1 {
+  /** `metrics_scope_id` nach spec.md §16.10. */
+  metricsScopeId: string;
+  /** Qualifizierter Name des Scopes, wie ihn der Sprachadapter meldet. */
+  label: string;
+  kind: string;
+  /** Erste Zeile des Scopes NACH der Aenderung, sonst davor. */
+  line: number;
+  metric: MetricKey;
+  previous: number | null;
+  current: number | null;
+  delta: number;
+  direction: ComplexityDirection;
+}
+
+/** Der Waechter hat den Lock erworben und die Grundmessung begonnen. */
+export interface WatchStartedEventV1 {
+  kind: "started";
+  sequence: number;
+  at: string;
+  root: string;
+  repoId: string;
+  refId: string;
+  lockKey: string;
+}
+
+/**
+ * Die Grundmessung ist fertig: ab hier sind alle Deltas gegen einen bekannten
+ * Stand gemessen und nicht gegen Nichts.
+ */
+export interface WatchBaselineEventV1 {
+  kind: "baseline";
+  sequence: number;
+  at: string;
+  filesAnalyzed: number;
+  /** Wie viele Dateien mit Grund im Ledger stehen (E4). */
+  filesUnanalyzed: number;
+  /**
+   * Wie viele Pfade der Scanner ueber Ignorierregeln ausgeschlossen hat
+   * (`.gitignore`, Vorgabeausschluesse, Konfiguration).
+   *
+   * WARUM NUR EINE ZAHL UND KEIN EREIGNIS JE PFAD: das sind auf einem
+   * gewoehnlichen Repository zehntausende Pfade (`node_modules/`, `dist/`),
+   * und ein Strom, der davon ueberflutet wird, verbirgt genau das, was E4
+   * sichtbar machen will. Ausgeschlossen-nach-Regel ist zudem eine
+   * Konfigurationsentscheidung des Nutzers, kein Analysefehlschlag. Jeder
+   * Ausschluss, der NICHT auf einer Regel beruht — binaerer Inhalt,
+   * Groessengrenze, unlesbar — bekommt sein eigenes `unanalyzed`-Ereignis.
+   */
+  filesExcludedByRules: number;
+  totals: MetricValues;
+  /** Summe der Scopes, die in die drei Scope-Metriken eingehen. */
+  scopeCount: number;
+  /**
+   * Wie viele Scope-Ids der Sprachadapter innerhalb einer Datei doppelt
+   * vergeben hat und `withUniqueScopeIds` reparieren musste (WP-82). `> 0`
+   * ist kein Fehler, aber eine Einschraenkung, die sichtbar bleiben muss.
+   */
+  scopeIdCollisions: number;
+  /**
+   * Wie viele `NodeKindFact`s nur ueber den Ersatzweg zugeordnet werden
+   * konnten (sie tragen keine `SourceRange`). Betrifft ausschliesslich die
+   * strukturelle Metrik.
+   */
+  nodeKindFallbacks: number;
+  durationMs: number;
+}
+
+/** Eine Aenderung an einer Datei, mit Deltas je Metrik und je Scope. */
+export interface WatchChangeEventV1 {
+  kind: "change";
+  sequence: number;
+  at: string;
+  changeKind: "added" | "modified" | "deleted";
+  /** "/"-normalisierter, repo-relativer Pfad. */
+  path: string;
+  languageId: string | null;
+  contentHash: string | null;
+  metrics: MetricDeltaV1[];
+  /**
+   * Die Scopes, deren Wert sich geaendert hat — nach Betrag absteigend,
+   * bei Gleichstand nach Scope-Id (Codepoint-Ordnung).
+   */
+  scopes: ScopeDeltaV1[];
+  /** Gesamtrichtung ueber alle vier Metriken (siehe `delta.ts`). */
+  verdict: ComplexityDirection;
+  /**
+   * Einschraenkungen dieser einen Messung im Klartext (Parse-Qualitaet,
+   * Chunker-Abstufung, Scope-Id-Kollisionen). Leer heisst: keine.
+   */
+  notes: string[];
+  analysisMs: number;
+}
+
+/**
+ * E4 an der Oberflaeche: eine Datei, die NICHT analysiert werden konnte,
+ * erscheint im Strom als solche — mit Grund, Detailtext und der Angabe, ob
+ * ein spaeterer Versuch Aussicht auf Erfolg hat.
+ */
+export interface WatchUnanalyzedEventV1 {
+  kind: "unanalyzed";
+  sequence: number;
+  at: string;
+  /** Woher die Datei kam: Grundmessung oder eine laufende Aenderung. */
+  origin: "baseline" | "change";
+  entry: SkipLedgerEntryV1;
+}
+
+/** Zustandswechsel des Watchers (`starting` → `running` → `degraded` → `stopped`). */
+export interface WatchStatusEventV1 {
+  kind: "status";
+  sequence: number;
+  at: string;
+  status: "starting" | "running" | "degraded" | "stopped";
+  /** Fehlertext, wenn der Wechsel durch einen Fehler ausgeloest wurde. */
+  detail: string | null;
+}
+
+/** Der Waechter hat sauber beendet: Strom geschlossen, Lock freigegeben. */
+export interface WatchStoppedEventV1 {
+  kind: "stopped";
+  sequence: number;
+  at: string;
+  /**
+   * `"signal"` = SIGINT/SIGTERM, `"limit"` = `--exit-after` erreicht,
+   * `"baseline"` = `--baseline-only`, `"error"` = Abbruch.
+   */
+  reason: "signal" | "limit" | "baseline" | "error";
+  signal: string | null;
+  changesObserved: number;
+  filesUnanalyzed: number;
+  /** Netto-Delta der Sitzung je Metrik: was diese Sitzung insgesamt bewirkt hat. */
+  net: MetricValues;
+  netDirection: ComplexityDirection;
+  /** Rueckstau-Kennzahlen der `BoundedQueue` (architecture.md §13.2). */
+  queue: {
+    maxDepthObserved: number;
+    maxBytesObserved: number;
+    overBudgetAdmissions: number;
+  };
+  lockReleased: boolean;
+  durationMs: number;
+}
+
+export type WatchStreamEventV1 =
+  | WatchStartedEventV1
+  | WatchBaselineEventV1
+  | WatchChangeEventV1
+  | WatchUnanalyzedEventV1
+  | WatchStatusEventV1
+  | WatchStoppedEventV1;
+
+/** Nullwerte fuer alle vier Metriken — nie `{}` weiterreichen. */
+export function zeroMetricValues(): MetricValues {
+  return { structural: 0, semantic: 0, cyclomatic: 0, cognitive: 0 };
+}
+
+/**
+ * Ein Ereignis OHNE Umschlag (`sequence`, `at`) — die Form, in der der
+ * Waechter ein Ereignis meldet; den Umschlag setzt `runWatch` an genau einer
+ * Stelle, damit die laufende Nummer luecken- und sprungfrei bleibt.
+ *
+ * Die Verteilung ueber die Vereinigung (`T extends unknown ? ... : never`)
+ * ist notwendig: ein `Omit` DIREKT auf der Vereinigung behielte nur die
+ * gemeinsamen Felder aller Varianten uebrig und verwuerfe genau die Felder,
+ * um die es geht.
+ */
+type WithoutEnvelope<T> = T extends unknown ? Omit<T, "sequence" | "at"> : never;
+export type WatchStreamEventDraftV1 = WithoutEnvelope<WatchStreamEventV1>;

package/src/commands/watch/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `untangle watch` — der Komplexitaetswaechter (vision.md §1b, §1d).
+ *
+ * Dies ist die EINZIGE oeffentliche Schnittstelle des Kommandos; `main.ts`
+ * und die Tests importieren nur von hier.
+ */
+export { createFileAnalyzer, ORDERED_METRICS } from "./analyze.js";
+export type {
+  AnalysisOutcomeV1,
+  FileAnalyzerOptions,
+  FileReadingV1,
+  ScopeReadingV1,
+} from "./analyze.js";
+export {
+  addMetricValues,
+  directionOf,
+  metricDeltas,
+  netDirectionOf,
+  readingOf,
+  scopeDeltas,
+  verdictOf,
+} from "./delta.js";
+export { METRIC_KEYS, zeroMetricValues } from "./events.js";
+export type {
+  ComplexityDirection,
+  MetricDeltaV1,
+  MetricKey,
+  MetricReadingKind,
+  MetricValues,
+  ScopeDeltaV1,
+  WatchBaselineEventV1,
+  WatchChangeEventV1,
+  WatchStartedEventV1,
+  WatchStatusEventV1,
+  WatchStoppedEventV1,
+  WatchStreamEventDraftV1,
+  WatchStreamEventV1,
+  WatchUnanalyzedEventV1,
+} from "./events.js";
+export { parseWatchArgs, WATCH_USAGE } from "./options.js";
+export type { ParseWatchArgsEnv, WatchOptionsV1 } from "./options.js";
+export { formatNumber, formatSigned, renderJson, renderText } from "./render.js";
+export { runWatch } from "./run.js";
+export type { RunWatchDeps } from "./run.js";
+export {
+  createIgnorePredicate,
+  createStreamSink,
+  CryptoRandom,
+  STATE_DIR_NAME,
+  stripAnsi,
+  SystemClock,
+} from "./runtime.js";
+export { runWatchCli } from "./cli.js";