depa-codument 0.4.1

package/src/cli/modeling/schema.ts

@@ -0,0 +1,160 @@
+import type { XnlNode, DataElementNode, TextElementNode } from 'xnl-core';
+import { isDataElement, readNodeId, type ModelingRegistry } from './registry';
+
+/**
+ * Node schema validation for the modeling registry: kind vocabulary, minimal
+ * required representations per kind, fact-source metadata, and namespaced ids.
+ * See std/spec/modeling-node-schema.md.
+ */
+
+export const FACT_GRADES = [
+  'authoritative_fact',
+  'domain_canonical_event',
+  'runtime_control_fact',
+  'append_only_journal',
+  'checkpoint_snapshot',
+  'derived_projection_cache',
+  'surface_view',
+] as const;
+
+/** Kernel (cross-domain) bare-tag kinds. Shell kinds are namespaced (`plane:kind`). */
+export const KERNEL_KINDS = [
+  'entity',
+  'object',
+  'enum',
+  'state-machine',
+  'module',
+  'capsule',
+  'component',
+  'port',
+  'actor',
+  'policy',
+] as const;
+
+type Element = DataElementNode | TextElementNode;
+
+function isElement(node: XnlNode | undefined): node is Element {
+  return Boolean(
+    node && typeof node === 'object' &&
+      ((node as Element).kind === 'DataElement' || (node as Element).kind === 'TextElement'),
+  );
+}
+
+function bodyChildren(node: DataElementNode): Element[] {
+  return (node.body ?? []).filter(isElement);
+}
+
+/** Direct child element tags (Data + Text). */
+function childTags(node: DataElementNode): Set<string> {
+  return new Set(bodyChildren(node).map((c) => c.tag));
+}
+
+/** Whether any descendant element has the given tag. */
+function hasChildDeep(node: DataElementNode, tag: string): boolean {
+  for (const child of bodyChildren(node)) {
+    if (child.tag === tag) return true;
+    if (isDataElement(child) && hasChildDeep(child, tag)) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether a component declares the given IO slot, accepting either the canonical
+ * bare tag (`<runtime>` …) or the role-tagged compat form (`<types role="runtime">`).
+ * Bare tags are spec-recommended; role-tagged is accepted-but-discouraged.
+ */
+function hasIoSlot(node: DataElementNode, slot: string): boolean {
+  for (const child of bodyChildren(node)) {
+    if (child.tag === slot) return true;
+    if (child.tag === 'types') {
+      const role = child.metadata?.['role'];
+      if (typeof role === 'string' && role === slot) return true;
+    }
+  }
+  return false;
+}
+
+function hasMeta(node: DataElementNode, key: string): boolean {
+  const v = node.metadata?.[key];
+  return v !== undefined && v !== null && v !== '';
+}
+
+function metaString(node: DataElementNode, key: string): string | undefined {
+  const v = node.metadata?.[key];
+  return typeof v === 'string' ? v : undefined;
+}
+
+export function nodeKind(node: DataElementNode): string | undefined {
+  return metaString(node, 'kind');
+}
+
+/** Validate one modeling node; returns a list of error messages (empty = ok). */
+export function validateModelingNode(node: XnlNode): string[] {
+  const errors: string[] = [];
+  if (!isDataElement(node)) return errors; // non-element top-level content is ignored
+  const id = readNodeId(node);
+  const where = id ? `#${id}` : `<${node.tag}>`;
+
+  if (!id) {
+    errors.push(`${where}: node has no id (use a namespaced #<context>.<name>)`);
+  }
+
+  const kind = nodeKind(node);
+  if (!kind) {
+    errors.push(`${where}: missing 'kind'`);
+    return errors;
+  }
+  const isShell = kind.includes(':');
+  if (!isShell && !(KERNEL_KINDS as readonly string[]).includes(kind)) {
+    errors.push(`${where}: unknown kernel kind '${kind}' (use a known kernel kind or a namespaced shell kind)`);
+  }
+
+  const tags = childTags(node);
+  const req = (cond: boolean, msg: string) => {
+    if (!cond) errors.push(`${where} (kind=${kind}): ${msg}`);
+  };
+
+  switch (kind) {
+    case 'entity':
+    case 'object':
+      req(tags.has('types'), 'entity requires a <types> representation');
+      req(hasMeta(node, 'fact_grade'), 'entity requires fact_grade');
+      req(hasMeta(node, 'single_writer'), 'entity requires single_writer');
+      break;
+    case 'enum':
+      req(tags.has('types'), 'enum requires a <types> representation');
+      break;
+    case 'state-machine':
+      req(hasChildDeep(node, 'mermaid'), 'state-machine requires a <mermaid> diagram');
+      break;
+    case 'module':
+    case 'capsule':
+      req(hasMeta(node, 'depends_on'), 'module requires depends_on');
+      req(tags.has('capsule-tree'), 'module requires a <capsule-tree>');
+      break;
+    case 'component':
+      for (const slot of ['runtime', 'input', 'config', 'output']) {
+        req(hasIoSlot(node, slot), `component requires a <${slot}> block`);
+      }
+      break;
+    // port/actor/policy: lenient (kind valid is enough for now)
+    default:
+      break;
+  }
+
+  const fg = metaString(node, 'fact_grade');
+  if (fg !== undefined && !(FACT_GRADES as readonly string[]).includes(fg)) {
+    errors.push(`${where}: invalid fact_grade '${fg}'`);
+  }
+
+  return errors;
+}
+
+/** Validate every node in a registry. */
+export function validateModelingRegistry(registry: ModelingRegistry): string[] {
+  const errors: string[] = [];
+  for (const nodes of registry.files.values()) {
+    for (const node of nodes) errors.push(...validateModelingNode(node));
+  }
+  return errors;
+}

package/src/cli/modeling/validate.ts

@@ -0,0 +1,282 @@
+import * as path from 'path';
+import type { XnlNode, DataElementNode, AttributeMap } from 'xnl-core';
+import {
+  loadModelingRegistrySafe,
+  isDataElement,
+  readNodeId,
+  idNamespace,
+  nodeName,
+  type ModelingRegistry,
+} from './registry';
+import { validateModelingNode } from './schema';
+
+/**
+ * Modeling validation engine. Checks every modeling `.xnl` file across three
+ * layers — XNL syntax, node-schema semantics, hierarchy/reference consistency —
+ * and returns author-friendly findings instead of throwing.
+ *
+ * See std/spec/modeling-node-schema.md (§5 id namespace, §6 references) and the
+ * track decisions: id↔path alignment is lenient (context must match; plane
+ * prefix optional but must match if present); `modeling://` dangling refs are
+ * errors; `behavior://` is syntax-only; a `domain` plane must exist; unknown
+ * derived planes are warnings; duplicate ids are findings, not throws.
+ */
+
+export type ValidateLayer = 'syntax' | 'schema' | 'hierarchy';
+export type ValidateSeverity = 'error' | 'warning';
+
+export interface ValidateFinding {
+  /** Path relative to the validated dir. */
+  file: string;
+  /** 1-based line, when known. */
+  line?: number;
+  layer: ValidateLayer;
+  severity: ValidateSeverity;
+  message: string;
+}
+
+export type ValidateMode = 'registry' | 'deltas';
+
+export interface ValidateOptions {
+  /**
+   * `registry` (default): files live at `<plane>/<context>/...index.xnl` — path
+   * context is the second path segment. `deltas`: files live at
+   * `<plane>/<context>.xnl` (a track's `modeling_deltas/`) — path context is the
+   * file basename without `.xnl`.
+   */
+  mode?: ValidateMode;
+}
+
+/** Planes with a fixed meaning; anything else is treated as an open derived plane. */
+const KNOWN_PLANES = new Set(['domain', 'backend', 'surface', 'cli', 'agent']);
+
+/** Reference scheme prefixes we recognise in metadata values. */
+const MODELING_SCHEME = 'modeling://';
+const BEHAVIOR_SCHEME = 'behavior://';
+
+interface PathLoc {
+  plane: string;
+  context: string;
+}
+
+/** Derive `<plane>/<context>` from a registry / delta file path. */
+function pathLoc(relFile: string, mode: ValidateMode): PathLoc {
+  const segs = relFile.split(path.sep).filter(Boolean);
+  const plane = segs[0] ?? '';
+  if (mode === 'deltas') {
+    // `<plane>/<context>.xnl`
+    const base = segs[1] ?? '';
+    const context = base.replace(/\.xnl$/i, '');
+    return { plane, context };
+  }
+  // registry: `<plane>/<context>/...`
+  const context = segs[1] ?? plane;
+  return { plane, context };
+}
+
+/** Collect every `modeling://` / `behavior://` string anywhere in a metadata map. */
+function collectRefs(meta: AttributeMap | undefined): string[] {
+  const out: string[] = [];
+  const visit = (v: unknown): void => {
+    if (typeof v === 'string') {
+      if (v.startsWith(MODELING_SCHEME) || v.startsWith(BEHAVIOR_SCHEME)) out.push(v);
+      return;
+    }
+    if (Array.isArray(v)) {
+      for (const item of v) visit(item);
+      return;
+    }
+    if (v && typeof v === 'object') {
+      // XnlWord or nested attribute map — scan its values.
+      for (const item of Object.values(v as Record<string, unknown>)) visit(item);
+    }
+  };
+  if (meta) for (const v of Object.values(meta)) visit(v);
+  return out;
+}
+
+/** Validate id↔path alignment for one node; returns hierarchy findings. */
+function checkIdPathAlignment(
+  node: DataElementNode,
+  relFile: string,
+  loc: PathLoc,
+): ValidateFinding[] {
+  const findings: ValidateFinding[] = [];
+  const id = readNodeId(node);
+  if (!id) return findings; // schema layer already flags a missing id
+  const ns = idNamespace(id);
+  const segs = ns ? ns.split('.') : [];
+
+  if (segs.length === 0) {
+    findings.push({
+      file: relFile,
+      layer: 'hierarchy',
+      severity: 'error',
+      message: `#${id}: id has no namespace context segment; expected '<context>.<name>' with context '${loc.context}'`,
+    });
+    return findings;
+  }
+
+  const idContext = segs[segs.length - 1];
+  if (idContext !== loc.context) {
+    findings.push({
+      file: relFile,
+      layer: 'hierarchy',
+      severity: 'error',
+      message: `#${id}: id context '${idContext}' does not match path context '${loc.context}' (${relFile})`,
+    });
+  }
+
+  // plane prefix optional; if present (namespace has >= 2 segments) it must match.
+  if (segs.length >= 2) {
+    const idPlane = segs[segs.length - 2];
+    if (idPlane !== loc.plane) {
+      findings.push({
+        file: relFile,
+        layer: 'hierarchy',
+        severity: 'error',
+        message: `#${id}: id plane prefix '${idPlane}' does not match path plane '${loc.plane}' (${relFile})`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/** Validate modeling:///behavior:// references for one node against the uri set. */
+function checkReferences(
+  node: DataElementNode,
+  relFile: string,
+  knownUris: Set<string>,
+): ValidateFinding[] {
+  const findings: ValidateFinding[] = [];
+  const id = readNodeId(node);
+  const where = id ? `#${id}` : `<${node.tag}>`;
+  for (const ref of collectRefs(node.metadata)) {
+    if (ref.startsWith(MODELING_SCHEME)) {
+      if (!knownUris.has(ref)) {
+        findings.push({
+          file: relFile,
+          layer: 'hierarchy',
+          severity: 'error',
+          message: `${where}: dangling reference '${ref}' (no such node in the registry index)`,
+        });
+      }
+    } else if (ref.startsWith(BEHAVIOR_SCHEME)) {
+      // Syntax-only: must look like behavior://<capability>/.../<id>; existence unverified.
+      const rest = ref.slice(BEHAVIOR_SCHEME.length);
+      if (rest.split('/').filter(Boolean).length < 2) {
+        findings.push({
+          file: relFile,
+          layer: 'hierarchy',
+          severity: 'error',
+          message: `${where}: malformed behavior reference '${ref}' (expected behavior://<capability>/...)`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Check plane legality: domain must exist; unknown = warning. Operates over every
+ * discovered file path (including ones that failed to parse), so a syntax error in
+ * a `domain/...` file does not also produce a spurious "missing domain plane".
+ */
+function checkPlanes(relFiles: Iterable<string>, mode: ValidateMode): ValidateFinding[] {
+  const findings: ValidateFinding[] = [];
+  const planes = new Set<string>();
+  for (const relFile of relFiles) {
+    planes.add(pathLoc(relFile, mode).plane);
+  }
+
+  if (!planes.has('domain')) {
+    findings.push({
+      file: '.',
+      layer: 'hierarchy',
+      severity: 'error',
+      message: `modeling registry must contain a 'domain' plane (found planes: ${[...planes].sort().join(', ') || '(none)'})`,
+    });
+  }
+
+  for (const plane of planes) {
+    if (plane && !KNOWN_PLANES.has(plane)) {
+      findings.push({
+        file: '.',
+        layer: 'hierarchy',
+        severity: 'warning',
+        message: `unknown derived plane '${plane}' (open derived planes are allowed; verify it is intentional)`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Validate a modeling tree (registry by default, or a track's `modeling_deltas/`
+ * tree when `mode: 'deltas'`). Returns all findings across the three layers;
+ * never throws on author errors.
+ */
+export function validateModelingTree(dir: string, opts: ValidateOptions = {}): ValidateFinding[] {
+  const mode: ValidateMode = opts.mode ?? 'registry';
+  const findings: ValidateFinding[] = [];
+
+  const { registry, issues } = loadModelingRegistrySafe(dir);
+
+  // Layer 1 (syntax) + duplicate id (hierarchy), from the safe loader.
+  for (const issue of issues) {
+    if (issue.kind === 'syntax') {
+      findings.push({
+        file: issue.file,
+        line: issue.line,
+        layer: 'syntax',
+        severity: 'error',
+        message: issue.message,
+      });
+    } else {
+      findings.push({
+        file: issue.file,
+        layer: 'hierarchy',
+        severity: 'error',
+        message: issue.message,
+      });
+    }
+  }
+
+  // Known uris for reference resolution. Recompute from the path layout so delta
+  // mode (`<plane>/<context>.xnl`) and registry mode agree on the canonical
+  // `modeling://<plane>/<context>/<name>` form.
+  const knownUris = new Set<string>();
+  for (const [relFile, nodes] of registry.files) {
+    const loc = pathLoc(relFile, mode);
+    for (const node of nodes) {
+      const id = readNodeId(node);
+      if (!id || !isDataElement(node)) continue;
+      knownUris.add(`${MODELING_SCHEME}${loc.plane}/${loc.context}/${nodeName(id)}`);
+    }
+  }
+
+  // Layer 2 (schema) + Layer 3 per-node (alignment + references).
+  for (const [relFile, nodes] of registry.files) {
+    const loc = pathLoc(relFile, mode);
+    for (const node of nodes) {
+      if (!isDataElement(node)) continue;
+      for (const msg of validateModelingNode(node)) {
+        findings.push({ file: relFile, layer: 'schema', severity: 'error', message: msg });
+      }
+      findings.push(...checkIdPathAlignment(node, relFile, loc));
+      findings.push(...checkReferences(node, relFile, knownUris));
+    }
+  }
+
+  // Layer 3 cross-file: plane legality, over all discovered files (parsed ones
+  // plus syntax-failed ones, so a broken domain file still counts as a domain plane).
+  const planeFiles = new Set<string>(registry.files.keys());
+  for (const issue of issues) if (issue.kind === 'syntax') planeFiles.add(issue.file);
+  findings.push(...checkPlanes(planeFiles, mode));
+
+  return findings;
+}
+
+export { idNamespace };