fix(Makefile): enhance comments for clarity and update caching strategy in build process

Signed-off-by: Adilhusain Shaikh <[email protected]>

Author: adilhusain-s

Makefile

@@ -1,5 +1,6 @@
 # ==============================================================================
 # Project: Python Build System (Containerized & Secured)
+# Description: Multi-stage build system with caching and security gates.
 # ==============================================================================
 
 # --- Configuration & Defaults -------------------------------------------------
@@ -13,24 +14,24 @@ else
   Q :=
 endif
 
-# Versioning
+# --- Versioning ---------------------------------------------------------------
 PYTHON_VERSION          ?= 3.13.3
 ACTIONS_PYTHON_VERSIONS ?= 3.13.3-14344076652
 POWERSHELL_VERSION      ?= v7.5.2
 POWERSHELL_NATIVE_VERSION ?= v7.4.0
 UBUNTU_VERSION          ?= 24.04
 
-# [UPDATED] Security Scanning & Gates
-# Latest Trivy version as of Dec 2025
+# --- Security Scanning --------------------------------------------------------
+# Latest Trivy version (Dec 2025)
 TRIVY_VERSION           ?= v0.68.2
 
-# [UPDATED] Gates Enabled (1 = Fail Build)
+# Gates: 0 = Log Only, 1 = Fail Build
 FAIL_ON_CRITICAL        ?= 1
 FAIL_ON_HIGH            ?= 1
 FAIL_ON_MEDIUM          ?= 0
 FAIL_ON_SECRET          ?= 1
 
-# Architecture
+# --- System Architecture ------------------------------------------------------
 ARCH_RAW := $(shell uname -m)
 ifeq ($(ARCH_RAW),x86_64)
   ARCH := amd64
@@ -40,22 +41,24 @@ else
   ARCH := $(ARCH_RAW)
 endif
 
-# Container Engine
+# --- Container Engine ---------------------------------------------------------
 CONTAINER_ENGINE := $(shell command -v podman 2>/dev/null || command -v docker)
 ifeq ($(strip $(CONTAINER_ENGINE)),)
   $(error No container runtime found. Please install `docker` or `podman`)
 endif
 
 # --- Internal Variables -------------------------------------------------------
 
+# The base image tag used internally between stages
 BASE_IMAGE := powershell:ubuntu-$(UBUNTU_VERSION)
 
 OUTPUT_DIR := python-versions/output
 IMAGE_NAME := python:$(PYTHON_VERSION)-ubuntu-$(UBUNTU_VERSION)-$(ARCH)
 TEMP_CONTAINER_NAME := python-build-$(PYTHON_VERSION)-$(ARCH)-tmp
 
+# Artifact filenames
 INTERNAL_ARTIFACT_NAME := python-$(PYTHON_VERSION)-linux-$(ARCH).tar.gz
-HOST_ARTIFACT_NAME := python-$(PYTHON_VERSION)-linux-$(UBUNTU_VERSION)-$(ARCH).tar.gz
+HOST_ARTIFACT_NAME     := python-$(PYTHON_VERSION)-linux-$(UBUNTU_VERSION)-$(ARCH).tar.gz
 
 PS_DIR := PowerShell
 PS_PREREQS := \
@@ -66,20 +69,17 @@ PS_PREREQS := \
 
 # --- Build Strategy Logic -----------------------------------------------------
 
-# Default: Standard local build
+# Default: Standard local build (Works for local dev)
 BUILD_CMD  := $(CONTAINER_ENGINE) build
 BUILD_OPTS := 
 
-# GHA Override: Use Buildx with Caching and explicit Loading
+# GHA Override: Use Buildx with Caching
+# Critical Fix: We use '--load' to ensure the built image is exported 
+# from the isolated BuildKit container to the local Docker daemon.
 ifeq ($(USE_GHA_CACHE),1)
   BUILDX_BUILDER ?= gha-builder
-  CACHE_SCOPE ?= default
-  
   BUILD_CMD := $(CONTAINER_ENGINE) buildx build
-  BUILD_OPTS := --builder $(BUILDX_BUILDER) \
-                --load \
-                --cache-from type=gha,scope=$(CACHE_SCOPE) \
-                --cache-to type=gha,mode=max,scope=$(CACHE_SCOPE)
+  BUILD_OPTS := --builder $(BUILDX_BUILDER) --load
 endif
 
 # --- Targets ------------------------------------------------------------------
@@ -88,11 +88,15 @@ endif
 
 all: $(OUTPUT_DIR)/$(HOST_ARTIFACT_NAME) verify-gate
 
-# 1. Build the Python Artifact
+# 1. Build the Python Artifact (Stage 2)
+# Depends on 'powershell' target being run first to create the BASE_IMAGE
 $(OUTPUT_DIR)/$(HOST_ARTIFACT_NAME): powershell | $(OUTPUT_DIR)
 	@echo "--- Building Python $(PYTHON_VERSION) Image ($(ARCH)) ---"
 	@echo "    Security Gate: CRIT=$(FAIL_ON_CRITICAL) HIGH=$(FAIL_ON_HIGH) SECRET=$(FAIL_ON_SECRET)"
+	
 	$(Q)cd python-versions && $(BUILD_CMD) $(BUILD_OPTS) \
+		--cache-from type=gha,scope=python-$(ARCH)-$(UBUNTU_VERSION) \
+		--cache-to type=gha,mode=max,scope=python-$(ARCH)-$(UBUNTU_VERSION) \
 		--network=host \
 		--build-arg PYTHON_VERSION=$(PYTHON_VERSION) \
 		--build-arg ACTIONS_PYTHON_VERSIONS=$(ACTIONS_PYTHON_VERSIONS) \
@@ -138,10 +142,13 @@ verify-gate:
 		echo ""; \
 	fi
 
-# 3. Build Base PowerShell Image
+# 3. Build Base PowerShell Image (Stage 1)
+# Uses separate cache scope to prevent overwriting the Python cache
 powershell: $(PS_PREREQS)
 	@echo "--- Building PowerShell Base Image ---"
 	$(Q)cd $(PS_DIR) && $(BUILD_CMD) $(BUILD_OPTS) \
+		--cache-from type=gha,scope=powershell-$(ARCH)-$(UBUNTU_VERSION) \
+		--cache-to type=gha,mode=max,scope=powershell-$(ARCH)-$(UBUNTU_VERSION) \
 		--network=host \
 		--build-arg POWERSHELL_VERSION=$(POWERSHELL_VERSION) \
 		--build-arg POWERSHELL_NATIVE_VERSION=$(POWERSHELL_NATIVE_VERSION) \