specweave 1.0.235 → 1.0.239

package/plugins/specweave-github/lib/github-issue-body-parser.ts

@@ -0,0 +1,92 @@
+/**
+ * GitHub Issue Body Parser
+ *
+ * Parses AC checkbox state and sync metadata from a GitHub issue body.
+ * Used by the pull sync to detect changes made on GitHub.
+ *
+ * @module github-issue-body-parser
+ */
+
+export interface ParsedIssueBody {
+  /** AC ID → checked state and description */
+  acceptanceCriteria: Record<string, { checked: boolean; description: string }>;
+  /** Sync marker metadata (if present) */
+  syncMarker?: { specId: string; userStoryId: string };
+}
+
+// Regex to match AC checkboxes: - [x] **AC-US1-01**: Description
+const AC_CHECKBOX_RE = /^-\s+\[([ xX])\]\s+\*\*(?<acId>AC-[A-Z0-9]+-\d+)\*\*:\s*(?<desc>.+)$/;
+
+// Regex to match sync footer marker
+const SYNC_MARKER_RE = /<!--\s*specweave:sync\s+(?:spec=(?<specId>[^\s]+)\s+)?us=(?<usId>[^\s]+)\s*-->/;
+
+/**
+ * Parse a GitHub issue body to extract AC checkbox states and sync metadata.
+ *
+ * Strategy:
+ * 1. Try to find ACs within "## Acceptance Criteria" section
+ * 2. Fallback: scan entire body for AC-pattern checkboxes
+ * 3. Parse sync footer marker if present
+ */
+export function parseIssueBody(body: string): ParsedIssueBody {
+  const result: ParsedIssueBody = {
+    acceptanceCriteria: {},
+  };
+
+  if (!body || !body.trim()) {
+    return result;
+  }
+
+  const lines = body.split('\n');
+
+  // Try to find the "## Acceptance Criteria" section
+  let inAcSection = false;
+  let foundAcSection = false;
+
+  for (const line of lines) {
+    // Detect section boundaries
+    if (/^##\s+Acceptance Criteria/i.test(line)) {
+      inAcSection = true;
+      foundAcSection = true;
+      continue;
+    }
+    if (inAcSection && /^##\s+/.test(line)) {
+      inAcSection = false;
+      continue;
+    }
+
+    if (inAcSection) {
+      const match = line.match(AC_CHECKBOX_RE);
+      if (match?.groups) {
+        result.acceptanceCriteria[match.groups.acId] = {
+          checked: match[1] !== ' ',
+          description: match.groups.desc.trim(),
+        };
+      }
+    }
+  }
+
+  // Fallback: if no AC section found, scan the entire body
+  if (!foundAcSection) {
+    for (const line of lines) {
+      const match = line.match(AC_CHECKBOX_RE);
+      if (match?.groups) {
+        result.acceptanceCriteria[match.groups.acId] = {
+          checked: match[1] !== ' ',
+          description: match.groups.desc.trim(),
+        };
+      }
+    }
+  }
+
+  // Parse sync footer marker
+  const syncMatch = body.match(SYNC_MARKER_RE);
+  if (syncMatch?.groups?.usId) {
+    result.syncMarker = {
+      specId: syncMatch.groups.specId || '',
+      userStoryId: syncMatch.groups.usId,
+    };
+  }
+
+  return result;
+}

package/plugins/specweave-github/lib/github-pull-sync.js

