@trailmark/core 0.1.0

package/src/diff.ts

@@ -0,0 +1,150 @@
+import {
+  BaselineEntry,
+  BaselineFile,
+  DiffOptions,
+  DiffResult,
+  TrailmarkFinding,
+  TrailmarkRun,
+} from "./types"
+import { scopedIssueKey, scopeKeyFromBaselineEntry, scopeKeyFromMeta } from "./scope"
+import { impactKey } from "./impact"
+
+function dedupeFindings(findings: TrailmarkFinding[]): TrailmarkFinding[] {
+  const unique = new Map<string, TrailmarkFinding>()
+  for (const finding of findings) {
+    const key = scopedIssueKey(finding.issueId, scopeKeyFromMeta(finding.meta))
+    if (!unique.has(key)) {
+      unique.set(key, finding)
+    }
+  }
+
+  return Array.from(unique.entries())
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([, finding]) => finding)
+}
+
+function makeRelaxedMap(baselineEntries: BaselineEntry[]): Map<string, BaselineEntry[]> {
+  const map = new Map<string, BaselineEntry[]>()
+  for (const entry of baselineEntries) {
+    const key = scopedIssueKey(entry.relaxedIssueId, scopeKeyFromBaselineEntry(entry))
+    const list = map.get(key) ?? []
+    list.push(entry)
+    map.set(key, list)
+  }
+  return map
+}
+
+function makeExactKey(entry: BaselineEntry): string {
+  return scopedIssueKey(entry.issueId, scopeKeyFromBaselineEntry(entry))
+}
+
+function pickUnmatched(
+  list: BaselineEntry[] | undefined,
+  matchedBaselineIds: Set<string>,
+): BaselineEntry | undefined {
+  if (!list || list.length === 0) {
+    return undefined
+  }
+
+  return list.find((entry) => !matchedBaselineIds.has(makeExactKey(entry)))
+}
+
+export function diffRuns(
+  baseline: BaselineFile,
+  current: TrailmarkRun,
+  options: DiffOptions = {},
+): DiffResult {
+  const debug = options.onDebug
+  const failOnImpact = new Set(
+    (options.failOnImpact ?? ["serious", "critical"]).map((value) => value.toLowerCase()),
+  )
+  const baselineEntries = Object.values(baseline.findings)
+  const baselineByIssueId = new Map(baselineEntries.map((entry) => [makeExactKey(entry), entry]))
+  const baselineByRelaxed = makeRelaxedMap(baselineEntries)
+
+  const newFindings: TrailmarkFinding[] = []
+  const existing: DiffResult["existing"] = []
+  const matchedBaselineIds = new Set<string>()
+
+  for (const finding of dedupeFindings(current.findings)) {
+    const scopeKey = scopeKeyFromMeta(finding.meta)
+    const scopedFindingIssueKey = scopedIssueKey(finding.issueId, scopeKey)
+    const exact = baselineByIssueId.get(scopedFindingIssueKey)
+
+    if (exact) {
+      const baselineKey = makeExactKey(exact)
+      existing.push({
+        finding,
+        matchedBy: "exact",
+        baselineIssueId: exact.issueId,
+        baselineScopeKey: scopeKeyFromBaselineEntry(exact),
+      })
+      matchedBaselineIds.add(baselineKey)
+      debug?.("exact-match", {
+        findingIssueId: finding.issueId,
+        findingScopeKey: scopeKey,
+        baselineIssueId: exact.issueId,
+        baselineScopeKey: scopeKeyFromBaselineEntry(exact),
+      })
+      continue
+    }
+
+    const relaxedMatches = baselineByRelaxed.get(scopedIssueKey(finding.relaxedIssueId, scopeKey))
+    const relaxed = pickUnmatched(relaxedMatches, matchedBaselineIds)
+
+    if (relaxed) {
+      const baselineKey = makeExactKey(relaxed)
+      existing.push({
+        finding,
+        matchedBy: "relaxed",
+        baselineIssueId: relaxed.issueId,
+        baselineScopeKey: scopeKeyFromBaselineEntry(relaxed),
+      })
+      matchedBaselineIds.add(baselineKey)
+      debug?.("relaxed-match", {
+        findingIssueId: finding.issueId,
+        findingScopeKey: scopeKey,
+        baselineIssueId: relaxed.issueId,
+        baselineScopeKey: scopeKeyFromBaselineEntry(relaxed),
+      })
+      continue
+    }
+
+    newFindings.push(finding)
+    debug?.("new-finding", {
+      findingIssueId: finding.issueId,
+      findingScopeKey: scopeKey,
+    })
+  }
+
+  const resolved = baselineEntries.filter((entry) => !matchedBaselineIds.has(makeExactKey(entry)))
+  for (const entry of resolved) {
+    debug?.("resolved-finding", {
+      baselineIssueId: entry.issueId,
+      baselineScopeKey: scopeKeyFromBaselineEntry(entry),
+    })
+  }
+
+  const newByImpact: Record<string, number> = {}
+  for (const finding of newFindings) {
+    const key = impactKey(finding.impact)
+    newByImpact[key] = (newByImpact[key] ?? 0) + 1
+  }
+
+  const blockingNew = newFindings.filter((finding) => failOnImpact.has(impactKey(finding.impact)))
+
+  return {
+    newFindings,
+    existing,
+    resolved,
+    blockingNew,
+    stats: {
+      totalCurrent: dedupeFindings(current.findings).length,
+      totalBaseline: baselineEntries.length,
+      newCount: newFindings.length,
+      existingCount: existing.length,
+      resolvedCount: resolved.length,
+      newByImpact,
+    },
+  }
+}

