A diff goes in.
A verdict comes out.Un diff entre.
Un verdict sort.

01 · What it touchesCe qu’il touche

It maps your diff to the code it touches.Il relie votre diff au code qu’il touche.

semctx keeps a local index of your TypeScript. For every changed line it finds the declaration the line belongs to and the contracts and rules attached to it. For every changed file it lists the test files that import any of its symbols.

semctx tient un index local de votre TypeScript. Pour chaque ligne modifiée, il retrouve la déclaration qui la contient et les contrats et règles qui s’y rattachent. Pour chaque fichier modifié, il liste les fichiers de test qui importent l’un de ses symboles.

1. SymbolsSymboles

   The functions, classes, interfaces, types and enums your changed lines land in, plus the modules that hold them.

   Les fonctions, classes, interfaces, types et enums où tombent vos lignes modifiées, plus les modules qui les contiennent.

   impacted nodes: 7

2. Exported contractsContrats exportésWARN

   Exported interfaces and type aliases that other code compiles against. In this diff, CartTotal changed and nothing tests it.

   Les interfaces et alias de type exportés sur lesquels compile le reste du code. Dans ce diff, CartTotal a changé et rien ne le teste.

   Exported interface "CartTotal" is a public, compiler-enforced contract. [statically_verified]

3. @invariant rulesRègles @invariant

   The rules you write in a JSDoc marker, like the one below. This diff touches none; section 02 shows this one at work.

   Les règles que vous écrivez dans un marqueur JSDoc, comme celui ci-dessous. Ce diff n’en touche aucune ; la section 02 montre celle-ci à l’œuvre.

   @invariant greeting-non-empty

4. Linked test filesFichiers de test liés

   Test files that import any symbol from a changed file. semctx lists them so you know what to run. It never runs them itself.

   Les fichiers de test qui importent un symbole d’un fichier modifié. semctx les liste pour que vous sachiez quoi lancer. Il ne les exécute jamais lui-même.

   Recommended tests
     none

02 · Your rulesVos règles

You decide what must not break.Vous décidez de ce qui ne doit pas casser.

Write the rule as a JSDoc marker right above the code, commit it and run semctx index. From then on, if that code changes and no test imports it, the verdict is BLOCK and, by default, the exit code is 3. semctx never guesses what is critical.

Écrivez la règle sous forme de marqueur JSDoc, juste au-dessus du code, commitez-la et lancez semctx index. Dès lors, si ce code change et qu’aucun test ne l’importe, le verdict est BLOCK et, par défaut, le code de sortie vaut 3. semctx ne devine jamais ce qui est critique.

1/**5 * @capability greeting6 * @invariant greeting-non-empty: a greeting must never be an empty string7 */8export function greet(name: string): string {9  return `Hello, ${name}!`;10}

