@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/review/review-prompts.js

@@ -21,6 +21,12 @@ const ACT_ON_REVIEW_VERBOSE_PROMPT_PATH = path.join(__dirname, '..', '..', 'prom
  * Slash-command / entrypoint used to invoke the review skill for each agent family.
  * Moved from scripts/autonomous-review.sh prompt_entrypoint_for() into Node.
  */
+/**
+ * @typedef {{review: string, actOnReview: string}} PromptEntry
+ * @typedef {{codex: PromptEntry, claude: PromptEntry, mistral: PromptEntry, custom: PromptEntry, autonomous: PromptEntry}} PromptEntrypoints
+ */
+
+/** @type {PromptEntrypoints} */
 const PROMPT_ENTRYPOINTS = {
   codex:  { review: '$review all',                           actOnReview: '$act-on-review' },
   claude: { review: '/review all',                           actOnReview: '/act-on-review' },
@@ -29,15 +35,17 @@ const PROMPT_ENTRYPOINTS = {
   autonomous: { review: '$review all',                       actOnReview: '$act-on-review' }
 };
 
+/** @param {string} agent */
 function reviewEntrypoint(agent) {
-  const entry = PROMPT_ENTRYPOINTS[agent];
-  if (!entry) throw new Error(`Unknown agent family for review entrypoint: ${agent}`);
+  const entry = /** @type {PromptEntry} */ (/** @type {{[key: string]: PromptEntry}} */ (PROMPT_ENTRYPOINTS)[agent]);
+  if (!entry) {throw new Error(`Unknown agent family for review entrypoint: ${agent}`);}
   return entry.review;
 }
 
+/** @param {string} agent */
 function actOnReviewEntrypoint(agent) {
-  const entry = PROMPT_ENTRYPOINTS[agent];
-  if (!entry) throw new Error(`Unknown agent family for act-on-review entrypoint: ${agent}`);
+  const entry = /** @type {PromptEntry} */ (/** @type {{[key: string]: PromptEntry}} */ (PROMPT_ENTRYPOINTS)[agent]);
+  if (!entry) {throw new Error(`Unknown agent family for act-on-review entrypoint: ${agent}`);}
   return entry.actOnReview;
 }
 
@@ -53,11 +61,17 @@ function actOnReviewEntrypoint(agent) {
  * @param {string} [opts.repoRoot]    - Absolute repo root path
  * @returns {string}
  */
+/**
+ * @param {string} slug
+ * @param {string} [repoRoot]
+ * @param {string} [missionPathOverride]
+ * @returns {string}
+ */
 function resolveMissionPath(slug, repoRoot, missionPathOverride) {
   // `--mission <path>` override: when the caller points the review loop at a
   // mission contract in a non-standard location, agents must read that file
   // instead of the slug-derived standard path (task-1272 SC7).
-  if (missionPathOverride) return missionPathOverride;
+  if (missionPathOverride) {return missionPathOverride;}
   const root = repoRoot || process.cwd();
   try {
     return missionPathForSlug(root, slug);
@@ -67,6 +81,7 @@ function resolveMissionPath(slug, repoRoot, missionPathOverride) {
   }
 }
 
+/** @param {string} [repoRoot] */
 function resolvePrimaryBranch(repoRoot) {
   try {
     return getPrimaryBranch(repoRoot || process.cwd());
@@ -75,6 +90,10 @@ function resolvePrimaryBranch(repoRoot) {
   }
 }
 
+/**
+ * @param {{reviewer: string, branch: string, implementer: string, focus?: string, attempt: number, repoRoot?: string, missionPath?: string}} opts
+ * @returns {string}
+ */
 function buildReviewPrompt({ reviewer, branch, implementer, focus = 'all', attempt, repoRoot = '', missionPath: missionPathOverride }) {
   const entrypoint = reviewEntrypoint(reviewer);
   const repoLine = repoRoot ? `\noperate from repo root: ${repoRoot}` : '';
@@ -109,6 +128,10 @@ function buildReviewPrompt({ reviewer, branch, implementer, focus = 'all', attem
  * @param {string} [opts.repoRoot]    - Absolute repo root path
  * @returns {string}
  */
+/**
+ * @param {{implementer: string, branch: string, attempt: number, repoRoot?: string, missionPath?: string}} opts
+ * @returns {string}
+ */
 function buildActOnReviewPrompt({ implementer, branch, attempt, repoRoot = '', missionPath: missionPathOverride }) {
   const entrypoint = actOnReviewEntrypoint(implementer);
   const repoLine = repoRoot ? `\noperate from repo root: ${repoRoot}` : '';
@@ -146,6 +169,10 @@ function buildActOnReviewPrompt({ implementer, branch, attempt, repoRoot = '', m
  * @param {string} [opts.actualReviewer] - The actual agent family launched (overrides reviewer for identity text, TASK-1051)
  * @returns {string}
  */
+/**
+ * @param {{reviewer: string, branch: string, implementer: string, focus?: string, attempt: number, actualReviewer?: string, repoRoot?: string, missionPath?: string}} opts
+ * @returns {string}
+ */
 function buildCompactReviewPrompt({ reviewer, branch, implementer, focus = 'all', attempt, actualReviewer, repoRoot = '', missionPath: missionPathOverride }) {
   const slug = branch.replace(/^mission\//, '');
   const finalReviewer = actualReviewer || reviewer;
@@ -180,6 +207,10 @@ function buildCompactReviewPrompt({ reviewer, branch, implementer, focus = 'all'
  * @param {string} [opts.actualImplementer] - The actual agent family launched (overrides implementer for identity text, TASK-1051)
  * @returns {string}
  */
+/**
+ * @param {{implementer: string, branch: string, attempt: number, reviewOutcome?: string, actualImplementer?: string, repoRoot?: string, missionPath?: string}} opts
+ * @returns {string}
+ */
 function buildCompactActOnReviewPrompt({ implementer, branch, attempt, reviewOutcome = '?', actualImplementer, repoRoot = '', missionPath: missionPathOverride }) {
   const slug = branch.replace(/^mission\//, '');
   const finalImplementer = actualImplementer || implementer;

package/lib/review/review-state.js

@@ -23,7 +23,7 @@ const fmt = require('../core/fmt');
  */
 function reviewStateFile(slug, rootDir = process.cwd()) {
   const missionDir = findMissionDir(slug, rootDir);
-  if (!missionDir) return null;
+  if (!missionDir) {return null;}
   return path.join(missionDir, 'review-state.json');
 }
 
@@ -36,7 +36,7 @@ function reviewStateFile(slug, rootDir = process.cwd()) {
  */
 function readReviewState(slug, rootDir = process.cwd()) {
   const statePath = reviewStateFile(slug, rootDir);
-  if (!statePath || !fs.existsSync(statePath)) return null;
+  if (!statePath || !fs.existsSync(statePath)) {return null;}
 
   try {
     const raw = fs.readFileSync(statePath, 'utf8');
@@ -58,10 +58,10 @@ function readReviewState(slug, rootDir = process.cwd()) {
  *
  * @param {string} slug
  * @param {string} [rootDir]
- * @param {object} [options]
+ * @param {{readReviewStateFn?: Function}} [options]
  * @returns {{ identityUser: string|null, commentIdentityUser: string|null, forgejoUser: string|null, commentForgejoUser: string|null, reviewState: ReviewState|null, source: 'review-state'|null }}
  */
-function resolveReviewIdentity(slug, rootDir = process.cwd(), options = {}) {
+function resolveReviewIdentity(slug, rootDir = process.cwd(), /** @type {{readReviewStateFn?: Function}} */ options = {}) {
   const readReviewStateFn = options.readReviewStateFn || readReviewState;
   const reviewState = readReviewStateFn(slug, rootDir);
   const reviewerUser = reviewState ? (reviewState.reviewer || reviewState.implementer || null) : null;
@@ -99,6 +99,7 @@ const PHASE_TRANSITIONS = {
   'approved': []
 };
 
+/** @param {string} disposition */
 function inferPhaseFromDisposition(disposition) {
   switch (String(disposition || '').trim().toUpperCase()) {
   case 'APPROVED':
@@ -116,6 +117,7 @@ function inferPhaseFromDisposition(disposition) {
   }
 }
 
+/** @param {string} phase @param {string} disposition */
 function normalizeReviewPhase(phase, disposition) {
   if (!phase) {
     return { phase: 'reviewing', original: null, normalized: false };
@@ -139,9 +141,17 @@ function normalizeReviewPhase(phase, disposition) {
   };
 }
 
+/**
+ * @typedef {{reviewer?: string, implementer?: string, round?: number, startedAt?: string, phase?: string, disposition?: string | null, reviewerRetryCount?: number, implementerRetryCount?: number, metadata?: {[key: string]: any}}} ReviewStateData
+ */
+
 class ReviewState {
-  constructor(slug, data = {}) {
-    const phaseInfo = normalizeReviewPhase(data.phase, data.disposition);
+  /**
+   * @param {string} slug
+   * @param {ReviewStateData} [data]
+   */
+  constructor(slug, /** @type {ReviewStateData} */ data = {}) {
+    const phaseInfo = normalizeReviewPhase(/** @type {string} */ (data.phase || ''), /** @type {string} */ (data.disposition || ''));
     this.slug = slug;
     this.reviewer = data.reviewer;
     this.implementer = data.implementer;
@@ -155,6 +165,11 @@ class ReviewState {
     this.phaseOriginal = phaseInfo.normalized ? phaseInfo.original : null;
   }
 
+  /**
+   * @param {string} slug
+   * @param {ReviewState|ReviewStateData} dataOrInstance
+   * @returns {ReviewState}
+   */
   static from(slug, dataOrInstance) {
     if (dataOrInstance instanceof ReviewState) {
       if (dataOrInstance.slug !== slug) {
@@ -165,13 +180,18 @@ class ReviewState {
     return new ReviewState(slug, dataOrInstance || {});
   }
 
+  /**
+   * @param {string} nextPhase
+   * @returns {ReviewState}
+   */
   transitionTo(nextPhase) {
     if (!VALID_PHASES.includes(nextPhase)) {
       throw new Error(`Invalid phase: "${nextPhase}". Valid: ${VALID_PHASES.join(', ')}`);
     }
-    const allowed = PHASE_TRANSITIONS[this.phase];
-    if (!allowed || !allowed.includes(nextPhase)) {
-      throw new Error(`Cannot transition from "${this.phase}" to "${nextPhase}". Allowed: ${(allowed || []).join(', ') || 'none'}`);
+    const transitions = /** @type {{[key: string]: string[]}} */ (PHASE_TRANSITIONS);
+    const allowedArr = transitions[this.phase];
+    if (!allowedArr || !allowedArr.includes(nextPhase)) {
+      throw new Error(`Cannot transition from "${this.phase}" to "${nextPhase}". Allowed: ${(allowedArr || []).join(', ') || 'none'}`);
     }
     this.phase = nextPhase;
     return this;
@@ -187,26 +207,30 @@ class ReviewState {
     return this;
   }
 
+  /**
+   * @returns {{reviewer?: string, implementer?: string, round?: number, startedAt?: string, phase?: string, disposition?: string, reviewerRetryCount?: number, implementerRetryCount?: number, metadata?: {[key: string]: any}}}
+   */
   toJSON() {
+    /** @type {{reviewer?: string, implementer?: string, round?: number, startedAt?: string, phase?: string, disposition?: string, reviewerRetryCount?: number, implementerRetryCount?: number, metadata?: {[key: string]: any}}} */
     const payload = {
       reviewer: this.reviewer,
       implementer: this.implementer,
       round: this.round,
       startedAt: this.startedAt,
       phase: this.phase,
-      disposition: this.disposition
+      disposition: this.disposition || undefined
     };
 
-    if (this.reviewerRetryCount > 0) payload.reviewerRetryCount = this.reviewerRetryCount;
-    if (this.implementerRetryCount > 0) payload.implementerRetryCount = this.implementerRetryCount;
-    if (Object.keys(this.metadata).length > 0) payload.metadata = this.metadata;
+    if (this.reviewerRetryCount > 0) {payload.reviewerRetryCount = this.reviewerRetryCount;}
+    if (this.implementerRetryCount > 0) {payload.implementerRetryCount = this.implementerRetryCount;}
+    if (Object.keys(this.metadata || {}).length > 0) {payload.metadata = this.metadata;}
 
     return payload;
   }
 
   save(worktree = resolveWorktree(this.slug) || process.cwd(), gitFn = git) {
     const statePath = reviewStateFile(this.slug, worktree);
-    if (!statePath) return false;
+    if (!statePath) {return false;}
 
     const payload = this.toJSON();
     fs.writeFileSync(statePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
@@ -250,7 +274,7 @@ function writeReviewState(slug, state, worktree = resolveWorktree(slug) || proce
  */
 function resetReviewState(slug, worktree = resolveWorktree(slug) || process.cwd(), gitFn = git) {
   const statePath = reviewStateFile(slug, worktree);
-  if (!statePath || !fs.existsSync(statePath)) return false;
+  if (!statePath || !fs.existsSync(statePath)) {return false;}
 
   fs.unlinkSync(statePath);