Checkpoint Lab — Monorepos, Multi-Module Builds, Generated Code, and Complex Repository Layouts

1. Checkpoint scenario

You own one synthetic Git repository with an API module and a worker module. The teams release independently, so the governed target topology is two SonarQube projects. You must prove that each project analyzes only its own files, imports only its own report, uses its own scanner workspace/token, and retains an independent asynchronous task chain.

You will also run one intentionally wrong worker coverage path, preserve the failure, correct it without changing the Git SHA, and finish with a timestamped Community Build governance summary plus an edition-aware aggregation plan.

2. Exact assumptions and preflight

git rev-parse --show-toplevel | tee evidence/repo-root.txt
git rev-parse HEAD | tee evidence/checkpoint-revision.txt
git status --short | tee evidence/git-status.txt
sonar-scanner --version | tee evidence/scanner-version.txt
python --version | tee evidence/python-version.txt
curl -fsS "$SONAR_HOST_URL/api/system/status" | tee evidence/server-status.json

3. Write the ownership manifest before scanning

repository: sq-ch24-layout-lab
revision: "<exact git sha>"
projects:
  - key: sq-ch24-api
    owner: team-api
    base_dir: modules/api
    sources: [src]
    tests: [tests]
    coverage: coverage.xml
    scanner_workdir: .scannerwork-ch24-api
    token_owner: project-analysis-token-api
  - key: sq-ch24-worker
    owner: team-worker
    base_dir: modules/worker
    sources: [src]
    tests: [tests]
    coverage: coverage.xml
    scanner_workdir: .scannerwork-ch24-worker
    token_owner: project-analysis-token-worker
generated:
  generated/: excluded-from-owned-project-scopes
vendor:
  vendor/: external/dependency ownership, not first-party module source
parallelism:
  distinct_projects: permitted with isolated work/report artifacts
  same_project_branch: serialize/supersede deterministically

4. Required predictions before execution

• Prediction A — indexing: API analysis will index modules/api/src only; worker analysis will index modules/worker/src only. Generated/vendor files will not enter either project because they are outside both initial scopes.
• Prediction B — path defect: with worker projectBaseDir=modules/worker, setting sonar.python.coverage.reportPaths=modules/worker/coverage.xml will fail to import the intended coverage report even though source indexing still succeeds.
• Prediction C — repair: changing only that value to coverage.xml at the same Git SHA will restore report-import evidence.
• Prediction D — governance: Community Build will keep API and worker as independent project histories; any cross-project aggregate produced in this checkpoint is an external summary, not a native Application/Portfolio object.

Write these predictions into evidence/predictions.md before running the broken scan.

5. Produce reports and prove their internal paths

(
  cd modules/api
  ../../.venv/bin/python -m pytest tests --cov=src --cov-report=xml:coverage.xml
)
(
  cd modules/worker
  ../../.venv/bin/python -m pytest tests --cov=src --cov-report=xml:coverage.xml
)

sha256sum modules/api/coverage.xml modules/worker/coverage.xml \
  | tee evidence/report-sha256.txt

grep -n 'filename=' modules/api/coverage.xml | head -20 \
  | tee evidence/api-report-files.txt
grep -n 'filename=' modules/worker/coverage.xml | head -20 \
  | tee evidence/worker-report-files.txt

6. Analyze API with its owned coordinate system

SONAR_TOKEN="$SONAR_TOKEN_API" sonar-scanner -X \
  -Dsonar.projectKey=sq-ch24-api \
  -Dsonar.projectBaseDir=modules/api \
  -Dsonar.sources=src \
  -Dsonar.tests=tests \
  -Dsonar.python.coverage.reportPaths=coverage.xml \
  -Dsonar.working.directory=.scannerwork-ch24-api \
  2>&1 | tee evidence/api-scanner.log

cp modules/api/.scannerwork-ch24-api/report-task.txt evidence/api-report-task.txt
API_TASK="$(sed -n 's/^ceTaskId=//p' evidence/api-report-task.txt)"
echo "$API_TASK" | tee evidence/api-ceTaskId.txt

Wait for Compute Engine terminal success, then capture ncloc, coverage, Quality Gate and issue counts. Also preserve the scanner lines proving which files were indexed/imported.

7. Run and preserve the deliberate worker defect

git rev-parse HEAD | tee evidence/worker-broken-revision.txt

SONAR_TOKEN="$SONAR_TOKEN_WORKER" sonar-scanner -X \
  -Dsonar.projectKey=sq-ch24-worker \
  -Dsonar.projectBaseDir=modules/worker \
  -Dsonar.sources=src \
  -Dsonar.tests=tests \
  -Dsonar.python.coverage.reportPaths=modules/worker/coverage.xml \
  -Dsonar.working.directory=.scannerwork-ch24-worker-broken \
  2>&1 | tee evidence/worker-broken-scanner.log

cp modules/worker/.scannerwork-ch24-worker-broken/report-task.txt \
  evidence/worker-broken-report-task.txt

grep -Ei 'coverage|report.*not|no report|cannot' \
  evidence/worker-broken-scanner.log \
  | tee evidence/worker-broken-import-evidence.txt || true

