@eddacraft/anvil-aps 0.1.0

package/src/validator/validator.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Validator module tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validatePlanningDoc, formatValidationIssues, type ValidationResult } from './index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixturesDir = join(__dirname, '__fixtures__');
+
+describe('validatePlanningDoc', () => {
+  describe('valid documents', () => {
+    it('should validate a valid leaf spec with no errors', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'valid-leaf.aps.md'));
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should validate a valid index file with linked modules', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'valid-index.aps.md'));
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  describe('required-sections rule', () => {
+    it('should error when leaf spec is missing H1 title', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-h1.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'required-sections')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('H1 title'))).toBe(true);
+    });
+
+    it('should error when leaf spec is missing ## Tasks section', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-tasks-section.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'required-sections')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('## Tasks'))).toBe(true);
+    });
+
+    it('should error when index file is missing ## Modules section', async () => {
+      // This file doesn't have ## Modules, so it's treated as a leaf spec
+      // and will error because it's missing ## Tasks
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-modules-section.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'required-sections')).toBe(true);
+    });
+  });
+
+  describe('task-format rule', () => {
+    it('should error when task heading has invalid format', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'invalid-task-id.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'task-format')).toBe(true);
+    });
+
+    it('should error on lowercase task IDs', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'invalid-task-id.aps.md'));
+
+      const formatErrors = result.errors.filter((e) => e.rule === 'task-format');
+      expect(formatErrors.some((e) => e.message.includes('test-001'))).toBe(true);
+    });
+
+    it('should error on task IDs with non-3-digit numbers', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'invalid-task-id.aps.md'));
+
+      const formatErrors = result.errors.filter((e) => e.rule === 'task-format');
+      expect(formatErrors.some((e) => e.message.includes('T-1'))).toBe(true);
+    });
+
+    it('should error on task IDs with scope longer than 10 characters', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'invalid-task-id.aps.md'));
+
+      const formatErrors = result.errors.filter((e) => e.rule === 'task-format');
+      expect(formatErrors.some((e) => e.message.includes('VERYLONGSCOPE123-001'))).toBe(true);
+    });
+  });
+
+  describe('task-intent rule', () => {
+    it('should error when task is missing Intent field', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'task-intent')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('Intent'))).toBe(true);
+    });
+  });
+
+  describe('missing-confidence rule (warning)', () => {
+    it('should warn when task is missing Confidence field', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-confidence.aps.md'));
+
+      // Should be valid (warnings don't invalidate)
+      expect(result.valid).toBe(true);
+      expect(result.warnings.some((w) => w.rule === 'missing-confidence')).toBe(true);
+      expect(result.warnings.some((w) => w.message.includes('Confidence'))).toBe(true);
+    });
+  });
+
+  describe('broken-links rule', () => {
+    it('should error when module link points to non-existent file', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'broken-links.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'broken-links')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('nonexistent'))).toBe(true);
+    });
+  });
+
+  describe('duplicate-ids rule', () => {
+    it('should error when same task ID appears in multiple modules', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'duplicate-ids-index.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'duplicate-ids')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('DUP-001'))).toBe(true);
+    });
+  });
+
+  describe('circular-dependencies rule', () => {
+    it('should error when modules have circular dependencies', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'circular-deps-index.aps.md'));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'circular-dependencies')).toBe(true);
+      expect(result.errors.some((e) => e.message.includes('Circular dependency'))).toBe(true);
+    });
+  });
+
+  describe('scope-mismatch rule (warning)', () => {
+    it('should warn when task ID scope prefix does not match module scope', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'scope-mismatch.aps.md'));
+
+      // Should be valid (warnings don't invalidate)
+      expect(result.valid).toBe(true);
+      expect(result.warnings.some((w) => w.rule === 'scope-mismatch')).toBe(true);
+      expect(result.warnings.some((w) => w.message.includes('AUTH-001'))).toBe(true);
+      expect(result.warnings.some((w) => w.message.includes('TEST'))).toBe(true);
+    });
+
+    it('should not warn when task ID scope prefix matches module scope', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'scope-mismatch.aps.md'));
+
+      // TEST-001 should not generate a scope-mismatch warning
+      const testScopeWarnings = result.warnings.filter(
+        (w) => w.rule === 'scope-mismatch' && w.message.includes('TEST-001')
+      );
+      expect(testScopeWarnings).toHaveLength(0);
+    });
+  });
+
+  describe('skipRules option', () => {
+    it('should skip specified rules', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'), {
+        skipRules: ['task-intent', 'missing-confidence'],
+      });
+
+      expect(result.errors.some((e) => e.rule === 'task-intent')).toBe(false);
+      expect(result.warnings.some((w) => w.rule === 'missing-confidence')).toBe(false);
+    });
+  });
+
+  describe('recursive option', () => {
+    it('should not validate linked modules when recursive is false', async () => {
+      const result = await validatePlanningDoc(join(fixturesDir, 'broken-links.aps.md'), {
+        recursive: false,
+      });
+
+      // When not recursive, broken links are not checked
+      expect(result.errors.some((e) => e.rule === 'broken-links')).toBe(false);
+    });
+  });
+
+  describe('file-readable rule', () => {
+    it('should error when file does not exist', async () => {
+      const result = await validatePlanningDoc('/nonexistent/path/file.aps.md');
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.rule === 'file-readable')).toBe(true);
+    });
+  });
+});
+
+describe('formatValidationIssues', () => {
+  it('should format issues for display', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'));
+    const formatted = formatValidationIssues(result);
+
+    expect(formatted).toContain('[ERROR]');
+    expect(formatted).toContain('Intent');
+    expect(formatted).toContain('error(s)');
+    expect(formatted).toContain('warning(s)');
+  });
+
+  it('should return "No issues found" for valid documents', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'valid-leaf.aps.md'));
+    // Valid leaf spec might still have warnings (e.g., missing confidence)
+    // so we test the "no issues" case with a mock
+    expect(result.valid).toBe(true);
+
+    // Test the "no issues" case with a mock result
+    const mockResult: ValidationResult = {
+      valid: true,
+      issues: [],
+      errors: [],
+      warnings: [],
+    };
+    const mockFormatted = formatValidationIssues(mockResult);
+    expect(mockFormatted).toBe('No issues found.');
+  });
+
+  it('should include context in formatted output', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'scope-mismatch.aps.md'));
+    const output = formatValidationIssues(result);
+
+    expect(output).toContain('Module scope:');
+  });
+
+  it('should include line numbers when available', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'));
+    const formatted = formatValidationIssues(result);
+
+    // Should contain file path with line number
+    expect(formatted).toMatch(/\.aps\.md:\d+/);
+  });
+});
+
+describe('ValidationResult structure', () => {
+  it('should separate errors and warnings', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'scope-mismatch.aps.md'));
+
+    expect(result.issues.length).toBe(result.errors.length + result.warnings.length);
+    expect(result.errors.every((e) => e.severity === 'error')).toBe(true);
+    expect(result.warnings.every((w) => w.severity === 'warning')).toBe(true);
+  });
+
+  it('should mark as valid when only warnings exist', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'missing-confidence.aps.md'));
+
+    expect(result.valid).toBe(true);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should mark as invalid when errors exist', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'));
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('should include path and lineNumber in issues where applicable', async () => {
+    const result = await validatePlanningDoc(join(fixturesDir, 'missing-intent.aps.md'));
+
+    const issueWithLocation = result.issues.find((i) => i.path && i.lineNumber);
+    expect(issueWithLocation).toBeDefined();
+    expect(issueWithLocation?.path).toContain('missing-intent.aps.md');
+    expect(typeof issueWithLocation?.lineNumber).toBe('number');
+  });
+});

