@trailmark/core 0.1.0

package/src/types.ts

@@ -0,0 +1,167 @@
+export type TrailmarkImpactKey = "minor" | "moderate" | "serious" | "critical" | "unknown"
+
+export type TrailmarkImpact = "minor" | "moderate" | "serious" | "critical" | null | undefined
+
+export interface UrlRoutePattern {
+  match: string
+  replace: string
+}
+
+export interface UrlNormalizationOptions {
+  stripHash?: boolean
+  stripQuery?: boolean | { allow: string[] }
+  routePatterns?: UrlRoutePattern[]
+}
+
+export interface TrailmarkFindingMeta {
+  testId?: string
+  testTitle?: string
+  testFile?: string
+  projectName?: string
+  scanLabel?: string
+}
+
+export interface TrailmarkScanError {
+  pageUrl?: string
+  pageKey?: string
+  message: string
+  stack?: string
+  occurredAt: string
+  meta?: TrailmarkFindingMeta
+}
+
+export interface TrailmarkAttachment {
+  kind: string
+  path?: string
+  error?: string
+}
+
+export interface TrailmarkFinding {
+  issueId: string
+  relaxedIssueId: string
+  ruleId: string
+  impact?: TrailmarkImpact
+  tags: string[]
+  help?: string
+  helpUrl?: string
+  pageUrl: string
+  pageKey: string
+  target: string[]
+  selectorHint?: string
+  targetHash: string
+  nodeHtml?: string
+  failureSummary?: string
+  failureHint?: string
+  occurredAt?: string
+  occurrenceId?: string
+  attachments?: TrailmarkAttachment[]
+  meta?: TrailmarkFindingMeta
+}
+
+export interface TrailmarkToolInfo {
+  name: string
+  version: string
+  scanner: string
+}
+
+export interface TrailmarkRun {
+  version: 1
+  startedAt: string
+  finishedAt?: string
+  tool: TrailmarkToolInfo
+  findings: TrailmarkFinding[]
+  scanErrors: TrailmarkScanError[]
+  metadata?: Record<string, unknown>
+}
+
+export interface BaselineEntry {
+  issueId: string
+  scopeKey?: string
+  projectName?: string
+  relaxedIssueId: string
+  ruleId: string
+  impact?: TrailmarkImpact
+  pageKey: string
+  pageUrl: string
+  targetHash: string
+  selectorHint?: string
+  sampleTarget?: string
+  help?: string
+  helpUrl?: string
+  tags: string[]
+  failureHint?: string
+  occurrences: number
+  firstSeenAt: string
+  lastSeenAt: string
+}
+
+export interface BaselineFile {
+  version: 1
+  createdAt: string
+  tool: TrailmarkToolInfo
+  configHash: string
+  findings: Record<string, BaselineEntry>
+}
+
+export interface DiffMatch {
+  finding: TrailmarkFinding
+  matchedBy: "exact" | "relaxed"
+  baselineIssueId: string
+  baselineScopeKey?: string
+}
+
+export interface DiffStats {
+  totalCurrent: number
+  totalBaseline: number
+  newCount: number
+  existingCount: number
+  resolvedCount: number
+  newByImpact: Record<string, number>
+}
+
+export interface DiffResult {
+  newFindings: TrailmarkFinding[]
+  existing: DiffMatch[]
+  resolved: BaselineEntry[]
+  blockingNew: TrailmarkFinding[]
+  stats: DiffStats
+}
+
+export interface DiffOptions {
+  failOnImpact?: string[]
+  onDebug?: (message: string, context?: Record<string, unknown>) => void
+}
+
+export interface AxeNodeResult {
+  target: string[]
+  html?: string
+  failureSummary?: string
+}
+
+export interface AxeViolation {
+  id: string
+  impact?: TrailmarkImpact
+  tags?: string[]
+  help?: string
+  helpUrl?: string
+  nodes: AxeNodeResult[]
+}
+
+export interface AxeLikeResults {
+  violations: AxeViolation[]
+}
+
+export interface NormalizeInput {
+  results: AxeLikeResults
+  pageUrl: string
+  urlOptions?: UrlNormalizationOptions
+  meta?: TrailmarkFindingMeta
+  htmlMaxLength?: number
+  failureSummaryMaxLength?: number
+}
+
+export interface TargetFingerprintCanonical {
+  tag: string | null
+  stableAttrs: Record<string, string>
+  structuralHint: string | null
+}

package/src/url.ts

@@ -0,0 +1,102 @@
+import { UrlNormalizationOptions } from "./types"
+
+const DEFAULT_OPTIONS: Required<Pick<UrlNormalizationOptions, "stripHash" | "stripQuery">> = {
+  stripHash: true,
+  stripQuery: true,
+}
+
+function normalizeQuery(params: URLSearchParams, allow?: Set<string>): string {
+  const keys = Array.from(new Set(params.keys()))
+    .filter((key) => !allow || allow.has(key))
+    .sort((a, b) => a.localeCompare(b))
+
+  const pairs: string[] = []
+  for (const key of keys) {
+    const values = params.getAll(key).sort((a, b) => a.localeCompare(b))
+    for (const value of values) {
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    }
+  }
+
+  return pairs.join("&")
+}
+
+function stripQueryFromFallback(
+  raw: string,
+  stripQuery: UrlNormalizationOptions["stripQuery"],
+): string {
+  if (stripQuery === true) {
+    return raw.replace(/\?.*$/, "")
+  }
+
+  if (stripQuery && typeof stripQuery === "object") {
+    const [base, rawQuery = ""] = raw.split("?")
+    if (!rawQuery) {
+      return base
+    }
+
+    const allow = new Set(stripQuery.allow)
+    const params = new URLSearchParams(rawQuery)
+    const query = normalizeQuery(params, allow)
+    return query ? `${base}?${query}` : base
+  }
+
+  return raw
+}
+
+function applyRoutePatterns(
+  pageKey: string,
+  routePatterns: UrlNormalizationOptions["routePatterns"],
+): string {
+  if (!routePatterns || routePatterns.length === 0) {
+    return pageKey
+  }
+
+  let result = pageKey
+  for (const pattern of routePatterns) {
+    try {
+      const matcher = new RegExp(pattern.match)
+      if (matcher.test(result)) {
+        result = result.replace(matcher, pattern.replace)
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return result
+}
+
+export function normalizeUrlToPageKey(
+  rawUrl: string,
+  options: UrlNormalizationOptions = {},
+): string {
+  const merged: UrlNormalizationOptions = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+  }
+
+  let pageKey: string
+
+  try {
+    const parsed = new URL(rawUrl)
+    const host = parsed.host.toLowerCase()
+    const pathname = parsed.pathname || "/"
+
+    let query = ""
+    if (merged.stripQuery === false) {
+      query = normalizeQuery(parsed.searchParams)
+    } else if (merged.stripQuery && typeof merged.stripQuery === "object") {
+      query = normalizeQuery(parsed.searchParams, new Set(merged.stripQuery.allow))
+    }
+
+    const hash = !merged.stripHash ? parsed.hash : ""
+    pageKey = `${host}${pathname}${query ? `?${query}` : ""}${hash}`
+  } catch {
+    const lowered = rawUrl.trim().toLowerCase()
+    const withoutHash = merged.stripHash ? lowered.replace(/#.*$/, "") : lowered
+    pageKey = stripQueryFromFallback(withoutHash, merged.stripQuery)
+  }
+
+  return applyRoutePatterns(pageKey, merged.routePatterns)
+}

package/test/baseline.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest"
+import { buildBaselineFromRun, parseBaselineFile } from "../src/baseline"
+import { diffRuns } from "../src/diff"
+import { createEmptyRun } from "../src/run"
+import { TrailmarkFinding } from "../src/types"
+
+function makeFinding(overrides: Partial<TrailmarkFinding> = {}): TrailmarkFinding {
+  return {
+    issueId: "issue-1",
+    relaxedIssueId: "relaxed-1",
+    ruleId: "color-contrast",
+    impact: "serious",
+    tags: ["wcag2aa"],
+    pageUrl: "https://example.com/checkout?order=123",
+    pageKey: "example.com/checkout",
+    target: ["button.cta"],
+    selectorHint: "button.cta",
+    targetHash: "target-1",
+    failureHint: "contrast ratio below threshold",
+    ...overrides,
+  }
+}
+
+describe("buildBaselineFromRun", () => {
+  it("roundtrips as JSON with schema version and stable entry shape", () => {
+    const run = createEmptyRun({
+      startedAt: "2026-01-01T00:00:00.000Z",
+      tool: {
+        name: "trailmark",
+        version: "0.1.0",
+        scanner: "@axe-core/playwright",
+      },
+    })
+
+    run.findings.push(makeFinding())
+    run.findings.push(makeFinding())
+
+    const baseline = buildBaselineFromRun(run, {
+      createdAt: "2026-01-02T00:00:00.000Z",
+      configHash: "cfg-123",
+    })
+
+    const parsed = JSON.parse(JSON.stringify(baseline)) as typeof baseline
+    expect(parsed.version).toBe(1)
+    expect(parsed.createdAt).toBe("2026-01-02T00:00:00.000Z")
+    expect(parsed.configHash).toBe("cfg-123")
+    expect(parsed.tool).toEqual(run.tool)
+
+    const entries = Object.values(parsed.findings)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].occurrences).toBe(2)
+
+    const current = createEmptyRun()
+    current.findings.push(makeFinding())
+
+    const diff = diffRuns(parsed, current, { failOnImpact: ["serious", "critical"] })
+    expect(diff.newFindings).toHaveLength(0)
+    expect(diff.existing).toHaveLength(1)
+  })
+
+  it("reuses previous baseline timestamps when findings are unchanged", () => {
+    const run = createEmptyRun({ startedAt: "2026-01-01T00:00:00.000Z" })
+    run.findings.push(makeFinding())
+
+    const first = buildBaselineFromRun(run, {
+      createdAt: "2026-01-02T00:00:00.000Z",
+      configHash: "cfg-123",
+    })
+    const second = buildBaselineFromRun(run, {
+      configHash: "cfg-123",
+      previousBaseline: first,
+    })
+
+    expect(second).toEqual(first)
+  })
+})
+
+describe("parseBaselineFile", () => {
+  function makeBaselinePayload(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      version: 1,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      tool: { name: "trailmark", version: "0.1.0", scanner: "@axe-core/playwright" },
+      configHash: "cfg",
+      findings: {
+        "issue-1::scope": {
+          issueId: "issue-1",
+          scopeKey: "scope",
+          projectName: "project-a",
+          relaxedIssueId: "relaxed-1",
+          ruleId: "color-contrast",
+          impact: "serious",
+          pageKey: "example.com/checkout",
+          pageUrl: "https://example.com/checkout",
+          targetHash: "target-1",
+          selectorHint: "button.cta",
+          sampleTarget: "button.cta",
+          help: "Fix contrast",
+          helpUrl: "https://example.com/help",
+          tags: ["wcag2a", "wcag2aa", "wcag2a"],
+          failureHint: "contrast ratio below threshold",
+          occurrences: 1,
+          firstSeenAt: "2026-01-01T00:00:00.000Z",
+          lastSeenAt: "2026-01-01T00:00:00.000Z",
+        },
+      },
+      ...overrides,
+    }
+  }
+
+  it("rejects unsupported versions with a clear error", () => {
+    const payload = {
+      version: 999,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      tool: { name: "trailmark", version: "0.1.0", scanner: "@axe-core/playwright" },
+      configHash: "cfg",
+      findings: {},
+    }
+
+    expect(parseBaselineFile(JSON.stringify(payload)).error).toBeTruthy()
+    expect(parseBaselineFile(JSON.stringify(payload)).message).toContain(
+      "unsupported baseline version",
+    )
+  })
+
+  it("normalizes tags while parsing", () => {
+    const { data: baseline, error } = parseBaselineFile(JSON.stringify(makeBaselinePayload()))
+    expect(error).toBeFalsy()
+    expect(baseline).not.toBeNull()
+    const entry = baseline!.findings["issue-1::scope"]
+    expect(entry.tags).toEqual(["wcag2a", "wcag2aa"])
+  })
+
+  it("reports nested schema violations", () => {
+    const findings = makeBaselinePayload().findings as Record<string, Record<string, unknown>>
+
+    const payload = makeBaselinePayload({
+      findings: {
+        "issue-1::scope": {
+          ...findings["issue-1::scope"],
+          occurrences: -1,
+        },
+      },
+    })
+
+    expect(parseBaselineFile(JSON.stringify(payload)).error).toBeTruthy()
+    expect(parseBaselineFile(JSON.stringify(payload)).message).toContain(
+      'trailmark: invalid baseline format at "findings.issue-1::scope.occurrences"',
+    )
+  })
+})

