feat(soroban): implement TTL analyzer with short-TTL detection (#885)

[Apostle-whykay]

Overview

Implements the Soroban TTL Analyzer in packages/analyzers/soroban/ttl/ and exposes it through packages/rules/soroban/ttl/. The analyzer covers every requirement in #885:

• detects TTL-related storage operations (set / extend_ttl) and the tier they target,
• identifies persistent entries written without a TTL extension,
• detects unusually short extend_to values (and threshold/extend_to pairs that can never extend anything),
• generates actionable, line-addressable findings with a concrete remediation.

Related Issue

Closes #885

Changes

packages/analyzers/soroban/ttl/ (new)

• types.ts — TtlOperation, TtlFinding, TtlAnalysisMetrics, SorobanTtlAnalysisResult, tuning options.
• ttl-analyzer.ts
  • detectTtlOperations(source) — scans for .set(...) / .extend_ttl(...) calls and classifies the receiver tier (persistent / instance / temporary).
  • analyzeShortTtlValues(source, options?) — flags extend_to below the one-day floor as high and below the 30-day recommendation as medium; flags threshold >= extend_to, non-positive thresholds and a missing extend_to as high invalid ranges. Named constants the analyzer cannot evaluate are skipped rather than guessed.
  • SorobanTtlAnalyzer.analyze() / analyzeTtl() — aggregate report that also reuses the existing storage analyzer for missing (Detect Missing Soroban TTL Extensions #886) and excessive (Detect Excessive Soroban TTL Extensions #887) extensions, so all TTL findings are available from one entry point with unified metrics.
  • Documented ledger constants: SOROBAN_LEDGER_CLOSE_SECONDS, SOROBAN_LEDGERS_PER_DAY, SOROBAN_RECOMMENDED_MIN_TTL_LEDGERS (30 days), SOROBAN_ABSOLUTE_MIN_TTL_LEDGERS (1 day).
• index.ts — public surface.

packages/rules/soroban/ttl/

• short-ttl.rule.ts (new) — SorobanShortTtlRule (soroban-short-ttl) + detectShortTtlValues.
• ttl.rule.ts (new) — SorobanTtlRule (soroban-ttl-analyzer) aggregate rule exposing analyze() warnings and getFullAnalysis(), plus detectTtlIssues().
• index.ts — exports the two new rules (already re-exported by packages/rules/soroban/src/index.ts).

Tests

• packages/analyzers/soroban/ttl/__tests__/ttl-analyzer.spec.ts — literal parsing, operation/tier detection, loop detection, short-TTL severity, ineffective/inverted ranges, missing extend_to, named-constant skipping, custom thresholds, aggregate metrics, comment/string masking, healthy contract.
• packages/rules/soroban/ttl/__tests__/ttl-rule.spec.ts — rule ids, warning shape (line, key, severity, suggestion), aggregate finding kinds and getFullAnalysis.

Verification

• Ran the two new spec files with a Jest-compatible runner against the analyzer/rules code plus the real ../common/source-utils and ../storage/ttl-analyzer modules: 28 tests passed (28) across 2 files.
• tsc --noEmit --strict passes on the new analyzer/rule modules.
• Could not run the full GasGuard Jest suite (no local checkout / monorepo install); the numbers above were produced by running the new specs in isolation against a faithful copy of the repository modules. Static reasoning was used for the integration points (index.ts re-exports).

[drips-wave]

@Apostle-whykay Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits