introduce phase typed program boundaries (#754)

Author: cssbruno

docs/compiler/pipeline.md

@@ -8,6 +8,7 @@ project config plus explicit file paths or configured discovery
   -> lower parsed records into internal/gwdkir.Program
   -> enrich IR with Go endpoint discovery and backend bindings
   -> validate IR invariants, render rules, routes, endpoints, packages, and assets
+     into a compiler-owned ValidatedProgram phase token
   -> emit diagnostics, public manifest JSON, site-map JSON, route/endpoint metadata, build-output artifacts, browser runtime assets, or generated app output
 ```
 
@@ -45,19 +46,34 @@ boundaries so one syntax error does not hide later declarations in the same
 file.
 
 `internal/gwdkanalysis` assembles parsed page, component, and layout records
-into `internal/gwdkir.Program`. The IR models packages, source
-files, page routes, backend endpoints from `.gwdk` declarations or explicit Go
-comments, templates, client behavior, source-selected assets, asset scope/hash
-metadata, parsed view nodes, typed literal records, and imported build-data call
-metadata. `gwdkir.Blocks` retains source bodies for spans and
-compatibility, but the parser-lowered handoff also carries parsed `view {}`
+into `internal/gwdkir.Program`. `internal/compiler.AnalyzedProgram` wraps that
+IR after enrichment, and `internal/compiler.ValidatedProgram` is the opaque
+phase token returned only by compiler validation. Build-output fast paths accept
+`ValidatedProgram`; raw `gwdkir.Program` entrypoints must run compiler
+validation before emission. Static build output resolves page artifacts, CSS,
+assets, manifests, and report metadata into `internal/buildgen.BuildPlan`
+before writing files. Generated app output resolves auto routes, endpoint
+projections, SSR artifacts, sitemap data, and generator-local validation into
+`internal/appgen.ApplicationPlan` before writing files.
+
+The IR models packages, source files, page routes, backend endpoints from
+`.gwdk` declarations or explicit Go comments, templates, client behavior,
+source-selected assets, asset scope/hash metadata, parsed view nodes, typed
+literal records, and imported build-data call metadata.
+
+`gwdkir.Blocks` retains source bodies for spans, formatting, inspection, and
+compatibility only. Parser/analyzer lowering must populate parsed `view {}`
 nodes, ordered literal `paths {}`/`build {}` records, and imported build-data
-call metadata; downstream passes should consume those typed fields before
-falling back to raw bodies. Build, memory build, incremental SPA build, SSR
-artifact, generated app planning, route reports, LSP metadata, and the public
-`gowdk manifest` report consume `internal/gwdkir.Program` and own their output
-planning separately. Route and asset manifests are generated output artifacts,
-not compiler handoff records.
+call metadata before validation. Downstream validation and generated-output
+planning consume those typed fields; raw block bodies are not a semantic fallback
+after lowering. `gwdkir.CheckInvariants` rejects non-empty supported `view {}`
+bodies that reach the IR without parsed view nodes.
+
+Build, memory build, incremental SPA build, SSR artifact, generated app
+planning, route reports, LSP metadata, and the public `gowdk manifest` report
+consume `internal/gwdkir.Program` and own their output planning separately.
+Route and asset manifests are generated output artifacts, not compiler handoff
+records.
 Generated app Go, backend adapter Go, build-data helper Go, and starter config
 Go are constructed as Go ASTs, printed, and formatted before use or write.
 

internal/appgen/appgen.go

@@ -21,13 +21,77 @@ const (
 	modFileName       = "go.mod"
 )
 
+var errInvalidApplicationPlan = fmt.Errorf("application plan was not constructed by appgen planning")
+
 // Generate writes a self-contained Go app that embeds outputDir.
 func Generate(outputDir, appDir string) (Result, error) {
 	return GenerateWithOptions(outputDir, appDir, Options{})
 }
 
+// PlanApplication resolves and validates generated app options before emission.
+func PlanApplication(outputDir string, options Options) (ApplicationPlan, error) {
+	if strings.TrimSpace(outputDir) == "" {
+		return ApplicationPlan{}, fmt.Errorf("build output directory is required")
+	}
+	absOutput, err := filepath.Abs(outputDir)
+	if err != nil {
+		return ApplicationPlan{}, err
+	}
+	planned, err := resolveOptions(absOutput, options)
+	if err != nil {
+		return ApplicationPlan{}, err
+	}
+	if err := validateAppPlanOptions(planned, true); err != nil {
+		return ApplicationPlan{}, err
+	}
+	return ApplicationPlan{options: planned, outputDir: absOutput, valid: true}, nil
+}
+
+// PlanBackendApplication resolves and validates backend-only generated app
+// options before emission.
+func PlanBackendApplication(options Options) (ApplicationPlan, error) {
+	planned, err := resolveBackendOptions(options)
+	if err != nil {
+		return ApplicationPlan{}, err
+	}
+	if err := validateAppPlanOptions(planned, false); err != nil {
+		return ApplicationPlan{}, err
+	}
+	return ApplicationPlan{options: planned, backendOnly: true, valid: true}, nil
+}
+
+func validateAppPlanOptions(options Options, includeSSR bool) error {
+	if err := validateActionEndpoints(options.Actions); err != nil {
+		return err
+	}
+	if err := validateAPIEndpoints(options.APIs); err != nil {
+		return err
+	}
+	if err := validateFragmentEndpoints(options.Fragments); err != nil {
+		return err
+	}
+	if err := validateContractRoutes(options.IR); err != nil {
+		return err
+	}
+	if includeSSR {
+		if err := validateSSRRoutes(options.SSR); err != nil {
+			return err
+		}
+	}
+	return validateCORSConfig(options)
+}
+
 // GenerateWithOptions writes a self-contained Go app that embeds outputDir.
 func GenerateWithOptions(outputDir, appDir string, options Options) (result Result, err error) {
+	plan, err := PlanApplication(outputDir, options)
+	if err != nil {
+		return Result{}, err
+	}
+	return GenerateWithPlan(outputDir, appDir, plan)
+}
+
+// GenerateWithPlan writes a self-contained Go app from an application plan.
+func GenerateWithPlan(outputDir, appDir string, plan ApplicationPlan) (result Result, err error) {
 	defer recoverGeneratedIdentifierError(&err)
 
 	if strings.TrimSpace(outputDir) == "" {
@@ -48,26 +112,14 @@ func GenerateWithOptions(outputDir, appDir string, options Options) (result Resu
 	if err := validateDirectories(absOutput, absApp); err != nil {
 		return Result{}, err
 	}
-	options, err = resolveOptions(absOutput, options)
-	if err != nil {
-		return Result{}, err
-	}
-	if err := validateActionEndpoints(options.Actions); err != nil {
-		return Result{}, err
-	}
-	if err := validateAPIEndpoints(options.APIs); err != nil {
-		return Result{}, err
-	}
-	if err := validateFragmentEndpoints(options.Fragments); err != nil {
-		return Result{}, err
+	if plan.backendOnly {
+		return Result{}, fmt.Errorf("backend application plan cannot be used for embedded app generation")
 	}
-	if err := validateContractRoutes(options.IR); err != nil {
-		return Result{}, err
-	}
-	if err := validateSSRRoutes(options.SSR); err != nil {
-		return Result{}, err
+	if plan.outputDir != "" && filepath.Clean(plan.outputDir) != filepath.Clean(absOutput) {
+		return Result{}, fmt.Errorf("application plan output directory %q does not match build output directory %q", plan.outputDir, absOutput)
 	}
-	if err := validateCORSConfig(options); err != nil {
+	options, err := plan.optionsForEmit()
+	if err != nil {
 		return Result{}, err
 	}
 
@@ -153,6 +205,16 @@ func GenerateWithOptions(outputDir, appDir string, options Options) (result Resu
 // GenerateBackendWithOptions writes a generated Go app that serves only
 // request-time backend routes for feature-bound actions and APIs.
 func GenerateBackendWithOptions(appDir string, options Options) (result Result, err error) {
+	plan, err := PlanBackendApplication(options)
+	if err != nil {
+		return Result{}, err
+	}
+	return GenerateBackendWithPlan(appDir, plan)
+}
+
+// GenerateBackendWithPlan writes a generated Go app that serves only
+// request-time backend routes from an application plan.
+func GenerateBackendWithPlan(appDir string, plan ApplicationPlan) (result Result, err error) {
 	defer recoverGeneratedIdentifierError(&err)
 
 	if strings.TrimSpace(appDir) == "" {
@@ -162,24 +224,12 @@ func GenerateBackendWithOptions(appDir string, options Options) (result Result,
 	if err != nil {
 		return Result{}, err
 	}
-	options, err = resolveBackendOptions(options)
+	options, err := plan.optionsForEmit()
 	if err != nil {
 		return Result{}, err
 	}
-	if err := validateActionEndpoints(options.Actions); err != nil {
-		return Result{}, err
-	}
-	if err := validateAPIEndpoints(options.APIs); err != nil {
-		return Result{}, err
-	}
-	if err := validateFragmentEndpoints(options.Fragments); err != nil {
-		return Result{}, err
-	}
-	if err := validateContractRoutes(options.IR); err != nil {
-		return Result{}, err
-	}
-	if err := validateCORSConfig(options); err != nil {
-		return Result{}, err
+	if !plan.backendOnly {
+		return Result{}, fmt.Errorf("embedded application plan cannot be used for backend app generation")
 	}
 	if err := os.MkdirAll(absApp, 0o755); err != nil {
 		return Result{}, err

internal/appgen/appgen_test.go

@@ -146,15 +146,15 @@ func TestGenerateWritesDynamicSitemapRoute(t *testing.T) {
 	writeTestFile(t, filepath.Join(outputDir, "sitemap.xml"), "<urlset></urlset>")
 	writeTestFile(t, filepath.Join(outputDir, "gowdk-assets.json"), `{"version":1}`)
 
-	ir := gwdkir.Program{Pages: []gwdkir.Page{{
+	ir := gwdkanalysis.BuildProgram(gowdk.Config{}, gwdkanalysis.Sources{Pages: []gwdkir.Page{{
 		ID:     "home",
 		Route:  "/",
 		Guards: []string{"public"},
 		Blocks: gwdkir.Blocks{
 			View:     true,
 			ViewBody: `<main>Home</main>`,
 		},
-	}}}
+	}}})
 	config := gowdk.Config{Addons: []gowdk.Addon{seo.Addon(seo.Options{
 		BaseURL: "https://example.com",
 		DynamicSitemap: gowdk.SEODynamicSitemap{
@@ -2022,6 +2022,59 @@ func TestGenerateRejectsInvalidCORSConfig(t *testing.T) {
 	}
 }
 
+func TestGenerateWithPlanRejectsZeroValue(t *testing.T) {
+	root := t.TempDir()
+	outputDir := filepath.Join(root, "dist")
+	appDir := filepath.Join(root, "generated-app")
+	writeTestFile(t, filepath.Join(outputDir, "index.html"), "<main>Home</main>")
+
+	_, err := GenerateWithPlan(outputDir, appDir, ApplicationPlan{})
+	if err == nil {
+		t.Fatal("expected zero-value application plan error")
+	}
+	if !strings.Contains(err.Error(), "application plan was not constructed") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestGenerateWithPlanRejectsBackendPlan(t *testing.T) {
+	root := t.TempDir()
+	outputDir := filepath.Join(root, "dist")
+	appDir := filepath.Join(root, "generated-app")
+	writeTestFile(t, filepath.Join(outputDir, "index.html"), "<main>Home</main>")
+	plan, err := PlanBackendApplication(Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = GenerateWithPlan(outputDir, appDir, plan)
+	if err == nil {
+		t.Fatal("expected backend plan lane error")
+	}
+	if !strings.Contains(err.Error(), "backend application plan cannot be used") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestGenerateBackendWithPlanRejectsEmbeddedPlan(t *testing.T) {
+	root := t.TempDir()
+	outputDir := filepath.Join(root, "dist")
+	appDir := filepath.Join(root, "generated-backend")
+	writeTestFile(t, filepath.Join(outputDir, "index.html"), "<main>Home</main>")
+	plan, err := PlanApplication(outputDir, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = GenerateBackendWithPlan(appDir, plan)
+	if err == nil {
+		t.Fatal("expected embedded plan lane error")
+	}
+	if !strings.Contains(err.Error(), "embedded application plan cannot be used") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
 func TestGenerateRejectsInvalidEndpointCORSConfig(t *testing.T) {
 	root := t.TempDir()
 	outputDir := filepath.Join(root, "dist")
@@ -9394,17 +9447,39 @@ func waitForHTTPStatusWithHeaders(url, method, body string, headers map[string]s
 // through the production manifest->IR path, asserting against exactly what the
 // generated-app pipeline derives.
 func actionEndpointsFromManifestFixture(app gwdkanalysis.Sources) ([]ActionEndpoint, error) {
+	app = normalizeEndpointFixtureSources(app)
 	return actionEndpointsFromIR(gowdk.Config{}, gwdkanalysis.BuildProgram(gowdk.Config{}, app))
 }
 
 func apiEndpointsFromManifestFixture(app gwdkanalysis.Sources) ([]APIEndpoint, error) {
+	app = normalizeEndpointFixtureSources(app)
 	return apiEndpointsFromIR(gwdkanalysis.BuildProgram(gowdk.Config{}, app))
 }
 
 func fragmentEndpointsFromManifestFixture(app gwdkanalysis.Sources) ([]FragmentEndpoint, error) {
+	app = normalizeEndpointFixtureSources(app)
 	return fragmentEndpointsFromIR(gwdkanalysis.BuildProgram(gowdk.Config{}, app))
 }
 
+func normalizeEndpointFixtureSources(app gwdkanalysis.Sources) gwdkanalysis.Sources {
+	for index := range app.Pages {
+		if strings.TrimSpace(app.Pages[index].Blocks.ViewBody) != "" {
+			app.Pages[index].Blocks.View = true
+		}
+	}
+	for index := range app.Components {
+		if strings.TrimSpace(app.Components[index].Blocks.ViewBody) != "" {
+			app.Components[index].Blocks.View = true
+		}
+	}
+	for index := range app.Layouts {
+		if strings.TrimSpace(app.Layouts[index].Blocks.ViewBody) != "" {
+			app.Layouts[index].Blocks.View = true
+		}
+	}
+	return app
+}
+
 func TestDeniedPageRoutesSelectsGuardlessStaticPages(t *testing.T) {
 	options := Options{
 		IR: &gwdkir.Program{Pages: []gwdkir.Page{

internal/appgen/auto_routes.go

@@ -39,11 +39,21 @@ func resolveOptions(outputDir string, options Options) (Options, error) {
 	if err != nil {
 		return Options{}, err
 	}
-	ssrArtifacts, err := buildgen.SSRArtifactsFromIR(options.Config, ir, outputDir)
+	var ssrArtifacts []buildgen.SSRArtifact
+	if options.Program != nil {
+		ssrArtifacts, err = buildgen.SSRArtifactsFromValidatedProgram(options.Config, *options.Program, outputDir)
+	} else {
+		ssrArtifacts, err = buildgen.SSRArtifactsFromIR(options.Config, ir, outputDir)
+	}
 	if err != nil {
 		return Options{}, err
 	}
-	sitemap, err := buildgen.RuntimeSitemapPlanFromIR(options.Config, ir)
+	var sitemap buildgen.RuntimeSitemapPlan
+	if options.Program != nil {
+		sitemap, err = buildgen.RuntimeSitemapPlanFromValidatedProgram(options.Config, *options.Program)
+	} else {
+		sitemap, err = buildgen.RuntimeSitemapPlanFromIR(options.Config, ir)
+	}
 	if err != nil {
 		return Options{}, err
 	}
@@ -91,6 +101,12 @@ func resolveBackendOptions(options Options) (Options, error) {
 }
 
 func optionsIR(options Options) (gwdkir.Program, error) {
+	if options.Program != nil {
+		if !options.Program.Valid() {
+			return gwdkir.Program{}, fmt.Errorf("validated program was not constructed by compiler validation")
+		}
+		return options.Program.Program(), nil
+	}
 	if options.IR != nil {
 		if err := gwdkir.CheckInvariants(*options.IR); err != nil {
 			return gwdkir.Program{}, fmt.Errorf("invalid compiler IR: %w", err)

internal/appgen/ir.go

@@ -94,10 +94,13 @@ func actionEndpointRoutes(config gowdk.I18NConfig, pageRoute string, route strin
 }
 
 func actionFormSchemaFromBlocks(blocks gwdkir.Blocks) (map[string][]view.ActionFormField, error) {
-	if len(blocks.ViewNodes) > 0 {
-		return view.ActionFormSchemaFromNodes(blocks.ViewNodes)
+	if len(blocks.ViewNodes) == 0 {
+		if strings.TrimSpace(blocks.ViewBody) == "" {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("view {} has source body but no parsed nodes")
 	}
-	return view.ActionFormSchema(blocks.ViewBody)
+	return view.ActionFormSchemaFromNodes(blocks.ViewNodes)
 }
 
 func apiEndpointsFromIR(ir gwdkir.Program) ([]APIEndpoint, error) {