@topogram/cli 0.3.64 → 0.3.66

package/src/validator/kinds.d.ts

@@ -0,0 +1,41 @@
+export const STATEMENT_KINDS: Set<string>;
+export const IDENTIFIER_PATTERN: RegExp;
+export const DOMAIN_IDENTIFIER_PATTERN: RegExp;
+export const DOMAIN_TAGGABLE_KINDS: Set<string>;
+export const PITCH_IDENTIFIER_PATTERN: RegExp;
+export const REQUIREMENT_IDENTIFIER_PATTERN: RegExp;
+export const ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN: RegExp;
+export const TASK_IDENTIFIER_PATTERN: RegExp;
+export const BUG_IDENTIFIER_PATTERN: RegExp;
+export const DOCUMENT_IDENTIFIER_PATTERN: RegExp;
+export const GLOBAL_STATUSES: Set<string>;
+export const DECISION_STATUSES: Set<string>;
+export const RULE_SEVERITIES: Set<string>;
+export const VERIFICATION_METHODS: Set<string>;
+export const STATUS_SETS_BY_KIND: Record<string, Set<string>>;
+export const PITCH_STATUSES: Set<string>;
+export const REQUIREMENT_STATUSES: Set<string>;
+export const ACCEPTANCE_CRITERION_STATUSES: Set<string>;
+export const TASK_STATUSES: Set<string>;
+export const BUG_STATUSES: Set<string>;
+export const PRIORITY_VALUES: Set<string>;
+export const WORK_TYPES: Set<string>;
+export const BUG_SEVERITIES: Set<string>;
+export const DOC_TYPES: Set<string>;
+export const AUDIENCES: Set<string>;
+export const UI_SCREEN_KINDS: Set<string>;
+export const UI_COLLECTION_PRESENTATIONS: Set<string>;
+export const UI_NAVIGATION_PATTERNS: Set<string>;
+export const UI_REGION_KINDS: Set<string>;
+export const UI_PATTERN_KINDS: Set<string>;
+export const UI_APP_SHELL_KINDS: Set<string>;
+export const UI_WINDOWING_MODES: Set<string>;
+export const UI_STATE_KINDS: Set<string>;
+export const UI_DESIGN_DENSITIES: Set<string>;
+export const UI_DESIGN_TONES: Set<string>;
+export const UI_DESIGN_RADIUS_SCALES: Set<string>;
+export const UI_DESIGN_COLOR_ROLES: Set<string>;
+export const UI_DESIGN_TYPOGRAPHY_ROLES: Set<string>;
+export const UI_DESIGN_ACTION_ROLES: Set<string>;
+export const UI_DESIGN_ACCESSIBILITY_VALUES: Record<string, Set<string>>;
+export const FIELD_SPECS: Record<string, { required: string[]; allowed: string[] }>;

