@aprimediet/codewalker 1.2.0 → 1.4.0

package/src/analyze/review.ts

@@ -0,0 +1,127 @@
+/**
+ * Review helpers for codewalker v1.4.
+ *
+ * Pure/lightweight helpers for the agent-driven best-practice review workflow:
+ * - `validateReviewPath()` — ensures path is provided
+ * - `checkReviewCap()` — enforces the review cap guardrail
+ * - `selectFilesForReview()` — selects files under a path prefix with cap
+ * - `formatReviewWorklist()` — formats worklist items for agent display
+ *
+ * Mirrors the shape of enrich.ts.
+ */
+
+/** Default maximum files per review command. */
+export const DEFAULT_REVIEW_CAP = 25;
+
+/** Result of validateReviewPath. */
+export interface PathValidation {
+  valid: boolean;
+  error?: string;
+}
+
+/** Result of checkReviewCap. */
+export interface CapCheck {
+  ok: boolean;
+  count: number;
+  /** Number of files over the cap (only when !ok). */
+  skipped: number;
+  error?: string;
+}
+
+/**
+ * Validate that a review path was provided.
+ */
+export function validateReviewPath(path: string | undefined | null): PathValidation {
+  const trimmed = (path ?? "").trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: 'Specify a path, e.g. src/auth. Bare /codewalker review with no path is not allowed.',
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Check whether a count of files exceeds the cap.
+ * If ok is false, the caller should refuse and tell the user to narrow the path.
+ *
+ * @param count - Number of files found.
+ * @param cap - Maximum allowed (default: DEFAULT_REVIEW_CAP = 25).
+ */
+export function checkReviewCap(count: number, cap: number = DEFAULT_REVIEW_CAP): CapCheck {
+  if (count > cap) {
+    const skipped = count - cap;
+    return {
+      ok: false,
+      count,
+      skipped,
+      error: `Refusing to review ${count} files (cap ${cap}). ` +
+        `Narrow your path or raise the cap with --max=${count}.`,
+    };
+  }
+  return { ok: true, count, skipped: 0 };
+}
+
+/**
+ * Select files under a path prefix, respecting the cap.
+ * Files not matching the prefix are excluded.
+ *
+ * @param files - Full list of source file paths.
+ * @param pathPrefix - The path prefix to filter by (empty string = all files).
+ * @param cap - Maximum number to select.
+ * @returns Array of file paths matching the prefix, up to cap.
+ */
+export function selectFilesForReview(
+  files: string[],
+  pathPrefix: string,
+  cap: number,
+): string[] {
+  const matching = pathPrefix
+    ? files.filter(f => f.startsWith(pathPrefix))
+    : files;
+  return matching.slice(0, cap);
+}
+
+/**
+ * Format a review worklist for the agent to process.
+ * Each line shows one file to review. Includes instructions about grounding
+ * findings in the project's own conventions and decisions.
+ */
+export function formatReviewWorklist(
+  files: string[],
+  pathPrefix: string,
+): string {
+  if (files.length === 0) {
+    return `No files found under "${pathPrefix}" to review.`;
+  }
+
+  const lines: string[] = [
+    `Found ${files.length} file(s) under "${pathPrefix}" selected for review:`,
+    "",
+  ];
+
+  for (const file of files) {
+    lines.push(`  ${file}`);
+  }
+
+  lines.push(
+    "",
+    "Instructions:",
+    `  For each file above, read its content and judge it against the project's`,
+    `  conventions and decisions. Before starting, query for relevant context:`,
+    `    codewalker_query source:'all' query:'conventions'`,
+    `    codewalker_query source:'all' query:'decisions'`,
+    "",
+    `  For each issue found, call \`codewalker_finding\` with kind='practice',`,
+    `  an appropriate severity, and a body grounded in a specific convention or`,
+    `  decision. Avoid generic style nits — only flag what the project's own`,
+    `  conventions would flag.`,
+    "",
+    `  Example: \`codewalker_finding { kind: "practice", title: "...",`,
+    `    file: "src/auth/token.ts", severity: "warn",`,
+    `    body: "Convention X says Y, but this code does Z." }\``,
+  );
+
+  return lines.join("\n");
+}

package/src/cards.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { renderCard, parseCard, cardHead } from './cards.ts';
+import { renderCard, parseCard, cardHead, updateCardSummary } from './cards.ts';
 import type { Symbol } from './types.ts';
 
 function makeSymbol(overrides: Partial<Symbol> = {}): Symbol {
@@ -71,6 +71,128 @@ describe('parseCard', () => {
   });
 });
 