package/test/diff.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest"
+import { buildBaselineFromRun } from "../src/baseline"
+import { diffRuns } from "../src/diff"
+import { TrailmarkFinding, TrailmarkRun } from "../src/types"
+
+function makeFinding(overrides: Partial<TrailmarkFinding>): TrailmarkFinding {
+  return {
+    issueId: "issue-a",
+    relaxedIssueId: "relaxed-a",
+    ruleId: "color-contrast",
+    impact: "serious",
+    tags: [],
+    pageUrl: "https://example.com/checkout",
+    pageKey: "example.com/checkout",
+    target: ["button.cta"],
+    targetHash: "target-a",
+    ...overrides,
+  }
+}
+
+function makeRun(findings: TrailmarkFinding[]): TrailmarkRun {
+  return {
+    version: 1,
+    startedAt: "2026-01-01T00:00:00.000Z",
+    finishedAt: "2026-01-01T00:00:01.000Z",
+    tool: { name: "trailmark", version: "0.1.0", scanner: "@axe-core/playwright" },
+    findings,
+  }
+}
+
+describe("diffRuns", () => {
+  it("matches exact and relaxed signatures", () => {
+    const baselineRun = makeRun([
+      makeFinding({
+        issueId: "exact-id",
+        relaxedIssueId: "relaxed-same",
+        failureHint: "old hint",
+      }),
+      makeFinding({
+        issueId: "resolved-id",
+        relaxedIssueId: "resolved-relaxed",
+        pageKey: "example.com/account",
+        pageUrl: "https://example.com/account",
+      }),
+    ])
+
+    const baseline = buildBaselineFromRun(baselineRun, { configHash: "cfg" })
+
+    const currentRun = makeRun([
+      makeFinding({
+        issueId: "exact-id",
+        relaxedIssueId: "relaxed-same",
+      }),
+      makeFinding({
+        issueId: "new-id-derived-from-new-failure",
+        relaxedIssueId: "relaxed-same",
+        failureHint: "changed hint",
+      }),
+      makeFinding({
+        issueId: "brand-new-id",
+        relaxedIssueId: "brand-new-relaxed",
+        impact: "critical",
+        pageKey: "example.com/cart",
+        pageUrl: "https://example.com/cart",
+      }),
+    ])
+
+    const diff = diffRuns(baseline, currentRun, { failOnImpact: ["serious", "critical"] })
+
+    expect(diff.existing).toHaveLength(1)
+    expect(diff.existing[0].matchedBy).toBe("exact")
+    expect(diff.newFindings).toHaveLength(2)
+    expect(new Set(diff.newFindings.map((finding) => finding.issueId))).toEqual(
+      new Set(["new-id-derived-from-new-failure", "brand-new-id"]),
+    )
+    expect(diff.resolved).toHaveLength(1)
+    expect(diff.blockingNew).toHaveLength(2)
+  })
+
+  it("enforces one-to-one relaxed matching cardinality", () => {
+    const baselineRun = makeRun([
+      makeFinding({
+        issueId: "baseline-id",
+        relaxedIssueId: "relaxed-shared",
+        failureHint: "old hint",
+      }),
+    ])
+    const baseline = buildBaselineFromRun(baselineRun, { configHash: "cfg" })
+
+    const currentRun = makeRun([
+      makeFinding({
+        issueId: "candidate-1",
+        relaxedIssueId: "relaxed-shared",
+        failureHint: "changed hint one",
+      }),
+      makeFinding({
+        issueId: "candidate-2",
+        relaxedIssueId: "relaxed-shared",
+        failureHint: "changed hint two",
+      }),
+    ])
+
+    const diff = diffRuns(baseline, currentRun, { failOnImpact: ["serious", "critical"] })
+
+    expect(diff.existing).toHaveLength(1)
+    expect(diff.existing[0].matchedBy).toBe("relaxed")
+    expect(diff.existing[0].baselineIssueId).toBe("baseline-id")
+    expect(diff.newFindings).toHaveLength(1)
+    expect(new Set(diff.newFindings.map((finding) => finding.issueId))).toEqual(
+      new Set(["candidate-2"]),
+    )
+  })
+})