Do not delete or overwrite this log. Capture the broken ceTaskId and terminal task state too. A successful CE task does not invalidate the report-import warning.

8. Repair only the path and prove the same SHA

SONAR_TOKEN="$SONAR_TOKEN_WORKER" sonar-scanner -X \
  -Dsonar.projectKey=sq-ch24-worker \
  -Dsonar.projectBaseDir=modules/worker \
  -Dsonar.sources=src \
  -Dsonar.tests=tests \
  -Dsonar.python.coverage.reportPaths=coverage.xml \
  -Dsonar.working.directory=.scannerwork-ch24-worker-fixed \
  2>&1 | tee evidence/worker-fixed-scanner.log

cp modules/worker/.scannerwork-ch24-worker-fixed/report-task.txt \
  evidence/worker-fixed-report-task.txt

git rev-parse HEAD | tee evidence/worker-fixed-revision.txt
cmp evidence/worker-broken-revision.txt evidence/worker-fixed-revision.txt

WORKER_TASK="$(sed -n 's/^ceTaskId=//p' evidence/worker-fixed-report-task.txt)"
echo "$WORKER_TASK" | tee evidence/worker-fixed-ceTaskId.txt

After terminal CE success, capture worker measures and compare scanner import evidence. The conclusion must say “report-path repair changed imported analysis evidence at the same revision,” not “coverage improved because code was fixed.”

9. Community Build aggregation fallback

Generate a timestamped Markdown summary from project-level APIs. Keep every row linked to its project and task/revision evidence. This is a governance report you own; it is not a SonarQube Application or Portfolio.

# summarize.py (conceptual excerpt)
projects = ["sq-ch24-api", "sq-ch24-worker"]
metrics = "ncloc,coverage,reliability_rating,security_rating,sqale_rating"
# GET /api/measures/component for each exact project key.
# Also query/record each project's Quality Gate status and latest analysis timestamp.
# Emit one row per project; never add percentages together naively.

10. Edition-aware aggregation plan

• Community Build: retain two independently governed projects and the external timestamped summary.
• Developer Edition+: if API and worker truly share a release lifecycle, consider an Application; otherwise keep them independent.
• Enterprise Edition: native monorepo onboarding/binding can associate multiple SonarQube projects with the same DevOps repository; Portfolios can provide broader governance views.
• Regardless of edition: preserve per-project scope/report/task evidence. Aggregation does not repair ownership.

11. Required evidence packet

12. Verification checklist

• ☐ API and worker use distinct project keys, project tokens and working directories.
• ☐ Both successful module scans refer to the same intended Git SHA.
• ☐ API indexing evidence contains no worker source and worker indexing evidence contains no API source.
• ☐ Generated/vendor files remain outside the chosen project scopes for a documented reason.
• ☐ Broken worker scan preserves the wrong report path and first warning/task evidence.
• ☐ Fixed worker scan changes only the report-path coordinate and imports the report.
• ☐ Scanner success, CE success, gate state and CI outcome are recorded separately.
• ☐ Community summary does not claim native Application/Portfolio semantics.
• ☐ Optional commercial capabilities are labeled with edition prerequisites.

13. Cleanup and rollback

• Revoke all three disposable project-analysis tokens and verify they no longer authenticate.
• Export the evidence packet before deleting the three lab projects.
• Delete only sq-ch24-* projects that you created for the lab; do not touch unrelated projects.
• Remove the local fixture only after the evidence packet has been preserved.
• Do not prune shared Docker volumes/databases or alter global quality profiles/gates as cleanup shortcuts.

14. What Chapter 24 adds to the operating model

Chapter 24 makes repository complexity an explicit governance object. Project keys, module owners, base directories, indexed source, generated/vendor policy, reports, scanner workspaces, concurrency and task evidence are now versioned as one topology contract. This prevents “green by omission” and “red by overlap” before those errors reach dashboards or executive views.

Chapter 25 continues into Portfolios, Applications, Enterprise Reporting, and Governance Boundaries, where the course will aggregate already-correct project evidence without hiding metric semantics or edition boundaries.

Knowledge check

Official references and version notes

• Community Build — analysis parameters not settable in UI — sonar.projectBaseDir, sonar.sources, sonar.tests, sonar.working.directory, report-task path and token guidance.
• Community Build — setting initial scope — source/test roots are simple paths relative to project base directory; no wildcards in initial roots.
• Community Build — analysis-scope introduction — generated/library code, coverage/duplication exclusions and verification workflow.
• Community Build — test coverage parameters — externally generated reports and project-root-relative path rules.
• Community Build — SonarScanner CLI — alternate project base directory behavior and CLI configuration.
• Community Build — Java/multi-module coverage — build-native JaCoCo generation and multi-module aggregation patterns.
• SonarQube Server — managing monorepo projects — Enterprise monorepo feature, multiple SonarQube projects bound to one repository, unique project keys and manual project definition.
• SonarQube Server — Applications — synthetic aggregation for projects sharing a lifecycle; commercial feature.
• SonarQube Server — Portfolios — Enterprise governance aggregation.
• SonarScanner CLI releases — current public scanner release baseline.
• SonarQube downloads — current Community Build/Server/LTA release identities.