+describe('updateCardSummary', () => {
+  it('replaces frontmatter summary line and appends ## What it does section', () => {
+    const card = `---
+name: probeCompat
+kind: function
+signature: (cwd: string) => CompatResult
+location: compat.ts:201-243
+summary: Old summary
+---
+
+# probeCompat
+
+Some body text here.
+`;
+
+    const updated = updateCardSummary(card, 'Detect whether minion & memory are active.');
+
+    // Frontmatter summary updated
+    expect(updated).toContain('summary: Detect whether minion & memory are active.');
+    expect(updated).not.toContain('summary: Old summary');
+
+    // ## What it does section added
+    expect(updated).toContain('## What it does');
+    expect(updated).toContain('Detect whether minion & memory are active.');
+  });
+
+  it('is idempotent — second apply does not stack duplicates', () => {
+    const card = `---
+name: probeCompat
+kind: function
+location: compat.ts:201-243
+summary: Old
+---
+
+# probeCompat
+`;
+
+    const once = updateCardSummary(card, 'First summary.');
+    const twice = updateCardSummary(once, 'Second summary.');
+
+    // Has the new summary
+    expect(twice).toContain('summary: Second summary.');
+    expect(twice).not.toContain('summary: First summary.');
+
+    // Only one ## What it does section
+    const matches = twice.match(/## What it does/g);
+    expect(matches).toHaveLength(1);
+
+    // Only one summary in frontmatter
+    const summaryMatches = twice.match(/^summary:/gm);
+    expect(summaryMatches).toHaveLength(1);
+  });
+
+  it('handles empty summary in input', () => {
+    const card = `---
+name: foo
+kind: function
+location: foo.ts:1-10
+summary:
+---
+
+# foo
+`;
+
+    const updated = updateCardSummary(card, 'New summary.');
+    expect(updated).toContain('summary: New summary.');
+    expect(updated).toContain('## What it does');
+  });
+
+  it('handles card with no existing body', () => {
+    const card = `---
+name: bar
+kind: const
+location: bar.ts:5-5
+summary:
+---
+`;
+
+    const updated = updateCardSummary(card, 'Just a constant.');
+    expect(updated).toContain('summary: Just a constant.');
+    expect(updated).toContain('## What it does');
+  });
+
+  it('does not break frontmatter for cards with tags field', () => {
+    const card = `---
+name: myFunc
+kind: function
+location: a.ts:1-10
+tags: alpha, beta
+summary:
+---
+
+# myFunc
+`;
+
+    const updated = updateCardSummary(card, 'A function that does something.');
+    const parsed = parseCard(updated);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.head.name).toBe('myFunc');
+    expect(parsed!.head.summary).toBe('A function that does something.');
+    expect(parsed!.head.tags).toEqual(['alpha', 'beta']);
+  });
+
+  it('round-trips through parseCard', () => {
+    const card = `---
+name: probeCompat
+kind: function
+location: compat.ts:201-243
+summary: Old
+---
+
+# probeCompat
+`;
+
+    const updated = updateCardSummary(card, 'A function to detect integrations.');
+    const parsed = parseCard(updated);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.head.summary).toBe('A function to detect integrations.');
+    expect(parsed!.body).toContain('A function to detect integrations.');
+  });
+});
+
 describe('cardHead', () => {
   it('returns only the frontmatter head from a card', () => {
     const sym = makeSymbol();

package/src/cards.ts

@@ -76,6 +76,59 @@ export function parseCard(text: string): { head: CardHead; body: string } | null
   };
 }
 
+/**
+ * Pure: rewrite a card's frontmatter summary: line and upsert a ## What it does body section.
+ * Idempotent — enriching twice yields the same card (replaces the section, doesn't stack duplicates).
+ */
+export function updateCardSummary(cardText: string, summary: string): string {
+  const trimmed = cardText.trim();
+
+  // Split into frontmatter and body
+  const endOfFm = trimmed.indexOf("\n---", 3);
+  if (endOfFm === -1) return cardText; // invalid card, return as-is
+
+  const fmRaw = trimmed.slice(3, endOfFm).trim();
+  const bodyRaw = trimmed.slice(endOfFm + 4).trim();
+
+  // Rebuild frontmatter, replacing summary: line
+  const fmLines = fmRaw.split("\n");
+  const newFmLines: string[] = [];
+  let summaryReplaced = false;
+
+  for (const line of fmLines) {
+    const sep = line.indexOf(":");
+    if (sep > 0) {
+      const key = line.slice(0, sep).trim();
+      if (key === "summary") {
+        newFmLines.push(`summary: ${summary}`);
+        summaryReplaced = true;
+        continue;
+      }
+    }
+    newFmLines.push(line);
+  }
+
+  if (!summaryReplaced) {
+    newFmLines.push(`summary: ${summary}`);
+  }
+
+  const newFrontmatter = `---\n${newFmLines.join("\n")}\n---`;
+
+  // Build body — replace existing ## What it does section if present
+  let body = bodyRaw;
+  const whatItDoesRegex = /## What it does[\s\S]*?(?=\n## |$)/;
+  const whatItDoesSection = `## What it does\n\n${summary}`;
+
+  if (whatItDoesRegex.test(body)) {
+    body = body.replace(whatItDoesRegex, whatItDoesSection);
+  } else {
+    // Append after existing body (or replace empty body)
+    body = body ? `${body}\n\n${whatItDoesSection}` : whatItDoesSection;
+  }
+
+  return `${newFrontmatter}\n\n${body}\n`;
+}
+
 /**
  * Extract only the frontmatter head from a card — the compact, agent-cheap view.
  * Returns null if the card is invalid.