// @vitest-environment node
/**
 * Die Dokumentation muss zur Fassung passen.
 *
 * Anlass ist ein wiederkehrendes Muster: Der Stand der Software stand an vier
 * Stellen – im Plan, in der Liesmich, im Prüfplan und in Gesprächen – und
 * lief auseinander. Der Plan führte das fertige Glossar als offen, die
 * Liesmich behauptete, es gebe keine Veröffentlichung, obwohl drei Etiketten
 * gesetzt waren.
 *
 * Geprüft wird deshalb genau der eine Fehler, der wirklich passiert: die
 * Nummer erhöhen und die Dokumentation vergessen. Ob der Inhalt stimmt, kann
 * kein Test wissen – dafür ist die Liste in `docs/veroeffentlichen.md` da.
 */

import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { describe, expect, it } from 'vitest';

/** Verzeichnis `app/`. */
const app = join(fileURLToPath(new URL('..', import.meta.url)));
/** Projektwurzel, eine Ebene darüber. */
const wurzel = join(app, '..');

function lesen(...teile: string[]): string {
  return readFileSync(join(...teile), 'utf8');
}

const fassung = (JSON.parse(lesen(app, 'package.json')) as { version: string }).version;

describe('Fassungsnummer', () => {
  it('ist eine gültige Nummer nach Semantic Versioning', () => {
    expect(fassung).toMatch(/^\d+\.\d+\.\d+$/u);
  });

  it('steht auch in der Sperrdatei', () => {
    /*
      Die Lücke, die genau einmal zwei Fassungen lang offen stand: Beim Sprung
      auf 0.22.0 blieb `package-lock.json` bei 0.21.0 stehen, und niemandem
      fiel es auf – die Wachen darunter sehen Changelog, stand.md und README
      an, nicht die Sperrdatei.

      Sie ist kein Nebenschauplatz: `npm ci` baut daraus, und ein
      Quelltextarchiv trägt sie mit. Eine Datei, die eine andere Fassung
      behauptet als die Anwendung, ist eine falsche Angabe – auch wenn sie
      nichts kaputt macht.

      Geprüft wird beides: der Wurzeleintrag und der Eintrag des eigenen
      Pakets. npm schreibt beide, wer von Hand ändert, vergisst leicht einen.
    */
    const sperre = JSON.parse(lesen(app, 'package-lock.json')) as {
      version: string;
      packages: Record<string, { version?: string }>;
    };

    expect(sperre.version, 'package-lock.json: Wurzeleintrag').toBe(fassung);
    expect(sperre.packages['']?.version, 'package-lock.json: eigener Paketeintrag').toBe(fassung);
  });
});

