@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/review/review-adapter.js

@@ -37,6 +37,7 @@ function isForgejoProvider(rootDir = process.cwd()) {
   return isEnabled(rootDir);
 }
 
+/** @param {string} [rootDir] */
 function resolveArtifactDir(rootDir = process.cwd()) {
   const review = loadAdapterConfig(rootDir).review || {};
   const configured = typeof review.tmpDir === 'string' && review.tmpDir.trim()
@@ -48,65 +49,151 @@ function resolveArtifactDir(rootDir = process.cwd()) {
   return path.isAbsolute(configured) ? configured : path.resolve(rootDir, configured);
 }
 
+/**
+ * @param {string} rootDir
+ * @param {Function} liveFn
+ * @param {*} noopValue
+ * @returns {*}
+ */
 function withForgejo(rootDir, liveFn, noopValue) {
   return isEnabled(rootDir) ? liveFn() : noopValue;
 }
 
+/**
+ * @param {string} branch
+ * @param {string} [rootDir]
+ * @param {{[key: string]: any}} [options]
+ * @returns {*}
+ */
 function getPrStatus(branch, rootDir = process.cwd(), options = {}) {
   return withForgejo(rootDir, () => forgejo.getPrStatus(branch, rootDir, options), NOOP_PR_STATUS);
 }
 
+/**
+ * @param {string} user
+ * @param {{rootDir?: string}} [options]
+ * @returns {string|null}
+ */
 function readToken(user, options = {}) {
   const rootDir = options.rootDir || process.cwd();
   return isEnabled(rootDir) ? forgejo.readToken(user) : null;
 }
 
+/**
+ * @param {number} prNumber
+ * @param {string} reviewerUser
+ * @param {string} sinceIso
+ * @param {string} token
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {Promise<*|null>}
+ */
 async function getLatestReviewForPr(prNumber, reviewerUser, sinceIso, token, options = {}) {
-  if (!token) return null;
+  if (!token) {return null;}
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.getLatestReviewForPr(prNumber, reviewerUser, sinceIso, token, options), null);
 }
 
+/**
+ * @param {number} prNumber
+ * @param {string} implementerUser
+ * @param {string} sinceIso
+ * @param {string} token
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {Promise<*|null>}
+ */
 async function getLatestDispositionForPr(prNumber, implementerUser, sinceIso, token, options = {}) {
-  if (!token) return null;
+  if (!token) {return null;}
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.getLatestDispositionForPr(prNumber, implementerUser, sinceIso, token, options), null);
 }
 
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {string} body
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
 function postComment(branch, token, body, options = {}) {
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.postComment(branch, token, body, options), { ok: true, skipped: true, reason: 'review-provider-disabled' });
 }
 
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {string} outcome
+ * @param {string} summary
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
 function postReview(branch, token, outcome, summary, options = {}) {
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.postReview(branch, token, outcome, summary, options), { ok: true, skipped: true, reason: 'review-provider-disabled' });
 }
 
+/**
+ * @param {string} branch
+ * @param {string} user
+ * @param {string} token
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
 function createPr(branch, user, token, options = {}) {
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.createPr(branch, user, token, options), { ok: true, skipped: true, url: null });
 }
 
-function forgejoAvailable(url = process.env.FORGEJO_URL || 'http://localhost:3300', options = {}) {
-  return withForgejo(options.rootDir || process.cwd(), () => forgejo.forgejoAvailable(url, options), false);
+/**
+ * @param {string} [url]
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
+function forgejoAvailable(url = process.env.FORGEJO_URL || 'http://localhost:3300', /** @type {{rootDir?: string, [key: string]: any}} */ options = {}) {
+  return withForgejo(options.rootDir || process.cwd(), () => forgejo.forgejoAvailable(url, /** @type {{request?: Function, timeout?: number}} */ (options)), false);
 }
 
+/**
+ * @param {string} [url]
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
 function providerAvailable(url = process.env.FORGEJO_URL || 'http://localhost:3300', options = {}) {
   return forgejoAvailable(url, options);
 }
 
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {Promise<*>}
+ */
 async function getComments(branch, token, options = {}) {
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.getComments(branch, token, options), []);
 }
 
