orbital-command 0.2.0 → 1.0.0

package/server/parsers/scope-parser.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { normalizeStatus, inferStatusFromDir, setValidStatuses, parseScopeFile, parseAllScopes } from './scope-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// ─── Pure function tests (no I/O) ──────────────────────────
+
+describe('normalizeStatus()', () => {
+  it('maps "in-progress" to "implementing"', () => {
+    expect(normalizeStatus('in-progress')).toBe('implementing');
+  });
+
+  it('maps "in_progress" to "implementing"', () => {
+    expect(normalizeStatus('in_progress')).toBe('implementing');
+  });
+
+  it('maps "complete" to "completed"', () => {
+    expect(normalizeStatus('complete')).toBe('completed');
+  });
+
+  it('maps "done" to "production"', () => {
+    expect(normalizeStatus('done')).toBe('production');
+  });
+
+  it('maps "exploring" to "planning"', () => {
+    expect(normalizeStatus('exploring')).toBe('planning');
+  });
+
+  it('maps "blocked" to "backlog"', () => {
+    expect(normalizeStatus('blocked')).toBe('backlog');
+  });
+
+  it('maps "testing" to "review"', () => {
+    expect(normalizeStatus('testing')).toBe('review');
+  });
+
+  it('returns identity for already-valid statuses', () => {
+    expect(normalizeStatus('implementing')).toBe('implementing');
+    expect(normalizeStatus('icebox')).toBe('icebox');
+    expect(normalizeStatus('staging')).toBe('staging');
+  });
+
+  it('returns raw value for unknown statuses', () => {
+    expect(normalizeStatus('custom-status')).toBe('custom-status');
+  });
+});
+
+describe('setValidStatuses() + inferStatusFromDir()', () => {
+  beforeEach(() => {
+    setValidStatuses(['icebox', 'planning', 'backlog', 'implementing', 'review', 'completed', 'main']);
+  });
+
+  it('returns dir name when it is a valid status', () => {
+    expect(inferStatusFromDir('implementing')).toBe('implementing');
+    expect(inferStatusFromDir('backlog')).toBe('backlog');
+  });
+
+  it('returns "planning" for unknown dir name', () => {
+    expect(inferStatusFromDir('unknown-dir')).toBe('planning');
+  });
+
+  it('returns dir name as-is when validDirStatuses not yet set', () => {
+    // Reset by setting to a set that doesn't include our test value
+    setValidStatuses([]);
+    expect(inferStatusFromDir('anything')).toBe('planning');
+  });
+});
+
+// ─── File-based tests ───────────────────────────────────────
+
+describe('parseScopeFile()', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-'));
+    setValidStatuses(['icebox', 'planning', 'backlog', 'implementing', 'review', 'completed', 'main']);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeScopeFile(subDir: string, filename: string, content: string): string {
+    const dir = path.join(tmpDir, subDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, filename);
+    fs.writeFileSync(filePath, content);
+    return filePath;
+  }
+
+  it('parses YAML frontmatter scope', () => {
+    const file = writeScopeFile('backlog', '001-test-scope.md', `---
+title: Test Scope
+status: backlog
+priority: high
+tags: [feature, backend]
+blocked_by: [2, 3]
+---
+# Test Scope
+
+Some content here.
+`);
+    const result = parseScopeFile(file);
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(1);
+    expect(result!.title).toBe('Test Scope');
+    expect(result!.status).toBe('backlog');
+    expect(result!.priority).toBe('high');
+    expect(result!.tags).toEqual(['feature', 'backend']);
+    expect(result!.blocked_by).toEqual([2, 3]);
+    expect(result!.raw_content).toContain('Some content here.');
+  });
+
+  it('extracts ID with suffix encoding: a→1000+base', () => {
+    const file = writeScopeFile('implementing', '047a-variant.md', `---
+title: Variant A
+status: implementing
+---
+Content
+`);
+    const result = parseScopeFile(file);
+    expect(result!.id).toBe(1047); // 1000 + 47
+  });
+
+  it('extracts ID with suffix encoding: X→9000+base', () => {
+    const file = writeScopeFile('review', '075X-experimental.md', `---
+title: Experimental
+status: review
+---
+Content
+`);
+    const result = parseScopeFile(file);
+    expect(result!.id).toBe(9075); // 9000 + 75
+  });
+
+  it('generates negative hash ID for slug-only icebox files', () => {
+    const file = writeScopeFile('icebox', 'onboarding-flow.md', `---
+title: Onboarding Flow
+status: icebox
+---
+An idea for onboarding.
+`);
+    const result = parseScopeFile(file);
+    expect(result).not.toBeNull();
+    expect(result!.id).toBeLessThan(0);
+    expect(result!.slug).toBe('onboarding-flow');
+  });
+
+  it('parses markdown-only scope (no YAML)', () => {
+    const file = writeScopeFile('planning', '010-markdown-only.md', `# Scope 010: Markdown Feature
+## Priority: high
+## Estimated Effort: 3 days
+## Category: Backend
+
+Implementation details...
+`);
+    const result = parseScopeFile(file);
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(10);
+    expect(result!.title).toBe('Markdown Feature');
+    expect(result!.priority).toBe('high');
+    expect(result!.effort_estimate).toBe('3 days');
+    expect(result!.category).toBe('Backend');
+  });
+
+  it('rejects invalid priority', () => {
+    const file = writeScopeFile('backlog', '002-test.md', `---
+title: Bad Priority
+status: backlog
+priority: urgent
+---
+Content
+`);
+    const result = parseScopeFile(file);
+    expect(result!.priority).toBeNull();
+  });
+
+  it('validates session keys', () => {
+    const file = writeScopeFile('implementing', '003-sessions.md', `---
+title: With Sessions
+status: implementing
+sessions:
+  implementScope: ["session-1"]
+  invalidKey: ["session-2"]
+---
+Content
+`);
+    const result = parseScopeFile(file);
+    expect(result!.sessions).toHaveProperty('implementScope');
+    expect(result!.sessions).not.toHaveProperty('invalidKey');
+  });
+
+  it('handles ghost scopes', () => {
+    const file = writeScopeFile('icebox', '004-ghost.md', `---
+title: Ghost Idea
+status: icebox
+ghost: true
+---
+AI-generated idea
+`);
+    const result = parseScopeFile(file);
+    expect(result!.is_ghost).toBe(true);
+  });
+
+  it('returns null for template/non-scope files', () => {
+    const file = writeScopeFile('backlog', '_template.md', `---
+title: Template
+---
+Template content
+`);
+    expect(parseScopeFile(file)).toBeNull();
+  });
+});
+
+describe('parseAllScopes()', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scopes-test-'));
+    setValidStatuses(['icebox', 'planning', 'backlog', 'implementing']);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('recursively scans and parses all .md files', () => {
+    const backlogDir = path.join(tmpDir, 'backlog');
+    const planningDir = path.join(tmpDir, 'planning');
+    fs.mkdirSync(backlogDir, { recursive: true });
+    fs.mkdirSync(planningDir, { recursive: true });
+
+    fs.writeFileSync(path.join(backlogDir, '001-first.md'), '---\ntitle: First\nstatus: backlog\n---\nContent\n');
+    fs.writeFileSync(path.join(planningDir, '002-second.md'), '---\ntitle: Second\nstatus: planning\n---\nContent\n');
+
+    const scopes = parseAllScopes(tmpDir);
+    expect(scopes).toHaveLength(2);
+    expect(scopes[0].id).toBe(1);
+    expect(scopes[1].id).toBe(2);
+  });
+
+  it('deduplicates by ID (first-seen wins)', () => {
+    const dir1 = path.join(tmpDir, 'backlog');
+    const dir2 = path.join(tmpDir, 'planning');
+    fs.mkdirSync(dir1, { recursive: true });
+    fs.mkdirSync(dir2, { recursive: true });
+
+    fs.writeFileSync(path.join(dir1, '001-original.md'), '---\ntitle: Original\nstatus: backlog\n---\n');
+    fs.writeFileSync(path.join(dir2, '001-duplicate.md'), '---\ntitle: Duplicate\nstatus: planning\n---\n');
+
+    const scopes = parseAllScopes(tmpDir);
+    expect(scopes).toHaveLength(1);
+  });
+
+  it('returns empty array for non-existent directory', () => {
+    expect(parseAllScopes('/tmp/nonexistent-scopes-dir')).toEqual([]);
+  });
+
+  it('returns sorted by ID', () => {
+    const dir = path.join(tmpDir, 'backlog');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, '003-third.md'), '---\ntitle: Third\nstatus: backlog\n---\n');
+    fs.writeFileSync(path.join(dir, '001-first.md'), '---\ntitle: First\nstatus: backlog\n---\n');
+    fs.writeFileSync(path.join(dir, '002-second.md'), '---\ntitle: Second\nstatus: backlog\n---\n');
+
+    const scopes = parseAllScopes(tmpDir);
+    expect(scopes.map(s => s.id)).toEqual([1, 2, 3]);
+  });
+});

