@contractspec/lib.contracts-spec 2.0.0

package/dist/policy/validation.js

@@ -0,0 +1,391 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/policy/validation.ts
+function validatePolicySpec(spec) {
+  const issues = [];
+  validateMeta(spec, issues);
+  validateRules(spec, issues);
+  validateFieldPolicies(spec, issues);
+  validateRateLimits(spec, issues);
+  validateConsents(spec, issues);
+  validateRelationships(spec, issues);
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+function validateMeta(spec, issues) {
+  const { meta } = spec;
+  if (!meta.key?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Policy must have a non-empty key",
+      path: "meta.key"
+    });
+  }
+  if (!meta.version?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Policy must have a non-empty version",
+      path: "meta.version"
+    });
+  }
+  if (!meta.owners?.length) {
+    issues.push({
+      level: "warning",
+      message: "Policy should specify owners",
+      path: "meta.owners"
+    });
+  }
+}
+function validateRules(spec, issues) {
+  if (!spec.rules?.length) {
+    issues.push({
+      level: "warning",
+      message: "Policy has no rules defined",
+      path: "rules"
+    });
+    return;
+  }
+  const seenRateRefs = new Set;
+  spec.rules.forEach((rule, index) => {
+    const path = `rules[${index}]`;
+    if (!rule.actions?.length) {
+      issues.push({
+        level: "error",
+        message: "Rule must specify at least one action",
+        path: `${path}.actions`
+      });
+    }
+    if (!["allow", "deny"].includes(rule.effect)) {
+      issues.push({
+        level: "error",
+        message: `Invalid rule effect: ${rule.effect}`,
+        path: `${path}.effect`
+      });
+    }
+    if (typeof rule.rateLimit === "string") {
+      seenRateRefs.add(rule.rateLimit);
+      if (!spec.rateLimits?.some((rl) => rl.id === rule.rateLimit)) {
+        issues.push({
+          level: "error",
+          message: `Rate limit "${rule.rateLimit}" referenced but not defined`,
+          path: `${path}.rateLimit`
+        });
+      }
+    }
+    if (rule.requiresConsent?.length) {
+      for (const consentId of rule.requiresConsent) {
+        if (!spec.consents?.some((c) => c.id === consentId)) {
+          issues.push({
+            level: "error",
+            message: `Consent "${consentId}" referenced but not defined`,
+            path: `${path}.requiresConsent`
+          });
+        }
+      }
+    }
+    validateConditions(rule.conditions, `${path}.conditions`, issues);
+  });
+  if (spec.rateLimits?.length) {
+    for (const rl of spec.rateLimits) {
+      if (!seenRateRefs.has(rl.id)) {
+        const hasInline = spec.rules.some((r) => typeof r.rateLimit === "object" && r.rateLimit.id === rl.id);
+        if (!hasInline) {
+          issues.push({
+            level: "info",
+            message: `Rate limit "${rl.id}" is defined but not referenced`,
+            path: `rateLimits`
+          });
+        }
+      }
+    }
+  }
+}
+function validateFieldPolicies(spec, issues) {
+  if (!spec.fieldPolicies?.length)
+    return;
+  const seenFields = new Map;
+  spec.fieldPolicies.forEach((rule, index) => {
+    const path = `fieldPolicies[${index}]`;
+    if (!rule.field?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Field policy must specify a field",
+        path: `${path}.field`
+      });
+    }
+    if (!rule.actions?.length) {
+      issues.push({
+        level: "error",
+        message: "Field policy must specify at least one action",
+        path: `${path}.actions`
+      });
+    }
+    for (const action of rule.actions) {
+      if (!["read", "write"].includes(action)) {
+        issues.push({
+          level: "error",
+          message: `Invalid field action: ${action}`,
+          path: `${path}.actions`
+        });
+      }
+    }
+    const existing = seenFields.get(rule.field) ?? [];
+    existing.push(rule);
+    seenFields.set(rule.field, existing);
+    validateConditions(rule.conditions, `${path}.conditions`, issues);
+  });
+  for (const [field, rules] of seenFields.entries()) {
+    if (rules.length > 1) {
+      const hasConflict = rules.some((r) => r.effect === "allow") && rules.some((r) => r.effect === "deny");
+      if (hasConflict) {
+        issues.push({
+          level: "warning",
+          message: `Field "${field}" has potentially conflicting allow/deny policies`,
+          path: "fieldPolicies",
+          context: { field, ruleCount: rules.length }
+        });
+      }
+    }
+  }
+}
+function validateRateLimits(spec, issues) {
+  if (!spec.rateLimits?.length)
+    return;
+  const seenIds = new Set;
+  spec.rateLimits.forEach((rl, index) => {
+    const path = `rateLimits[${index}]`;
+    if (!rl.id?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Rate limit must have an id",
+        path: `${path}.id`
+      });
+    } else if (seenIds.has(rl.id)) {
+      issues.push({
+        level: "error",
+        message: `Duplicate rate limit id: ${rl.id}`,
+        path: `${path}.id`
+      });
+    } else {
+      seenIds.add(rl.id);
+    }
+    if (typeof rl.rpm !== "number" || rl.rpm <= 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit rpm must be a positive number",
+        path: `${path}.rpm`
+      });
+    }
+    if (rl.windowSeconds !== undefined && rl.windowSeconds <= 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit windowSeconds must be positive if specified",
+        path: `${path}.windowSeconds`
+      });
+    }
+    if (rl.burst !== undefined && rl.burst < 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit burst must be non-negative if specified",
+        path: `${path}.burst`
+      });
+    }
+  });
+}
+function validateConsents(spec, issues) {
+  if (!spec.consents?.length)
+    return;
+  const seenIds = new Set;
+  spec.consents.forEach((consent, index) => {
+    const path = `consents[${index}]`;
+    if (!consent.id?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must have an id",
+        path: `${path}.id`
+      });
+    } else if (seenIds.has(consent.id)) {
+      issues.push({
+        level: "error",
+        message: `Duplicate consent id: ${consent.id}`,
+        path: `${path}.id`
+      });
+    } else {
+      seenIds.add(consent.id);
+    }
+    if (!consent.scope?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must specify a scope",
+        path: `${path}.scope`
+      });
+    }
+    if (!consent.purpose?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must specify a purpose",
+        path: `${path}.purpose`
+      });
+    }
+    if (consent.expiresInDays !== undefined && consent.expiresInDays <= 0) {
+      issues.push({
+        level: "error",
+        message: "Consent expiresInDays must be positive if specified",
+        path: `${path}.expiresInDays`
+      });
+    }
+  });
+}
+function validateRelationships(spec, issues) {
+  if (!spec.relationships?.length)
+    return;
+  const seenRelations = new Set;
+  spec.relationships.forEach((rel, index) => {
+    const path = `relationships[${index}]`;
+    const key = `${rel.subjectType}:${rel.relation}:${rel.objectType}`;
+    if (!rel.subjectType?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify subjectType",
+        path: `${path}.subjectType`
+      });
+    }
+    if (!rel.relation?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify relation",
+        path: `${path}.relation`
+      });
+    }
+    if (!rel.objectType?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify objectType",
+        path: `${path}.objectType`
+      });
+    }
+    if (seenRelations.has(key)) {
+      issues.push({
+        level: "warning",
+        message: `Duplicate relationship definition: ${key}`,
+        path
+      });
+    } else {
+      seenRelations.add(key);
+    }
+  });
+}
+function validateConditions(conditions, path, issues) {
+  if (!conditions?.length)
+    return;
+  conditions.forEach((cond, index) => {
+    if (!cond.expression?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Condition must have a non-empty expression",
+        path: `${path}[${index}].expression`
+      });
+    }
+  });
+}
+function validatePolicyConsistency(deps) {
+  const issues = [];
+  for (const policy of deps.policies.list()) {
+    const specResult = validatePolicySpec(policy);
+    issues.push(...specResult.issues.map((i) => ({
+      ...i,
+      path: `${policy.meta.key}.v${policy.meta.version}${i.path ? `.${i.path}` : ""}`
+    })));
+  }
+  if (deps.operations) {
+    for (const operation of deps.operations.list()) {
+      const policyRefs = operation.policy.policies ?? [];
+      for (const ref of policyRefs) {
+        const policy = deps.policies.get(ref.key, ref.version);
+        if (!policy) {
+          issues.push({
+            level: "error",
+            message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown policy "${ref.key}.v${ref.version}"`,
+            path: `operations.${operation.meta.key}.policy.policies`
+          });
+        }
+      }
+      const fieldPolicies = operation.policy.fieldPolicies ?? [];
+      for (const fp of fieldPolicies) {
+        if (fp.policy) {
+          const policy = deps.policies.get(fp.policy.key, fp.policy.version);
+          if (!policy) {
+            issues.push({
+              level: "error",
+              message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown field policy "${fp.policy.key}.v${fp.policy.version}"`,
+              path: `operations.${operation.meta.key}.policy.fieldPolicies`
+            });
+          }
+        }
+      }
+    }
+  }
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+
+class PolicyValidationError extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "PolicyValidationError";
+  }
+}
+function assertPolicySpecValid(spec) {
+  const result = validatePolicySpec(spec);
+  if (!result.valid) {
+    throw new PolicyValidationError(`Policy ${spec.meta.key}.v${spec.meta.version} is invalid`, result.issues);
+  }
+}
+function assertPolicyConsistency(deps) {
+  const result = validatePolicyConsistency(deps);
+  if (!result.valid) {
+    throw new PolicyValidationError("Policy consistency check failed", result.issues);
+  }
+}
+export {
+  validatePolicySpec,
+  validatePolicyConsistency,
+  assertPolicySpecValid,
+  assertPolicyConsistency,
+  PolicyValidationError
+};

