archgate check

Kjør alle automatiserte ADR-samsvarskontroller mot kodebasen.

archgate check [options] [files...]

Laster inn hver ADR med rules: true i frontmatteren, kjører den tilhørende .rules.ts-filen og rapporterer brudd med filstier og linjenumre. Når filstier oppgis som posisjonsargumenter, kjøres bare ADR-er der files-mønstrene matcher disse filene.

Valg

Valg	Beskrivelse
--staged	Sjekk kun git-stagede filer (nyttig for pre-commit-hooks)
--base [ref]	Sammenlign endrede filer mot en basisreferanse (autodetekteres hvis utelatt)
--output <format>	Utdataformat: console (standard), json, github eller sarif. Se SARIF-utdata.
--adr <id>	Sjekk kun regler fra en bestemt ADR
--verbose	Vis beståtte regler og tidsinformasjon
--strict	Behandle enhver regelbasert advarsel, og veiledende funn (sammendragsbudsjett, undertrykkelse, utolkede ADR-er), som feil. Se Streng modus.

Argumenter

Argument	Beskrivelse
[files...]	Valgfrie filstier for å begrense kontrollene. Bare ADR-er der files-mønstrene matcher vil kjøres. Støtter stdin-piping.

Avslutningskoder

Kode	Betydning
0	Alle regler bestått. Ingen brudd funnet.
1	Ett eller flere brudd oppdaget, eller --strict eskalerte advarsler eller veiledende funn til feil.
2	Feil ved regelkjøring (f.eks. feilformatert regel, sikkerhetsskannerblokkering).

Eksempler

Sjekk hele prosjektet:

archgate check

Sjekk kun stagede filer før commit:

archgate check --staged

Sjekk alle filer endret på gjeldende gren vs main:

archgate check --base main

Sjekk en enkelt ADR:

archgate check --adr ARCH-001

Behandle enhver regelbasert advarsel og ethvert veiledende funn (sammendragsbudsjett, undertrykkelse, utolkede ADR-er) som en feil (nyttig i CI):

archgate check --strict

Sjekk bestemte filer (bare matchende ADR-er kjøres):

archgate check src/foo.ts src/bar.ts

Pipe fra git (sjekk kun endrede filer):

git diff --name-only | archgate check --output json

Hent JSON-utdata for CI-integrasjon:

archgate check --output json

Hent GitHub Actions-annotasjoner:

archgate check --output github

Hent SARIF-utdata for GitHub Code Scanning:

archgate check --output sarif > results.sarif

SARIF-utdata

archgate check --output sarif gir ut SARIF 2.1.0, standardformatet GitHubs Code Scanning- og Code Quality-funksjoner leser i CI. Hvert regelbrudd blir et SARIF-resultat; alvorlighetsgradene error/warning/info tilordnes SARIF sine error/warning/note. Veiledende funn (sammendragsbudsjett, undertrykkelse og utolkede ADR-er) er også inkludert, som syntetiske resultater under egne regel-ID-er (archgate/briefing-budget, archgate/suppression-warning, archgate/unparsed-adr), alltid på nivået warning — i tråd med at de aldri behandles som blokkerende utenfor --strict.

--output sarif er kun opt-in: i motsetning til agent-kontekst json, blir det aldri autodetektert.

Last opp resultater til GitHubs Security-fane i CI:

- name: Run archgate check
  run: archgate check --output sarif > results.sarif

- name: Upload SARIF to GitHub Security tab
  if: success() || failure()
  uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
  with:
    sarif_file: results.sarif

Betingelsen if: success() || failure() er påkrevd: archgate check avslutter med kode 1 når den finner brudd, noe som ellers ville hoppet over opplastingssteget akkurat når det finnes funn å rapportere. Foretrekk den fremfor always(), som også ville kjørt opplastingen for kansellerte jobber. Jobben trenger også tillatelsen security-events: write for at opplastingen skal lykkes.

Se CI-integrasjonsguiden for hele arbeidsflyten.

Deteksjon av endrede filer

