@topogram/cli 0.3.34

package/src/validator/per-kind/component.js

@@ -0,0 +1,274 @@
+import {
+  UI_PATTERN_KINDS,
+  UI_REGION_KINDS
+} from "../kinds.js";
+import {
+  blockEntries,
+  getFieldValue,
+  pushError,
+  symbolValues
+} from "../utils.js";
+
+const COMPONENT_CATEGORIES = new Set([
+  "collection",
+  "form",
+  "display",
+  "navigation",
+  "dialog",
+  "feedback",
+  "lookup",
+  "layout",
+  "service"
+]);
+
+const COMPONENT_BEHAVIOR_KINDS = new Set([
+  "selection",
+  "sorting",
+  "filtering",
+  "search",
+  "pagination",
+  "grouping",
+  "drag_drop",
+  "inline_edit",
+  "bulk_action",
+  "optimistic_update",
+  "realtime_update",
+  "keyboard_navigation"
+]);
+
+const COMPONENT_BEHAVIOR_DIRECTIVES = {
+  selection: new Set(["mode", "state", "emits"]),
+  sorting: new Set(["fields", "default"]),
+  filtering: new Set(["fields"]),
+  search: new Set(["fields"]),
+  pagination: new Set(["mode", "page_size"]),
+  grouping: new Set(["fields"]),
+  drag_drop: new Set(["axis", "reorder"]),
+  inline_edit: new Set(["fields", "submit", "emits"]),
+  bulk_action: new Set(["actions", "state", "emits"]),
+  optimistic_update: new Set(["actions", "rollback"]),
+  realtime_update: new Set(["source", "merge"]),
+  keyboard_navigation: new Set(["scope", "shortcuts"])
+};
+
+function tokenValue(token) {
+  return token?.value ?? null;
+}
+
+function tokenValues(token) {
+  if (!token) {
+    return [];
+  }
+  if (token.type === "list") {
+    return token.items.map((item) => item.value).filter((value) => value != null);
+  }
+  const value = tokenValue(token);
+  return value == null ? [] : [value];
+}
+
+function componentPropNames(statement) {
+  return new Set(blockEntries(getFieldValue(statement, "props"))
+    .map((entry) => entry.items[0])
+    .filter((item) => item?.type === "symbol")
+    .map((item) => item.value));
+}
+
+function componentEventNames(statement) {
+  return new Set(blockEntries(getFieldValue(statement, "events"))
+    .map((entry) => entry.items[0])
+    .filter((item) => item?.type === "symbol")
+    .map((item) => item.value));
+}
+
+function validateComponentCategory(errors, statement, fieldMap) {
+  const field = fieldMap.get("category")?.[0];
+  if (!field) {
+    return;
+  }
+
+  if (field.value.type !== "symbol") {
+    pushError(errors, `Field 'category' on component ${statement.id} must be a symbol`, field.loc);
+    return;
+  }
+
+  if (!COMPONENT_CATEGORIES.has(field.value.value)) {
+    pushError(errors, `Invalid component category '${field.value.value}' on component ${statement.id}`, field.loc);
+  }
+}
+
+function validateComponentProps(errors, statement) {
+  for (const entry of blockEntries(getFieldValue(statement, "props"))) {
+    const [name, type, requiredness, ...rest] = entry.items;
+    if (!name || !type || !requiredness) {
+      pushError(errors, `Component ${statement.id} props entries must be '<name> <type> <required|optional> [default <value>]'`, entry.loc);
+      continue;
+    }
+
+    if (name.type !== "symbol" || type.type !== "symbol" || requiredness.type !== "symbol") {
+      pushError(errors, `Component ${statement.id} props entries must start with symbols`, entry.loc);
+      continue;
+    }
+
+    if (requiredness.value !== "required" && requiredness.value !== "optional") {
+      pushError(errors, `Component ${statement.id} prop '${name.value}' must use required or optional`, requiredness.loc);
+    }
+
+    for (let i = 0; i < rest.length; i += 1) {
+      const token = rest[i];
+      if (token.type === "symbol" && token.value === "default") {
+        if (!rest[i + 1]) {
+          pushError(errors, `Component ${statement.id} prop '${name.value}' default is missing a value`, token.loc);
+        }
+        i += 1;
+        continue;
+      }
+      pushError(errors, `Component ${statement.id} prop '${name.value}' has unsupported directive '${token.value}'`, token.loc);
+    }
+  }
+}
+
+function validateComponentEvents(errors, statement, registry) {
+  for (const entry of blockEntries(getFieldValue(statement, "events"))) {
+    const [eventName, shapeRef] = entry.items;
+    if (!eventName || !shapeRef) {
+      pushError(errors, `Component ${statement.id} events entries must be '<event_name> <shape_id>'`, entry.loc);
+      continue;
+    }
+
+    if (eventName.type !== "symbol" || shapeRef.type !== "symbol") {
+      pushError(errors, `Component ${statement.id} events entries must use symbols`, entry.loc);
+      continue;
+    }
+
+    const target = registry.get(shapeRef.value);
+    if (!target) {
+      pushError(errors, `Component ${statement.id} event '${eventName.value}' references missing shape '${shapeRef.value}'`, shapeRef.loc);
+      continue;
+    }
+    if (target.kind !== "shape") {
+      pushError(errors, `Component ${statement.id} event '${eventName.value}' must reference a shape, found ${target.kind} '${target.id}'`, shapeRef.loc);
+    }
+  }
+}
+
+function validateComponentSlots(errors, statement) {
+  for (const entry of blockEntries(getFieldValue(statement, "slots"))) {
+    const [slotName, description] = entry.items;
+    if (!slotName || !description) {
+      pushError(errors, `Component ${statement.id} slots entries must be '<slot_name> <description>'`, entry.loc);
+      continue;
+    }
+
+    if (slotName.type !== "symbol" || (description.type !== "string" && description.type !== "symbol")) {
+      pushError(errors, `Component ${statement.id} slots entries must use a symbol name and string or symbol description`, entry.loc);
+    }
+  }
+}
+
+function validateSymbolList(errors, statement, fieldMap, key, allowed, label) {
+  const field = fieldMap.get(key)?.[0];
+  if (!field) {
+    return;
+  }
+
+  for (const value of symbolValues(field.value)) {
+    if (!allowed.has(value)) {
+      pushError(errors, `Component ${statement.id} ${label} '${value}' is not supported`, field.loc);
+    }
+  }
+}
+
+function validateBehaviorActionReferences(errors, statement, registry, kind, directive, valueToken, eventNames) {
+  for (const actionId of tokenValues(valueToken)) {
+    if (eventNames.has(actionId)) {
+      continue;
+    }
+    const target = registry.get(actionId);
+    if (target?.kind === "capability") {
+      continue;
+    }
+    pushError(
+      errors,
+      `Component ${statement.id} behavior '${kind}' references unknown event or capability '${actionId}' for '${directive}'`,
+      valueToken.loc
+    );
+  }
+}
+
+function validateComponentBehaviors(errors, statement, fieldMap, registry) {
+  validateSymbolList(errors, statement, fieldMap, "behavior", COMPONENT_BEHAVIOR_KINDS, "behavior");
+
+  const field = fieldMap.get("behaviors")?.[0];
+  if (!field || field.value.type !== "block") {
+    return;
+  }
+
+  const propNames = componentPropNames(statement);
+  const eventNames = componentEventNames(statement);
+
+  for (const entry of field.value.entries) {
+    const [kindToken, ...rest] = entry.items;
+    const kind = tokenValue(kindToken);
+    if (!kind || kindToken.type !== "symbol") {
+      pushError(errors, `Component ${statement.id} behaviors entries must start with a behavior kind`, entry.loc);
+      continue;
+    }
+    if (!COMPONENT_BEHAVIOR_KINDS.has(kind)) {
+      pushError(errors, `Component ${statement.id} behavior '${kind}' is not supported`, entry.loc);
+      continue;
+    }
+
+    const allowedDirectives = COMPONENT_BEHAVIOR_DIRECTIVES[kind] || new Set();
+    for (let i = 0; i < rest.length; i += 2) {
+      const directiveToken = rest[i];
+      const valueToken = rest[i + 1];
+      const directive = tokenValue(directiveToken);
+      if (!directive || directiveToken.type !== "symbol") {
+        pushError(errors, `Component ${statement.id} behavior '${kind}' directives must use symbol keys`, entry.loc);
+        continue;
+      }
+      if (!valueToken) {
+        pushError(errors, `Component ${statement.id} behavior '${kind}' is missing a value for '${directive}'`, directiveToken.loc);
+        continue;
+      }
+      if (!allowedDirectives.has(directive)) {
+        pushError(errors, `Component ${statement.id} behavior '${kind}' has unsupported directive '${directive}'`, directiveToken.loc);
+        continue;
+      }
+
+      if (directive === "state" && !propNames.has(tokenValue(valueToken))) {
+        pushError(errors, `Component ${statement.id} behavior '${kind}' references unknown prop '${tokenValue(valueToken)}' for '${directive}'`, valueToken.loc);
+      }
+      if (directive === "emits") {
+        for (const eventName of tokenValues(valueToken)) {
+          if (!eventNames.has(eventName)) {
+            pushError(errors, `Component ${statement.id} behavior '${kind}' references unknown event '${eventName}' for '${directive}'`, valueToken.loc);
+          }
+        }
+      }
+      if (directive === "actions" || directive === "submit") {
+        validateBehaviorActionReferences(errors, statement, registry, kind, directive, valueToken, eventNames);
+      }
+      if (kind === "selection" && directive === "mode" && !["single", "multi", "none"].includes(tokenValue(valueToken))) {
+        pushError(errors, `Component ${statement.id} behavior 'selection' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
+      }
+      if (kind === "pagination" && directive === "mode" && !["cursor", "paged", "infinite", "none"].includes(tokenValue(valueToken))) {
+        pushError(errors, `Component ${statement.id} behavior 'pagination' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
+      }
+    }
+  }
+}
+
+export function validateComponent(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "component") {
+    return;
+  }
+
+  validateComponentCategory(errors, statement, fieldMap);
+  validateComponentProps(errors, statement);
+  validateComponentEvents(errors, statement, registry);
+  validateComponentSlots(errors, statement);
+  validateComponentBehaviors(errors, statement, fieldMap, registry);
+  validateSymbolList(errors, statement, fieldMap, "patterns", UI_PATTERN_KINDS, "pattern");
+  validateSymbolList(errors, statement, fieldMap, "regions", UI_REGION_KINDS, "region");
+}