package/dist/policy/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/presentations/docs/presentations-conventions.docblock.d.ts

@@ -0,0 +1,2 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+export declare const tech_contracts_presentations_conventions_DocBlocks: DocBlock[];

package/dist/presentations/docs/presentations-conventions.docblock.js

@@ -0,0 +1,171 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/presentations/docs/presentations-conventions.docblock.ts
+var tech_contracts_presentations_conventions_DocBlocks = [
+  {
+    id: "docs.tech.contracts.presentations-conventions",
+    title: "Presentations Conventions (A11y & i18n)",
+    summary: "- Always provide `meta.description` (\u2265 3 chars) \u2014 used by a11y/docs/agents.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/presentations-conventions",
+    tags: ["tech", "contracts", "presentations-conventions"],
+    body: `## Presentations Conventions (A11y & i18n)
+
+- Always provide \`meta.description\` (\u2265 3 chars) \u2014 used by a11y/docs/agents.
+- Prefer source = BlockNote for rich guides; use component key for interactive flows.
+- i18n strings belong in host apps; descriptors carry keys/defaults only.
+- Target selection: include only what you intend to support to avoid drift.
+- PII: declare JSON-like paths under \`policy.pii\`; engine redacts in outputs.
+`
+  }
+];
+registerDocBlocks(tech_contracts_presentations_conventions_DocBlocks);
+export {
+  tech_contracts_presentations_conventions_DocBlocks
+};

package/dist/presentations/index.d.ts

@@ -0,0 +1,2 @@
+export * from './presentations';
+export * from './registry';