@eddacraft/anvil-aps 0.1.0

package/src/templates/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Template generation for APS planning documents
+ */
+
+export * from './generator.js';

package/src/types/index.ts

@@ -0,0 +1,168 @@
+/**
+ * APS type definitions and schemas
+ */
+
+import { z } from 'zod';
+
+/**
+ * Task confidence levels
+ */
+export const ConfidenceSchema = z.enum(['low', 'medium', 'high']);
+export type Confidence = z.infer<typeof ConfidenceSchema>;
+
+/**
+ * Task status values
+ * Note: Status is managed externally in .anvil/state.json
+ */
+export const TaskStatusSchema = z.enum(['open', 'locked', 'completed', 'cancelled']);
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+
+/**
+ * Priority levels
+ */
+export const PrioritySchema = z.enum(['low', 'medium', 'high']);
+export type Priority = z.infer<typeof PrioritySchema>;
+
+/**
+ * Parsed task from APS document
+ */
+/** Task ID regex: 1-10 uppercase alphanumeric scope, hyphen, 3-digit zero-padded number */
+export const TASK_ID_REGEX = /^[A-Z0-9]{1,10}-\d{3}$/;
+
+export const TaskSchema = z.object({
+  /** Task ID in format SCOPE-NUMBER (e.g., AUTH-001, LLM2-007) */
+  id: z.string().regex(TASK_ID_REGEX),
+
+  /** Task title (after the ID and colon in H3 heading) */
+  title: z.string(),
+
+  /** What the task aims to achieve (required) */
+  intent: z.string(),
+
+  /** Success criteria (optional) */
+  expectedOutcome: z.string().optional(),
+
+  /** Command or method to verify task completion (optional) */
+  validation: z.string().optional(),
+
+  /** Certainty about approach (optional, defaults to 'medium') */
+  confidence: ConfidenceSchema.default('medium'),
+
+  /** What can be changed - LLM file access constraints (optional) */
+  scopes: z.array(z.string()).optional(),
+
+  /** What will NOT be changed (optional) */
+  nonScope: z.array(z.string()).optional(),
+
+  /** Best-effort list of files that may be affected (optional) */
+  files: z.array(z.string()).optional(),
+
+  /** Labels for filtering and search (optional) */
+  tags: z.array(z.string()).optional(),
+
+  /** Tasks that must complete first (optional) */
+  dependencies: z.array(z.string()).optional(),
+
+  /** Required inputs or context (optional) */
+  inputs: z.array(z.string()).optional(),
+
+  /** Potential risks associated with this task (optional) */
+  risks: z.array(z.string()).optional(),
+
+  /** Packages affected by this task (monorepo support) */
+  packages: z.array(z.string()).optional(),
+
+  /** External link (e.g., Jira ticket) (optional) */
+  link: z.string().optional(),
+
+  /** Current execution state (optional, managed externally) */
+  status: TaskStatusSchema.optional(),
+
+  /** Source file path where this task was parsed from */
+  sourcePath: z.string().optional(),
+
+  /** Line number in source file where this task starts */
+  sourceLineNumber: z.number().optional(),
+});
+
+export type Task = z.infer<typeof TaskSchema>;
+
+/**
+ * Module status values
+ * Legacy values (Draft, Complete) are accepted during parsing but normalised
+ * to their canonical equivalents (Proposed, Done).
+ */
+export const ModuleStatusSchema = z.enum(['Proposed', 'Ready', 'In Progress', 'Done', 'Blocked']);
+export type ModuleStatus = z.infer<typeof ModuleStatusSchema>;
+
+/**
+ * Module metadata from index files or leaf spec headers
+ */
+export const ModuleMetadataSchema = z.object({
+  /** Module identifier (e.g., 'auth', 'payments') */
+  id: z.string().optional(),
+
+  /** Module title from H1 heading */
+  title: z.string().optional(),
+
+  /** Path to leaf spec file (for index files) */
+  path: z.string().optional(),
+
+  /** Scope prefix for task IDs (e.g., AUTH, PAY) */
+  scope: z.string().optional(),
+
+  /** Person/team responsible */
+  owner: z.string().optional(),
+
+  /** Current module status */
+  status: ModuleStatusSchema.optional(),
+
+  /** Priority level */
+  priority: PrioritySchema.optional(),
+
+  /** Tags for filtering */
+  tags: z.array(z.string()).optional(),
+
+  /** Modules this depends on */
+  dependencies: z.array(z.string()).optional(),
+
+  /** Packages affected by this module (monorepo support) */
+  packages: z.array(z.string()).optional(),
+});
+
+export type ModuleMetadata = z.infer<typeof ModuleMetadataSchema>;
+
+/**
+ * Parsed leaf spec document result
+ * For index files, use ParsedIndex from the parser module
+ */
+export interface ParsedDocument {
+  /** Document title from H1 */
+  title: string;
+
+  /** Module metadata from header line */
+  metadata?: ModuleMetadata;
+
+  /** List of tasks */
+  tasks: Task[];
+
+  /** Source file path */
+  sourcePath?: string;
+}
+
+/**
+ * Parser error with context
+ */
+export class ParseError extends Error {
+  constructor(
+    message: string,
+    public readonly sourcePath?: string,
+    public readonly lineNumber?: number,
+    public readonly context?: string
+  ) {
+    super(message);
+    this.name = 'ParseError';
+  }
+}
+
+// ValidationResult is exported from validator/index.ts

