fix(release): select historical chart sources

Prefer tagged source charts during historical inventory bootstrap, and fall back to published charts only when the source path is unavailable in the selected tag.

Refs #1838

Author: sbaum1994

.github/workflows/release-tags.yml

@@ -189,7 +189,7 @@ jobs:
           else
             echo "WARNING: ${INVENTORY_TAG} predates its per-stack inventory states; using ${bootstrap_config}." >&2
             inventory_config="${bootstrap_config}"
-            inventory_args+=(--use-published-charts)
+            inventory_args+=(--allow-unavailable-source-charts)
           fi
           "${RUNNER_TEMP}/docs-version-sync" \
             --generate-stack-inventory "${RUNNER_TEMP}/stack-inventory.json" \

deploy/stacks/INVENTORY.md

@@ -195,10 +195,10 @@ The manual `inventory_tag` preflight uploads the rendered JSON as a workflow
 artifact. New releases use the inventory config stored in the immutable tag.
 For a release that lacks a config with per-stack states, the preflight uses the
 config from the workflow ref as a bootstrap. The inventory still records and
-renders the selected tag, using the published charts referenced there instead
-of source chart paths that might not exist in the historical commit. This
-fallback is only for validating historical releases. Tags created after this
-workflow lands are self-contained.
+renders the selected tag. It uses source charts available in the historical
+commit and falls back to a published chart when its source path did not exist
+yet. This fallback is only for validating historical releases. Tags created
+after this workflow lands are self-contained.
 
 ## Development Documentation Sync
 

tools/ci/test-github-release.py

@@ -1768,7 +1768,7 @@ def test_stack_inventory_preflight_renders_without_release_publication(self):
         self.assertIn("--inventory-config", preflight_workflow)
         self.assertIn("grep -q '^states:'", preflight_workflow)
         self.assertIn("predates its per-stack inventory states", preflight_workflow)
-        self.assertIn("--use-published-charts", preflight_workflow)
+        self.assertIn("--allow-unavailable-source-charts", preflight_workflow)
         self.assertIn("actions/upload-artifact@v4", preflight_workflow)
         self.assertIn("if-no-files-found: error", preflight_workflow)
         self.assertNotIn("github-release tag", preflight_workflow)

tools/docs-version-sync/README.md

@@ -189,8 +189,9 @@ directory normally contains three separated inventories.
 Use the `inventory_tag` input on `release-tags.yml` to reproduce an inventory
 without publishing a release. The preflight uploads the JSON as a workflow
 artifact. Tags that lack a config with per-stack states use the config from the
-workflow ref as a one-time bootstrap and render their published chart versions.
-New tags carry their own config.
+workflow ref as a one-time bootstrap. They use an available tagged source chart
+and otherwise render the published chart version. New tags carry their own
+config.
 
 ## Validation
 

tools/docs-version-sync/main.go

