Report unsupported configuration fields

CHANGELOG.md

@@ -8,6 +8,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- `LoadProject` and `GenerateAsync` expose value-free diagnostics for unknown, unsupported, and partially applied Compose fields; strict validation rejects them before Docker Engine operations.
 - `UpAsync`, `CreateAsync`, and `StartAsync` include transitive service dependencies, reject cycles and missing services, and wait for effective Docker health checks or running state before starting dependents; an optional per-dependency timeout bounds readiness waits.
 - `GenerateAsync` returns a normalized YAML snapshot of selected loaded services alongside the project summary, with service selection and an output project-name override.
 - `TopAsync` returns real process listings for running project service containers through the Docker Engine process-list API.
@@ -22,6 +23,11 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- Scalar health checks are normalized before Docker creation, diagnostics identify unapplied build options and network attachments, and strict validation covers direct Engine operations.
+- Validation diagnoses multiple build platforms and duplicate container-port mappings, preserves escaped resource-name provenance, and recognizes the service platform as a build fallback.
+- Validation diagnoses long-form service volumes and unretained build options, honors dependency conditions that match readiness behavior, ignores default zero resource values, and attributes merged-map diagnostics to overlay values.
+- Validation ignores build extension metadata and false boolean defaults, and diagnoses unsupported long-form `env_file` entries.
+- Validation ignores nested extension metadata and diagnoses `service_started` when an image may provide an inherited health check.
 - Service-level `on-failure:N` restart policies preserve the Docker retry limit and reject malformed suffixes with contextual validation errors.
 
 - `WaitAsync` collects container exit codes without concurrent dictionary writes and chooses its aggregate code deterministically by ordinal container ID.

CONTRIBUTING.md

@@ -21,6 +21,7 @@ Docker integration tests run only when a reachable Docker daemon is available.
 - Preserve cancellation-token behavior and avoid introducing Docker CLI process calls into the managed SDK.
 - Update XML comments, `README.md` / `README.zh-CN.md`, relevant `docs/*` guides, and `CHANGELOG.md` `[Unreleased]` in the same PR when public behavior or compatibility claims change. Follow the matrix below to identify the affected documents.
 - Include a minimal Compose file or Docker reproduction when fixing compatibility behavior.
+- For every newly parsed Compose field, either apply its semantics in the Docker Engine mapping or add a stable diagnostic and focused test for the unsupported or partial behavior. Update the field matrix with links to that diagnostic and test.
 
 ## Documentation and CHANGELOG
 

README.md

@@ -103,7 +103,7 @@ Invalid input throws `ComposeValidationException`. Its message and structured pr
 
 `ComposeProjectContext.Profiles` selects services consistently for project loading and service-scoped lifecycle, inspection, image, log, event, and watch operations. Services without `profiles` are always selected; a profiled service is selected when any of its profiles is active. An operation that explicitly names a service can select it even when its profile is not active. An empty selection is a no-op rather than a request to operate on every project container.
 
-The loader can retain fields that the engine does not yet apply. Consult the [Compose field support matrix](docs/compose-field-matrix.md) before relying on a Compose property at runtime.
+The loader can retain fields that the engine does not fully apply. `LoadProject` and `GenerateAsync` expose stable, value-free `Diagnostics` with the source file, property path, service name when relevant, and an `unsupported-field` or `partially-supported-field` code. The default `ComposeValidationMode.Report` continues with documented behavior; `ComposeValidationMode.Strict` rejects these fields before any Docker Engine operation. Unknown non-empty project, service, and build fields are also reported. Long-form service volumes and `env_file` entries, unapplied dependency conditions, and ignored build options produce diagnostics; default zero resource values and false boolean defaults remain quiet. Empty/default values and `x-*` extensions do not produce diagnostics. Diagnostics never include field values, which may contain credentials or secrets. Consult the [Compose field support matrix](docs/compose-field-matrix.md) for field behavior and diagnostic coverage before relying on a Compose property at runtime.
 
 ## What the engine does today
 

