From bbbf2fc258fce274591ce67b5be26fc183ce6643 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Nov 2026 11:22:51 +0000
Subject: [PATCH] feat: type validation issue kinds as ValidationIssueKind

FileValidationIssue.kind was a string. VALIDATION_ISSUE_KINDS lists the
kinds at runtime and ValidationIssueKind derives from it, so consumers
such as map-views can build enums from it instead of restating the list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpfuisYsa8kb3fSwLCX
---
 docs/api.md  |  2 +-
 src/api.ts   |  2 ++
 src/types.ts | 17 +++++++++++++++--
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index fb086f3..04b5325 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -31,7 +31,7 @@ see [architecture.md](architecture.md#information-flow) for that flow.
 
 `ValidationResult.ruleViolations` carries each violation's effective `severity` (`error`, `warning` or `info`). Only `error` severity violations should be treated as failures.
 
-`nodeIssues(result)` gathers every result about a node into one map per node: schema, duplicate id, broken link, hierarchy, rule, gated and unresolved content link issues, each keyed by a composite id such as `rule:<id>` and carrying its `kind`, `message` and `severity`. Read `severity` rather than deriving it from `kind`. Pass `{ includeGated }` as validation ran, so a gated node's note says whether its rules were evaluated. Rule violations without a node and parse issues stay in their own parts of the result. `validateFile` returns one node's map as `issues`.
+`nodeIssues(result)` gathers every result about a node into one map per node: schema, duplicate id, broken link, hierarchy, rule, gated and unresolved content link issues, each keyed by a composite id such as `rule:<id>` and carrying its `kind`, `message` and `severity`. `kind` is a `ValidationIssueKind`, and `VALIDATION_ISSUE_KINDS` lists every kind at runtime. Read `severity` rather than deriving it from `kind`. Pass `{ includeGated }` as validation ran, so a gated node's note says whether its rules were evaluated. Rule violations without a node and parse issues stay in their own parts of the result. `validateFile` returns one node's map as `issues`.
 
 Each `ValidationResult` entry about a node carries its `nodeId`, and, where the entry is tied to a location, an optional `source` (`{ file, line?, column? }`). `duplicateErrors` lists a `sources` location for each node that shares the `id`. See [Validation results and nodes](concepts.md#validation-results-and-nodes).
 
diff --git a/src/api.ts b/src/api.ts
index cf05218..1ca65f2 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -83,6 +83,8 @@ export type {
   SpaceContext,
   UnresolvedRef,
   ValidateFileOutput,
+  ValidationIssueKind,
 } from './types';
+export { VALIDATION_ISSUE_KINDS } from './types';
 export type { ValidationResult } from './validate';
 export { nodeIssues, validateFile, validateSpace } from './validate';
diff --git a/src/types.ts b/src/types.ts
index e08deb8..d072e0f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -274,9 +274,22 @@ export type SpaceContext = {
   configDir: string;
 };
 
+/** The checks a validation issue can come from. */
+export const VALIDATION_ISSUE_KINDS = [
+  'schema',
+  'duplicate',
+  'broken-link',
+  'hierarchy',
+  'rule',
+  'gated',
+  'content-link',
+] as const;
+
+export type ValidationIssueKind = (typeof VALIDATION_ISSUE_KINDS)[number];
+
 export interface FileValidationIssue {
-  /** The check it came from: `schema`, `duplicate`, `broken-link`, `hierarchy`, `rule`, `gated` or `content-link`. */
-  kind: string;
+  /** The check it came from. */
+  kind: ValidationIssueKind;
   message: string;
   /** How serious the issue is; consumers read it rather than infer it from `kind`. */
   severity: RuleSeverity;