describe('CHANGELOG.md', () => {
  const pfad = join(wurzel, 'CHANGELOG.md');

  it('ist vorhanden', () => {
    expect(existsSync(pfad)).toBe(true);
  });

  it('führt die Fassung aus der package.json', () => {
    /*
      Der eigentliche Wächter. Wer die Nummer erhöht und den Verlauf
      vergisst, bekommt hier eine Meldung, die sagt, was zu tun ist – nicht
      erst ein Anwender, der wissen will, was sich geändert hat.
    */
    const text = lesen(pfad);
    expect(
      text.includes(`## [${fassung}]`),
      `CHANGELOG.md hat keinen Abschnitt "## [${fassung}]". ` +
        'Beim Anheben der Fassungsnummer den Abschnitt [Unveröffentlicht] ' +
        'umbenennen und einen neuen leeren darüber anlegen ' +
        '(siehe docs/veroeffentlichen.md).',
    ).toBe(true);
  });

  it('hält einen Abschnitt für Unveröffentlichtes offen', () => {
    /* Ohne ihn hat die nächste Änderung keinen Platz und landet unter der
       zuletzt veröffentlichten Nummer – dort ist sie falsch. */
    expect(lesen(pfad)).toContain('## [Unveröffentlicht]');
  });

  it('nennt zu jeder Fassung ein Datum', () => {
    const text = lesen(pfad);
    const ueberschriften = [...text.matchAll(/^## \[(?!Unveröffentlicht)([^\]]+)\](.*)$/gmu)];

    expect(ueberschriften.length).toBeGreaterThan(0);
    for (const [, nummer, rest] of ueberschriften) {
      expect(rest, `Der Fassung ${String(nummer)} fehlt das Datum.`).toMatch(
        /—\s*\d{4}-\d{2}-\d{2}/u,
      );
    }
  });
});

describe('docs/stand.md', () => {
  const pfad = join(wurzel, 'docs', 'stand.md');

  it('ist vorhanden', () => {
    expect(existsSync(pfad)).toBe(true);
  });

  it('gilt für die Fassung aus der package.json', () => {
    /*
      Ein Standdokument, das eine ältere Fassung nennt, ist schlimmer als
      keines: Es sagt mit der Autorität eines Dokuments etwas Falsches.
    */
    const text = lesen(pfad);
    expect(
      text.includes(`Fassung ${fassung}`),
      `docs/stand.md nennt nicht "Fassung ${fassung}". ` +
        'Beim Anheben der Fassungsnummer den Kopf des Dokuments nachführen ' +
        'und die Tabellen durchsehen (siehe docs/veroeffentlichen.md).',
    ).toBe(true);
  });

  it('verweist auf die übrigen Dokumente, statt sie zu wiederholen', () => {
    /* Der Umsetzungsstand soll an genau einer Stelle stehen. Die Wegweiser
       oben im Dokument sind das, was Leser dorthin führt. */
    const text = lesen(pfad);
    for (const ziel of ['PLAN.md', 'CHANGELOG.md', 'veroeffentlichen.md']) {
      expect(text, `docs/stand.md verweist nicht auf ${ziel}.`).toContain(ziel);
    }
  });
});

describe('README.md', () => {
  const pfad = join(wurzel, 'README.md');

  it('ist vorhanden', () => {
    expect(existsSync(pfad)).toBe(true);
  });

  it('nennt die Fassung aus der package.json', () => {
    /*
      Diese Wache fehlte, und sie hat gefehlt: Das README führte „Fassung
      0.9.0“, während die Anwendung bei 0.22.0 stand – dreizehn Nummern
      Rückstand, sichtbar in der ersten Bildschirmseite, die ein Besucher
      eines öffentlichen Archivs zu sehen bekäme. CHANGELOG und stand.md
      waren seit je bewacht, das Aushängeschild nicht.
    */
    const text = lesen(pfad);
    expect(
      text.includes(`Fassung ${fassung}`),
      `README.md nennt nicht "Fassung ${fassung}". ` +
        'Beim Anheben der Fassungsnummer den Standblock oben nachführen ' +
        '(siehe docs/veroeffentlichen.md).',
    ).toBe(true);
  });

  it('nennt einen Rückmeldeweg', () => {
    /* Wer eine Barriere findet, muss sie melden können, ohne die Anwendung
       erst zu installieren. Ein Archiv ohne Kontakt ist eine Sackgasse. */
    const text = lesen(pfad);
    expect(text).toContain('Olaf@olaf-willerding.de');
  });

  it('behauptet keine macOS-Fassung', () => {
    /* Es existiert kein macOS-Paket, und nichts davon lief je auf einem Mac
       (docs/stand.md, Abschnitt 5). docs/store-eintrag.md 9.1 führt „Auch für
       macOS“ deshalb unter „Nicht belegt – deshalb nicht behauptet“; für das
       README gilt derselbe Maßstab. Erlaubt bleibt, die Fassung als geplant
       oder als fehlend zu benennen – verboten ist die Behauptung, sie laufe. */
    const text = lesen(pfad);
    expect(text).not.toMatch(/läuft[^.]*\bmacOS\b/iu);
    expect(text).not.toMatch(/\bWindows und macOS\b/u);
  });
});

describe('docs/veroeffentlichen.md', () => {
  it('ist vorhanden und nennt die Schritte, die der Test nicht prüfen kann', () => {
    const text = lesen(wurzel, 'docs', 'veroeffentlichen.md');

    expect(text).toContain('CHANGELOG.md');
    expect(text).toContain('stand.md');
    // Ohne gebautes Paket sagt ein grüner E2E-Lauf nichts über das Paket.
    expect(text).toContain('dist:win');
  });
});

/*
  Der Updatebericht.

  Er ist **erzeugt** (`python tools/updatebericht.py`) und nicht von Hand
  gepflegt — der Mittelteil stammt Wort für Wort aus dem Changelog-Abschnitt
  der Fassung. Genau deshalb braucht er eine Wache: Ein erzeugtes Dokument,
  das niemand neu erzeugt, ist stiller falsch als ein handgeschriebenes, weil
  niemand mehr hinsieht.
*/
describe('docs/updatebericht.md', () => {
  const pfad = join(wurzel, 'docs', 'updatebericht.md');

  /**
   * Entfernt die Verweisziele, behält den sichtbaren Text.
   *
   * Der Bericht liegt in `docs/`, der Changelog im Wurzelverzeichnis; das
   * Werkzeug rechnet die relativen Ziele deshalb um. Verglichen wird der
   * Wortlaut, nicht der Pfad — sonst prüfte dieser Test die Umrechnung statt
   * der Aktualität.
   */
  function ohneVerweisziele(text: string): string {
    return text.replace(/\]\([^)]*\)/gu, ']()');
  }

  /** Der Changelog-Abschnitt einer Fassung, ohne Überschrift und Trennlinie. */
  function changelogAbschnitt(nummer: string): string {
    const text = lesen(wurzel, 'CHANGELOG.md');
    const kopf = new RegExp(`^## \\[${nummer.replace(/\./gu, '\\.')}\\]`, 'mu');
    const start = text.search(kopf);
    if (start === -1) {
      return '';
    }
    const rest = text.slice(start);
    const naechste = rest.slice(1).search(/^## \[/mu);
    const roh = naechste === -1 ? rest : rest.slice(0, naechste + 1);
    return roh
      .split('\n')
      .slice(1)
      .join('\n')
      .replace(/\n---\s*$/u, '')
      .trim();
  }

  it('ist vorhanden', () => {
    expect(existsSync(pfad), 'docs/updatebericht.md fehlt.').toBe(true);
  });

  it('gilt für die Fassung aus der package.json', () => {
    expect(
      lesen(pfad).includes(`Updatebericht zur Fassung ${fassung}`),
      `docs/updatebericht.md gilt nicht für Fassung ${fassung}. ` +
        'Neu erzeugen mit: python tools/updatebericht.py',
    ).toBe(true);
  });

  it('gibt den Changelog-Abschnitt der Fassung unverändert wieder', () => {
    /* Die eigentliche Zusage. Ohne sie stünde im Bericht irgendwann etwas
       anderes als im Änderungsverlauf — und niemand wüsste, welches von
       beiden gilt. */
    const bericht = lesen(pfad);
    const anfang = bericht.indexOf('## Was sich geändert hat');
    const ende = bericht.indexOf('## Wie Sie aktualisieren');

    expect(anfang, 'Der Bericht hat keinen Abschnitt „Was sich geändert hat".').toBeGreaterThan(-1);
    expect(ende, 'Der Bericht hat keinen Abschnitt „Wie Sie aktualisieren".').toBeGreaterThan(-1);

    const imBericht = bericht
      .slice(anfang + '## Was sich geändert hat'.length, ende)
      .replace(/\n---\s*$/u, '')
      .trim();

    expect(
      ohneVerweisziele(imBericht),
      'docs/updatebericht.md gibt den Changelog-Abschnitt nicht mehr wieder. ' +
        'Neu erzeugen mit: python tools/updatebericht.py',
    ).toBe(ohneVerweisziele(changelogAbschnitt(fassung)));
  });

  it('führt keinen toten Verweis', () => {
    /* Ein erzeugtes Dokument bekommt seine Verweise umgerechnet. Rechnet die
       Umrechnung falsch, merkt es beim Lesen niemand — beim Klicken schon. */
    const bericht = lesen(pfad);
    const tot = [...bericht.matchAll(/\]\(([^)#]+)\)/gu)]
      .map((treffer) => treffer[1] ?? '')
      .filter((ziel) => !/^(https?:|mailto:)/u.test(ziel))
      .filter((ziel) => !existsSync(join(wurzel, 'docs', ziel)));

    expect([...new Set(tot)]).toEqual([]);
  });

  it('nennt die stehenden Vorbehalte', () => {
    /* Sie sind der Grund, warum der Bericht mehr ist als eine Kopie des
       Changelogs: Wer die Datei in die Hand bekommt, muss ohne Nachfrage
       wissen, was die Fassung nicht leistet. */
    const text = lesen(pfad);
    for (const zusage of ['nicht signiert', 'macOS', 'Prüfungsausschuss', 'Ihr Lernstand bleibt']) {
      expect(text, `docs/updatebericht.md nennt „${zusage}" nicht.`).toContain(zusage);
    }
  });
});

/*
  Die öffentlichen Versionshinweise.

  Jede Fassung braucht einen Text, der veröffentlicht werden darf – auch eine
  Unterfassung, die nur einen Fehler behebt. Er steht im Changelog unter
  `### Für die Öffentlichkeit`, dem Gegenstück zu `### Für die Werkbank`, und
  `tools/store_notiz.py` macht daraus `docs/store-notiz.md`.

  Warum ein Test und nicht nur ein Haken auf einer Liste: Der Text entsteht am
  Ende einer Fassung, wenn alles andere fertig ist und niemand mehr Lust hat.
  Genau dort wird er vergessen. Ein Haken erinnert daran, ein roter Test hält
  an.

  Arbeitsteilung mit dem Werkzeug: Hier steht, was **strukturell** stimmen
  muss – der Block ist da, er steht auch in der erzeugten Datei, und er trägt
  nichts offensichtlich Internes. Die vollständige Liste der
  Öffentlichkeitsregeln führt `tools/store_notiz.py`; sie hier zu wiederholen
  hieße, zwei Listen auseinanderlaufen zu lassen. Wer eine Regel dort verletzt,
  bekommt kein Dokument mehr erzeugt – und fällt spätestens über die Prüfung
  auf, dass die erzeugte Datei nicht mehr zum Changelog passt.
*/
describe('Der Updatebericht widerspricht sich nicht selbst', () => {
  /*
    Die Wache, die gefehlt hat.

    `docs/updatebericht.md` ist das eine Dokument, das dem Anwender mit der
    Installationsdatei in die Hand gegeben wird. Sein Mittelteil kommt aus dem
    Changelog und wird hier oben Wort für Wort verglichen; der Rahmen bleibt
    von Hand — und genau dort stand bis Fassung 0.27.2 „ein öffentliches
    Archiv gibt es bislang nicht“, während 83 Zeilen weiter oben im selben
    Blatt „Der Quelltext dieser Software ist jetzt öffentlich einsehbar“ zu
    lesen war. Bei der EUPL ist die Verfügbarkeit des Quelltextes kein
    Nebensatz; wer den Rahmen las, ging den Anfrageweg statt der Adresse.

    Geprüft wird gegen `README.md` als Quelle der Wahrheit über das Archiv,
    nicht gegen eine hier wiederholte Adresse.
  */
  const bericht = lesen(wurzel, 'docs', 'updatebericht.md');
  const liesmich = lesen(wurzel, 'README.md');
  const klonadresse = /`git clone (https:\/\/[^`]+)`/u.exec(liesmich)?.[1];

  it('nennt dieselbe Klonadresse wie die Liesmich', () => {
    expect(klonadresse, 'README.md nennt keine Klonadresse mehr').toBeDefined();
    expect(bericht).toContain(klonadresse);
  });

  it('bestreitet das Archiv nicht, das die Liesmich nennt', () => {
    /* Geprüft wird der **Rahmen**, nicht der Mittelteil: Der Mittelteil kommt
       aus dem Changelog und darf den alten Wortlaut zitieren, wenn er dessen
       Behebung beschreibt. Der Rahmen ist die Stelle, an der der Satz als
       Zusage stand. */
    const rahmen = bericht.slice(bericht.indexOf('## Woran Sie die Angaben nachprüfen können'));
    expect(rahmen.length, 'der Schlussrahmen fehlt im Bericht').toBeGreaterThan(100);

    expect(rahmen).not.toMatch(/öffentliches Archiv gibt es (bislang )?nicht/u);
    expect(rahmen).not.toMatch(/nur auf Anfrage erhältlich/u);
  });
});

describe('Die Zahl der Abnahmebilder ist gezählt', () => {
  /*
    Zwei Dokumente nannten „dreizehn“, im Verzeichnis lagen vierzehn – seit
    `14-kapitelwahl.png` mit Fassung 0.27.1 dazukam. Abschnitt 5 der
    Veröffentlichungsliste verlangt, die Bilder nach dem Bauen neu zu ziehen;
    wer das Ergebnis gegen die Beschreibung hält, sucht sonst ein Bild zu
    wenig und weiß nicht, ob eines fehlt oder die Zahl alt ist.
  */
  const ZAHLWORT: Record<number, string> = {
    10: 'zehn',
    11: 'elf',
    12: 'zwölf',
    13: 'dreizehn',
    14: 'vierzehn',
    15: 'fünfzehn',
    16: 'sechzehn',
    17: 'siebzehn',
    18: 'achtzehn',
    19: 'neunzehn',
    20: 'zwanzig',
  };

  const bilder = readdirSync(join(wurzel, 'docs', 'bildschirmfotos')).filter((n) =>
    n.endsWith('.png'),
  );

  it('steht so in docs/stand.md und in docs/store-bilder/README.md', () => {
    const wort = ZAHLWORT[bilder.length];
    expect(wort, `Für ${String(bilder.length)} fehlt das Zahlwort in dieser Wache`).toBeDefined();

    expect(lesen(wurzel, 'docs', 'stand.md')).toContain(
      `Die ${String(wort)} Abnahmebilder unter \`docs/bildschirmfotos/\``,
    );
    expect(lesen(wurzel, 'docs', 'store-bilder', 'README.md')).toContain(
      `Die ${String(wort)} dort sind Abnahmedokumente`,
    );
  });
});