package/server/parsers/scope-parser.ts

@@ -8,6 +8,7 @@ const log = createLogger('scope');
 export interface ParsedScope {
   id: number;
   title: string;
+  slug?: string;
   status: string;
   priority: string | null;
   effort_estimate: string | null;
@@ -21,6 +22,7 @@ export interface ParsedScope {
   raw_content: string;
   sessions: Record<string, string[]>;
   is_ghost: boolean;
+  favourite: boolean;
 }
 
 const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
@@ -69,35 +71,73 @@ export function normalizeStatus(raw: string): string {
   return STATUS_MAP[raw] ?? raw;
 }
 
+/** Generate a stable positive integer hash from a string (for synthetic icebox IDs) */
+function slugHash(s: string): number {
+  let hash = 5381;
+  for (let i = 0; i < s.length; i++) {
+    hash = ((hash << 5) + hash + s.charCodeAt(i)) >>> 0;
+  }
+  // Keep in range 10000-2147483647 to avoid collisions with real scope IDs and suffix-encoded IDs
+  return 10000 + (hash % 2137483647);
+}
+
 /**
  * Parse a scope markdown file into structured data.
  * Handles both YAML frontmatter and plain markdown formats.
  */
 export function parseScopeFile(filePath: string): ParsedScope | null {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const fileName = path.basename(filePath, '.md');
-  const dirName = path.basename(path.dirname(filePath));
-
-  // Extract ID from filename pattern: NNN[suffix]-description.md
-  // Suffixes (a-d, X) encode as thousands offset for unique DB keys
-  const idMatch = fileName.match(/^(\d+)([a-dA-DxX])?/);
-  const fileId = idMatch ? scopeFileId(parseInt(idMatch[1], 10), idMatch[2]) : 0;
-
-  // Skip non-scope files
-  if (fileId === 0 && !fileName.startsWith('0')) {
-    // Files like _template.md, technical-debt.md, backlog_plan.md
-    if (fileName.startsWith('_') || !idMatch) return null;
-  }
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const fileName = path.basename(filePath, '.md');
+    const dirName = path.basename(path.dirname(filePath));
 
-  // Try YAML frontmatter first
-  const { data: frontmatter, content: markdownBody } = matter(content);
+    // Extract ID from filename pattern: NNN[suffix]-description.md
+    // Suffixes (a-d, X) encode as thousands offset for unique DB keys
+    const idMatch = fileName.match(/^(\d+)([a-dA-DxX])?/);
+    const fileId = idMatch ? scopeFileId(parseInt(idMatch[1], 10), idMatch[2]) : 0;
 
-  if (frontmatter && Object.keys(frontmatter).length > 0) {
-    return parseFrontmatterScope(frontmatter, markdownBody, filePath, fileId, dirName);
-  }
+    // Slug-only icebox files: no numeric prefix, e.g. "onboarding-flow.md"
+    const isSlugOnly = !idMatch && dirName === 'icebox';
+
+    // Skip non-scope files (but allow slug-only icebox files)
+    if (fileId === 0 && !fileName.startsWith('0') && !isSlugOnly) {
+      // Files like _template.md, technical-debt.md, backlog_plan.md
+      if (fileName.startsWith('_') || !idMatch) return null;
+    }
+
+    // For slug-only icebox files, generate a stable negative ID for internal cache indexing.
+    // This avoids collisions with real scope IDs (positive) and between icebox items.
+    const effectiveId = isSlugOnly ? -slugHash(fileName) : fileId;
 
-  // Fallback: extract from markdown structure
-  return parseMarkdownScope(content, filePath, fileId, dirName);
+    // Try YAML frontmatter first
+    let frontmatter: Record<string, unknown>;
+    let markdownBody: string;
+    try {
+      ({ data: frontmatter, content: markdownBody } = matter(content));
+    } catch (err) {
+      log.warn('Skipping scope with malformed YAML frontmatter', { file: filePath, error: (err as Error).message });
+      return null;
+    }
+
+    if (frontmatter && Object.keys(frontmatter).length > 0) {
+      const scope = parseFrontmatterScope(frontmatter, markdownBody, filePath, effectiveId, dirName);
+      // Populate slug for icebox items
+      if (isSlugOnly || dirName === 'icebox') {
+        scope.slug = isSlugOnly ? fileName : fileName.replace(/^\d+[a-dA-DxX]?-/, '');
+      }
+      return scope;
+    }
+
+    // Fallback: extract from markdown structure
+    const fallbackScope = parseMarkdownScope(content, filePath, effectiveId, dirName);
+    if (isSlugOnly || dirName === 'icebox') {
+      fallbackScope.slug = isSlugOnly ? fileName : fileName.replace(/^\d+[a-dA-DxX]?-/, '');
+    }
+    return fallbackScope;
+  } catch (err) {
+    log.warn('Failed to parse scope file', { file: filePath, error: (err as Error).message });
+    return null;
+  }
 }
 
 function parseFrontmatterScope(
@@ -128,6 +168,7 @@ function parseFrontmatterScope(
     raw_content: body.trim(),
     sessions: parseSessions(fm.sessions),
     is_ghost: fm.ghost === true,
+    favourite: fm.favourite === true,
   };
 }
 
