@topogram/cli 0.3.63 → 0.3.65

package/src/validator/data-model.js

@@ -0,0 +1,237 @@
+// @ts-check
+
+import {
+  blockEntries,
+  blockSymbolItems,
+  getFieldValue,
+  pushError,
+  valueAsArray
+} from "./utils.js";
+import {
+  resolveShapeBaseFieldNames,
+  statementFieldNames
+} from "./model-helpers.js";
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateShapeFrom(errors, statement, registry) {
+  if (statement.kind !== "shape" || !statement.from) {
+    return;
+  }
+
+  const target = registry.get(statement.from.value);
+  if (!target) {
+    pushError(errors, `Shape ${statement.id} derives from missing statement '${statement.from.value}'`, statement.from.loc);
+    return;
+  }
+
+  if (target.kind !== "entity") {
+    pushError(errors, `Shape ${statement.id} can only derive from an entity, found ${target.kind} '${target.id}'`, statement.from.loc);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+function validateEntityRelations(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "entity") {
+    return;
+  }
+
+  const field = fieldMap.get("relations")?.[0];
+  if (!field || field.value.type !== "block") {
+    return;
+  }
+
+  for (const entry of field.value.entries) {
+    const [left, operator, target] = entry.items;
+    if (!left || !operator || !target) {
+      continue;
+    }
+
+    if (left.type !== "symbol" || operator.type !== "symbol" || target.type !== "symbol") {
+      pushError(errors, `Relation entries on entity ${statement.id} must use symbols`, entry.loc);
+      continue;
+    }
+
+    if (operator.value !== "references") {
+      pushError(errors, `Relation entries on entity ${statement.id} must use 'references'`, operator.loc);
+    }
+
+    const [entityId] = target.value.split(".");
+    const related = registry.get(entityId);
+    if (!related) {
+      pushError(errors, `Relation on entity ${statement.id} references missing entity '${entityId}'`, target.loc);
+      continue;
+    }
+
+    if (related.kind !== "entity") {
+      pushError(errors, `Relation on entity ${statement.id} must target an entity, found ${related.kind} '${related.id}'`, target.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+function validateShapeTransforms(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "shape") {
+    return;
+  }
+
+  const baseFieldNames = resolveShapeBaseFieldNames(statement, registry);
+  const baseFieldSet = new Set(baseFieldNames);
+  const source = statement.from ? registry.get(statement.from.value) : null;
+  const sourceFieldSet = new Set(source ? statementFieldNames(source) : []);
+  const includeField = fieldMap.get("include")?.[0];
+  const excludeField = fieldMap.get("exclude")?.[0];
+
+  /** @type {Array<[string, TopogramField | undefined]>} */
+  const inheritedFieldLists = [
+    ["include", includeField],
+    ["exclude", excludeField]
+  ];
+
+  for (const [fieldKey, field] of inheritedFieldLists) {
+    if (!field) {
+      continue;
+    }
+
+    for (const item of valueAsArray(field.value)) {
+      if (item.type !== "symbol") {
+        continue;
+      }
+
+      if (statement.from && !sourceFieldSet.has(item.value) && fieldKey === "include") {
+        pushError(errors, `Shape ${statement.id} includes unknown field '${item.value}' from ${statement.from.value}`, item.loc);
+      }
+
+      if (statement.from && fieldKey === "exclude") {
+        if (!sourceFieldSet.has(item.value)) {
+          pushError(errors, `Shape ${statement.id} excludes unknown field '${item.value}' from ${statement.from.value}`, item.loc);
+        }
+      }
+    }
+  }
+
+  const renameEntries = blockEntries(getFieldValue(statement, "rename"));
+  const renameFrom = new Map();
+  const renameTo = new Map();
+
+  for (const entry of renameEntries) {
+    const items = blockSymbolItems(entry);
+    if (items.length !== 2) {
+      pushError(errors, `Each 'rename' entry on shape ${statement.id} must be exactly '<from> <to>'`, entry.loc);
+      continue;
+    }
+
+    const [fromItem, toItem] = items;
+    if (!baseFieldSet.has(fromItem.value)) {
+      pushError(errors, `Shape ${statement.id} renames unknown field '${fromItem.value}'`, fromItem.loc);
+    }
+
+    if (renameFrom.has(fromItem.value)) {
+      pushError(errors, `Shape ${statement.id} renames field '${fromItem.value}' more than once`, fromItem.loc);
+    } else {
+      renameFrom.set(fromItem.value, toItem.value);
+    }
+
+    if (renameTo.has(toItem.value)) {
+      pushError(errors, `Shape ${statement.id} renames multiple fields to '${toItem.value}'`, toItem.loc);
+    } else {
+      renameTo.set(toItem.value, fromItem.value);
+    }
+  }
+
+  const finalFieldNames = baseFieldNames.map((fieldName) => renameFrom.get(fieldName) || fieldName);
+  const finalFieldSet = new Set();
+  for (const fieldName of finalFieldNames) {
+    if (finalFieldSet.has(fieldName)) {
+      pushError(errors, `Shape ${statement.id} produces duplicate projected field '${fieldName}'`, statement.loc);
+      continue;
+    }
+    finalFieldSet.add(fieldName);
+  }
+
+  const sourceNameSet = new Set(baseFieldNames);
+  const overrideEntries = blockEntries(getFieldValue(statement, "overrides"));
+  const seenOverrides = new Set();
+
+  for (const entry of overrideEntries) {
+    const items = blockSymbolItems(entry);
+    if (items.length < 2) {
+      pushError(errors, `Each 'overrides' entry on shape ${statement.id} must include a field and at least one override`, entry.loc);
+      continue;
+    }
+
+    const [fieldItem, ...rest] = items;
+    if (!finalFieldSet.has(fieldItem.value) && !sourceNameSet.has(fieldItem.value)) {
+      pushError(errors, `Shape ${statement.id} overrides unknown field '${fieldItem.value}'`, fieldItem.loc);
+    }
+
+    if (seenOverrides.has(fieldItem.value)) {
+      pushError(errors, `Shape ${statement.id} overrides field '${fieldItem.value}' more than once`, fieldItem.loc);
+    } else {
+      seenOverrides.add(fieldItem.value);
+    }
+
+    let sawChange = false;
+    for (let i = 0; i < rest.length; i += 1) {
+      const token = rest[i];
+      if (token.value === "required" || token.value === "optional") {
+        sawChange = true;
+        continue;
+      }
+
+      if (token.value === "type") {
+        sawChange = true;
+        if (!rest[i + 1]) {
+          pushError(errors, `Shape ${statement.id} override for '${fieldItem.value}' is missing a type value`, token.loc);
+        } else {
+          i += 1;
+        }
+        continue;
+      }
+
+      if (token.value === "default") {
+        sawChange = true;
+        if (!rest[i + 1]) {
+          pushError(errors, `Shape ${statement.id} override for '${fieldItem.value}' is missing a default value`, token.loc);
+        } else {
+          i += 1;
+        }
+        continue;
+      }
+
+      pushError(errors, `Shape ${statement.id} override for '${fieldItem.value}' has unknown directive '${token.value}'`, token.loc);
+    }
+
+    if (!sawChange) {
+      pushError(errors, `Shape ${statement.id} override for '${fieldItem.value}' must specify at least one valid directive`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateDataModelStatement(errors, statement, fieldMap, registry) {
+  validateEntityRelations(errors, statement, fieldMap, registry);
+  validateShapeTransforms(errors, statement, fieldMap, registry);
+}

package/src/validator/docs.js

@@ -0,0 +1,167 @@
+// @ts-check
+
+import {
+  DOC_ARRAY_FIELDS,
+  DOC_CONFIDENCE,
+  DOC_KINDS,
+  DOC_REFERENCE_FIELDS,
+  DOC_STATUSES
+} from "../workspace-docs.js";
+import { IDENTIFIER_PATTERN } from "./kinds.js";
+import { pushError } from "./utils.js";
+
+/**
+ * @param {import("../parser.js").WorkspaceAst} workspaceAst
+ * @param {TopogramRegistry} registry
+ * @param {ValidationErrors} errors
+ * @returns {void}
+ */
+export function validateDocs(workspaceAst, registry, errors) {
+  const docs = workspaceAst.docs || [];
+  const docRegistry = new Map();
+
+  for (const doc of docs) {
+    if (doc.parseError) {
+      pushError(errors, doc.parseError.message, doc.parseError.loc);
+      continue;
+    }
+
+    const { metadata } = doc;
+    for (const required of ["id", "kind", "title", "status"]) {
+      if (!metadata[required]) {
+        pushError(errors, `Missing required doc metadata '${required}'`, doc.loc);
+      }
+    }
+
+    if (metadata.id && !IDENTIFIER_PATTERN.test(metadata.id)) {
+      pushError(errors, `Invalid doc identifier '${metadata.id}'`, doc.loc);
+    }
+
+    if (metadata.kind && !DOC_KINDS.has(metadata.kind)) {
+      pushError(errors, `Unsupported doc kind '${metadata.kind}'`, doc.loc);
+    }
+
+    if (metadata.status && !DOC_STATUSES.has(metadata.status)) {
+      pushError(errors, `Unsupported doc status '${metadata.status}'`, doc.loc);
+    }
+
+    if (metadata.confidence && !DOC_CONFIDENCE.has(metadata.confidence)) {
+      pushError(errors, `Unsupported doc confidence '${metadata.confidence}'`, doc.loc);
+    }
+
+    if (metadata.review_required != null && typeof metadata.review_required !== "boolean") {
+      pushError(errors, "Doc metadata 'review_required' must be a boolean", doc.loc);
+    }
+
+    for (const key of DOC_ARRAY_FIELDS) {
+      if (metadata[key] != null && !Array.isArray(metadata[key])) {
+        pushError(errors, `Doc metadata '${key}' must be a list`, doc.loc);
+      }
+    }
+
+    if (metadata.id) {
+      if (docRegistry.has(metadata.id)) {
+        pushError(errors, `Duplicate doc id '${metadata.id}'`, doc.loc);
+      } else {
+        docRegistry.set(metadata.id, doc);
+      }
+    }
+  }
+
+  for (const doc of docs) {
+    if (doc.parseError) {
+      continue;
+    }
+    const { metadata } = doc;
+
+    for (const entityId of metadata.related_entities || []) {
+      const statement = registry.get(entityId);
+      if (!statement || statement.kind !== "entity") {
+        pushError(errors, `Doc '${metadata.id}' references missing entity '${entityId}'`, doc.loc);
+      }
+    }
+
+    for (const capabilityId of metadata.related_capabilities || []) {
+      const statement = registry.get(capabilityId);
+      if (!statement || statement.kind !== "capability") {
+        pushError(errors, `Doc '${metadata.id}' references missing capability '${capabilityId}'`, doc.loc);
+      }
+    }
+
+    for (const actorId of metadata.related_actors || []) {
+      const statement = registry.get(actorId);
+      if (!statement || statement.kind !== "actor") {
+        pushError(errors, `Doc '${metadata.id}' references missing actor '${actorId}'`, doc.loc);
+      }
+    }
+
+    for (const roleId of metadata.related_roles || []) {
+      const statement = registry.get(roleId);
+      if (!statement || statement.kind !== "role") {
+        pushError(errors, `Doc '${metadata.id}' references missing role '${roleId}'`, doc.loc);
+      }
+    }
+
+    for (const ruleId of metadata.related_rules || []) {
+      const statement = registry.get(ruleId);
+      if (!statement || statement.kind !== "rule") {
+        pushError(errors, `Doc '${metadata.id}' references missing rule '${ruleId}'`, doc.loc);
+      }
+    }
+
+    for (const workflowDocId of metadata.related_workflows || []) {
+      const relatedDoc = docRegistry.get(workflowDocId);
+      if (!relatedDoc || relatedDoc.metadata.kind !== "workflow") {
+        pushError(errors, `Doc '${metadata.id}' references missing workflow doc '${workflowDocId}'`, doc.loc);
+      }
+    }
+
+    for (const decisionId of metadata.related_decisions || []) {
+      const statement = registry.get(decisionId);
+      if (!statement || statement.kind !== "decision") {
+        pushError(errors, `Doc '${metadata.id}' references missing decision '${decisionId}'`, doc.loc);
+      }
+    }
+
+    for (const shapeId of metadata.related_shapes || []) {
+      const statement = registry.get(shapeId);
+      if (!statement || statement.kind !== "shape") {
+        pushError(errors, `Doc '${metadata.id}' references missing shape '${shapeId}'`, doc.loc);
+      }
+    }
+
+    for (const projectionId of metadata.related_projections || []) {
+      const statement = registry.get(projectionId);
+      if (!statement || statement.kind !== "projection") {
+        pushError(errors, `Doc '${metadata.id}' references missing projection '${projectionId}'`, doc.loc);
+      }
+    }
+
+    for (const relatedDocId of metadata.related_docs || []) {
+      if (!docRegistry.has(relatedDocId)) {
+        pushError(errors, `Doc '${metadata.id}' references missing doc '${relatedDocId}'`, doc.loc);
+      }
+    }
+
+    for (const [fieldName, expectedKind] of Object.entries(DOC_REFERENCE_FIELDS)) {
+      const value = metadata[fieldName];
+      if (value == null) continue;
+      if (typeof value !== "string") {
+        pushError(errors, `Doc metadata '${fieldName}' must be a single id`, doc.loc);
+        continue;
+      }
+      const target = registry.get(value);
+      if (!target) {
+        pushError(errors, `Doc '${metadata.id}' references missing ${expectedKind} '${value}'`, doc.loc);
+        continue;
+      }
+      if (target.kind !== expectedKind) {
+        pushError(
+          errors,
+          `Doc '${metadata.id}' ${fieldName} must reference a ${expectedKind}, found ${target.kind} '${target.id}'`,
+          doc.loc
+        );
+      }
+    }
+  }
+}

package/src/validator/expressions.js

@@ -1 +1,146 @@
-// Expression validation remains orchestrated from index.js after the initial split.
+// @ts-check
+
+import {
+  blockSymbolItems,
+  pushError,
+  valueAsArray
+} from "./utils.js";
+
+/**
+ * @param {unknown} token
+ * @returns {token is string}
+ */
+function isIdentifierLike(token) {
+  return typeof token === "string" && token.length > 0;
+}
+
+/**
+ * @param {unknown} token
+ * @returns {token is string}
+ */
+function isComparator(token) {
+  return typeof token === "string" && ["==", "!=", "<", "<=", ">", ">="].includes(token);
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramBlockEntry} entry
+ * @returns {void}
+ */
+function validateInvariantEntry(errors, statement, entry) {
+  const tokens = blockSymbolItems(entry).map((item) => item.value);
+  if (tokens.length < 2) {
+    pushError(errors, `Invariant on ${statement.kind} ${statement.id} is too short`, entry.loc);
+    return;
+  }
+
+  const [left, op, ...rest] = tokens;
+  if (!isIdentifierLike(left)) {
+    pushError(errors, `Invariant on ${statement.kind} ${statement.id} must start with a field or expression target`, entry.loc);
+    return;
+  }
+
+  if (op === "requires") {
+    if (rest.length < 3) {
+      pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} must be '<field> requires <field> <op> <value>'`, entry.loc);
+    } else if (!isComparator(rest[1])) {
+      pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} uses an invalid comparator '${rest[1]}'`, entry.loc);
+    }
+    return;
+  }
+
+  if (op === "length") {
+    if (rest.length !== 2 || !["<", "<=", ">", ">=", "=="].includes(rest[0])) {
+      pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} must be '<field> length <op> <number>'`, entry.loc);
+    }
+    return;
+  }
+
+  if (op === "format") {
+    if (rest.length !== 2 || rest[0] !== "==") {
+      pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} must be '<field> format == <format>'`, entry.loc);
+    }
+    return;
+  }
+
+  if (isComparator(op)) {
+    if (rest.length < 1) {
+      pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} is missing a right-hand value`, entry.loc);
+      return;
+    }
+
+    if (rest[1] === "implies") {
+      const [, , impliedField, impliedOperator, impliedValue] = rest;
+      if (!impliedField || !impliedOperator || !impliedValue) {
+        pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} must fully specify the implied clause`, entry.loc);
+      } else if (!(impliedOperator === "is" || isComparator(impliedOperator))) {
+        pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} has invalid implied operator '${impliedOperator}'`, entry.loc);
+      }
+      return;
+    }
+
+    return;
+  }
+
+  pushError(errors, `Invariant '${tokens.join(" ")}' on ${statement.kind} ${statement.id} uses unsupported form`, entry.loc);
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramField | null | undefined} field
+ * @param {string} label
+ * @returns {void}
+ */
+function validateRuleExpressionValue(errors, statement, field, label) {
+  if (!field) {
+    return;
+  }
+
+  const items = valueAsArray(field.value);
+  if (items.length !== 1) {
+    pushError(errors, `Field '${label}' on rule ${statement.id} must contain a single expression`, field.loc);
+    return;
+  }
+
+  const item = items[0];
+  if (item.type !== "string" && item.type !== "symbol") {
+    pushError(errors, `Field '${label}' on rule ${statement.id} must be a string or symbol expression`, field.loc);
+    return;
+  }
+
+  const text = item.value.trim();
+  if (text.length === 0) {
+    pushError(errors, `Field '${label}' on rule ${statement.id} must not be empty`, field.loc);
+    return;
+  }
+
+  if (label === "requirement" || label === "condition") {
+    if (!/(==|!=|<=|>=|<|>)/.test(text)) {
+      pushError(errors, `Field '${label}' on rule ${statement.id} must include a comparison operator`, field.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {void}
+ */
+export function validateExpressions(errors, statement, fieldMap) {
+  if (statement.kind === "entity") {
+    const invariantsField = fieldMap.get("invariants")?.[0];
+    if (invariantsField?.value.type === "block") {
+      for (const entry of invariantsField.value.entries) {
+        validateInvariantEntry(errors, statement, entry);
+      }
+    }
+  }
+
+  if (statement.kind === "rule") {
+    validateRuleExpressionValue(errors, statement, fieldMap.get("condition")?.[0], "condition");
+    validateRuleExpressionValue(errors, statement, fieldMap.get("requirement")?.[0], "requirement");
+  }
+}

package/src/validator/index.d.ts

@@ -0,0 +1,23 @@
+import type {
+  TopogramBlockEntry,
+  TopogramField,
+  TopogramFieldMap,
+  TopogramRegistry,
+  TopogramStatement,
+  TopogramToken,
+  ValidationErrors
+} from "../topogram-types.js";
+
+export function pushError(errors: ValidationErrors, message: string, loc?: any): void;
+export function formatLoc(loc: any): string;
+export function valueAsArray(value: TopogramToken | null | undefined): TopogramToken[];
+export function symbolValues(value: TopogramToken | null | undefined): string[];
+export function collectFieldMap(statement: TopogramStatement): TopogramFieldMap;
+export function getField(statement: TopogramStatement, key: string): TopogramField | null;
+export function getFieldValue(statement: TopogramStatement, key: string): TopogramToken | null;
+export function stringValue(value: TopogramToken | null | undefined): string | null;
+export function symbolValue(value: TopogramToken | null | undefined): string | null;
+export function blockEntries(value: TopogramToken | null | undefined): TopogramBlockEntry[];
+export function buildRegistry(workspaceAst: any, errors: ValidationErrors): TopogramRegistry;
+export function validateWorkspace(workspaceAst: any): any;
+export function formatValidationErrors(result: any): string;