@devmedic/issue-engine

Centralizes issue handling. Rules shouldn't hand back whatever ad hoc shape they feel like — every issue, from every rule, from every plugin, passes through this one engine and comes out the other side normalized the same way. No report generation, no UI, no React Native rules live here.

Rule Engine (@devmedic/rule-engine)
   │  Issue[]  (raw: per-rule, per-file, this run only)
   ▼
Issue Engine (this package)
   │  NormalizedIssue[]  (canonical: stable id, full location, deduplicated
   │                       across runs, sortable, filterable, serializable)
   ▼
a future Report Engine

Basic usage

import { RuleEngine } from '@devmedic/rule-engine';
import { IssueEngine } from '@devmedic/issue-engine';

const ruleEngine = new RuleEngine();
await ruleEngine.loadRulesFrom('devmedic-plugin-security');
const { issues } = await ruleEngine.analyze(['src/a.ts', 'src/b.ts']);

const issueEngine = new IssueEngine();
issueEngine.ingest(issues); // normalizes + deduplicates against anything already ingested

issueEngine.getIssues(); // sorted by severity, then file, then position
issueEngine.getIssues({ filter: { minSeverity: 'error', onlyFixable: true } });
issueEngine.groupBy('filePath'); // also: 'ruleId' | 'severity' | 'category'

const json = issueEngine.serialize();
const restored = IssueEngine.deserialize(json); // e.g. a later CLI run picking up a prior scan's output

ingest() accepts a plain Rule Engine Issue as-is — every extra field below is optional, so nothing about the Rule Engine had to change for this package to exist.

Responsibilities

| Responsibility | How | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issue IDs | A stable, content-derived id (ruleId + filePath + line + column + message, hashed). The same finding gets the same id whether it was seen this run or a previous one — that's what makes deduplication and cross-run tracking possible. | | Severity | Reuses @devmedic/rule-engine's Severity; adds a rank (SEVERITY_RANK) for sorting/filtering, since the Rule Engine has no reason to care about ordering. | | Location | { filePath, start: { line, column }, end: { line, column } } — end defaults to start when a rule only reported a single point, so every normalized issue has a complete range. | | Quick Fix support | quickFix: { available, edits? }. available comes straight from the Rule Engine's canFix; edits is carried through if a caller already computed them (e.g. by calling a Rule's fix() itself) — this engine never computes a fix. | | Suggestions | An optional suggestions: string[] a caller can attach per issue; deduplicated on normalization, and merged (not dropped) when two duplicate issues each carry different suggestions. | | Documentation links | An optional documentationUrl, carried through as-is — never fabricated when absent. | | Deduplication | Issues sharing the same id collapse into one, across a single ingest() call and across separate calls to it (an IssueEngine accumulates). | | Issue grouping | groupBy('filePath' \| 'ruleId' \| 'severity' \| 'category'). | | Sorting | Most severe first, then file path, then position — overridable with any custom comparator. | | Filtering | By minimum severity, category, rule id, file path, or fixability — combinable, AND semantics. | | Serialization | serialize()/IssueEngine.deserialize() — a versioned JSON envelope ({ schemaVersion, generatedAt, issues, cloudSync? }), validated with Zod on the way back in. | | Version compatibility | schemaVersion is checked on deserialize; a major-version mismatch throws VersionCompatibilityError rather than silently misreading an incompatible shape. | | Future cloud synchronization | cloudSync?: { lastSyncedAt?, remoteId? } is part of the schema now so a serialized issue set written today won't need to change shape once cloud sync ships — reserved, inert, nothing reads or writes it yet. |

Depends on

• @devmedic/rule-engine — the source of Issue, Severity, RuleCategory, RuleFixEdit
• zod
• semver