describe('docs/veroeffentlichen.md nennt nur Befehle, die es gibt', () => {
  /*
    Die Liste sagte im Kopf „Alle Befehle laufen in `app/`.“ – und keiner der
    acht Python-Aufrufe darunter läuft dort: `tools/` und `data-pipeline/`
    liegen im Wurzelverzeichnis. Aus `app/` heraus bricht jeder mit „No such
    file or directory“ ab, ausgerechnet bei den Schritten, deren Auslassen
    die Liste selbst „den wahrscheinlichsten Fehler“ nennt.

    Geprüft wird nicht die Ortsangabe im Text, sondern die Wirklichkeit
    dahinter: Jedes genannte Skript muss vom Wurzelverzeichnis aus dasein.
  */
  const liste = lesen(wurzel, 'docs', 'veroeffentlichen.md');

  it('nennt zu jedem Python-Aufruf ein Skript, das vom Wurzelverzeichnis aus dasteht', () => {
    const skripte = [...liste.matchAll(/python\s+(\S+\.py)/gu)].map((t) => t[1] ?? '');

    expect(skripte.length, 'keine Python-Aufrufe in der Liste gefunden').toBeGreaterThan(5);
    const fehlend = skripte.filter((skript) => !existsSync(join(wurzel, skript)));
    expect(fehlend, 'genannt, aber vom Wurzelverzeichnis aus nicht vorhanden').toEqual([]);
  });

  it('behauptet nicht, die Befehle liefen in app/', () => {
    /* Die eine Formulierung, die alle acht Aufrufe falsch verortet. */
    expect(liste).not.toMatch(/Alle Befehle laufen in `app\/`\./u);
  });
});

describe('Der Commit-Haken verspricht nichts, was die Projektregel verbietet', () => {
  /*
    `.githooks/pre-commit` schrieb: „`git commit --no-verify` bleibt möglich
    und soll es bleiben.“ CLAUDE.md sagt „Kein `--no-verify`“, und
    `.claude/settings.json` sperrt den Aufruf. Die eine Datei, die bei jedem
    Commit tatsächlich läuft, versprach damit das Gegenteil der Regel, unter
    der sie steht.
  */
  const haken = lesen(wurzel, '.githooks', 'pre-commit');
  const regeln = lesen(wurzel, 'CLAUDE.md');

  it('lädt nicht zum Umgehen ein, solange CLAUDE.md es verbietet', () => {
    expect(regeln, 'CLAUDE.md nennt die Regel nicht mehr').toContain('Kein `--no-verify`');
    expect(haken).not.toMatch(/--no-verify` bleibt möglich/u);
    expect(haken).toContain('NICHT vorgesehen');
  });
});

describe('docs/store-notiz.md', () => {
  const werkzeug = lesen(wurzel, 'tools', 'store_notiz.py');

  /**
   * Holt eine Festlegung aus dem Werkzeug, statt sie zu wiederholen.
   *
   * Die Feldgrenze und der Name des Abschnitts sind Zahlen und Zeichenketten,
   * die an genau einer Stelle stehen sollen. Stünden sie hier ein zweites Mal,
   * wäre die nächste Änderung eine halbe.
   */
  function ausWerkzeug(name: string, muster: RegExp): string {
    const treffer = muster.exec(werkzeug);
    expect(treffer?.[1], `tools/store_notiz.py: ${name} nicht gefunden.`).toBeDefined();
    return treffer?.[1] ?? '';
  }

  const ueberschrift = ausWerkzeug('OEFFENTLICH', /^OEFFENTLICH = '(.+)'$/mu);
  const feldgrenze = Number(ausWerkzeug('FELDGRENZE', /^FELDGRENZE = (\d+)$/mu));

  /** Eine Fassung des Changelogs mit ihrem öffentlichen Block. */
  interface Fassungsabschnitt {
    nummer: string;
    datum: string;
    /** `null`, wenn der Abschnitt fehlt. */
    block: string[] | null;
    /** Alle `###`-Überschriften der Fassung. */
    unterabschnitte: string[];
  }

  function changelogFassungen(): Fassungsabschnitt[] {
    const zeilen = lesen(wurzel, 'CHANGELOG.md').split('\n');
    const kopf = /^## \[([^\]]+)\](?:\s*—\s*(\S+))?\s*$/u;

    const koepfe: { i: number; nummer: string; datum: string }[] = [];
    zeilen.forEach((zeile, i) => {
      const treffer = kopf.exec(zeile);
      if (treffer) {
        koepfe.push({ i, nummer: treffer[1] ?? '', datum: treffer[2] ?? '' });
      }
    });

    // Hinter der ältesten Fassung steht ein Kommentar, der zu keiner gehört.
    let schluss = zeilen.length;
    for (let i = (koepfe.at(-1)?.i ?? 0) + 1; i < zeilen.length; i += 1) {
      if (zeilen[i]?.startsWith('<!--')) {
        schluss = i;
        break;
      }
    }

    return koepfe.map((eintrag, k) => {
      const ende = koepfe[k + 1]?.i ?? schluss;
      const inhalt = zeilen.slice(eintrag.i + 1, ende);
      return {
        nummer: eintrag.nummer,
        datum: eintrag.datum,
        unterabschnitte: inhalt.filter((z) => z.startsWith('### ')),
        block: blockLesen(inhalt),
      };
    });
  }

  function blockLesen(inhalt: string[]): string[] | null {
    const start = inhalt.findIndex((z) => z.trim() === ueberschrift);
    if (start === -1) {
      return null;
    }
    let ende = inhalt.length;
    for (let i = start + 1; i < inhalt.length; i += 1) {
      if (inhalt[i]?.startsWith('### ') || inhalt[i]?.startsWith('## ')) {
        ende = i;
        break;
      }
    }
    const block = inhalt.slice(start + 1, ende);
    while (block.length > 0 && !(block[0] ?? '').trim()) {
      block.shift();
    }
    while (block.length > 0 && !(block.at(-1) ?? '').trim()) {
      block.pop();
    }
    return block;
  }

  /** Der Block als reiner Text – so, wie ihn eine Eingabemaske zählt. */
  function reintext(block: string[]): string {
    const absaetze: string[] = [];
    let laufend = '';
    for (const zeile of block) {
      const blank = zeile.trim();
      if (!blank) {
        continue;
      }
      if (blank.startsWith('- ')) {
        if (laufend) {
          absaetze.push(laufend);
        }
        laufend = `- ${blank.slice(2)}`;
      } else {
        laufend = laufend ? `${laufend} ${blank}` : blank;
      }
    }
    if (laufend) {
      absaetze.push(laufend);
    }
    return absaetze
      .join('\n')
      .replace(/\*\*([^*]+)\*\*/gu, '$1')
      .replace(/(?<![*\w])\*([^*]+)\*(?![*\w])/gu, '$1')
      .normalize('NFC');
  }

  const fassungen = changelogFassungen();

  it('findet überhaupt Fassungen im Changelog', () => {
    /* Wäre der Kopf-Ausdruck falsch, liefen alle folgenden Prüfungen über eine
       leere Liste und wären grün, ohne etwas geprüft zu haben. */
    expect(fassungen.length, 'CHANGELOG.md: keine Fassungsüberschrift erkannt.').toBeGreaterThan(
      10,
    );
    expect(ueberschrift).toBe('### Für die Öffentlichkeit');
    expect(feldgrenze).toBeGreaterThan(0);
  });

  it('gibt jeder Fassung einen öffentlichen Text', () => {
    /* Die eigentliche Zusage: Es gibt keine Fassung ohne. Ausgenommen ist ein
       leerer Abschnitt `[Unveröffentlicht]` – solange dort nichts steht, gibt
       es auch nichts zu veröffentlichen. Sobald eine Rubrik auftaucht, gilt
       die Pflicht. */
    const ohne = fassungen
      .filter((f) => f.block === null)
      .filter((f) => !(f.nummer === 'Unveröffentlicht' && f.unterabschnitte.length === 0))
      .map((f) => f.nummer);

    expect(
      ohne,
      `Diesen Fassungen fehlt „${ueberschrift}" in CHANGELOG.md. ` +
        'Ohne diesen Abschnitt gibt es keinen Text, der veröffentlicht werden darf.',
    ).toEqual([]);
  });

  it('hält jeden öffentlichen Text im Rahmen des Feldes', () => {
    /* Der Text geht in ein Feld mit fester Grenze. Zu lang heißt: abgeschnitten
       – und abgeschnitten heißt, dass der letzte Punkt mitten im Satz endet. */
    const zuLang = fassungen
      .filter((f) => f.block !== null)
      .map((f) => ({ nummer: f.nummer, zeichen: reintext(f.block ?? []).length }))
      .filter((f) => f.zeichen > feldgrenze);

    expect(zuLang, `Erlaubt sind ${String(feldgrenze)} Zeichen.`).toEqual([]);
  });

  it('lässt nichts Internes in einen öffentlichen Text', () => {
    /* Nur die auffälligsten Muster – die vollständige Liste führt
       `tools/store_notiz.py`. Hier stehen die drei, die beim schnellen
       Schreiben wirklich passieren: ein Dateiname, ein Verweis auf ein anderes
       Dokument, eine Auszeichnung als Quelltext. */
    const auffaellig: { muster: RegExp; was: string }[] = [
      { muster: /`/u, was: 'Auszeichnung als Quelltext' },
      { muster: /\]\(/u, was: 'Verweis auf ein Dokument' },
      {
        muster: /\b[\w-]+\.(?:json|ts|tsx|js|mjs|md|py|yml|html|exe|db|png)\b/u,
        was: 'Dateiname',
      },
    ];

    const treffer: string[] = [];
    for (const f of fassungen) {
      if (f.block === null) {
        continue;
      }
      const text = f.block.join('\n');
      for (const { muster, was } of auffaellig) {
        const gefunden = muster.exec(text);
        if (gefunden) {
          treffer.push(`${f.nummer}: ${was} – „${gefunden[0]}"`);
        }
      }
    }

    expect(treffer).toEqual([]);
  });

  it('ist vorhanden und gibt jeden Block unverändert wieder', () => {
    /* Ohne diese Prüfung stünde im veröffentlichten Dokument irgendwann etwas
       anderes als im Changelog – und niemand wüsste, welches von beiden gilt.
       Sie fängt zugleich den Fall ab, dass jemand eine Öffentlichkeitsregel
       verletzt hat: Das Werkzeug erzeugt dann nichts mehr, und die Datei bleibt
       zurück. */
    const pfad = join(wurzel, 'docs', 'store-notiz.md');
    expect(existsSync(pfad), 'docs/store-notiz.md fehlt.').toBe(true);

    const notiz = lesen(pfad);
    const fehlend: string[] = [];
    for (const f of fassungen) {
      if (f.block === null || f.nummer === 'Unveröffentlicht') {
        /* Was noch keine Fassung hat, wird nicht veröffentlicht – der Text
           dafür muss trotzdem geschrieben sein, und die Prüfungen oben sehen
           ihn sich an. */
        continue;
      }
      const kopf = f.datum ? `### ${f.nummer} — ${f.datum}` : `### ${f.nummer}`;
      if (!notiz.includes(`${kopf}\n\n${f.block.join('\n')}`)) {
        fehlend.push(f.nummer);
      }
    }

    expect(
      fehlend,
      'docs/store-notiz.md gibt diese Fassungen nicht mehr so wieder wie CHANGELOG.md. ' +
        'Neu erzeugen mit: python tools/store_notiz.py',
    ).toEqual([]);
  });

  it('hält den Text der laufenden Fassung zum Einfügen bereit', () => {
    /* Wer eine Einreichung macht, soll den Text kopieren können, statt ihn aus
       dem Changelog zusammenzusuchen – samt der Zahl, die die Eingabemaske
       gleich selbst zählen wird. */
    const notiz = lesen(wurzel, 'docs', 'store-notiz.md');
    const aktuell = fassungen.find((f) => f.nummer === fassung);

    expect(
      aktuell?.block,
      `CHANGELOG.md hat keinen öffentlichen Text für ${fassung}.`,
    ).toBeTruthy();
    expect(notiz).toContain(`## Zum Einfügen: Fassung ${fassung}`);
    expect(notiz).toContain(reintext(aktuell?.block ?? []));
  });
});

describe('Die Adresse des Quelltextarchivs steht überall gleich', () => {
  /*
    Die Wache, die gefehlt hat.

    Die Übersichtsseite des Archivs war als Abfrage geschrieben
    (`?page=code&repo=waffensachkunde`) und ist auf einen sauberen Pfad
    umgestellt worden. Am 03.09.2026 stand die neue Form in `README.md`, die
    alte noch in `docs/fernarchiv.md`, `docs/stand.md` und
    `docs/store-eintrag.md` — drei Verweise, die ins Leere zeigen, wenn die
    alte Form nicht mehr aufgelöst wird.

    Geprüft wird gegen `README.md` als Quelle: Was dort steht, gilt. Eine
    Adresse in zwei Schreibweisen ist immer eine zu viel — eine davon ist
    falsch, und niemand merkt welche.
  */
  const liesmich = lesen(wurzel, 'README.md');
  const DOKUMENTE = ['stand.md', 'fernarchiv.md', 'store-eintrag.md', 'datenschutz.md'];

  it('nennt die Übersichtsseite nirgends mehr als Abfrage', () => {
    const uebersicht = /<(https:\/\/[^>]*\/quelltext[^>]*)>/u.exec(liesmich)?.[1];
    expect(uebersicht, 'README.md nennt keine Übersichtsseite unter /quelltext mehr').toBeDefined();

    const alt = DOKUMENTE.filter((name) => lesen(wurzel, 'docs', name).includes('?page=code'));
    expect(alt, 'tragen noch die alte Abfrageform der Archivadresse').toEqual([]);
  });

  it('nennt in jedem Dokument dieselbe Klonadresse wie die Liesmich', () => {
    const klon = /`git clone (https:\/\/[^`]+)`/u.exec(liesmich)?.[1] ?? '';
    expect(klon).not.toBe('');

    for (const name of DOKUMENTE) {
      const text = lesen(wurzel, 'docs', name);
      if (!text.includes('git clone')) {
        continue;
      }
      const eigene = [...text.matchAll(/git clone (https:\/\/\S+?)`/gu)].map((t) => t[1]);
      const abweichend = eigene.filter((adresse) => adresse !== klon);
      expect(abweichend, `${name} nennt eine andere Klonadresse als README.md`).toEqual([]);
    }
  });
});