package/test/fingerprint.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest"
+import { buildTargetFingerprint } from "../src/fingerprint"
+
+describe("buildTargetFingerprint", () => {
+  it("produces deterministic hashes regardless of attribute order", () => {
+    const first = buildTargetFingerprint({
+      target: ["main > button:nth-child(5)"],
+      html: '<button data-testid="save" aria-label="Save" type="button">Save</button>',
+    })
+
+    const second = buildTargetFingerprint({
+      target: ["main > button:nth-child(2)"],
+      html: '<button type="button" aria-label="Save" data-testid="save">Save</button>',
+    })
+
+    expect(first.targetHash).toBe(second.targetHash)
+  })
+
+  it("sanitizes selector hints", () => {
+    const result = buildTargetFingerprint({
+      target: ["#app > ul > li:nth-child(12) > a[data-id=123456]"],
+      html: '<a data-testid="item-link" href="/items/123456">Item</a>',
+    })
+
+    expect(result.selectorHint).toBe("a[data-id]")
+  })
+
+  it("extracts only stable attributes from node html", () => {
+    const result = buildTargetFingerprint({
+      target: ["form > input#email"],
+      html: '<input id="email" data-testid="email-input" class="input" aria-label="Email" />',
+    })
+
+    expect(result.canonical.tag).toBe("input")
+    expect(result.canonical.stableAttrs).toEqual({
+      "aria-label": "Email",
+      "data-testid": "email-input",
+      id: "email",
+    })
+  })
+})

