@trailmark/core 0.1.0

package/src/report/buildReport.ts

@@ -0,0 +1,276 @@
+import { hashObject } from "../hash"
+import {
+  BuildReportInput,
+  TrailmarkReport,
+  TrailmarkReportIssue,
+  TrailmarkReportOccurrence,
+} from "./types"
+import { TrailmarkAttachment, TrailmarkFinding } from "../types"
+import { impactKey, impactRank } from "../impact"
+import { compareIssueLike } from "./sort"
+
+type MutableIssue = TrailmarkReportIssue & {
+  occurrenceKeys: Set<string>
+}
+
+function dedupeAndSortTags(tags: string[]): string[] {
+  return Array.from(new Set(tags)).sort((left, right) => left.localeCompare(right))
+}
+
+function compareOccurrence(
+  left: TrailmarkReportOccurrence,
+  right: TrailmarkReportOccurrence,
+): number {
+  const projectDiff = (left.projectName ?? "").localeCompare(right.projectName ?? "")
+  if (projectDiff !== 0) {
+    return projectDiff
+  }
+
+  const testDiff = (left.testId ?? "").localeCompare(right.testId ?? "")
+  if (testDiff !== 0) {
+    return testDiff
+  }
+
+  const urlDiff = left.url.localeCompare(right.url)
+  if (urlDiff !== 0) {
+    return urlDiff
+  }
+
+  const timestampDiff = left.timestamp.localeCompare(right.timestamp)
+  if (timestampDiff !== 0) {
+    return timestampDiff
+  }
+
+  return (left.occurrenceId ?? "").localeCompare(right.occurrenceId ?? "")
+}
+
+function toSortedRecord(map: Map<string, number>): Record<string, number> {
+  const sorted = Array.from(map.entries()).sort((left, right) => left[0].localeCompare(right[0]))
+  const record: Record<string, number> = {}
+  for (const [key, value] of sorted) {
+    record[key] = value
+  }
+
+  return record
+}
+
+function toSortedAttachment(attachment: TrailmarkAttachment): TrailmarkAttachment {
+  return {
+    kind: attachment.kind,
+    path: attachment.path,
+    error: attachment.error,
+  }
+}
+
+function compareAttachment(left: TrailmarkAttachment, right: TrailmarkAttachment): number {
+  const kindDiff = left.kind.localeCompare(right.kind)
+  if (kindDiff !== 0) {
+    return kindDiff
+  }
+
+  const pathDiff = (left.path ?? "").localeCompare(right.path ?? "")
+  if (pathDiff !== 0) {
+    return pathDiff
+  }
+
+  return (left.error ?? "").localeCompare(right.error ?? "")
+}
+
+function resolveAttachments(
+  finding: TrailmarkFinding,
+  artifacts: BuildReportInput["artifacts"],
+): TrailmarkAttachment[] {
+  const fromOccurrenceId = finding.occurrenceId
+    ? artifacts?.byOccurrenceId?.[finding.occurrenceId]
+    : undefined
+  const fromIssueId = artifacts?.byIssueId?.[finding.issueId]
+  const source = fromOccurrenceId ?? finding.attachments ?? fromIssueId ?? []
+
+  return [...source].map(toSortedAttachment).sort(compareAttachment)
+}
+
+function occurrenceKey(finding: TrailmarkFinding, occurrence: TrailmarkReportOccurrence): string {
+  if (finding.occurrenceId) {
+    return finding.occurrenceId
+  }
+
+  return hashObject({
+    issueId: finding.issueId,
+    testId: occurrence.testId,
+    projectName: occurrence.projectName,
+    url: occurrence.url,
+    selector: finding.target[0] ?? finding.selectorHint ?? "",
+  })
+}
+
+function findingSortKey(finding: TrailmarkFinding): string {
+  return [
+    impactRank(finding.impact),
+    finding.ruleId,
+    finding.pageKey,
+    finding.issueId,
+    finding.meta?.projectName ?? "",
+    finding.meta?.testId ?? "",
+    finding.target[0] ?? finding.selectorHint ?? "",
+  ].join("|")
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right))
+}
+
+export function buildReport(input: BuildReportInput): TrailmarkReport {
+  const createdAt = input.createdAt ?? new Date().toISOString()
+  const issuesById = new Map<string, MutableIssue>()
+  const scannedPages = new Set<string>()
+  const sortedFindings = [...input.run.findings].sort((left, right) =>
+    findingSortKey(left).localeCompare(findingSortKey(right)),
+  )
+
+  for (const finding of sortedFindings) {
+    scannedPages.add(finding.pageKey)
+
+    const existing = issuesById.get(finding.issueId)
+    const issue = existing ?? {
+      issueId: finding.issueId,
+      ruleId: finding.ruleId,
+      impact: finding.impact,
+      tags: dedupeAndSortTags(finding.tags),
+      pageKey: finding.pageKey,
+      url: finding.pageUrl,
+      target: [...finding.target],
+      selectorHint: finding.selectorHint,
+      failureSummary: finding.failureSummary,
+      occurrences: [],
+      occurrenceKeys: new Set<string>(),
+    }
+
+    if (!existing) {
+      issuesById.set(finding.issueId, issue)
+    }
+
+    const occurrence: TrailmarkReportOccurrence = {
+      occurrenceId: finding.occurrenceId,
+      testId: finding.meta?.testId,
+      projectName: finding.meta?.projectName,
+      url: finding.pageUrl,
+      timestamp: finding.occurredAt ?? input.run.finishedAt ?? input.run.startedAt,
+      attachments: resolveAttachments(finding, input.artifacts),
+    }
+
+    const key = occurrenceKey(finding, occurrence)
+    if (issue.occurrenceKeys.has(key)) {
+      continue
+    }
+
+    issue.occurrenceKeys.add(key)
+    issue.occurrences.push(occurrence)
+  }
+
+  const issues = Array.from(issuesById.values())
+    .map((issue) => ({
+      issueId: issue.issueId,
+      ruleId: issue.ruleId,
+      impact: issue.impact,
+      tags: issue.tags,
+      pageKey: issue.pageKey,
+      url: issue.url,
+      target: issue.target,
+      selectorHint: issue.selectorHint,
+      failureSummary: issue.failureSummary,
+      occurrences: [...issue.occurrences].sort(compareOccurrence),
+    }))
+    .sort(compareIssueLike)
+
+  const byImpact = new Map<string, number>()
+  const byRuleId = new Map<string, number>()
+  const byPageKey = new Map<string, number>()
+
+  for (const issue of issues) {
+    const impact = impactKey(issue.impact)
+    byImpact.set(impact, (byImpact.get(impact) ?? 0) + 1)
+    byRuleId.set(issue.ruleId, (byRuleId.get(issue.ruleId) ?? 0) + 1)
+    byPageKey.set(issue.pageKey, (byPageKey.get(issue.pageKey) ?? 0) + 1)
+  }
+
+  const newIssueIds = uniqueSorted(input.diff?.newFindings.map((finding) => finding.issueId) ?? [])
+  const existingIssueIds = uniqueSorted(
+    input.diff?.existing.map((entry) => entry.finding.issueId) ?? [],
+  )
+  const resolvedIssueIds = uniqueSorted(input.diff?.resolved.map((entry) => entry.issueId) ?? [])
+
+  const summary = {
+    scannedPages: scannedPages.size,
+    totalIssues: issues.length,
+    totalOccurrences: sortedFindings.length,
+    scanErrors: input.run.scanErrors.length,
+    newIssues: newIssueIds.length,
+    existingIssues: existingIssueIds.length,
+    resolvedIssues: resolvedIssueIds.length,
+    byImpact: toSortedRecord(byImpact),
+    byRuleId: toSortedRecord(byRuleId),
+    byPageKey: toSortedRecord(byPageKey),
+  }
+
+  const report: TrailmarkReport = {
+    run: {
+      reportVersion: 2,
+      mode: input.mode,
+      createdAt,
+      startedAt: input.run.startedAt,
+      finishedAt: input.run.finishedAt,
+      configHash: input.configHash,
+      tool: input.run.tool,
+      engine: {
+        scanner: input.run.tool.scanner,
+        runtime: "playwright",
+      },
+      metadata: input.run.metadata,
+    },
+    summary,
+    issues,
+  }
+
+  if (input.diff) {
+    const issuesByIssueId = new Map(issues.map((issue) => [issue.issueId, issue]))
+    const newIssues = newIssueIds
+      .map((issueId) => {
+        const issue = issuesByIssueId.get(issueId)
+        if (!issue) {
+          const fallback = input.diff?.newFindings.find((finding) => finding.issueId === issueId)
+          if (!fallback) {
+            return undefined
+          }
+
+          return {
+            issueId,
+            ruleId: fallback.ruleId,
+            impact: fallback.impact,
+            pageKey: fallback.pageKey,
+            selectorHint: fallback.target[0] ?? fallback.selectorHint,
+            occurrenceCount: 1,
+          }
+        }
+
+        return {
+          issueId,
+          ruleId: issue.ruleId,
+          impact: issue.impact,
+          pageKey: issue.pageKey,
+          selectorHint: issue.target[0] ?? issue.selectorHint,
+          occurrenceCount: issue.occurrences.length,
+        }
+      })
+      .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+      .sort(compareIssueLike)
+
+    report.diff = {
+      newIssueIds,
+      existingIssueIds,
+      resolvedIssueIds,
+      newIssues,
+    }
+  }
+
+  return report
+}

package/src/report/formatConsole.ts

@@ -0,0 +1,137 @@
+import { FormatConsoleOptions, TrailmarkReport, TrailmarkReportIssue } from "./types"
+import { TrailmarkImpactKey } from "../types"
+import { impactKey, impactRank } from "../impact"
+import { compareIssueLike } from "./sort"
+
+function topPages(issues: TrailmarkReportIssue[], limit: number): string {
+  const counts = new Map<string, number>()
+  for (const issue of issues) {
+    counts.set(issue.pageKey, (counts.get(issue.pageKey) ?? 0) + 1)
+  }
+
+  return Array.from(counts.entries())
+    .sort((left, right) => {
+      const countDiff = right[1] - left[1]
+      if (countDiff !== 0) {
+        return countDiff
+      }
+      return left[0].localeCompare(right[0])
+    })
+    .slice(0, limit)
+    .map(([page]) => page)
+    .join(", ")
+}
+
+function firstArtifactPath(issue: TrailmarkReportIssue): string | undefined {
+  for (const occurrence of issue.occurrences) {
+    for (const attachment of occurrence.attachments) {
+      if (attachment.path) {
+        return attachment.path
+      }
+    }
+  }
+
+  return undefined
+}
+
+function firstReproHint(issue: TrailmarkReportIssue): string {
+  const occurrence = issue.occurrences[0]
+  if (!occurrence) {
+    return `url=${issue.url}`
+  }
+
+  const segments: string[] = []
+  if (occurrence.testId) {
+    segments.push(`testId=${occurrence.testId}`)
+  }
+  segments.push(`url=${occurrence.url}`)
+  return segments.join(" ")
+}
+
+export function formatConsoleReport(
+  report: TrailmarkReport,
+  options: FormatConsoleOptions = {},
+): string {
+  const failOnImpact = options.failOnImpact ?? ["serious", "critical"]
+  const topPagesPerRule = options.topPagesPerRule ?? 3
+  const lines: string[] = []
+
+  lines.push(
+    `trailmark: scanned pages=${report.summary.scannedPages} | total issues=${report.summary.totalIssues} | NEW=${report.summary.newIssues} | fail on=${failOnImpact.join(", ")}`,
+  )
+
+  if (!report.diff) {
+    if (report.summary.scanErrors > 0) {
+      lines.push(`trailmark: scan errors=${report.summary.scanErrors}`)
+    }
+    return lines.join("\n")
+  }
+
+  if (report.diff.newIssueIds.length === 0) {
+    lines.push("trailmark: no new accessibility violations compared to baseline.")
+    if (report.summary.scanErrors > 0) {
+      lines.push(`trailmark: scan errors=${report.summary.scanErrors}`)
+    }
+    return lines.join("\n")
+  }
+
+  const newIssueIds = new Set(report.diff.newIssueIds)
+  const newIssues = report.issues
+    .filter((issue) => newIssueIds.has(issue.issueId))
+    .sort(compareIssueLike)
+
+  const byImpact = new Map<TrailmarkImpactKey, TrailmarkReportIssue[]>()
+  for (const issue of newIssues) {
+    const impact = impactKey(issue.impact)
+    const list = byImpact.get(impact) ?? []
+    list.push(issue)
+    byImpact.set(impact, list)
+  }
+
+  const sortedImpactKeys = Array.from(byImpact.keys()).sort((left, right) => {
+    const leftRank = impactRank(left)
+    const rightRank = impactRank(right)
+    if (leftRank !== rightRank) {
+      return leftRank - rightRank
+    }
+
+    return left.localeCompare(right)
+  })
+
+  for (const impact of sortedImpactKeys) {
+    const issues = byImpact.get(impact) ?? []
+    lines.push(`trailmark: [${impact}] ${issues.length} NEW issue(s)`)
+
+    const byRule = new Map<string, TrailmarkReportIssue[]>()
+    for (const issue of issues) {
+      const list = byRule.get(issue.ruleId) ?? []
+      list.push(issue)
+      byRule.set(issue.ruleId, list)
+    }
+
+    const sortedRuleIds = Array.from(byRule.keys()).sort((left, right) => left.localeCompare(right))
+    for (const ruleId of sortedRuleIds) {
+      const ruleIssues = (byRule.get(ruleId) ?? []).sort(compareIssueLike)
+      const pages = topPages(ruleIssues, topPagesPerRule)
+      lines.push(`  rule ${ruleId} (${ruleIssues.length}) top pages: ${pages || "n/a"}`)
+
+      for (const issue of ruleIssues) {
+        const locator = issue.target[0] ?? issue.selectorHint ?? "<unknown-target>"
+        lines.push(`  - ${impact} | ${issue.ruleId} | ${issue.pageKey} | ${locator}`)
+
+        const artifactPath = firstArtifactPath(issue)
+        if (artifactPath) {
+          lines.push(`    artifact: ${artifactPath}`)
+        }
+
+        lines.push(`    reproduce: ${firstReproHint(issue)}`)
+      }
+    }
+  }
+
+  if (report.summary.scanErrors > 0) {
+    lines.push(`trailmark: scan errors=${report.summary.scanErrors}`)
+  }
+
+  return lines.join("\n")
+}

package/src/report/index.ts

@@ -0,0 +1,3 @@
+export * from "./types"
+export * from "./buildReport"
+export * from "./formatConsole"

package/src/report/sort.ts

@@ -0,0 +1,28 @@
+import { impactRank } from "../impact"
+import { TrailmarkImpact } from "../types"
+
+export interface IssueSortInput {
+  issueId: string
+  ruleId: string
+  pageKey: string
+  impact?: TrailmarkImpact
+}
+
+export function compareIssueLike(left: IssueSortInput, right: IssueSortInput): number {
+  const impactDiff = impactRank(left.impact) - impactRank(right.impact)
+  if (impactDiff !== 0) {
+    return impactDiff
+  }
+
+  const ruleDiff = left.ruleId.localeCompare(right.ruleId)
+  if (ruleDiff !== 0) {
+    return ruleDiff
+  }
+
+  const pageDiff = left.pageKey.localeCompare(right.pageKey)
+  if (pageDiff !== 0) {
+    return pageDiff
+  }
+
+  return left.issueId.localeCompare(right.issueId)
+}

package/src/report/types.ts

@@ -0,0 +1,101 @@
+import {
+  DiffResult,
+  TrailmarkAttachment,
+  TrailmarkImpact,
+  TrailmarkRun,
+  TrailmarkToolInfo,
+} from "../types"
+
+export type TrailmarkReportMode = "baseline" | "check"
+
+export interface TrailmarkArtifactIndex {
+  byOccurrenceId?: Record<string, TrailmarkAttachment[]>
+  byIssueId?: Record<string, TrailmarkAttachment[]>
+}
+
+export interface TrailmarkReportOccurrence {
+  occurrenceId?: string
+  testId?: string
+  projectName?: string
+  url: string
+  timestamp: string
+  attachments: TrailmarkAttachment[]
+}
+
+export interface TrailmarkReportIssue {
+  issueId: string
+  ruleId: string
+  impact?: TrailmarkImpact
+  tags: string[]
+  pageKey: string
+  url: string
+  target: string[]
+  selectorHint?: string
+  failureSummary?: string
+  occurrences: TrailmarkReportOccurrence[]
+}
+
+export interface TrailmarkReportDiffIssueSummary {
+  issueId: string
+  ruleId: string
+  impact?: TrailmarkImpact
+  pageKey: string
+  selectorHint?: string
+  occurrenceCount: number
+}
+
+export interface TrailmarkReportDiff {
+  newIssueIds: string[]
+  existingIssueIds: string[]
+  resolvedIssueIds: string[]
+  newIssues: TrailmarkReportDiffIssueSummary[]
+}
+
+export interface TrailmarkReportSummary {
+  scannedPages: number
+  totalIssues: number
+  totalOccurrences: number
+  scanErrors: number
+  newIssues: number
+  existingIssues: number
+  resolvedIssues: number
+  byImpact: Record<string, number>
+  byRuleId: Record<string, number>
+  byPageKey: Record<string, number>
+}
+
+export interface TrailmarkReportRunMetadata {
+  reportVersion: 2
+  mode: TrailmarkReportMode
+  createdAt: string
+  startedAt: string
+  finishedAt?: string
+  configHash: string
+  tool: TrailmarkToolInfo
+  engine: {
+    scanner: string
+    runtime: "playwright"
+  }
+  metadata?: Record<string, unknown>
+}
+
+export interface TrailmarkReport {
+  run: TrailmarkReportRunMetadata
+  summary: TrailmarkReportSummary
+  issues: TrailmarkReportIssue[]
+  diff?: TrailmarkReportDiff
+}
+
+export interface BuildReportInput {
+  run: TrailmarkRun
+  mode: TrailmarkReportMode
+  configHash: string
+  diff?: DiffResult
+  createdAt?: string
+  artifacts?: TrailmarkArtifactIndex
+}
+
+export interface FormatConsoleOptions {
+  failOnImpact?: string[]
+  topPagesPerRule?: number
+}