describe('docs/stand.md führt nichts als offen, was die Unterlagen als erledigt belegen', () => {
  /*
    Die Wache, die gefehlt hat — und der teuerste Fehler dieses Dokuments.

    CLAUDE.md macht `docs/stand.md` zur einzigen Stelle für den
    Umsetzungsstand. Abschnitt 8 ist die Liste, die abgearbeitet wird. Stand
    dort etwas als offen, das erledigt ist, sucht der Leser Arbeit, die schon
    getan ist — und übersieht den Punkt daneben, der wirklich offen ist. Am
    03.09.2026 traf das auf drei Dinge zu: das MSIX-Paket (seit 0.22.0
    gebaut), den BVA-Brief (am 29.08.2026 versendet) und die
    Store-Einreichung (zweimal abgesendet).

    Geprüft wird nicht die Liste selbst, sondern der Widerspruch zwischen
    Dokumenten: Was ein anderes Dokument mit Datum als erledigt belegt, darf
    hier nicht als Aufgabe stehen. Jeder Fall hängt an der Quelle, die den
    Beleg trägt — fällt der Beleg weg, greift der Fall nicht mehr.
  */
  const stand = lesen(wurzel, 'docs', 'stand.md');

  it('nennt den BVA-Brief nicht als zu versendend, wenn er versendet ist', () => {
    const brief = lesen(wurzel, 'docs', 'bva-anschreiben.md');
    const versendet = /\*\*Versendet am (\d{2}\.\d{2}\.\d{4})\.?\*\*/u.exec(brief);

    if (versendet === null) {
      /* Noch nicht versendet – dann darf und soll die Liste ihn führen. */
      expect(stand).toContain('BVA-Brief');
      return;
    }

    expect(stand, 'der Brief ist versendet').not.toContain('**versendet ist er nicht**');
    expect(stand).not.toContain('**Der BVA-Brief ist zu versenden.**');
    expect(stand, 'das Versanddatum gehört in den Stand').toContain(versendet[1] ?? '');
  });

  it('behauptet nicht, es werde nur NSIS gebaut, wenn ein appx-Block dasteht', () => {
    const bauplan = lesen(app, 'electron-builder.yml');
    expect(bauplan, 'kein appx-Block mehr – dieser Fall ist dann gegenstandslos').toMatch(
      /^appx:$/mu,
    );

    expect(stand).not.toContain('baut nur NSIS');
  });

  it('nennt den Store-Eintrag nicht als nicht absendbar, wenn eingereicht ist', () => {
    const eintrag = lesen(wurzel, 'docs', 'store-eintrag.md');
    const eingereicht = /Einreichung\s+\*\*[\d.]+\*\*\s+abgesendet worden/u.test(eintrag);

    expect(eingereicht, 'store-eintrag.md meldet keine Einreichung mehr').toBe(true);

    /* Verboten ist die Behauptung, nicht das Zitat: Rückblicke dürfen den
       alten Wortlaut in Anführungszeichen nennen. Geprüft wird deshalb die
       zusagende Form und die Stand-Spalte der Zeile. */
    expect(stand).not.toContain('**Absendbar ist er nicht.**');
    expect(stand).not.toContain('| Vorhaben, Entwurf angelegt |');
  });
});