@@ -0,0 +1,185 @@
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { parseIssueBody } from "./github-issue-body-parser.js";
+async function pullSyncFromGitHub(userStoryLinks, specAcceptanceCriteria, options) {
+  const result = { changes: [], conflicts: [], errors: [] };
+  const entries = Object.entries(userStoryLinks);
+  if (entries.length === 0) {
+    return result;
+  }
+  const env = getEnv(options.token);
+  const repoSlug = `${options.owner}/${options.repo}`;
+  for (const [usId, link] of entries) {
+    try {
+      const issueData = await fetchIssue(link.issueNumber, repoSlug, env);
+      const parsed = parseIssueBody(issueData.body || "");
+      const specACs = specAcceptanceCriteria[usId] || [];
+      compareACStates(usId, specACs, parsed.acceptanceCriteria, options.dryRun ?? false, result);
+      compareIssueState(usId, issueData.state, specACs, result, options.dryRun ?? false);
+    } catch (err) {
+      result.errors.push({
+        userStoryId: usId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return result;
+}
+function compareACStates(usId, specACs, githubACs, dryRun, result) {
+  for (const specAC of specACs) {
+    const ghAC = githubACs[specAC.id];
+    if (!ghAC) continue;
+    const specValue = String(specAC.completed);
+    const githubValue = String(ghAC.checked);
+    if (specValue !== githubValue) {
+      if (specAC.completed && !ghAC.checked) {
+        result.conflicts.push({
+          userStoryId: usId,
+          field: specAC.id,
+          specValue,
+          githubValue
+        });
+      } else {
+        result.changes.push({
+          userStoryId: usId,
+          field: specAC.id,
+          specValue,
+          githubValue,
+          applied: !dryRun
+        });
+      }
+    }
+  }
+}
+function compareIssueState(usId, githubState, specACs, result, dryRun) {
+  const normalizedState = githubState.toLowerCase() === "closed" ? "closed" : "open";
+  const allDone = specACs.length > 0 && specACs.every((ac) => ac.completed);
+  const specState = allDone ? "closed" : "open";
+  if (specState !== normalizedState) {
+    result.changes.push({
+      userStoryId: usId,
+      field: "status",
+      specValue: specState,
+      githubValue: normalizedState,
+      applied: !dryRun
+    });
+  }
+}
+async function fetchIssue(issueNumber, repoSlug, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "view",
+    String(issueNumber),
+    "--repo",
+    repoSlug,
+    "--json",
+    "title,body,state,labels"
+  ], { env });
+  if (!res.success) {
+    throw new Error(res.stderr || "Failed to fetch issue");
+  }
+  return JSON.parse(res.stdout);
+}
+function getEnv(token) {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}
+async function pullSyncMultiRepo(repos, userStoryLinks, specAcceptanceCriteria, options) {
+  const result = {
+    changes: [],
+    conflicts: [],
+    disagreements: [],
+    errors: []
+  };
+  if (repos.length === 0) {
+    return result;
+  }
+  const env = getEnv(options.token);
+  const perRepoACStates = {};
+  const failedRepos = /* @__PURE__ */ new Set();
+  for (const repo of repos) {
+    const repoSlug = `${repo.owner}/${repo.repo}`;
+    for (const usId of repo.relevantStories) {
+      const links = userStoryLinks[usId];
+      if (!links || !links[repoSlug]) continue;
+      const issueNumber = links[repoSlug].issueNumber;
+      try {
+        const issueData = await fetchIssue(issueNumber, repoSlug, env);
+        const parsed = parseIssueBody(issueData.body || "");
+        if (!perRepoACStates[usId]) {
+          perRepoACStates[usId] = {};
+        }
+        const specACs = specAcceptanceCriteria[usId] || [];
+        for (const specAC of specACs) {
+          const ghAC = parsed.acceptanceCriteria[specAC.id];
+          if (!ghAC) continue;
+          if (!perRepoACStates[usId][specAC.id]) {
+            perRepoACStates[usId][specAC.id] = {};
+          }
+          perRepoACStates[usId][specAC.id][repoSlug] = ghAC.checked;
+        }
+      } catch (err) {
+        failedRepos.add(repoSlug);
+        result.errors.push({
+          userStoryId: usId,
+          repo: repoSlug,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  }
+  for (const [usId, acMap] of Object.entries(perRepoACStates)) {
+    const specACs = specAcceptanceCriteria[usId] || [];
+    const usLinks = userStoryLinks[usId] || {};
+    const expectedRepos = Object.keys(usLinks).filter((r) => !failedRepos.has(r));
+    for (const specAC of specACs) {
+      const repoStates = acMap[specAC.id];
+      if (!repoStates) continue;
+      const validStates = Object.entries(repoStates).filter(
+        ([repo]) => !failedRepos.has(repo)
+      );
+      if (validStates.length === 0) continue;
+      const allChecked = validStates.every(([, checked]) => checked);
+      const allUnchecked = validStates.every(([, checked]) => !checked);
+      const isShared = expectedRepos.length > 1;
+      if (isShared) {
+        if (allChecked && !specAC.completed) {
+          result.changes.push({
+            userStoryId: usId,
+            field: specAC.id,
+            specValue: String(specAC.completed),
+            githubValue: "true",
+            applied: true
+          });
+        } else if (!allChecked && !allUnchecked && !specAC.completed) {
+          const stateMap = {};
+          for (const [repo, checked] of validStates) {
+            stateMap[repo] = checked;
+          }
+          result.disagreements.push({
+            userStoryId: usId,
+            field: specAC.id,
+            repoStates: stateMap
+          });
+        }
+      } else {
+        const [, checked] = validStates[0];
+        if (checked && !specAC.completed) {
+          result.changes.push({
+            userStoryId: usId,
+            field: specAC.id,
+            specValue: String(specAC.completed),
+            githubValue: "true",
+            applied: true
+          });
+        }
+      }
+    }
+  }
+  return result;
+}
+export {
+  pullSyncFromGitHub,
+  pullSyncMultiRepo
+};

package/plugins/specweave-github/lib/github-pull-sync.ts

@@ -0,0 +1,343 @@
+/**
+ * GitHub Pull Sync — GitHub Issues → Spec
+ *
+ * Fetches GitHub issue state and compares with spec acceptance criteria
+ * to detect changes, conflicts, and apply updates.
+ *
+ * @module github-pull-sync
+ */
+
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import { parseIssueBody } from './github-issue-body-parser.js';
+import type { GitHubUserStoryLink } from '../../../src/core/types/sync-profile.js';
+
+export interface PullSyncOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+  dryRun?: boolean;
+}
+
+export interface PullSyncChange {
+  userStoryId: string;
+  field: string;
+  specValue: string;
+  githubValue: string;
+  applied: boolean;
+}
+
+export interface PullSyncConflict {
+  userStoryId: string;
+  field: string;
+  specValue: string;
+  githubValue: string;
+}
+
+export interface PullSyncResult {
+  changes: PullSyncChange[];
+  conflicts: PullSyncConflict[];
+  errors: Array<{ userStoryId: string; error: string }>;
+}
+
+/**
+ * Pull sync from GitHub — fetch issue state and compare with spec ACs.
+ *
+ * For each linked user story:
+ * 1. Fetch issue via `gh issue view`
+ * 2. Parse body to extract AC checkbox states
+ * 3. Compare with spec AC states
+ * 4. Report changes and conflicts
+ */
+export async function pullSyncFromGitHub(
+  userStoryLinks: Record<string, GitHubUserStoryLink>,
+  specAcceptanceCriteria: Record<string, Array<{ id: string; completed: boolean }>>,
+  options: PullSyncOptions,
+): Promise<PullSyncResult> {
+  const result: PullSyncResult = { changes: [], conflicts: [], errors: [] };
+
+  const entries = Object.entries(userStoryLinks);
+  if (entries.length === 0) {
+    return result;
+  }
+
+  const env = getEnv(options.token);
+  const repoSlug = `${options.owner}/${options.repo}`;
+
+  for (const [usId, link] of entries) {
+    try {
+      const issueData = await fetchIssue(link.issueNumber, repoSlug, env);
+      const parsed = parseIssueBody(issueData.body || '');
+      const specACs = specAcceptanceCriteria[usId] || [];
+
+      // Compare AC checkbox states
+      compareACStates(usId, specACs, parsed.acceptanceCriteria, options.dryRun ?? false, result);
+
+      // Compare issue state (open/closed)
+      compareIssueState(usId, issueData.state, specACs, result, options.dryRun ?? false);
+    } catch (err) {
+      result.errors.push({
+        userStoryId: usId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return result;
+}
+
+function compareACStates(
+  usId: string,
+  specACs: Array<{ id: string; completed: boolean }>,
+  githubACs: Record<string, { checked: boolean; description: string }>,
+  dryRun: boolean,
+  result: PullSyncResult,
+): void {
+  for (const specAC of specACs) {
+    const ghAC = githubACs[specAC.id];
+    if (!ghAC) continue;
+
+    const specValue = String(specAC.completed);
+    const githubValue = String(ghAC.checked);
+
+    if (specValue !== githubValue) {
+      // Both changed from a baseline? That's a conflict.
+      // Simple heuristic: if spec says true and GitHub says false, it's a conflict
+      // (someone completed on spec side, but GitHub unchecked it)
+      if (specAC.completed && !ghAC.checked) {
+        result.conflicts.push({
+          userStoryId: usId,
+          field: specAC.id,
+          specValue,
+          githubValue,
+        });
+      } else {
+        // GitHub is ahead — record as a change
+        result.changes.push({
+          userStoryId: usId,
+          field: specAC.id,
+          specValue,
+          githubValue,
+          applied: !dryRun,
+        });
+      }
+    }
+  }
+}
+
+function compareIssueState(
+  usId: string,
+  githubState: string,
+  specACs: Array<{ id: string; completed: boolean }>,
+  result: PullSyncResult,
+  dryRun: boolean,
+): void {
+  // Normalize GitHub state
+  const normalizedState = githubState.toLowerCase() === 'closed' ? 'closed' : 'open';
+
+  // Check if spec is effectively "complete" (all ACs done) or "open"
+  const allDone = specACs.length > 0 && specACs.every(ac => ac.completed);
+  const specState = allDone ? 'closed' : 'open';
+
+  if (specState !== normalizedState) {
+    result.changes.push({
+      userStoryId: usId,
+      field: 'status',
+      specValue: specState,
+      githubValue: normalizedState,
+      applied: !dryRun,
+    });
+  }
+}
+
+async function fetchIssue(
+  issueNumber: number,
+  repoSlug: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ title: string; body: string; state: string; labels: Array<{ name: string }> }> {
+  const res = await execFileNoThrow('gh', [
+    'issue', 'view', String(issueNumber),
+    '--repo', repoSlug,
+    '--json', 'title,body,state,labels',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(res.stderr || 'Failed to fetch issue');
+  }
+
+  return JSON.parse(res.stdout);
+}
+
+function getEnv(token?: string): NodeJS.ProcessEnv {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}
+
+// ============================================================================
+// Multi-Repo Pull Sync (v1.0.236+)
+// ============================================================================
+
+export interface MultiRepoPullSyncOptions extends PullSyncOptions {}
+
+export interface MultiRepoDisagreement {
+  userStoryId: string;
+  field: string;
+  repoStates: Record<string, boolean>;
+}
+
+export interface MultiRepoPullSyncResult {
+  changes: PullSyncChange[];
+  conflicts: PullSyncConflict[];
+  disagreements: MultiRepoDisagreement[];
+  errors: Array<{ userStoryId?: string; repo?: string; error: string }>;
+}
+
+interface RepoConfig {
+  owner: string;
+  repo: string;
+  relevantStories: string[];
+}
+
+interface MultiRepoUserStoryLinks {
+  [usId: string]: Record<string, { issueNumber: number }>;
+}
+
+/**
+ * Pull sync from multiple repos with all-repos-must-agree consensus.
+ *
+ * For shared user stories (appearing in 2+ repos):
+ * - AC is marked done ONLY if ALL repos agree it is done
+ * - Disagreements are recorded separately
+ *
+ * For repo-specific user stories (1 repo):
+ * - Standard single-repo logic applies
+ *
+ * Repo errors are non-blocking: erroring repos are excluded from consensus.
+ */
+export async function pullSyncMultiRepo(
+  repos: RepoConfig[],
+  userStoryLinks: MultiRepoUserStoryLinks,
+  specAcceptanceCriteria: Record<string, Array<{ id: string; completed: boolean }>>,
+  options: MultiRepoPullSyncOptions,
+): Promise<MultiRepoPullSyncResult> {
+  const result: MultiRepoPullSyncResult = {
+    changes: [],
+    conflicts: [],
+    disagreements: [],
+    errors: [],
+  };
+
+  if (repos.length === 0) {
+    return result;
+  }
+
+  const env = getEnv(options.token);
+
+  // Step 1: Fetch per-repo AC states
+  // Map: usId → acId → repoSlug → checked
+  const perRepoACStates: Record<string, Record<string, Record<string, boolean>>> = {};
+  const failedRepos = new Set<string>();
+
+  for (const repo of repos) {
+    const repoSlug = `${repo.owner}/${repo.repo}`;
+
+    for (const usId of repo.relevantStories) {
+      const links = userStoryLinks[usId];
+      if (!links || !links[repoSlug]) continue;
+
+      const issueNumber = links[repoSlug].issueNumber;
+
+      try {
+        const issueData = await fetchIssue(issueNumber, repoSlug, env);
+        const parsed = parseIssueBody(issueData.body || '');
+
+        // Record AC states for this repo
+        if (!perRepoACStates[usId]) {
+          perRepoACStates[usId] = {};
+        }
+
+        const specACs = specAcceptanceCriteria[usId] || [];
+        for (const specAC of specACs) {
+          const ghAC = parsed.acceptanceCriteria[specAC.id];
+          if (!ghAC) continue;
+
+          if (!perRepoACStates[usId][specAC.id]) {
+            perRepoACStates[usId][specAC.id] = {};
+          }
+          perRepoACStates[usId][specAC.id][repoSlug] = ghAC.checked;
+        }
+      } catch (err) {
+        failedRepos.add(repoSlug);
+        result.errors.push({
+          userStoryId: usId,
+          repo: repoSlug,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  // Step 2: Build consensus per AC
+  for (const [usId, acMap] of Object.entries(perRepoACStates)) {
+    const specACs = specAcceptanceCriteria[usId] || [];
+
+    // Determine how many repos this US should appear in (excluding failed)
+    const usLinks = userStoryLinks[usId] || {};
+    const expectedRepos = Object.keys(usLinks).filter(r => !failedRepos.has(r));
+
+    for (const specAC of specACs) {
+      const repoStates = acMap[specAC.id];
+      if (!repoStates) continue;
+
+      // Filter out failed repos
+      const validStates = Object.entries(repoStates).filter(
+        ([repo]) => !failedRepos.has(repo),
+      );
+
+      if (validStates.length === 0) continue;
+
+      const allChecked = validStates.every(([, checked]) => checked);
+      const allUnchecked = validStates.every(([, checked]) => !checked);
+      const isShared = expectedRepos.length > 1;
+
+      if (isShared) {
+        // All-repos-must-agree consensus
+        if (allChecked && !specAC.completed) {
+          result.changes.push({
+            userStoryId: usId,
+            field: specAC.id,
+            specValue: String(specAC.completed),
+            githubValue: 'true',
+            applied: true,
+          });
+        } else if (!allChecked && !allUnchecked && !specAC.completed) {
+          // Disagreement
+          const stateMap: Record<string, boolean> = {};
+          for (const [repo, checked] of validStates) {
+            stateMap[repo] = checked;
+          }
+          result.disagreements.push({
+            userStoryId: usId,
+            field: specAC.id,
+            repoStates: stateMap,
+          });
+        }
+      } else {
+        // Single-repo: use directly
+        const [, checked] = validStates[0];
+        if (checked && !specAC.completed) {
+          result.changes.push({
+            userStoryId: usId,
+            field: specAC.id,
+            specValue: String(specAC.completed),
+            githubValue: 'true',
+            applied: true,
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}