package/src/validator/__fixtures__/broken-links.aps.md

@@ -0,0 +1,10 @@
+# Project Plan
+
+> Index with broken module links.
+
+## Modules
+
+### auth
+
+- **Path:** [./modules/nonexistent.aps.md](./modules/nonexistent.aps.md)
+- **Scope:** AUTH

package/src/validator/__fixtures__/circular-deps-index.aps.md

@@ -0,0 +1,26 @@
+# Project Plan
+
+> Index for testing circular dependency detection.
+
+## Modules
+
+### module-a
+
+- **Path:**
+  [./circular-modules/module-a.aps.md](./circular-modules/module-a.aps.md)
+- **Scope:** CIRC
+- **Dependencies:** module-b
+
+### module-b
+
+- **Path:**
+  [./circular-modules/module-b.aps.md](./circular-modules/module-b.aps.md)
+- **Scope:** CIRC
+- **Dependencies:** module-c
+
+### module-c
+
+- **Path:**
+  [./circular-modules/module-c.aps.md](./circular-modules/module-c.aps.md)
+- **Scope:** CIRC
+- **Dependencies:** module-a

package/src/validator/__fixtures__/circular-modules/module-a.aps.md

@@ -0,0 +1,9 @@
+# Module A
+
+**Scope:** CIRC
+
+## Tasks
+
+### CIRC-001: Task A
+
+**Intent:** Task in module A **Confidence:** high

package/src/validator/__fixtures__/circular-modules/module-b.aps.md

@@ -0,0 +1,9 @@
+# Module B
+
+**Scope:** CIRC
+
+## Tasks
+
+### CIRC-002: Task B
+
+**Intent:** Task in module B **Confidence:** high

package/src/validator/__fixtures__/circular-modules/module-c.aps.md

@@ -0,0 +1,9 @@
+# Module C
+
+**Scope:** CIRC
+
+## Tasks
+
+### CIRC-003: Task C
+
+**Intent:** Task in module C **Confidence:** high

package/src/validator/__fixtures__/dup-modules/module-a.aps.md

@@ -0,0 +1,9 @@
+# Module A
+
+**Scope:** DUP
+
+## Tasks
+
+### DUP-001: First task
+
+**Intent:** This task ID will be duplicated **Confidence:** high

package/src/validator/__fixtures__/dup-modules/module-b.aps.md

@@ -0,0 +1,9 @@
+# Module B
+
+**Scope:** DUP
+
+## Tasks
+
+### DUP-001: Duplicate task
+
+**Intent:** This task ID is duplicated from module-a **Confidence:** high

package/src/validator/__fixtures__/duplicate-ids-index.aps.md

@@ -0,0 +1,15 @@
+# Project Plan
+
+> Index for testing duplicate ID detection.
+
+## Modules
+
+### module-a
+
+- **Path:** [./dup-modules/module-a.aps.md](./dup-modules/module-a.aps.md)
+- **Scope:** DUP
+
+### module-b
+
+- **Path:** [./dup-modules/module-b.aps.md](./dup-modules/module-b.aps.md)
+- **Scope:** DUP

package/src/validator/__fixtures__/invalid-task-id.aps.md

