gswd 0.1.0

package/lib/specify-journeys.ts

@@ -0,0 +1,410 @@
+/**
+ * GSWD Specify Journeys Module — Journey generation, FR extraction, cross-linking
+ *
+ * Produces journey structures and extracts functional requirements from journey steps.
+ * Bidirectional cross-linking: journeys reference FR IDs, FRs reference source journeys.
+ *
+ * Schema: GSWD_SPEC.md Section 6.1 (ID formats), 6.2 (scope tagging), 8.3 (specify workflow)
+ */
+
+import { normalizeId } from './parse.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type JourneyType =
+  | 'onboarding'
+  | 'core_action'
+  | 'view_results'
+  | 'settings'
+  | 'error_states'
+  | 'empty_states';
+
+export interface FailureMode {
+  /** Concise scenario description (1-2 sentences max) */
+  scenario: string;
+  /** How the system handles this failure */
+  handling: string;
+}
+
+export interface JourneyStep {
+  /** Step number (1-based) */
+  number: number;
+  /** User action description */
+  action: string;
+  /** FR-XXX IDs derived from this step (populated during extraction) */
+  frIds: string[];
+}
+
+export interface Journey {
+  /** Journey ID in J-001 format */
+  id: string;
+  /** Human-readable journey name */
+  name: string;
+  /** Journey type category */
+  type: JourneyType;
+  /** Conditions that must be true before journey starts */
+  preconditions: string[];
+  /** Ordered user action steps (5-8 for main, 3+ for error/empty) */
+  steps: JourneyStep[];
+  /** Successful completion outcome */
+  success: string;
+  /** Failure scenarios (>= 2 required) */
+  failureModes: FailureMode[];
+  /** Single assertable test statements (>= 1 required) */
+  acceptanceTests: string[];
+  /** FR-XXX IDs linked to this journey (populated after extraction) */
+  linkedFRs: string[];
+  /** NFR-XXX IDs linked to this journey (populated later) */
+  linkedNFRs: string[];
+}
+
+export interface FunctionalRequirement {
+  /** FR ID in FR-001 format */
+  id: string;
+  /** What this requirement describes */
+  description: string;
+  /** Scope tag: v1/v2/out */
+  scope: 'v1' | 'v2' | 'out';
+  /** Priority: P0 (blocks core), P1 (required v1), P2 (enhances) */
+  priority: 'P0' | 'P1' | 'P2';
+  /** J-XXX IDs of source journeys */
+  sourceJourneys: string[];
+  /** "J-XXX step N" format references */
+  sourceSteps: string[];
+}
+
+export interface TraceabilityEntry {
+  /** FR ID */
+  frId: string;
+  /** FR description */
+  description: string;
+  /** Formatted journey references: "J-001 (step 3), J-002 (step 1)" */
+  journeyRefs: string[];
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * All 6 required journey types from GSWD_SPEC Section 8.3.
+ */
+export const JOURNEY_TYPES: { type: JourneyType; displayName: string }[] = [
+  { type: 'onboarding', displayName: 'Onboarding' },
+  { type: 'core_action', displayName: 'Core Action' },
+  { type: 'view_results', displayName: 'View Results/History' },
+  { type: 'settings', displayName: 'Settings/Preferences' },
+  { type: 'error_states', displayName: 'Error States' },
+  { type: 'empty_states', displayName: 'Empty States' },
+];
+
+/** Journey types that allow fewer steps (minimum 3 instead of 5) */
+const REDUCED_STEP_TYPES: JourneyType[] = ['error_states', 'empty_states'];
+
+// ─── Scope & Priority Heuristics ────────────────────────────────────────────
+
+/**
+ * Assign scope based on journey type.
+ * Heuristic from CONTEXT.md locked decisions:
+ * - core_action/onboarding → v1
+ * - error_states/empty_states → v1 (required for polish)
+ * - view_results → v1
+ * - settings → v1 (default; caller can override to v2 for non-essential)
+ */
+export function assignScope(journeyType: JourneyType): 'v1' | 'v2' | 'out' {
+  switch (journeyType) {
+    case 'onboarding':
+    case 'core_action':
+    case 'view_results':
+    case 'error_states':
+    case 'empty_states':
+    case 'settings':
+      return 'v1';
+    default:
+      return 'v1';
+  }
+}
+
+/**
+ * Assign priority based on journey type.
+ * Heuristic from CONTEXT.md locked decisions:
+ * - core_action/onboarding → P0 (blocks core journey)
+ * - error_states/empty_states/view_results/settings → P1 (required for complete v1)
+ */
+export function assignPriority(journeyType: JourneyType): 'P0' | 'P1' | 'P2' {
+  switch (journeyType) {
+    case 'core_action':
+    case 'onboarding':
+      return 'P0';
+    case 'error_states':
+    case 'empty_states':
+    case 'view_results':
+    case 'settings':
+      return 'P1';
+    default:
+      return 'P1';
+  }
+}
+
+// ─── Journey Structure Generation ───────────────────────────────────────────
+
+/**
+ * Format a journey ID: J-001, J-002, etc.
+ */
+function formatJourneyId(journeyNumber: number): string {
+  return normalizeId(`J-${journeyNumber}`);
+}
+
+/**
+ * Create a journey skeleton with proper ID and empty arrays.
+ */
+export function generateJourneyStructure(
+  type: JourneyType,
+  journeyNumber: number
+): Journey {
+  const typeInfo = JOURNEY_TYPES.find((t) => t.type === type);
+  const displayName = typeInfo ? typeInfo.displayName : type;
+
+  return {
+    id: formatJourneyId(journeyNumber),
+    name: displayName,
+    type,
+    preconditions: [],
+    steps: [],
+    success: '',
+    failureModes: [],
+    acceptanceTests: [],
+    linkedFRs: [],
+    linkedNFRs: [],
+  };
+}
+
+// ─── Journey Validation ─────────────────────────────────────────────────────
+
+/**
+ * Validate a journey meets all structural requirements.
+ */
+export function validateJourney(
+  journey: Journey
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // ID format check
+  if (!/^J-\d{3,}$/.test(journey.id)) {
+    errors.push(`Invalid journey ID format: ${journey.id} (expected J-XXX)`);
+  }
+
+  // Minimum step count: 3 for error/empty, 5 for main journeys
+  const minSteps = REDUCED_STEP_TYPES.includes(journey.type) ? 3 : 5;
+  if (journey.steps.length < minSteps) {
+    errors.push(
+      `Journey ${journey.id} has ${journey.steps.length} steps, minimum is ${minSteps} for type '${journey.type}'`
+    );
+  }
+
+  // Maximum step count: 8 recommended
+  if (journey.steps.length > 8) {
+    errors.push(
+      `Journey ${journey.id} has ${journey.steps.length} steps, recommended maximum is 8`
+    );
+  }
+
+  // Failure modes >= 2
+  if (journey.failureModes.length < 2) {
+    errors.push(
+      `Journey ${journey.id} has ${journey.failureModes.length} failure modes, minimum is 2`
+    );
+  }
+
+  // Acceptance tests >= 1
+  if (journey.acceptanceTests.length < 1) {
+    errors.push(
+      `Journey ${journey.id} has ${journey.acceptanceTests.length} acceptance tests, minimum is 1`
+    );
+  }
+
+  // Failure mode conciseness (max 200 chars per scenario)
+  for (const fm of journey.failureModes) {
+    if (fm.scenario.length > 200) {
+      errors.push(
+        `Journey ${journey.id} failure mode too long (${fm.scenario.length} chars, max 200): "${fm.scenario.substring(0, 50)}..."`
+      );
+    }
+  }
+
+  // Acceptance test conciseness (max 200 chars, single statement)
+  for (const at of journey.acceptanceTests) {
+    if (at.length > 200) {
+      errors.push(
+        `Journey ${journey.id} acceptance test too long (${at.length} chars, max 200): "${at.substring(0, 50)}..."`
+      );
+    }
+  }
+
+  // Preconditions non-empty
+  if (journey.preconditions.length === 0) {
+    errors.push(`Journey ${journey.id} has empty preconditions`);
+  }
+
+  // Success non-empty
+  if (!journey.success || journey.success.trim() === '') {
+    errors.push(`Journey ${journey.id} has empty success outcome`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ─── FR Extraction ──────────────────────────────────────────────────────────
+
+/**
+ * Format an FR ID: FR-001, FR-002, etc.
+ */
+function formatFRId(frNumber: number): string {
+  return normalizeId(`FR-${frNumber}`);
+}
+
+/**
+ * Extract FRs from journeys. Each journey step maps to at least 1 FR.
+ * Populates bidirectional cross-links:
+ * - Each step.frIds gets the generated FR IDs
+ * - Each journey.linkedFRs gets all FR IDs from its steps
+ * - Each FR.sourceJourneys references the parent journey
+ * - Each FR.sourceSteps references "J-XXX step N"
+ *
+ * Duplicate step descriptions merge into a single FR with multiple sources.
+ */
+export function extractFRsFromJourneys(
+  journeys: Journey[]
+): FunctionalRequirement[] {
+  let frCounter = 1;
+  const frMap = new Map<string, FunctionalRequirement>();
+  /** Map from normalized description to FR ID for deduplication */
+  const descriptionToFrId = new Map<string, string>();
+
+  for (const journey of journeys) {
+    for (const step of journey.steps) {
+      const normalizedDesc = step.action.trim().toLowerCase();
+
+      if (descriptionToFrId.has(normalizedDesc)) {
+        // Merge: add this journey/step as additional source
+        const existingFrId = descriptionToFrId.get(normalizedDesc)!;
+        const existingFr = frMap.get(existingFrId)!;
+
+        if (!existingFr.sourceJourneys.includes(journey.id)) {
+          existingFr.sourceJourneys.push(journey.id);
+        }
+        existingFr.sourceSteps.push(`${journey.id} step ${step.number}`);
+        step.frIds.push(existingFrId);
+      } else {
+        // New FR
+        const frId = formatFRId(frCounter);
+        frCounter++;
+
+        const fr: FunctionalRequirement = {
+          id: frId,
+          description: step.action,
+          scope: assignScope(journey.type),
+          priority: assignPriority(journey.type),
+          sourceJourneys: [journey.id],
+          sourceSteps: [`${journey.id} step ${step.number}`],
+        };
+
+        frMap.set(frId, fr);
+        descriptionToFrId.set(normalizedDesc, frId);
+        step.frIds.push(frId);
+      }
+    }
+
+    // Populate journey.linkedFRs from step frIds
+    const journeyFrIds = new Set<string>();
+    for (const step of journey.steps) {
+      for (const frId of step.frIds) {
+        journeyFrIds.add(frId);
+      }
+    }
+    journey.linkedFRs = Array.from(journeyFrIds).sort();
+  }
+
+  // Return sorted by FR ID
+  return Array.from(frMap.values()).sort((a, b) => {
+    const aNum = parseInt(a.id.split('-')[1], 10);
+    const bNum = parseInt(b.id.split('-')[1], 10);
+    return aNum - bNum;
+  });
+}
+
+// ─── Traceability ───────────────────────────────────────────────────────────
+
+/**
+ * Build traceability map for SPEC.md traceability table.
+ * Each entry maps an FR to its source journeys.
+ */
+export function buildTraceabilityMap(
+  frs: FunctionalRequirement[]
+): TraceabilityEntry[] {
+  return frs.map((fr) => ({
+    frId: fr.id,
+    description: fr.description,
+    journeyRefs: fr.sourceSteps.map((stepRef) => {
+      // Convert "J-001 step 3" to "J-001 (step 3)"
+      const match = stepRef.match(/^(J-\d+)\s+step\s+(\d+)$/);
+      if (match) {
+        return `${match[1]} (step ${match[2]})`;
+      }
+      return stepRef;
+    }),
+  }));
+}
+
+// ─── Coverage Validation ────────────────────────────────────────────────────
+
+/**
+ * Validate FR coverage: every journey step has FRs, every FR has sources.
+ */
+export function validateFRCoverage(
+  journeys: Journey[],
+  frs: FunctionalRequirement[]
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Every journey step must have at least 1 FR
+  for (const journey of journeys) {
+    for (const step of journey.steps) {
+      if (step.frIds.length === 0) {
+        errors.push(
+          `Journey ${journey.id} step ${step.number} has no FR coverage`
+        );
+      }
+    }
+  }
+
+  // Every FR must have at least 1 source journey
+  for (const fr of frs) {
+    if (fr.sourceJourneys.length === 0) {
+      errors.push(`FR ${fr.id} has no source journey (orphan FR)`);
+    }
+  }
+
+  // All FR IDs use correct format
+  for (const fr of frs) {
+    if (!/^FR-\d{3,}$/.test(fr.id)) {
+      errors.push(`Invalid FR ID format: ${fr.id} (expected FR-XXX)`);
+    }
+  }
+
+  // All scope tags are valid
+  const validScopes = ['v1', 'v2', 'out'];
+  for (const fr of frs) {
+    if (!validScopes.includes(fr.scope)) {
+      errors.push(`FR ${fr.id} has invalid scope: ${fr.scope}`);
+    }
+  }
+
+  // All priority tags are valid
+  const validPriorities = ['P0', 'P1', 'P2'];
+  for (const fr of frs) {
+    if (!validPriorities.includes(fr.priority)) {
+      errors.push(`FR ${fr.id} has invalid priority: ${fr.priority}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/lib/specify-nfr.ts

@@ -0,0 +1,208 @@
+/**
+ * GSWD Specify NFR Module — Rule-based non-functional requirement generation
+ *
+ * Generates NFRs across 4 required categories: security, privacy, performance, observability.
+ * Thresholds calibrated for v1 MVP — conservative and achievable.
+ *
+ * Schema: GSWD_SPEC.md Section 6.1 (ID formats), 8.3 (specify workflow step 4)
+ */
+
+import { normalizeId } from './parse.js';
+import type { FunctionalRequirement } from './specify-journeys.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type NFRCategory = 'security' | 'privacy' | 'performance' | 'observability';
+
+export interface NonFunctionalRequirement {
+  /** NFR ID in NFR-001 format */
+  id: string;
+  /** Category: security, privacy, performance, or observability */
+  category: NFRCategory;
+  /** What this NFR requires */
+  description: string;
+  /** Measurable threshold or acceptance criteria */
+  threshold: string;
+  /** FR-XXX IDs this NFR applies to */
+  linkedFRs: string[];
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * The 4 required NFR categories from GSWD_SPEC Section 8.3.
+ */
+export const NFR_CATEGORIES: { category: NFRCategory; description: string }[] = [
+  { category: 'security', description: 'Input validation, authentication, authorization' },
+  { category: 'privacy', description: 'Data handling, user consent, PII protection' },
+  { category: 'performance', description: 'Response time, throughput, resource usage' },
+  { category: 'observability', description: 'Logging, error tracking, health checks' },
+];
+
+// ─── NFR Generation ─────────────────────────────────────────────────────────
+
+/**
+ * Format an NFR ID: NFR-001, NFR-002, etc.
+ */
+function formatNFRId(nfrNumber: number): string {
+  return normalizeId(`NFR-${nfrNumber}`);
+}
+
+/**
+ * Generate NFRs from FR list across all 4 required categories.
+ * Rule-based: each category produces a standard set of NFRs.
+ * Thresholds calibrated for v1 MVP.
+ *
+ * @param frs - Functional requirements to link NFRs to
+ * @param decisionsContext - Optional DECISIONS.md content for calibration
+ */
+export function generateNFRs(
+  frs: FunctionalRequirement[],
+  decisionsContext?: string
+): NonFunctionalRequirement[] {
+  const nfrs: NonFunctionalRequirement[] = [];
+  let counter = 1;
+
+  const v1FrIds = frs.filter((fr) => fr.scope === 'v1').map((fr) => fr.id);
+  const p0FrIds = frs.filter((fr) => fr.priority === 'P0').map((fr) => fr.id);
+
+  // ─── Security NFRs ───────────────────────────────────────────────────────
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'security',
+    description: 'All user-facing input fields must be validated before processing',
+    threshold: 'No unvalidated user input reaches data store or business logic',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'security',
+    description: 'All authenticated operations must verify session validity',
+    threshold: 'Unauthorized access returns 401/403 within 100ms',
+    linkedFRs: p0FrIds.length > 0 ? p0FrIds : [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'security',
+    description: 'Operations must enforce role-based access when roles are defined',
+    threshold: 'Users can only access resources they own or are authorized to view',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  // ─── Privacy NFRs ────────────────────────────────────────────────────────
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'privacy',
+    description: 'User data must not be logged in plain text or exposed in error messages',
+    threshold: 'No PII appears in application logs or stack traces',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'privacy',
+    description: 'User data collection requires explicit consent where applicable',
+    threshold: 'No data stored without user-initiated action',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  // ─── Performance NFRs ────────────────────────────────────────────────────
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'performance',
+    description: 'Core user actions must complete within acceptable time',
+    threshold: 'P95 response time < 2s for core actions, < 5s for complex operations',
+    linkedFRs: p0FrIds.length > 0 ? p0FrIds : [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'performance',
+    description: 'System must handle expected v1 concurrent load',
+    threshold: 'Supports 100 concurrent users without degradation',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  // ─── Observability NFRs ──────────────────────────────────────────────────
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'observability',
+    description: 'All errors must be captured with context for debugging',
+    threshold: 'Errors include timestamp, user context (anonymized), stack trace, and request ID',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'observability',
+    description: 'System health must be verifiable',
+    threshold: 'Health endpoint returns status within 1s',
+    linkedFRs: [],
+  });
+
+  nfrs.push({
+    id: formatNFRId(counter++),
+    category: 'observability',
+    description: 'Key operations must produce structured logs',
+    threshold: 'All state-changing operations produce at least one log entry',
+    linkedFRs: v1FrIds.length > 0 ? v1FrIds : [],
+  });
+
+  return nfrs;
+}
+
+// ─── NFR Validation ─────────────────────────────────────────────────────────
+
+/**
+ * Validate NFRs: all 4 categories represented, IDs correct, fields non-empty.
+ */
+export function validateNFRs(
+  nfrs: NonFunctionalRequirement[]
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const categoriesPresent = new Set<NFRCategory>();
+
+  for (const nfr of nfrs) {
+    categoriesPresent.add(nfr.category);
+
+    // ID format check
+    if (!/^NFR-\d{3,}$/.test(nfr.id)) {
+      errors.push(`Invalid NFR ID format: ${nfr.id} (expected NFR-XXX)`);
+    }
+
+    // Non-empty description
+    if (!nfr.description || nfr.description.trim() === '') {
+      errors.push(`NFR ${nfr.id} has empty description`);
+    }
+
+    // Non-empty threshold
+    if (!nfr.threshold || nfr.threshold.trim() === '') {
+      errors.push(`NFR ${nfr.id} has empty threshold`);
+    }
+  }
+
+  // All 4 categories represented
+  const requiredCategories: NFRCategory[] = ['security', 'privacy', 'performance', 'observability'];
+  for (const category of requiredCategories) {
+    if (!categoriesPresent.has(category)) {
+      errors.push(`Missing required NFR category: ${category}`);
+    }
+  }
+
+  // Sequential IDs (warning-level, but include in errors for strict validation)
+  for (let i = 0; i < nfrs.length; i++) {
+    const expectedId = formatNFRId(i + 1);
+    if (nfrs[i].id !== expectedId) {
+      errors.push(`Non-sequential NFR ID: expected ${expectedId}, got ${nfrs[i].id}`);
+      break; // Only report first gap
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}