ADR-skjema

Hver Archgate ADR er en Markdown-fil lagret i .archgate/adrs/ med YAML frontmatter som definerer beslutningens identitet og omfang. Denne siden dokumenterer frontmatter-skjemaet, Markdown-seksjonsstrukturen og valideringsatferd.

Frontmatter-skjema

YAML frontmatter-blokken ligger mellom ----skilletegn øverst i filen.

---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---

Felt

| Felt | Type | Påkrevd | Beskrivelse | | ------------------ | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Ja | Unik identifikator. Må være ikke-tom. Konvensjon: PREFIX-NNN (f.eks. ARCH-001). | | title | string | Ja | Lesbar tittel på beslutningen. Må være ikke-tom. | | domain | string | Ja | Et registrert domenenavn i kebab-case med små bokstaver. Innebygde: backend, frontend, data, architecture, general. Egendefinerte domener registreres via archgate adr domain add. | | rules | boolean | Ja | Om denne ADR-en har en tilhørende .rules.ts-fil med automatiserte kontroller. | | files | string[] | Nei | Globmønstre som avgrenser hvilke filer reglene gjelder for. | | respectGitignore | boolean | Nei | Om .gitignore-filer skal filtreres bort. Standard er true. |

id

ADR-identifikatoren. Etter konvensjon brukes domeneprefikset etterfulgt av et null-utfylt sekvensnummer (f.eks. ARCH-001, BE-003). Kommandoen archgate adr create genererer ID-er automatisk.

Enhver ikke-tom streng er gyldig, men å følge prefikskonvensjonen holder ADR-ene organisert og sorterbare.

title

Et kort, beskrivende navn for den arkitektoniske beslutningen. Vises i archgate adr list-utdata og brukes som overskrift når AI-agenter refererer til ADR-en.

domain

Grupperer relaterte ADR-er sammen. Domenet bestemmer også ID-prefikset som brukes av archgate adr create.

Prosjekter kan utvide det innebygde settet med egendefinerte domener via archgate adr domain add. Egendefinerte domene-til-prefiks-tilordninger lagres i .archgate/config.json og slås sammen med de innebygde ved lesing.

rules

Sett til true når denne ADR-en har en tilhørende .rules.ts-fil. Når archgate check kjører, hopper den over ADR-er der rules er false.

files

En valgfri matrise med globmønstre som avgrenser regelens fildekning. Når den er til stede, inneholder ctx.scopedFiles i regelfilen kun filer som matcher disse mønstrene. Når den er fraværende, er alle prosjektfiler i omfang.

files: ["src/commands/**/*.ts"]

Flere mønstre kan spesifiseres:

files: ["src/api/**/*.ts", "src/middleware/**/*.ts"]

respectGitignore

Styrer om .gitignore-filer ekskluderes fra ctx.scopedFiles, ctx.glob() og ctx.grepFiles(). Standard er true når feltet utelates — gitignorerte filer (f.eks. node_modules/, dist/) filtreres automatisk bort.

Sett til false når en regel med vilje trenger å inspisere ignorerte filer, for eksempel for å sjekke strukturen på byggeutdata:

respectGitignore: false
files: ["dist/**/*.js"]

Når respectGitignore er false, inkluderes alle filer som matcher files-globene uavhengig av .gitignore-regler. Når man ikke er inne i et git-repository, har dette feltet ingen effekt — alle matchede filer inkluderes.

---

Domeneprefikser

Hvert domene tilordnes et prefiks som brukes i ADR-ID-konvensjonen.

Innebygde domener

| Domene | Prefiks | Eksempel-ID | | -------------- | ------- | ----------- | | backend | BE | BE-001 | | frontend | FE | FE-001 | | data | DATA | DATA-001 | | architecture | ARCH | ARCH-001 | | general | GEN | GEN-001 |

Kommandoen archgate adr create bruker denne tilordningen til å autogenerere ID-er.

Egendefinerte domener

Prosjekter kan registrere ytterligere domene-til-prefiks-tilordninger via archgate adr domain add. Når de er registrert, oppfører egendefinerte domener seg som innebygde: archgate adr create --domain <name> autogenererer ID-er med det tilhørende prefikset, og ADR-er med egendefinerte domener parses uten problemer.

Se konseptsiden for domener for veiledning om når du bør introdusere et egendefinert domene.

---

Konvensjon for filnavn

ADR-filer følger en navnekonvensjon som koder inn ID-en og en lesbar slug:

{ID}-{slug}.md              # Dokumentet
{ID}-{slug}.rules.ts        # Den tilhørende regelfilen (valgfri)

For eksempel:

ARCH-001-command-structure.md
ARCH-001-command-structure.rules.ts

Slugen er en kebab-case-versjon av tittelen, autogenerert av archgate adr create.

---

Markdown-seksjoner

Etter frontmatter følger ADR-kroppen en standard seksjonsstruktur. Selv om Archgate ikke påtvinger spesifikke seksjoner, anbefales følgende struktur for konsistens.

Context

Beskriver problemet eller situasjonen som utløste beslutningen. Inkluder alternativer som ble vurdert og hvorfor de ble forkastet.

## Context

The CLI returns errors in inconsistent formats. Some commands print raw
stack traces, others print nothing, and a few use `console.error()` with
custom formatting.

**Alternatives considered:**

- **No standard** -- Let each command handle errors its own way. Simple
  but leads to an inconsistent user experience.
- **Try/catch wrapper** -- A global try/catch at the CLI entry point.
  Loses context about which command failed.

Decision

Angir selve beslutningen og dens viktigste begrensninger. Dette er den primære seksjonen AI-agenter leser før de skriver kode.

## Decision

All commands MUST use `logError()` from `src/helpers/log.ts` for error
output. Commands MUST NOT call `console.error()` directly.

Do’s and Don’ts

Konkret, handlingsrettet veiledning delt i to underseksjoner. Disse fungerer som en hurtigreferanse-sjekkliste for utviklere og AI-agenter.

## Do's and Don'ts

### Do

- Use `logError(message, detail?)` for all error output
- Include a suggested fix in the detail parameter when possible
- Exit with code 1 for user errors, code 2 for internal errors

### Don't

- Don't call `console.error()` directly in command files
- Don't print stack traces to users
- Don't exit without printing an error message first

Consequences

Delt i tre underseksjoner som dokumenterer avveininger.

## Consequences

### Positive

- Consistent error formatting across all commands
- Machine-parseable error output when combined with `--json`

### Negative

- Requires importing `logError` in every command file
- Cannot use built-in error formatting from libraries

### Risks

- New contributors may use `console.error()` by habit. Mitigated by the
  automated rule that scans for direct `console.error()` calls.

Compliance and Enforcement

Beskriver hvordan beslutningen håndheves gjennom automatiserte regler og manuell gjennomgang.

## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** ARCH-002/no-console-error: Scans command files for
  `console.error()` calls. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. Error messages are actionable and include context
2. Exit codes match the error type (1 for user, 2 for internal)

References

Lenker til relaterte ADR-er, ekstern dokumentasjon eller designdokumenter.

## References

- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md)
- [Node.js process.exit documentation](https://nodejs.org/api/process.html#processexitcode)

---

Tilhørende regelfil

Når rules: true, leter Archgate etter en tilhørende fil med samme navn men .rules.ts-endelse.

ARCH-002-error-handling.md          # rules: true i frontmatter
ARCH-002-error-handling.rules.ts    # tilhørende regelfil

Regelfilen må eksportere et standard RuleSet ved hjelp av et vanlig objekt med satisfies RuleSet:

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

export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from src/helpers/log and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Se Rule API for den komplette TypeScript API-referansen.

---

Validering

YAML frontmatter valideres ved parsetidspunkt ved hjelp av et Zod-skjema. Ugyldig frontmatter forårsaker en parsefeil med en beskrivende melding.

Påkrevde felt

Hvis et påkrevd felt mangler, feiler ADR-parsingen:

Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: Required

Ugyldig domeneformat

Hvis domain ikke er en gyldig kebab-case-identifikator (f.eks. har store bokstaver eller mellomrom):

Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops')

Merk: parseren aksepterer ethvert navn som matcher kebab-case-mønsteret. Om et spesifikt navn er “kjent” for prosjektet — og dermed har et prefiks som archgate adr create kan bruke — avhenger av det innebygde settet pluss eventuelle egendefinerte domener registrert via archgate adr domain add. Å opprette en ADR med et uregistrert domenenavn feiler med en “Unknown ADR domain”-feil som foreslår å kjøre archgate adr domain add.

Typefeil

Hvis rules er en streng i stedet for en boolean:

Invalid ADR frontmatter in ARCH-001-example.md:
  - rules: Expected boolean, received string

ADR-er som feiler validering, hoppes over av archgate check og rapporteres som feil.