describe('Die Zahlen im Verzeichnisbaum von app/README.md sind gezählt', () => {
  /*
    Die Wache, die gefehlt hat.

    Der Baum im Abschnitt „Verzeichnisstruktur“ nennt zu neun Stellen eine
    Anzahl. Für die IPC-Kanäle gibt es seit Fassung 0.27.2 einen Fall darunter
    – die Zahl stimmte deshalb. Fünf der übrigen waren mitgewandert, ohne
    nachgeführt zu werden: `main/` 31 statt 32, `lernen/` 38 statt 40,
    `ueber/` 3 statt 4, `hooks/` 26 statt 29, `tests/` 72 statt 79. Wer den
    Umfang eines Bereichs daran abschätzt – etwa, um zu beurteilen, ob eine
    Testdatei fehlt oder ein Haken schon existiert –, rechnet mit zu wenig.

    CLAUDE.md verlangt: „Zahlen werden gemessen, nicht geschätzt.“ Also wird
    hier gemessen, und zwar so, wie der Baum zählt: `main/` alle Dateien,
    `tests/` nur die Testdateien, `e2e/` nur die Prüfdateien (die drei Helfer
    stehen im Baum eigens daneben).
  */
  const readme = lesen(app, 'README.md');

  function dateien(...teile: string[]): string[] {
    return readdirSync(join(app, ...teile), { withFileTypes: true })
      .filter((eintrag) => eintrag.isFile())
      .map((eintrag) => eintrag.name);
  }

  const faelle: readonly [string, number, string][] = [
    ['main/', dateien('src', 'main').length, 'voller Systemzugriff) – %d Dateien'],
    [
      'tests/',
      dateien('tests').filter((n) => /\.test\.tsx?$/u.test(n)).length,
      'Unit-Tests (Vitest, jsdom) – %d Testdateien',
    ],
    [
      'e2e/',
      dateien('e2e').filter((n) => n.endsWith('.spec.ts')).length,
      'gegen echtes Electron) – %d Prüfdateien',
    ],
    ['hooks/', dateien('src', 'renderer', 'src', 'hooks').length, 'hooks/             %d Haken'],
  ];

  for (const [was, anzahl, vorlage] of faelle) {
    it(`nennt zu ${was} die gezählte Anzahl`, () => {
      expect(readme, `${was} zählt ${String(anzahl)}`).toContain(
        vorlage.replace('%d', String(anzahl)),
      );
    });
  }

  it('nennt zu jedem Bausteinbereich die gezählte Anzahl', () => {
    const bereiche = ['lernen', 'pruefung', 'profil', 'suche', 'ueber', 'hilfe'];
    const gezaehlt = bereiche.map(
      (name) =>
        `${name}/ (${String(dateien('src', 'renderer', 'src', 'components', name).length)})`,
    );

    const fehlend = gezaehlt.filter((eintrag) => !readme.includes(eintrag));
    expect(fehlend, 'so steht es nicht im Baum von app/README.md').toEqual([]);
  });
});