-function closePr(branch, token, user, options = {}) {
-  return withForgejo(options.rootDir || process.cwd(), () => forgejo.closePr(branch, token, user, options), { ok: true, skipped: true, reason: 'review-provider-disabled' });
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {string} user
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*}
+ */
+function closePr(branch, token, user, /** @type {{rootDir?: string, [key: string]: any}} */ options = {}) {
+  return withForgejo(options.rootDir || process.cwd(), () => (/** @type {any} */ (forgejo).closePr)(branch, token, user, options), { ok: true, skipped: true, reason: 'review-provider-disabled' });
 }
 
+/** @param {string} explicitUser */
 function resolveForgejoUser(explicitUser) {
   return explicitUser || process.env.FORGEJO_USER || null;
 }
 
+/** @param {string} explicitUser */
 function resolveReviewUser(explicitUser) {
   return resolveForgejoUser(explicitUser);
 }
 
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {{rootDir?: string, [key: string]: any}} [options]
+ * @returns {*|null}
+ */
 function getPrAuthor(branch, token, options = {}) {
   return withForgejo(options.rootDir || process.cwd(), () => forgejo.getPrAuthor(branch, token, options), null);
 }

package/lib/review/review-artifacts.js

@@ -10,16 +10,21 @@ const path = require('path');
 const fmt = require('../core/fmt');
 const { missionBranchName, resolveWorktree } = require('../core/mission-utils');
 const { readReviewState, writeReviewState, reviewStateFile, ReviewState, resolveReviewIdentity } = require('./review-state');
-const { readToken, postComment, postReview, getComments, getPrAuthor, isEnabled, resolveArtifactDir: resolveConfiguredArtifactDir } = require('./review-adapter');
+const { readToken, postComment, postReview, getPrAuthor, isEnabled, resolveArtifactDir: resolveConfiguredArtifactDir } = require('./review-adapter');
 const { createEvent, consumeHumanNotes, VALID_EVENT_TYPES } = require('./review-events');
 
 // ============================================================================
 // Metadata Footer
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {string}
+ */
 function buildMetadataFooter(slug, rootDir) {
   const state = readReviewState(slug, rootDir);
-  if (!state) return '';
+  if (!state) {return '';}
   return `\n\n---\n\`[workflow-round:${state.round}, workflow-phase:${state.phase}]\``;
 }
 
@@ -27,6 +32,12 @@ function buildMetadataFooter(slug, rootDir) {
 // Artifact Path Utilities
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} artifactName
+ * @param {string} [tmpDir]
+ * @returns {string}
+ */
 function reviewArtifactPath(slug, artifactName, tmpDir = os.tmpdir()) {
   return path.join(tmpDir, `${slug}-${artifactName}`);
 }
