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)
--json	Maskinlesbar JSON-utdata
--ci	GitHub Actions-annotasjonsformat
--adr <id>	Sjekk kun regler fra en bestemt ADR
--verbose	Vis beståtte regler og tidsinformasjon
--max-warnings <n>	Mislykkes (kode 1) når antallet advarsler overskrider n. Bruk 0 for å mislykkes ved enhver advarsel.

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 advarsler overskred --max-warnings.
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 advarsel som en feil (nyttig i CI):

archgate check --max-warnings 0

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 --json

Hent JSON-utdata for CI-integrasjon:

archgate check --json

Hent GitHub Actions-annotasjoner:

archgate check --ci

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" }

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 --json brukes (som brudd med "severity": "warning").

Som standard endrer advarsler (både diagnostikk og regelrapporterte brudd med "severity": "warning") aldri avslutningskoden. Send --max-warnings <n> for å få archgate check til å avslutte med kode 1 når det totale antallet advarsler overskrider n. --max-warnings 0 mislykkes ved enhver advarsel. Når terskelen overskrides, er feltet warningsExceeded i JSON-utdataene true og pass er false.

JSON-utdataformat

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

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": 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).