@topogram/cli 0.3.64 → 0.3.65

package/src/validator/projections/api-http-core.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+import {
+  blockSymbolItems,
+  getFieldValue,
+  pushError,
+  symbolValues
+} from "../utils.js";
+import { resolveCapabilityContractFields } from "./helpers.js";
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateProjectionHttp(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpField = fieldMap.get("endpoints")?.[0];
+  if (!httpField || httpField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+
+  for (const entry of httpField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const capabilityId = tokens[0];
+    if (!capabilityId) {
+      continue;
+    }
+
+    const target = registry.get(capabilityId);
+    if (!target) {
+      pushError(errors, `Projection ${statement.id} http metadata references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (target.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} http metadata must target a capability, found ${target.kind} '${target.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+
+    const directives = new Map();
+    for (let i = 1; i < tokens.length; i += 2) {
+      const key = tokens[i];
+      const value = tokens[i + 1];
+      if (!value) {
+        pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' is missing a value for '${key}'`, entry.loc);
+        continue;
+      }
+      directives.set(key, value);
+    }
+
+    for (const requiredKey of ["method", "path", "success"]) {
+      if (!directives.has(requiredKey)) {
+        pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' must include '${requiredKey}'`, entry.loc);
+      }
+    }
+
+    for (const key of directives.keys()) {
+      if (!["method", "path", "success", "auth", "request"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+
+    const method = directives.get("method");
+    if (method && !["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' has invalid method '${method}'`, entry.loc);
+    }
+
+    const path = directives.get("path");
+    if (path && !path.startsWith("/")) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' must use an absolute path`, entry.loc);
+    }
+
+    const success = directives.get("success");
+    if (success && !/^\d{3}$/.test(success)) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' must use a 3-digit success status`, entry.loc);
+    }
+
+    const auth = directives.get("auth");
+    if (auth && !["none", "user", "manager", "admin"].includes(auth)) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' has invalid auth mode '${auth}'`, entry.loc);
+    }
+
+    const request = directives.get("request");
+    if (request && !["body", "query", "path", "none"].includes(request)) {
+      pushError(errors, `Projection ${statement.id} http metadata for '${capabilityId}' has invalid request placement '${request}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionHttpErrors(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpErrorsField = fieldMap.get("error_responses")?.[0];
+  if (!httpErrorsField || httpErrorsField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of httpErrorsField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId, errorCode, status] = tokens;
+
+    const target = registry.get(capabilityId);
+    if (!target) {
+      pushError(errors, `Projection ${statement.id} error_responses references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (target.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} error_responses must target a capability, found ${target.kind} '${target.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} error_responses for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+    if (!/^\d{3}$/.test(status || "")) {
+      pushError(errors, `Projection ${statement.id} error_responses for '${capabilityId}' must use a 3-digit status`, entry.loc);
+    }
+    if (!errorCode) {
+      pushError(errors, `Projection ${statement.id} error_responses for '${capabilityId}' must include an error code`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionHttpFields(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpFieldsField = fieldMap.get("wire_fields")?.[0];
+  if (!httpFieldsField || httpFieldsField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of httpFieldsField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId, direction, fieldName, keywordIn, location, maybeAs, maybeWireName] = tokens;
+
+    const capability = registry.get(capabilityId);
+    if (!capability) {
+      pushError(errors, `Projection ${statement.id} wire_fields references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (capability.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} wire_fields must target a capability, found ${capability.kind} '${capability.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+    if (!["input", "output"].includes(direction)) {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' has invalid direction '${direction}'`, entry.loc);
+    }
+    if (keywordIn !== "in") {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' must use 'in' before the location`, entry.loc);
+    }
+    if (!["path", "query", "header", "body"].includes(location)) {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' has invalid location '${location}'`, entry.loc);
+    }
+    if (maybeAs && maybeAs !== "as") {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' has unexpected token '${maybeAs}'`, entry.loc);
+    }
+    if (maybeAs === "as" && !maybeWireName) {
+      pushError(errors, `Projection ${statement.id} wire_fields for '${capabilityId}' must provide a wire name after 'as'`, entry.loc);
+    }
+
+    const availableFields = resolveCapabilityContractFields(registry, capabilityId, direction);
+    if (fieldName && availableFields.size > 0 && !availableFields.has(fieldName)) {
+      pushError(errors, `Projection ${statement.id} wire_fields references unknown ${direction} field '${fieldName}' on ${capabilityId}`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */

package/src/validator/projections/api-http-policies.js

@@ -0,0 +1,339 @@
+// @ts-check
+
+import {
+  blockEntries,
+  blockSymbolItems,
+  getFieldValue,
+  pushError,
+  symbolValues
+} from "../utils.js";
+import { resolveCapabilityContractFields } from "./helpers.js";
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateProjectionHttpPreconditions(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpPreconditionsField = fieldMap.get("preconditions")?.[0];
+  if (!httpPreconditionsField || httpPreconditionsField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of httpPreconditionsField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId] = tokens;
+    const capability = registry.get(capabilityId);
+
+    if (!capability) {
+      pushError(errors, `Projection ${statement.id} preconditions references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (capability.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} preconditions must target a capability, found ${capability.kind} '${capability.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+
+    const directives = new Map();
+    for (let i = 1; i < tokens.length; i += 2) {
+      const key = tokens[i];
+      const value = tokens[i + 1];
+      if (!value) {
+        pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' is missing a value for '${key}'`, entry.loc);
+        continue;
+      }
+      directives.set(key, value);
+    }
+
+    for (const requiredKey of ["header", "required", "error", "source", "code"]) {
+      if (!directives.has(requiredKey)) {
+        pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' must include '${requiredKey}'`, entry.loc);
+      }
+    }
+
+    for (const key of directives.keys()) {
+      if (!["header", "required", "error", "source", "code"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+
+    const required = directives.get("required");
+    if (required && !["true", "false"].includes(required)) {
+      pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' has invalid required value '${required}'`, entry.loc);
+    }
+
+    const errorStatus = directives.get("error");
+    if (errorStatus && !/^\d{3}$/.test(errorStatus)) {
+      pushError(errors, `Projection ${statement.id} preconditions for '${capabilityId}' must use a 3-digit error status`, entry.loc);
+    }
+
+    const sourceField = directives.get("source");
+    const outputFields = resolveCapabilityContractFields(registry, capabilityId, "output");
+    if (sourceField && outputFields.size > 0 && !outputFields.has(sourceField)) {
+      pushError(errors, `Projection ${statement.id} preconditions references unknown output field '${sourceField}' on ${capabilityId}`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionHttpIdempotency(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpIdempotencyField = fieldMap.get("idempotency")?.[0];
+  if (!httpIdempotencyField || httpIdempotencyField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of httpIdempotencyField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId] = tokens;
+    const capability = registry.get(capabilityId);
+
+    if (!capability) {
+      pushError(errors, `Projection ${statement.id} idempotency references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (capability.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} idempotency must target a capability, found ${capability.kind} '${capability.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+
+    const directives = new Map();
+    for (let i = 1; i < tokens.length; i += 2) {
+      const key = tokens[i];
+      const value = tokens[i + 1];
+      if (!value) {
+        pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' is missing a value for '${key}'`, entry.loc);
+        continue;
+      }
+      directives.set(key, value);
+    }
+
+    for (const requiredKey of ["header", "required", "error", "code"]) {
+      if (!directives.has(requiredKey)) {
+        pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' must include '${requiredKey}'`, entry.loc);
+      }
+    }
+
+    for (const key of directives.keys()) {
+      if (!["header", "required", "error", "code"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+
+    const required = directives.get("required");
+    if (required && !["true", "false"].includes(required)) {
+      pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' has invalid required value '${required}'`, entry.loc);
+    }
+
+    const errorStatus = directives.get("error");
+    if (errorStatus && !/^\d{3}$/.test(errorStatus)) {
+      pushError(errors, `Projection ${statement.id} idempotency for '${capabilityId}' must use a 3-digit error status`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionHttpCache(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpCacheField = fieldMap.get("cache")?.[0];
+  if (!httpCacheField || httpCacheField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  const httpEntries = blockEntries(getFieldValue(statement, "endpoints"));
+  const httpMethodsByCapability = new Map();
+
+  for (const entry of httpEntries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const capabilityId = tokens[0];
+    for (let i = 1; i < tokens.length - 1; i += 1) {
+      if (tokens[i] === "method") {
+        httpMethodsByCapability.set(capabilityId, tokens[i + 1]);
+        break;
+      }
+    }
+  }
+
+  for (const entry of httpCacheField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId] = tokens;
+    const capability = registry.get(capabilityId);
+
+    if (!capability) {
+      pushError(errors, `Projection ${statement.id} cache references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (capability.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} cache must target a capability, found ${capability.kind} '${capability.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+
+    const directives = new Map();
+    for (let i = 1; i < tokens.length; i += 2) {
+      const key = tokens[i];
+      const value = tokens[i + 1];
+      if (!value) {
+        pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' is missing a value for '${key}'`, entry.loc);
+        continue;
+      }
+      directives.set(key, value);
+    }
+
+    for (const requiredKey of ["response_header", "request_header", "required", "not_modified", "source", "code"]) {
+      if (!directives.has(requiredKey)) {
+        pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' must include '${requiredKey}'`, entry.loc);
+      }
+    }
+
+    for (const key of directives.keys()) {
+      if (!["response_header", "request_header", "required", "not_modified", "source", "code"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+
+    const required = directives.get("required");
+    if (required && !["true", "false"].includes(required)) {
+      pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' has invalid required value '${required}'`, entry.loc);
+    }
+
+    const notModifiedStatus = directives.get("not_modified");
+    if (notModifiedStatus && notModifiedStatus !== "304") {
+      pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' must use 304 for 'not_modified'`, entry.loc);
+    }
+
+    const sourceField = directives.get("source");
+    const outputFields = resolveCapabilityContractFields(registry, capabilityId, "output");
+    if (sourceField && outputFields.size > 0 && !outputFields.has(sourceField)) {
+      pushError(errors, `Projection ${statement.id} cache references unknown output field '${sourceField}' on ${capabilityId}`, entry.loc);
+    }
+
+    const method = httpMethodsByCapability.get(capabilityId);
+    if (method && method !== "GET") {
+      pushError(errors, `Projection ${statement.id} cache for '${capabilityId}' requires an HTTP GET realization, found '${method}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionHttpDelete(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const httpDeleteField = fieldMap.get("delete_semantics")?.[0];
+  if (!httpDeleteField || httpDeleteField.value.type !== "block") {
+    return;
+  }
+
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of httpDeleteField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [capabilityId] = tokens;
+    const capability = registry.get(capabilityId);
+
+    if (!capability) {
+      pushError(errors, `Projection ${statement.id} delete_semantics references missing capability '${capabilityId}'`, entry.loc);
+      continue;
+    }
+    if (capability.kind !== "capability") {
+      pushError(errors, `Projection ${statement.id} delete_semantics must target a capability, found ${capability.kind} '${capability.id}'`, entry.loc);
+    }
+    if (!realized.has(capabilityId)) {
+      pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' must also appear in 'realizes'`, entry.loc);
+    }
+
+    const directives = new Map();
+    for (let i = 1; i < tokens.length; i += 2) {
+      const key = tokens[i];
+      const value = tokens[i + 1];
+      if (!value) {
+        pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' is missing a value for '${key}'`, entry.loc);
+        continue;
+      }
+      directives.set(key, value);
+    }
+
+    for (const requiredKey of ["mode", "response"]) {
+      if (!directives.has(requiredKey)) {
+        pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' must include '${requiredKey}'`, entry.loc);
+      }
+    }
+
+    for (const key of directives.keys()) {
+      if (!["mode", "field", "value", "response"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+
+    const mode = directives.get("mode");
+    if (mode && !["soft", "hard"].includes(mode)) {
+      pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' has invalid mode '${mode}'`, entry.loc);
+    }
+
+    const response = directives.get("response");
+    if (response && !["none", "body"].includes(response)) {
+      pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' has invalid response '${response}'`, entry.loc);
+    }
+
+    if (mode === "soft") {
+      if (!directives.has("field") || !directives.has("value")) {
+        pushError(errors, `Projection ${statement.id} delete_semantics for '${capabilityId}' must include 'field' and 'value' for soft deletes`, entry.loc);
+      }
+      const outputFields = resolveCapabilityContractFields(registry, capabilityId, "output");
+      const fieldName = directives.get("field");
+      if (fieldName && outputFields.size > 0 && !outputFields.has(fieldName)) {
+        pushError(errors, `Projection ${statement.id} delete_semantics references unknown output field '${fieldName}' on ${capabilityId}`, entry.loc);
+      }
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */