opencode-rules-md 0.6.5

package/src/message-paths.ts

@@ -0,0 +1,153 @@
+/**
+ * Message path extraction utilities
+ */
+
+/**
+ * Message part types from OpenCode plugin API
+ */
+interface ToolInvocationPart {
+  type: 'tool-invocation';
+  toolInvocation: {
+    toolName: string;
+    args: Record<string, unknown>;
+  };
+}
+
+interface TextPart {
+  type: 'text';
+  text: string;
+}
+
+export type MessagePart = ToolInvocationPart | TextPart | { type: string };
+
+export interface Message {
+  role: string;
+  parts: MessagePart[];
+}
+
+/**
+ * Extract file paths from conversation messages for conditional rule filtering.
+ * Parses tool call arguments and scans message content for path-like strings.
+ *
+ * @param messages - Array of conversation messages
+ * @returns Deduplicated array of file paths found in messages
+ */
+export function extractFilePathsFromMessages(messages: Message[]): string[] {
+  const paths = new Set<string>();
+
+  for (const message of messages) {
+    for (const part of message.parts) {
+      // Extract from tool invocations
+      if (part.type === 'tool-invocation') {
+        const toolPart = part as ToolInvocationPart;
+        extractPathsFromToolCall(toolPart, paths);
+      }
+
+      // Extract from text content
+      if (part.type === 'text') {
+        const textPart = part as TextPart;
+        extractPathsFromText(textPart.text, paths);
+      }
+    }
+  }
+
+  return Array.from(paths);
+}
+
+/**
+ * Extract file paths from tool call arguments
+ */
+function extractPathsFromToolCall(
+  part: ToolInvocationPart,
+  paths: Set<string>
+): void {
+  const { toolName, args } = part.toolInvocation;
+
+  // Tools that have a direct file path argument
+  const pathArgTools: Record<string, string[]> = {
+    read: ['filePath'],
+    edit: ['filePath'],
+    write: ['filePath'],
+    glob: ['pattern', 'path'],
+    grep: ['path'],
+  };
+
+  const argNames = pathArgTools[toolName];
+  if (argNames) {
+    for (const argName of argNames) {
+      const value = args[argName];
+      if (typeof value === 'string' && value.length > 0) {
+        // For glob patterns, extract the directory part
+        if (argName === 'pattern') {
+          const dirPart = extractDirFromGlob(value);
+          if (dirPart) paths.add(dirPart);
+        } else {
+          paths.add(value);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Extract directory path from a glob pattern
+ */
+function extractDirFromGlob(pattern: string): string | null {
+  // Find the first glob character
+  const globChars = ['*', '?', '[', '{'];
+  let firstGlobIndex = pattern.length;
+
+  for (const char of globChars) {
+    const idx = pattern.indexOf(char);
+    if (idx !== -1 && idx < firstGlobIndex) {
+      firstGlobIndex = idx;
+    }
+  }
+
+  if (firstGlobIndex === 0) return null;
+
+  // Get the directory part before the glob
+  const beforeGlob = pattern.substring(0, firstGlobIndex);
+  const lastSlash = beforeGlob.lastIndexOf('/');
+
+  if (lastSlash === -1) {
+    // If no slash and pattern has glob characters, it's just a file prefix, not a directory
+    if (firstGlobIndex < pattern.length) return null;
+    return beforeGlob;
+  }
+  return beforeGlob.substring(0, lastSlash);
+}
+
+/**
+ * Extract file paths from text content using regex
+ */
+function extractPathsFromText(text: string, paths: Set<string>): void {
+  // Match paths that look like file paths:
+  // - Start with ./, ../, /, or a word character
+  // - Contain at least one /
+  // - End with a file extension or directory
+  const pathRegex =
+    /(?:^|[\s"'`(])((\.{0,2}\/)?[\w./-]+\/[\w./-]+(?:\.\w+)?)/gm;
+
+  let match;
+  while ((match = pathRegex.exec(text)) !== null) {
+    let potentialPath = match[1];
+
+    // Trim trailing punctuation that likely belongs to prose, not the path
+    potentialPath = potentialPath.replace(/[.,!?:;]+$/, '');
+
+    // Filter out URLs and other non-paths
+    if (
+      potentialPath.includes('://') ||
+      potentialPath.startsWith('http') ||
+      potentialPath.includes('@')
+    ) {
+      continue;
+    }
+
+    // Must have a reasonable structure (not just slashes)
+    if (potentialPath.replace(/[/.]/g, '').length > 0) {
+      paths.add(potentialPath);
+    }
+  }
+}

package/src/project-fingerprint.ts

@@ -0,0 +1,72 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const SIMPLE_MARKERS: Array<[string, string]> = [
+  ['package.json', 'node'],
+  ['pyproject.toml', 'python'],
+  ['go.mod', 'go'],
+  ['Cargo.toml', 'rust'],
+  ['pnpm-workspace.yaml', 'monorepo'],
+  ['turbo.json', 'monorepo'],
+];
+
+const BROWSER_EXTENSION_SIGNAL_KEYS = [
+  'background',
+  'content_scripts',
+  'browser_action',
+  'page_action',
+  'action',
+  'permissions',
+];
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isBrowserExtensionManifest(
+  manifestPath: string
+): Promise<boolean> {
+  try {
+    const content = await fs.readFile(manifestPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+      return false;
+    const version = parsed.manifest_version;
+    if (version !== 2 && version !== 3) return false;
+    return BROWSER_EXTENSION_SIGNAL_KEYS.some(key => key in parsed);
+  } catch {
+    return false;
+  }
+}
+
+export async function detectProjectTags(projectDir: string): Promise<string[]> {
+  const tags = new Set<string>();
+
+  const checks = SIMPLE_MARKERS.map(async ([marker, tag]) => {
+    const markerPath = path.join(projectDir, marker);
+    if (await fileExists(markerPath)) {
+      tags.add(tag);
+    }
+  });
+
+  const manifestPath = path.join(projectDir, 'manifest.json');
+  checks.push(
+    (async () => {
+      if (
+        (await fileExists(manifestPath)) &&
+        (await isBrowserExtensionManifest(manifestPath))
+      ) {
+        tags.add('browser-extension');
+      }
+    })()
+  );
+
+  await Promise.all(checks);
+
+  return [...tags].sort((a, b) => a.localeCompare(b));
+}

package/src/rule-discovery.ts

@@ -0,0 +1,205 @@
+/**
+ * Rule file discovery utilities
+ */
+
+import { stat, readFile, readdir } from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { createDebugLog } from './debug';
+import {
+  parseRuleMetadata,
+  stripFrontmatter,
+  type RuleMetadata,
+} from './rule-metadata';
+
+const debugLog = createDebugLog();
+
+/**
+ * Cached rule data for performance optimization
+ */
+interface CachedRule {
+  /** Raw file content */
+  content: string;
+  /** Parsed metadata from frontmatter */
+  metadata: RuleMetadata | undefined;
+  /** Content with frontmatter stripped */
+  strippedContent: string;
+  /** File modification time for cache invalidation */
+  mtime: number;
+}
+
+/**
+ * Rule cache keyed by absolute file path
+ */
+const ruleCache = new Map<string, CachedRule>();
+
+/**
+ * Clear the rule cache (useful for testing or manual invalidation)
+ */
+export function clearRuleCache(): void {
+  ruleCache.clear();
+}
+
+/**
+ * Get cached rule data, refreshing from disk if file has changed.
+ * Uses mtime-based invalidation to detect file changes.
+ *
+ * @param filePath - Absolute path to the rule file
+ * @returns Cached rule data or undefined if file cannot be read
+ */
+export async function getCachedRule(
+  filePath: string
+): Promise<CachedRule | undefined> {
+  try {
+    const stats = await stat(filePath);
+    const mtime = stats.mtimeMs;
+
+    // Check if we have a valid cached entry
+    const cached = ruleCache.get(filePath);
+    if (cached && cached.mtime === mtime) {
+      debugLog(`Cache hit: ${filePath}`);
+      return cached;
+    }
+
+    // Read and cache the file
+    debugLog(`Cache miss: ${filePath}`);
+    const content = await readFile(filePath, 'utf-8');
+    const metadata = parseRuleMetadata(content);
+    const strippedContent = stripFrontmatter(content);
+
+    const entry: CachedRule = {
+      content,
+      metadata,
+      strippedContent,
+      mtime,
+    };
+
+    ruleCache.set(filePath, entry);
+    return entry;
+  } catch (error) {
+    // Remove stale cache entry if file no longer exists
+    ruleCache.delete(filePath);
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[opencode-rules-md] Warning: Failed to read rule file ${filePath}: ${message}`
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Get the global rules directory path
+ */
+function getGlobalRulesDir(): string | null {
+  const opencodeConfigDir = process.env.OPENCODE_CONFIG_DIR;
+  if (opencodeConfigDir) {
+    return path.join(opencodeConfigDir, 'rules');
+  }
+
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome) {
+    return path.join(xdgConfigHome, 'opencode', 'rules');
+  }
+
+  const homeDir = process.env.HOME || os.homedir();
+  return path.join(homeDir, '.config', 'opencode', 'rules');
+}
+
+/**
+ * Recursively scan a directory for markdown rule files
+ * Skips hidden files and directories (starting with .)
+ * @param dir - Directory to scan
+ * @param baseDir - Base directory for relative path calculation
+ * @returns Array of discovered file paths with their relative paths from baseDir
+ */
+async function scanDirectoryRecursively(
+  dir: string,
+  baseDir: string
+): Promise<Array<{ filePath: string; relativePath: string }>> {
+  const results: Array<{ filePath: string; relativePath: string }> = [];
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip hidden files and directories
+      if (entry.name.startsWith('.')) {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Recurse into subdirectory
+        results.push(...(await scanDirectoryRecursively(fullPath, baseDir)));
+      } else if (entry.name.endsWith('.md') || entry.name.endsWith('.mdc')) {
+        // Add markdown file
+        const relativePath = path.relative(baseDir, fullPath);
+        results.push({ filePath: fullPath, relativePath });
+      }
+    }
+  } catch (error) {
+    // Treat ENOENT as benign (directory doesn't exist or was deleted)
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return results;
+    }
+    // Log non-ENOENT directory read errors
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[opencode-rules-md] Warning: Failed to read directory ${dir}: ${message}`
+    );
+  }
+
+  return results;
+}
+
+/**
+ * Discovered rule file with both absolute and relative paths
+ */
+export interface DiscoveredRule {
+  /** Absolute path to the rule file */
+  filePath: string;
+  /** Relative path from the rules directory root (for unique headings) */
+  relativePath: string;
+}
+
+/**
+ * Discover markdown rule files from standard directories
+ * Searches recursively in:
+ * - $OPENCODE_CONFIG_DIR/rules/ (highest priority)
+ * - $XDG_CONFIG_HOME/opencode/rules/ (or ~/.config/opencode/rules as fallback)
+ * - .opencode/rules/ (in project directory if provided)
+ * Finds all .md and .mdc files including nested subdirectories.
+ */
+export async function discoverRuleFiles(
+  projectDir?: string
+): Promise<DiscoveredRule[]> {
+  const files: DiscoveredRule[] = [];
+
+  // Discover global rules (recursively)
+  const globalRulesDir = getGlobalRulesDir();
+  if (globalRulesDir) {
+    const globalRules = await scanDirectoryRecursively(
+      globalRulesDir,
+      globalRulesDir
+    );
+    for (const { filePath, relativePath } of globalRules) {
+      debugLog(`Discovered global rule: ${relativePath} (${filePath})`);
+      files.push({ filePath, relativePath });
+    }
+  }
+
+  // Discover project-local rules (recursively) if project directory is provided
+  if (projectDir) {
+    const projectRulesDir = path.join(projectDir, '.opencode', 'rules');
+    const projectRules = await scanDirectoryRecursively(
+      projectRulesDir,
+      projectRulesDir
+    );
+    for (const { filePath, relativePath } of projectRules) {
+      debugLog(`Discovered project rule: ${relativePath} (${filePath})`);
+      files.push({ filePath, relativePath });
+    }
+  }
+
+  return files;
+}

package/src/rule-filter.ts

@@ -0,0 +1,269 @@
+/**
+ * Rule filtering and matching utilities
+ */
+
+import { minimatch } from 'minimatch';
+import { createDebugLog } from './debug.js';
+import { getCachedRule, type DiscoveredRule } from './rule-discovery.js';
+
+const debugLog = createDebugLog();
+
+/**
+ * Check if a file path matches any of the given glob patterns
+ */
+function fileMatchesGlobs(filePath: string, globs: string[]): boolean {
+  return globs.some(glob => minimatch(filePath, glob, { matchBase: true }));
+}
+
+/**
+ * Check if a user prompt matches any of the given keywords.
+ * Uses case-insensitive word-boundary matching.
+ *
+ * @param prompt - The user's prompt text
+ * @param keywords - Array of keywords to match
+ * @returns true if any keyword matches the prompt
+ */
+export function promptMatchesKeywords(
+  prompt: string,
+  keywords: string[]
+): boolean {
+  const lowerPrompt = prompt.toLowerCase();
+
+  return keywords.some(keyword => {
+    const lowerKeyword = keyword.toLowerCase();
+    // Escape special regex characters in the keyword
+    const escaped = lowerKeyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Word boundary at start, but allow continuation at end (e.g., "test" matches "testing")
+    const regex = new RegExp(`\\b${escaped}`, 'i');
+    return regex.test(lowerPrompt);
+  });
+}
+
+/**
+ * Check if any of the required tools are available.
+ * Uses exact string matching (OR logic: any match returns true).
+ *
+ * @param availableToolIDs - Array of tool IDs currently available
+ * @param requiredTools - Array of tool IDs from rule metadata
+ * @returns true if any required tool is available
+ */
+export function toolsMatchAvailable(
+  availableToolIDs: string[],
+  requiredTools: string[]
+): boolean {
+  if (requiredTools.length === 0) {
+    return false;
+  }
+  // Create a Set for O(1) lookups
+  const availableSet = new Set(availableToolIDs);
+  return requiredTools.some(tool => availableSet.has(tool));
+}
+
+/**
+ * Result of reading and formatting rules
+ */
+export interface FilterResult {
+  formattedRules: string;
+  matchedPaths: string[];
+}
+
+/**
+ * Runtime filter context for conditional rule matching
+ */
+export interface RuleFilterContext {
+  /** File paths from conversation context (for glob matching) */
+  contextFilePaths?: string[];
+  /** User's prompt text (for keyword matching) */
+  userPrompt?: string;
+  /** Available tool IDs (for tool-based filtering) */
+  availableToolIDs?: string[];
+  /** Current model ID */
+  modelID?: string;
+  /** Current agent type */
+  agentType?: string;
+  /** Current slash command (e.g., /plan, /review) */
+  command?: string;
+  /** Detected project tags (e.g., node, python, monorepo) */
+  projectTags?: string[];
+  /** Current git branch name */
+  gitBranch?: string;
+  /** Current operating system (e.g., linux, darwin, win32) */
+  os?: string;
+  /** Whether running in CI environment */
+  ci?: boolean;
+}
+
+/**
+ * Read and format rule files for system prompt injection
+ * @param files - Array of discovered rule files with paths
+ * @param context - Optional RuleFilterContext for conditional rule matching
+ */
+export async function readAndFormatRules(
+  files: DiscoveredRule[],
+  context: RuleFilterContext = {}
+): Promise<FilterResult> {
+  if (files.length === 0) {
+    return { formattedRules: '', matchedPaths: [] };
+  }
+
+  const ruleContents: string[] = [];
+  const matchedPaths: string[] = [];
+  const availableToolSet =
+    context.availableToolIDs && context.availableToolIDs.length > 0
+      ? new Set(context.availableToolIDs)
+      : undefined;
+
+  for (const { filePath, relativePath } of files) {
+    // Use cached rule data with mtime-based invalidation
+    const cachedRule = await getCachedRule(filePath);
+    if (!cachedRule) {
+      continue; // Error already logged by getCachedRule
+    }
+
+    const { metadata, strippedContent } = cachedRule;
+
+    // Check if rule has any conditional filters
+    const hasConditions = Boolean(
+      metadata?.globs ||
+      metadata?.keywords ||
+      metadata?.tools ||
+      metadata?.model ||
+      metadata?.agent ||
+      metadata?.command ||
+      metadata?.project ||
+      metadata?.branch ||
+      metadata?.os ||
+      metadata?.ci !== undefined
+    );
+
+    if (hasConditions && metadata) {
+      // Compute per-dimension match booleans (only for declared conditions)
+      const declaredChecks: boolean[] = [];
+
+      // Legacy: globs
+      if (metadata.globs) {
+        const globs = metadata.globs;
+        const globsMatch =
+          context.contextFilePaths &&
+          context.contextFilePaths.length > 0 &&
+          context.contextFilePaths.some(contextPath =>
+            fileMatchesGlobs(contextPath, globs)
+          );
+        declaredChecks.push(Boolean(globsMatch));
+      }
+
+      // Legacy: keywords
+      if (metadata.keywords) {
+        const keywordsMatch =
+          context.userPrompt &&
+          promptMatchesKeywords(context.userPrompt, metadata.keywords);
+        declaredChecks.push(Boolean(keywordsMatch));
+      }
+
+      // Legacy: tools
+      if (metadata.tools) {
+        const toolsMatch =
+          availableToolSet &&
+          metadata.tools.some(tool => availableToolSet.has(tool));
+        declaredChecks.push(Boolean(toolsMatch));
+      }
+
+      // New: model
+      if (metadata.model) {
+        const modelMatch =
+          context.modelID && metadata.model.includes(context.modelID);
+        declaredChecks.push(Boolean(modelMatch));
+      }
+
+      // New: agent
+      if (metadata.agent) {
+        const agentMatch =
+          context.agentType && metadata.agent.includes(context.agentType);
+        declaredChecks.push(Boolean(agentMatch));
+      }
+
+      // New: command
+      if (metadata.command) {
+        const commandMatch =
+          context.command && metadata.command.includes(context.command);
+        declaredChecks.push(Boolean(commandMatch));
+      }
+
+      // New: project
+      if (metadata.project) {
+        const projectTags = context.projectTags;
+        const projectMatch =
+          projectTags &&
+          projectTags.length > 0 &&
+          metadata.project.some(tag => projectTags.includes(tag));
+        declaredChecks.push(Boolean(projectMatch));
+      }
+
+      // New: branch (supports glob patterns)
+      if (metadata.branch) {
+        const gitBranch = context.gitBranch;
+        const branchMatch =
+          gitBranch &&
+          metadata.branch.some(pattern => {
+            // Exact match for non-glob patterns
+            if (pattern === gitBranch) {
+              return true;
+            }
+            // Only use glob matching if pattern contains glob characters
+            const hasGlobChars = /[*?\[{]/.test(pattern);
+            if (hasGlobChars) {
+              return minimatch(gitBranch, pattern);
+            }
+            return false;
+          });
+        declaredChecks.push(Boolean(branchMatch));
+      }
+
+      // New: os
+      if (metadata.os) {
+        const osMatch = context.os && metadata.os.includes(context.os);
+        declaredChecks.push(Boolean(osMatch));
+      }
+
+      // New: ci (strict boolean equality)
+      if (metadata.ci !== undefined) {
+        const ciMatch = context.ci === metadata.ci;
+        declaredChecks.push(ciMatch);
+      }
+
+      // Apply combinator: default 'any', or 'all' if specified
+      const mode = metadata.match ?? 'any';
+      const shouldInclude =
+        mode === 'all'
+          ? declaredChecks.every(Boolean)
+          : declaredChecks.some(Boolean);
+
+      if (!shouldInclude) {
+        debugLog(
+          `Skipping conditional rule: ${relativePath} (match: ${mode}, checks: ${declaredChecks.join(', ')})`
+        );
+        continue;
+      }
+
+      debugLog(
+        `Including conditional rule: ${relativePath} (match: ${mode}, checks: ${declaredChecks.join(', ')})`
+      );
+    }
+
+    // Use cached stripped content for output
+    // Use relativePath for unique headings instead of just filename
+    ruleContents.push(`## ${relativePath}\n\n${strippedContent}`);
+    matchedPaths.push(filePath);
+  }
+
+  if (ruleContents.length === 0) {
+    return { formattedRules: '', matchedPaths: [] };
+  }
+
+  return {
+    formattedRules:
+      `# OpenCode Rules\n\nPlease follow the following rules:\n\n` +
+      ruleContents.join('\n\n---\n\n'),
+    matchedPaths,
+  };
+}