package/templates/index-full.md

@@ -0,0 +1,94 @@
+# APS Index — [Project Name]
+
+## Problem & Success Criteria
+
+**Problem:** [What problem are we solving? Why does this work matter?]
+
+**Success Criteria:**
+
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [How we know we're done]
+
+## Scope
+
+**In Scope:**
+
+- [What this plan covers]
+- [Boundaries of work]
+
+**Out of Scope:**
+
+- [What this plan explicitly excludes]
+- [Things deferred to future work]
+
+## System Map
+
+[High-level view of modules and their relationships]
+
+```
+[Module A] ──→ [Module B] ──→ [Module C]
+     ↑              ↓
+[External Service]  [Database]
+```
+
+## Milestones
+
+### M1: [Milestone Name]
+
+- [What's included]
+- Modules: [module-a, module-b]
+- Target: [date]
+
+### M2: [Milestone Name]
+
+- [What's included]
+- Modules: [module-c]
+- Target: [date]
+
+## Modules
+
+### [module-id]
+
+- **Path:** [./modules/[module-name].aps.md](./modules/[module-name].aps.md)
+- **Scope:** [SCOPE]
+- **Owner:** @[username]
+- **Status:** Draft
+- **Priority:** [low|medium|high]
+- **Tags:** [tag1, tag2]
+- **Dependencies:** [other-module-id]
+
+### [another-module-id]
+
+- **Path:**
+  [./modules/[another-module].aps.md](./modules/[another-module].aps.md)
+- **Scope:** [SCOPE2]
+- **Owner:** @[username]
+- **Status:** Draft
+- **Priority:** [low|medium|high]
+- **Tags:** [tag1, tag2]
+- **Dependencies:** (none)
+
+## Epics
+
+### [epic-id]
+
+- **Path:** [./epics/[epic-name].aps.md](./epics/[epic-name].aps.md)
+- **Owner:** @[username]
+- **Modules:** [module-id-1, module-id-2]
+- **Milestone:** M1
+
+## Decisions
+
+- **D-001:** [Short decision] — [rationale] ([ADR-001](./decisions/ADR-001.md))
+- **D-002:** [Another decision] — [rationale]
+
+## Risks
+
+- **R-001:** [Risk description] — Mitigation: [approach]
+- **R-002:** [Risk description] — Mitigation: [approach]
+
+## Open Questions
+
+- [Unresolved question 1]
+- [Unresolved question 2]

package/templates/index-minimal.md

@@ -0,0 +1,16 @@
+# [Plan Title]
+
+## Modules
+
+### [module-id]
+
+- **Path:** [./modules/[module-name].aps.md](./modules/[module-name].aps.md)
+- **Scope:** [SCOPE]
+- **Owner:** @[username]
+
+### [another-module-id]
+
+- **Path:**
+  [./modules/[another-module].aps.md](./modules/[another-module].aps.md)
+- **Scope:** [SCOPE2]
+- **Owner:** @[username]

package/templates/index-template.md

@@ -0,0 +1,63 @@
+# [Plan Title]
+
+## Problem & Success Criteria
+
+**Problem:** [What problem are we solving? Why does this work matter?]
+
+**Success Criteria:**
+
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [How we know we're done]
+
+## System Map
+
+[High-level view of modules and their relationships]
+
+- **[module-a]** → depends on → **[module-b]**
+- **[module-c]** — standalone
+
+## Milestones
+
+### M1: [Milestone Name]
+
+- [What's included]
+- Target: [date or modules/features]
+
+### M2: [Milestone Name]
+
+- [What's included]
+- Target: [date or modules/features]
+
+## Modules
+
+### [module-id]
+
+- **Path:** [./modules/[module-name].aps.md](./modules/[module-name].aps.md)
+- **Scope:** [SCOPE]
+- **Owner:** @[username]
+- **Status:** Draft
+- **Priority:** [low|medium|high]
+- **Tags:** [tag1, tag2]
+- **Dependencies:** [other-module-id]
+
+### [another-module-id]
+
+- **Path:**
+  [./modules/[another-module].aps.md](./modules/[another-module].aps.md)
+- **Scope:** [SCOPE2]
+- **Owner:** @[username]
+- **Status:** Draft
+- **Priority:** [low|medium|high]
+- **Tags:** [tag1, tag2]
+- **Dependencies:** (none)
+
+## Decisions
+
+- **D-001:** [Short decision] — [rationale] ([ADR-001](./decisions/ADR-001.md))
+- **D-002:** [Another decision] — [rationale]
+
+## Open Questions
+
+- [Unresolved question 1]
+- [Unresolved question 2]

package/templates/leaf-full.md

@@ -0,0 +1,76 @@
+# Module APS — [Module Name]
+
+**Scope:** [SCOPE] **Owner:** @[username] **Priority:** [low|medium|high]
+
+## Purpose
+
+[Why this module exists and what problem it solves. The "why" behind this work.]
+
+## In Scope / Out of Scope
+
+**In Scope:**
+
+- [What this module WILL do]
+- [Boundaries of responsibility]
+- [Features included]
+
+**Out of Scope:**
+
+- [What this module will NOT do]
+- [Things that belong elsewhere]
+- [Explicit exclusions]
+
+## Assumptions
+
+- [Assumption 1] — Confidence: [low|medium|high]
+- [Assumption 2] — Confidence: [low|medium|high]
+
+## Interfaces
+
+**Depends on:**
+
+- [Service/Module name] — [what we need from it]
+- [External API] — [what we consume]
+
+**Exposes:**
+
+- [Endpoint/API] — [what others can use]
+- [Event/Hook] — [what we publish]
+
+## Tasks
+
+### [SCOPE]-001: [Task title]
+
+**Intent:** [Clear statement of what this task aims to achieve] **Expected
+Outcome:** [What success looks like] **Confidence:** [low|medium|high] **Link:**
+[PROJ-123](https://jira.example.com/browse/PROJ-123) **Scopes:** [SCOPE1,
+SCOPE2] **Tags:** [tag1, tag2, tag3] **Dependencies:** [SCOPE-XXX, OTHER-YYY]
+**Inputs:**
+
+- [Required input 1]
+- [Required input 2]
+
+### [SCOPE]-002: [Another task]
+
+**Intent:** [What this task does] **Expected Outcome:** [Success criteria]
+**Confidence:** [low|medium|high] **Link:**
+[PROJ-124](https://jira.example.com/browse/PROJ-124) **Scopes:** [SCOPE]
+**Dependencies:** [SCOPE]-001
+
+## Decisions
+
+- **D-001:** [Short decision] — [rationale] ([ADR-001](../decisions/ADR-001.md))
+- **D-002:** [Another decision] — [rationale]
+
+## Risks
+
+- **R-001:** [Risk description] — Mitigation: [approach]
+
+## Open Questions
+
+- [Unresolved question about this module]
+
+## Notes
+
+- [Additional context or considerations]
+- [Links to relevant resources]

package/templates/leaf-minimal.md

@@ -0,0 +1,14 @@
+# [Module Title]
+
+**Scope:** [SCOPE] **Owner:** @[username]
+
+## Tasks
+
+### [SCOPE]-001: [Task title]
+
+**Intent:** [What this task aims to achieve] **Confidence:** [low|medium|high]
+
+### [SCOPE]-002: [Another task]
+
+**Intent:** [What this task does] **Confidence:** [low|medium|high]
+**Dependencies:** [SCOPE]-001

package/templates/leaf-template.md

@@ -0,0 +1,55 @@
+# [Module Title]
+
+**Scope:** [SCOPE] **Owner:** @[username] **Priority:** [low|medium|high]
+
+## Purpose
+
+[Why this module exists and what problem it solves]
+
+## In Scope / Out of Scope
+
+**In Scope:**
+
+- [What this module WILL do]
+- [Boundaries of responsibility]
+
+**Out of Scope:**
+
+- [What this module will NOT do]
+- [Things that belong elsewhere]
+
+## Interfaces
+
+**Depends on:**
+
+- [Service/Module name] — [what we need from it]
+
+**Exposes:**
+
+- [Endpoint/API] — [what others can use]
+
+## Tasks
+
+### [SCOPE]-001: [Task title]
+
+**Intent:** [Clear statement of what this task aims to achieve] **Expected
+Outcome:** [What success looks like] **Confidence:** [low|medium|high] **Link:**
+[PROJ-123](https://jira.example.com/browse/PROJ-123) **Scopes:** [SCOPE1,
+SCOPE2] **Tags:** [tag1, tag2, tag3] **Dependencies:** [SCOPE-XXX, OTHER-YYY]
+**Inputs:**
+
+- [Required input 1]
+- [Required input 2]
+
+### [SCOPE]-002: [Another task]
+
+**Intent:** [What this task does] **Confidence:** [low|medium|high] **Scopes:**
+[SCOPE] **Dependencies:** [SCOPE]-001
+
+## Decisions
+
+- **D-001:** [Short decision] — [rationale]
+
+## Notes
+
+- [Additional context or considerations]

package/templates/simple-full.md

@@ -0,0 +1,56 @@
+# Feature: [Feature Name]
+
+**Scope:** [SCOPE] **Owner:** @[username] **Priority:** [low|medium|high]
+
+## Purpose
+
+[Why we're building this feature and what problem it solves]
+
+## Success Criteria
+
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [How we know we're done]
+
+## In Scope / Out of Scope
+
+**In Scope:**
+
+- [What this feature WILL do]
+
+**Out of Scope:**
+
+- [What this feature will NOT do]
+
+## Assumptions
+
+- [Assumption 1] — Confidence: [low|medium|high]
+
+## Tasks
+
+### [SCOPE]-001: [First task]
+
+**Intent:** [What this task achieves] **Expected Outcome:** [Success criteria]
+**Confidence:** [low|medium|high] **Link:**
+[PROJ-123](https://jira.example.com/browse/PROJ-123) **Scopes:** [SCOPE]
+**Tags:** [tag1, tag2] **Inputs:**
+
+- [Required input 1]
+
+### [SCOPE]-002: [Second task]
+
+**Intent:** [What this task achieves] **Expected Outcome:** [Success criteria]
+**Confidence:** [low|medium|high] **Scopes:** [SCOPE] **Dependencies:**
+[SCOPE]-001
+
+## Decisions
+
+- **D-001:** [Decision] — [rationale]
+
+## Open Questions
+
+- [Unresolved question]
+
+## Notes
+
+- [Additional notes or considerations]

package/templates/simple-minimal.md

@@ -0,0 +1,14 @@
+# [Feature Name]
+
+**Scope:** [SCOPE] **Owner:** @[username]
+
+## Tasks
+
+### [SCOPE]-001: [First task]
+
+**Intent:** [What this task achieves] **Confidence:** [low|medium|high]
+
+### [SCOPE]-002: [Second task]
+
+**Intent:** [What this task achieves] **Confidence:** [low|medium|high]
+**Dependencies:** [SCOPE]-001

package/templates/simple-template.md

@@ -0,0 +1,30 @@
+# Feature: [Feature Name]
+
+**Scope:** [SCOPE] **Owner:** @[username] **Priority:** [low|medium|high]
+
+## Purpose
+
+[Why we're building this feature and what problem it solves]
+
+## Success Criteria
+
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+
+## Tasks
+
+### [SCOPE]-001: [First task]
+
+**Intent:** [What this task achieves] **Expected Outcome:** [Success criteria]
+**Confidence:** [low|medium|high] **Link:**
+[PROJ-123](https://jira.example.com/browse/PROJ-123) **Scopes:** [SCOPE]
+**Tags:** [tag1, tag2]
+
+### [SCOPE]-002: [Second task]
+
+**Intent:** [What this task achieves] **Confidence:** [low|medium|high]
+**Scopes:** [SCOPE] **Dependencies:** [SCOPE]-001
+
+## Notes
+
+- [Additional notes or considerations]