@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/agents/integrity/circular-dependency-agent.js

@@ -0,0 +1,88 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.CIRCULAR.DEPENDENCY
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=refresh-cw
+
+5WH:
+WHAT = Circular dependency agent — detects circular imports and risky graph patterns
+WHY = Circular imports cause module initialization failures and memory leaks
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/circular-dependency-agent.js
+WHEN = 2026
+HOW = DFS cycle detection on the dependency graph produced by dependency-graph-agent
+
+AGENTS:
+CIRCULAR
+DEPENDENCY
+
+LICENSE:
+MIT
+*/
+
+/**
+ * CircularDependencyAgent detects cycles in a dependency graph.
+ */
+export class CircularDependencyAgent {
+  /**
+   * Find all circular dependency cycles in a graph.
+   *
+   * @param {object} graph - Adjacency map from DependencyGraphAgent
+   * @returns {{ cycles: string[][], hasCycles: boolean }}
+   */
+  findCycles(graph) {
+    const visited = new Set();
+    const inStack = new Set();
+    const cycles = [];
+
+    const dfs = (node, path) => {
+      if (inStack.has(node)) {
+        const cycleStart = path.indexOf(node);
+        cycles.push(path.slice(cycleStart).concat(node));
+        return;
+      }
+      if (visited.has(node)) return;
+
+      visited.add(node);
+      inStack.add(node);
+      path.push(node);
+
+      for (const dep of (graph[node]?.imports || [])) {
+        dfs(dep, [...path]);
+      }
+
+      inStack.delete(node);
+    };
+
+    for (const node of Object.keys(graph)) {
+      if (!visited.has(node)) {
+        dfs(node, []);
+      }
+    }
+
+    const uniqueCycles = cycles.filter((cycle, i) =>
+      cycles.findIndex(c => c.join() === cycle.join()) === i
+    );
+
+    return { cycles: uniqueCycles, hasCycles: uniqueCycles.length > 0 };
+  }
+
+  /**
+   * Describe a cycle in human-readable form.
+   *
+   * @param {string[]} cycle
+   * @returns {string}
+   */
+  describeCycle(cycle) {
+    return cycle.join(' → ');
+  }
+}

package/LeeWay-Standards/src/agents/integrity/dependency-graph-agent.js