package/src/run.ts

@@ -0,0 +1,22 @@
+import { TrailmarkRun, TrailmarkToolInfo } from "./types"
+
+export const DEFAULT_TOOL_INFO: TrailmarkToolInfo = {
+  name: "trailmark",
+  version: "0.1.0",
+  scanner: "@axe-core/playwright",
+}
+
+export function createEmptyRun(options?: {
+  metadata?: Record<string, unknown>
+  tool?: TrailmarkToolInfo
+  startedAt?: string
+}): TrailmarkRun {
+  return {
+    version: 1,
+    startedAt: options?.startedAt ?? new Date().toISOString(),
+    tool: options?.tool ?? DEFAULT_TOOL_INFO,
+    findings: [],
+    scanErrors: [],
+    metadata: options?.metadata,
+  }
+}

package/src/scope.ts

@@ -0,0 +1,25 @@
+import { BaselineEntry, TrailmarkFindingMeta } from "./types"
+
+const DEFAULT_SCOPE_KEY = "default"
+
+function normalizeScopeValue(value: string | undefined): string {
+  const normalized = value?.trim().toLowerCase()
+  if (!normalized) {
+    return DEFAULT_SCOPE_KEY
+  }
+  return normalized
+}
+
+export function scopeKeyFromMeta(meta: TrailmarkFindingMeta | undefined): string {
+  return normalizeScopeValue(meta?.projectName)
+}
+
+export function scopeKeyFromBaselineEntry(
+  entry: Pick<BaselineEntry, "scopeKey" | "projectName">,
+): string {
+  return normalizeScopeValue(entry.scopeKey ?? entry.projectName)
+}
+
+export function scopedIssueKey(issueId: string, scopeKey: string): string {
+  return `${scopeKey}::${issueId}`
+}