@defra/fcp-sfd-frontend-engine 0.2.8 → 0.2.10

package/README.md

@@ -45,4 +45,31 @@ Docker-based local development support will be used so engine changes can be pic
 - prefer shared reusable modules over duplication
 - avoid premature abstraction
 - maintain clear ownership boundaries between the engine and applications
-- evolve incrementally
+- evolve incrementally
+
+## SonarQube Cloud scan
+
+Run a local scan against [SonarCloud](https://sonarcloud.io/project/overview?id=defra_fcp-sfd-frontend-engine) for the current git branch. See the [DEFRA SonarCloud guide](https://github.com/DEFRA/cdp-documentation/blob/main/how-to/sonarcloud.md) for organisation access and CI setup.
+
+### Setup
+
+1. Log in to [SonarQube Cloud](https://sonarcloud.io) with your DEFRA GitHub account
+2. Go to **My Account → Security → Generate Tokens** and create a personal token
+3. Add `SONAR_TOKEN=<your-token>` to your `.env` file
+
+### Run
+
+Generate test coverage first, then scan:
+
+```bash
+npm test
+npm run sonar
+```
+
+The script uploads results for the current branch and prints:
+
+- Quality gate pass/fail and failed conditions
+- Open issues on new code (when the gate fails)
+- **Accepted / false-positive issues without comment** — DEFRA quality gates require a justification comment on each suppressed issue; add comments in SonarCloud under the issue **Activity** tab
+
+Exit code is `0` when the gate passes and all suppressed issues are commented, `1` otherwise.

package/dist/index.cjs

@@ -54,9 +54,48 @@ var mapPersonalBusinessDetails = (value) => {
   };
 };
 
+// src/mappers/address-mapper.js
+var mapAddress = (address = {}) => {
+  return {
+    lookup: {
+      pafOrganisationName: address.pafOrganisationName,
+      buildingNumberRange: address.buildingNumberRange,
+      flatName: address.flatName,
+      buildingName: address.buildingName,
+      dependentLocality: address.dependentLocality,
+      doubleDependentLocality: address.doubleDependentLocality,
+      street: address.street,
+      county: address.county,
+      uprn: address.uprn
+    },
+    manual: {
+      line1: address.line1,
+      line2: address.line2,
+      line3: address.line3,
+      line4: address.line4,
+      line5: address.line5
+    },
+    city: address.city,
+    postcode: address.postalCode,
+    country: address.country
+  };
+};
+
+// src/mappers/customer-name-mapper.js
+var mapCustomerName = (name = {}) => {
+  return {
+    userName: [
+      name.first,
+      name.last
+    ].filter(Boolean).join(" ")
+  };
+};
+
 // src/mappers/mappers.js
 var mappers = {
-  mapPersonalBusinessDetails
+  personalBusinessDetails: mapPersonalBusinessDetails,
+  address: mapAddress,
+  customerName: mapCustomerName
 };
 
 // src/schemas/business/business-sbi-schema.js

package/dist/index.js

@@ -17,9 +17,48 @@ var mapPersonalBusinessDetails = (value) => {
   };
 };
 
