@rmrdeveloper/sideroom-pi 8.0.2 → 8.1.1

package/extensions/rules/checks.ts

@@ -0,0 +1,346 @@
+import {
+  LANGUAGE,
+  type LanguageId,
+  RULE_SEVERITY,
+  type RuleId,
+  supportsBracedConditionals,
+} from './catalog.ts';
+import { maskNonCode } from './lexer.ts';
+import type { AddedLine, RuleViolation } from './model.ts';
+
+const BANNED_ALTERNATION = 'data|info|temp|tmp|result|obj|val|x';
+const CONTROL_HEADER = /\b(?:if|else\s+if|for|while)\s*\(/g;
+const ELSE_KEYWORD = /\belse\b/g;
+const PYTHON_INLINE_SUITE =
+  /^\s*(?:if|elif|else|for|while|with|try|except|finally|def|class)\b.*:\s*(?:return|pass|raise|break|continue|yield|assert|del|import|from|global|nonlocal|print|await|lambda)\b/;
+
+const EMPTY_CATCH =
+  /\bcatch\s*(?:\([^)]*\))?\s*\{\s*(?:(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)?\}/g;
+const SWALLOW_RETURN =
+  /\bcatch\s*(?:\([^)]*\))?\s*\{\s*return\s+(?:null|undefined|void\s+0)\s*;?\s*\}/g;
+const PYTHON_SWALLOW =
+  /^[ \t]*except\b[^:\n]*:[ \t]*(?:pass|\.\.\.)[ \t]*(?:#[^\n]*)?$/gm;
+const PYTHON_SWALLOW_BLOCK =
+  /^[ \t]*except\b[^:\n]*:[ \t]*\n[ \t]*(?:pass|\.\.\.)[ \t]*(?:#[^\n]*)?$/gm;
+
+const TODO_COMMENT = /(?:\/\/|#|\/\*)[^\n]*\b(?:TODO|FIXME|XXX|HACK)\b/;
+const COMMENTED_CODE =
+  /^\s*(?:\/\/|#)\s*(?:if|for|while|return|const|let|var|function|class|def|import|from|print|console|await|async)\b/;
+const CODE_LIKE_COMMENT = /^\s*(?:\/\/|#).*[;{}]\s*$/;
+
+const DEBUG_PATTERNS: readonly RegExp[] = [
+  /\bconsole\.(?:log|debug)\s*\(/,
+  /\bdebugger\b/,
+  /^\s*print\s*\(/,
+  /\bvar_dump\s*\(/,
+  /\bdd\s*\(/,
+  /\bdump\s*\(/,
+  /\bdbg!\s*\(/,
+];
+
+const FUNCTION_PARAMS: readonly RegExp[] = [
+  /\bfunction\s+\w*\s*\(([^()]*)\)/g,
+  /\bdef\s+\w+\s*\(([^()]*)\)/g,
+  /\bfn\s+\w+\s*\(([^()]*)\)/g,
+  /\(([^()]*)\)\s*=>/g,
+];
+
+export function evaluateAddedLines(
+  language: LanguageId,
+  lines: readonly AddedLine[],
+): RuleViolation[] {
+  const violations: RuleViolation[] = [];
+  const joined = lines.map((added) => added.text).join('\n');
+  const code = maskNonCode(joined, language);
+  const codeLines = code.split('\n');
+  const usesBracedConditionals = supportsBracedConditionals(language);
+
+  if (usesBracedConditionals) {
+    collectBracedConditionals(code, lines, violations);
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const added = lines[index];
+    if (added === undefined) {
+      continue;
+    }
+    const codeLine: AddedLine = {
+      line: added.line,
+      text: codeLines[index] ?? '',
+    };
+    if (language === LANGUAGE.python) {
+      collectPythonSuite(codeLine, violations);
+    }
+    collectClearNames(codeLine, violations);
+    collectComments(added, violations);
+    collectDebugArtifacts(codeLine, violations);
+  }
+
+  collectErrorHandling(language, code, lines, violations);
+  return dedupe(violations);
+}
+
+function violation(
+  ruleId: RuleId,
+  message: string,
+  line: number,
+): RuleViolation {
+  return { ruleId, severity: RULE_SEVERITY[ruleId], message, line };
+}
+
+function collectBracedConditionals(
+  code: string,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  const controlMatcher = new RegExp(
+    CONTROL_HEADER.source,
+    CONTROL_HEADER.flags,
+  );
+  const controlMatches = code.matchAll(controlMatcher);
+  for (const match of controlMatches) {
+    const matchOffset = match.index ?? 0;
+    const openingOffset = code.indexOf('(', matchOffset);
+    if (openingOffset < 0) {
+      continue;
+    }
+    const closingOffset = closingParenthesisOffset(code, openingOffset);
+    if (closingOffset === undefined) {
+      continue;
+    }
+    const bodyOffset = nextCodeOffset(code, closingOffset + 1);
+    if (bodyOffset === undefined) {
+      continue;
+    }
+    const hasBlockBody = code[bodyOffset] === '{';
+    if (hasBlockBody) {
+      continue;
+    }
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Wrap the conditional body in braces.',
+        lineForOffset(code, lines, matchOffset),
+      ),
+    );
+  }
+
+  const elseMatcher = new RegExp(ELSE_KEYWORD.source, ELSE_KEYWORD.flags);
+  const elseMatches = code.matchAll(elseMatcher);
+  for (const match of elseMatches) {
+    const matchOffset = match.index ?? 0;
+    const bodyOffset = nextCodeOffset(code, matchOffset + match[0].length);
+    if (bodyOffset === undefined) {
+      continue;
+    }
+    const hasBlockBody = code[bodyOffset] === '{';
+    const hasNestedIf = startsWithWord(code, bodyOffset, 'if');
+    if (hasBlockBody || hasNestedIf) {
+      continue;
+    }
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Wrap the conditional body in braces.',
+        lineForOffset(code, lines, matchOffset),
+      ),
+    );
+  }
+}
+
+function collectPythonSuite(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (PYTHON_INLINE_SUITE.test(added.text)) {
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Put the suite on its own indented line.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function collectErrorHandling(
+  language: LanguageId,
+  code: string,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  if (language === LANGUAGE.python) {
+    collectPattern(PYTHON_SWALLOW, code, lines, violations);
+    collectPattern(PYTHON_SWALLOW_BLOCK, code, lines, violations);
+    return;
+  }
+  if (language === LANGUAGE.generic) {
+    return;
+  }
+  collectPattern(EMPTY_CATCH, code, lines, violations);
+  collectPattern(SWALLOW_RETURN, code, lines, violations);
+}
+
+function collectPattern(
+  pattern: RegExp,
+  joined: string,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  const matcher = new RegExp(pattern.source, pattern.flags);
+  for (const match of joined.matchAll(matcher)) {
+    const offset = match.index ?? 0;
+    violations.push(
+      violation(
+        'explicit-error-handling',
+        '[explicit-error-handling] Do not swallow errors; rethrow with context or let them propagate.',
+        lineForOffset(joined, lines, offset),
+      ),
+    );
+  }
+}
+
+function collectClearNames(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  const declaration = new RegExp(
+    `\\b(?:const|let|var|val|auto|final)\\s+(${BANNED_ALTERNATION})\\b`,
+  );
+  const assignment = new RegExp(`^\\s*(${BANNED_ALTERNATION})\\s*(?::=|=)`);
+  const match = declaration.exec(added.text) ?? assignment.exec(added.text);
+  if (match !== null) {
+    pushClearName(added.line, match[1], violations);
+    return;
+  }
+
+  for (const pattern of FUNCTION_PARAMS) {
+    const params = new RegExp(pattern.source, pattern.flags);
+    for (const paramMatch of added.text.matchAll(params)) {
+      const banned = new RegExp(`\\b(${BANNED_ALTERNATION})\\b`).exec(
+        paramMatch[1] ?? '',
+      );
+      if (banned !== null) {
+        pushClearName(added.line, banned[1], violations);
+        return;
+      }
+    }
+  }
+}
+
+function pushClearName(
+  line: number,
+  name: string | undefined,
+  violations: RuleViolation[],
+): void {
+  const label = name ?? 'identifier';
+  violations.push(
+    violation(
+      'clear-names',
+      `[clear-names] Rename '${label}' to a name that reveals its role.`,
+      line,
+    ),
+  );
+}
+
+function collectComments(added: AddedLine, violations: RuleViolation[]): void {
+  if (
+    TODO_COMMENT.test(added.text) ||
+    COMMENTED_CODE.test(added.text) ||
+    CODE_LIKE_COMMENT.test(added.text)
+  ) {
+    violations.push(
+      violation(
+        'comments',
+        '[comments] Remove stale TODO/FIXME or commented-out code; keep only non-obvious intent.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function collectDebugArtifacts(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (DEBUG_PATTERNS.some((pattern) => pattern.test(added.text))) {
+    violations.push(
+      violation(
+        'debug-artifacts',
+        '[debug-artifacts] Remove debug output before finishing.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function closingParenthesisOffset(
+  code: string,
+  openingOffset: number,
+): number | undefined {
+  let depth = 0;
+  for (let index = openingOffset; index < code.length; index += 1) {
+    const character = code[index];
+    if (character === '(') {
+      depth += 1;
+      continue;
+    }
+    if (character !== ')') {
+      continue;
+    }
+    depth -= 1;
+    if (depth === 0) {
+      return index;
+    }
+  }
+  return undefined;
+}
+
+function nextCodeOffset(code: string, offset: number): number | undefined {
+  for (let index = offset; index < code.length; index += 1) {
+    const character = code[index] ?? '';
+    const isWhitespace = /\s/.test(character);
+    if (!isWhitespace) {
+      return index;
+    }
+  }
+  return undefined;
+}
+
+function startsWithWord(code: string, offset: number, word: string): boolean {
+  const startsAtOffset = code.startsWith(word, offset);
+  if (!startsAtOffset) {
+    return false;
+  }
+  const following = code[offset + word.length] ?? '';
+  const isWordCharacter = /[A-Za-z0-9_$]/.test(following);
+  return following.length === 0 || !isWordCharacter;
+}
+
+function lineForOffset(
+  joined: string,
+  lines: readonly AddedLine[],
+  offset: number,
+): number {
+  let lineIndex = 0;
+  for (let index = 0; index < offset; index += 1) {
+    if (joined.charCodeAt(index) === 10) {
+      lineIndex += 1;
+    }
+  }
+  return lines[lineIndex]?.line ?? lines.at(-1)?.line ?? 0;
+}
+
+function dedupe(violations: readonly RuleViolation[]): RuleViolation[] {
+  const seen = new Set<string>();
+  const deduped: RuleViolation[] = [];
+  for (const item of violations) {
+    const key = `${item.ruleId}:${String(item.line)}:${item.message}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(item);
+  }
+  return deduped;
+}

package/extensions/rules/guard.ts

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isToolCallEventType,
+  isWriteToolResult,
+  type ToolCallEvent,
+} from '@earendil-works/pi-coding-agent';
+import { languageForPath, type RuleId, SEVERITY } from './catalog.ts';
+import { evaluateAddedLines } from './checks.ts';
+import {
+  type AddedLine,
+  addedLines,
+  formatBlockReason,
+  formatWarnings,
+  type RuleViolation,
+} from './model.ts';
+
+const BLOCK_DEGRADE_AFTER = 3;
+const CLEAN_RESET_AFTER = 5;
+
+interface PendingWarnings {
+  readonly path: string;
+  readonly violations: readonly RuleViolation[];
+}
+
+export interface RulesState {
+  readonly fires: Map<RuleId, number>;
+  cleanChecks: number;
+  readonly pendingWarnings: Map<string, PendingWarnings>;
+}
+
+interface ExtractedMutation {
+  readonly path: string;
+  readonly language: ReturnType<typeof languageForPath>;
+  readonly lines: readonly AddedLine[];
+}
+
+export function createRulesState(): RulesState {
+  return { fires: new Map(), cleanChecks: 0, pendingWarnings: new Map() };
+}
+
+export function resetRulesState(state: RulesState): void {
+  state.fires.clear();
+  state.cleanChecks = 0;
+  state.pendingWarnings.clear();
+}
+
+export function registerRulesGuard(pi: ExtensionAPI, state: RulesState): void {
+  pi.on('tool_call', (event, ctx) => {
+    const mutation = extractMutation(event, ctx.cwd);
+    if (mutation === undefined) {
+      return undefined;
+    }
+    const violations = evaluateAddedLines(mutation.language, mutation.lines);
+    return applyRulesOutcome(
+      state,
+      event.toolCallId,
+      mutation.path,
+      decideRules(state, violations),
+    );
+  });
+
+  pi.on('tool_result', (event) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+      return;
+    }
+    const pending = state.pendingWarnings.get(event.toolCallId);
+    state.pendingWarnings.delete(event.toolCallId);
+    if (pending === undefined || event.isError) {
+      return;
+    }
+    return {
+      content: [
+        ...event.content,
+        {
+          type: 'text' as const,
+          text: formatWarnings(pending.path, pending.violations),
+        },
+      ],
+    };
+  });
+}
+
+export interface RulesDecision {
+  readonly blocking: readonly RuleViolation[];
+  readonly warnings: readonly RuleViolation[];
+}
+
+export function decideRules(
+  state: RulesState,
+  violations: readonly RuleViolation[],
+): RulesDecision {
+  return {
+    blocking: violations.filter(
+      (item) =>
+        item.severity === SEVERITY.block && !isDegraded(state, item.ruleId),
+    ),
+    warnings: violations.filter(
+      (item) =>
+        item.severity === SEVERITY.warn || isDegraded(state, item.ruleId),
+    ),
+  };
+}
+
+function applyRulesOutcome(
+  state: RulesState,
+  toolCallId: string,
+  path: string,
+  decision: RulesDecision,
+): { block: true; reason: string } | undefined {
+  if (decision.blocking.length > 0) {
+    for (const item of decision.blocking) {
+      incrementFires(state, item.ruleId);
+    }
+    return { block: true, reason: formatBlockReason(path, decision.blocking) };
+  }
+
+  registerCleanCheck(state);
+  if (decision.warnings.length > 0) {
+    state.pendingWarnings.set(toolCallId, {
+      path,
+      violations: decision.warnings,
+    });
+  }
+  return undefined;
+}
+
+function extractMutation(
+  event: ToolCallEvent,
+  cwd: string,
+): ExtractedMutation | undefined {
+  if (isToolCallEventType('write', event)) {
+    return extractWrite(event.input.path, event.input.content, cwd);
+  }
+  if (isToolCallEventType('edit', event)) {
+    return extractEdit(event.input.path, event.input.edits);
+  }
+  return undefined;
+}
+
+function extractWrite(
+  path: string,
+  content: string,
+  cwd: string,
+): ExtractedMutation {
+  const previous = readFileIfExists(resolve(cwd, path));
+  return {
+    path,
+    language: languageForPath(path),
+    lines: addedLines(previous, content),
+  };
+}
+
+function extractEdit(
+  path: string,
+  edits: readonly { readonly oldText: string; readonly newText: string }[],
+): ExtractedMutation {
+  const lines: AddedLine[] = [];
+  for (const edit of edits) {
+    lines.push(...addedLines(edit.oldText, edit.newText));
+  }
+  return { path, language: languageForPath(path), lines };
+}
+
+function readFileIfExists(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+function isDegraded(state: RulesState, ruleId: RuleId): boolean {
+  return (state.fires.get(ruleId) ?? 0) >= BLOCK_DEGRADE_AFTER;
+}
+
+function incrementFires(state: RulesState, ruleId: RuleId): void {
+  state.fires.set(ruleId, (state.fires.get(ruleId) ?? 0) + 1);
+}
+
+function registerCleanCheck(state: RulesState): void {
+  state.cleanChecks += 1;
+  if (state.cleanChecks < CLEAN_RESET_AFTER) {
+    return;
+  }
+  state.cleanChecks = 0;
+  state.fires.clear();
+}

package/extensions/rules/index.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  createRulesState,
+  registerRulesGuard,
+  resetRulesState,
+} from './guard.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerRules(pi: ExtensionAPI): void {
+  const state = createRulesState();
+  registerRulesGuard(pi, state);
+
+  pi.on('input', (event) => {
+    if (event.source === 'interactive' || event.source === 'rpc') {
+      resetRulesState(state);
+    }
+  });
+
+  pi.on('session_compact', () => {
+    resetRulesState(state);
+  });
+}

package/extensions/rules/lexer.ts

@@ -0,0 +1,136 @@
+import { LANGUAGE, type LanguageId } from './catalog.ts';
+
+const LEXICAL_MODE = {
+  code: 'code',
+  lineComment: 'line-comment',
+  blockComment: 'block-comment',
+  string: 'string',
+} as const;
+
+type LexicalMode = (typeof LEXICAL_MODE)[keyof typeof LEXICAL_MODE];
+
+export function maskNonCode(source: string, language: LanguageId): string {
+  const masked = [...source];
+  let mode: LexicalMode = LEXICAL_MODE.code;
+  let delimiter = '';
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index] ?? '';
+
+    if (mode === LEXICAL_MODE.lineComment) {
+      if (character === '\n') {
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    if (mode === LEXICAL_MODE.blockComment) {
+      const closesComment = character === '*' && source[index + 1] === '/';
+      if (closesComment) {
+        maskCharacter(masked, index);
+        maskCharacter(masked, index + 1);
+        index += 1;
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    if (mode === LEXICAL_MODE.string) {
+      if (character === '\\') {
+        maskCharacter(masked, index);
+        if (source[index + 1] !== undefined) {
+          maskCharacter(masked, index + 1);
+          index += 1;
+        }
+        continue;
+      }
+      const closesString = source.startsWith(delimiter, index);
+      if (closesString) {
+        for (let offset = 0; offset < delimiter.length; offset += 1) {
+          maskCharacter(masked, index + offset);
+        }
+        index += delimiter.length - 1;
+        delimiter = '';
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      if (delimiter.length === 1 && character === '\n') {
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    const startsLineComment = character === '/' && source[index + 1] === '/';
+    if (startsLineComment) {
+      maskCharacter(masked, index);
+      maskCharacter(masked, index + 1);
+      index += 1;
+      mode = LEXICAL_MODE.lineComment;
+      continue;
+    }
+
+    const startsBlockComment = character === '/' && source[index + 1] === '*';
+    if (startsBlockComment) {
+      maskCharacter(masked, index);
+      maskCharacter(masked, index + 1);
+      index += 1;
+      mode = LEXICAL_MODE.blockComment;
+      continue;
+    }
+
+    const startsHashComment =
+      character === '#' && supportsHashComments(language);
+    if (startsHashComment) {
+      maskCharacter(masked, index);
+      mode = LEXICAL_MODE.lineComment;
+      continue;
+    }
+
+    const startsString =
+      character === "'" || character === '"' || character === '`';
+    if (startsString) {
+      delimiter = stringDelimiter(source, index, language, character);
+      for (let offset = 0; offset < delimiter.length; offset += 1) {
+        maskCharacter(masked, index + offset);
+      }
+      index += delimiter.length - 1;
+      mode = LEXICAL_MODE.string;
+    }
+  }
+
+  return masked.join('');
+}
+
+function stringDelimiter(
+  source: string,
+  index: number,
+  language: LanguageId,
+  quote: string,
+): string {
+  const tripleQuote = `${quote}${quote}${quote}`;
+  const isPythonTripleQuote =
+    language === LANGUAGE.python && source.startsWith(tripleQuote, index);
+  if (isPythonTripleQuote) {
+    return tripleQuote;
+  }
+  return quote;
+}
+
+function supportsHashComments(language: LanguageId): boolean {
+  return language === LANGUAGE.python || language === LANGUAGE.php;
+}
+
+function maskCharacter(masked: string[], index: number): void {
+  const character = masked[index];
+  const shouldMask =
+    character !== undefined && character !== '\n' && character !== '\r';
+  if (shouldMask) {
+    masked[index] = ' ';
+  }
+}