package/src/validator/per-kind/domain.js

@@ -0,0 +1,205 @@
+import {
+  DOMAIN_IDENTIFIER_PATTERN,
+  DOMAIN_TAGGABLE_KINDS
+} from "../kinds.js";
+import {
+  blockEntries,
+  getFieldValue,
+  pushError,
+  symbolValue,
+  symbolValues,
+  valueAsArray
+} from "../utils.js";
+
+function isStringOrSymbolList(value) {
+  for (const item of valueAsArray(value)) {
+    if (item.type !== "string" && item.type !== "symbol") {
+      return false;
+    }
+  }
+  return true;
+}
+
+function validateDomainIdentifier(errors, statement) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  if (!DOMAIN_IDENTIFIER_PATTERN.test(statement.id)) {
+    pushError(
+      errors,
+      `Domain identifier '${statement.id}' must match ${DOMAIN_IDENTIFIER_PATTERN.source}`,
+      statement.loc
+    );
+  }
+}
+
+function validateScopeFields(errors, statement, fieldMap) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  for (const key of ["in_scope", "out_of_scope", "aliases"]) {
+    const field = fieldMap.get(key)?.[0];
+    if (!field) continue;
+    if (!isStringOrSymbolList(field.value)) {
+      pushError(
+        errors,
+        `Field '${key}' on domain ${statement.id} must be a list of strings or symbols`,
+        field.loc
+      );
+    }
+  }
+}
+
+function validateParentDomain(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  const field = fieldMap.get("parent_domain")?.[0];
+  if (!field) return;
+
+  const parentId = symbolValue(field.value);
+  if (!parentId) {
+    pushError(
+      errors,
+      `Field 'parent_domain' on domain ${statement.id} must be a single symbol`,
+      field.loc
+    );
+    return;
+  }
+
+  if (parentId === statement.id) {
+    pushError(
+      errors,
+      `Domain ${statement.id} cannot be its own parent_domain`,
+      field.loc
+    );
+    return;
+  }
+
+  const target = registry.get(parentId);
+  if (!target) {
+    pushError(
+      errors,
+      `Domain ${statement.id} parent_domain references missing domain '${parentId}'`,
+      field.loc
+    );
+    return;
+  }
+  if (target.kind !== "domain") {
+    pushError(
+      errors,
+      `Domain ${statement.id} parent_domain must reference a domain, found ${target.kind} '${target.id}'`,
+      field.loc
+    );
+  }
+}
+
+function validateOwners(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  const field = fieldMap.get("owners")?.[0];
+  if (!field) return;
+
+  for (const id of symbolValues(field.value)) {
+    const target = registry.get(id);
+    if (!target) {
+      pushError(
+        errors,
+        `Domain ${statement.id} owners references missing statement '${id}'`,
+        field.loc
+      );
+      continue;
+    }
+    if (target.kind !== "actor" && target.kind !== "role") {
+      pushError(
+        errors,
+        `Domain ${statement.id} owners must reference actor or role, found ${target.kind} '${target.id}'`,
+        field.loc
+      );
+    }
+  }
+}
+
+function detectParentDomainCycle(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  const field = fieldMap.get("parent_domain")?.[0];
+  if (!field) return;
+
+  const seen = new Set([statement.id]);
+  let cursor = registry.get(symbolValue(field.value));
+  while (cursor && cursor.kind === "domain") {
+    if (seen.has(cursor.id)) {
+      pushError(
+        errors,
+        `Domain ${statement.id} parent_domain chain forms a cycle through '${cursor.id}'`,
+        field.loc
+      );
+      return;
+    }
+    seen.add(cursor.id);
+    const parentField = cursor.fields.find((f) => f.key === "parent_domain");
+    if (!parentField) break;
+    cursor = registry.get(symbolValue(parentField.value));
+  }
+}
+
+export function validateDomain(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "domain") {
+    return;
+  }
+  validateDomainIdentifier(errors, statement);
+  validateScopeFields(errors, statement, fieldMap);
+  validateParentDomain(errors, statement, fieldMap, registry);
+  validateOwners(errors, statement, fieldMap, registry);
+  detectParentDomainCycle(errors, statement, fieldMap, registry);
+}
+
+// Cross-kind validator: when *any* statement carries a `domain` field, verify
+// it resolves to kind=domain. Skipped on the `domain` kind itself (its own
+// `parent_domain` field handles that case).
+export function validateDomainTag(errors, statement, fieldMap, registry) {
+  if (statement.kind === "domain") {
+    return;
+  }
+  const field = fieldMap.get("domain")?.[0];
+  if (!field) return;
+
+  if (!DOMAIN_TAGGABLE_KINDS.has(statement.kind)) {
+    pushError(
+      errors,
+      `Field 'domain' is not allowed on ${statement.kind} ${statement.id}`,
+      field.loc
+    );
+    return;
+  }
+
+  const id = symbolValue(field.value);
+  if (!id) {
+    pushError(
+      errors,
+      `Field 'domain' on ${statement.kind} ${statement.id} must be a single symbol`,
+      field.loc
+    );
+    return;
+  }
+
+  const target = registry.get(id);
+  if (!target) {
+    pushError(
+      errors,
+      `${statement.kind} ${statement.id} domain references missing domain '${id}'`,
+      field.loc
+    );
+    return;
+  }
+  if (target.kind !== "domain") {
+    pushError(
+      errors,
+      `${statement.kind} ${statement.id} domain must reference a domain, found ${target.kind} '${target.id}'`,
+      field.loc
+    );
+  }
+}