+// src/mappers/address-mapper.js
+var mapAddress = (address = {}) => {
+  return {
+    lookup: {
+      pafOrganisationName: address.pafOrganisationName,
+      buildingNumberRange: address.buildingNumberRange,
+      flatName: address.flatName,
+      buildingName: address.buildingName,
+      dependentLocality: address.dependentLocality,
+      doubleDependentLocality: address.doubleDependentLocality,
+      street: address.street,
+      county: address.county,
+      uprn: address.uprn
+    },
+    manual: {
+      line1: address.line1,
+      line2: address.line2,
+      line3: address.line3,
+      line4: address.line4,
+      line5: address.line5
+    },
+    city: address.city,
+    postcode: address.postalCode,
+    country: address.country
+  };
+};
+
+// src/mappers/customer-name-mapper.js
+var mapCustomerName = (name = {}) => {
+  return {
+    userName: [
+      name.first,
+      name.last
+    ].filter(Boolean).join(" ")
+  };
+};
+
 // src/mappers/mappers.js
 var mappers = {
-  mapPersonalBusinessDetails
+  personalBusinessDetails: mapPersonalBusinessDetails,
+  address: mapAddress,
+  customerName: mapCustomerName
 };
 
 // src/schemas/business/business-sbi-schema.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/fcp-sfd-frontend-engine",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Shared frontend engine used by both the internal and external frontend applications.",
   "main": "./dist/index.cjs",
   "exports": {
@@ -14,7 +14,8 @@
     "lint:fix": "eslint --fix",
     "build": "tsup",
     "test": "npm run build && vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "sonar": "node scripts/sonar-scan.js"
   },
   "repository": {
     "type": "git",

package/scripts/sonar-scan.js

@@ -0,0 +1,552 @@
+import { readFileSync } from 'node:fs'
+import { execFileSync, spawn } from 'node:child_process'
+import { resolve } from 'node:path'
+
+const SONARCLOUD_BASE_URL = 'https://sonarcloud.io'
+const BORDER = '═'.repeat(51)
+const THIN_BORDER = '─'.repeat(51)
+const MAX_ISSUES_DISPLAYED = 30
+
+const SEVERITY_ORDER = ['BLOCKER', 'CRITICAL', 'MAJOR', 'MINOR', 'INFO']
+const SEVERITY_ICONS = {
+  BLOCKER: '🔴',
+  CRITICAL: '🟠',
+  MAJOR: '🟡',
+  MINOR: '🔵',
+  INFO: '⚪'
+}
+
+const HOTSPOT_ICONS = {
+  HIGH: '🔴',
+  MEDIUM: '🟠',
+  LOW: '🟡'
+}
+
+const METRIC_LABELS = {
+  new_reliability_rating: 'Reliability Rating',
+  new_security_rating: 'Security Rating',
+  new_maintainability_rating: 'Maintainability Rating',
+  new_coverage: 'Coverage on New Code',
+  new_duplicated_lines_density: 'Duplication on New Code',
+  new_violations: 'New Issues',
+  new_security_hotspots_reviewed: 'Security Hotspots Reviewed',
+  new_blocker_violations: 'Blocker Issues',
+  new_critical_violations: 'Critical Issues',
+  false_positive_issues_without_comment: 'False Positives without Comment',
+  accepted_issues_without_comment: 'Accepted Issues without Comment'
+}
+
+const ACCEPTED_ISSUE_STATUSES = ['FALSE_POSITIVE', 'ACCEPTED']
+const CHANGELOG_FETCH_CONCURRENCY = 8
+
+const COMPARATOR_SYMBOLS = {
+  GT: '>',
+  LT: '<',
+  EQ: '=',
+  NE: '≠'
+}
+
+const parseKeyValue = (content) =>
+  Object.fromEntries(
+    content
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#'))
+      .map((line) => {
+        const idx = line.indexOf('=')
+        return idx > 0 ? [line.slice(0, idx).trim(), line.slice(idx + 1).trim()] : null
+      })
+      .filter(Boolean)
+  )
+
+const getCurrentBranch = () =>
+  execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf8' }).trim()
+
+const runScanner = (sonarToken, cwd, branch) =>
+  new Promise((resolve, reject) => {
+    const args = [
+      'run',
+      '--rm',
+      '--name',
+      'sonar-scan',
+      '-v',
+      `${cwd}:/usr/src`,
+      '-e',
+      `SONAR_TOKEN=${sonarToken}`,
+      'sonarsource/sonar-scanner-cli',
+      '-Dsonar.issuesReport.console.enable=true',
+      '-Dsonar.qualitygate.wait=true',
+      `-Dsonar.branch.name=${branch}`,
+      '-Dsonar.verbose=true'
+    ]
+
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    const message =
+      'Code scan in progress using sonar-scanner-cli (to view logs in real-time a Docker client can be used e.g. Docker Desktop)'
+    let i = 0
+
+    const spinner = setInterval(() => {
+      process.stdout.write(`\r ${frames[i++ % frames.length]} ${message}`)
+    }, 80)
+
+    const child = spawn('docker', args, { stdio: 'ignore' })
+
+    child.on('error', (err) => {
+      clearInterval(spinner)
+      process.stdout.write('\r')
+      reject(err)
+    })
+
+    // Always resolve with the exit code — a non-zero exit may simply mean the
+    // quality gate failed (analysis was still uploaded). We check the gate
+    // status via the API after the scan and exit accordingly.
+    child.on('close', (code) => {
+      clearInterval(spinner)
+      process.stdout.write(`\r ${message}\n`)
+      console.log('\n ✔ Code scan complete. See below for the results.\n')
+      resolve(code)
+    })
+  })
+
+const sonarcloudFetch = async (path, sonarToken) => {
+  const url = `${SONARCLOUD_BASE_URL}${path}`
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${sonarToken}`
+    }
+  })
+
+  if (!response.ok) {
+    const body = await response.text()
+    throw new Error(`SonarCloud API error ${response.status}: ${response.statusText} (${url})${body ? ` — ${body}` : ''}`)
+  }
+
+  return response.json()
+}
+
+const fetchQualityGate = (projectKey, sonarToken, branch) =>
+  sonarcloudFetch(
+    `/api/qualitygates/project_status?projectKey=${encodeURIComponent(projectKey)}&branch=${encodeURIComponent(branch)}`,
+    sonarToken
+  )
+
+const fetchMeasures = (projectKey, sonarToken, branch) =>
+  sonarcloudFetch(
+    `/api/measures/component?component=${encodeURIComponent(projectKey)}&branch=${encodeURIComponent(branch)}&metricKeys=new_violations,accepted_issues,security_hotspots,new_coverage,new_duplicated_lines_density`,
+    sonarToken
+  )
+
+const fetchIssues = (projectKey, sonarToken, branch) =>
+  sonarcloudFetch(
+    `/api/issues/search?componentKeys=${encodeURIComponent(projectKey)}&branch=${encodeURIComponent(branch)}&resolved=false&inNewCodePeriod=true&ps=500&statuses=OPEN,CONFIRMED,REOPENED`,
+    sonarToken
+  )
+
+const fetchSecurityHotspots = (projectKey, sonarToken, branch) =>
+  sonarcloudFetch(
+    `/api/hotspots/search?projectKey=${encodeURIComponent(projectKey)}&branch=${encodeURIComponent(branch)}&inNewCodePeriod=true&ps=500&status=TO_REVIEW`,
+    sonarToken
+  )
+
+const fetchAcceptedIssues = async (projectKey, sonarToken) => {
+  const issueStatuses = ACCEPTED_ISSUE_STATUSES.join(',')
+  const pageSize = 500
+  let page = 1
+  const issues = []
+
+  while (true) {
+    const response = await sonarcloudFetch(
+      `/api/issues/search?componentKeys=${encodeURIComponent(projectKey)}&issueStatuses=${issueStatuses}&ps=${pageSize}&p=${page}`,
+      sonarToken
+    )
+
+    issues.push(...(response.issues ?? []))
+
+    const total = response.total ?? issues.length
+    if (issues.length >= total || (response.issues ?? []).length < pageSize) break
+    page++
+  }
+
+  return issues
+}
+
+const fetchIssueChangelog = (issueKey, sonarToken) =>
+  sonarcloudFetch(`/api/issues/changelog?issue=${encodeURIComponent(issueKey)}`, sonarToken)
+
+const issueHasComment = (changelogResponse) => {
+  const entries = changelogResponse?.changelog ?? []
+
+  return entries.some((entry) =>
+    (entry.items ?? []).some((item) => {
+      if (item.field !== 'comment') return false
+
+      const value = item.newValue ?? item.newString ?? ''
+      return String(value).trim().length > 0
+    })
+  )
+}
+
+const mapConcurrent = async (items, fn, concurrency = CHANGELOG_FETCH_CONCURRENCY) => {
+  const results = new Array(items.length)
+  let nextIndex = 0
+
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (nextIndex < items.length) {
+      const index = nextIndex++
+      results[index] = await fn(items[index], index)
+    }
+  })
+
+  await Promise.all(workers)
+  return results
+}
+
+const findAcceptedIssuesWithoutComment = async (projectKey, sonarToken) => {
+  const acceptedIssues = await fetchAcceptedIssues(projectKey, sonarToken)
+  if (acceptedIssues.length === 0) return []
+
+  const issuesWithCommentFlags = await mapConcurrent(acceptedIssues, async (issue) => {
+    const changelog = await fetchIssueChangelog(issue.key, sonarToken)
+    return { issue, hasComment: issueHasComment(changelog) }
+  })
+
+  return issuesWithCommentFlags.filter(({ hasComment }) => !hasComment)
+}
+
+const getMeasureValue = (measures, key) => {
+  const measure = measures.find((m) => m.metric === key)
+  if (!measure) return 'N/A'
+
+  return measure.value ?? measure.periods?.[0]?.value ?? 'N/A'
+}
+
+const formatPercent = (value) => (value === 'N/A' ? 'N/A' : `${parseFloat(value).toFixed(1)}%`)
+
+const row = (label, value) => ` ${`  ${label}`.padEnd(28)}${value}`
+
+const extractFilePath = (component, projectKey) => {
+  const prefix = `${projectKey}:`
+  return component.startsWith(prefix) ? component.slice(prefix.length) : component
+}
+
+const printFailedConditions = (qualityGate) => {
+  const conditions = qualityGate.projectStatus?.conditions ?? []
+  const failed = conditions.filter((c) => c.status === 'ERROR')
+
+  if (failed.length === 0) return
+
+  console.log(THIN_BORDER)
+  console.log(' ⛔ Failed Conditions')
+
+  for (const condition of failed) {
+    const label = METRIC_LABELS[condition.metricKey] ?? condition.metricKey
+    const comparator = COMPARATOR_SYMBOLS[condition.comparator] ?? condition.comparator
+
+    const actual =
+      condition.metricKey.includes('coverage') || condition.metricKey.includes('duplicat')
+        ? formatPercent(condition.actualValue)
+        : condition.actualValue
+
+    const threshold =
+      condition.metricKey.includes('coverage') || condition.metricKey.includes('duplicat')
+        ? formatPercent(condition.errorThreshold)
+        : condition.errorThreshold
+
+    console.log(`    ${label}: ${actual} (threshold ${comparator} ${threshold})`)
+  }
+}
+
+const printIssues = (issuesResponse, projectKey) => {
+  const issues = issuesResponse?.issues ?? []
+  const total = issuesResponse?.total ?? issues.length
+
+  if (issues.length === 0) return
+
+  // Sort by severity
+  issues.sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity))
+
+  // Group by file
+  const byFile = new Map()
+
+  for (const issue of issues) {
+    const filePath = extractFilePath(issue.component, projectKey)
+    if (!byFile.has(filePath)) byFile.set(filePath, [])
+    byFile.get(filePath).push(issue)
+  }
+
+  const issuesUrl = `${SONARCLOUD_BASE_URL}/project/issues?id=${encodeURIComponent(projectKey)}&resolved=false&inNewCodePeriod=true`
+
+  console.log(`\n${BORDER}`)
+  console.log(` 🐛 Issues (${total} total)`)
+  console.log(BORDER)
+
+  let displayed = 0
+
+  for (const [filePath, fileIssues] of [...byFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (displayed >= MAX_ISSUES_DISPLAYED) break
+
+    console.log(`\n  📄 ${filePath}`)
+
+    for (const issue of fileIssues) {
+      if (displayed >= MAX_ISSUES_DISPLAYED) break
+
+      const icon = SEVERITY_ICONS[issue.severity] ?? '⚪'
+      const rule = issue.rule ? ` (${issue.rule})` : ''
+
+      console.log(`    ${icon} L${issue.line ?? '?'} ${issue.message}${rule}`)
+
+      const issueUrl = `${SONARCLOUD_BASE_URL}/project/issues?id=${encodeURIComponent(projectKey)}&open=${encodeURIComponent(issue.key)}`
+      console.log(`       ${issueUrl}`)
+
+      displayed++
+    }
+  }
+
+  if (total > MAX_ISSUES_DISPLAYED) {
+    console.log(`\n  ... and ${total - MAX_ISSUES_DISPLAYED} more`)
+  }
+
+  console.log(THIN_BORDER)
+  console.log(` 🔗 ${issuesUrl}`)
+  console.log(`${BORDER}\n`)
+}
+
+const formatIssueStatus = (status) => {
+  if (status === 'FALSE_POSITIVE') return 'False positive'
+  if (status === 'ACCEPTED') return 'Accepted'
+  return status ?? 'Unknown'
+}
+
+const printAcceptedIssuesWithoutComment = (issuesWithoutComment, projectKey) => {
+  if (issuesWithoutComment.length === 0) return false
+
+  const issuesUrl = `${SONARCLOUD_BASE_URL}/project/issues?id=${encodeURIComponent(projectKey)}&issueStatuses=${ACCEPTED_ISSUE_STATUSES.join(',')}`
+
+  console.log(`\n${BORDER}`)
+  console.log(` 💬 Accepted / False Positive Issues without Comment (${issuesWithoutComment.length})`)
+  console.log(BORDER)
+  console.log('  DEFRA quality gates require a justification comment on each accepted issue.')
+  console.log('  Add a comment in SonarCloud under the issue Activity tab.\n')
+
+  const byFile = new Map()
+
+  for (const { issue } of issuesWithoutComment) {
+    const filePath = extractFilePath(issue.component, projectKey)
+    if (!byFile.has(filePath)) byFile.set(filePath, [])
+    byFile.get(filePath).push(issue)
+  }
+
+  let displayed = 0
+
+  for (const [filePath, fileIssues] of [...byFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (displayed >= MAX_ISSUES_DISPLAYED) break
+
+    console.log(`\n  📄 ${filePath}`)
+
+    for (const issue of fileIssues) {
+      if (displayed >= MAX_ISSUES_DISPLAYED) break
+
+      const icon = SEVERITY_ICONS[issue.severity] ?? '⚪'
+      const rule = issue.rule ? ` (${issue.rule})` : ''
+      const status = formatIssueStatus(issue.issueStatus ?? issue.status)
+
+      console.log(`    ${icon} [${status}] L${issue.line ?? '?'} ${issue.message}${rule}`)
+
+      const issueUrl = `${SONARCLOUD_BASE_URL}/project/issues?id=${encodeURIComponent(projectKey)}&open=${encodeURIComponent(issue.key)}`
+      console.log(`       ${issueUrl}`)
+
+      displayed++
+    }
+  }
+
+  if (issuesWithoutComment.length > MAX_ISSUES_DISPLAYED) {
+    console.log(`\n  ... and ${issuesWithoutComment.length - MAX_ISSUES_DISPLAYED} more`)
+  }
+
+  console.log(THIN_BORDER)
+  console.log(` 🔗 ${issuesUrl}`)
+  console.log(`${BORDER}\n`)
+
+  return true
+}
+
+const printHotspots = (hotspotsResponse, projectKey) => {
+  const hotspots = hotspotsResponse?.hotspots ?? []
+
+  if (hotspots.length === 0) return
+
+  const total = hotspotsResponse?.paging?.total ?? hotspots.length
+
+  console.log(`\n${BORDER}`)
+  console.log(` 🔥 Security Hotspots (${total} to review)`)
+  console.log(BORDER)
+
+  let displayed = 0
+
+  for (const hotspot of hotspots) {
+    if (displayed >= MAX_ISSUES_DISPLAYED) break
+
+    const filePath = extractFilePath(hotspot.component, projectKey)
+    const icon = HOTSPOT_ICONS[hotspot.vulnerabilityProbability] ?? '🟡'
+    const probability = hotspot.vulnerabilityProbability ?? 'UNKNOWN'
+
+    console.log(`\n  📄 ${filePath}`)
+    console.log(`    ${icon} [${probability}] L${hotspot.line ?? '?'} ${hotspot.message}`)
+
+    const hotspotUrl = `${SONARCLOUD_BASE_URL}/security_hotspots?id=${encodeURIComponent(projectKey)}&hotspots=${encodeURIComponent(hotspot.key)}`
+    console.log(`       ${hotspotUrl}`)
+
+    displayed++
+  }
+
+  if (total > MAX_ISSUES_DISPLAYED) {
+    console.log(`\n  ... and ${total - MAX_ISSUES_DISPLAYED} more`)
+  }
+
+  const hotspotsUrl = `${SONARCLOUD_BASE_URL}/security_hotspots?id=${encodeURIComponent(projectKey)}&inNewCodePeriod=true`
+  console.log(THIN_BORDER)
+  console.log(` 🔗 ${hotspotsUrl}`)
+  console.log(`${BORDER}\n`)
+}
+
+const printSummary = (qualityGate, measuresResponse, projectKey, branch) => {
+  const measures = measuresResponse.component?.measures ?? []
+  const status = qualityGate.projectStatus?.status
+
+  const passed = status === 'OK'
+  const statusLabel = passed ? '✅ PASSED' : status === 'WARN' ? '⚠️  WARN' : '❌ FAILED'
+
+  // Issues
+  const newIssues = getMeasureValue(measures, 'new_violations')
+  const acceptedIssues = getMeasureValue(measures, 'accepted_issues')
+
+  // Measures
+  const securityHotspots = getMeasureValue(measures, 'security_hotspots')
+  const coverageOnNew = formatPercent(getMeasureValue(measures, 'new_coverage'))
+  const duplicationOnNew = formatPercent(getMeasureValue(measures, 'new_duplicated_lines_density'))
+
+  const dashboardUrl = `${SONARCLOUD_BASE_URL}/summary/overall?id=${encodeURIComponent(projectKey)}`
+
+  console.log(`\n${BORDER}`)
+  console.log(` SonarCloud Quality Gate: ${statusLabel}`)
+  console.log(BORDER)
+  console.log(' Issues')
+  console.log(row('New Issues:', newIssues))
+  console.log(row('Accepted Issues:', acceptedIssues))
+  console.log(' Measures')
+  console.log(row('Security Hotspots:', securityHotspots))
+  console.log(row('Coverage on New Code:', coverageOnNew))
+  console.log(row('Duplication on New Code:', duplicationOnNew))
+
+  if (!passed) {
+    printFailedConditions(qualityGate)
+  }
+
+  console.log(BORDER)
+  console.log(` 🔀 Branch: ${branch}`)
+  console.log(` 🔗 ${dashboardUrl}`)
+  console.log(`${BORDER}\n`)
+
+  return passed || status === 'WARN'
+}
+
+const sonarScan = async () => {
+  const cwd = resolve('.')
+
+  // Load .env if present (mirrors `source .env` from the old npm script)
+  try {
+    const envVars = parseKeyValue(readFileSync(resolve(cwd, '.env'), 'utf8'))
+    for (const [key, value] of Object.entries(envVars)) {
+      process.env[key] ??= value
+    }
+  } catch {
+    // .env file is optional — SONAR_TOKEN may already be in the environment
+  }
+
+  const sonarToken = process.env.SONAR_TOKEN
+
+  if (!sonarToken) {
+    console.error('Error: SONAR_TOKEN is not set. Add it to your .env file.')
+    process.exit(1)
+  }
+
+  // Read project config from sonar-project.properties
+  const propsPath = resolve(cwd, 'sonar-project.properties')
+  const props = parseKeyValue(readFileSync(propsPath, 'utf8'))
+  const projectKey = props['sonar.projectKey']
+
+  if (!projectKey) {
+    console.error('Error: sonar.projectKey not found in sonar-project.properties')
+    process.exit(1)
+  }
+
+  // Detect current branch so the scan targets it on SonarCloud
+  const branch = getCurrentBranch()
+  console.log(`\n🔀 Branch: ${branch}\n`)
+
+  // Run the scanner — resolves with exit code (0 = success, non-zero = quality
+  // gate failed or scan error). We always attempt to fetch the summary.
+  const scanCode = await runScanner(sonarToken, cwd, branch)
+
+  // Fetch quality gate + metrics and print summary
+  let qualityGate, measuresResponse
+
+  try {
+    ;[qualityGate, measuresResponse] = await Promise.all([
+      fetchQualityGate(projectKey, sonarToken, branch),
+      fetchMeasures(projectKey, sonarToken, branch)
+    ])
+  } catch (apiErr) {
+    // API fetch failed — the scan likely didn't upload (e.g. auth error, network)
+    if (scanCode !== 0) {
+      console.error(`\nSonar scanner exited with code ${scanCode}. No results to display.`)
+      process.exit(scanCode)
+    }
+
+    throw apiErr
+  }
+
+  const passed = printSummary(qualityGate, measuresResponse, projectKey, branch)
+
+  let hasAcceptedIssuesWithoutComment = false
+
+  try {
+    const issuesWithoutComment = await findAcceptedIssuesWithoutComment(projectKey, sonarToken)
+    hasAcceptedIssuesWithoutComment = printAcceptedIssuesWithoutComment(issuesWithoutComment, projectKey)
+  } catch (acceptedErr) {
+    console.error(`\nCould not fetch accepted/false-positive issue comments: ${acceptedErr.message}`)
+  }
+
+  if (!passed || hasAcceptedIssuesWithoutComment) {
+    // Fetch detailed issues and hotspots to help developers fix problems locally
+    try {
+      const measures = measuresResponse.component?.measures ?? []
+      const hotspotCount = getMeasureValue(measures, 'security_hotspots')
+      const shouldFetchHotspots = hotspotCount !== 'N/A' && parseInt(hotspotCount, 10) > 0
+
+      const fetches = [fetchIssues(projectKey, sonarToken, branch)]
+
+      if (shouldFetchHotspots) {
+        fetches.push(fetchSecurityHotspots(projectKey, sonarToken, branch))
+      }
+
+      const [issuesResponse, hotspotsResponse] = await Promise.all(fetches)
+
+      printIssues(issuesResponse, projectKey)
+
+      if (hotspotsResponse) {
+        printHotspots(hotspotsResponse, projectKey)
+      }
+    } catch (detailErr) {
+      console.error(`\nCould not fetch issue details: ${detailErr.message}`)
+    }
+
+    process.exit(1)
+  }
+}
+
+sonarScan().catch((err) => {
+  console.error(`\nSonar scan failed: ${err.message}`)
+  process.exit(1)
+})

package/src/mappers/address-mapper.js

@@ -0,0 +1,32 @@
+/**
+ * Takes the raw address data and maps it to a more usable format
+ *
+ * @param {Object} address - The raw address data
+ *
+ * @returns {Object} Formatted address data
+ */
+export const mapAddress = (address = {}) => {
+  return {
+    lookup: {
+      pafOrganisationName: address.pafOrganisationName,
+      buildingNumberRange: address.buildingNumberRange,
+      flatName: address.flatName,
+      buildingName: address.buildingName,
+      dependentLocality: address.dependentLocality,
+      doubleDependentLocality: address.doubleDependentLocality,
+      street: address.street,
+      county: address.county,
+      uprn: address.uprn
+    },
+    manual: {
+      line1: address.line1,
+      line2: address.line2,
+      line3: address.line3,
+      line4: address.line4,
+      line5: address.line5
+    },
+    city: address.city,
+    postcode: address.postalCode,
+    country: address.country
+  }
+}

package/src/mappers/customer-name-mapper.js

@@ -0,0 +1,16 @@
+/**
+ * Takes the raw customer name data and maps it to a more usable format
+ *
+ * @param {Object} value - The data from the DAL
+ *
+ * @returns {Object} Formatted customer name data
+ */
+
+export const mapCustomerName = (name = {}) => {
+  return {
+    userName: [
+      name.first,
+      name.last
+    ].filter(Boolean).join(' ')
+  }
+}

package/src/mappers/mappers.js

@@ -1,5 +1,9 @@
 import { mapPersonalBusinessDetails } from './personal-business-details-mapper.js'
+import { mapAddress } from './address-mapper.js'
+import { mapCustomerName } from './customer-name-mapper.js'
 
 export const mappers = {
-  mapPersonalBusinessDetails
+  personalBusinessDetails: mapPersonalBusinessDetails,
+  address: mapAddress,
+  customerName: mapCustomerName
 }

package/src/mappers/personal-business-details-mapper.js

@@ -22,4 +22,4 @@ export const mapPersonalBusinessDetails = (value) => {
       }
     }
   }
-}
+}