@@ -45,7 +45,7 @@ func run(args []string) error {
 	qualificationVersion := flags.String("qualification-version", "", "documentation version for an exact QA-qualified three-stack release set")
 	inventoryOutput := flags.String("generate-stack-inventory", "", "write a resolved stack inventory to this path")
 	inventoryConfig := flags.String("inventory-config", "", "release inventory config path; defaults to the stack checkout")
-	usePublishedCharts := flags.Bool("use-published-charts", false, "render inventory with published charts instead of configured source charts")
+	allowUnavailableSourceCharts := flags.Bool("allow-unavailable-source-charts", false, "use published charts when configured source paths are unavailable in a historical tag")
 	stackSourceTag := flags.String("stack-source-tag", "", "immutable owning stack source tag for inventory generation")
 	stackSourceCommit := flags.String("stack-source-commit", "", "immutable owning stack source commit for inventory generation")
 	compareFrom := flags.String("compare-release-set-from", "", "directory containing previous release-set inventory JSON files")
@@ -71,7 +71,7 @@ func run(args []string) error {
 		}
 		if *updateCatalog || *check || *inventoryOutput != "" || *qualificationVersion != "" ||
 			*stackVersion != "" || *computeStackVersion != "" || *observabilityStackVersion != "" ||
-			*inventoryConfig != "" || *usePublishedCharts || *stackSourceTag != "" || *stackSourceCommit != "" {
+			*inventoryConfig != "" || *allowUnavailableSourceCharts || *stackSourceTag != "" || *stackSourceCommit != "" {
 			return fmt.Errorf("release-set comparison cannot be combined with catalog update, check, or inventory generation flags")
 		}
 		fromPath := resolveRepoPath(repoRoot, *compareFrom)
@@ -105,7 +105,7 @@ func run(args []string) error {
 			Tag:     *stackSourceTag,
 			Commit:  *stackSourceCommit,
 		}, resolvedInventoryGenerationOptions{
-			UsePublishedCharts: *usePublishedCharts,
+			AllowUnavailableSourceCharts: *allowUnavailableSourceCharts,
 		})
 	}
 	if !*updateCatalog && (*computeStackVersion != "" || *observabilityStackVersion != "") {
@@ -122,8 +122,8 @@ func run(args []string) error {
 			return fmt.Errorf("--qualification-version requires exact control-plane, compute-plane, and observability stack versions")
 		}
 	}
