unspaghettit 0.2.0 → 0.4.0

package/mcp-server/tools/specGaps.ts

@@ -1,221 +1,221 @@
-import { z } from 'zod';
-import type { Action } from '../../src/features/behavior-model/domain/entities/Action';
-import { isEvolution } from '../../src/features/behavior-model/domain/entities/Action';
-import type { Feature } from '../../src/features/behavior-model/domain/entities/Feature';
-import type { Surface } from '../../src/features/behavior-model/domain/entities/Surface';
-import { asFeatureId } from '../../src/features/behavior-model/domain/value-objects/ids';
-import { trackTokens } from '../metrics';
-import { errorText, text, type ToolDeps } from './_shared';
-import { expandFeatureId } from './short-ids';
-
-type Severity = 'critical' | 'recommended';
-type EntityKind = 'feature' | 'surface' | 'action';
-
-export type SpecGap = {
-  readonly severity: Severity;
-  readonly entityType: EntityKind;
-  readonly entityId: string;
-  readonly entityName: string;
-  readonly reason: string;
-  readonly suggestedFix: string;
-};
-
-const normalizeName = (s: string): string => s.trim().toLowerCase();
-
-const hasLoadingOrErrorCoverage = (action: Action): boolean => {
-  const scenarios = action.scenarios ?? [];
-  return scenarios.some((sc) => {
-    const overridePaths = sc.stateOverrides.map((o) => String(o.path).toLowerCase());
-    const assertionPaths = (sc.expectedAssertions ?? []).map((a) =>
-      String(a.path).toLowerCase()
-    );
-    const all = [...overridePaths, ...assertionPaths];
-    return all.some((p) => p.includes('loading') || p.includes('error'));
-  });
-};
-
-const hasBlockingValidationRule = (action: Action): boolean =>
-  action.rules.some(
-    (r) => r.condition.operator === 'is_false' || r.condition.operator === 'does_not_exist'
-  );
-
-/**
- * Pure detector. Walks the feature + implementation-status sidecar and
- * returns spec-depth gaps in priority order: critical first, then
- * recommended; stable surface-index / action-index ordering within each
- * group. Reuses existing entity references, no new validation fork.
- */
-export const detectSpecGaps = (
-  feature: Feature,
-  implementedCapabilityIds: ReadonlySet<string>
-): readonly SpecGap[] => {
-  const critical: SpecGap[] = [];
-  const recommended: SpecGap[] = [];
-
-  // Evolution proposals (dashed placeholders) are not committed behavior, so
-  // a proposal named "Sign in with SSO" must NOT satisfy an expectedActions
-  // entry of the same name.
-  const allActionNames = new Set<string>();
-  for (const s of feature.surfaces) {
-    for (const c of s.actions) {
-      if (!isEvolution(c)) allActionNames.add(normalizeName(c.name));
-    }
-  }
-
-  // Feature-level: expectedActions without a matching Action.
-  for (const expected of feature.expectedActions ?? []) {
-    if (!allActionNames.has(normalizeName(expected))) {
-      critical.push({
-        severity: 'critical',
-        entityType: 'feature',
-        entityId: String(feature.id),
-        entityName: feature.name,
-        reason: `expectedActions entry "${expected}" has no matching Action.`,
-        suggestedFix: `Add an Action for ${expected}`
-      });
-    }
-  }
-
-  // A surface counts as having state if it owns at least one stateDefinition
-  // OR another surface shares one into it via stateDefinition.sharedWith.
-  // Without this, a modal that legitimately operates entirely on shared state
-  // (e.g. a payment-hold modal sharing payment.* from the parent screen)
-  // gets flagged as critical even though every action on it reads + writes
-  // state.
-  const sharedIntoSurface = new Set<string>();
-  for (const s of feature.surfaces) {
-    for (const def of s.stateDefinitions) {
-      for (const target of def.sharedWith ?? []) {
-        sharedIntoSurface.add(String(target));
-      }
-    }
-  }
-
-  feature.surfaces.forEach((surface: Surface, surfaceIndex: number) => {
-    if (
-      surface.stateDefinitions.length === 0 &&
-      !sharedIntoSurface.has(String(surface.id))
-    ) {
-      critical.push({
-        severity: 'critical',
-        entityType: 'surface',
-        entityId: String(surface.id),
-        entityName: surface.name,
-        reason: `Surface "${surface.name}" has no stateDefinitions.`,
-        suggestedFix: 'Define at least one state path'
-      });
-    }
-
-    surface.actions.forEach((cap: Action, capIndex: number) => {
-      // Skip Evolution proposals entirely: they're intentionally empty
-      // dashed placeholders, so every gap check (no effects, no impl status…)
-      // would fire falsely. They re-enter analysis once accepted.
-      if (isEvolution(cap)) {
-        void capIndex;
-        return;
-      }
-      const roles = new Set<string>(cap.roles ?? []);
-
-      if (cap.effects.length === 0) {
-        critical.push({
-          severity: 'critical',
-          entityType: 'action',
-          entityId: String(cap.id),
-          entityName: cap.name,
-          reason: `Action "${cap.name}" has no effects.`,
-          suggestedFix: 'Add at least one effect'
-        });
-      }
-
-      if (roles.has('destructive') && (cap.scenarios ?? []).length === 0) {
-        critical.push({
-          severity: 'critical',
-          entityType: 'action',
-          entityId: String(cap.id),
-          entityName: cap.name,
-          reason: `Destructive action "${cap.name}" has no scenario covering its path.`,
-          suggestedFix: 'Add a scenario covering the destructive path'
-        });
-      }
-
-      if (roles.has('async') && !hasLoadingOrErrorCoverage(cap)) {
-        recommended.push({
-          severity: 'recommended',
-          entityType: 'action',
-          entityId: String(cap.id),
-          entityName: cap.name,
-          reason: `Async action "${cap.name}" has no scenario setting or asserting a loading/error state.`,
-          suggestedFix: 'Add loading + error scenarios'
-        });
-      }
-
-      if (roles.has('validation') && !hasBlockingValidationRule(cap)) {
-        recommended.push({
-          severity: 'recommended',
-          entityType: 'action',
-          entityId: String(cap.id),
-          entityName: cap.name,
-          reason: `Validation action "${cap.name}" has no rule with operator is_false/does_not_exist.`,
-          suggestedFix: 'Add a rule blocking invalid input'
-        });
-      }
-
-      if (!implementedCapabilityIds.has(String(cap.id))) {
-        recommended.push({
-          severity: 'recommended',
-          entityType: 'action',
-          entityId: String(cap.id),
-          entityName: cap.name,
-          reason: `Action "${cap.name}" has no ImplementationStatus entry.`,
-          suggestedFix: 'Report implementation via report_implementation_status'
-        });
-      }
-
-      // surfaceIndex / capIndex are captured implicitly: forEach iterates in
-      // declaration order and we push as we go.
-      void surfaceIndex;
-      void capIndex;
-    });
-
-    if (surface.stateDefinitions.length > 1 && surface.transitions.length === 0) {
-      recommended.push({
-        severity: 'recommended',
-        entityType: 'surface',
-        entityId: String(surface.id),
-        entityName: surface.name,
-        reason: `Surface "${surface.name}" declares multiple states but no transitions wire them.`,
-        suggestedFix: 'Add transitions wiring the states'
-      });
-    }
-  });
-
-  return [...critical, ...recommended];
-};
-
-export const registerSpecGapsTool = (deps: ToolDeps): void => {
-  const { server, repo, getImplementationStatus } = deps;
-
-  server.registerTool(
-    'get_spec_gaps',
-    {
-      description:
-        'Diagnose spec depth: returns a prioritized to-do list of critical + recommended gaps grounded in existing entities. Critical gaps must be resolved before claiming the spec complete (missing expectedActions, stateless surfaces, effect-less actions, untested destructive actions). Recommended gaps catch shallow modeling (async without loading/error coverage, validation without blocking rule, multi-state surface without transitions, action never implemented). Use after build/edit sessions, especially after a "don\'t-ask-just-build" pass.',
-      inputSchema: { featureId: z.string() }
-    },
-    async ({ featureId }) => {
-      try {
-        featureId = await expandFeatureId(repo, featureId);
-      } catch (e) {
-        return errorText((e as Error).message);
-      }
-      const exp = await repo.get(asFeatureId(featureId));
-      if (!exp) return errorText(`Feature ${featureId} not found`);
-      const status = await getImplementationStatus(asFeatureId(featureId));
-      const implementedIds = new Set<string>(
-        (status?.actions ?? []).map((c) => String(c.actionId))
-      );
-      const gaps = detectSpecGaps(exp, implementedIds);
-      return text(trackTokens('get_spec_gaps', { gaps }));
-    }
-  );
-};
+import { z } from 'zod';
+import type { Action } from '../../src/features/behavior-model/domain/entities/Action';
+import { isEvolution } from '../../src/features/behavior-model/domain/entities/Action';
+import type { Feature } from '../../src/features/behavior-model/domain/entities/Feature';
+import type { Surface } from '../../src/features/behavior-model/domain/entities/Surface';
+import { asFeatureId } from '../../src/features/behavior-model/domain/value-objects/ids';
+import { trackTokens } from '../metrics';
+import { errorText, text, type ToolDeps } from './_shared';
+import { expandFeatureId } from './short-ids';
+
+type Severity = 'critical' | 'recommended';
+type EntityKind = 'feature' | 'surface' | 'action';
+
+export type SpecGap = {
+  readonly severity: Severity;
+  readonly entityType: EntityKind;
+  readonly entityId: string;
+  readonly entityName: string;
+  readonly reason: string;
+  readonly suggestedFix: string;
+};
+
+const normalizeName = (s: string): string => s.trim().toLowerCase();
+
+const hasLoadingOrErrorCoverage = (action: Action): boolean => {
+  const scenarios = action.scenarios ?? [];
+  return scenarios.some((sc) => {
+    const overridePaths = sc.stateOverrides.map((o) => String(o.path).toLowerCase());
+    const assertionPaths = (sc.expectedAssertions ?? []).map((a) =>
+      String(a.path).toLowerCase()
+    );
+    const all = [...overridePaths, ...assertionPaths];
+    return all.some((p) => p.includes('loading') || p.includes('error'));
+  });
+};
+
+const hasBlockingValidationRule = (action: Action): boolean =>
+  action.rules.some(
+    (r) => r.condition.operator === 'is_false' || r.condition.operator === 'does_not_exist'
+  );
+
+/**
+ * Pure detector. Walks the feature + implementation-status sidecar and
+ * returns spec-depth gaps in priority order: critical first, then
+ * recommended; stable surface-index / action-index ordering within each
+ * group. Reuses existing entity references, no new validation fork.
+ */
+export const detectSpecGaps = (
+  feature: Feature,
+  implementedCapabilityIds: ReadonlySet<string>
+): readonly SpecGap[] => {
+  const critical: SpecGap[] = [];
+  const recommended: SpecGap[] = [];
+
+  // Evolution proposals (dashed placeholders) are not committed behavior, so
+  // a proposal named "Sign in with SSO" must NOT satisfy an expectedActions
+  // entry of the same name.
+  const allActionNames = new Set<string>();
+  for (const s of feature.surfaces) {
+    for (const c of s.actions) {
+      if (!isEvolution(c)) allActionNames.add(normalizeName(c.name));
+    }
+  }
+
+  // Feature-level: expectedActions without a matching Action.
+  for (const expected of feature.expectedActions ?? []) {
+    if (!allActionNames.has(normalizeName(expected))) {
+      critical.push({
+        severity: 'critical',
+        entityType: 'feature',
+        entityId: String(feature.id),
+        entityName: feature.name,
+        reason: `expectedActions entry "${expected}" has no matching Action.`,
+        suggestedFix: `Add an Action for ${expected}`
+      });
+    }
+  }
+
+  // A surface counts as having state if it owns at least one stateDefinition
+  // OR another surface shares one into it via stateDefinition.sharedWith.
+  // Without this, a modal that legitimately operates entirely on shared state
+  // (e.g. a payment-hold modal sharing payment.* from the parent screen)
+  // gets flagged as critical even though every action on it reads + writes
+  // state.
+  const sharedIntoSurface = new Set<string>();
+  for (const s of feature.surfaces) {
+    for (const def of s.stateDefinitions) {
+      for (const target of def.sharedWith ?? []) {
+        sharedIntoSurface.add(String(target));
+      }
+    }
+  }
+
+  feature.surfaces.forEach((surface: Surface, surfaceIndex: number) => {
+    if (
+      surface.stateDefinitions.length === 0 &&
+      !sharedIntoSurface.has(String(surface.id))
+    ) {
+      critical.push({
+        severity: 'critical',
+        entityType: 'surface',
+        entityId: String(surface.id),
+        entityName: surface.name,
+        reason: `Surface "${surface.name}" has no stateDefinitions.`,
+        suggestedFix: 'Define at least one state path'
+      });
+    }
+
+    surface.actions.forEach((cap: Action, capIndex: number) => {
+      // Skip Evolution proposals entirely: they're intentionally empty
+      // dashed placeholders, so every gap check (no effects, no impl status…)
+      // would fire falsely. They re-enter analysis once accepted.
+      if (isEvolution(cap)) {
+        void capIndex;
+        return;
+      }
+      const roles = new Set<string>(cap.roles ?? []);
+
+      if (cap.effects.length === 0) {
+        critical.push({
+          severity: 'critical',
+          entityType: 'action',
+          entityId: String(cap.id),
+          entityName: cap.name,
+          reason: `Action "${cap.name}" has no effects.`,
+          suggestedFix: 'Add at least one effect'
+        });
+      }
+
+      if (roles.has('destructive') && (cap.scenarios ?? []).length === 0) {
+        critical.push({
+          severity: 'critical',
+          entityType: 'action',
+          entityId: String(cap.id),
+          entityName: cap.name,
+          reason: `Destructive action "${cap.name}" has no scenario covering its path.`,
+          suggestedFix: 'Add a scenario covering the destructive path'
+        });
+      }
+
+      if (roles.has('async') && !hasLoadingOrErrorCoverage(cap)) {
+        recommended.push({
+          severity: 'recommended',
+          entityType: 'action',
+          entityId: String(cap.id),
+          entityName: cap.name,
+          reason: `Async action "${cap.name}" has no scenario setting or asserting a loading/error state.`,
+          suggestedFix: 'Add loading + error scenarios'
+        });
+      }
+
+      if (roles.has('validation') && !hasBlockingValidationRule(cap)) {
+        recommended.push({
+          severity: 'recommended',
+          entityType: 'action',
+          entityId: String(cap.id),
+          entityName: cap.name,
+          reason: `Validation action "${cap.name}" has no rule with operator is_false/does_not_exist.`,
+          suggestedFix: 'Add a rule blocking invalid input'
+        });
+      }
+
+      if (!implementedCapabilityIds.has(String(cap.id))) {
+        recommended.push({
+          severity: 'recommended',
+          entityType: 'action',
+          entityId: String(cap.id),
+          entityName: cap.name,
+          reason: `Action "${cap.name}" has no ImplementationStatus entry.`,
+          suggestedFix: 'Report implementation via report_implementation_status'
+        });
+      }
+
+      // surfaceIndex / capIndex are captured implicitly: forEach iterates in
+      // declaration order and we push as we go.
+      void surfaceIndex;
+      void capIndex;
+    });
+
+    if (surface.stateDefinitions.length > 1 && surface.transitions.length === 0) {
+      recommended.push({
+        severity: 'recommended',
+        entityType: 'surface',
+        entityId: String(surface.id),
+        entityName: surface.name,
+        reason: `Surface "${surface.name}" declares multiple states but no transitions wire them.`,
+        suggestedFix: 'Add transitions wiring the states'
+      });
+    }
+  });
+
+  return [...critical, ...recommended];
+};
+
+export const registerSpecGapsTool = (deps: ToolDeps): void => {
+  const { server, repo, getImplementationStatus } = deps;
+
+  server.registerTool(
+    'get_spec_gaps',
+    {
+      description:
+        'Diagnose spec depth: returns a prioritized to-do list of critical + recommended gaps grounded in existing entities. Critical gaps must be resolved before claiming the spec complete (missing expectedActions, stateless surfaces, effect-less actions, untested destructive actions). Recommended gaps catch shallow modeling (async without loading/error coverage, validation without blocking rule, multi-state surface without transitions, action never implemented). Use after build/edit sessions, especially after a "don\'t-ask-just-build" pass.',
+      inputSchema: { featureId: z.string() }
+    },
+    async ({ featureId }) => {
+      try {
+        featureId = await expandFeatureId(repo, featureId);
+      } catch (e) {
+        return errorText((e as Error).message);
+      }
+      const exp = await repo.get(asFeatureId(featureId));
+      if (!exp) return errorText(`Feature ${featureId} not found`);
+      const status = await getImplementationStatus(asFeatureId(featureId));
+      const implementedIds = new Set<string>(
+        (status?.actions ?? []).map((c) => String(c.actionId))
+      );
+      const gaps = detectSpecGaps(exp, implementedIds);
+      return text(trackTokens('get_spec_gaps', { gaps }));
+    }
+  );
+};