package/src/validator/per-kind/pitch.js

@@ -0,0 +1,101 @@
+import {
+  PITCH_IDENTIFIER_PATTERN,
+  PRIORITY_VALUES
+} from "../kinds.js";
+import {
+  pushError,
+  symbolValue,
+  symbolValues
+} from "../utils.js";
+
+function validatePitchIdentifier(errors, statement) {
+  if (!PITCH_IDENTIFIER_PATTERN.test(statement.id)) {
+    pushError(
+      errors,
+      `Pitch identifier '${statement.id}' must match ${PITCH_IDENTIFIER_PATTERN.source}`,
+      statement.loc
+    );
+  }
+}
+
+function validatePriority(errors, statement, fieldMap) {
+  const field = fieldMap.get("priority")?.[0];
+  if (!field) return;
+  if (field.value.type !== "symbol") {
+    pushError(errors, `Field 'priority' on pitch ${statement.id} must be a symbol`, field.loc);
+    return;
+  }
+  if (!PRIORITY_VALUES.has(field.value.value)) {
+    pushError(
+      errors,
+      `Invalid priority '${field.value.value}' on pitch ${statement.id}`,
+      field.loc
+    );
+  }
+}
+
+function validateAppetite(errors, statement, fieldMap) {
+  const field = fieldMap.get("appetite")?.[0];
+  if (!field) return;
+  if (field.value.type !== "string" && field.value.type !== "symbol") {
+    pushError(
+      errors,
+      `Field 'appetite' on pitch ${statement.id} must be a string or symbol`,
+      field.loc
+    );
+  }
+}
+
+function validateShapingFields(errors, statement, fieldMap) {
+  // When a pitch enters status `shaped`, the appetite, rabbit_holes, and
+  // no_go_areas sections must be filled. This mirrors the Forge pitch
+  // shaping discipline.
+  const statusField = fieldMap.get("status")?.[0];
+  if (!statusField || statusField.value.type !== "symbol") return;
+  const status = statusField.value.value;
+  if (status !== "shaped" && status !== "submitted" && status !== "approved") return;
+
+  for (const required of ["appetite", "rabbit_holes", "no_go_areas"]) {
+    if (!fieldMap.has(required)) {
+      pushError(
+        errors,
+        `Pitch ${statement.id} status '${status}' requires field '${required}' to be filled`,
+        statusField.loc
+      );
+    }
+  }
+}
+
+function validateDecisionRefs(errors, statement, fieldMap, registry) {
+  const field = fieldMap.get("decisions")?.[0];
+  if (!field) return;
+  for (const id of symbolValues(field.value)) {
+    const target = registry.get(id);
+    if (!target) {
+      pushError(
+        errors,
+        `Pitch ${statement.id} decisions references missing decision '${id}'`,
+        field.loc
+      );
+      continue;
+    }
+    if (target.kind !== "decision") {
+      pushError(
+        errors,
+        `Pitch ${statement.id} decisions must reference decision, found ${target.kind} '${target.id}'`,
+        field.loc
+      );
+    }
+  }
+}
+
+export function validatePitch(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "pitch") {
+    return;
+  }
+  validatePitchIdentifier(errors, statement);
+  validatePriority(errors, statement, fieldMap);
+  validateAppetite(errors, statement, fieldMap);
+  validateShapingFields(errors, statement, fieldMap);
+  validateDecisionRefs(errors, statement, fieldMap, registry);
+}

