Merge pull request #568 from Maryermarh/feat/soroban-metrics-fingerprinting-presets-functions

feat: implement Soroban metrics, fingerprinting, analysis presets, and function inventory

Author: mijinummi

src/fingerprinting/stellar/index.ts

@@ -0,0 +1,2 @@
+export { SorobanContractFingerprinter } from './soroban-contract-fingerprinter';
+export type { ContractFingerprint, DuplicateMatch, FingerprintReport } from './types';

src/fingerprinting/stellar/soroban-contract-fingerprinter.spec.ts

@@ -0,0 +1,80 @@
+import { SorobanContractFingerprinter } from './soroban-contract-fingerprinter';
+
+const CONTRACT_A = `
+impl TokenContract {
+  pub fn new(env: Env) -> Self { Self {} }
+  pub fn transfer(env: Env, from: Address, to: Address, amount: i128) {}
+  fn validate(amount: i128) -> bool { amount > 0 }
+}
+`;
+
+const CONTRACT_B = `
+impl TokenContract {
+  pub fn new(env: Env) -> Self { Self {} }
+  pub fn transfer(env: Env, from: Address, to: Address, amount: i128) {}
+  fn validate(amount: i128) -> bool { amount > 0 }
+}
+`;
+
+const CONTRACT_C = `
+impl StakingContract {
+  pub fn stake(env: Env, amount: i128) {}
+}
+`;
+
+describe('SorobanContractFingerprinter', () => {
+  let fingerprinter: SorobanContractFingerprinter;
+
+  beforeEach(() => {
+    fingerprinter = new SorobanContractFingerprinter();
+  });
+
+  describe('fingerprint', () => {
+    it('should generate a fingerprint with expected fields', () => {
+      const fp = fingerprinter.fingerprint(CONTRACT_A, 'contracts/token.rs');
+      expect(fp.fingerprint).toBeTruthy();
+      expect(fp.structuralHash).toBeTruthy();
+      expect(fp.contractName).toBe('TokenContract');
+      expect(fp.functionCount).toBeGreaterThan(0);
+    });
+
+    it('should produce the same fingerprint for identical sources', () => {
+      const fp1 = fingerprinter.fingerprint(CONTRACT_A, 'a.rs');
+      const fp2 = fingerprinter.fingerprint(CONTRACT_B, 'b.rs');
+      expect(fp1.fingerprint).toBe(fp2.fingerprint);
+    });
+
+    it('should produce different fingerprints for different sources', () => {
+      const fp1 = fingerprinter.fingerprint(CONTRACT_A, 'a.rs');
+      const fp2 = fingerprinter.fingerprint(CONTRACT_C, 'c.rs');
+      expect(fp1.fingerprint).not.toBe(fp2.fingerprint);
+    });
+  });
+
+  describe('detectDuplicates', () => {
+    it('should detect exact duplicates', () => {
+      fingerprinter.fingerprint(CONTRACT_A, 'a.rs');
+      fingerprinter.fingerprint(CONTRACT_B, 'b.rs');
+      const duplicates = fingerprinter.detectDuplicates();
+      expect(duplicates).toHaveLength(1);
+      expect(duplicates[0].similarity).toBe('exact');
+    });
+
+    it('should return no duplicates for unique contracts', () => {
+      fingerprinter.fingerprint(CONTRACT_A, 'a.rs');
+      fingerprinter.fingerprint(CONTRACT_C, 'c.rs');
+      expect(fingerprinter.detectDuplicates()).toHaveLength(0);
+    });
+  });
+
+  describe('generateReport', () => {
+    it('should report duplicate and unique counts', () => {
+      fingerprinter.fingerprint(CONTRACT_A, 'a.rs');
+      fingerprinter.fingerprint(CONTRACT_B, 'b.rs');
+      fingerprinter.fingerprint(CONTRACT_C, 'c.rs');
+      const report = fingerprinter.generateReport();
+      expect(report.duplicateCount).toBe(1);
+      expect(report.uniqueCount).toBe(2);
+    });
+  });
+});

src/fingerprinting/stellar/soroban-contract-fingerprinter.ts

