@decentrys/ui-sdk 0.1.0

package/src/presentation.test.ts

@@ -0,0 +1,521 @@
+/**
+ * These tests target the mapping, not the markup.
+ *
+ * A snapshot of rendered HTML would pass just as happily with a fact painted
+ * in critical red, because a snapshot only asserts that nothing changed — not
+ * that what is there is right. Every assertion below is about a decision that,
+ * if made the other way, would break the rule the whole product rests on while
+ * leaving every classifier test green.
+ *
+ * All fixtures here are clearly-labelled examples, constructed in the test
+ * file. Nothing in the package itself ships example data.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  HISTORY_STATUS_MEANING, RISK_LEVEL_MEANING, RISK_LEVELS, unavailableAssessment,
+  type Assessment, type Evidence, type ObservedFact, type RiskLevel, type SignalStatus,
+  type TechnicalCapability, type ThreatSignal, type UnknownField,
+} from '@decentrys/protect';
+import { DEFAULT_COPY } from './copy';
+import {
+  MIN_RAISING_CONFIDENCE, RISK_LEVEL_LABEL, approvalPresentation, assessmentSections,
+  availabilityPresentation, capabilityPresentation, componentRows, decisionPresentation,
+  factPresentation, formatConfidence, formatTimestamp, formatTokenAmount, historyPresentation,
+  hopPresentation, isUnlimitedAllowance, kindPresentation, levelPresentation, shortenAddress,
+  signalPresentation, unknownPresentation,
+} from './presentation';
+
+// ---------------------------------------------------------------------------
+// Example fixtures — illustrative data for the tests only.
+// ---------------------------------------------------------------------------
+
+const EXAMPLE_EVIDENCE = (analystVerified: boolean): Evidence => ({
+  id: 'ev_example_1',
+  type: 'BYTECODE_MATCH',
+  source: 'Decentrys',
+  observedAt: '2026-09-05T18:22:04.000Z',
+  confidence: 0.99,
+  analystVerified,
+});
+
+const EXAMPLE_SIGNAL = (overrides: Partial<ThreatSignal> = {}): ThreatSignal => ({
+  type: 'KNOWN_DRAINER_BYTECODE',
+  severity: 'CRITICAL',
+  confidence: 0.99,
+  explanation: 'Bytecode matches a confirmed drainer family.',
+  hops: 0,
+  evidence: [EXAMPLE_EVIDENCE(true)],
+  status: 'ACTIVE',
+  createdAt: '2026-09-01T00:00:00.000Z',
+  lastSeen: '2026-09-05T00:00:00.000Z',
+  ...overrides,
+});
+
+const EXAMPLE_FACT: ObservedFact = {
+  type: 'CONTRACT_AGE_HOURS',
+  value: 72,
+  statement: 'Deployed 3 days ago.',
+  source: 'chain',
+  observedAt: '2026-09-05T12:00:00.000Z',
+};
+
+const EXAMPLE_CAPABILITY = (
+  severity: TechnicalCapability['severity'],
+): TechnicalCapability => ({
+  type: 'MINT_AUTHORITY_ACTIVE',
+  severity,
+  statement: 'The owner can mint additional supply.',
+  grantedBy: 'mint(address,uint256)',
+});
+
+const EXAMPLE_UNKNOWN: UnknownField = {
+  field: 'sourceCode',
+  reason: 'UNKNOWN',
+  statement: 'Whether source code is published is not known.',
+};
+
+const EXAMPLE_ASSESSMENT = (overrides: Partial<Assessment> = {}): Assessment => ({
+  riskLevel: 'INFORMATIONAL',
+  confirmedMalicious: false,
+  confidence: 0.5,
+  historyStatus: 'LIMITED',
+  facts: [EXAMPLE_FACT],
+  capabilities: [EXAMPLE_CAPABILITY('INFO')],
+  threatSignals: [],
+  unknowns: [EXAMPLE_UNKNOWN],
+  components: {
+    technicalRisk: 4, behavioralRisk: 0, threatIntelligenceRisk: 0, historyConfidence: 25,
+  },
+  explanation: ['The owner can mint additional supply.'],
+  modelVersion: 'protect-1.0.0',
+  assessedAt: '2026-09-06T00:00:00.000Z',
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+
+describe('risk level presentation', () => {
+  it('uses the exact labels already published to customers', () => {
+    expect(RISK_LEVEL_LABEL).toEqual({
+      NO_CRITICAL_RISK_DETECTED: 'No critical risk detected',
+      INFORMATIONAL: 'Informational',
+      CAUTION: 'Caution',
+      ELEVATED_RISK: 'Elevated risk',
+      HIGH_RISK: 'High risk',
+      CRITICAL_THREAT: 'Critical threat',
+      KNOWN_MALICIOUS: 'Known malicious',
+    });
+  });
+
+  it('never invents a meaning — it renders the model’s own words', () => {
+    for (const level of RISK_LEVELS) {
+      expect(levelPresentation(level).meaning).toBe(RISK_LEVEL_MEANING[level]);
+    }
+  });
+
+  it('gives the two non-danger levels a non-warning tone', () => {
+    // Nothing at these levels indicates danger, and a new project landing on
+    // INFORMATIONAL is the common case, not an exception.
+    expect(levelPresentation('NO_CRITICAL_RISK_DETECTED').tone).toBe('neutral');
+    expect(levelPresentation('INFORMATIONAL').tone).toBe('info');
+    for (const level of ['NO_CRITICAL_RISK_DETECTED', 'INFORMATIONAL'] as RiskLevel[]) {
+      expect(levelPresentation(level).evidenceBacked).toBe(false);
+      expect(levelPresentation(level).liveRegionRole).toBe('status');
+    }
+  });
+
+  it('interrupts a screen reader only from ELEVATED_RISK upward', () => {
+    expect(levelPresentation('CAUTION').liveRegionRole).toBe('status');
+    for (const level of ['ELEVATED_RISK', 'HIGH_RISK', 'CRITICAL_THREAT', 'KNOWN_MALICIOUS'] as RiskLevel[]) {
+      expect(levelPresentation(level).liveRegionRole).toBe('alert');
+      expect(levelPresentation(level).evidenceBacked).toBe(true);
+    }
+  });
+
+  it('marks only KNOWN_MALICIOUS as accusatory', () => {
+    const accusatory = RISK_LEVELS.filter((level) => levelPresentation(level).accusatory);
+    expect(accusatory).toEqual(['KNOWN_MALICIOUS']);
+  });
+
+  it('gives every level a distinct glyph, so colour is never the only carrier', () => {
+    const glyphs = RISK_LEVELS.map((level) => levelPresentation(level).glyph);
+    expect(new Set(glyphs).size).toBe(RISK_LEVELS.length);
+  });
+
+  it('lets an integrator relabel a level without touching its meaning', () => {
+    const p = levelPresentation('CAUTION', { labels: { CAUTION: 'Achtung' } });
+    expect(p.label).toBe('Achtung');
+    expect(p.meaning).toBe(RISK_LEVEL_MEANING.CAUTION);
+  });
+
+  it('puts the meaning into the accessible name, not just the label', () => {
+    expect(levelPresentation('INFORMATIONAL').ariaLabel).toContain(RISK_LEVEL_MEANING.INFORMATIONAL);
+  });
+});
+
+describe('history presentation', () => {
+  it('is neutral for every status, including LIMITED and NONE', () => {
+    for (const status of ['ESTABLISHED', 'MODERATE', 'LIMITED', 'NONE'] as const) {
+      const h = historyPresentation(status);
+      expect(h.tone).toBe('neutral');
+      expect(h.isWarning).toBe(false);
+    }
+  });
+
+  it('gives LIMITED exactly the same tone as ESTABLISHED', () => {
+    // The failure this guards against is subtle: an amber "limited history"
+    // chip beside a green "established" one is a risk signal wearing a fact's
+    // label, and it taxes every project deployed this week.
+    expect(historyPresentation('LIMITED').tone).toBe(historyPresentation('ESTABLISHED').tone);
+  });
+
+  it('states that limited history is not a risk finding', () => {
+    expect(historyPresentation('LIMITED').statement).toBe(HISTORY_STATUS_MEANING.LIMITED);
+    expect(historyPresentation('LIMITED').statement).toContain('not a risk finding');
+    expect(historyPresentation('NONE').statement).toContain('not a risk finding');
+  });
+
+  it('labels the statuses without implying anything about the subject', () => {
+    expect(historyPresentation('LIMITED').label).toBe('Limited history');
+    expect(historyPresentation('NONE').label).toBe('No history');
+  });
+});
+
+describe('facts, capabilities and signals are visually separate species', () => {
+  it('gives a fact the fact tone, never a severity tone', () => {
+    expect(factPresentation(EXAMPLE_FACT).tone).toBe('fact');
+  });
+
+  it('keeps a capability in the capability tone at every severity', () => {
+    for (const severity of ['INFO', 'NOTABLE', 'SIGNIFICANT'] as const) {
+      const p = capabilityPresentation(EXAMPLE_CAPABILITY(severity));
+      expect(p.tone).toBe('capability');
+    }
+    // Severity is carried by weight, not by recolouring into the threat palette.
+    expect(capabilityPresentation(EXAMPLE_CAPABILITY('SIGNIFICANT')).emphasis).toBe('strong');
+    expect(capabilityPresentation(EXAMPLE_CAPABILITY('INFO')).emphasis).toBe('normal');
+  });
+
+  it('keeps an unknown in the unknown tone', () => {
+    expect(unknownPresentation(EXAMPLE_UNKNOWN).tone).toBe('unknown');
+  });
+
+  it('never puts a fact, capability or unknown on the risk tone ramp', () => {
+    const riskTones = new Set(['caution', 'elevated', 'high', 'critical']);
+    expect(riskTones.has(factPresentation(EXAMPLE_FACT).tone)).toBe(false);
+    expect(riskTones.has(capabilityPresentation(EXAMPLE_CAPABILITY('SIGNIFICANT')).tone)).toBe(false);
+    expect(riskTones.has(unknownPresentation(EXAMPLE_UNKNOWN).tone)).toBe(false);
+  });
+
+  it('gives every kind a distinct word, glyph and rule style', () => {
+    const kinds = (['fact', 'capability', 'signal', 'unknown'] as const)
+      .map((kind) => kindPresentation(kind, DEFAULT_COPY));
+    expect(new Set(kinds.map((k) => k.label)).size).toBe(4);
+    expect(new Set(kinds.map((k) => k.glyph)).size).toBe(4);
+    // Glyph and rule together separate every pair even with no colour at all.
+    expect(new Set(kinds.map((k) => `${k.glyph}|${k.rule}|${k.ruleWidth}`)).size).toBe(4);
+  });
+});
+
+describe('threat signal presentation', () => {
+  it('gives a live, confident signal its severity tone', () => {
+    const p = signalPresentation(EXAMPLE_SIGNAL(), DEFAULT_COPY);
+    expect(p.tone).toBe('critical');
+    expect(p.raising).toBe(true);
+    expect(p.inertStatement).toBeUndefined();
+  });
+
+  it('tones a stale signal as inactive and says it did not count', () => {
+    const p = signalPresentation(EXAMPLE_SIGNAL({ status: 'STALE' }), DEFAULT_COPY);
+    expect(p.tone).toBe('inactive');
+    expect(p.raising).toBe(false);
+    expect(p.inertStatement).toContain('stale');
+    expect(p.inertStatement).toContain('did not affect this assessment');
+  });
+
+  it('does not paint a low-confidence signal in the colour of one that counted', () => {
+    const p = signalPresentation(
+      EXAMPLE_SIGNAL({ confidence: 0.3 }), DEFAULT_COPY,
+    );
+    expect(p.severity).toBe('CRITICAL');
+    expect(p.tone).toBe('inactive');
+    expect(p.raising).toBe(false);
+    expect(p.inertStatement).toContain('30%');
+    expect(p.inertStatement).toContain('too low to raise the risk level');
+  });
+
+  it('treats the confidence floor as inclusive, matching the classifier', () => {
+    const at = signalPresentation(
+      EXAMPLE_SIGNAL({ confidence: MIN_RAISING_CONFIDENCE }), DEFAULT_COPY,
+    );
+    const below = signalPresentation(
+      EXAMPLE_SIGNAL({ confidence: MIN_RAISING_CONFIDENCE - 0.01 }), DEFAULT_COPY,
+    );
+    expect(at.raising).toBe(true);
+    expect(below.raising).toBe(false);
+  });
+
+  it('reports confidence as a number, never rounded away to a word', () => {
+    expect(signalPresentation(EXAMPLE_SIGNAL({ confidence: 0.62 }), DEFAULT_COPY).confidenceLabel)
+      .toBe('62%');
+  });
+
+  it('distinguishes an analyst-confirmed signal from an automated one', () => {
+    const confirmed = signalPresentation(EXAMPLE_SIGNAL(), DEFAULT_COPY);
+    const automated = signalPresentation(
+      EXAMPLE_SIGNAL({ evidence: [EXAMPLE_EVIDENCE(false)] }), DEFAULT_COPY,
+    );
+    expect(confirmed.analystConfirmed).toBe(true);
+    expect(confirmed.attribution).toBe(DEFAULT_COPY.analystConfirmed);
+    expect(automated.analystConfirmed).toBe(false);
+    expect(automated.attribution).toBe(DEFAULT_COPY.notAnalystConfirmed);
+  });
+
+  it('labels every non-active status rather than dropping the signal', () => {
+    const statuses: SignalStatus[] = ['STALE', 'RESOLVED', 'DISPUTED_FACT', 'REMOVED'];
+    for (const status of statuses) {
+      const p = signalPresentation(EXAMPLE_SIGNAL({ status }), DEFAULT_COPY);
+      expect(p.statusLabel.length).toBeGreaterThan(0);
+      expect(p.inertStatement).toBeTruthy();
+      expect(p.explanation).toBe('Bytecode matches a confirmed drainer family.');
+    }
+  });
+});
+
+describe('hop distance', () => {
+  it('describes zero hops as a direct observation', () => {
+    const h = hopPresentation(0);
+    expect(h.label).toBe('Direct');
+    expect(h.indirect).toBe(false);
+    expect(h.statement).not.toContain('inference');
+  });
+
+  it('describes one hop as an inference about a counterparty', () => {
+    const h = hopPresentation(1);
+    expect(h.label).toBe('1 hop');
+    expect(h.indirect).toBe(true);
+    expect(h.statement).toContain('inference');
+    expect(h.statement).toContain('counterparty');
+  });
+
+  it('names the distance when it is more than one', () => {
+    const h = hopPresentation(3);
+    expect(h.label).toBe('3 hops');
+    expect(h.indirect).toBe(true);
+    expect(h.statement).toContain('3 hops away');
+    expect(h.statement).toContain('3 steps removed');
+  });
+
+  it('uses the caller’s noun for the subject', () => {
+    expect(hopPresentation(2, 'token').statement).toContain('this token');
+    expect(hopPresentation(0, 'contract').statement).toBe('Observed directly on this contract.');
+  });
+
+  it('clamps a nonsensical hop count rather than rendering it', () => {
+    expect(hopPresentation(-4).label).toBe('Direct');
+    expect(hopPresentation(2.7).label).toBe('2 hops');
+  });
+
+  it('threads hop wording through the signal presentation', () => {
+    const p = signalPresentation(EXAMPLE_SIGNAL({ hops: 2 }), DEFAULT_COPY, { subjectNoun: 'token' });
+    expect(p.indirect).toBe(true);
+    expect(p.hopLabel).toBe('2 hops');
+    expect(p.hopStatement).toContain('inference about a counterparty');
+  });
+});
+
+describe('assessment sections', () => {
+  it('never lets a fact reach the signal list, or a signal reach the facts', () => {
+    const assessment = EXAMPLE_ASSESSMENT({ threatSignals: [EXAMPLE_SIGNAL()] });
+    const s = assessmentSections(assessment, DEFAULT_COPY);
+    expect(s.facts).toEqual([EXAMPLE_FACT]);
+    expect(s.activeSignals).toHaveLength(1);
+    expect(s.facts.some((f) => 'severity' in f)).toBe(false);
+    expect([...s.activeSignals, ...s.inertSignals].some((sig) => 'statement' in sig)).toBe(false);
+  });
+
+  it('reports a signal that did not count instead of hiding it', () => {
+    const assessment = EXAMPLE_ASSESSMENT({
+      threatSignals: [EXAMPLE_SIGNAL({ confidence: 0.2 }), EXAMPLE_SIGNAL({ status: 'STALE' })],
+    });
+    const s = assessmentSections(assessment, DEFAULT_COPY);
+    expect(s.activeSignals).toHaveLength(0);
+    expect(s.inertSignals).toHaveLength(2);
+    expect(s.summary).toContain('2 threat signals');
+  });
+
+  it('states emptiness rather than rendering a blank panel', () => {
+    const empty = EXAMPLE_ASSESSMENT({
+      facts: [], capabilities: [], threatSignals: [], unknowns: [],
+    });
+    const s = assessmentSections(empty, DEFAULT_COPY);
+    expect(s.isEmpty).toBe(true);
+    expect(s.emptyStatement).toContain(DEFAULT_COPY.nothingReturned);
+    expect(s.emptyStatement).toContain(DEFAULT_COPY.notAnAssurance);
+  });
+
+  it('summarises what is present, with correct plurals', () => {
+    const s = assessmentSections(EXAMPLE_ASSESSMENT(), DEFAULT_COPY);
+    expect(s.summary).toBe('1 fact · 1 capability · 1 unknown');
+    const many = assessmentSections(
+      EXAMPLE_ASSESSMENT({
+        facts: [EXAMPLE_FACT, EXAMPLE_FACT],
+        capabilities: [EXAMPLE_CAPABILITY('INFO'), EXAMPLE_CAPABILITY('NOTABLE')],
+        unknowns: [],
+      }),
+      DEFAULT_COPY,
+    );
+    expect(many.summary).toBe('2 facts · 2 capabilities');
+  });
+});
+
+describe('availability', () => {
+  it('renders our own outage neutrally, never as a finding', () => {
+    const a = availabilityPresentation(unavailableAssessment('warn', 'timeout'));
+    expect(a.unavailable).toBe(true);
+    expect(a.tone).toBe('neutral');
+    expect(a.statement).toContain('Nothing was checked');
+  });
+
+  it('reports availability as fine when no provider unknown is present', () => {
+    expect(availabilityPresentation(EXAMPLE_ASSESSMENT()).unavailable).toBe(false);
+  });
+
+  it('does not let an outage raise the level it renders', () => {
+    const assessment = unavailableAssessment('warn', 'timeout');
+    expect(levelPresentation(assessment.riskLevel).tone).toBe('neutral');
+  });
+});
+
+describe('policy decisions', () => {
+  it('never blocks the host UI, for any action including block', () => {
+    for (const action of ['allow', 'inform', 'warn', 'warn_strong', 'require_confirmation', 'block'] as const) {
+      expect(decisionPresentation({ action, reason: 'example' }).blocksUi).toBe(false);
+    }
+  });
+
+  it('attributes a block to the integrator, not to Decentrys', () => {
+    const d = decisionPresentation({ action: 'block', reason: 'example' });
+    expect(d.statement).toContain('belongs to this application');
+    expect(d.statement).toContain('Decentrys reports evidence and does not stop anything');
+  });
+});
+
+describe('score components', () => {
+  it('labels history confidence as coverage and attaches its caveat', () => {
+    const rows = componentRows(EXAMPLE_ASSESSMENT().components, DEFAULT_COPY);
+    const coverage = rows.find((r) => r.key === 'historyConfidence');
+    expect(coverage?.label).toBe('Coverage');
+    expect(coverage?.isCoverage).toBe(true);
+    expect(coverage?.caveat).toBe(DEFAULT_COPY.coverageIsNotRisk);
+    expect(rows.filter((r) => r.isCoverage)).toHaveLength(1);
+  });
+});
+
+describe('approvals', () => {
+  it('recognises the ways an unlimited allowance is expressed', () => {
+    expect(isUnlimitedAllowance('unlimited')).toBe(true);
+    expect(isUnlimitedAllowance('UNLIMITED')).toBe(true);
+    expect(isUnlimitedAllowance((2n ** 256n - 1n).toString())).toBe(true);
+    expect(isUnlimitedAllowance((2n ** 255n).toString())).toBe(true);
+    expect(isUnlimitedAllowance('1000000')).toBe(false);
+    expect(isUnlimitedAllowance('not-a-number')).toBe(false);
+  });
+
+  it('says unlimited approval requested, and does not accuse anyone', () => {
+    const p = approvalPresentation({
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      symbol: 'USDC',
+      decimals: 6,
+      spender: '0x1111111254EEB25477B68fb85Ed929f73A960582',
+      amount: 'unlimited',
+    });
+    expect(p.unlimited).toBe(true);
+    expect(p.scopeLabel).toBe('Unlimited allowance');
+    expect(p.statement).toContain('unlimited amount of your USDC');
+    expect(p.statement).toContain('until it is revoked');
+    expect(p.emphasis).toBe('strong');
+  });
+
+  it('renders an approval scope as a capability, never as a threat', () => {
+    const unlimited = approvalPresentation({
+      token: '0xtoken', spender: '0xspender', amount: 'unlimited',
+    });
+    const limited = approvalPresentation({
+      token: '0xtoken', spender: '0xspender', amount: '1000000', decimals: 6,
+    });
+    expect(unlimited.tone).toBe('capability');
+    expect(limited.tone).toBe('capability');
+  });
+
+  it('formats a bounded allowance in whole tokens when decimals are known', () => {
+    const p = approvalPresentation({
+      token: '0xtoken', symbol: 'USDC', decimals: 6, spender: '0xspender', amount: '1234500000',
+    });
+    expect(p.unlimited).toBe(false);
+    expect(p.amountLabel).toBe('1,234.5 USDC');
+    expect(p.statement).toContain('up to 1,234.5 USDC');
+  });
+
+  it('labels base units as base units rather than pretending they are tokens', () => {
+    const p = approvalPresentation({
+      token: '0xtoken', symbol: 'USDC', spender: '0xspender', amount: '1234500000',
+    });
+    expect(p.amountLabel).toBe('1,234,500,000 base units');
+    expect(p.statement).toContain('base units of USDC');
+  });
+
+  it('says plainly when the amount could not be decoded', () => {
+    const p = approvalPresentation({ token: '0xtoken', spender: '0xspender' });
+    expect(p.amountKnown).toBe(false);
+    expect(p.statement).toContain('could not be decoded');
+    expect(p.statement).toContain('is not known');
+  });
+
+  it('prefers a name the integrator already has for the spender', () => {
+    const p = approvalPresentation({
+      token: '0xtoken', spender: '0x1111111254EEB25477B68fb85Ed929f73A960582',
+      spenderLabel: 'Uniswap router', amount: 'unlimited',
+    });
+    expect(p.spenderName).toBe('Uniswap router');
+    expect(p.statement).toContain('Uniswap router');
+  });
+});
+
+describe('formatting', () => {
+  it('renders confidence as a clamped percentage', () => {
+    expect(formatConfidence(0)).toBe('0%');
+    expect(formatConfidence(0.505)).toBe('51%');
+    expect(formatConfidence(1)).toBe('100%');
+    expect(formatConfidence(1.4)).toBe('100%');
+    expect(formatConfidence(-0.2)).toBe('0%');
+  });
+
+  it('renders timestamps identically in every runtime', () => {
+    expect(formatTimestamp('2026-09-05T18:22:04.000Z')).toBe('2026-09-05 18:22 UTC');
+  });
+
+  it('passes an unparseable timestamp through rather than inventing one', () => {
+    expect(formatTimestamp('soon')).toBe('soon');
+  });
+
+  it('formats token amounts in integer arithmetic, without precision loss', () => {
+    // A double cannot hold this exactly; the point of using BigInt is that a
+    // user is never shown a rounded version of a number they would act on.
+    expect(formatTokenAmount('123456789012345678901234567890', 18))
+      .toBe('123,456,789,012.34567890123456789');
+    expect(formatTokenAmount('1000000', 6)).toBe('1');
+    expect(formatTokenAmount('1500000', 6)).toBe('1.5');
+    expect(formatTokenAmount('0', 18)).toBe('0');
+  });
+
+  it('returns an unparseable amount untouched', () => {
+    expect(formatTokenAmount('n/a', 18)).toBe('n/a');
+  });
+
+  it('shortens an address without hiding either end', () => {
+    expect(shortenAddress('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')).toBe('0xA0b8…eB48');
+    expect(shortenAddress('0xshort')).toBe('0xshort');
+  });
+});