fix project root discovery and build diagnostics (#752)

Author: cssbruno

docs/compiler/pipeline.md

@@ -24,7 +24,7 @@ builds, and the flag may be repeated or comma-separated. Discovery uses
 `**/*.gwdk` defaults when no root/module source is configured in the loaded
 config.
 
-`gowdk build [--config <file>] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--worker-app <dir>] [--worker-bin <file>] [--cron-app <dir>] [--cron-bin <file>] [files...]` currently
+`gowdk build [--config <file>] [--project-root <dir>] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--worker-app <dir>] [--worker-bin <file>] [--cron-app <dir>] [--cron-bin <file>] [files...]` currently
 emits app-shell HTML, `gowdk-routes.json`, `gowdk-assets.json`, generated
 embedded app source, optional web/backend binaries, and optional contract
 worker/cron binaries for the selected source set. The current rendered page

docs/compiler/project-structure.md

@@ -3,9 +3,11 @@
 ## Current Inputs
 
 Project-level CLI commands require `gowdk.config.go` in the current directory,
-or an explicit config passed with `--config <file>`, before they compile,
-validate, or inspect `.gwdk` code. Explicit `.gwdk` file paths narrow the input
-set, but they do not bypass the config requirement:
+a parent directory, the directory passed with `--project-root <dir>`, or an
+explicit config passed with `--config <file>`, before they compile, validate,
+or inspect `.gwdk` code. Explicit `.gwdk` file paths narrow the input set, but
+they do not bypass the config requirement. Explicit paths outside the selected
+project root are rejected:
 
 ```sh
 go run ./cmd/gowdk check examples/pages/*.gwdk examples/actions/*.gwdk examples/partials/*.gwdk examples/api/*.gwdk examples/ssr/*.gwdk

docs/product/requirements.md

@@ -49,7 +49,7 @@ language references, compiler docs, and examples.
 | PRD-021 | Provide a dependency-free fast local development loop. | High | Implemented | `gowdk dev` polls discovered inputs without production dependencies, compares content hashes, caches watched input snapshots between ticks, rebuilds only on real input changes, incrementally renders page/component/layout affected SPA output when possible, falls back to full builds for config/CSS/source-set/app/binary/WASM changes, serves the generated output, live reloads browsers after successful rebuilds, keeps the last successful output after failed rebuilds, and can build/restart generated app targets. SPA/app generation skips identical file writes. |
 | PRD-022 | Allow generated app output to compile to a WASM deploy artifact. | Medium | Partial | `gowdk build --wasm <file>` and `Build.Targets[].WASM` compile the generated app with `GOOS=js GOARCH=wasm`. CI verifies the emitted artifact is a real WASM module by checking the WebAssembly magic header. This remains separate from component-level browser island assets emitted for `wasm` components; host runtime/loader integration is deploy-platform owned. |
 | PRD-023 | Keep current documentation aligned with implemented CLI, config, compiler, language, routing, deployment, and examples. | High | Implemented | `README.md`, `docs/getting-started.md`, `docs/cookbook/README.md`, reference docs, language docs, compiler docs, and `examples/README.md` describe current support, link to the right source of truth, and call out planned behavior. |
-| PRD-024 | Require project config before compiling or validating `.gwdk` code. | High | Implemented | `check`, `audit`, `manifest`, `sitemap`, `routes`, `build`, and `dev` require `gowdk.config.go` in the current directory or an explicit `--config <file>`, even when explicit `.gwdk` file paths are provided. Project-aware `build`, `check`, and `dev` execute importable configs through a cached native helper instead of serializing `gowdk.Config`. |
+| PRD-024 | Require project config before compiling or validating `.gwdk` code. | High | Implemented | `check`, `audit`, `manifest`, `sitemap`, `routes`, `build`, and `dev` require `gowdk.config.go` discovered upward from the current directory or explicit source paths, `--project-root <dir>`, or an explicit `--config <file>`, even when explicit `.gwdk` file paths are provided. Project-aware `build`, `check`, and `dev` execute importable configs through a cached native helper instead of serializing `gowdk.Config`. |
 | PRD-025 | Keep framework integrations optional and outside compiler/runtime core. | Medium | Implemented | Generated apps expose standard `net/http` handlers and framework-neutral code by default. Optional `runtime/adapters/chi`, `runtime/adapters/echo`, `runtime/adapters/gin`, and `runtime/adapters/fiber` nested modules wrap the same generated `http.Handler`; route-aware Chi/Echo/Gin mounting can consume generated OpenAPI metadata, and docs cover middleware overlap and Fiber adaptor caveats. |
 | PRD-026 | Provide declarative security posture and baseline audit gating. | High | Partial | `internal/securitymanifest` projects validated IR into a route/endpoint/contract/frontend posture, `internal/auditspec` evaluates the built-in baseline plus declared `*.audit.gwdk` policies, `gowdk audit` reports human/JSON findings with registry-backed severities and exits non-zero on error findings, and `gowdk build` evaluates the same baseline before writing output plus scans final emitted artifact files after generation. Production builds fail on error-severity findings unless `--allow-insecure` is set; non-production builds print a warning summary. The baseline covers action/command/state-changing API CSRF, guardless action/fragment/command/query endpoints, public-by-omission APIs, roleless contracts, bundle secret leaks, client-visible guardless routes, and raw-HTML sinks, and auth-addon session mode posture; policy rules can require headers. `gowdk audit --emit-tests` writes readable standalone `_test.go` posture tests without overwriting user-owned files unless `--force` is passed, and `--run` builds a temporary generated app and executes its generated app audit test through `runtime/testkit` without auto-authorizing app-owned custom guards. Richer role fixture injection and deeper browser/data-flow analysis remain planned; authentication, sessions, RBAC storage, and backend resource authorization stay app-owned by design. |
 | PRD-027 | Provide opt-in browser presentation-event fanout without adding WebSocket dependencies to the root module. | Medium | Implemented | `FeatureRealtime` and `addons/realtime` provide config and `gowdk add realtime` wiring for presentation-event fanout. Dependency-free SSE fanout remains in the root module through `runtime/contracts/sse` and `realtime.NewSSE`; WebSocket fanout remains isolated in the nested `runtime/contracts/websocketfanout` module. Docs cover SSE versus WebSocket setup, deployment caveats, and the M14 boundary for live DOM reactivity. |

docs/reference/cli.md

@@ -13,31 +13,31 @@ gowdk add <addon> [--config <file>] [--base-url <url>]
 gowdk add --list [--registry] [--json]
 gowdk tokens <file.gwdk>
 gowdk fmt [--write] <files>
-gowdk check [--config <file>] [--env-file <file>] [--module <name>] [--json] [--warnings-as-errors] [--ssr] [files...]
-gowdk fix [--dry-run] [--code <diagnostic-code>] [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
-gowdk manifest [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
-gowdk sitemap [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
-gowdk routes [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
-gowdk endpoints [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
-gowdk inspect ir|tree|endpoint-graph|asset-graph|go-bindings [--config <file>] [--env-file <file>] [--module <name>] [--json] [--ssr] [files...]
-gowdk generate stubs [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk check [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--json] [--warnings-as-errors] [--ssr] [files...]
+gowdk fix [--dry-run] [--code <diagnostic-code>] [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk manifest [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk sitemap [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk routes [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk endpoints [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
+gowdk inspect ir|tree|endpoint-graph|asset-graph|go-bindings [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--json] [--ssr] [files...]
+gowdk generate stubs [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [files...]
 gowdk explain [--json] <diagnostic-code>
-gowdk doctor [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [--json] [files...]
+gowdk doctor [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [--json] [files...]
 gowdk test [--config <file>] [--env-file <file>] [--module <name>] [--target <name>] [--stage <unit|app|binary|browser>] [--run <pattern>] [--timeout <duration>] [--count <n>] [--cover] [--json] [--keep-workdir] [--browser-command <command>] [--ssr] [files...]
-gowdk audit [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [--json] [--sarif[=<file>]] [--diff <previous-report>] [--schema[=report|security]] [--emit-tests[=<file>]] [--check-tests[=<file>]] [--force] [--run] [--run-timeout=<duration>] [files...]
+gowdk audit [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [--json] [--sarif[=<file>]] [--diff <previous-report>] [--schema[=report|security]] [--emit-tests[=<file>]] [--check-tests[=<file>]] [--force] [--run] [--run-timeout=<duration>] [files...]
 gowdk contracts [--json] [dir]
 gowdk graph [--json] [dir]
 gowdk trace <contract> [--json] [dir]
 gowdk list commands|queries|events|jobs [--json] [dir]
-gowdk build [--config <file>] [--env-file <file>] [--debug] [--timings[=<file>]] [--ssr] [--allow-missing-backend] [--allow-insecure] [--obfuscate-assets] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--docker] [--docker-base <distroless|scratch>] [--deploy-recipe <caddy|nginx|split|static|systemd>] [--wasm <file>] [--backend-app <dir>] [--backend-bin <file>] [--worker-app <dir>] [--worker-bin <file>] [--cron-app <dir>] [--cron-bin <file>] [files...]
+gowdk build [--config <file>] [--project-root <dir>] [--env-file <file>] [--debug] [--timings[=<file>]] [--ssr] [--allow-missing-backend] [--allow-insecure] [--obfuscate-assets] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--docker] [--docker-base <distroless|scratch>] [--deploy-recipe <caddy|nginx|split|static|systemd>] [--wasm <file>] [--backend-app <dir>] [--backend-bin <file>] [--worker-app <dir>] [--worker-bin <file>] [--cron-app <dir>] [--cron-bin <file>] [files...]
 gowdk clean [--config <file>] [--target <name>] [--out <dir>] [--dry-run] [--json]
 gowdk dev [--addr <addr>] [--interval <duration>] [build flags...]
 gowdk preview [--addr <addr>] [--hot] [build flags...]
 gowdk serve --dir <dir> [--addr <addr>]
 gowdk playground policy [--json]
 gowdk playground export --dir <project> --out <project.zip> [--json]
 gowdk playground run --dir <project> --out <dir> --allow-hosted-execution (--module-cache <dir> | --allow-shared-module-cache)
-gowdk lsp [--ssr]
+gowdk lsp [--config <file>] [--project-root <dir>] [--ssr]
 ```
 
 ## Flags
@@ -148,6 +148,11 @@ gowdk lsp [--ssr]
   config file. Project-aware `build`, `check`, and `dev` execute importable
   configs through the generated native helper instead of the required default
   `gowdk.config.go`.
+- `--project-root`: supported by project-aware commands and `lsp`; selects the
+  directory that owns `gowdk.config.go`. Without it, project-aware commands
+  discover the root by walking upward from the current directory or explicit
+  source paths. Explicit input files outside the selected project root are
+  rejected.
 - `--env-file`: supported by project-aware compile/report commands that load
   `gowdk.config.go`, including `check`, `doctor`, `test`, `audit`, `manifest`,
   `sitemap`, `routes`, `endpoints`, `inspect`, `generate stubs`, and `build`;
@@ -316,9 +321,10 @@ generated outputs. The target's intermediate build output is inferred as
 writes only the config, `.gitignore`, one page, and one CSS file.
 
 `check`, `audit`, `manifest`, `sitemap`, `routes`, `build`, and `dev` require a config
-file before they compile or validate `.gwdk` code. By default they load
-`gowdk.config.go` from the current directory; `--config <file>` can point at a
-different config for project examples or one-off checks.
+file before they compile or validate `.gwdk` code. By default they discover
+`gowdk.config.go` by walking upward from the current directory or explicit
+source paths; `--project-root <dir>` selects a root directory, and `--config
+<file>` can point at a different config for project examples or one-off checks.
 
 These commands accept explicit file paths, but explicit paths do not remove the
 config requirement. If no files are passed, commands discover configured root

docs/reference/config.md

@@ -21,14 +21,16 @@ type Config struct {
 
 `gowdk.config.go` is required for CLI commands that compile, validate, inspect,
 or serve a development loop for `.gwdk` code: `check`, `manifest`, `sitemap`,
-`routes`, `inspect ir`, `build`, and `dev`. Those commands load
-`gowdk.config.go` from the current directory by default, or the file passed
-with `--config <file>`.
+`routes`, `inspect ir`, `build`, and `dev`. Those commands discover
+`gowdk.config.go` by walking upward from the current directory, use the
+directory passed with `--project-root <dir>`, or load the exact file passed with
+`--config <file>`.
 
 `SourceConfig` has include and exclude patterns. Discovery support exists in
 `internal/discover`, and `gowdk build` reads `Source.Include` and
 `Source.Exclude` fields from the loaded config when no explicit files are
-supplied. Explicit file paths still require a loaded config.
+supplied. Explicit file paths still require a loaded config and must stay under
+the selected project root.
 
 `Modules` declares named source groups. Build discovery treats modules as
 source selectors. Generated app and binary composition is controlled by the

docs/reference/validation.md

@@ -8,20 +8,20 @@ Use standalone mode for a `.gwdk` file that is not inside a configured project:
 gowdk check --standalone path/to/page.gwdk
 ```
 
-When explicit files are passed and the current directory has no
-`gowdk.config.go`, `gowdk check` selects standalone mode automatically. Text
-output reports `ok (standalone)` and JSON output includes
+When explicit files are passed and neither the current directory nor any parent
+directory contains `gowdk.config.go`, `gowdk check` selects standalone mode
+automatically. Text output reports `ok (standalone)` and JSON output includes
 `"mode": "standalone"`.
 
 Standalone mode does not load or execute project config, addons, environment
 files, build functions, lifecycle hooks, or sibling Go packages. It checks
 syntax and source-local semantics independently for each file. A warning says
 `project context required` when a file uses bindings that need a configured
-project. Run the same check from the project root, or pass `--config`, for the
-authoritative project result.
+project. Run the same check from inside the project, pass `--project-root`, or
+pass `--config`, for the authoritative project result.
 
 `--standalone` cannot be combined with `--config`, `--env-file`, `--module`, or
-`--ssr`.
+`--project-root`, or `--ssr`.
 
 ## Project check and build
 

internal/gowdkcmd/audit.go

@@ -26,7 +26,7 @@ import (
 	"github.com/cssbruno/gowdk/internal/securitymanifest"
 )
 
-const auditUsage = "usage: gowdk audit [--config <file>] [--env-file <file>] [--module <name>] [--ssr] [--json] [--sarif[=<file>]] [--diff <previous-report>] [--schema[=report|security]] [--emit-tests[=<file>]] [--check-tests[=<file>]] [--force] [--run] [--run-timeout=<duration>] [files...]"
+const auditUsage = "usage: gowdk audit [--config <file>] [--project-root <dir>] [--env-file <file>] [--module <name>] [--ssr] [--json] [--sarif[=<file>]] [--diff <previous-report>] [--schema[=report|security]] [--emit-tests[=<file>]] [--check-tests[=<file>]] [--force] [--run] [--run-timeout=<duration>] [files...]"
 
 const (
 	auditGeneratedMarker         = "// Code generated by gowdk audit --emit-tests; DO NOT EDIT.\n"