@eddacraft/anvil-aps 0.1.0

package/src/filter/index.ts

@@ -0,0 +1,249 @@
+/**
+ * Filter module - Task and module filtering for APS plans
+ *
+ * Provides filtering capabilities for:
+ * - Scope-based filtering (by module scope or task scopes)
+ * - Module-based filtering (by module ID)
+ * - Task-based filtering (by task ID)
+ * - Metadata filtering (owner, tags, priority, confidence)
+ *
+ * Also provides context bundle generation for LLM consumption.
+ */
+
+// Re-export context bundle functions
+export {
+  buildContextBundleJSON,
+  buildContextBundleText,
+  buildTaskContext,
+  type ContextBundleJSON,
+} from './context-bundle.js';
+
+import type { LoadedPlan, LoadedModule } from '../loader/index.js';
+import type { Task, Priority, Confidence } from '../types/index.js';
+
+/**
+ * Filter criteria for tasks and modules
+ */
+export interface FilterCriteria {
+  /** Filter by scope (matches module scope or task scopes) */
+  scopes?: string[];
+
+  /** Filter by module ID */
+  modules?: string[];
+
+  /** Filter by specific task IDs */
+  tasks?: string[];
+
+  /** Filter by owner (e.g., @alice) */
+  owners?: string[];
+
+  /** Filter by tags (matches any) */
+  tags?: string[];
+
+  /** Filter by priority levels */
+  priorities?: Priority[];
+
+  /** Filter by confidence levels */
+  confidences?: Confidence[];
+
+  /** Filter by task status */
+  statuses?: Array<'open' | 'locked' | 'completed' | 'cancelled'>;
+}
+
+/**
+ * Result of filtering a plan
+ */
+export interface FilteredPlan {
+  /** Original plan reference */
+  plan: LoadedPlan;
+
+  /** Filtered modules (only those matching criteria) */
+  modules: LoadedModule[];
+
+  /** Filtered tasks (only those matching criteria) */
+  tasks: Task[];
+
+  /** Applied filter criteria */
+  criteria: FilterCriteria;
+}
+
+/**
+ * Filter a loaded plan by the given criteria
+ *
+ * @param plan - The loaded plan to filter
+ * @param criteria - Filter criteria to apply
+ * @returns Filtered plan with matching modules and tasks
+ */
+export function filterPlan(plan: LoadedPlan, criteria: FilterCriteria): FilteredPlan {
+  // Start with all modules and tasks
+  let filteredModules = Array.from(plan.modules.values());
+  let filteredTasks = [...plan.allTasks];
+
+  // Apply module-level filters first
+  if (criteria.modules && criteria.modules.length > 0) {
+    filteredModules = filteredModules.filter((m) => criteria.modules!.includes(m.id));
+    // Also filter tasks to only those in matching modules
+    const moduleIds = new Set(criteria.modules);
+    filteredTasks = filteredTasks.filter((t) => {
+      const taskModule = findTaskModule(plan, t.id);
+      return taskModule && moduleIds.has(taskModule.id);
+    });
+  }
+
+  // Apply scope filter (matches module scope OR task scopes)
+  if (criteria.scopes && criteria.scopes.length > 0) {
+    const scopeSet = new Set(criteria.scopes.map((s) => s.toUpperCase()));
+
+    filteredModules = filteredModules.filter((m) => {
+      const moduleScope = m.metadata.scope?.toUpperCase();
+      return moduleScope && scopeSet.has(moduleScope);
+    });
+
+    filteredTasks = filteredTasks.filter((t) => {
+      // Check if any of the task's scopes match
+      if (t.scopes && t.scopes.length > 0) {
+        return t.scopes.some((s) => scopeSet.has(s.toUpperCase()));
+      }
+      // Fall back to checking if task ID prefix matches scope
+      const taskScope = t.id.split('-')[0];
+      return scopeSet.has(taskScope);
+    });
+  }
+
+  // Apply task ID filter
+  if (criteria.tasks && criteria.tasks.length > 0) {
+    const taskIdSet = new Set(criteria.tasks);
+    filteredTasks = filteredTasks.filter((t) => taskIdSet.has(t.id));
+  }
+
+  // Apply owner filter
+  if (criteria.owners && criteria.owners.length > 0) {
+    const ownerSet = new Set(criteria.owners.map((o) => o.toLowerCase()));
+
+    filteredModules = filteredModules.filter((m) => {
+      const owner = m.metadata.owner?.toLowerCase();
+      return owner && ownerSet.has(owner);
+    });
+
+    // For tasks, filter by the module owner (tasks don't have individual owners)
+    filteredTasks = filteredTasks.filter((t) => {
+      const taskModule = findTaskModule(plan, t.id);
+      if (!taskModule) return false;
+      const owner = taskModule.metadata.owner?.toLowerCase();
+      return owner && ownerSet.has(owner);
+    });
+  }
+
+  // Apply tag filter (matches any tag)
+  if (criteria.tags && criteria.tags.length > 0) {
+    const tagSet = new Set(criteria.tags.map((t) => t.toLowerCase()));
+
+    filteredModules = filteredModules.filter((m) => {
+      const moduleTags = m.metadata.tags?.map((t) => t.toLowerCase()) ?? [];
+      return moduleTags.some((t) => tagSet.has(t));
+    });
+
+    filteredTasks = filteredTasks.filter((t) => {
+      const taskTags = t.tags?.map((tag) => tag.toLowerCase()) ?? [];
+      return taskTags.some((tag) => tagSet.has(tag));
+    });
+  }
+
+  // Apply priority filter
+  if (criteria.priorities && criteria.priorities.length > 0) {
+    const prioritySet = new Set(criteria.priorities);
+
+    filteredModules = filteredModules.filter((m) => {
+      return m.metadata.priority && prioritySet.has(m.metadata.priority);
+    });
+
+    // Tasks don't have priority, so filter by module priority
+    filteredTasks = filteredTasks.filter((t) => {
+      const taskModule = findTaskModule(plan, t.id);
+      return taskModule?.metadata.priority && prioritySet.has(taskModule.metadata.priority);
+    });
+  }
+
+  // Apply confidence filter
+  if (criteria.confidences && criteria.confidences.length > 0) {
+    const confidenceSet = new Set(criteria.confidences);
+    filteredTasks = filteredTasks.filter((t) => confidenceSet.has(t.confidence));
+  }
+
+  // Apply status filter
+  if (criteria.statuses && criteria.statuses.length > 0) {
+    const statusSet = new Set(criteria.statuses);
+    filteredTasks = filteredTasks.filter((t) => {
+      const status = t.status ?? 'open';
+      return statusSet.has(status);
+    });
+  }
+
+  return {
+    plan,
+    modules: filteredModules,
+    tasks: filteredTasks,
+    criteria,
+  };
+}
+
+/**
+ * Find the module that contains a task
+ */
+function findTaskModule(plan: LoadedPlan, taskId: string): LoadedModule | undefined {
+  for (const module of plan.modules.values()) {
+    if (module.tasks.some((t) => t.id === taskId)) {
+      return module;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Filter tasks by scope (convenience function)
+ */
+export function filterByScope(plan: LoadedPlan, scopes: string[]): Task[] {
+  return filterPlan(plan, { scopes }).tasks;
+}
+
+/**
+ * Filter tasks by module (convenience function)
+ */
+export function filterByModule(plan: LoadedPlan, moduleIds: string[]): Task[] {
+  return filterPlan(plan, { modules: moduleIds }).tasks;
+}
+
+/**
+ * Filter tasks by tags (convenience function)
+ */
+export function filterByTags(plan: LoadedPlan, tags: string[]): Task[] {
+  return filterPlan(plan, { tags }).tasks;
+}
+
+/**
+ * Filter tasks by owner (convenience function)
+ */
+export function filterByOwner(plan: LoadedPlan, owners: string[]): Task[] {
+  return filterPlan(plan, { owners }).tasks;
+}
+
+/**
+ * Filter tasks by priority (convenience function)
+ */
+export function filterByPriority(plan: LoadedPlan, priorities: Priority[]): Task[] {
+  return filterPlan(plan, { priorities }).tasks;
+}
+
+/**
+ * Filter tasks by confidence (convenience function)
+ */
+export function filterByConfidence(plan: LoadedPlan, confidences: Confidence[]): Task[] {
+  return filterPlan(plan, { confidences }).tasks;
+}
+
+/**
+ * Get tasks matching specific IDs
+ */
+export function getTasksById(plan: LoadedPlan, taskIds: string[]): Task[] {
+  return filterPlan(plan, { tasks: taskIds }).tasks;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @eddacraft/anvil-aps - Anvil Planning Spec library
+ *
+ * This package provides functionality for parsing, loading, validating,
+ * and managing Anvil Planning Spec (APS) documents.
+ *
+ * @module @eddacraft/anvil-aps
+ */
+
+export * from './parser/index.js';
+export * from './loader/index.js';
+export * from './filter/index.js';
+export * from './validator/index.js';
+export * from './state/index.js';
+export * from './types/index.js';
+export * from './templates/index.js';

package/src/loader/index.ts

@@ -0,0 +1,364 @@
+/**
+ * Plan loader module
+ * Loads and resolves APS planning documents into a graph structure
+ */
+
+import { promises as fs } from 'node:fs';
+import { dirname, resolve, isAbsolute, sep } from 'node:path';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import type { Root, Heading } from 'mdast';
+import { parseDocument } from '../parser/parse-document.js';
+import { parseIndex } from '../parser/parse-index.js';
+import { ParseError, type Task, type ModuleMetadata } from '../types/index.js';
+
+/**
+ * A loaded module with its tasks and metadata
+ */
+export interface LoadedModule {
+  /** Module identifier */
+  id: string;
+
+  /** Module metadata from index or leaf spec */
+  metadata: ModuleMetadata;
+
+  /** All tasks in this module */
+  tasks: Task[];
+
+  /** Resolved absolute path to the module file */
+  resolvedPath: string;
+
+  /** IDs of modules this module depends on */
+  dependsOn: string[];
+}
+
+/**
+ * A complete loaded plan with all modules resolved
+ */
+export interface LoadedPlan {
+  /** Plan title */
+  title: string;
+
+  /** Root file path */
+  rootPath: string;
+
+  /** Whether this is a single-file plan or multi-module */
+  isMultiModule: boolean;
+
+  /** All loaded modules */
+  modules: Map<string, LoadedModule>;
+
+  /** All tasks from all modules (flattened) */
+  allTasks: Task[];
+
+  /** Dependency graph (module ID -> dependent module IDs) */
+  dependencyGraph: Map<string, string[]>;
+}
+
+/**
+ * Options for loading a plan
+ */
+export interface LoadOptions {
+  /** Base directory for resolving relative paths (defaults to directory of root file) */
+  baseDir?: string;
+
+  /** Whether to recursively load linked modules (default: true) */
+  recursive?: boolean;
+
+  /** Maximum depth for recursive loading (default: 10) */
+  maxDepth?: number;
+}
+
+/**
+ * Load an APS plan from a file path
+ *
+ * @param filePath - Path to the root plan file (index or leaf spec)
+ * @param options - Loading options
+ * @returns Loaded plan with all modules resolved
+ */
+export async function loadPlan(filePath: string, options: LoadOptions = {}): Promise<LoadedPlan> {
+  const absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);
+  const baseDir = options.baseDir ?? dirname(absolutePath);
+  const recursive = options.recursive ?? true;
+  const maxDepth = options.maxDepth ?? 10;
+
+  const content = await readFile(absolutePath);
+
+  // Try to detect if this is an index file or leaf spec
+  const isIndex = detectIndexFile(content);
+
+  if (isIndex) {
+    return loadMultiModulePlan(absolutePath, content, baseDir, recursive, maxDepth);
+  } else {
+    return loadSingleFilePlan(absolutePath, content);
+  }
+}
+
+/**
+ * Detect if content is an index file (has ## Modules section)
+ * Uses AST parsing for robust detection (case-insensitive, handles variants)
+ */
+function detectIndexFile(content: string): boolean {
+  const processor = unified().use(remarkParse);
+  const ast = processor.parse(content) as Root;
+
+  let hasModulesSection = false;
+
+  visit(ast, 'heading', (node: Heading) => {
+    if (node.depth === 2) {
+      // Extract heading text and normalize
+      let text = '';
+      visit(node, 'text', (textNode: { value: string }) => {
+        text += textNode.value;
+      });
+
+      // Check if heading starts with "modules" (case-insensitive)
+      // This handles "## Modules", "## modules", "## Modules & Scopes", etc.
+      const normalizedText = text.trim().toLowerCase();
+      if (normalizedText === 'modules' || normalizedText.startsWith('modules')) {
+        hasModulesSection = true;
+      }
+    }
+  });
+
+  return hasModulesSection;
+}
+
+/**
+ * Load a single-file plan (leaf spec with tasks)
+ */
+async function loadSingleFilePlan(filePath: string, content: string): Promise<LoadedPlan> {
+  const doc = await parseDocument(content, filePath);
+
+  const moduleId = doc.metadata?.scope ?? 'main';
+  const module: LoadedModule = {
+    id: moduleId,
+    metadata: doc.metadata ?? {},
+    tasks: doc.tasks,
+    resolvedPath: filePath,
+    dependsOn: [],
+  };
+
+  const modules = new Map<string, LoadedModule>();
+  modules.set(moduleId, module);
+
+  return {
+    title: doc.title,
+    rootPath: filePath,
+    isMultiModule: false,
+    modules,
+    allTasks: doc.tasks,
+    dependencyGraph: new Map([[moduleId, []]]),
+  };
+}
+
+/**
+ * Load a multi-module plan from an index file
+ */
+async function loadMultiModulePlan(
+  indexPath: string,
+  content: string,
+  baseDir: string,
+  recursive: boolean,
+  _maxDepth: number // TODO: implement depth limiting for nested index files
+): Promise<LoadedPlan> {
+  const index = await parseIndex(content, indexPath);
+
+  const modules = new Map<string, LoadedModule>();
+  const allTasks: Task[] = [];
+  const dependencyGraph = new Map<string, string[]>();
+
+  // Load each module
+  for (const moduleMeta of index.modules) {
+    const moduleId = moduleMeta.id;
+    if (!moduleId) {
+      throw new ParseError('Module is missing required id field', indexPath);
+    }
+
+    if (!moduleMeta.path) {
+      throw new ParseError(`Module "${moduleId}" is missing required Path field`, indexPath);
+    }
+
+    const resolvedPath = resolvePath(moduleMeta.path, baseDir);
+
+    if (recursive) {
+      const moduleContent = await readFile(resolvedPath);
+      const moduleDoc = await parseDocument(moduleContent, resolvedPath);
+
+      // Merge metadata from index with any from the leaf spec
+      const mergedMetadata: ModuleMetadata = {
+        ...moduleDoc.metadata,
+        ...moduleMeta,
+        id: moduleId,
+      };
+
+      const loadedModule: LoadedModule = {
+        id: moduleId,
+        metadata: mergedMetadata,
+        tasks: moduleDoc.tasks,
+        resolvedPath,
+        dependsOn: moduleMeta.dependencies ?? [],
+      };
+
+      modules.set(moduleId, loadedModule);
+      allTasks.push(...moduleDoc.tasks);
+      dependencyGraph.set(moduleId, moduleMeta.dependencies ?? []);
+    } else {
+      // Non-recursive: just record module metadata without loading content
+      const loadedModule: LoadedModule = {
+        id: moduleId,
+        metadata: moduleMeta,
+        tasks: [],
+        resolvedPath,
+        dependsOn: moduleMeta.dependencies ?? [],
+      };
+
+      modules.set(moduleId, loadedModule);
+      dependencyGraph.set(moduleId, moduleMeta.dependencies ?? []);
+    }
+  }
+
+  return {
+    title: index.title,
+    rootPath: indexPath,
+    isMultiModule: true,
+    modules,
+    allTasks,
+    dependencyGraph,
+  };
+}
+
+/**
+ * Resolve a relative path against a base directory.
+ * Rejects absolute paths and paths that escape the base directory.
+ */
+export function resolvePath(relativePath: string, baseDir: string): string {
+  // Reject absolute paths — module paths must be relative to baseDir
+  if (isAbsolute(relativePath)) {
+    throw new ParseError(`Absolute module paths are not allowed: ${relativePath}`, relativePath);
+  }
+
+  // Remove leading ./ if present
+  const cleanPath = relativePath.replace(/^\.\//, '');
+  const resolved = resolve(baseDir, cleanPath);
+  const resolvedBase = resolve(baseDir);
+
+  // Validate the resolved path stays within baseDir
+  if (resolved !== resolvedBase && !resolved.startsWith(resolvedBase + sep)) {
+    throw new ParseError(`Module path escapes base directory: ${relativePath}`, relativePath);
+  }
+
+  return resolved;
+}
+
+/**
+ * Read a file with proper error handling
+ */
+async function readFile(filePath: string): Promise<string> {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new ParseError(`File not found: ${filePath}`, filePath);
+    }
+    throw new ParseError(
+      `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+      filePath
+    );
+  }
+}
+
+/**
+ * Get all tasks for a specific module
+ */
+export function getModuleTasks(plan: LoadedPlan, moduleId: string): Task[] {
+  const module = plan.modules.get(moduleId);
+  return module?.tasks ?? [];
+}
+
+/**
+ * Get all modules that depend on a specific module
+ */
+export function getDependentModules(plan: LoadedPlan, moduleId: string): string[] {
+  const dependents: string[] = [];
+
+  for (const [id, deps] of plan.dependencyGraph) {
+    if (deps.includes(moduleId)) {
+      dependents.push(id);
+    }
+  }
+
+  return dependents;
+}
+
+/**
+ * Get modules in topological order (dependencies first)
+ */
+export function getModulesInOrder(plan: LoadedPlan): string[] {
+  const visited = new Set<string>();
+  const result: string[] = [];
+
+  function visit(moduleId: string) {
+    if (visited.has(moduleId)) return;
+    visited.add(moduleId);
+
+    const deps = plan.dependencyGraph.get(moduleId) ?? [];
+    for (const dep of deps) {
+      visit(dep);
+    }
+
+    result.push(moduleId);
+  }
+
+  for (const moduleId of plan.modules.keys()) {
+    visit(moduleId);
+  }
+
+  return result;
+}
+
+/**
+ * Check for circular dependencies in the plan
+ */
+export function detectCycles(plan: LoadedPlan): string[][] {
+  const cycles: string[][] = [];
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+  const path: string[] = [];
+
+  function dfs(moduleId: string): boolean {
+    visited.add(moduleId);
+    recursionStack.add(moduleId);
+    path.push(moduleId);
+
+    const deps = plan.dependencyGraph.get(moduleId) ?? [];
+    for (const dep of deps) {
+      if (!visited.has(dep)) {
+        if (dfs(dep)) {
+          return true;
+        }
+      } else if (recursionStack.has(dep)) {
+        // Found a cycle
+        const cycleStart = path.indexOf(dep);
+        cycles.push([...path.slice(cycleStart), dep]);
+      }
+    }
+
+    path.pop();
+    recursionStack.delete(moduleId);
+    return false;
+  }
+
+  for (const moduleId of plan.modules.keys()) {
+    if (!visited.has(moduleId)) {
+      dfs(moduleId);
+    }
+  }
+
+  return cycles;
+}
+
+// Re-export types
+export type { ParsedIndex } from '../parser/parse-index.js';
+export type { ParsedDocument } from '../types/index.js';