@@ -0,0 +1,107 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.DEPENDENCY.GRAPH
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=git-branch
+
+5WH:
+WHAT = Dependency graph agent — builds lightweight dependency maps between modules
+WHY = Understanding module dependencies is essential for safe refactoring and change impact analysis
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/dependency-graph-agent.js
+WHEN = 2026
+HOW = Parses import/require statements, builds directed adjacency graph
+
+AGENTS:
+DEPENDENCY
+CIRCULAR
+REFACTOR
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+
+/**
+ * DependencyGraphAgent builds a lightweight module dependency map.
+ */
+export class DependencyGraphAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Extract local import paths from file content.
+   *
+   * @param {string} content
+   * @returns {string[]}
+   */
+  extractImports(content) {
+    const imports = [];
+    const patterns = [
+      /import\s+[^'"]*from\s+['"`](\.\.?\/[^'"`]+)['"`]/g,
+      /require\s*\(\s*['"`](\.\.?\/[^'"`]+)['"`]\s*\)/g,
+    ];
+
+    for (const pattern of patterns) {
+      let match;
+      const regex = new RegExp(pattern.source, pattern.flags);
+      while ((match = regex.exec(content)) !== null) {
+        imports.push(match[1]);
+      }
+    }
+
+    return [...new Set(imports)];
+  }
+
+  /**
+   * Build a dependency graph for a set of files.
+   *
+   * @param {string[]} filePaths - Relative file paths
+   * @returns {Promise<DependencyGraph>}
+   */
+  async buildGraph(filePaths) {
+    const graph = {};
+
+    for (const fp of filePaths) {
+      const fullPath = fp.startsWith('/') ? fp : join(this.rootDir, fp);
+      graph[fp] = { imports: [], importedBy: [] };
+
+      try {
+        const content = await readFile(fullPath, 'utf8');
+        const rawImports = this.extractImports(content);
+
+        for (const imp of rawImports) {
+          const resolved = resolve(dirname(fullPath), imp).replace(this.rootDir + '/', '');
+          const normalized = filePaths.find(f => f.startsWith(resolved.replace(/\.[^.]+$/, '')));
+          if (normalized) {
+            graph[fp].imports.push(normalized);
+          }
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    for (const [file, data] of Object.entries(graph)) {
+      for (const dep of data.imports) {
+        if (graph[dep]) {
+          graph[dep].importedBy.push(file);
+        }
+      }
+    }
+
+    return { agent: 'dependency-graph-agent', graph };
+  }
+}

package/LeeWay-Standards/src/agents/integrity/duplicate-logic-agent.js

@@ -0,0 +1,108 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.DUPLICATE.LOGIC
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=copy
+
+5WH:
+WHAT = Duplicate logic agent — detects repeated logic and duplicate injected blocks
+WHY = Duplicate code wastes space, confuses developers, and creates maintenance debt
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/duplicate-logic-agent.js
+WHEN = 2026
+HOW = Hash-based block comparison across files, sliding window on function bodies
+
+AGENTS:
+DUPLICATE
+SYNTAX
+REFACTOR
+
+LICENSE:
+MIT
+*/
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const MIN_BLOCK_LINES = 5;
+
+/**
+ * DuplicateLogicAgent detects repeated code blocks across files.
+ */
+export class DuplicateLogicAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.minBlockLines = options.minBlockLines || MIN_BLOCK_LINES;
+  }
+
+  /**
+   * Extract normalized code blocks from content for comparison.
+   *
+   * @param {string} content
+   * @returns {Map<string, string>} - Map of hash to block text
+   */
+  extractBlocks(content) {
+    const blocks = new Map();
+    const lines = content.split('\n').map(l => l.trim()).filter(Boolean);
+
+    for (let i = 0; i <= lines.length - this.minBlockLines; i++) {
+      const block = lines.slice(i, i + this.minBlockLines).join('\n');
+      if (block.length < 50) continue;
+      const hash = createHash('sha256').update(block).digest('hex').slice(0, 16);
+      if (!blocks.has(hash)) blocks.set(hash, block);
+    }
+
+    return blocks;
+  }
+
+  /**
+   * Find duplicate blocks across multiple files.
+   *
+   * @param {string[]} filePaths
+   * @returns {Promise<DuplicateReport>}
+   */
+  async findDuplicates(filePaths) {
+    const fileBlocks = new Map();
+
+    for (const fp of filePaths) {
+      const fullPath = fp.startsWith('/') ? fp : join(this.rootDir, fp);
+      try {
+        const content = await readFile(fullPath, 'utf8');
+        fileBlocks.set(fp, this.extractBlocks(content));
+      } catch {
+        continue;
+      }
+    }
+
+    const hashToFiles = new Map();
+    for (const [file, blocks] of fileBlocks.entries()) {
+      for (const [hash, block] of blocks.entries()) {
+        if (!hashToFiles.has(hash)) hashToFiles.set(hash, { block, files: [] });
+        hashToFiles.get(hash).files.push(file);
+      }
+    }
+
+    const duplicates = [];
+    for (const [hash, { block, files }] of hashToFiles.entries()) {
+      if (files.length > 1) {
+        duplicates.push({ hash, files, preview: block.slice(0, 100) + '...' });
+      }
+    }
+
+    return {
+      agent: 'duplicate-logic-agent',
+      duplicatesFound: duplicates.length,
+      duplicates,
+    };
+  }
+}

package/LeeWay-Standards/src/agents/integrity/import-agent.js

@@ -0,0 +1,83 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.IMPORT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=package
+
+5WH:
+WHAT = Import agent — normalizes import style and validates local import rules
+WHY = Mixed import styles and broken paths cause module resolution failures
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/import-agent.js
+WHEN = 2026
+HOW = Scans import statements for style violations and common path issues
+
+AGENTS:
+IMPORT
+SYNTAX
+MODULE
+
+LICENSE:
+MIT
+*/
+
+/**
+ * ImportAgent normalizes and validates import statements.
+ */
+export class ImportAgent {
+  /**
+   * Analyze import statements in file content.
+   *
+   * @param {string} content
+   * @param {{ moduleType?: 'esm' | 'cjs', filePath?: string }} [options]
+   * @returns {{ valid: boolean, issues: string[], suggestions: string[] }}
+   */
+  analyze(content, options = {}) {
+    const { moduleType = 'esm' } = options;
+    const issues = [];
+    const suggestions = [];
+    const lines = content.split('\n');
+
+    const esmImports = lines.filter(l => /^\s*import\s+/.test(l));
+    const cjsRequires = lines.filter(l => /\brequire\s*\(/.test(l));
+
+    if (moduleType === 'esm' && cjsRequires.length > 0) {
+      issues.push(`Found ${cjsRequires.length} require() call(s) in ESM module — use import instead`);
+      suggestions.push('Convert require() to import statements');
+    }
+    if (moduleType === 'cjs' && esmImports.length > 0) {
+      issues.push(`Found ${esmImports.length} import statement(s) in CJS module — use require() instead`);
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const importMatch = line.match(/from\s+['"`]([^'"`]+)['"`]/);
+      if (!importMatch) continue;
+
+      const importPath = importMatch[1];
+
+      if (importPath.startsWith('.') && !importPath.includes('.js') && !importPath.includes('.ts')
+          && importPath.includes('/') && moduleType === 'esm') {
+        const hasExtension = /\.[a-z]+$/.test(importPath);
+        if (!hasExtension) {
+          suggestions.push(`Line ${i + 1}: ESM local imports should include file extension: "${importPath}" → "${importPath}.js"`);
+        }
+      }
+
+      if (importPath.includes('../../..')) {
+        issues.push(`Line ${i + 1}: Deep relative import "${importPath}" — consider using path aliases`);
+      }
+    }
+
+    return { valid: issues.length === 0, issues, suggestions };
+  }
+}

package/LeeWay-Standards/src/agents/integrity/module-policy-agent.js

@@ -0,0 +1,94 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.MODULE.POLICY
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=layers
+
+5WH:
+WHAT = Module policy agent — prevents CommonJS/ESM drift within a project
+WHY = Mixed module systems cause runtime errors that are extremely hard to debug
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/module-policy-agent.js
+WHEN = 2026
+HOW = Reads package.json type field and validates all files follow the declared module system
+
+AGENTS:
+MODULE
+IMPORT
+SYNTAX
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+
+/**
+ * ModulePolicyAgent prevents CommonJS/ESM drift in a project.
+ */
+export class ModulePolicyAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.declaredType = null;
+  }
+
+  async _getModuleType() {
+    if (this.declaredType) return this.declaredType;
+    try {
+      const raw = await readFile(join(this.rootDir, 'package.json'), 'utf8');
+      const pkg = JSON.parse(raw);
+      this.declaredType = pkg.type || 'commonjs';
+    } catch {
+      this.declaredType = 'commonjs';
+    }
+    return this.declaredType;
+  }
+
+  /**
+   * Check a file for module type consistency.
+   *
+   * @param {string} filePath
+   * @returns {Promise<{ valid: boolean, issues: string[] }>}
+   */
+  async checkFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    const ext = extname(filePath);
+
+    if (ext === '.mjs') return { valid: true, issues: [], moduleType: 'esm', forced: true };
+    if (ext === '.cjs') return { valid: true, issues: [], moduleType: 'commonjs', forced: true };
+
+    const declaredType = await this._getModuleType();
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { valid: false, issues: ['Cannot read file'] };
+    }
+
+    const issues = [];
+    const hasEsmImport = /^\s*import\s+/m.test(content) || /^\s*export\s+/m.test(content);
+    const hasCjsRequire = /\brequire\s*\(/.test(content);
+    const hasCjsExport = /\bmodule\.exports\b/.test(content);
+
+    if (declaredType === 'module') {
+      if (hasCjsRequire) issues.push('require() found in ESM project — use import instead');
+      if (hasCjsExport) issues.push('module.exports found in ESM project — use export instead');
+    } else {
+      if (hasEsmImport && !hasCjsRequire) {
+        issues.push('ESM import/export found in CommonJS project — add "type":"module" to package.json or use .mjs extension');
+      }
+    }
+
+    return { valid: issues.length === 0, issues, moduleType: declaredType };
+  }
+}