package/src/validator/per-kind/requirement.js

@@ -0,0 +1,75 @@
+import {
+  REQUIREMENT_IDENTIFIER_PATTERN,
+  PRIORITY_VALUES
+} from "../kinds.js";
+import {
+  pushError,
+  symbolValue,
+  symbolValues
+} from "../utils.js";
+
+function validateRequirementIdentifier(errors, statement) {
+  if (!REQUIREMENT_IDENTIFIER_PATTERN.test(statement.id)) {
+    pushError(
+      errors,
+      `Requirement identifier '${statement.id}' must match ${REQUIREMENT_IDENTIFIER_PATTERN.source}`,
+      statement.loc
+    );
+  }
+}
+
+function validatePriority(errors, statement, fieldMap) {
+  const field = fieldMap.get("priority")?.[0];
+  if (!field) return;
+  if (field.value.type !== "symbol") {
+    pushError(errors, `Field 'priority' on requirement ${statement.id} must be a symbol`, field.loc);
+    return;
+  }
+  if (!PRIORITY_VALUES.has(field.value.value)) {
+    pushError(
+      errors,
+      `Invalid priority '${field.value.value}' on requirement ${statement.id}`,
+      field.loc
+    );
+  }
+}
+
+function validateSupersedes(errors, statement, fieldMap, registry) {
+  const field = fieldMap.get("supersedes")?.[0];
+  if (!field) return;
+  for (const id of symbolValues(field.value)) {
+    if (id === statement.id) {
+      pushError(
+        errors,
+        `Requirement ${statement.id} cannot supersede itself`,
+        field.loc
+      );
+      continue;
+    }
+    const target = registry.get(id);
+    if (!target) {
+      pushError(
+        errors,
+        `Requirement ${statement.id} supersedes references missing requirement '${id}'`,
+        field.loc
+      );
+      continue;
+    }
+    if (target.kind !== "requirement") {
+      pushError(
+        errors,
+        `Requirement ${statement.id} supersedes must reference requirement, found ${target.kind} '${target.id}'`,
+        field.loc
+      );
+    }
+  }
+}
+
+export function validateRequirement(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "requirement") {
+    return;
+  }
+  validateRequirementIdentifier(errors, statement);
+  validatePriority(errors, statement, fieldMap);
+  validateSupersedes(errors, statement, fieldMap, registry);
+}