describe('Die Zahl der IPC-Kanäle in app/README.md ist gezählt', () => {
  /*
    Befund der Prüfrunde zu 0.27.2. Die Übersicht führte „41 Kanäle“; gezählt
    waren es 44 — in `IPC_KANAELE`, unter den Handlern in `main/ipc.ts` und
    unter den vom Preload benutzten Kanälen, jeweils deckungsgleich. Drei
    Kanäle sind seit dem Schreiben der Zeile dazugekommen.

    Die Zahl beziffert die Größe der einzigen Grenze zwischen Oberfläche und
    Anwendungskern. Wer die Angriffsfläche über das README abschätzt,
    unterschätzte sie — und für `app/README.md` gab es bis dahin überhaupt
    keine Wache.
  */
  it('nennt so viele Kanäle, wie der Vertrag führt', () => {
    const vertrag = readFileSync(join(wurzel, 'app', 'src', 'shared', 'ipc.ts'), 'utf8');
    const block = vertrag.slice(vertrag.indexOf('IPC_KANAELE'));
    const kanaele = new Set(
      [...block.slice(0, block.indexOf('];')).matchAll(/'([a-z-]+:[a-z-]+)'/gu)].map((t) => t[1]),
    );
    expect(kanaele.size, 'Keine Kanäle gefunden – der Test misst nichts').toBeGreaterThan(30);

    const readme = readFileSync(join(wurzel, 'app', 'README.md'), 'utf8');
    const genannt = /\((\d+) Kanäle/u.exec(readme);

    expect(genannt, 'Die Zeile mit der Kanalzahl fehlt').not.toBeNull();
    expect(Number(genannt?.[1]), 'app/README.md nennt eine andere Zahl als der Vertrag').toBe(
      kanaele.size,
    );
  });

  it('hält Vertrag und Handler deckungsgleich', () => {
    /* Die Gegenprobe zur Zählung: Ein Kanal ohne Handler wäre eine tote
       Zusage, ein Handler ohne Eintrag ein Tor am Vertrag vorbei. */
    const vertrag = readFileSync(join(wurzel, 'app', 'src', 'shared', 'ipc.ts'), 'utf8');
    const block = vertrag.slice(vertrag.indexOf('IPC_KANAELE'));
    const kanaele = new Set(
      [...block.slice(0, block.indexOf('];')).matchAll(/'([a-z-]+:[a-z-]+)'/gu)].map((t) => t[1]),
    );
    const main = readFileSync(join(wurzel, 'app', 'src', 'main', 'ipc.ts'), 'utf8');
    const handler = new Set(
      [...main.matchAll(/behandeln\(\s*'([a-z-]+:[a-z-]+)'/gu)].map((t) => t[1]),
    );

    expect([...kanaele].filter((k) => !handler.has(k))).toEqual([]);
    expect([...handler].filter((k) => !kanaele.has(k))).toEqual([]);
  });
});