@@ -173,6 +214,7 @@ function parseMarkdownScope(
     raw_content: content,
     sessions: {},
     is_ghost: false,
+    favourite: false,
   };
 }
 
@@ -194,7 +236,7 @@ export function setValidStatuses(statuses: Iterable<string>): void {
   validDirStatuses = new Set(statuses);
 }
 
-function inferStatusFromDir(dirName: string): string {
+export function inferStatusFromDir(dirName: string): string {
   if (validDirStatuses) {
     return validDirStatuses.has(dirName) ? dirName : 'planning';
   }
@@ -215,26 +257,32 @@ export function parseAllScopes(scopesDir: string): ParsedScope[] {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        scanDir(fullPath);
-      } else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
-        const parsed = parseScopeFile(fullPath);
-        if (parsed) scopes.push(parsed);
+      try {
+        if (entry.isDirectory()) {
+          scanDir(fullPath);
+        } else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
+          const parsed = parseScopeFile(fullPath);
+          if (parsed) scopes.push(parsed);
+        }
+      } catch (err) {
+        log.warn('Failed to process scope entry', { file: fullPath, error: (err as Error).message });
       }
     }
   }
 
   scanDir(scopesDir);
 
-  // Detect ID collisions — last-write-wins but warn on stderr
+  // Detect ID collisions — first-seen wins, duplicates are dropped
   const seen = new Map<number, string>();
-  for (const scope of scopes) {
+  const deduped = scopes.filter(scope => {
     const existing = seen.get(scope.id);
     if (existing) {
       log.error('Scope ID collision — renumber one of them', { id: scope.id, existing, duplicate: scope.file_path });
+      return false;
     }
     seen.set(scope.id, scope.file_path);
-  }
+    return true;
+  });
 
-  return scopes.sort((a, b) => a.id - b.id);
+  return deduped.sort((a, b) => a.id - b.id);
 }