@@ -9 +9 @@ export function greet(name: string): string {-  return `Hello, ${name}!`;+  return name.length > 0 ? `Hello, ${name}!` : "";

Verdict: BLOCKlines omittedlignes omisesImpacted invariants  ! a greeting must never be an empty string [inferred]lines omittedlignes omisesFindings  [BLOCK] invariant_touched_without_test: invariant-constrained code changed without a covering test: greet

• Markers work above a function, a constant holding an arrow function, a class, an interface, a type alias or an enum. On a method, a property or a plain constant they are ignored, so to guard a method, mark its class.Les marqueurs fonctionnent au-dessus d’une fonction, d’une constante qui contient une fonction fléchée, d’une classe, d’une interface, d’un alias de type ou d’un enum. Sur une méthode, une propriété ou une simple constante, ils sont ignorés : pour protéger une méthode, marquez sa classe.
• In the default TypeScript-only flow, a test covers a symbol through a direct import under its declared name. Aliased, namespace, type-only and barrel imports do not count in that flow.Dans le parcours TypeScript seul par défaut, un test couvre un symbole par un import direct qui conserve son nom déclaré. Les imports renommés, par espace de noms, de type seul ou via un barrel ne comptent pas dans ce parcours.
• The opt-in config v2 qualified-static-v1 profile also follows canonical renamed imports, modeled namespace members and re-exports. Unknown or unsupported targets do not establish coverage. See the qualified profile and admission contract. These links are static associations; semctx does not run the tests.Le profil optionnel qualified-static-v1, en config v2, suit aussi les imports renommés, les membres d’espaces de noms modélisés et les réexports. Une cible inconnue ou non prise en charge ne prouve pas la couverture. Voir le profil qualifié et le contrat d’admission, en anglais. Ces liens restent statiques ; semctx n’exécute pas les tests.
• @tag security on a function, class, interface, type alias or enum (methods and plain constants are ignored), or @tag critical on an exported interface or type, also turns a missing test into BLOCK.@tag security sur une fonction, une classe, une interface, un alias de type ou un enum (les méthodes et les simples constantes sont ignorées), ou @tag critical sur une interface ou un type exporté, transforme aussi un test manquant en BLOCK.

03 · Three verdictsTrois verdicts

Three verdicts, one exit code to gate on.Trois verdicts, un code de sortie pour trancher.

The verdict is the most severe finding in the report. A hook, a CI job or a coding agent can stop on the exit code alone; to tell PASS from WARN, read the verdict line or --format json. The lamps keep their order: BLOCK on top, WARN in the middle, PASS at the bottom.

Le verdict reprend le constat le plus grave du rapport. Un hook, une CI ou un agent de code peut s’arrêter sur le seul code de sortie ; pour distinguer PASS de WARN, lisez la ligne du verdict ou --format json. Les feux gardent leur ordre : BLOCK en haut, WARN au milieu, PASS en bas.

04 · Where it runsOù il tourne

The same verdict in a terminal, a pull request or an agent.Le même verdict dans un terminal, une pull request ou un agent.

1. CLI

   semctx verify diff

   Human text, a versioned JSON report (--format json) or GitHub annotations (--format github). CLI referenceTexte lisible, rapport JSON versionné (--format json) ou annotations GitHub (--format github). Référence CLI

2. GitHub Actions

   uses: hoklims/semctx/packages/github-action@v0.4.5::warning title=semctx%3A contract_changed_without_test,file=src/cart.ts,line=1::exported contract changed without a covering test: CartTotal

   Indexes the checked-out commit, checks the pull request range, annotates each finding at the declaration it concerns and fails the job on BLOCK. No secrets, no PR comments. GuideIndexe le commit extrait, vérifie la plage de la pull request, annote chaque constat sur la déclaration concernée et fait échouer le job sur BLOCK. Sans secret, sans commentaire de PR. Guide

3. Claude Code

   bunx semctx@0.4.5 installsemctx guarded mode: no verification on record.

   A plugin with MCP tools and skills. Optional guarded mode: git commit and git push wait until a non-BLOCK verdict is recorded for that exact content. Guarded modeUn plugin avec outils MCP et skills. Mode protégé en option : git commit et git push attendent qu’un verdict autre que BLOCK soit enregistré pour ce contenu exact. Mode protégé

4. Codex

   bunx semctx@0.4.5 install --host codex

   The same MCP tools and skills. Codex has no guarded mode. GuideLes mêmes outils MCP et skills. Codex n’a pas de mode protégé. Guide

5. MCP

   semctx_verify_change

   Other MCP clients can run the server from a source checkout. An agent then checks its own diff before it says it is done. SetupLes autres clients MCP peuvent lancer le serveur depuis une copie du dépôt. Un agent vérifie alors son propre diff avant de dire qu’il a fini. Configuration

05 · Run itLancez-le

Three ways to start.Trois façons de commencer.

The CLI and the plugins need Bun 1.4.0 or newer, and the plugin hooks also need Node. The GitHub Action installs Bun itself. Every path needs a Git repository with at least one commit.

La CLI et les plugins demandent Bun 1.4.0 ou plus récent, et les hooks des plugins demandent aussi Node. L’action GitHub installe Bun elle-même. Dans tous les cas, il faut un dépôt Git avec au moins un commit.

# start from a clean, committed tree# partez d’un arbre propre, déjà commité
bunx semctx@0.4.5 setup
git switch -c try-semctx
# edit your code, then commit# modifiez le code, puis commitez
git add -A && git commit -m "my change"
bunx semctx@0.4.5 index
bunx semctx@0.4.5 verify diff --base main

# preview, change nothing# aperçu, rien n’est modifié
bunx semctx@0.4.5 install --dry-run
bunx semctx@0.4.5 install

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: hoklims/semctx/packages/github-action@v0.4.5
  with:
    base: ${{ github.event.pull_request.base.sha }}
    head: ${{ github.sha }}
    fail-on: block

06 · Keep the index currentGardez l’index à jour

Re-index after every commit.Réindexez après chaque commit.

semctx reads your diff through a local index of your code, so the index has to describe the commit you start from. Three situations cover it.

semctx lit votre diff à travers un index local de votre code : l’index doit donc décrire le commit dont vous partez. Trois situations couvrent l’essentiel.

1. Uncommitted editsModifications non commitées

   semctx setup# edit, no re-index# modifiez, sans réindexersemctx verify diff? Could not confirm index binding (STALE: ANALYSIS_INPUT_MISMATCH, WORKING_DIFF_MISMATCH); impact is reported without a freshness proof.

   The verdict stands, with this note under Unknowns. Do not re-index in between: the index would hold your edited line numbers while the diff counts from your last commit, and a finding can disappear.Le verdict tient, avec cette note sous Unknowns. Ne réindexez pas entre les deux : l’index prendrait vos numéros de ligne modifiés alors que le diff compte depuis votre dernier commit, et un constat peut disparaître.

2. After a commit, pull or branch switchAprès un commit, un pull ou un changement de branche

   semctx index[BLOCK] index_binding_stale

   Run it before the next check. Until you do, verify diff returns BLOCK with index_binding_stale, even for a harmless change.Lancez-le avant la vérification suivante. Tant que vous ne le faites pas, verify diff rend BLOCK avec index_binding_stale, même pour un changement anodin.

3. A branch or a pull requestUne branche ou une pull request

   git commitsemctx indexsemctx verify diff --base main

   The most complete check: new files and new tests count, and no freshness note appears. The GitHub Action runs this flow for you.La vérification la plus complète : les nouveaux fichiers et les nouveaux tests comptent, et aucune note de fraîcheur n’apparaît. L’action GitHub suit ce chemin pour vous.

With setup --polyglot (config v2), use the branch flow for files the config selects: an uncommitted check after editing one returns BLOCK. Commit the change, run semctx index, then verify with --base; never re-index uncommitted edits.

Avec setup --polyglot (config v2), passez par la branche pour les fichiers que la config sélectionne : une vérification non commitée après la modification de l’un d’eux rend BLOCK. Commitez la modification, lancez semctx index, puis vérifiez avec --base ; ne réindexez jamais des modifications non commitées.