Som standard autodetekterer archgate check hovedgrenen og fyller ctx.changedFiles med grendifferansen (git diff <base>...HEAD) pluss eventuelle ikke-committede endringer i arbeidstreet (stagede, ustagede og usporede ikke-ignorerte filer). Dette gjør at regler for avhengigheter på tvers av filer fungerer lokalt — ikke bare i CI — og sikrer at endringer som ennå ikke er committet, også sjekkes.

Basisreferansen løses i denne prioritetsrekkefølgen:

Prioritet	Kilde	changedFiles fylles med
1	--staged	Kun git-stagingområdet
2	--base <ref>	git diff <ref>...HEAD + arbeidstre-endringer
3	.archgate/config.json baseBranch	git diff <resolved-ref>...HEAD + arbeidstre-endringer
4	Git-autodeteksjon	git diff <detected-ref>...HEAD + arbeidstre-endringer
5	Deteksjon mislykkes	Tom (fullskanmodus)

Autodeteksjon prøver origin/HEAD, deretter origin/main, origin/master, lokal main og lokal master. For å sette en prosjektstandard, legg til baseBranch i .archgate/config.json:

{ "baseBranch": "main" }

Hopper over uberørte ADR-er

Når endringssettet ikke er tomt (en av prioritetene 1—4 ovenfor), hoppes en ADR hvis files-globs ikke matcher noen av de endrede filene over i sin helhet: reglene kjøres aldri, og ADR-en vises verken i resultatene eller i tellingen av beståtte/feilede regler — samme oppførsel som et [files...]-filter som ikke matcher noe ADR-en styrer. Slettede filer regnes som endringer, så fjerning av en fil innenfor en ADRs omfang kjører fortsatt den ADR-en. ADR-er uten files-omfang kjøres alltid.

Det betyr at en regel ikke trenger å filtrere ctx.scopedFiles mot ctx.changedFiles bare for å unngå arbeid når ADR-en er irrelevant for endringen; rammeverket kaller den aldri i det tilfellet. Filtrering inne i regelen er fortsatt nyttig når noen filer i omfanget er endret og regelen bare vil undersøke dem.

Når endringssettet er tomt — deteksjonen mislykkes, --staged finner ingenting staget, eller arbeidstreet er likt basen (for eksempel på selve basegrenen i CI) — kjøres alle ADR-er (fullskanmodus).

Diagnostikk

Under kjøring sender archgate check advarsler for vanlige feilkonfigurasjoner som kan forårsake trege eller uventede resultater:

Advarsel	Tilstand	Anbefaling
Bredt filomfang	En ADRs files-mønstre løser til mer enn 1000 filer eller glob-skanningen tar over 2 sekunder	Begrens files-mønstrene i ADR-frontmatteren til å kun omfatte relevante kildekatalogene
Uscopet gitignore-fravalg	respectGitignore: false er satt uten et files-omfang	Legg til files-mønstre for å unngå skanning av alle filer inkludert node_modules/, .git/ osv.
Alle filer ekskludert av gitignore	Eksplisitte files-mønstre matcher filer, men alle treff er ekskludert av .gitignore	Sett respectGitignore: false i ADR-frontmatteren for å inkludere gitignorerte filer

Disse advarslene vises i standardutdataene og påvirker ikke avslutningskoden. De vises også i JSON-utdata når --output json brukes (som brudd med "severity": "warning").

Sammendragsbudsjett

archgate review-context --verbose bygger inn Decision- og Do’s and Don’ts-seksjonene fra hver aktuelle ADR og avkorter hver av dem ved en fast tegngrense. Tekst utover dette når aldri agenten ADR-en styrer, og ingen tilhørende regel kan oppdage det — regler måler kode, ikke ADR-ens egen tekst.

archgate check rapporterer derfor hver ADR-seksjon som overskrider grensen, for alle ADR-er, også de med rules: false:

[briefing] ARCH-024 "Decision" is 3574 chars; review-context truncates at 2000, hiding 1574 from agent briefings

De samme oppføringene finnes i JSON-utdata under briefingWarnings, med adrId, file, section, length og cap.

En ADR som ikke kan leses eller tolkes, blir målt av ingenting, og rapporteres derfor separat i stedet for å telle som etterlevd:

[adr] could not be parsed, so it was excluded from every check above  .archgate/adrs/BROKEN.md

