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). Når --staged brukes, inneholder den kun stagede filer. Når --base <ref> brukes, inneholder den alle filer som er endret siden den referansen. 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.