@@ -0,0 +1,85 @@
+import { createHash } from 'crypto';
+import { ContractFingerprint, DuplicateMatch, FingerprintReport } from './types';
+
+export class SorobanContractFingerprinter {
+  private registry: Map<string, ContractFingerprint> = new Map();
+
+  fingerprint(source: string, filePath: string): ContractFingerprint {
+    const contractName = this.extractContractName(source);
+    const normalized = this.normalizeSource(source);
+    const fingerprint = this.hash(normalized);
+    const structuralHash = this.hash(this.extractStructure(source));
+    const functionCount = (source.match(/\bfn\s+\w+/g) ?? []).length;
+
+    const entry: ContractFingerprint = {
+      contractName,
+      filePath,
+      fingerprint,
+      structuralHash,
+      functionCount,
+      sourceLength: source.length,
+      createdAt: new Date(),
+    };
+
+    this.registry.set(filePath, entry);
+    return entry;
+  }
+
+  detectDuplicates(): DuplicateMatch[] {
+    const entries = Array.from(this.registry.values());
+    const duplicates: DuplicateMatch[] = [];
+
+    for (let i = 0; i < entries.length; i++) {
+      for (let j = i + 1; j < entries.length; j++) {
+        const a = entries[i];
+        const b = entries[j];
+        if (a.fingerprint === b.fingerprint) {
+          duplicates.push({ original: a, duplicate: b, similarity: 'exact' });
+        } else if (a.structuralHash === b.structuralHash) {
+          duplicates.push({ original: a, duplicate: b, similarity: 'structural' });
+        }
+      }
+    }
+
+    return duplicates;
+  }
+
+  generateReport(): FingerprintReport {
+    const fingerprints = Array.from(this.registry.values());
+    const duplicates = this.detectDuplicates();
+    const duplicateFiles = new Set(duplicates.map((d) => d.duplicate.filePath));
+
+    return {
+      fingerprints,
+      duplicates,
+      uniqueCount: fingerprints.filter((f) => !duplicateFiles.has(f.filePath)).length,
+      duplicateCount: duplicateFiles.size,
+      generatedAt: new Date(),
+    };
+  }
+
+  clear(): void {
+    this.registry.clear();
+  }
+
+  private hash(input: string): string {
+    return createHash('sha256').update(input).digest('hex');
+  }
+
+  private normalizeSource(source: string): string {
+    return source.replace(/\/\/[^\n]*/g, '').replace(/\s+/g, ' ').trim();
+  }
+
+  private extractStructure(source: string): string {
+    // Keep only fn signatures and struct/impl declarations for structural comparison
+    return source
+      .split('\n')
+      .filter((l) => /^\s*(pub\s+)?(?:fn|struct|impl|trait|enum)\s/.test(l))
+      .join('\n');
+  }
+
+  private extractContractName(source: string): string {
+    const match = source.match(/(?:impl|struct)\s+(\w+)/);
+    return match?.[1] ?? 'UnknownContract';
+  }
+}

src/fingerprinting/stellar/types.ts

@@ -0,0 +1,23 @@
+export interface ContractFingerprint {
+  contractName: string;
+  filePath: string;
+  fingerprint: string;
+  structuralHash: string;
+  functionCount: number;
+  sourceLength: number;
+  createdAt: Date;
+}
+
+export interface DuplicateMatch {
+  original: ContractFingerprint;
+  duplicate: ContractFingerprint;
+  similarity: 'exact' | 'structural';
+}
+
+export interface FingerprintReport {
+  fingerprints: ContractFingerprint[];
+  duplicates: DuplicateMatch[];
+  uniqueCount: number;
+  duplicateCount: number;
+  generatedAt: Date;
+}

src/metrics/rules/stellar/index.ts

@@ -0,0 +1,2 @@
+export { SorobanRuleMetricsCollector } from './soroban-rule-metrics-collector';
+export type { SorobanRuleMetric, SorobanMetricsReport, SorobanMetricsConfig } from './types';

src/metrics/rules/stellar/soroban-rule-metrics-collector.spec.ts

@@ -0,0 +1,61 @@
+import { SorobanRuleMetricsCollector } from './soroban-rule-metrics-collector';
+
+describe('SorobanRuleMetricsCollector', () => {
+  let collector: SorobanRuleMetricsCollector;
+
+  beforeEach(() => {
+    collector = new SorobanRuleMetricsCollector();
+  });
+
+  describe('record', () => {
+    it('should record a new rule metric', () => {
+      collector.record('soroban-storage', 50);
+      const metric = collector.getMetric('soroban-storage');
+      expect(metric).toBeDefined();
+      expect(metric!.invocations).toBe(1);
+      expect(metric!.avgDurationMs).toBe(50);
+    });
+
+    it('should accumulate invocations and recalculate averages', () => {
+      collector.record('rule-a', 100);
+      collector.record('rule-a', 200);
+      const metric = collector.getMetric('rule-a');
+      expect(metric!.invocations).toBe(2);
+      expect(metric!.totalDurationMs).toBe(300);
+      expect(metric!.avgDurationMs).toBe(150);
+      expect(metric!.minDurationMs).toBe(100);
+      expect(metric!.maxDurationMs).toBe(200);
+    });
+
+    it('should track errors', () => {
+      collector.record('rule-b', 10, true);
+      expect(collector.getMetric('rule-b')!.errorCount).toBe(1);
+    });
+  });
+
+  describe('getReport', () => {
+    it('should return a report with correct totals', () => {
+      collector.record('rule-a', 100);
+      collector.record('rule-b', 200);
+      const report = collector.getReport();
+      expect(report.totalRules).toBe(2);
+      expect(report.totalInvocations).toBe(2);
+      expect(report.totalDurationMs).toBe(300);
+    });
+
+    it('should list slowest rules first', () => {
+      collector.record('slow', 500);
+      collector.record('fast', 10);
+      const report = collector.getReport();
+      expect(report.slowestRules[0].ruleId).toBe('slow');
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all metrics', () => {
+      collector.record('rule-a', 50);
+      collector.reset();
+      expect(collector.getAllMetrics()).toHaveLength(0);
+    });
+  });
+});