package/src/fingerprint.ts

@@ -0,0 +1,107 @@
+import { hashObject } from "./hash"
+import { AxeNodeResult, TargetFingerprintCanonical } from "./types"
+
+const STABLE_ATTR_NAMES = [
+  "data-testid",
+  "data-test",
+  "data-qa",
+  "aria-label",
+  "aria-labelledby",
+  "id",
+  "name",
+  "role",
+  "type",
+  "href",
+  "for",
+] as const
+
+const STABLE_ATTR_SET = new Set<string>(STABLE_ATTR_NAMES)
+
+function truncate(value: string, maxLength = 120): string {
+  if (value.length <= maxLength) {
+    return value
+  }
+  return value.slice(0, maxLength)
+}
+
+function parseTag(html: string | undefined): string | null {
+  if (!html) {
+    return null
+  }
+
+  const match = html.match(/^\s*<\s*([a-zA-Z0-9:-]+)/)
+  return match ? match[1].toLowerCase() : null
+}
+
+function parseStableAttrs(html: string | undefined): Record<string, string> {
+  if (!html) {
+    return {}
+  }
+
+  const attrs: Record<string, string> = {}
+  const attrRegex = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g
+
+  for (const match of html.matchAll(attrRegex)) {
+    const rawName = match[1]
+    const name = rawName.toLowerCase()
+    if (!STABLE_ATTR_SET.has(name)) {
+      continue
+    }
+
+    const value = match[3] ?? match[4] ?? match[5] ?? ""
+    attrs[name] = truncate(value.trim())
+  }
+
+  return attrs
+}
+
+function sanitizeSelectorHint(selector: string): string {
+  let output = selector
+    .replace(/:nth-[a-z-]+\([^)]*\)/gi, "")
+    .replace(/\[(\w[\w-]*)\s*=\s*["']?\d{2,}["']?\s*\]/g, "[$1]")
+    .replace(/\b\d{2,}\b/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+  return truncate(output, 120)
+}
+
+function selectorHintFromTarget(target: string[] | undefined): string | null {
+  const first = target?.[0]
+  if (!first) {
+    return null
+  }
+
+  const chunks = first
+    .split(/\s+|>|\+|~/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+
+  const last = chunks.length > 0 ? chunks[chunks.length - 1] : first
+  const hint = sanitizeSelectorHint(last)
+  return hint || null
+}
+
+export interface TargetFingerprintResult {
+  canonical: TargetFingerprintCanonical
+  targetHash: string
+  selectorHint: string | null
+}
+
+export function buildTargetFingerprint(
+  node: Pick<AxeNodeResult, "target" | "html">,
+): TargetFingerprintResult {
+  const selectorHint = selectorHintFromTarget(node.target)
+  const stableAttrs = parseStableAttrs(node.html)
+
+  const canonical: TargetFingerprintCanonical = {
+    tag: parseTag(node.html),
+    stableAttrs,
+    structuralHint: Object.keys(stableAttrs).length === 0 ? selectorHint : null,
+  }
+
+  return {
+    canonical,
+    selectorHint,
+    targetHash: hashObject(canonical),
+  }
+}

package/src/hash.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto"
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortValue(item))
+  }
+
+  if (value && typeof value === "object") {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortValue((value as Record<string, unknown>)[key])
+    }
+    return sorted
+  }
+
+  return value
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(sortValue(value))
+}
+
+export function sha1Hex(input: string): string {
+  return createHash("sha1").update(input).digest("hex")
+}
+
+export function hashObject(input: unknown): string {
+  return sha1Hex(stableStringify(input))
+}

package/src/impact.ts

@@ -0,0 +1,27 @@
+import { TrailmarkImpact, TrailmarkImpactKey } from "./types"
+
+export const IMPACT_ORDER: TrailmarkImpactKey[] = [
+  "critical",
+  "serious",
+  "moderate",
+  "minor",
+  "unknown",
+]
+
+export function impactKey(impact: TrailmarkImpact | TrailmarkImpactKey): TrailmarkImpactKey {
+  if (!impact) {
+    return "unknown"
+  }
+
+  return impact
+}
+
+export function impactRank(impact: TrailmarkImpact | TrailmarkImpactKey): number {
+  const key = impactKey(impact)
+  const index = IMPACT_ORDER.indexOf(key)
+  if (index >= 0) {
+    return index
+  }
+
+  return IMPACT_ORDER.length + 1
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./types"
+export * from "./hash"
+export * from "./url"
+export * from "./issue"
+export * from "./fingerprint"
+export * from "./normalize"
+export * from "./run"
+export * from "./baseline"
+export * from "./scope"
+export * from "./diff"
+export * from "./report"

package/src/issue.ts

@@ -0,0 +1,49 @@
+import { hashObject } from "./hash"
+
+export interface IssueIdInput {
+  ruleId: string
+  pageKey: string
+  targetHash: string
+  failureHint?: string
+}
+
+export function normalizeFailureHint(summary: string | undefined): string | undefined {
+  if (!summary) {
+    return undefined
+  }
+
+  const normalized = summary
+    .toLowerCase()
+    .replace(/["']/g, "")
+    .replace(/\d+/g, "#")
+    .replace(/\s+/g, " ")
+    .trim()
+
+  if (!normalized) {
+    return undefined
+  }
+
+  return normalized
+}
+
+export function buildRelaxedIssueId(input: Omit<IssueIdInput, "failureHint">): string {
+  return hashObject({
+    ruleId: input.ruleId,
+    pageKey: input.pageKey,
+    targetHash: input.targetHash,
+  })
+}
+
+export function buildIssueId(input: IssueIdInput): string {
+  const payload: Record<string, string> = {
+    ruleId: input.ruleId,
+    pageKey: input.pageKey,
+    targetHash: input.targetHash,
+  }
+
+  if (input.failureHint) {
+    payload.failureHint = input.failureHint
+  }
+
+  return hashObject(payload)
+}

package/src/normalize.ts

@@ -0,0 +1,66 @@
+import { buildTargetFingerprint } from "./fingerprint"
+import { buildIssueId, buildRelaxedIssueId, normalizeFailureHint } from "./issue"
+import { normalizeUrlToPageKey } from "./url"
+import { NormalizeInput, TrailmarkFinding } from "./types"
+
+function truncate(value: string | undefined, maxLength: number): string | undefined {
+  if (!value) {
+    return undefined
+  }
+
+  if (value.length <= maxLength) {
+    return value
+  }
+
+  return value.slice(0, maxLength)
+}
+
+export function normalizeAxeResults(input: NormalizeInput): TrailmarkFinding[] {
+  const pageKey = normalizeUrlToPageKey(input.pageUrl, input.urlOptions)
+  const htmlMaxLength = input.htmlMaxLength ?? 400
+  const failureSummaryMaxLength = input.failureSummaryMaxLength ?? 400
+
+  const findings: TrailmarkFinding[] = []
+
+  for (const violation of input.results.violations ?? []) {
+    for (const node of violation.nodes ?? []) {
+      const fingerprint = buildTargetFingerprint(node)
+      const failureSummary = truncate(node.failureSummary, failureSummaryMaxLength)
+      const failureHint = normalizeFailureHint(failureSummary)
+
+      const relaxedIssueId = buildRelaxedIssueId({
+        ruleId: violation.id,
+        pageKey,
+        targetHash: fingerprint.targetHash,
+      })
+
+      const issueId = buildIssueId({
+        ruleId: violation.id,
+        pageKey,
+        targetHash: fingerprint.targetHash,
+        failureHint,
+      })
+
+      findings.push({
+        issueId,
+        relaxedIssueId,
+        ruleId: violation.id,
+        impact: violation.impact,
+        tags: [...(violation.tags ?? [])],
+        help: violation.help,
+        helpUrl: violation.helpUrl,
+        pageUrl: input.pageUrl,
+        pageKey,
+        target: Array.isArray(node.target) ? [...node.target] : [],
+        selectorHint: fingerprint.selectorHint ?? undefined,
+        targetHash: fingerprint.targetHash,
+        nodeHtml: truncate(node.html, htmlMaxLength),
+        failureSummary,
+        failureHint,
+        meta: input.meta,
+      })
+    }
+  }
+
+  return findings
+}