Skip to content

feat(lint): native config lint command for Flex and Fixed config - #108

Open
pjcdawkins wants to merge 17 commits into
mainfrom
feat/native-lint-command
Open

feat(lint): native config lint command for Flex and Fixed config#108
pjcdawkins wants to merge 17 commits into
mainfrom
feat/native-lint-command

Conversation

@pjcdawkins

@pjcdawkins pjcdawkins commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Summary

Replaces the app:config-validate command (aliases validate, lint), which used the platformify library's schema validator and reported a single error at a time, with a new lint command that reports all errors and warnings at once. It runs a JSON-schema check plus semantic checks (relationships, names, types/versions, scripts, web config, dependencies, routes).

It works for both configuration styles:

  • Flex (Upsun): .upsun/*.yaml, merged.
  • Fixed (legacy Platform.sh): .platform.app.yaml files and/or .platform/applications.yaml (list or map form), plus optional .platform/routes.yaml and .platform/services.yaml. The .yml extension is accepted as well as .yaml.

About 8600 lines of this PR are the new internal/lint package - almost entirely copied from the internal AI API project where it has been used in production for ~ 9 months.

In the AI API it only supported "Flex" validation, so the "Fixed" configuration is now normalized into the same shape, so the further checks are shared across both styles.

Project root and style detection

Detection is offline (no API calls) and based on the running CLI's own config plus the files present:

  • The project root is the nearest enclosing .git directory (falling back to the given path), so the command can run from any subdirectory. The nearest, not topmost, .git is used so a stray repository higher up the tree cannot hijack the result.
  • The directory names come from the CLI config (project_config_flavor, project_config_dir, app_config_file), so vendor/white-label builds work. The style is chosen as: Flex when present, else Fixed, else the build's native format. A first-party build (.upsun or .platform) also recognizes the other first-party format as a migration case; white-label builds use only their own names.
  • Fixed detection is anchored at the root (a config directory or a top-level app file), so a stray nested config file (e.g. a test fixture) does not turn an unrelated repository into a project. Nested per-app config files are still collected once a project is confirmed.

Details

  • commands/lint.go: the command, taking an optional [path] or piped stdin, with --format text|json. Exits non-zero on errors. Piped stdin is only consumed when it carries content, so lint with no arguments in a non-interactive shell or CI lints the current directory instead of erroring.
  • internal/lint: the pure linter (CheckDir, CheckContent), Fixed-style loaders, and the embedded Flex/Fixed JSON schemas.
  • internal/lint/registry: the image registry. gen.go transforms meta.upsun.com/images into the embedded registry.json.
  • make lint-assets refreshes the embedded registry and schemas; make lint-assets-check and a CI job fail when they are stale.

Warnings and messages

  • A config directory found below the project root (e.g. a nested .platform or .upsun) is warned about, since the platform only reads it at the root.
  • A duplicate application name names both source files so the error is actionable.
  • The command prints the validated directory on its own line each run; error and warning headings are colored, with the issue lines in the default color.

Out of scope

Folding the Platformify repository into this one is a separate follow-up; only the three Fixed-style schemas were copied in for now. The Platformify dependency is still used by the init command.

The meta.upsun.com schema is intentionally not used for validation: it resolves type and version via remote $refs (fetched at runtime, which would break offline use) and duplicates the registry-based type check.

🤖 Generated with Claude Code

Copilot AI review requested due to automatic review settings June 16, 2026 09:08

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR replaces the legacy app:config-validate (aliases validate, lint) command that delegated to the PHP CLI with a native Go linter that validates both Flex (.upsun/*.yaml) and Fixed (.platform*.yaml) project configurations offline, reporting all issues in one run.

Changes:

  • Added a native Cobra command for config linting with --format text|json and optional path/stdin input handling.
  • Introduced internal/lint with schema validation + semantic checks (types/versions, scripts, web config, dependencies, routes, relationships, naming), plus Fixed-style normalization and embedded schemas.
  • Added tooling/CI to keep embedded registry + schemas in sync with upstream sources.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
Makefile Adds lint-assets and lint-assets-check targets to refresh/verify embedded registry + schemas.
commands/root.go Removes legacy Platformify validate command wiring and registers the new native lint command.
commands/list_models.go Updates help/usage metadata for app:config-validate with path, --format, and --stdin.
commands/lint.go Implements the new native app:config-validate command (aliases lint, validate) with text/json output.
internal/lint/linter.go Adds CheckContent and wires schema + semantic checks for Flex-style content.
internal/lint/linter_test.go Adds tests covering combined lints and common failure cases.
internal/lint/normalize.go Detects Flex vs Fixed config layouts and dispatches to the appropriate loader/linter.
internal/lint/normalize_test.go Tests style detection and directory linting behavior.
internal/lint/fixed.go Loads Fixed-style config files, schema-validates them, normalizes into shared config shape, and runs semantic checks.
internal/lint/fixed_test.go Tests Fixed-style loading/validation paths and edge cases.
internal/lint/merge.go Merges `.upsun/*.yaml
internal/lint/merge_test.go Tests merging behavior and error cases.
internal/lint/yaml.go Adds YAML→Go decoding and JSON-schema validation helpers with scoped paths.
internal/lint/yaml_test.go Tests YAML schema validation behavior on valid/invalid content.
internal/lint/result.go Adds shared Result/Issue types and deterministic formatted output.
internal/lint/names.go Adds application/service/worker name validation.
internal/lint/names_test.go Tests name validation rules and error formatting.
internal/lint/types.go Adds registry-backed type/version validation with Flex-only composable/stack warnings.
internal/lint/types_test.go Tests type/version validation against a test registry.
internal/lint/relationships.go Adds relationship target validation and “unused service” detection.
internal/lint/relationships_test.go Tests relationship validation scenarios.
internal/lint/scripts.go Adds POSIX shell syntax validation for hooks/commands/cron scripts + start-command warnings.
internal/lint/scripts_test.go Tests script parsing failures and warning behavior.
internal/lint/web.go Adds web location key/root path checks and rule regex validation.
internal/lint/web_test.go Comprehensive tests for web linting rules and error formatting.
internal/lint/routes.go Adds basic route upstream target/protocol validation.
internal/lint/routes_test.go Tests route linting scenarios and expected messages.
internal/lint/dependencies.go Adds dependency section validation (type and empty values).
internal/lint/dependencies_test.go Tests dependency validation including complex PHP dependency shapes.
internal/lint/config_schema.go Defines shared decoded config model used by semantic checks.
internal/lint/schema/schema.go Embeds and loads the Flex JSON schema with sync.Once caching.
internal/lint/schema/schema_test.go Smoke test that the embedded Flex schema validates a basic config.
internal/lint/schema/fixed.go Embeds and loads Fixed-style schemas (application/routes/services).
internal/lint/schema/platformsh.application.json Embedded Fixed application JSON schema.
internal/lint/schema/platformsh.routes.json Embedded Fixed routes JSON schema.
internal/lint/schema/platformsh.services.json Embedded Fixed services JSON schema.
internal/lint/registry/registry.go Embeds registry data and provides parsing + normalization (clean()).
internal/lint/registry/registry_test.go Smoke test that the embedded registry parses and includes expected entries.
internal/lint/registry/model.go Defines registry model types and JSON unmarshalling behavior for versions.
internal/lint/registry/model_test.go Tests registry model parsing helpers and template-friendly mapping.
internal/lint/registry/gen.go Generator that fetches meta.upsun.com/images and writes registry.json.
internal/lint/registry/registry.json Embedded minimized registry snapshot consumed by the linter.
internal/lint/testdata/registry.json Test registry fixture used by type-check tests.
go.mod Adds new dependencies used by the native linter (schema, regex, shell parser).
go.sum Updates module checksums for the new/updated dependencies.
.github/workflows/ci.yml Adds a CI job to fail when embedded lint assets are stale.
CLAUDE.md Updates repo documentation to include the new native lint command.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread internal/lint/dependencies.go
Comment thread internal/lint/dependencies.go
Comment thread internal/lint/routes.go

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 48 out of 49 changed files in this pull request and generated 3 comments.

Comment thread internal/lint/scripts.go
Comment on lines +25 to +35
// Group all scripts for shell syntax checking.
scripts[keyPrefix+"hooks.build"] = app.Hooks.Build
scripts[keyPrefix+"hooks.deploy"] = app.Hooks.Deploy
scripts[keyPrefix+"hooks.post_deploy"] = app.Hooks.PostDeploy
scripts[keyPrefix+"web.commands.start"] = app.Web.Commands.Start
scripts[keyPrefix+"web.commands.post_start"] = app.Web.Commands.PostStart
for cronName, cron := range app.Crons {
cronPrefix := keyPrefix + "crons." + cronName + "."
scripts[cronPrefix+"start"] = cron.Commands.Start
scripts[cronPrefix+"stop"] = cron.Commands.Stop
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ae3c6ccConfig now decodes workers.*.commands, and CheckScripts parses pre_start, start and post_start (the last is Flex-only). This covers both styles, since Fixed config is normalized through the same shape.

Comment thread internal/lint/yaml_test.go Outdated
Comment on lines +79 to +98
func mockSchema() *gojsonschema.Schema {
schema, _ := gojsonschema.NewSchema(gojsonschema.NewStringLoader(`
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"key": {
"type": "string"
},
"list": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["key"]
}`))
return schema
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 539ea49mockSchema now takes *testing.T and asserts with require.NoError.

Comment thread Makefile

@upsun-dispatch upsun-dispatch Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Changes suggested — 🟡 2 warnings · 3 minor points

🔍 Full review · 49 files reviewed

🔵 Minor points

Not blocking, and no threads opened for these.

  • internal/lint/registry/model.go:121 — Registry.ForTemplates, and its comment about "Jinja template access", has no production caller in this repo; it is exercised only by model_test.go and this CLI uses no Jinja templates. It is dead code carried over from the source project whose comment misdescribes how the registry is consumed here.
  • CLAUDE.md:70 — This line describes the command as "lint.go: Native config linter (aliases validate, app:config-validate)", implying lint is the canonical name. commands/lint.go sets Use "app:config-validate" with Aliases {"lint", "validate"}, so app:config-validate is canonical and lint is the alias; the doc lists the canonical name among the aliases.
  • general — This PR does not merge cleanly onto the base branch: go.mod is in conflict. The branch must be rebased or the go.mod conflict resolved before it can merge. Note that go.mod here promotes dlclark/regexp2/v2, xeipuuv/gojsonschema, and mvdan.cc/sh/v3 from indirect to direct requires, so the conflict must be resolved carefully to keep those direct.
Review details
  • Commit: f564f12
  • Model: claude-opus-4-8
  • Panel: security · correctness · robustness · design

Comment thread internal/lint/merge.go Outdated
Comment thread commands/lint.go Outdated
pjcdawkins and others added 14 commits August 7, 2026 21:43
Add internal/lint with the multi-error config linter ported from the
ai-api repository (internal/linter, internal/schema, internal/registry,
plus the .upsun config merge helpers). The linter validates merged
Flex-style config against the embedded JSON schema and runs semantic
checks (relationships, names, types, scripts, web, dependencies,
routes), collecting all errors and warnings rather than stopping at the
first.

Changes from the source:
- Inline the composable-image stable channel constant to drop the nix
  dependency.
- Drop the AI-only file_modifications schema patch.
- Use github.com/dlclark/regexp2/v2.

Promote gojsonschema to a direct dependency and add mvdan.cc/sh/v3.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the platformify-backed app:config-validate command (which
delegated to the legacy PHP CLI) with a native Go command that runs the
ported linter and reports all errors and warnings at once.

- Add internal/lint/normalize.go: DetectStyle plus LintDir, which detect
  the configuration style from the directory layout (.upsun vs
  .platform) and lint the merged Flex configuration. Fixed-style linting
  is stubbed pending Phase 3.
- Add commands/lint.go: the "lint" command (aliases "validate",
  "app:config-validate") accepting an optional path or stdin, with text
  and JSON output, exiting non-zero on errors.
- Rename Lint to LintContent and add JSON tags to Issue.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add linting for legacy Platform.sh configuration: .platform.app.yaml
files and .platform/applications.yaml (list or map form), plus optional
.platform/routes.yaml and .platform/services.yaml. CheckDir detects the
style from the directory layout and normalizes Fixed-style config into
the same Config the Flex path uses, so the semantic checks are shared.

- Add the three Fixed-style JSON schemas (application, routes, services)
  copied from platformify, with per-file loaders and CheckSchemaScoped to
  attribute schema errors to their source file or app.
- Gate composable-image and stack warnings to Flex in CheckTypes.
- Guard against Flex-style keys appearing in a Fixed-style file.
- Inject the application name from the map key when validating map-form
  applications.yaml, matching the canonical parser.
- Rename the entrypoints to CheckContent and CheckDir, consistent with
  the Check* family, and satisfy the repository linters.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add tooling to regenerate the embedded lint assets:

- gen.go (build-tagged) fetches https://meta.upsun.com/images and
  transforms it into registry.json, mapping per-version status to
  supported/legacy and service/runtime. Regenerate with `go generate
  ./internal/lint/registry` or `make lint-assets`.
- `make lint-assets` also refreshes the Flex and Fixed-style schemas
  from platformify. The meta.upsun.com schema is intentionally not used:
  it validates types via remote $refs (fetched at runtime) and
  duplicates the registry-based type check, so type and version
  validation stays in CheckTypes.
- `make lint-assets-check` and a CI job fail when the committed assets
  are stale.

Refresh the registry from meta.upsun.com and make the registry test
robust to version drift.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the app:config-validate help metadata to document the optional
path argument and the --format and --stdin options, and note the native
lint command in CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address findings from code review:

- lint: only read piped stdin when it carries content; otherwise (a
  non-interactive shell or CI, where stdin is not a TTY but empty) fall
  back to linting the directory. Previously `lint` with no arguments
  errored with "empty content" in CI. Explicit --stdin still errors on
  empty input.
- lint: make app:config-validate the primary command name (aliases lint,
  validate), matching the listing/help metadata and generated docs.
- Fixed-style: reject a name set inside a map-form applications.yaml
  entry, matching the canonical parser and avoiding inconsistent app
  identity keying.
- Add Result.Merge and use it instead of reallocating via Combine; drop
  the dead map[any]any branch in toStringMap; fix a misspelled
  identifier.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The "available targets: ..." message in CheckRoutes was built by ranging
over a map, so its order varied between runs. Sort it before joining.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Make config-style detection match how a project actually deploys, and
drive the directory names from the CLI's own config so vendor/white-label
builds work.

- Resolve the project root by walking up to the nearest enclosing .git
  (falling back to the given path), so lint can run from any subdirectory.
  The nearest .git is used, not the topmost, so a stray repository higher
  up the tree (e.g. a dotfiles repo, or /tmp) cannot hijack the result.
- Detect Flex vs Fixed from the vendor's conventions (project_config_flavor,
  project_config_dir, app_config_file) plus the files present: Flex wins
  when present, else Fixed, else the native format. A first-party build
  (.upsun or .platform) also recognizes the other first-party format as a
  migration case; white-label builds use only their own names.
- Anchor Fixed detection at the root (a config directory or a top-level app
  file). Nested per-app files are still collected once a project is
  confirmed, but a stray fixture no longer turns an unrelated repo into a
  project.
- Warn about nested copies of any known config directory (.upsun, .platform,
  or the configured dir); the platform only reads them at the project root.
- Make the duplicate application-name error name both source files.
- Accept .yml as well as .yaml for Fixed routes/services/applications files.
- Add app_config_file to the Go config schema (it was already in the YAML).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Print the validated directory on its own line every run
  ("Validating configuration in directory: <path>", path in cyan).
- Colour only the "Linter errors:" / "Linter warnings:" headings
  (bold red / bold yellow); the issue lines use the default colour so
  they stay readable.
- Keep the green check mark but leave "The configuration is valid."
  in the default colour.
- Capitalize the first letter of operational errors for display (the Go
  error strings stay lowercase per convention), so "no configuration
  found" reads as "No configuration found".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Go 1.27 is about to be released where this is on by default anyway.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
io/fs glob patterns are always slash-separated, but filepath.Join used the
OS separator, so on Windows the pattern was `.upsun\*.yaml`. path.Match
treats the backslash as an escape, so nothing matched: detection returned
false and every Flex project reported "no configuration files found".

Use path.Join, and rename the parameter to `dir` so it no longer shadows
the package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
For a valid configuration both slices are nil, so --format json produced
{"errors": null, "warnings": null}. The output documents these as arrays,
so a consumer iterating them without a null guard broke on valid input.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Hooks, web commands and crons were parsed, but worker commands were not
decoded at all, so a syntax error in one went unreported. Both schemas
require workers.*.commands.start; pre_start is also accepted, and
post_start in Flex.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Registry.ForTemplates has no caller: it came from the source project,
where the registry fed Jinja templates. Only its own tests used it.

mockSchema discarded the error from gojsonschema.NewSchema, so an invalid
schema would have returned nil and panicked later instead of failing.

Also correct the CLAUDE.md description, which listed app:config-validate
as an alias of itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@pjcdawkins
pjcdawkins force-pushed the feat/native-lint-command branch from f564f12 to 539ea49 Compare August 8, 2026 02:13

@upsun-dispatch upsun-dispatch Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Reviewed — No new blocking findings · 3 minor points

🔍 Full review · 50 files reviewed

🔵 Minor points

Not blocking, and no threads opened for these.

  • .github/workflows/ci.yml:67 — The lint-assets job runs make lint-assets-check, which first runs make lint-assets (fetching live data from meta.upsun.com via go run gen.go and the platformify schemas via curl) and then git diff --exit-code. Because it re-derives the embedded assets from live upstream on every pull_request, any upstream registry/schema change turns this job red on PRs that never touched lint code, and the job fails outright if those hosts are unreachable during CI.
  • .github/workflows/ci.yml:59 — The new lint-assets job pins actions/checkout@v6 and actions/setup-go@v6, while the sibling test, legacy-php, and integration-test jobs in this same file use @v7. The mismatched action versions look unintentional.
  • internal/lint/registry/model.go:30 — Image.Docs and the Web, Upstream, Location, Hooks, BuildConfig, and Dependency types it references, plus Image.Description and Image.Configuration, are never populated by gen.go (which writes only name/type/runtime/versions into registry.json) and are never read by any linter check — clean() even blanks Description. They are dead speculative fields carried over from the source project.
Review details
  • Commit: 539ea49
  • Model: claude-opus-4-8
  • Panel: security · correctness · robustness · design

@upsun-dispatch
upsun-dispatch Bot dismissed their stale review August 8, 2026 02:19

Superseded: the latest Upsun Dispatch review no longer requests changes.

pjcdawkins and others added 2 commits August 7, 2026 22:23
Two service types were rejected outright:

valkey-persistent was created inside `if _, ok := reg["valkey"]; !ok`.
The registry does contain valkey, so the branch never ran and the alias
was never added. Split it into its own check, keyed on the alias, as the
redis-persistent block already does.

mariadb-replica and postgresql-replica are listed upstream without
versions of their own, so every version was rejected, with an empty "it
must be exactly one of: " list. They now track the type they replicate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Worker names were added to the same map as application and service names,
so two applications each defining a `queue` worker were reported as a
duplicate, as was a worker sharing a name with a service. Worker names are
scoped beneath their application, so they are now tracked separately and
excluded from the duplicate check.

They remain valid relationship targets, as before.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@pjcdawkins

Copy link
Copy Markdown
Contributor Author

Rebased on main (the go.mod conflict is resolved, keeping dlclark/regexp2/v2, xeipuuv/gojsonschema and mvdan.cc/sh/v3 as direct requires).

Beyond the review threads above, a codex review pass found several cases where the ported linter rejected valid configuration. Fixed here:

  • valkey-persistent was rejected outright. The alias was created inside if _, ok := reg["valkey"]; !ok, but the registry does contain valkey, so the branch never ran. Now keyed on the alias itself, as the redis-persistent block already was.
  • mariadb-replica and postgresql-replica rejected every version, with an empty it must be exactly one of: list — they are published upstream without versions of their own. They now track the type they replicate.
  • Duplicate worker names across applications were reported as an error. Worker names are scoped beneath their application, so they are tracked separately now and excluded from the duplicate check. They remain valid relationship targets.

Not changed: web location rules are validated with regexp2 (.NET syntax), so PCRE constructs such as (?P<name>...) are rejected. Named groups are rarely used in these rules, so this is left for later.

The same three bugs exist in the AI API, which this package was ported from. Fixed there in platformsh/ai/api!205.

The registry had drifted from meta.upsun.com, failing lint-assets-check:
mariadb and postgresql gained 12.3, redis gained 8.8, rabbitmq moved to
4.3, and elixir, kafka and python versions moved.

The refresh also dropped mariadb-replica and postgresql-replica, which are
no longer published upstream at all, so filling in their versions was not
enough. They are now created from the type they replicate, like the
persistent aliases, which keeps them working whether or not upstream lists
them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants