Rule API

Archgate-regler er TypeScript-filer som eksporterer et vanlig objekt typet med satisfies RuleSet. Hver regel mottar en RuleContext med verktøy for å søke i filer, lese innhold og rapportere brudd.

RuleSet

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "my-rule-id": {
      description: "Human-readable description of what this rule checks",
      severity: "error", // optional, defaults to "error"
      async check(ctx) {
        // Rule logic here
      },
    },
  },
} satisfies RuleSet;

En regelfil eksporterer som standard et vanlig objekt med en rules-post indeksert etter regel-ID. Nøklene blir regel-ID-ene som vises i sjekkutdata og bruddrapporter. Annotasjonen satisfies RuleSet gir typekontroll uten å pakke inn i et funksjonskall.

type RuleSet = { rules: Record<string, RuleConfig> };

---

RuleConfig

Hver regel i posten må samsvare med RuleConfig-grensesnittet.

interface RuleConfig {
  description: string;
  severity?: Severity;
  check: (ctx: RuleContext) => Promise<void>;
}

Felt	Type	Påkrevd	Beskrivelse
description	string	Ja	Lesbar beskrivelse som vises i sjekkutdata
severity	Severity	Nei	Standard alvorlighetsgrad for brudd. Standard er "error"
check	(ctx: RuleContext) => Promise<void>	Ja	Asynkron funksjon som inneholder regellogikken

---

RuleContext

check-funksjonen mottar et RuleContext-objekt med prosjekttilstand og hjelpemetoder.

interface RuleContext {
  projectRoot: string;
  scopedFiles: string[];
  changedFiles: string[];
  glob(pattern: string): Promise<string[]>;
  grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;
  grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;
  readFile(path: string): Promise<string>;
  readJSON(path: string): Promise<unknown>;
  report: RuleReport;
}

Egenskaper

projectRoot

projectRoot: string;

Absolutt sti til prosjektets rotkatalog (der .archgate/ ligger).

scopedFiles

scopedFiles: string[];

Filer som matcher ADR-ens files-globmønstre fra frontmatter. Hvis ADR-en ikke har et files-felt, inneholder denne alle prosjektfiler. Bruk denne som den primære fillisten for regelkontrollene dine.

changedFiles

changedFiles: string[];

Filer som har blitt endret ifølge git. Som standard fylles denne automatisk med branch-diffen mot den detekterte basisgrenen (f.eks. origin/main) pluss eventuelle ikke-committede endringer i arbeidstreet (stagede, ustagede og usporede ikke-ignorerte filer). Når --staged brukes, inneholder den kun stagede filer. Når --base <ref> brukes, inneholder den alle filer som er endret siden den referansen pluss ikke-committede endringer i arbeidstreet. Tom når basisdeteksjon feiler eller ingen endringer finnes. Bruk denne til å bygge regler for avhengigheter mellom filer (f.eks. “hvis fil A endret seg, må fil B også endres”).

report

report: RuleReport;

Rapporteringsgrensesnittet for å registrere brudd, advarsler og informasjonsmeldinger. Se RuleReport nedenfor.

Metoder

glob

glob(pattern: string): Promise<string[]>;

Finn filer som matcher et globmønster relativt til prosjektroten. Returnerer en matrise med filstier. Filer som ignoreres av .gitignore er ekskludert som standard. Sett respectGitignore: false i ADR-ens frontmatter for å inkludere dem.

const testFiles = await ctx.glob("tests/**/*.test.ts");

grep

grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;

Søk i en enkelt fil etter linjer som matcher et regulært uttrykk. Returnerer en matrise med GrepMatch-objekter med filsti, linjenummer, kolonne og matchet innhold.

const matches = await ctx.grep(file, /console\.error\(/);

grepFiles

grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;

Søk i flere filer som matcher et globmønster etter linjer som matcher et regulært uttrykk. Kombinerer glob og grep i ett enkelt kall. Filer som ignoreres av .gitignore er ekskludert som standard. Sett respectGitignore: false i ADR-ens frontmatter for å inkludere dem.

const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts");

readFile

readFile(path: string): Promise<string>;

Les innholdet i en fil som en streng. Stien er relativ til prosjektroten.

const content = await ctx.readFile("src/config.ts");

readJSON

readJSON(path: string): Promise<unknown>;

Les og parse en JSON-fil. Stien er relativ til prosjektroten. Returnerer den parsede verdien som unknown — cast til forventet type i regelen din.

const pkg = (await ctx.readJSON("package.json")) as {
  dependencies?: Record<string, string>;
};

---

RuleReport

Rapporteringsgrensesnittet for å registrere sjekkresultater. Hver metode aksepterer et detalobjekt som beskriver problemet.

interface RuleReport {
  violation(detail: ReportDetail): void;
  warning(detail: ReportDetail): void;
  info(detail: ReportDetail): void;
}

violation

report.violation(detail: ReportDetail): void;

Rapporter et regelbrudd. Brudd får sjekken til å feile med avslutningskode 1. Bruk for harde begrensninger som ikke skal merges.

warning

report.warning(detail: ReportDetail): void;

Rapporter en advarsel. Advarsler vises i sjekkutdata, men får ikke sjekken til å feile. Bruk for ikke-blokkerende veiledning.

info

report.info(detail: ReportDetail): void;

Rapporter en informasjonsmelding. Påvirker ikke avslutningskoden for sjekken. Bruk for forslag eller notater.

ReportDetail

Detalobjektet som sendes til violation, warning og info.

interface ReportDetail {
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
}

Felt	Type	Påkrevd	Beskrivelse
message	string	Ja	Lesbar beskrivelse av problemet
file	string	Nei	Filsti der problemet ble funnet
line	number	Nei	Startlinjenummer (1-basert)
endLine	number	Nei	Sluttlinjenummer (1-basert) — for presis uthevning av område i editoren
endColumn	number	Nei	Sluttkolonnenummer (0-basert) — for presis uthevning av område i editoren
fix	string	Nei	Foreslått rettelse eller utbedringstiltak

Når endLine og endColumn er oppgitt, kan editorer (VS Code, Cursor) utheve det nøyaktige uttrykket som bryter regelen, i stedet for hele linjen. Hvis de utelates, utheves hele linjen ved line.

---

GrepMatch

Returnert av ctx.grep() og ctx.grepFiles().

interface GrepMatch {
  file: string;
  line: number;
  column: number;
  content: string;
}

Felt	Type	Beskrivelse
file	string	Prosjektrelativ sti til den matchede filen
line	number	Linjenummer for treffet (1-basert)
column	number	Kolonnenummer for treffet (1-basert)
content	string	Fullt innhold av den matchede linjen

---

Severity

type Severity = "error" | "warning" | "info";

Verdi	Påvirkning på avslutningskode	Beskrivelse
"error"	Forårsaker avslutningskode 1	Hard begrensning, blokkerer sammenslåinger
"warning"	Ingen påvirkning	Ikke-blokkerende veiledning
"info"	Ingen påvirkning	Informasjon, kun forslag

---

ViolationDetail

Den interne representasjonen av et rapportert problem, brukt i sjekkutdata og JSON-resultater.

interface ViolationDetail {
  ruleId: string;
  adrId: string;
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
  severity: Severity;
}

Felt	Type	Beskrivelse
ruleId	string	Regel-ID fra rules-objektnøkkelen
adrId	string	ADR-ID fra frontmatter
message	string	Lesbar beskrivelse
file	string?	Filsti der problemet ble funnet
line	number?	Startlinjenummer (1-basert)
endLine	number?	Sluttlinje (1-basert) — for presis uthevning i editoren
endColumn	number?	Sluttkolonne (0-basert) — for presis uthevning i editoren
fix	string?	Foreslått rettelse
severity	Severity	Effektiv alvorlighetsgrad for dette bruddet

---

Inline undertrykkelse

Brudd kan undertrykkes i kildekoden ved hjelp av archgate-ignore-kommentarer. Motoren håndterer dette automatisk. Regler trenger ingen spesiell logikk.

// archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet, migrering planlagt
import chalk from "chalk";

En begrunnelse er påkrevd. Filnivå-undertrykkelse bruker archgate-ignore-file. Stable flere kommentarer for å undertrykke mer enn én regel på samme linje. Se Opt-out-direktiver for fullstendige detaljer og egendefinerte direktivmønstre.