package/test/issue.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest"
+import { normalizeAxeResults } from "../src/normalize"
+
+describe("issue identity", () => {
+  it("stays stable when impact changes", () => {
+    const base = {
+      violations: [
+        {
+          id: "color-contrast",
+          impact: "critical",
+          help: "Fix contrast",
+          helpUrl: "https://example.com",
+          tags: ["wcag2aa"],
+          nodes: [
+            {
+              target: ["button.cta"],
+              html: '<button data-testid="cta" aria-label="Continue">Continue</button>',
+              failureSummary: "Element has insufficient color contrast of 2.9:1",
+            },
+          ],
+        },
+      ],
+    }
+
+    const changedImpact = {
+      ...base,
+      violations: [{ ...base.violations[0], impact: "serious" }],
+    }
+
+    const first = normalizeAxeResults({ results: base, pageUrl: "https://example.com/checkout" })[0]
+    const second = normalizeAxeResults({
+      results: changedImpact,
+      pageUrl: "https://example.com/checkout",
+    })[0]
+
+    expect(first.issueId).toBe(second.issueId)
+    expect(first.relaxedIssueId).toBe(second.relaxedIssueId)
+  })
+
+  it("normalizes numeric noise in failure summaries", () => {
+    const first = normalizeAxeResults({
+      results: {
+        violations: [
+          {
+            id: "aria-valid-attr-value",
+            nodes: [
+              {
+                target: ["input"],
+                html: '<input id="zip" />',
+                failureSummary: 'Expected value "123" but found "999"',
+              },
+            ],
+          },
+        ],
+      },
+      pageUrl: "https://example.com/form",
+    })[0]
+
+    const second = normalizeAxeResults({
+      results: {
+        violations: [
+          {
+            id: "aria-valid-attr-value",
+            nodes: [
+              {
+                target: ["input"],
+                html: '<input id="zip" />',
+                failureSummary: 'Expected value "456" but found "111"',
+              },
+            ],
+          },
+        ],
+      },
+      pageUrl: "https://example.com/form",
+    })[0]
+
+    expect(first.issueId).toBe(second.issueId)
+  })
+})