package/LeeWay-Standards/src/agents/integrity/refactor-scan-agent.js

@@ -0,0 +1,113 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.REFACTOR.SCAN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=wand-2
+
+5WH:
+WHAT = Refactor scan agent — suggests safe structural improvements to code
+WHY = Continuous refactoring suggestions keep the codebase clean and maintainable
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/refactor-scan-agent.js
+WHEN = 2026
+HOW = Pattern-based heuristics detect long functions, deep nesting, and complex conditionals
+
+AGENTS:
+REFACTOR
+SYNTAX
+DUPLICATE
+
+LICENSE:
+MIT
+*/
+
+/**
+ * RefactorScanAgent suggests safe structural improvements.
+ */
+export class RefactorScanAgent {
+  constructor(options = {}) {
+    this.maxFunctionLines = options.maxFunctionLines || 50;
+    this.maxNestingDepth = options.maxNestingDepth || 4;
+  }
+
+  /**
+   * Scan file content for refactoring opportunities.
+   *
+   * @param {string} content
+   * @param {{ filePath?: string }} [options]
+   * @returns {{ suggestions: Suggestion[] }}
+   */
+  scan(content, options = {}) {
+    if (!content || typeof content !== 'string') {
+      return { suggestions: [] };
+    }
+
+    const suggestions = [];
+    const lines = content.split('\n');
+
+    let functionStart = -1;
+    let functionName = '';
+    let maxDepth = 0;
+    let currentDepth = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      const fnMatch = trimmed.match(/^(?:export\s+)?(?:async\s+)?function\s+(\w+)|^(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\(/);
+      if (fnMatch && functionStart === -1) {
+        functionStart = i;
+        functionName = fnMatch[1] || fnMatch[2] || 'anonymous';
+        currentDepth = 0;
+        maxDepth = 0;
+      }
+
+      currentDepth += (line.match(/\{/g) || []).length;
+      currentDepth -= (line.match(/\}/g) || []).length;
+      if (currentDepth > maxDepth) maxDepth = currentDepth;
+
+      if (functionStart !== -1 && currentDepth <= 0 && i > functionStart) {
+        const functionLength = i - functionStart;
+        if (functionLength > this.maxFunctionLines) {
+          suggestions.push({
+            type: 'long_function',
+            line: functionStart + 1,
+            message: `Function "${functionName}" is ${functionLength} lines — consider extracting into smaller functions`,
+            severity: 'warning',
+          });
+        }
+        if (maxDepth > this.maxNestingDepth) {
+          suggestions.push({
+            type: 'deep_nesting',
+            line: functionStart + 1,
+            message: `Function "${functionName}" has nesting depth of ${maxDepth} — flatten with early returns or extracted functions`,
+            severity: 'warning',
+          });
+        }
+        functionStart = -1;
+        maxDepth = 0;
+      }
+
+      if (/TODO|FIXME|HACK|XXX/.test(trimmed)) {
+        const match = trimmed.match(/(TODO|FIXME|HACK|XXX)[:\s]+(.+)/);
+        suggestions.push({
+          type: 'todo',
+          line: i + 1,
+          message: `Unresolved ${match?.[1] || 'TODO'}: ${match?.[2]?.slice(0, 60) || trimmed}`,
+          severity: 'info',
+        });
+      }
+    }
+
+    return { suggestions };
+  }
+}

package/LeeWay-Standards/src/agents/integrity/syntax-agent.js

@@ -0,0 +1,84 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.INTEGRITY
+TAG: AI.AGENT.SYNTAX.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=code-2
+
+5WH:
+WHAT = Syntax agent — guards against malformed code and unsafe patch results
+WHY = Malformed syntax breaks builds; this agent catches errors before they reach CI
+WHO = Rapid Web Development
+WHERE = src/agents/integrity/syntax-agent.js
+WHEN = 2026
+HOW = Lightweight structural pattern checks for common JS/TS syntax issues
+
+AGENTS:
+SYNTAX
+IMPORT
+MODULE
+
+LICENSE:
+MIT
+*/
+
+/**
+ * SyntaxAgent performs lightweight structural syntax validation.
+ */
+export class SyntaxAgent {
+  /**
+   * Check JS/TS content for common syntax issues.
+   *
+   * @param {string} content
+   * @param {{ filePath?: string }} [options]
+   * @returns {{ valid: boolean, issues: string[] }}
+   */
+  check(content, options = {}) {
+    if (!content || typeof content !== 'string') {
+      return { valid: false, issues: ['Empty or invalid content'] };
+    }
+
+    const issues = [];
+    const lines = content.split('\n');
+
+    const openBraces = (content.match(/\{/g) || []).length;
+    const closeBraces = (content.match(/\}/g) || []).length;
+    if (openBraces !== closeBraces) {
+      issues.push(`Unbalanced braces: ${openBraces} opening, ${closeBraces} closing`);
+    }
+
+    const openParens = (content.match(/\(/g) || []).length;
+    const closeParens = (content.match(/\)/g) || []).length;
+    if (openParens !== closeParens) {
+      issues.push(`Unbalanced parentheses: ${openParens} opening, ${closeParens} closing`);
+    }
+
+    const openBrackets = (content.match(/\[/g) || []).length;
+    const closeBrackets = (content.match(/\]/g) || []).length;
+    if (openBrackets !== closeBrackets) {
+      issues.push(`Unbalanced brackets: ${openBrackets} opening, ${closeBrackets} closing`);
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.includes('<<<<<<< ') || line.includes('=======') || line.includes('>>>>>>> ')) {
+        issues.push(`Unresolved git merge conflict at line ${i + 1}`);
+      }
+    }
+
+    const consoleLogs = lines.filter(l => l.trim().startsWith('console.log(')).length;
+    if (consoleLogs > 10) {
+      issues.push(`Excessive console.log usage (${consoleLogs} occurrences) — use namespaced logging`);
+    }
+
+    return { valid: issues.length === 0, issues };
+  }
+}