src/metrics/rules/stellar/soroban-rule-metrics-collector.ts

@@ -0,0 +1,76 @@
+import { SorobanRuleMetric, SorobanMetricsConfig, SorobanMetricsReport } from './types';
+
+const DEFAULT_CONFIG: Required<SorobanMetricsConfig> = {
+  slowThresholdMs: 100,
+  topN: 10,
+};
+
+export class SorobanRuleMetricsCollector {
+  private metrics: Map<string, SorobanRuleMetric> = new Map();
+  private config: Required<SorobanMetricsConfig>;
+
+  constructor(config?: Partial<SorobanMetricsConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  record(ruleId: string, durationMs: number, error = false): void {
+    const existing = this.metrics.get(ruleId);
+    if (!existing) {
+      this.metrics.set(ruleId, {
+        ruleId,
+        invocations: 1,
+        totalDurationMs: durationMs,
+        minDurationMs: durationMs,
+        maxDurationMs: durationMs,
+        avgDurationMs: durationMs,
+        errorCount: error ? 1 : 0,
+        lastExecutedAt: new Date(),
+      });
+      return;
+    }
+    const invocations = existing.invocations + 1;
+    const totalDurationMs = existing.totalDurationMs + durationMs;
+    this.metrics.set(ruleId, {
+      ruleId,
+      invocations,
+      totalDurationMs,
+      minDurationMs: Math.min(existing.minDurationMs, durationMs),
+      maxDurationMs: Math.max(existing.maxDurationMs, durationMs),
+      avgDurationMs: totalDurationMs / invocations,
+      errorCount: existing.errorCount + (error ? 1 : 0),
+      lastExecutedAt: new Date(),
+    });
+  }
+
+  getMetric(ruleId: string): SorobanRuleMetric | undefined {
+    return this.metrics.get(ruleId);
+  }
+
+  getAllMetrics(): SorobanRuleMetric[] {
+    return Array.from(this.metrics.values());
+  }
+
+  getReport(): SorobanMetricsReport {
+    const all = this.getAllMetrics();
+    const totalInvocations = all.reduce((s, m) => s + m.invocations, 0);
+    const totalDurationMs = all.reduce((s, m) => s + m.totalDurationMs, 0);
+    return {
+      totalRules: all.length,
+      totalInvocations,
+      totalDurationMs,
+      avgDurationMs: all.length > 0 ? totalDurationMs / all.length : 0,
+      slowestRules: [...all]
+        .sort((a, b) => b.avgDurationMs - a.avgDurationMs)
+        .slice(0, this.config.topN),
+      mostInvokedRules: [...all]
+        .sort((a, b) => b.invocations - a.invocations)
+        .slice(0, this.config.topN),
+      metrics: all,
+      generatedAt: new Date(),
+    };
+  }
+
+  reset(): void {
+    this.metrics.clear();
+  }
+}

src/metrics/rules/stellar/types.ts

@@ -0,0 +1,26 @@
+export interface SorobanRuleMetric {
+  ruleId: string;
+  invocations: number;
+  totalDurationMs: number;
+  minDurationMs: number;
+  maxDurationMs: number;
+  avgDurationMs: number;
+  errorCount: number;
+  lastExecutedAt: Date;
+}
+
+export interface SorobanMetricsReport {
+  totalRules: number;
+  totalInvocations: number;
+  totalDurationMs: number;
+  avgDurationMs: number;
+  slowestRules: SorobanRuleMetric[];
+  mostInvokedRules: SorobanRuleMetric[];
+  metrics: SorobanRuleMetric[];
+  generatedAt: Date;
+}
+
+export interface SorobanMetricsConfig {
+  slowThresholdMs: number;
+  topN: number;
+}

src/profiles/stellar/index.ts

@@ -0,0 +1,2 @@
+export { SorobanAnalysisPresets } from './soroban-analysis-presets';
+export type { AnalysisPreset, PresetName, PresetResult } from './types';