package/mcp-server/tools/state.ts

@@ -32,13 +32,14 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
     'add_state_definition',
     {
       description:
-        'Declare schema for a state path on a Surface (path, type, default). When type=enum, supply EITHER inline enumValues OR a valueSetId referencing a feature-level value set (add_value_set) — not both. sharedWith[] lists other surfaces that also read/write this path. Declarative only (the runtime snapshot is global), but it lets the dashboard render cross-surface state sharing honestly.',
+        'Declare schema for a state path on a Surface (path, type, default). When type=enum, supply EITHER inline enumValues OR a valueSetId referencing a feature-level value set (add_value_set) — not both. sharedWith[] lists other surfaces that also read/write this path. Declarative only (the runtime snapshot is global), but it lets the dashboard render cross-surface state sharing honestly. Pass `derived` (an Expression, same AST as set_state.value) to make the path COMPUTED: the engine recomputes it after every mutation, so e.g. cart.subtotal stays correct without any action re-setting it. Derived paths are read-only — effects that write them are rejected. defaultValue is still required (used before the first compute / when the expression cannot evaluate). Example: derived:{ kind:"sum_pluck", operand:{kind:"state",path:"cart.lines"}, field:"amount" }.',
       inputSchema: {
         featureId: z.string(),
         surfaceId: z.string(),
         path: z.string(),
         type: stateTypeSchema,
         defaultValue: z.unknown(),
+        derived: z.unknown().optional(),
         enumValues: z.array(z.string()).optional(),
         valueSetId: z.string().optional(),
         description: z.string().min(1),
@@ -51,6 +52,7 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
       path,
       type,
       defaultValue,
+      derived,
       enumValues,
       valueSetId,
       description,
@@ -61,6 +63,7 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
         path: asStatePath(path),
         type: type as StateType,
         defaultValue: coerceScalarByType(defaultValue, type) as StateDefinition['defaultValue'],
+        ...(derived !== undefined ? { derived: derived as StateDefinition['derived'] } : {}),
         ...(enumValues ? { enumValues } : {}),
         ...(valueSetId ? { valueSetId: asValueSetId(valueSetId) } : {}),
         description,
@@ -82,7 +85,7 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
   server.registerTool(
     'update_state_definition',
     {
-      description: 'Patch StateDefinition fields. Path renames are not auto-rewritten. Run find_state_references first. sharedWith:[] clears all sharing entries. valueSetId references a feature-level value set (mutually exclusive with enumValues); valueSetId:null clears it.',
+      description: 'Patch StateDefinition fields. Path renames are not auto-rewritten. Run find_state_references first. sharedWith:[] clears all sharing entries. valueSetId references a feature-level value set (mutually exclusive with enumValues); valueSetId:null clears it. `derived` (an Expression) makes the path computed/read-only; derived:null clears it back to an authored path.',
       inputSchema: {
         featureId: z.string(),
         surfaceId: z.string(),
@@ -90,6 +93,7 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
         path: z.string().optional(),
         type: stateTypeSchema.optional(),
         defaultValue: z.unknown().optional(),
+        derived: z.unknown().optional(),
         enumValues: z.array(z.string()).optional(),
         valueSetId: z.string().nullable().optional(),
         description: z.string().min(1).optional(),
@@ -103,6 +107,7 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
       path,
       type,
       defaultValue,
+      derived,
       enumValues,
       valueSetId,
       description,
@@ -118,6 +123,9 @@ export const registerStateDefinitionTools = (deps: ToolDeps): void => {
             {
               ...(path !== undefined ? { path: asStatePath(path) } : {}),
               ...(type !== undefined ? { type: type as StateType } : {}),
+              ...(derived !== undefined
+                ? { derived: derived === null ? undefined : (derived as StateDefinition['derived']) }
+                : {}),
               ...(defaultValue !== undefined
                 ? {
                     defaultValue: coerceScalarByType(