@@ -0,0 +1,17 @@
+# Test Module
+
+**Scope:** TEST
+
+## Tasks
+
+### test-001: Lowercase ID
+
+**Intent:** This ID is lowercase which is invalid
+
+### T-1: Too short number
+
+**Intent:** This ID number should be 3 digits
+
+### VERYLONGSCOPE123-001: Scope too long
+
+**Intent:** Scope should be 1-10 characters

package/src/validator/__fixtures__/missing-confidence.aps.md

@@ -0,0 +1,9 @@
+# Test Module
+
+**Scope:** TEST
+
+## Tasks
+
+### TEST-001: Task without confidence
+
+**Intent:** Do something without specifying confidence

package/src/validator/__fixtures__/missing-h1.aps.md

@@ -0,0 +1,5 @@
+## Tasks
+
+### TEST-001: Some task
+
+**Intent:** Do something

package/src/validator/__fixtures__/missing-intent.aps.md

@@ -0,0 +1,9 @@
+# Test Module
+
+**Scope:** TEST
+
+## Tasks
+
+### TEST-001: Task without intent
+
+**Confidence:** high **Expected Outcome:** Something happens

package/src/validator/__fixtures__/missing-modules-section.aps.md

@@ -0,0 +1,7 @@
+# Project Plan
+
+> This index file is missing the Modules section.
+
+## Open Questions
+
+- What modules do we need?

package/src/validator/__fixtures__/missing-tasks-section.aps.md

@@ -0,0 +1,7 @@
+# Test Module
+
+**Scope:** TEST
+
+## Notes
+
+This module has no Tasks section.

package/src/validator/__fixtures__/modules/auth.aps.md

@@ -0,0 +1,17 @@
+# Authentication Module
+
+**Scope:** AUTH **Owner:** @alice
+
+## Tasks
+
+### AUTH-001: Implement login
+
+**Intent:** Create login endpoint **Confidence:** high
+
+### AUTH-002: Add logout
+
+**Intent:** Create logout endpoint **Confidence:** high
+
+## Notes
+
+- Use JWT tokens

package/src/validator/__fixtures__/modules/payments.aps.md

@@ -0,0 +1,13 @@
+# Payments Module
+
+**Scope:** PAY **Owner:** @bob
+
+## Tasks
+
+### PAY-001: Integrate Stripe
+
+**Intent:** Set up Stripe payment processing **Confidence:** medium
+
+### PAY-002: Add invoicing
+
+**Intent:** Generate PDF invoices **Confidence:** low **Dependencies:** PAY-001

package/src/validator/__fixtures__/scope-mismatch.aps.md

@@ -0,0 +1,14 @@
+# Test Module
+
+**Scope:** TEST
+
+## Tasks
+
+### AUTH-001: Wrong scope prefix
+
+**Intent:** This task has AUTH prefix but module scope is TEST **Confidence:**
+high
+
+### TEST-001: Correct scope prefix
+
+**Intent:** This task has matching scope **Confidence:** high

package/src/validator/__fixtures__/valid-index.aps.md

@@ -0,0 +1,24 @@
+# Project Plan
+
+> A multi-module project plan for testing validation.
+
+## Modules
+
+### auth
+
+- **Path:** [./modules/auth.aps.md](./modules/auth.aps.md)
+- **Scope:** AUTH
+- **Owner:** @alice
+- **Priority:** high
+
+### payments
+
+- **Path:** [./modules/payments.aps.md](./modules/payments.aps.md)
+- **Scope:** PAY
+- **Owner:** @bob
+- **Priority:** medium
+- **Dependencies:** auth
+
+## Open Questions
+
+- How do we handle rate limiting?

package/src/validator/__fixtures__/valid-leaf.aps.md

@@ -0,0 +1,22 @@
+# Authentication Module
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+> Handles user authentication and session management.
+
+## Tasks
+
+### AUTH-001: Implement login endpoint
+
+**Intent:** Create POST /auth/login endpoint with JWT response **Confidence:**
+high **Expected Outcome:** Returns JWT token on success, 401 on failure
+**Tags:** security, api
+
+### AUTH-002: Add password reset
+
+**Intent:** Implement password reset flow with email verification
+**Confidence:** medium **Dependencies:** AUTH-001
+
+## Notes
+
+- Consider OAuth support in future