-	if *stackSourceTag != "" || *stackSourceCommit != "" || *inventoryConfig != "" || *usePublishedCharts {
-		return fmt.Errorf("--stack-source-tag, --stack-source-commit, --inventory-config, and --use-published-charts require --generate-stack-inventory")
+	if *stackSourceTag != "" || *stackSourceCommit != "" || *inventoryConfig != "" || *allowUnavailableSourceCharts {
+		return fmt.Errorf("--stack-source-tag, --stack-source-commit, --inventory-config, and --allow-unavailable-source-charts require --generate-stack-inventory")
 	}
 	if *catalogPath == "" {
 		*catalogPath = filepath.Join(repoRoot, "docs", "version-catalog", *target+".yaml")

tools/docs-version-sync/resolved_inventory_publish.go

@@ -162,7 +162,7 @@ type resolvedInventoryConfig struct {
 }
 
 type resolvedInventoryGenerationOptions struct {
-	UsePublishedCharts bool
+	AllowUnavailableSourceCharts bool
 }
 
 type resolvedInventorySourceChart struct {
@@ -245,9 +245,6 @@ func collectResolvedStackInventory(repoRoot, configPath string, source stackSour
 	if err != nil {
 		return resolvedStackInventory{}, err
 	}
-	if options.UsePublishedCharts {
-		config.SourceCharts = nil
-	}
 	states := config.States
 	if len(states) == 0 {
 		return resolvedStackInventory{}, fmt.Errorf("resolved inventory config must declare at least one stack-owned state")
@@ -292,6 +289,7 @@ func collectResolvedStackInventory(repoRoot, configPath string, source stackSour
 			renderSource,
 			config.PublishedChartRepository,
 			config.SourceCharts,
+			options.AllowUnavailableSourceCharts,
 			ngcAPIKey,
 			runner,
 		)
@@ -334,9 +332,11 @@ func collectResolvedStackInventory(repoRoot, configPath string, source stackSour
 			plane.ManifestByRelease[release] = manifest
 		}
 	}
-	for chart := range config.SourceCharts {
-		if _, used := usedSourceCharts[chart]; !used {
-			return resolvedStackInventory{}, fmt.Errorf("source chart %s is not used by any resolved Helmfile state", chart)
+	if !options.AllowUnavailableSourceCharts {
+		for chart := range config.SourceCharts {
+			if _, used := usedSourceCharts[chart]; !used {
+				return resolvedStackInventory{}, fmt.Errorf("source chart %s is not used by any resolved Helmfile state", chart)
+			}
 		}
 	}
 
@@ -708,6 +708,7 @@ func collectResolvedInventoryState(
 	renderSource resolvedInventoryHelmSource,
 	publishedChartRepository string,
 	sourceCharts map[string]resolvedInventorySourceChart,
+	allowUnavailableSourceCharts bool,
 	ngcAPIKey string,
 	runner resolvedInventoryCommandRunner,
 ) ([]helmfileRelease, map[string][]byte, []string, error) {
@@ -728,6 +729,7 @@ func collectResolvedInventoryState(
 		source,
 		fullList,
 		sourceCharts,
+		allowUnavailableSourceCharts,
 	)
 	if err != nil {
 		return nil, nil, nil, err
@@ -795,6 +797,7 @@ func materializeResolvedInventorySourceCharts(
 	stackSource stackSourceRelease,
 	fullRaw []byte,
 	sourceCharts map[string]resolvedInventorySourceChart,
+	allowUnavailableSourceCharts bool,
 ) ([]string, error) {
 	if len(sourceCharts) == 0 {
 		return nil, nil
@@ -820,6 +823,12 @@ func materializeResolvedInventorySourceCharts(
 			return nil, fmt.Errorf("source chart %s release %s version %q is not semantic", name, release.Name, release.Version)
 		}
 		tag := sourceChart.TagPrefix + release.Version
+		if _, err := gitOutput(repoRoot, "cat-file", "-e", tag+":"+sourceChart.Path); err != nil {
+			if allowUnavailableSourceCharts {
+				continue
+			}
+			return nil, fmt.Errorf("source chart %s path %s is unavailable at %s: %w", name, sourceChart.Path, tag, err)
+		}
 		if _, err := gitOutput(repoRoot, "merge-base", "--is-ancestor", tag, stackSource.Commit); err != nil {
 			return nil, fmt.Errorf("source chart %s tag %s is not an ancestor of stack commit %s: %w", name, tag, stackSource.Commit, err)
 		}

tools/docs-version-sync/resolved_inventory_publish_test.go

@@ -102,6 +102,53 @@ releases:
 	}
 }
 
+func TestMaterializeResolvedInventorySourceChartsAllowsUnavailableHistoricalPath(t *testing.T) {
+	repo := initTestGitRepo(t)
+	source := commitTestStackSource(t, repo, "1.2.3", map[string]string{
+		"deploy/stacks/self-managed/helmfile.d/state.yaml.gotmpl": "releases: []\n",
+	})
+	fullRaw := mustJSON(t, []helmfileRelease{{
+		Name:    "example",
+		Chart:   "nvcf/helm-example",
+		Version: "1.0.0",
+	}})
+	sourceCharts := map[string]resolvedInventorySourceChart{
+		"helm-example": {
+			TagPrefix: "deploy/helm/example/v",
+			Path:      "deploy/helm/example",
+		},
+	}
+
+	used, err := materializeResolvedInventorySourceCharts(
+		repo,
+		filepath.Join(repo, "deploy/stacks/self-managed/helmfile.d/state.yaml.gotmpl"),
+		t.TempDir(),
+		source,
+		fullRaw,
+		sourceCharts,
+		true,
+	)
+	if err != nil {
+		t.Fatalf("historical source-chart fallback failed: %v", err)
+	}
+	if len(used) != 0 {
+		t.Fatalf("used source charts = %v, want published chart fallback", used)
+	}
+
+	_, err = materializeResolvedInventorySourceCharts(
+		repo,
+		filepath.Join(repo, "deploy/stacks/self-managed/helmfile.d/state.yaml.gotmpl"),
+		t.TempDir(),
+		source,
+		fullRaw,
+		sourceCharts,
+		false,
+	)
+	if err == nil || !strings.Contains(err.Error(), "is unavailable") {
+		t.Fatalf("strict source-chart error = %v, want unavailable path", err)
+	}
+}
+
 func TestCollectResolvedStackInventoryBuildsConfiguredSelfManagedStates(t *testing.T) {
 	t.Setenv("NVCF_RELEASE_NGC_API_KEY", "test-api-key")
 	t.Setenv("NVCF_RELEASE_HELM_REGISTRY", "registry.example.test/release/charts")