@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/review/review-events.js

@@ -93,7 +93,7 @@ const VALID_VERDICTS = Object.freeze([
  */
 function reviewEventsDir(slug, rootDir = process.cwd()) {
   const missionDir = findMissionDir(slug, rootDir);
-  if (!missionDir) return null;
+  if (!missionDir) {return null;}
   const dir = path.join(missionDir, 'review-events');
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
@@ -118,9 +118,9 @@ function reviewEventsDir(slug, rootDir = process.cwd()) {
  * @param {string} [rootDir] - Root directory to resolve from
  * @returns {string|null} - Absolute file path, or null if mission dir not found
  */
-function eventFilePath(slug, eventType, round, actor, timestamp = null, rootDir = process.cwd()) {
+function eventFilePath(slug, eventType, round, actor, /** @type {string|null} */ timestamp = null, rootDir = process.cwd()) {
   const eventsDir = reviewEventsDir(slug, rootDir);
-  if (!eventsDir) return null;
+  if (!eventsDir) {return null;}
   
   const ts = timestamp || generateEventTimestamp();
   const sanitizedActor = sanitizeFilename(actor);
@@ -161,7 +161,7 @@ function generateEventTimestamp() {
  * @returns {string} - Filesystem-safe string
  */
 function sanitizeFilename(str) {
-  if (!str) return 'unknown';
+  if (!str) {return 'unknown';}
   return String(str)
     .toLowerCase()
     // Replace @ and . with empty string first (common in emails/agent names)
@@ -179,8 +179,8 @@ function sanitizeFilename(str) {
  * @param {string} eventType - The type to validate
  * @returns {boolean} - True if valid
  */
-function isValidEventType(eventType) {
-  return ALL_EVENT_TYPES.includes(eventType);
+function isValidEventType(/** @type {string} */ eventType) {
+  return ALL_EVENT_TYPES.includes(/** @type {typeof ALL_EVENT_TYPES[number]} */ (eventType));
 }
 
 /**
@@ -206,8 +206,8 @@ function isValidVerdict(verdict) {
  * @param {string} eventType - The event type
  * @returns {boolean} - True if mirrored
  */
-function shouldMirrorToProvider(eventType) {
-  return MIRRORED_EVENT_TYPES.has(eventType);
+function shouldMirrorToProvider(/** @type {string} */ eventType) {
+  return MIRRORED_EVENT_TYPES.has(/** @type {typeof MIRRORED_EVENT_TYPES extends Set<infer T> ? T : string} */ (eventType));
 }
 
 // -------- Event Structure --------
@@ -221,8 +221,15 @@ function shouldMirrorToProvider(eventType) {
  * @param {Object} [metadata] - Additional metadata (round, phase, actor, etc.)
  * @returns {Object} - Normalized event structure
  */
+/**
+ * @param {string} content
+ * @param {string} eventType
+ * @param {{[key: string]: any}} [metadata]
+ * @returns {{eventType: string, timestamp: string, content: string}}
+ */
 function normalizeEventContent(content, eventType, metadata = {}) {
-  const payload = { ...metadata };
+  /** @type {{eventType: string, timestamp: string, content: string, [key: string]: any}} */
+  const payload = { eventType, timestamp: '', content, ...metadata };
   
   // Ensure we have the base metadata
   payload.eventType = eventType;
@@ -241,6 +248,10 @@ function normalizeEventContent(content, eventType, metadata = {}) {
  * @param {Object} event - Normalized event structure
  * @returns {string} - Frontmatter block
  */
+/**
+ * @param {{eventType: string, timestamp: string, round?: number, phase?: string, actor?: string, slug?: string, disposition?: string, verdict?: string, fixedItems?: string[], pushedBackItems?: string[], parkedItems?: string[], blockedReason?: string, followUpReference?: string}} event
+ * @returns {string}
+ */
 function buildEventFrontmatter(event) {
   const lines = [
     '---',
@@ -319,7 +330,7 @@ function hasWorkflowFooter(body) {
  * @param {Object} comment - Comment object with body field
  * @returns {string|null} - 'human_note' if human, null if workflow-generated
  */
-function classifyComment(comment) {
+function classifyComment(/** @type {{[key: string]: any}} */ comment) {
   const body = comment.body || '';
   // Workflow-generated comments have the metadata footer
   if (hasWorkflowFooter(body)) {
@@ -349,6 +360,12 @@ function classifyComment(comment) {
  * @param {Function} [options.error] - Error function
  * @returns {Object} - { ok: boolean, created: Array, skipped: Array }
  */
+/**
+ * @param {string} slug
+ * @param {string} actor
+ * @param {{getCommentsFn?: Function, createEventFn?: Function, readTokenFn?: Function, reviewIdentity?: string|null, forgejoUser?: string|null, worktree?: string, log?: Function, error?: Function}} [options]
+ * @returns {Promise<{ok: boolean, created: Array<any>, skipped: Array<any>, error?: string}>}
+ */
 async function consumeHumanNotes(slug, actor, options = {}) {
   const {
     getCommentsFn,
@@ -440,9 +457,13 @@ async function consumeHumanNotes(slug, actor, options = {}) {
  * @param {Object} event - Normalized event structure
  * @returns {string} - Complete file content
  */
+/**
+ * @param {{content?: string, round?: number, phase?: string, slug?: string, eventType?: string, timestamp?: string}} event
+ * @returns {string}
+ */
 function renderEventFile(event) {
-  const frontmatter = buildEventFrontmatter(event);
-  const content = event.content || '';
+  const frontmatter = buildEventFrontmatter(/** @type {{eventType: string, timestamp: string, content?: string, round?: number, phase?: string, slug?: string}} */ (event));
+  const content = /** @type {string} */ (event.content || '');
   
   // If the content already has a metadata footer, don't add another
   const hasFooter = /\n\n---\n`\[workflow-round:\d+, workflow-phase:[^\]]+\]`/.test(content);
@@ -453,7 +474,7 @@ function renderEventFile(event) {
   
   // Add footer if we have round and phase
   const footer = event.round !== undefined && event.phase !== undefined
-    ? buildEventFooter(event.slug, event.round, event.phase)
+    ? buildEventFooter(/** @type {string} */ (event.slug), event.round, event.phase)
     : '';
   
   return `${frontmatter}\n\n${content}${footer}`;
@@ -473,9 +494,9 @@ function renderEventFile(event) {
  * @param {string} [params.actor] - Agent family or 'human'
  * @param {string} [params.disposition] - For implementer disposition events
  * @param {string} [params.verdict] - For reviewer outcome events
- * @param {Array} [params.fixedItems] - For implementer round summary
- * @param {Array} [params.pushedBackItems] - For implementer round summary
- * @param {Array} [params.parkedItems] - For implementer round summary
+ * @param {Array<any>} [params.fixedItems] - For implementer round summary
+ * @param {Array<any>} [params.pushedBackItems] - For implementer round summary
+ * @param {Array<any>} [params.parkedItems] - For implementer round summary
  * @param {string} [params.blockedReason] - For BLOCKED events
  * @param {string} [params.followUpReference] - For PARKED_FOLLOWUP events
  * @param {string} [params.timestamp] - Custom timestamp
@@ -485,6 +506,13 @@ function renderEventFile(event) {
  * @param {Function} [options.gitFn] - Git function override for testing
  * @returns {Object} - { ok: boolean, path: string|null, error: string|null }
  */
+/**
+ * @param {string} slug
+ * @param {string} eventType
+ * @param {{content: string, round?: number, phase?: string, actor?: string, disposition?: string, verdict?: string, fixedItems?: Array<any>, pushedBackItems?: Array<any>, parkedItems?: Array<any>, blockedReason?: string, followUpReference?: string, timestamp?: string}} params
+ * @param {{skipGit?: boolean, gitFn?: Function, log?: Function, error?: Function, worktree?: string, allowMissingRequiredFields?: boolean}} [options]
+ * @returns {{ok: boolean, path: string|null, error?: string|null, event?: Object}}
+ */
 function createEvent(slug, eventType, params, options = {}) {
   const {
     skipGit = false,
@@ -605,6 +633,14 @@ function createEvent(slug, eventType, params, options = {}) {
  * @param {Object} [options] - Options (same as createEvent)
  * @returns {Object} - { ok: boolean, path: string|null, importedFrom: string|null, error: string|null }
  */
+/**
+ * @param {string} slug
+ * @param {string} artifactName
+ * @param {string} eventType
+ * @param {{round?: number, phase?: string, actor?: string}} [params]
+ * @param {{tmpDir?: string, log?: Function, error?: Function, worktree?: string}} [options]
+ * @returns {{ok: boolean, path: string|null, importedFrom: string|null, event?: Object, skipped?: boolean, legacyPath?: string, error?: string}}
+ */
 function importLegacyArtifact(slug, artifactName, eventType, params = {}, options = {}) {
   const {
     tmpDir = os.tmpdir(),
@@ -612,8 +648,7 @@ function importLegacyArtifact(slug, artifactName, eventType, params = {}, option
     error = fmt.log.plainError,
     worktree
   } = options;
-  
-  const rootDir = worktree || resolveWorktree(slug) || process.cwd();
+
   const legacyPath = legacyArtifactPath(slug, artifactName, tmpDir);
   
   // Check if legacy file exists
@@ -626,9 +661,9 @@ function importLegacyArtifact(slug, artifactName, eventType, params = {}, option
   let content;
   try {
     content = fs.readFileSync(legacyPath, 'utf8');
-  } catch (err) {
-    error(fmt.status('FAIL', `Failed to read legacy artifact: ${err.message}`));
-    return { ok: false, path: null, importedFrom: legacyPath, error: err.message };
+  } catch (/** @type {unknown} */ err) {
+    error(fmt.status('FAIL', `Failed to read legacy artifact: ${/** @type {Error} */(err).message}`));
+    return { ok: false, path: null, importedFrom: legacyPath, error: /** @type {Error} */ (err).message };
   }
   
   // Create the normalized event
@@ -637,14 +672,14 @@ function importLegacyArtifact(slug, artifactName, eventType, params = {}, option
     content,
     ...params,
     // Default actor from artifact name
-    actor: params.actor || inferActorFromArtifact(artifactName)
-  }, { ...options, worktree: rootDir, allowMissingRequiredFields: true });
+    actor: params.actor || (/** @type {Function} */ (inferActorFromArtifact))()
+  }, { ...options, worktree: worktree || undefined, allowMissingRequiredFields: true });
   
   if (!result.ok) {
-    return { ok: false, path: null, importedFrom: legacyPath, error: result.error };
+    return { ok: false, path: null, importedFrom: legacyPath, error: /** @type {string | undefined} */ (result.error) };
   }
   
-  log(fmt.status('PASS', `Imported legacy artifact ${artifactName} to ${path.basename(result.path)}`));
+  log(fmt.status('PASS', `Imported legacy artifact ${artifactName} to ${path.basename(/** @type {string} */ (result.path))}`));
   
   return { 
     ok: true, 
@@ -659,7 +694,7 @@ function importLegacyArtifact(slug, artifactName, eventType, params = {}, option
  * Infer actor from legacy artifact name (best guess).
  * In practice, the actor should be passed explicitly from the workflow context.
  */
-function inferActorFromArtifact(artifactName) {
+function inferActorFromArtifact() {
   // Can't reliably infer from artifact name alone
   return 'unknown';
 }
@@ -687,10 +722,14 @@ const LEGACY_ARTIFACT_TO_EVENT_TYPE = Object.freeze({
  * @param {Object} [options] - Options
  * @returns {Object} - { ok: boolean, imported: Array, errors: Array }
  */
+/**
+ * @param {string} slug
+ * @param {{tmpDir?: string, error?: Function, worktree?: string, log?: Function}} [options]
+  * @returns {{ok: boolean, imported: Array<any>, errors: Array<any>}}
+ */
 function importAllLegacyArtifacts(slug, options = {}) {
   const {
     tmpDir = os.tmpdir(),
-    log = fmt.log.plain,
     error = fmt.log.plainError,
     worktree
   } = options;
@@ -705,6 +744,7 @@ function importAllLegacyArtifacts(slug, options = {}) {
   const phase = state ? state.phase : 'reviewing';
   
   // Track which legacy files exist
+  /** @type {{[key: string]: string|null}} */
   const legacyFiles = {};
   for (const artifactName of Object.keys(LEGACY_ARTIFACT_TO_EVENT_TYPE)) {
     const legacyPath = legacyArtifactPath(slug, artifactName, tmpDir);
@@ -724,14 +764,15 @@ function importAllLegacyArtifacts(slug, options = {}) {
         if (fs.existsSync(verdictPath)) {
           verdictContent = fs.readFileSync(verdictPath, 'utf8').trim();
         }
-      } catch (err) {
-        error(fmt.status('WARN', `Failed to read verdict file: ${err.message}`));
+      } catch (/** @type {unknown} */ err) {
+        error(fmt.status('WARN', `Failed to read verdict file: ${/** @type {Error} */(err).message}`));
       }
     }
     
     // Import review-outcome.md with verdict as metadata (only include verdict if valid)
+    /** @type {{round: number, phase: string, actor: string, verdict?: string}} */
     const outcomeParams = { round, phase, actor: 'legacy' };
-    if (verdictContent && isValidVerdict(verdictContent)) {
+    if (verdictContent && isValidVerdict(/** @type {string} */ (verdictContent))) {
       outcomeParams.verdict = verdictContent;
     }
     
@@ -768,12 +809,13 @@ function importAllLegacyArtifacts(slug, options = {}) {
     let verdictContent = null;
     try {
       verdictContent = fs.readFileSync(verdictPath, 'utf8').trim();
-    } catch (err) {
-      error(fmt.status('WARN', `Failed to read verdict file: ${err.message}`));
+    } catch (/** @type {unknown} */ err) {
+      error(fmt.status('WARN', `Failed to read verdict file: ${/** @type {Error} */(err).message}`));
     }
     
+    /** @type {{round: number, phase: string, actor: string, verdict?: string}} */
     const outcomeParams = { round, phase, actor: 'legacy' };
-    if (verdictContent && isValidVerdict(verdictContent)) {
+    if (verdictContent && isValidVerdict(/** @type {string} */ (verdictContent))) {
       outcomeParams.verdict = verdictContent;
     }
     
@@ -797,16 +839,16 @@ function importAllLegacyArtifacts(slug, options = {}) {
       continue;
     }
     
-    const result = importLegacyArtifact(slug, artifactName, LEGACY_ARTIFACT_TO_EVENT_TYPE[artifactName], 
+    const result = importLegacyArtifact(slug, artifactName, /** @type {string} */ (LEGACY_ARTIFACT_TO_EVENT_TYPE[/** @type {keyof typeof LEGACY_ARTIFACT_TO_EVENT_TYPE} */ (artifactName)]), 
       { round, phase, actor: 'legacy' }, 
       { ...options, worktree: rootDir });
     
     if (result.ok) {
       if (result.path) {
-        imported.push({ artifactName, eventType: LEGACY_ARTIFACT_TO_EVENT_TYPE[artifactName], path: result.path, legacyPath: result.legacyPath });
+        imported.push({ artifactName, eventType: LEGACY_ARTIFACT_TO_EVENT_TYPE[/** @type {keyof typeof LEGACY_ARTIFACT_TO_EVENT_TYPE} */ (artifactName)], path: result.path, legacyPath: result.legacyPath });
       }
     } else {
-      errors.push({ artifactName, eventType: LEGACY_ARTIFACT_TO_EVENT_TYPE[artifactName], error: result.error });
+      errors.push({ artifactName, eventType: LEGACY_ARTIFACT_TO_EVENT_TYPE[/** @type {keyof typeof LEGACY_ARTIFACT_TO_EVENT_TYPE} */ (artifactName)], error: result.error });
     }
   }
   
@@ -823,14 +865,18 @@ function importAllLegacyArtifacts(slug, options = {}) {
  * @param {string} [options.rootDir] - Root directory
  * @param {Function} [options.readdirSync] - readdirSync override for testing
  * @param {Function} [options.readFileSync] - readFileSync override for testing
- * @returns {Array} - Array of parsed event objects
+ * @returns {Array<any>} - Array of parsed event objects
+ */
+/**
+ * @param {string} slug
+ * @param {{rootDir?: string, readdirSync?: Function, readFileSync?: Function, error?: Function}} [options]
+ * @returns {Array<any>}
  */
 function readAllEvents(slug, options = {}) {
   const {
     rootDir = process.cwd(),
     readdirSync = fs.readdirSync,
     readFileSync = fs.readFileSync,
-    log = fmt.log.plain,
     error = fmt.log.plainError
   } = options;
   
@@ -844,21 +890,21 @@ function readAllEvents(slug, options = {}) {
   
   try {
     files = readdirSync(eventsDir);
-  } catch (err) {
-    error(fmt.status('WARN', `Failed to read review-events directory: ${err.message}`));
+  } catch (/** @type {unknown} */ err) {
+    error(fmt.status('WARN', `Failed to read review-events directory: ${/** @type {Error} */(err).message}`));
     return [];
   }
   
   for (const filename of files) {
-    if (!filename.endsWith('.md')) continue;
+    if (!filename.endsWith('.md')) {continue;}
     
     const filePath = path.join(eventsDir, filename);
     let content;
     
     try {
       content = readFileSync(filePath, 'utf8');
-    } catch (err) {
-      error(fmt.status('WARN', `Failed to read event file ${filename}: ${err.message}`));
+    } catch (/** @type {unknown} */ err) {
+      error(fmt.status('WARN', `Failed to read event file ${filename}: ${/** @type {Error} */(err).message}`));
       continue;
     }
     
@@ -886,6 +932,11 @@ function readAllEvents(slug, options = {}) {
  * @param {string} filePath - File path (for fallback metadata)
  * @returns {Object|null} - Parsed event or null
  */
+/**
+ * @param {string} content
+ * @param {string} filePath
+ * @returns {{[key: string]: any}|null}
+ */
 function parseEventFile(content, filePath) {
   // Try to parse frontmatter
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
@@ -900,9 +951,9 @@ function parseEventFile(content, filePath) {
     // Parse YAML-like frontmatter
     const lines = frontmatterText.split('\n');
     for (const line of lines) {
-      if (!line.trim()) continue;
+      if (!line.trim()) {continue;}
       const colonIdx = line.indexOf(':');
-      if (colonIdx === -1) continue;
+      if (colonIdx === -1) {continue;}
       
       const key = line.slice(0, colonIdx).trim().toLowerCase();
       const value = line.slice(colonIdx + 1).trim();
@@ -910,21 +961,21 @@ function parseEventFile(content, filePath) {
       // Handle quoted strings
       if ((value.startsWith('"') && value.endsWith('"')) || 
           (value.startsWith("'") && value.endsWith("'"))) {
-        metadata[key] = value.slice(1, -1);
+        /** @type {any} */ (metadata)[key] = value.slice(1, -1);
       }
       // Handle JSON arrays
       else if (value.startsWith('[') && value.endsWith(']')) {
         try {
-          metadata[key] = JSON.parse(value);
+          /** @type {any} */ (metadata)[key] = JSON.parse(value);
         } catch (_) {
-          metadata[key] = value;
+          /** @type {any} */ (metadata)[key] = value;
         }
       }
       // Handle booleans and numbers
-      else if (value === 'true') metadata[key] = true;
-      else if (value === 'false') metadata[key] = false;
-      else if (!isNaN(value)) metadata[key] = Number(value);
-      else metadata[key] = value;
+      else if (value === 'true') {/** @type {any} */ (metadata)[key] = true;}
+      else if (value === 'false') {/** @type {any} */ (metadata)[key] = false;}
+      else if (value !== '' && !isNaN(Number(value))) {/** @type {any} */ (metadata)[key] = Number(value);}
+      else {/** @type {any} */ (metadata)[key] = value;}
     }
   }