@@ -44,6 +55,12 @@ function reviewArtifactPath(slug, artifactName, tmpDir = os.tmpdir()) {
 // the loop passes the resolved default dir explicitly. This is defense-in-depth:
 // once the prompts substitute {{artifactDir}}, producer and consumer share one
 // dir by construction and this fallback is rarely exercised.
+/**
+ * @param {string} slug
+ * @param {string} artifactName
+ * @param {{tmpDir: string, explicitTmpDir?: boolean, fallbackToTmp?: boolean, readArtifactFn: Function}} opts
+ * @returns {{path: string, value: string|null}}
+ */
 function resolveArtifactRead(slug, artifactName, { tmpDir, explicitTmpDir, fallbackToTmp, readArtifactFn }) {
   const primaryPath = reviewArtifactPath(slug, artifactName, tmpDir);
   const primaryValue = readArtifactFn(primaryPath);
@@ -77,6 +94,11 @@ function resolveArtifactDir(rootDir = process.cwd()) {
   return resolveConfiguredArtifactDir(rootDir);
 }
 
+/**
+ * @param {string} filePath
+ * @param {Function} [readFileSync]
+ * @returns {string|null}
+ */
 function readArtifactFile(filePath, readFileSync = fs.readFileSync) {
   try {
     const value = readFileSync(filePath, 'utf8');
@@ -86,6 +108,11 @@ function readArtifactFile(filePath, readFileSync = fs.readFileSync) {
   }
 }
 
+/**
+ * @param {string} filePath
+ * @param {Function} [unlinkSync]
+ * @returns {void}
+ */
 function deleteArtifactFile(filePath, unlinkSync = fs.unlinkSync) {
   try {
     unlinkSync(filePath);
@@ -98,11 +125,18 @@ function deleteArtifactFile(filePath, unlinkSync = fs.unlinkSync) {
 // Normalization Utilities
 // ============================================================================
 
+/**
+ * @param {string} value
+ * @returns {string|null}
+ */
 function normalizeReviewVerdict(value) {
   const normalized = String(value || '').trim().toLowerCase();
   return ['approve', 'request-changes', 'comment'].includes(normalized) ? normalized : null;
 }
 
+/** @param {string} value
+ * @returns {string|null}
+ */
 function normalizeDisposition(value) {
   const normalized = String(value || '').trim().toUpperCase();
   return ['CHANGES_MADE', 'PUSHBACK_ALL', 'PARKED', 'BLOCKED'].includes(normalized) ? normalized : null;
@@ -112,6 +146,12 @@ function normalizeDisposition(value) {
 // Workflow Comment/Review Posting
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} message
+ * @param {{log?: Function, error?: Function, readTokenFn?: Function, postCommentFn?: Function, buildMetadataFooterFn?: Function, readReviewStateFn?: Function, rootDir?: string, reviewIdentity?: string, forgejoUser?: string}} [options]
+ * @returns {{ok: boolean, error?: string}}
+ */
 function postWorkflowComment(slug, message, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -147,12 +187,13 @@ function postWorkflowComment(slug, message, options = {}) {
 // the real HTTP status and response body (e.g. `422 approve your own pull is not
 // allowed`) instead of masking it behind a generic "API error". Falls back to
 // the result's own error/raw fields, then "API error" when nothing is present.
+/** @param {*} result */
 function describeProviderFailure(result) {
-  if (!result || typeof result !== 'object') return 'API error';
+  if (!result || typeof result !== 'object') {return 'API error';}
   // Prefer the HTTP status code (statusCode) over curl's process status.
-  const httpStatus = (result.statusCode != null && Number(result.statusCode) > 0)
+  const httpStatus = (result.statusCode !== null && Number(result.statusCode) > 0)
     ? result.statusCode
-    : (result.status != null && Number(result.status) >= 100 ? result.status : null);
+    : (result.status !== null && Number(result.status) >= 100 ? result.status : null);
   let body = null;
   if (result.data && typeof result.data === 'object') {
     body = result.data.message || JSON.stringify(result.data);
@@ -160,15 +201,21 @@ function describeProviderFailure(result) {
     body = result.data;
   }
   const parts = [];
-  if (httpStatus != null) parts.push(String(httpStatus));
-  if (body) parts.push(body);
-  if (parts.length) return parts.join(' ');
+  if (httpStatus !== null) {parts.push(String(httpStatus));}
+  if (body) {parts.push(body);}
+  if (parts.length) {return parts.join(' ');}
   return result.error || result.raw || 'API error';
 }
 
 // Record a review verdict in local review-state.json / review-events without
 // posting to the review provider. Used by the self-author skip path so the verdict is still
 // captured even though the formal provider approval is intentionally not posted.
+/**
+ * @param {string} slug
+ * @param {string} outcome
+ * @param {{worktree?: string, writeReviewStateFn?: Function, createEventFn?: Function, readReviewStateFn?: Function, log?: Function, error?: Function, reviewer?: string}} [options]
+ * @returns {void}
+ */
 function recordLocalReviewVerdict(slug, outcome, options = {}) {
   const worktree = options.worktree || resolveWorktree(slug) || process.cwd();
   const writeReviewStateFn = options.writeReviewStateFn || writeReviewState;
@@ -199,6 +246,13 @@ function recordLocalReviewVerdict(slug, outcome, options = {}) {
   createEventFn(slug, VALID_EVENT_TYPES.REVIEWER_OUTCOME, { verdict: outcome }, { worktree, log, error });
 }
 
+/**
+ * @param {string} slug
+ * @param {string} outcome
+ * @param {string} message
+ * @param {{log?: Function, error?: Function, readTokenFn?: Function, postReviewFn?: Function, buildMetadataFooterFn?: Function, readReviewStateFn?: Function, worktree?: string, reviewIdentity?: string, forgejoUser?: string, getPrAuthorFn?: Function, writeReviewStateFn?: Function, createEventFn?: Function}} [options]
+ * @returns {{ok: boolean, error?: string, skipped?: boolean, reason?: string, prAuthor?: string}}
+ */
 function postWorkflowReview(slug, outcome, message, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -262,18 +316,24 @@ function postWorkflowReview(slug, outcome, message, options = {}) {
 // Artifact Consumption
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} reviewer
+ * @param {{log?: Function, error?: Function, readArtifactFn?: Function, deleteArtifactFn?: Function, tmpDir?: string|null, fallbackToTmp?: boolean, worktree?: string, providerEnabled?: boolean|null, forgejoEnabled?: boolean|null, readTokenFn?: Function, getCommentsFn?: Function, postCommentFn?: Function, postReviewFn?: Function, buildMetadataFooterFn?: Function, createEventFn?: Function}} [options]
+ * @returns {Promise<{consumed: boolean, ok?: boolean, reviewState?: string|null}>}
+ */
 async function consumeReviewerArtifacts(slug, reviewer, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
   const readArtifactFn = options.readArtifactFn || readArtifactFile;
   const deleteArtifactFn = options.deleteArtifactFn || deleteArtifactFile;
-  const explicitTmpDir = options.tmpDir != null;
+  const explicitTmpDir = options.tmpDir !== null && options.tmpDir !== undefined;
   const fallbackToTmp = options.fallbackToTmp === true;
   const worktree = options.worktree || resolveWorktree(slug) || process.cwd();
   const tmpDir = options.tmpDir || resolveArtifactDir(worktree);
-  const providerEnabled = options.providerEnabled != null
+  const providerEnabled = options.providerEnabled !== null && options.providerEnabled !== undefined
     ? options.providerEnabled
-    : (options.forgejoEnabled != null ? options.forgejoEnabled : isEnabled(worktree));
+    : (options.forgejoEnabled !== null && options.forgejoEnabled !== undefined ? options.forgejoEnabled : isEnabled(worktree));
   const reviewStatePath = reviewStateFile(slug, worktree);
 
   const findingsResolved = resolveArtifactRead(slug, 'review-findings.md', { tmpDir, explicitTmpDir, fallbackToTmp, readArtifactFn });
@@ -289,7 +349,7 @@ async function consumeReviewerArtifacts(slug, reviewer, options = {}) {
   
   // Extract verdict from outcome message if review-verdict.txt is not provided
   // This allows a single review-outcome.md file to contain both the outcome and verdict
-  let verdict = normalizeReviewVerdict(verdictRaw);
+  let verdict = normalizeReviewVerdict(/** @type {string} */ (verdictRaw || ''));
   if (!verdict && outcomeMessage) {
     // Try to extract verdict from outcome content (e.g., "Verdict: approve" or frontmatter)
     const outcomeVerdictMatch = outcomeMessage.match(/^verdict:\s*(approve|request-changes|comment)/im) ||
@@ -418,8 +478,8 @@ async function consumeReviewerArtifacts(slug, reviewer, options = {}) {
   deleteArtifactFn(outcomePath);
   deleteArtifactFn(verdictPath);
 
-  if (verdict === 'approve') return { consumed: true, ok: true, reviewState: 'APPROVED' };
-  if (verdict === 'request-changes') return { consumed: true, ok: true, reviewState: 'REQUEST_CHANGES' };
+  if (verdict === 'approve') {return { consumed: true, ok: true, reviewState: 'APPROVED' };}
+  if (verdict === 'request-changes') {return { consumed: true, ok: true, reviewState: 'REQUEST_CHANGES' };}
   // Defensive fallback: a stray `comment` verdict (prompts no longer offer it) cannot be
   // resolved via provider polling when the provider is disabled, so normalize it to the
   // disposition format and pass it through. inferPhaseFromDisposition() maps COMMENT -> fixing.
@@ -432,18 +492,24 @@ async function consumeReviewerArtifacts(slug, reviewer, options = {}) {
   return { consumed: true, ok: true, reviewState: null };
 }
 
+/**
+ * @param {string} slug
+ * @param {string} implementer
+ * @param {{log?: Function, error?: Function, readArtifactFn?: Function, deleteArtifactFn?: Function, tmpDir?: string|null, fallbackToTmp?: boolean, worktree?: string, providerEnabled?: boolean|null, forgejoEnabled?: boolean|null, readTokenFn?: Function, getCommentsFn?: Function, postCommentFn?: Function, buildMetadataFooterFn?: Function, createEventFn?: Function}} [options]
+ * @returns {Promise<{consumed: boolean, ok?: boolean, disposition?: string|null}>}
+ */
 async function consumeImplementerArtifacts(slug, implementer, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
   const readArtifactFn = options.readArtifactFn || readArtifactFile;
   const deleteArtifactFn = options.deleteArtifactFn || deleteArtifactFile;
-  const explicitTmpDir = options.tmpDir != null;
+  const explicitTmpDir = options.tmpDir !== null && options.tmpDir !== undefined;
   const fallbackToTmp = options.fallbackToTmp === true;
   const worktree = options.worktree || resolveWorktree(slug) || process.cwd();
   const tmpDir = options.tmpDir || resolveArtifactDir(worktree);
-  const providerEnabled = options.providerEnabled != null
+  const providerEnabled = options.providerEnabled !== null && options.providerEnabled !== undefined
     ? options.providerEnabled
-    : (options.forgejoEnabled != null ? options.forgejoEnabled : isEnabled(worktree));
+    : (options.forgejoEnabled !== null && options.forgejoEnabled !== undefined ? options.forgejoEnabled : isEnabled(worktree));
   const reviewStatePath = reviewStateFile(slug, worktree);
 
   const resolutionResolved = resolveArtifactRead(slug, 'round-resolution.md', { tmpDir, explicitTmpDir, fallbackToTmp, readArtifactFn });
@@ -453,7 +519,7 @@ async function consumeImplementerArtifacts(slug, implementer, options = {}) {
 
   const resolution = resolutionResolved.value;
   const dispositionRaw = dispositionResolved.value;
-  const disposition = normalizeDisposition(dispositionRaw);
+  const disposition = normalizeDisposition(/** @type {string} */ (dispositionRaw || ''));
   const hasAny = resolution !== null || dispositionRaw !== null;
 
   if (!hasAny) {
@@ -492,10 +558,10 @@ async function consumeImplementerArtifacts(slug, implementer, options = {}) {
     const parkedMatch = resolution.match(/parked_items:\s*(\[[^\]]*\])/i);
     const blockedMatch = resolution.match(/blocked_reason:\s*"([^"]*)"/i);
     
-    if (fixedMatch) fixedItems = JSON.parse(fixedMatch[1]);
-    if (pushedMatch) pushedBackItems = JSON.parse(pushedMatch[1]);
-    if (parkedMatch) parkedItems = JSON.parse(parkedMatch[1]);
-    if (blockedMatch) blockedReason = blockedMatch[1];
+    if (fixedMatch) {fixedItems = JSON.parse(fixedMatch[1]);}
+    if (pushedMatch) {pushedBackItems = JSON.parse(pushedMatch[1]);}
+    if (parkedMatch) {parkedItems = JSON.parse(parkedMatch[1]);}
+    if (blockedMatch) {blockedReason = blockedMatch[1];}
   } catch (_) {
     // If parsing fails, use empty arrays
     fixedItems = [];
@@ -507,7 +573,7 @@ async function consumeImplementerArtifacts(slug, implementer, options = {}) {
   if (disposition === 'BLOCKED' && !blockedReason) {
     // Check if it's in the resolution content
     const match = resolution.match(/blocked.*?:\s*(.+)/i);
-    if (match) blockedReason = match[1].trim();
+    if (match) {blockedReason = match[1].trim();}
   }
 
   const summaryEventResult = createEventFn(slug, VALID_EVENT_TYPES.IMPLEMENTER_ROUND_SUMMARY, {