README.zh-CN.md

@@ -105,8 +105,8 @@ builder.Services.AddComposeSharp();
 - `PublishAsync` 会把每个被选中服务的镜像打成 `repository:serviceName`，并使用 `ComposeProjectContext.RegistryAuth` 推送；返回值为每个服务一条 `PublishResult`，分别记录 tag 与 push 结果，不会在第一个失败处中断。`ComposePublishOptions` 中的 `ResolveImageDigests`、`WithEnvironment`、`OcIVersion` 和 `InsecureRegistry` 尚未应用。
 - `LoadMerged` 按字段逐步合并后置文件：标量由后置值覆盖，映射递归合并，列表追加；服务资源、`command` 和 `entrypoint` 有明确的替换规则。它仍不是 Docker Compose 的完整合并算法；精确规则和不支持的 YAML 标签见[合并语义](docs/merge-semantics.md)。
 - `ComposeProjectContext.Profiles` 会在加载项目，以及面向服务的生命周期、检查、镜像、日志、事件和 watch 操作中统一选择服务：未配置 `profiles` 的服务始终会被选择；配置了 profile 的服务会在任一 profile 被激活时被选择。显式指定服务的操作即使未激活该服务的 profile，也可以选择它；选择结果为空时不会退化成操作项目中的全部容器。
-- 加载器可以保留引擎尚未应用的字段。在运行时依赖某个 Compose 属性之前，请查阅 [Compose 字段支持矩阵](docs/compose-field-matrix.md)。
-- `depends_on` 会将所选服务的传递依赖纳入启动范围，并按稳定顺序启动。未启用有效 Docker 健康检查的依赖必须处于运行状态；启用了健康检查（包括从镜像继承）的依赖必须通过健康检查。依赖变为不健康或停止时会返回诊断错误；调用方可以设置 `DependencyWaitTimeoutSeconds` 或取消操作。缺失服务和依赖环也会返回诊断错误；长格式条件仍不支持。
+- 加载器可能会保留引擎尚未完全应用的字段。`LoadProject` 和 `GenerateAsync` 会通过 `Diagnostics` 返回稳定且不包含字段值的诊断，其中包含来源文件、属性路径、适用时的服务名，以及 `unsupported-field` 或 `partially-supported-field` 类型。默认的 `ComposeValidationMode.Report` 会按已记录的行为继续；`ComposeValidationMode.Strict` 会在任何 Docker Engine 操作前拒绝这些字段。非空的未知项目、服务和 build 字段也会报告。长格式服务卷和 `env_file` 条目、未应用的依赖条件和忽略的 build 选项会产生诊断；默认资源零值和布尔 `false` 默认值保持静默。空值/默认值和 `x-*` 扩展不会产生诊断。诊断不会包含字段值，因为其中可能有凭据或机密。依赖某个 Compose 属性的运行时行为前，请查看 [Compose 字段支持矩阵](docs/compose-field-matrix.md)中的行为说明和诊断覆盖。
+- `depends_on` 会将所选服务的传递依赖纳入启动范围，并按稳定顺序启动。未启用有效 Docker 健康检查的依赖必须处于运行状态；启用了健康检查（包括从镜像继承）的依赖必须通过健康检查。依赖变为不健康或停止时会返回诊断错误；调用方可以设置 `DependencyWaitTimeoutSeconds` 或取消操作。缺失服务和依赖环也会返回诊断错误；长格式条件不会被保留。依赖显式启用健康检查时，`service_healthy` 与当前就绪行为一致；只有 Compose 服务显式禁用健康检查时，`service_started` 才不会产生诊断。未显式禁用时，镜像可能提供继承的健康检查，因此会报告诊断。
 
 默认端点在 Windows 是 `npipe://./pipe/docker_engine`，Unix 是 `unix:///var/run/docker.sock`；也可以通过 `SocketPath` 显式指定。