JSON-utdata lister disse filene under unparsedAdrs. En tom briefingWarnings betyr «ingenting over grensen» bare når unparsedAdrs også er tom — ellers ble deler av korpuset aldri undersøkt.

Disse er veiledende og påvirker aldri pass, med mindre --strict er satt — se Streng modus.

For å fjerne en overskridelse, bruk først tiltakene som ikke kan koste en regel: flytt begrunnelser til Context eller Consequences, som aldri inngår i sammendraget og derfor aldri har grense; fjern historisk fortellende tekst; og slå sammen punkter som sier samme regel to ganger.

Hvis neste kutt ville fjerne en normativ bestemmelse — en oppregnet liste med identifikatorer, en ordnet sikkerhetssjekk, et unntak — stopp. Den seksjonen forventes å overskride grensen og MÅ IKKE kortes ned ytterligere. Dokumenter hvorfor i ADR-ens egen Compliance-seksjon, og ordne seksjonen slik at det mest normative innholdet kommer før kuttet, siden avkorting alltid fjerner slutten.

Som standard endrer advarsler (både diagnostikk og regelrapporterte brudd med "severity": "warning") aldri avslutningskoden. Send --strict for å eskalere dem til feil — se Streng modus.

Streng modus

--strict kombinerer to opptrappinger bak ett enkelt valg: ethvert regelbrudd med "severity": "warning" får bygget til å mislykkes (feltet warningsExceeded i JSON-utdataene er true og pass er false), og det får også bygget til å mislykkes separat når briefingWarnings, suppressionWarnings eller unparsedAdrs ikke er tomme — de veiledende diagnostikkene ovenfor, som i utgangspunktet aldri påvirker pass. Feltet strictAdvisoryExceeded i JSON-utdataene er true når sistnevnte tilstand utløste feilen.

Diagnostikken for sammendragsbudsjett og utolkede ADR-er dekker hele korpuset, ikke bare reglene: den samles inn og håndheves selv når ingen ADR med rules: true finnes, så et ADR-korpus med bare prosa mislykkes fortsatt med --strict ved en overskridelse av sammendragsbudsjettet eller en utolkbar ADR-fil. Undertrykkelsesadvarsler stammer derimot fra regelbrudd og oppstår bare når regler kjøres.

--strict gjelder også for archgate review-context og archgate adr sync. Se konfigurasjonsreferansen for hele skjemaet.

For å unngå å sende --strict ved hver kjøring, sett en prosjektstandard i .archgate/config.json:

{ "strict": true }

Det finnes ingen --no-strict-flagg: --strict på kommandolinjen kan bare slå på streng modus over et fraværende eller false konfigurasjonsstandard — den kan ikke slå av en konfigurert strict: true.

JSON-utdataformat

Når --output json brukes, er utdataene et enkelt JSON-objekt.

results inneholder bare regler som har noe å rapportere: feil, regelfeil og alle regler med brudd (inkludert regler som bare gir advarsler eller informasjon). Regler som består uten brudd, utelates — oppføringen deres ville bare gjenta statisk ADR-tekst, og i store prosjekter dominerer disse oppføringene utdataene. Tellerne total og passed rapporterer fortsatt nøyaktig hvor mange regler som ble kjørt og bestått. Bruk --verbose for å inkludere alle regler i results.

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": false,
  "strictAdvisoryExceeded": false,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "line": 1,
          "endLine": 1,
          "endColumn": 42,
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}

Bruddfelter

Felt	Type	Beskrivelse
message	string	Hva bruddet er
file	string?	Relativ filsti
line	number?	Startlinje (1-basert)
endLine	number?	Sluttlinje (1-basert) — for presis editor-utheving
endColumn	number?	Sluttkolonne (0-basert) — for presis editor-utheving
fix	string?	Foreslått fiks (kun veiledning)
severity	string	"error", "warning" eller "info"

Blokkerte regelfiler

Når en regelfil blokkeres av sikkerhetsskanneren (f.eks. bruker Bun.spawn()) eller en tilhørende .rules.ts-fil mangler, vises resultatet i JSON-utdataene med status: "error" og ruleId: "security-scan". Brudd inkluderer den eksakte filen og linjen til den blokkerte koden (eller rules: true-linjen i ADR-en for manglende tilhørende filer).