@eddacraft/anvil-aps 0.1.0

package/src/filter/context-bundle.ts

@@ -0,0 +1,312 @@
+/**
+ * Context Bundle Builder
+ *
+ * Generates context bundles for LLM consumption from filtered plans.
+ * Outputs both text (Markdown) and JSON formats.
+ */
+
+import type { FilteredPlan } from './index.js';
+
+/**
+ * Context bundle in JSON format
+ */
+export interface ContextBundleJSON {
+  /** Plan title */
+  title: string;
+
+  /** Filter criteria that was applied */
+  filter: {
+    scopes?: string[];
+    modules?: string[];
+    tasks?: string[];
+    owners?: string[];
+    tags?: string[];
+    priorities?: string[];
+    confidences?: string[];
+  };
+
+  /** Summary statistics */
+  summary: {
+    totalModules: number;
+    totalTasks: number;
+    tasksByConfidence: {
+      high: number;
+      medium: number;
+      low: number;
+    };
+    tasksByStatus: {
+      open: number;
+      locked: number;
+      completed: number;
+      cancelled: number;
+    };
+  };
+
+  /** Modules with their tasks */
+  modules: Array<{
+    id: string;
+    scope?: string;
+    owner?: string;
+    priority?: string;
+    tags?: string[];
+    tasks: Array<{
+      id: string;
+      title: string;
+      intent: string;
+      confidence: string;
+      status: string;
+      scopes?: string[];
+      tags?: string[];
+      dependencies?: string[];
+      inputs?: string[];
+      expectedOutcome?: string;
+    }>;
+  }>;
+
+  /** Dependency graph (module -> dependencies) */
+  dependencyGraph: Record<string, string[]>;
+}
+
+/**
+ * Build a context bundle from a filtered plan
+ *
+ * @param filtered - The filtered plan
+ * @returns Context bundle in JSON format
+ */
+export function buildContextBundleJSON(filtered: FilteredPlan): ContextBundleJSON {
+  const { plan, modules, tasks, criteria } = filtered;
+
+  // Build summary statistics
+  const summary = {
+    totalModules: modules.length,
+    totalTasks: tasks.length,
+    tasksByConfidence: {
+      high: tasks.filter((t) => t.confidence === 'high').length,
+      medium: tasks.filter((t) => t.confidence === 'medium').length,
+      low: tasks.filter((t) => t.confidence === 'low').length,
+    },
+    tasksByStatus: {
+      open: tasks.filter((t) => (t.status ?? 'open') === 'open').length,
+      locked: tasks.filter((t) => t.status === 'locked').length,
+      completed: tasks.filter((t) => t.status === 'completed').length,
+      cancelled: tasks.filter((t) => t.status === 'cancelled').length,
+    },
+  };
+
+  // Build module data with tasks
+  const moduleData = modules.map((module) => {
+    const moduleTasks = tasks.filter((t) => module.tasks.some((mt) => mt.id === t.id));
+
+    return {
+      id: module.id,
+      scope: module.metadata.scope,
+      owner: module.metadata.owner,
+      priority: module.metadata.priority,
+      tags: module.metadata.tags,
+      tasks: moduleTasks.map((t) => ({
+        id: t.id,
+        title: t.title,
+        intent: t.intent,
+        confidence: t.confidence,
+        status: t.status ?? 'open',
+        scopes: t.scopes,
+        tags: t.tags,
+        dependencies: t.dependencies,
+        inputs: t.inputs,
+        expectedOutcome: t.expectedOutcome,
+      })),
+    };
+  });
+
+  // Build dependency graph for filtered modules
+  const dependencyGraph: Record<string, string[]> = {};
+  for (const module of modules) {
+    const deps = plan.dependencyGraph.get(module.id) ?? [];
+    // Only include dependencies that are in the filtered set
+    const filteredDeps = deps.filter((d) => modules.some((m) => m.id === d));
+    dependencyGraph[module.id] = filteredDeps;
+  }
+
+  return {
+    title: plan.title,
+    filter: {
+      scopes: criteria.scopes,
+      modules: criteria.modules,
+      tasks: criteria.tasks,
+      owners: criteria.owners,
+      tags: criteria.tags,
+      priorities: criteria.priorities,
+      confidences: criteria.confidences,
+    },
+    summary,
+    modules: moduleData,
+    dependencyGraph,
+  };
+}
+
+/**
+ * Build a context bundle in Markdown text format
+ *
+ * @param filtered - The filtered plan
+ * @returns Markdown text suitable for LLM context
+ */
+export function buildContextBundleText(filtered: FilteredPlan): string {
+  const { plan, modules, tasks, criteria } = filtered;
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`# ${plan.title}`);
+  lines.push('');
+
+  // Filter info
+  const filterParts: string[] = [];
+  if (criteria.scopes?.length) filterParts.push(`scopes: ${criteria.scopes.join(', ')}`);
+  if (criteria.modules?.length) filterParts.push(`modules: ${criteria.modules.join(', ')}`);
+  if (criteria.tasks?.length) filterParts.push(`tasks: ${criteria.tasks.join(', ')}`);
+  if (criteria.owners?.length) filterParts.push(`owners: ${criteria.owners.join(', ')}`);
+  if (criteria.tags?.length) filterParts.push(`tags: ${criteria.tags.join(', ')}`);
+  if (criteria.priorities?.length)
+    filterParts.push(`priorities: ${criteria.priorities.join(', ')}`);
+  if (criteria.confidences?.length)
+    filterParts.push(`confidences: ${criteria.confidences.join(', ')}`);
+
+  if (filterParts.length > 0) {
+    lines.push(`> Filtered by: ${filterParts.join('; ')}`);
+    lines.push('');
+  }
+
+  // Summary
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- **Modules:** ${modules.length}`);
+  lines.push(`- **Tasks:** ${tasks.length}`);
+
+  const highConfidence = tasks.filter((t) => t.confidence === 'high').length;
+  const mediumConfidence = tasks.filter((t) => t.confidence === 'medium').length;
+  const lowConfidence = tasks.filter((t) => t.confidence === 'low').length;
+  lines.push(
+    `- **Confidence:** ${highConfidence} high, ${mediumConfidence} medium, ${lowConfidence} low`
+  );
+
+  const openTasks = tasks.filter((t) => (t.status ?? 'open') === 'open').length;
+  const lockedTasks = tasks.filter((t) => t.status === 'locked').length;
+  const completedTasks = tasks.filter((t) => t.status === 'completed').length;
+  lines.push(`- **Status:** ${openTasks} open, ${lockedTasks} locked, ${completedTasks} completed`);
+  lines.push('');
+
+  // Modules and tasks
+  for (const module of modules) {
+    lines.push(`## Module: ${module.id}`);
+    lines.push('');
+
+    if (module.metadata.scope) lines.push(`**Scope:** ${module.metadata.scope}`);
+    if (module.metadata.owner) lines.push(`**Owner:** ${module.metadata.owner}`);
+    if (module.metadata.priority) lines.push(`**Priority:** ${module.metadata.priority}`);
+    if (module.metadata.tags?.length) lines.push(`**Tags:** ${module.metadata.tags.join(', ')}`);
+
+    const deps = plan.dependencyGraph.get(module.id) ?? [];
+    if (deps.length > 0) lines.push(`**Dependencies:** ${deps.join(', ')}`);
+    lines.push('');
+
+    // Tasks for this module
+    const moduleTasks = tasks.filter((t) => module.tasks.some((mt) => mt.id === t.id));
+
+    if (moduleTasks.length === 0) {
+      lines.push('*No tasks match the filter criteria.*');
+      lines.push('');
+      continue;
+    }
+
+    lines.push('### Tasks');
+    lines.push('');
+
+    for (const task of moduleTasks) {
+      lines.push(`#### ${task.id}: ${task.title}`);
+      lines.push('');
+      lines.push(`**Intent:** ${task.intent}`);
+      lines.push(`**Confidence:** ${task.confidence}`);
+      lines.push(`**Status:** ${task.status ?? 'open'}`);
+
+      if (task.scopes?.length) lines.push(`**Scopes:** ${task.scopes.join(', ')}`);
+      if (task.tags?.length) lines.push(`**Tags:** ${task.tags.join(', ')}`);
+      if (task.dependencies?.length)
+        lines.push(`**Dependencies:** ${task.dependencies.join(', ')}`);
+      if (task.expectedOutcome) lines.push(`**Expected Outcome:** ${task.expectedOutcome}`);
+
+      if (task.inputs?.length) {
+        lines.push('**Inputs:**');
+        for (const input of task.inputs) {
+          lines.push(`- ${input}`);
+        }
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build context for a single task (focused view)
+ */
+export function buildTaskContext(filtered: FilteredPlan, taskId: string): string | null {
+  const task = filtered.tasks.find((t) => t.id === taskId);
+  if (!task) return null;
+
+  const lines: string[] = [];
+
+  lines.push(`# Task: ${task.id}`);
+  lines.push('');
+  lines.push(`## ${task.title}`);
+  lines.push('');
+  lines.push(`**Intent:** ${task.intent}`);
+  lines.push('');
+  lines.push(`**Confidence:** ${task.confidence}`);
+  lines.push(`**Status:** ${task.status ?? 'open'}`);
+
+  if (task.scopes?.length) {
+    lines.push('');
+    lines.push(`**Scopes:** ${task.scopes.join(', ')}`);
+    lines.push('');
+    lines.push('> These scopes define what files/modules this task is allowed to modify.');
+  }
+
+  if (task.tags?.length) {
+    lines.push('');
+    lines.push(`**Tags:** ${task.tags.join(', ')}`);
+  }
+
+  if (task.dependencies?.length) {
+    lines.push('');
+    lines.push('## Dependencies');
+    lines.push('');
+    lines.push('This task depends on:');
+    for (const dep of task.dependencies) {
+      const depTask = filtered.plan.allTasks.find((t) => t.id === dep);
+      if (depTask) {
+        lines.push(`- **${dep}:** ${depTask.title} (${depTask.status ?? 'open'})`);
+      } else {
+        lines.push(`- **${dep}:** (not found)`);
+      }
+    }
+  }
+
+  if (task.inputs?.length) {
+    lines.push('');
+    lines.push('## Inputs');
+    lines.push('');
+    for (const input of task.inputs) {
+      lines.push(`- ${input}`);
+    }
+  }
+
+  if (task.expectedOutcome) {
+    lines.push('');
+    lines.push('## Expected Outcome');
+    lines.push('');
+    lines.push(task.expectedOutcome);
+  }
+
+  return lines.join('\n');
+}

package/src/filter/filter.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Tests for filter module
+ */
+
+import { describe, it, expect } from 'vitest';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadPlan } from '../loader/index.js';
+import {
+  filterPlan,
+  filterByScope,
+  filterByModule,
+  filterByTags,
+  filterByOwner,
+  filterByPriority,
+  filterByConfidence,
+  getTasksById,
+  buildContextBundleJSON,
+  buildContextBundleText,
+  buildTaskContext,
+} from './index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const EXAMPLES_DIR = join(__dirname, '../../examples');
+
+describe('filterPlan', () => {
+  describe('scope filtering', () => {
+    it('should filter tasks by scope', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH'] });
+
+      expect(filtered.modules.length).toBe(1);
+      expect(filtered.modules[0].id).toBe('auth');
+      // Tasks are filtered by having AUTH in their scopes array, not just ID prefix
+      // This includes AUTH-* tasks and any task that lists AUTH in its scopes
+      expect(
+        filtered.tasks.every((t) => t.scopes?.includes('AUTH') || t.id.startsWith('AUTH-'))
+      ).toBe(true);
+    });
+
+    it('should filter by multiple scopes', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH', 'PROD'] });
+
+      expect(filtered.modules.length).toBe(2);
+      const moduleIds = filtered.modules.map((m) => m.id);
+      expect(moduleIds).toContain('auth');
+      expect(moduleIds).toContain('products');
+    });
+
+    it('should be case-insensitive for scopes', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['auth'] });
+
+      expect(filtered.modules.length).toBe(1);
+      expect(filtered.modules[0].id).toBe('auth');
+    });
+  });
+
+  describe('module filtering', () => {
+    it('should filter by module ID', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { modules: ['cart'] });
+
+      expect(filtered.modules.length).toBe(1);
+      expect(filtered.modules[0].id).toBe('cart');
+      expect(filtered.tasks.every((t) => t.id.startsWith('CART-'))).toBe(true);
+    });
+
+    it('should filter by multiple modules', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { modules: ['auth', 'payments'] });
+
+      expect(filtered.modules.length).toBe(2);
+    });
+  });
+
+  describe('task filtering', () => {
+    it('should filter by specific task IDs', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { tasks: ['AUTH-001', 'AUTH-002'] });
+
+      expect(filtered.tasks.length).toBe(2);
+      expect(filtered.tasks.map((t) => t.id)).toEqual(['AUTH-001', 'AUTH-002']);
+    });
+  });
+
+  describe('owner filtering', () => {
+    it('should filter by owner', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { owners: ['@alice'] });
+
+      expect(filtered.modules.length).toBe(1);
+      expect(filtered.modules[0].metadata.owner).toBe('@alice');
+    });
+
+    it('should be case-insensitive for owners', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { owners: ['@ALICE'] });
+
+      expect(filtered.modules.length).toBe(1);
+    });
+  });
+
+  describe('tag filtering', () => {
+    it('should filter by tags', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { tags: ['security'] });
+
+      // Auth module has 'security' tag
+      expect(filtered.modules.some((m) => m.id === 'auth')).toBe(true);
+    });
+
+    it('should match any tag (OR logic)', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { tags: ['security', 'billing'] });
+
+      // Should match both auth (security) and payments (billing)
+      expect(filtered.modules.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe('priority filtering', () => {
+    it('should filter by priority', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { priorities: ['high'] });
+
+      expect(filtered.modules.every((m) => m.metadata.priority === 'high')).toBe(true);
+    });
+
+    it('should filter by multiple priorities', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { priorities: ['high', 'medium'] });
+
+      expect(filtered.modules.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('confidence filtering', () => {
+    it('should filter tasks by confidence', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, { confidences: ['high'] });
+
+      expect(filtered.tasks.every((t) => t.confidence === 'high')).toBe(true);
+    });
+
+    it('should filter by multiple confidence levels', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, { confidences: ['high', 'medium'] });
+
+      expect(
+        filtered.tasks.every((t) => t.confidence === 'high' || t.confidence === 'medium')
+      ).toBe(true);
+    });
+  });
+
+  describe('combined filters', () => {
+    it('should apply multiple filters (AND logic)', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, {
+        scopes: ['AUTH'],
+        priorities: ['high'],
+      });
+
+      expect(filtered.modules.length).toBe(1);
+      expect(filtered.modules[0].id).toBe('auth');
+      expect(filtered.modules[0].metadata.priority).toBe('high');
+    });
+  });
+});
+
+describe('convenience filter functions', () => {
+  it('filterByScope should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+    const tasks = filterByScope(plan, ['AUTH']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+    // Tasks are filtered by having AUTH in their scopes array
+    expect(tasks.every((t) => t.scopes?.includes('AUTH') || t.id.startsWith('AUTH-'))).toBe(true);
+  });
+
+  it('filterByModule should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+    const tasks = filterByModule(plan, ['cart']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+    expect(tasks.every((t) => t.id.startsWith('CART-'))).toBe(true);
+  });
+
+  it('filterByTags should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+    const tasks = filterByTags(plan, ['security']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+  });
+
+  it('filterByOwner should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+    const tasks = filterByOwner(plan, ['@alice']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+  });
+
+  it('filterByPriority should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+    const tasks = filterByPriority(plan, ['high']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+  });
+
+  it('filterByConfidence should return tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+    const tasks = filterByConfidence(plan, ['high']);
+
+    expect(tasks.length).toBeGreaterThan(0);
+    expect(tasks.every((t) => t.confidence === 'high')).toBe(true);
+  });
+
+  it('getTasksById should return specific tasks', async () => {
+    const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+    const tasks = getTasksById(plan, ['AUTH-001', 'AUTH-003']);
+
+    expect(tasks.length).toBe(2);
+    expect(tasks.map((t) => t.id).sort()).toEqual(['AUTH-001', 'AUTH-003']);
+  });
+});
+
+describe('context bundle builders', () => {
+  describe('buildContextBundleJSON', () => {
+    it('should build JSON bundle with summary', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH'] });
+      const bundle = buildContextBundleJSON(filtered);
+
+      expect(bundle.title).toBe('E-commerce Platform MVP');
+      expect(bundle.summary.totalModules).toBe(1);
+      expect(bundle.summary.totalTasks).toBeGreaterThan(0);
+      expect(bundle.modules.length).toBe(1);
+      expect(bundle.modules[0].id).toBe('auth');
+    });
+
+    it('should include filter criteria in bundle', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH'], tags: ['security'] });
+      const bundle = buildContextBundleJSON(filtered);
+
+      expect(bundle.filter.scopes).toEqual(['AUTH']);
+      expect(bundle.filter.tags).toEqual(['security']);
+    });
+
+    it('should include task details', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, {});
+      const bundle = buildContextBundleJSON(filtered);
+
+      expect(bundle.modules[0].tasks.length).toBeGreaterThan(0);
+      const task = bundle.modules[0].tasks[0];
+      expect(task.id).toBeDefined();
+      expect(task.title).toBeDefined();
+      expect(task.intent).toBeDefined();
+      expect(task.confidence).toBeDefined();
+    });
+  });
+
+  describe('buildContextBundleText', () => {
+    it('should build Markdown text bundle', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH'] });
+      const text = buildContextBundleText(filtered);
+
+      expect(text).toContain('# E-commerce Platform MVP');
+      expect(text).toContain('## Summary');
+      expect(text).toContain('## Module: auth');
+      expect(text).toContain('### Tasks');
+    });
+
+    it('should include filter info in text', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'system-ecommerce/APS.md'));
+      const filtered = filterPlan(plan, { scopes: ['AUTH'] });
+      const text = buildContextBundleText(filtered);
+
+      expect(text).toContain('Filtered by:');
+      expect(text).toContain('scopes: AUTH');
+    });
+  });
+
+  describe('buildTaskContext', () => {
+    it('should build focused context for a single task', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, {});
+      const context = buildTaskContext(filtered, 'AUTH-001');
+
+      expect(context).not.toBeNull();
+      expect(context).toContain('# Task: AUTH-001');
+      expect(context).toContain('**Intent:**');
+    });
+
+    it('should return null for non-existent task', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, {});
+      const context = buildTaskContext(filtered, 'NONEXISTENT-999');
+
+      expect(context).toBeNull();
+    });
+
+    it('should include dependencies with status', async () => {
+      const plan = await loadPlan(join(EXAMPLES_DIR, 'feature-auth.aps.md'));
+      const filtered = filterPlan(plan, {});
+      // AUTH-003 depends on AUTH-001 and AUTH-002
+      const context = buildTaskContext(filtered, 'AUTH-003');
+
+      expect(context).toContain('## Dependencies');
+      expect(context).toContain('AUTH-001');
+      expect(context).toContain('AUTH-002');
+    });
+  });
+});