package/src/validator/kinds.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 export const STATEMENT_KINDS = new Set([
   "term",
   "actor",

package/src/validator/model-helpers.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+import {
+  blockEntries,
+  getFieldValue,
+  symbolValues
+} from "./utils.js";
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {string[]}
+ */
+export function statementFieldNames(statement) {
+  return blockEntries(getFieldValue(statement, "fields"))
+    .map((entry) => entry.items[0])
+    .filter((item) => item?.type === "symbol")
+    .map((item) => item.value);
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {string[]}
+ */
+export function resolveShapeBaseFieldNames(statement, registry) {
+  const explicitFieldNames = statementFieldNames(statement);
+  if (explicitFieldNames.length > 0) {
+    return explicitFieldNames;
+  }
+
+  if (!statement.from) {
+    return [];
+  }
+
+  const source = registry.get(statement.from.value);
+  if (!source || source.kind !== "entity") {
+    return [];
+  }
+
+  const sourceFieldNames = statementFieldNames(source);
+  const includeNames = symbolValues(getFieldValue(statement, "include"));
+  const excludeNames = new Set(symbolValues(getFieldValue(statement, "exclude")));
+  const selectedNames = includeNames.length > 0 ? includeNames.filter((name) => sourceFieldNames.includes(name)) : sourceFieldNames;
+
+  return selectedNames.filter((fieldName) => !excludeNames.has(fieldName));
+}

package/src/validator/per-kind/acceptance-criterion.js

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN
 } from "../kinds.js";
@@ -7,6 +8,7 @@ import {
   symbolValues
 } from "../utils.js";
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateAcIdentifier(errors, statement) {
   if (!ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN.test(statement.id)) {
     pushError(
@@ -17,6 +19,7 @@ function validateAcIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateRequirementRef(errors, statement, fieldMap, registry) {
   // Generic reference validator skips `requirement` (it's overloaded with
   // rule.requirement which is a string condition); validate the kind=requirement
@@ -50,6 +53,7 @@ function validateRequirementRef(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateSupersedes(errors, statement, fieldMap, registry) {
   const field = fieldMap.get("supersedes")?.[0];
   if (!field) return;
@@ -81,6 +85,7 @@ function validateSupersedes(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateAcceptanceCriterion(errors, statement, fieldMap, registry) {
   if (statement.kind !== "acceptance_criterion") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   BUG_IDENTIFIER_PATTERN,
   PRIORITY_VALUES,
@@ -9,6 +10,7 @@ import {
   symbolValues
 } from "../utils.js";
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateBugIdentifier(errors, statement) {
   if (!BUG_IDENTIFIER_PATTERN.test(statement.id)) {
     pushError(
@@ -19,6 +21,7 @@ function validateBugIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validatePriority(errors, statement, fieldMap) {
   const field = fieldMap.get("priority")?.[0];
   if (!field) return;
@@ -35,6 +38,7 @@ function validatePriority(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateSeverity(errors, statement, fieldMap) {
   const field = fieldMap.get("severity")?.[0];
   if (!field) return;
@@ -51,6 +55,7 @@ function validateSeverity(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateFixedInVerificationOnVerified(errors, statement, fieldMap) {
   // A bug in `verified` status must point at the verification that proved
   // the fix; this lets release-notes assemble a closed-loop record.
@@ -66,6 +71,7 @@ function validateFixedInVerificationOnVerified(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateBug(errors, statement, fieldMap, registry) {
   if (statement.kind !== "bug") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   DOMAIN_IDENTIFIER_PATTERN,
   DOMAIN_TAGGABLE_KINDS
@@ -11,6 +12,7 @@ import {
   valueAsArray
 } from "../utils.js";
 
+/** @param {TopogramToken} value @returns {boolean} */
 function isStringOrSymbolList(value) {
   for (const item of valueAsArray(value)) {
     if (item.type !== "string" && item.type !== "symbol") {
@@ -20,6 +22,7 @@ function isStringOrSymbolList(value) {
   return true;
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateDomainIdentifier(errors, statement) {
   if (statement.kind !== "domain") {
     return;
@@ -33,6 +36,7 @@ function validateDomainIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateScopeFields(errors, statement, fieldMap) {
   if (statement.kind !== "domain") {
     return;
@@ -50,6 +54,7 @@ function validateScopeFields(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateParentDomain(errors, statement, fieldMap, registry) {
   if (statement.kind !== "domain") {
     return;
@@ -94,6 +99,7 @@ function validateParentDomain(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateOwners(errors, statement, fieldMap, registry) {
   if (statement.kind !== "domain") {
     return;
@@ -121,6 +127,7 @@ function validateOwners(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function detectParentDomainCycle(errors, statement, fieldMap, registry) {
   if (statement.kind !== "domain") {
     return;
@@ -129,7 +136,9 @@ function detectParentDomainCycle(errors, statement, fieldMap, registry) {
   if (!field) return;
 
   const seen = new Set([statement.id]);
-  let cursor = registry.get(symbolValue(field.value));
+  const parentId = symbolValue(field.value);
+  if (!parentId) return;
+  let cursor = registry.get(parentId);
   while (cursor && cursor.kind === "domain") {
     if (seen.has(cursor.id)) {
       pushError(
@@ -142,10 +151,13 @@ function detectParentDomainCycle(errors, statement, fieldMap, registry) {
     seen.add(cursor.id);
     const parentField = cursor.fields.find((f) => f.key === "parent_domain");
     if (!parentField) break;
-    cursor = registry.get(symbolValue(parentField.value));
+    const nextParentId = symbolValue(parentField.value);
+    if (!nextParentId) break;
+    cursor = registry.get(nextParentId);
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateDomain(errors, statement, fieldMap, registry) {
   if (statement.kind !== "domain") {
     return;
@@ -160,6 +172,7 @@ export function validateDomain(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).
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateDomainTag(errors, statement, fieldMap, registry) {
   if (statement.kind === "domain") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   PITCH_IDENTIFIER_PATTERN,
   PRIORITY_VALUES
@@ -8,6 +9,7 @@ import {
   symbolValues
 } from "../utils.js";
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validatePitchIdentifier(errors, statement) {
   if (!PITCH_IDENTIFIER_PATTERN.test(statement.id)) {
     pushError(
@@ -18,6 +20,7 @@ function validatePitchIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validatePriority(errors, statement, fieldMap) {
   const field = fieldMap.get("priority")?.[0];
   if (!field) return;
@@ -34,6 +37,7 @@ function validatePriority(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateAppetite(errors, statement, fieldMap) {
   const field = fieldMap.get("appetite")?.[0];
   if (!field) return;
@@ -46,6 +50,7 @@ function validateAppetite(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 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
@@ -66,6 +71,7 @@ function validateShapingFields(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateDecisionRefs(errors, statement, fieldMap, registry) {
   const field = fieldMap.get("decisions")?.[0];
   if (!field) return;
@@ -89,6 +95,7 @@ function validateDecisionRefs(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validatePitch(errors, statement, fieldMap, registry) {
   if (statement.kind !== "pitch") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   REQUIREMENT_IDENTIFIER_PATTERN,
   PRIORITY_VALUES
@@ -8,6 +9,7 @@ import {
   symbolValues
 } from "../utils.js";
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateRequirementIdentifier(errors, statement) {
   if (!REQUIREMENT_IDENTIFIER_PATTERN.test(statement.id)) {
     pushError(
@@ -18,6 +20,7 @@ function validateRequirementIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validatePriority(errors, statement, fieldMap) {
   const field = fieldMap.get("priority")?.[0];
   if (!field) return;
@@ -34,6 +37,7 @@ function validatePriority(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateSupersedes(errors, statement, fieldMap, registry) {
   const field = fieldMap.get("supersedes")?.[0];
   if (!field) return;
@@ -65,6 +69,7 @@ function validateSupersedes(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateRequirement(errors, statement, fieldMap, registry) {
   if (statement.kind !== "requirement") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   TASK_IDENTIFIER_PATTERN,
   PRIORITY_VALUES,
@@ -9,6 +10,7 @@ import {
   symbolValues
 } from "../utils.js";
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateTaskIdentifier(errors, statement) {
   if (!TASK_IDENTIFIER_PATTERN.test(statement.id)) {
     pushError(
@@ -19,6 +21,7 @@ function validateTaskIdentifier(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validatePriority(errors, statement, fieldMap) {
   const field = fieldMap.get("priority")?.[0];
   if (!field) return;
@@ -35,6 +38,7 @@ function validatePriority(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateWorkType(errors, statement, fieldMap) {
   const field = fieldMap.get("work_type")?.[0];
   if (!field) return;
@@ -51,6 +55,7 @@ function validateWorkType(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateBlockingPair(errors, statement, fieldMap, registry) {
   // Self-block guard. Reciprocal `blocks` <-> `blocked_by` resolution is the
   // resolver's job; here we just guard against trivial cycles.
@@ -69,6 +74,7 @@ function validateBlockingPair(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateClaimedByPresence(errors, statement, fieldMap) {
   // claimed/in-progress/done all require a claimed_by; unclaimed/blocked do not.
   const statusField = fieldMap.get("status")?.[0];
@@ -84,6 +90,7 @@ function validateClaimedByPresence(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateTask(errors, statement, fieldMap, registry) {
   if (statement.kind !== "task") {
     return;

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

@@ -1,3 +1,4 @@
+// @ts-check
 import {
   UI_PATTERN_KINDS,
   UI_REGION_KINDS
@@ -36,6 +37,7 @@ const WIDGET_BEHAVIOR_KINDS = new Set([
   "keyboard_navigation"
 ]);
 
+/** @type {Record<string, Set<string>>} */
 const WIDGET_BEHAVIOR_DIRECTIVES = {
   selection: new Set(["mode", "state", "emits"]),
   sorting: new Set(["fields", "default"]),
@@ -51,10 +53,12 @@ const WIDGET_BEHAVIOR_DIRECTIVES = {
   keyboard_navigation: new Set(["scope", "shortcuts"])
 };
 
+/** @param {TopogramToken | null | undefined} token @returns {any} */
 function tokenValue(token) {
   return token?.value ?? null;
 }
 
+/** @param {TopogramToken | null | undefined} token @returns {any[]} */
 function tokenValues(token) {
   if (!token) {
     return [];
@@ -66,6 +70,7 @@ function tokenValues(token) {
   return value == null ? [] : [value];
 }
 
+/** @param {TopogramStatement} statement @returns {Set<any>} */
 function widgetPropNames(statement) {
   return new Set(blockEntries(getFieldValue(statement, "props"))
     .map((entry) => entry.items[0])
@@ -73,6 +78,7 @@ function widgetPropNames(statement) {
     .map((item) => item.value));
 }
 
+/** @param {TopogramStatement} statement @returns {Set<any>} */
 function widgetEventNames(statement) {
   return new Set(blockEntries(getFieldValue(statement, "events"))
     .map((entry) => entry.items[0])
@@ -80,6 +86,7 @@ function widgetEventNames(statement) {
     .map((item) => item.value));
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
 function validateWidgetCategory(errors, statement, fieldMap) {
   const field = fieldMap.get("category")?.[0];
   if (!field) {
@@ -96,6 +103,7 @@ function validateWidgetCategory(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateWidgetProps(errors, statement) {
   for (const entry of blockEntries(getFieldValue(statement, "props"))) {
     const [name, type, requiredness, ...rest] = entry.items;
@@ -127,6 +135,7 @@ function validateWidgetProps(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramRegistry} registry */
 function validateWidgetEvents(errors, statement, registry) {
   for (const entry of blockEntries(getFieldValue(statement, "events"))) {
     const [eventName, shapeRef] = entry.items;
@@ -151,6 +160,7 @@ function validateWidgetEvents(errors, statement, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
 function validateWidgetSlots(errors, statement) {
   for (const entry of blockEntries(getFieldValue(statement, "slots"))) {
     const [slotName, description] = entry.items;
@@ -165,6 +175,7 @@ function validateWidgetSlots(errors, statement) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {string} key @param {Set<string>} allowed @param {string} label */
 function validateSymbolList(errors, statement, fieldMap, key, allowed, label) {
   const field = fieldMap.get(key)?.[0];
   if (!field) {
@@ -178,6 +189,7 @@ function validateSymbolList(errors, statement, fieldMap, key, allowed, label) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramRegistry} registry @param {any} kind @param {any} directive @param {TopogramToken} valueToken @param {Set<any>} eventNames */
 function validateBehaviorActionReferences(errors, statement, registry, kind, directive, valueToken, eventNames) {
   for (const actionId of tokenValues(valueToken)) {
     if (eventNames.has(actionId)) {
@@ -195,6 +207,7 @@ function validateBehaviorActionReferences(errors, statement, registry, kind, dir
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateWidgetBehaviors(errors, statement, fieldMap, registry) {
   validateSymbolList(errors, statement, fieldMap, "behavior", WIDGET_BEHAVIOR_KINDS, "behavior");
 
@@ -259,6 +272,7 @@ function validateWidgetBehaviors(errors, statement, fieldMap, registry) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 export function validateWidget(errors, statement, fieldMap, registry) {
   if (statement.kind !== "widget") {
     return;