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>;
  ast(path: string, language: AstLanguage): Promise<AstNode>;
  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>;
};

ast

ast(
  path: string,
  language: "typescript" | "javascript" | "python" | "ruby"
): Promise<AstNode>;

Parse en kildefil til dens språknative AST. Stien er relativ til prosjektroten og går gjennom samme sandkasse som readFile. TypeScript og JavaScript parses i prosessen; Python og Ruby parses ved å starte systemtolkens egen AST-fasilitet fra standardbiblioteket som en underprosess. Formen på det returnerte treet varierer per språk — se AstNode.

const program = await ctx.ast("src/cli.ts", "typescript");
for (const node of program.body) {
  console.log(node.type);
}

ast() kaster ved feil — den returnerer aldri null:

• Parsefeil: filen kan ikke parses som det forespurte språket. Feilmeldingen inkluderer parserens diagnostikk.
• Manglende tolk (kun python/ruby): ingen egnet tolk ble funnet på PATH.
• Usannsynlig input: filens filendelse samsvarer ikke med det forespurte språket (f.eks. kaster ctx.ast("config.json", "python") før noen tolk startes).

En kastet feil er isolert til regelen som feiler: andre regler og ADR-er i samme sjekk-kjøring fortsetter som normalt, og feilen vises som en regelkjøringsfeil med avslutningskode 2 (til forskjell fra avslutningskode 1 for brudd). De to kastetilfellene kan skilles fra hverandre på meldingsteksten, slik at sjekkutdataene skiller “dette miljøet kan ikke kjøre denne regelen” fra “denne filen har en syntaksfeil”.

Advarsel

Python- og Ruby-regler krever at den tilhørende tolken (python3/python, ruby) finnes på PATH overalt der archgate check kjører — på hver utviklermaskin og i CI. TypeScript- og JavaScript-parsing er innebygd i Archgate og trenger ingen tolk.

---

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

---

AstNode

Returnert av ctx.ast(). Formen er språknativ og bevisst ikke enhetlig på tvers av språk — hvert språk returnerer sitt eget standard AST-vokabular, så en regel som inspiserer Python-kode jobber mot en annen grammatikk enn en som inspiserer TypeScript.

type AstLanguage = "typescript" | "javascript" | "python" | "ruby";
type AstNode = Record<string, unknown> | unknown[];

Språk	Underliggende parser	Returnert form
typescript	meriyah, i prosessen, etter at TypeScript er transpilert bort med Bun.Transpiler	ESTree Program med loc-posisjonsinfo. Typenivå-syntaks (interface, typealiaser, export type { ... } from) fjernes før parsing — en fil som bare inneholder setninger på typenivå parses til en tom Program-body. loc-posisjoner refererer til det transpilerte resultatet, ikke den opprinnelige .ts-filen — fjernede typenivå-setninger, kommentarer og tomme linjer gjør at linjenumrene forskyves, så finn konstruksjonen på nytt i den opprinnelige kildekoden (f.eks. ctx.readFile() pluss indexOf) før du rapporterer en line, eller utelat line helt; loc er nøyaktig mot kildekoden bare for javascript
javascript	meriyah, i prosessen	ESTree Program med loc-posisjonsinfo
python	Pythons ast-modul fra standardbiblioteket, via systemtolken	JSON-serialiserte ast-noder: { "_type": "Module", "body": [...] } — hver node har _type, nodens egne felt og posisjonene lineno / col_offset
ruby	Rubys Ripper fra standardbiblioteket, via systemtolken	Nestede Ripper.sexp-matriser: ["program", [["command", ...]]] med [line, column]-posisjonspar innebygd i token-oppføringene

Se Strukturelle sjekker med ctx.ast() for et komplett eksempel på en regel per språk.

---

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.