v0.18.0-alpha.2

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, the try experiment and the shortcircuit experiment introduced in v0.17.0 are both still ongoing. Please give them a try and report any issues or feedback!

⚠️ Strict embedding and the ... operator

The explicitopen experiment, ongoing since v0.15.0, is now stable: from language version v0.18.0 on, embedding is strict and needs no opt-in. A struct which embeds a closed value is now closed to that value's fields, where before the embedding constrained only itself and left its sibling fields alone, and a comprehension's conjunct closes its struct just like any other conjunct. The new postfix ... operator opens an embedded value again, so #A... embeds #A without closing the struct around it.

#A: {a: int}

x: {
	#A     // x is now closed to #A's fields
	b: 1   // error: field not allowed
}
y: {
	#A...  // spread leaves y open
	b: 1
}

Migrate a module by running cue fix --exp=explicitopen while it is still at an older language version, and only then raise language.version in cue.mod/module.cue: a file at v0.18.0 or later has no way back, as an @experiment attribute can only enable an experiment. See the how-to guide and the proposal for the full design.

⚠️ Postfix aliases and self

The aliasv2 experiment, also ongoing since v0.15.0, is now stable: from language version v0.18.0 on, the postfix alias syntax and the predeclared self identifier need no opt-in, and the old prefix syntax is no longer accepted.

x~(X):          {a: 1, b: X.a} // was x: X={a: 1, b: X.a}
[string]~(K,_): {name: K}      // was [K=string]: {name: K}

// A value alias becomes a let binding on self.
y: {
	let Y = self
	c: 2
	d: Y.c // was y: Y={c: 2, d: Y.c}
}

As above, run cue fix --exp=aliasv2 to rewrite the prefix form before the module moves to v0.18.0; cue fix --exp=explicitopen,aliasv2 applies both of this release's migrations in one pass. See the how-to guide and the proposal.

The new functions experiment

This release introduces the functions experiment, which adds function literals, function types, and calls to the language. A function literal declares its parameters, may constrain its result with ->, and defines its body after the final :; a call supplies arguments by position or by label. Functions are values: they unify with themselves and with function types, they capture the scope they are declared in, and they may be applied partially.

You can try this experiment on a module at language version v0.18.0 via the @experiment(functions) file attribute:

@experiment(functions)

add:   func(a: int, b: int) -> int: a + b
scale: func(x: int) -> int: x * 2
out:   add(1, scale(3)) // 7

A literal without a body denotes a function type, which constrains a function value in the same way a schema constrains a struct. See the proposal discussion for the full design, including parameter forms, contract labels, and partial application.

Evaluator

Fix a recursive disjunction wrapped in a struct dropping disjuncts and growing exponentially in cost (#4475), and a definition whose body compares the definition itself against _|_ overflowing the stack (#4176).

Further bugs causing spurious errors have been fixed: let bindings referring to their enclosing scope could still misresolve or fail as cyclic in some cases (#4474, #4478), and a struct literal embedding a self-referencing scalar reported a structural cycle (#4479). Thank you to all who reported these.

A comprehension now runs after the sibling conjuncts whose values it reads, rather than in declaration order, so a configuration which resolved only when its fields happened to be written in the right order now resolves either way (#4098).

== and != now compare integers and floats numerically wherever they appear, so {a: 1.0} == {a: 1} and [1.0] == [1] are true, matching how 1.0 == 1 already behaved at the top level (#4120). cue.Value.Equals and list.Contains change in the same way.

Error reporting is more precise in two further ways. An error about a field which was closed off by an earlier comprehension or reference cycle now points at the declaration responsible for it (#2615). Failing disjuncts which report different errors at the same position are no longer collapsed into one, so all of the reasons a disjunction failed are shown (#4477).

cmd/cue

cue cmd now unifies data files named on the command line with the loaded package, as the other commands do and as cue help inputs documents, so tool files can finally see that data (#4473).

-e expressions are now parsed and compiled at the language version of the module they are evaluated against, so they may use the features which are stable there, such as self to select a field whose name is not an identifier (#358, #4297).

tool/http.Do gains a timeout field and now aborts when its task is canceled (#4467), and tls.caCert accepts the CERTIFICATE PEM blocks which certificate authorities hand out rather than only PUBLIC KEY blocks, reporting an error instead of trusting nothing when it yields no certificates (#4468).

tool/http.Serve no longer crashes the whole cue cmd process on an out-of-range statusCode, and writes nothing until the entire response is known (#4465).

Modules

Each module's files are now parsed at the language version that module declares, rather than at the main module's version, so a module which has moved to v0.18.0 can still depend on packages written for an older version of CUE.

An HTTP failure from a module registry, such as a rate limit, is now reported as such instead of as an opaque decoding error (#3696).

A module version is now downloaded at most once per process, which avoids redundant fetches and the "Access is denied" failures seen on Windows when two fetches of the same version overlapped (#3413).

LSP server

Standard library imports now resolve, so strings, list, and the rest offer completion and hover like any other package, and builtin functions show their signature rather than an opaque _.

Organize Imports now groups imports the way goimports does, preserving the groups written in the source and sorting standard library imports ahead of module imports within each group, and leaves the buffer alone when it does not parse cleanly.

Doc comments are now surfaced on comprehensions, let declarations, embeddings, list elements, and call arguments, and completion no longer fires in places where no identifier can go, such as inside attributes and import specs.

The language server now also reloads the packages which import a module that has gone away, and fixes further panics and cache staleness bugs.

As always, the language server is under active development: please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack. See our Getting Started wiki page for instructions on how to set it up with your editor.

Encodings

The JSON Schema encoder gains two further generation improvements: list.MinItems for the minItems keyword, and positional item schemas encoded by index (#3485).

The JSON Schema decoder now gives every decoded constant the position it came from, so an error against one member of an enum points at that member rather than at the keyword (#4477).

Go API

The new cue/ast.Clone function copies a syntax tree, including its comments and its resolved references, so a tree can be rewritten without disturbing the original.

cue/format exposes the knobs of the new formatter: its new Indent, IndentWidth and LineWidth options control the indentation string, its visual width, and the target line width, and its new Compact option renders a value on a single line. UseSpaces and TabIndent are deprecated in favor of Indent and IndentWidth; go fix migrates uses of UseSpaces.

Inlining imports, via cue def --inline-imports or cue.InlineImports, now handles let declarations and values which have been unified or merg...

v0.18.0-alpha.1

Changes which may break some users are marked below with: ⚠️

Language

⚠️ Pattern constraints may no longer be marked as optional or required: [string]?: int and [string]!: int are now rejected by the parser, matching the spec grammar. A pattern constraint is optional by construction, so the markers had no effect; simply remove them (#3716).

The comparison bounds == and != now work with boolean values, so constraints like !=true behave as documented in the spec (#4388).

Fix a spurious parse error for fields named try, such as try: x (#4394).

Evaluator

Several hangs and panics have been fixed: a hang when chaining disjunctions across nested fields (#4453), and panics involving disjunctions (#4447) and pattern constraints with cue eval -e (#4449).

Several bugs causing spurious errors have also been fixed: let bindings referring to their enclosing scope could misresolve or fail as cyclic (#4428, #4440); or() over a cyclic reference could report a spurious structural cycle (#4399); and looking up a field could force the evaluation of unrelated comprehensions and disjunctions, producing errors out of thin air (#4448). Thank you to all who reported these.

"Incomplete value" errors now include the positions of the values involved, making it easier to locate the offending field in a large configuration (#2507).

cmd/cue

⚠️ The new formatter is enabled by default

The formatv2 experiment, announced in v0.17.0, is now enabled by default: cue fmt and the cue/format Go API are backed by a rewritten formatter. The new implementation resolves long-standing issues with the old one, in particular around the alignment of fields and trailing comments and the layout of multi-line expressions, so expect some reformatting when running cue fmt over existing files.

The old formatter remains available via CUE_EXPERIMENT=formatv2=0 for v0.18; v0.17 also accepts the formatv2 experiment name, so the setting can be shared by teams using both versions. Please report any misformatting via the issue tracker, as we intend to remove the old formatter once the new one is stable.

Other changes

CUE packages can now be combined with individual schema and data files in a single invocation, such as cue vet ./schemapkg extra-schema.json data.yaml, and the --package flag now treats individual CUE files the same way as packages (#3341, #3671, #3914).

cue vet now honors all -d/--schema flags rather than only the last one (#3726), and -e expressions now apply only to the selected expressions, avoiding spurious errors from unrelated parts of the input (#3371).

Tool tasks such as exec.Run, file.Read, and cli.Ask now surface evaluation errors in their fields, such as a broken stdin value, rather than silently treating them as unset.

Modules

Imports using a redundant package qualifier, such as foo.com/bar:bar, now resolve correctly in all cases (#4446).

@embed now works in files named directly on the command line within a module, and in packages loaded from dependency modules (#4439).

Wildcard package patterns such as ./.../name now match the package path in full rather than any of its suffixes (#3212), and package directory arguments with a trailing slash or a relative form now behave consistently (#3707).

Module registry errors are clearer: they now name the registry host and the module involved without repeating them at every level (#2952, #3611). cue mod publish now works with registries which reject overwriting existing blobs (#3340).

LSP server

Hovering over a field now shows its value with all conjuncts unified, and doc comments shown on hover now follow the semantic ownership rules of the language, such as attaching to the innermost field of a shorthand like a: b: c (#2672).

The language server is also more robust: it now notices files created on disk which satisfy previously failing imports or @embed patterns, publishes diagnostics for files with syntax errors and clears them for closed files, preserves comments when organizing imports, and fixes several panics and cache staleness bugs.

Encodings

The new yamlgoccy experiment, enabled by default, backs the YAML decoder and encoder with github.com/goccy/go-yaml, which retains more precise position and comment information and resolves a number of parsing bugs, such as the %YAML 1.2 directive being rejected (#3349). The old implementation remains available via CUE_EXPERIMENT=yamlgoccy=0 for v0.18.

The new openapiv2 experiment teaches cue import and cue export to handle complete OpenAPI documents — including paths, servers, and security — rather than only their component schemas. Enable it via CUE_EXPERIMENT=openapiv2; the underlying Go APIs are openapi.ExtractV2 and openapi.GenerateV2.

New output encoding tags: --out yaml+indentSequences=false emits the zero-indent list style favored by Kubernetes and others (#4177), and --out cue+compact or --out json+compact emit compact single-line output.

cue import now prefers hash-delimited strings like #"..."# when they avoid escaping, keeping strings with quotes or backslashes readable (#124).

The JSON Schema encoder can now generate JSON Schema draft-07 and the OpenAPI 3.0 dialect in addition to draft 2020-12. Generation is also improved in a number of ways: format keywords for sized number types (#2529), struct.MinFields and struct.MaxFields (#3605), bytes as base64-encoded strings (#1785), non-concrete comparison bounds (#3742), and distinct names for same-named references (#4277).

The ProtoBuf decoder now resolves unqualified references to types declared in proto files without a package (#4416).

cue get go now supports map keys which are integers or implement encoding.TextMarshaler (#3064), and translates fields of type cue.Value to _ (#3488).

Go API

The new cue.Unify function unifies many values at once, more efficiently than a chain of Value.Unify calls.

The new ast.DocComments and ast.ResolveComments functions report the doc comments that semantically document a node, resolving the field-shorthand convention.

The experimental jsonschema.GenerateMany function generates several schemas at once with a shared pool of definitions, as used by the new OpenAPI generator.

cue.Context.Encode now honors the omitzero JSON struct tag (#4429), and renders multi-line strings from json.Marshaler values as CUE multi-line strings (#3578).

tools/flow now supports tasks in a value below the root of its instance (#2185), and a data race in the task runner has been fixed (#2184).

Fix a panic in Value.Subsume involving validators with unevaluated arguments (#4387), and fix sub-values not being associated with their enclosing package instance (#2577).

The Go code generated from cue.proto is now shipped as the encoding/protobuf/cueproto package, so proto definitions using CUE options can be compiled without extra setup (#581). The compatibility shim at encoding/protobuf/cue is deprecated and will be removed in v0.19.

Full list of changes since v0.17.0

• .claude: refine the release-notes skill after drafting v0.18.0-alpha.1 by @mvdan in adba4fa
• cue/load: keep the module root of dependency instances by @mvdan in 2e12f86
• cue/load: keep FS location when re-parsing with a language version by @mvdan in 242338f
• internal/core/adt: fix panic on reinserted pattern constraint conjunct by @mvdan in cacb4b8
• internal/core/adt: fix hang when chaining disjunction cross products by @mvdan in d57c348
• yaml/goccy: test that a %YAML 1.2 directive is accept...

v0.17.1

Evaluator

Fix several regressions introduced in v0.17.0: a panic when evaluating some disjunctions (#4419), and spurious invalid interpolation (#4420), field not allowed (#4423), and structural cycle (#4430) errors involving comprehensions or self references.

Fix two regressions introduced in v0.17.0 where evaluation could hang (#4421, #4422), as well as two long-standing hangs on self-referencing configurations (#2766, #4231).

cmd/cue

Fix a panic in cue exp gengotypes, a regression introduced in v0.17.0, when a definition references a definition from another package via embedding (#4436).

Module replacements are now subject to minimum-version selection like any other dependency. cue mod tidy now normalizes a fully-pinned replacement to its major version and records the target as a regular dependency.

Full list of changes since v0.17.0

• internal/cueversion: bump for v0.17.1 by @mvdan in fc6c0b2
• internal/ci: bump pinnedReleaseGo for v0.17.1 by @mvdan in 9c720d0
• [release-branch.v0.17] internal/core: resolve import instances back to their build instance by @mvdan in 8ead2d9
• [release-branch.v0.17] internal/core/adt: allow chained re-instantiation of inline conjunctions by @mvdan in f81f772
• [release-branch.v0.17] cue/testdata/cycle: add regression test for spurious inline cycle by @mvdan in 993c44e
• [release-branch.v0.17] internal/core/adt: fix hang on let binding a self-referencing struct by @mvdan in 1cd5e1f
• [release-branch.v0.17] internal/core/adt: fix hang on self-feeding cycle advancing depth by @mvdan in ed51952
• [release-branch.v0.17] internal/core/adt: defer field-set freeze for a running resolver by @mvdan in e69e621
• [release-branch.v0.17] internal/core/adt: defer fieldSetKnown for a running field-adding conjunct by @mvdan in 459016a
• [release-branch.v0.17] internal/core/adt: do not defer resolvers during comprehension clauses by @mvdan in f89ebec
• [release-branch.v0.17] cue/testdata/comprehensions: test guard-driven premature finalization by @mvdan in 6176fb5
• [release-branch.v0.17] internal/core/adt,pkg: bound string, bytes, and list repeat counts by @mvdan in 3017156
• [release-branch.v0.17] cue/parser: limit expression nesting depth during parsing by @mvdan in f6f05bb
• [release-branch.v0.17] internal/encoding/yaml: limit the size of YAML alias expansion by @mvdan in 04d57ab
• [release-branch.v0.17] internal/core/adt: treat cyclic under-resolved values as incomplete scalars by @mvdan in 63994d5
• [release-branch.v0.17] cue/testdata/references: test a comprehension dynamic field under a let self by @mvdan in 0ba71ca
• [release-branch.v0.17] internal/core/adt: do not reclaim disjunct arc states before merging by @mvdan in b72d5b4
• [release-branch.v0.17] internal/core/adt: do not discard recomputed let cycle placeholders by @mvdan in f82d498
• [release-branch.v0.17] internal/core/adt: fix hang on dynamic field whose key is under evaluation by @mvdan in e0b974d
• [release-branch.v0.17] all: re-run tests with CUE_UPDATE=1 by @mvdan in 7d5a557
• [release-branch.v0.17] encoding/jsonschema: avoid panic on non-string element in "required" by @mvdan in f6bc350

v0.17.0

Changes which may break some users are marked below with: ⚠️

Language

The active try experiment renames the new fallback keyword, used with for comprehensions, to otherwise. fallback continues to be accepted for now, but is rewritten to the new form.

The active aliasv2 experiment now allows ~(X) as an alternative to ~X for the single postfix alias form. ~X is also rewritten as ~(X) for the sake of consistency and clarity.

Language versions v0.17.0 and later allow omitting commas in multi-line lists. Just like a newline after a struct field implies a comma, a newline after a list element now implies a comma as well.

Language versions v0.17.0 and later allow a newline or a comma before the closing bracket of an index expression, matching how lists and func arguments allow omitting trailing commas.

The language spec is tweaked to make $ a valid identifier, which was already allowed by the parser and evaluator.

⚠️ Support for the infix div, mod, quo, and rem operators has been removed. Since late 2020, these infix forms have been undocumented and rewritten by cue fix to the new function calls.

The new shortcircuit experiment

This release introduces the shortcircuit experiment, which changes the && and || operators to not evaluate the right operand if the left operand alone determines the result.

This matches the behavior already documented in the CUE spec and is consistent with most mainstream languages, but for the sake of a smooth transition for end users, we are rolling out this change via an experiment.

You can try this experiment via the @experiment(shortcircuit) file attribute. To mimic the old behavior with the experiment, you can use a hidden field:

_y: Y
if X && _y {}

Evaluator

Comprehensions

The comprehension algorithm now waits to run a comprehension's body until the fields it reads have a concrete value, rather than trying to produce its fields up front. This resolves a number of long-standing bugs, most notably the last known regressions from evalv2, where a comprehension that should have resolved instead failed as an incomplete value or a cycle.

This design also greatly simplifies upcoming evaluator work, such as introducing new builtins to replace comparing values to bottom, as well as the design of evalv4.

Other changes

The evaluator no longer deduplicates errors just by position, which was causing some useful errors from disjunctions or standard library calls to be dropped incorrectly.

Several long-standing cycle-detection bugs have been fixed, such as self-referential uses of matchN and matchIf, self-feeding disjunctions, and comprehensions that read a let binding which refers back to the comprehension's own fields.

Fixed a bug where the same package imported via different qualified import paths (e.g. foo.com/bar@v0 or foo.com/bar:baz) did not share the same hidden field namespace.

Resolving an unversioned import from a dependency module now respects that module's own default major version, instead of always using the main module's default.

Fix a number of issues where cue def could produce invalid CUE output, such as due to name conflicts.

Fix an evaluator regression where embedded disjunctions across packages may not correctly apply closedness.

Fix an evaluator bug where cue.Context.BuildExpr of close({}) did not actually result in a closed struct.

Fix a bug where some calls to standard library functions or validators did not include the "error in call to pkg.Func" error context, or included it twice.

A few changes to the evaluator should reduce allocated objects by up to 16%, reducing GC overhead and memory usage.

To ease the transition into the new formatter we plan to release with v0.18, CUE_EXPERIMENT=formatv2=0 is now allowed as a no-op.

A number of other bugs, panics, and hangs have been resolved as well.

cmd/cue

Module replaces

CUE now supports substituting a module dependency with a local directory or a different remote module during development - for example while testing a fix to a dependency before it is published, or to replace a dependency with a fork including improvements.

This configuration lives in cue.mod/local-module.cue, which is excluded when publishing to registries. cue mod edit and cue mod tidy gain support for maintaining this file.

We have also published a how-to guide on replacing a dependency with a local module.

Read the full design doc in the proposal, or read the cue.mod/local-module.cue reference docs.

Other changes

The new global -C or --chdir flag runs cue from the given working directory.

Command input parsing is improved so that CUE packages can come after data files, such as cue vet -c data.yaml ./schema.

cue import --with-context now ensures that data represents the original raw input data, and not its interpretation like JSON Schema.
cue import --path now skips over null values in an input stream, such as empty documents in a YAML file.

Fix a bug where the flag cue export --path was ignored when the inputs were pure CUE.

The new cue exp gengotypes --outfile flag controls the output file path when generating a single package.

cue vet -d/--schema now supports hidden fields, and correctly reports an error when the command inputs are CUE only.

cue fix and cue trim no longer change file modification times when no changes are necessary.

A $CUE_CACHE_DIR directory is no longer required when loading CUE without external dependencies.

The "filetypes" lookup tables now use a more compact encoding, saving about 150KiB in binary size for cmd/cue as well as Go API users.

LSP server

Add an initial version of organize-imports, which sorts the existing imports and removes unneeded imports. It is not yet capable of suggesting missing imports.

Wait for a short period of inactivity before sending diagnostics to the editor. This "debounce" means that a user typing incomplete CUE syntax will not be distracted with syntax errors as much.

The aliasv2 experiment is now fully supported.

The rename function is fixed to distinguish between field names and aliases.

Improve field name analysis in general so that fields with multiple aliases (e.g. v=[k=string]: _) are properly supported.

Improve attribute handling for file-level embedded attributes, and to attach attributes within expressions to the correct struct.

Treat conjunctions (&) and disjunctions (|) the same way for goto-definition. With the cursor on a path, it returns all results that the path MAY resolve to. With the cursor on a field declaration name, it returns all results that the path constructed from the field's name, and its field's name (and so on) MAY resolve to.

Special-case close function calls so that paths can resolve through fields within the argument to close.

Encodings

⚠️ The experimental JSON Schema encoder now emits most definitions without the leading # character, shortening names and ensuring compatibility with the wider JSON Schema ecosystem. This required deprecating encoding/jsonschema.GenerateConfig.NameFunc in favor of NamesFunc.

The JSON Schema encoder is improved to support list.UniqueItems and standalone validators, to use maxItems and minItems instead of maxLength and minLength for lists with prefix elements, and to generate description keywords for doc comments.

Several closedness bugs in the JSON Schema encoder have been fixed, ensuring that the generated JSON Schema behaves the same way as the original CUE definition.

The JSON Schema decoder is improved to better handle the prefixItems keyword.

The ProtoBuf decoder now resolves relative references following the usual scoping rules, instead of always resolving them against the top-level scope.

Standard library

Add time.ToUnix and time.ToUnixNano, which convert an RFC3339Nano time value into seconds or nanoseconds since the Unix epoch, complementing the existing Unix builtin.

strconv.FormatFloat now accepts a string format parameter, like FormatFloat(3.14, "e", 4, 64).

list.MatchN now shows what expected value it's matching against when it fails.

The net IP APIs now consistently return an error on invalid input types.

Go API

Using cue.Values concurrently is now fully supported, which required deprecating cue.Value.Context. If you encounter any races or bugs, please report them via the issue tracker.

cue/load now supports loading from an io/fs.FS, as outlined in proposal #4285. Loading file embeds through Config.Overlay and Config.FS is supported now as well.

cue/ast/astutil deprecates Sanitize in favor of the new SanitizeFiles API, given that Sanitize on a single file cannot know if another file in the same package shadows builtin names like self.

Add Path.Compare and Selector.Compare, providing allocation-free total ordering suitable for slices.SortFunc.

Clarify that cue/format indents with a tab width of 4 by default.

A new fuzzer has been introduced in the cue package, checking that the parser doesn't crash and that its results are consistent with the rest of the Go APIs like cue/literal. So far, it has already resulted in seventeen bug fixes.

The cue.Interpreter option API has been depr...

v0.17.0-rc.1

Evaluator

A performance optimization for the or builtin function has been reverted, as it caused a regression when its arguments included cyclic references.

Fix a regression introduced since v0.16.0 where a "field set was already referenced" error could appear when using an if comprehension inside a let block.

To ease the transition into the new formatter we plan to release with v0.18, CUE_EXPERIMENT=formatv2=0 is now allowed as a no-op.

cmd/cue

Module replaces are adjusted to rename the replace field in cue.mod/local-module.cue to replaceWith. See the proposal discussion for more information.

The "filetypes" lookup tables now use a more compact encoding, saving about 150KiB in binary size for cmd/cue as well as Go API users.

Full list of changes since v0.17.0-alpha.3

• cue/format: revert #4296 regression test by @mvdan in e73658d
• cue/format: revert manual-AST field alignment fix by @mvdan in c3f08a1
• cue/format: revert issue #1006 test cases by @mvdan in 60e1bb7
• cue/format: revert list and call argument column alignment fix by @mvdan in 3f7aafe
• cue/format: revert spurious empty line fix by @mvdan in e2eb7f5
• cue/format: revert Option-behavior test by @mvdan in 0fa6c09
• cue/format: revert default tab width change from 8 to 4 by @mvdan in 1e07f16
• cue/format: revert multiline string interpolation indentation fix by @mvdan in 7190842
• internal/cueexperiment: teach v0.17 about the formatv2 experiment by @mvdan in 8d2db9d
• cmd/cue: test sharing CUE_EXPERIMENT=formatv2 across v0.17 and v0.18 by @mvdan in ac083b5
• Revert "internal/core/compile: return Disjunction directly from or() builtin" by @mvdan in bc31ef8
• all: hide the "ini" decoder for v0.17 by @mvdan in 0f15eed
• internal/core/compile: re-run with CUE_UPDATE=1 by @mvdan in 4bec06b
• all: stop using "directive" terminology for module replaces by @mvdan in 9916719
• cmd/cue: test that mod publish rejects an invalid module path by @mvdan in 376a328
• mod/modfile: rename the local-module.cue replace field to replaceWith by @mvdan in b32aca7
• internal/ci: stop running trybot jobs with pull_request_target by @mvdan in 61bcbc9
• internal/filetypes: shrink embedded toFile lookup tables by @mvdan in 01907a9
• internal/core/adt: do not freeze fieldSetKnown while an own field task is pending by @mvdan in 906c3e9
• cue/testdata/eval: add test for issue 4392 list-in-let freeze regression by @mvdan in 7d77fe7
• mod/modzip: reject a downloaded module containing local-module.cue by @rogpeppe in 4d73286
• cue/cmd: more replacement test cases by @rogpeppe in a4372d3

v0.17.0-alpha.3

Changes which may break some users are marked below with: ⚠️

Evaluator

Several long-standing cycle-detection bugs have been fixed, such as self-referential uses of matchN and matchIf, self-feeding disjunctions, and comprehensions that read a let binding which refers back to the comprehension's own fields.

Fixed a bug where the same package imported via different qualified import paths (e.g. foo.com/bar@v0 or foo.com/bar:baz) did not share the same hidden field namespace.

Fix a data race which could occur when concurrently loading the same imported packages.

cmd/cue

Module replace directives

cue now supports replace directives, letting you substitute a module dependency with a local directory or a different remote module during development - for example while testing a fix to a dependency before it is published, or to replace a dependency with a fork including improvements.

This configuration lives in cue.mod/local-module.cue, which is excluded when publishing to registries. cue mod edit and cue mod tidy gain support for maintaining this file.

We have also published a how-to guide on replacing a dependency with a local module.

Read the full design and provide feedback in the proposal, or read the cue.mod/local-module.cue reference docs.

Other changes

Resolving an unversioned import from a dependency module now respects that module's own default major version, instead of always using the main module's default.

Fix a bug where the flag cue export --path was ignored when the inputs were pure CUE.

cue import --with-context now ensures that data represents the original raw input data, and not its interpretation like JSON Schema.
Command input parsing is improved so that CUE packages can come after data files, such as cue vet -c data.yaml ./schema.

A $CUE_CACHE_DIR directory is no longer required when loading CUE without external dependencies.

Standard library

Add time.ToUnix and time.ToUnixNano, which convert an RFC3339Nano time value into seconds or nanoseconds since the Unix epoch, complementing the existing Unix builtin.

Go API

⚠️ The modconfig.Registry interface is changed to report default major versions, which is required for resolving unversioned imports against each dependency module's own defaults. Clients that implement or wrap the interface will need to update. The new interface is future-proofed for upcoming modules changes.

Full list of changes since v0.17.0-alpha.2

• cmd/cue: reject non-string label values for --path by @mvdan in 5a0f4f7
• cmd/cue: add test for --path with a non-string label value by @mvdan in 772d1d3
• update dependencies ahead of v0.17.0-alpha.3 by @mvdan in b7d1625
• cmd/cue: drop github.com/google/shlex test dependency by @mvdan in 69bf7d7
• cue/load: accept package arguments after file arguments by @mvdan in dd80111
• cmd/cue: add test for package arguments listed after files by @mvdan in ed3622b
• internal/cuetxtar: port old stats framework by @mpvl in 489b249
• encoding/ini: pass token.Pos through the decoder directly by @mvdan in 91a3f18
• encoding/ini: minor decoder cleanups by @mvdan in 5b8ba6e
• encoding/ini: reject section and property name collisions by @mvdan in eb8ac73
• cue/testdata: add missing error output for issue2627 by @mpvl in 092c281
• Revert "cue/errors: augment paths of wrapped errors" by @mvdan in a361a5b
• cmd/cue: add replace directive support to mod edit by @rogpeppe in 9984dae
• internal/mod/modload,mod/modzip,cmd/cue: tidy and publish two-file modules by @rogpeppe in 5adf7f5
• mod/modfile,cue/load: read replace directives from local-module.cue by @rogpeppe in 12ecd27
• all: add core plumbing for module replace directives by @rogpeppe in 74d78c1
• cue/build,cue/load: fix hidden-field namespace for versioned imports by @rogpeppe in b159ed1
• cue/testdata: add regression test for issue #2937 by @mvdan in 39d5c4e
• cue/errors: augment paths of wrapped errors by @mvdan in 71c13d2
• pkg/encoding/json: add test for Validate hiding the failing field by @mvdan in 8507be6
• pkg/time: add ToUnix and ToUnixNano builtins by @mvdan in d5a3fb7
• cmd/cue: honor -l/--path when exporting CUE values by @mvdan in 0abb86e
• cmd/cue: add test for export -l with CUE output by @mvdan in 14d7d4d
• all: make more use of string cut/trim/contains APIs by @mvdan in 40ad26f
• internal/mod/modpkgload,cue/load: resolve major version defaults per module by @rogpeppe in b24b39c
• cue: format builtin call's function operand as a bare reference by @mvdan in 7392c8e
• cue: add test for builtin call function operand formatting by @mvdan in 72ff12b
• cue/parser: support try clauses in list literals by @mvdan in b0a4125
• cmd/cue: point to 'cue help flags' from the --with-context flag by @mvdan in 8b9f8be
• cmd/cue: evaluate --with-context labels against the source data by @mvdan in 9bb021f
• mod/modconfig: lazily initialize registry clients by @mvdan in 44f24f1
• cmd/cue: test various command scenarios without cache/config dirs by @mvdan in 445c76d
• cmd/cue: add test for label references with jsonschema import by @mvdan in f33b9de
• internal: only wrap over-long generated comment lines by @mvdan in b682521
• encoding/jsonschema: add test for doc comment reflow by @mvdan in fa683ed
• internal/core/adt: handle cycle placeholder for composite builtins by @mpvl in 32244d1
• internal/core/adt: guard nodeContext free on refCount by @mpvl in 03748aa
• internal/cuetxtar: fix inline runner writeStruct cycle and BasicType embed by @mpvl in afa5272
• cue/testdata: add test case demonstrating #2627 reopen by @mpvl in 684e354
• internal/core/adt: resolve imports to a per-evaluation instance by @mvdan in 86eb4f1
• cmd/cue: add test cases for issues 4370 and 4371 by @rogpeppe in 230bbbb
• internal/mod: minor module-related code improvements by @rogpeppe in 964c012
• internal/core/adt: test optional field referencing pushed-down comprehension by @mvdan in 32e6da5
• encoding/jsonschema: compile CRD schema only once by @mvdan in 139794b
• internal/core/adt: attribute failed try references to the owning body by @mvdan in 8c8c47c
• cue/testdata: add regression tests for nested try clauses by @mvdan in f7a59da
• internal/core/adt: fire comprehensions on let-bound self references by @mvdan in f6d7894
• internal/core/adt: add test for comprehensions on let-bound self references by @mvdan in c60ba81
• internal/core/adt: bound self-feeding disjunction recursion in cycle detection by @mvdan in 43d216f
• cue/testdata: add a test for the cycle-detection blowup of issue #4377 by @mvdan in e7d5121
• cue: add regression test for FillPath exporting fields as optional by @mvdan in 00df6eb
• internal/core/compile: detect structural cycles in self-referential matchIf by @mvdan in ec1313c
• internal/core/compile: detect structural cycles in self-referential matchN by @mvdan in d1a6540
• cue: accept a leading index in ParsePath by @mvdan in 0b61fdf
• cue: add TestPaths cases for a leading index in a path by @mvdan in a035333
• cue: give each TestPaths case its own CUE input by @mvdan in 5cf0e58
• pkg/list: add regression test for list.Contains with defaults by @mvdan in 7c6d8ae

v0.17.0-alpha.2

Changes which may break some users are marked below with: ⚠️

Language

The parser now allows a newline or a comma before the closing bracket of an index expression, matching how lists and func arguments allow omitting trailing commas:

foo[
    "bar"
]

Evaluator

The comprehension algorithm now waits to run a comprehension's body until the fields it reads have a concrete value, rather than trying to produce its fields up front. This resolves a number of long-standing bugs, most notably the last known regressions from evalv2, where a comprehension that should have resolved instead failed as an incomplete value or a cycle.

This design also greatly simplifies upcoming evaluator work, such as introducing new builtins to replace comparing values to bottom, as well as the design of evalv4.

The evaluator no longer deduplicates errors just by position, which was causing some useful errors from disjunctions or standard library calls to be dropped incorrectly.

A number of bugs, panics, and hangs have been resolved as well.

cmd/cue

cue vet -d/--schema now supports hidden fields, and correctly reports an error when the command inputs are CUE only.

cue fix and cue trim no longer change file modification times when no changes are necessary.

Encodings

⚠️ The experimental JSON Schema encoder now emits most definitions without the leading # character, shortening names and ensuring compatibility with the wider JSON Schema ecosystem. This required deprecating encoding/jsonschema.GenerateConfig.NameFunc in favor of NamesFunc.

Several closedness bugs in the JSON Schema encoder have been fixed, ensuring that the generated JSON Schema behaves the same way as the original CUE definition.

The ProtoBuf decoder now resolves relative references following the usual scoping rules, instead of always resolving them against the top-level scope.

Go API

Add Path.Compare and Selector.Compare, providing allocation-free total ordering suitable for slices.SortFunc.

Full list of changes since v0.17.0-alpha.1

• .claude: add a skill to draft release notes from a commit log by @mvdan in 7935fe8
• internal/ci: bump Go and goreleaser for the upcoming alpha by @mvdan in c2a8155
• encoding/jsonschema: mark generation as experimental by @rogpeppe in 223cfa7
• encoding/protobuf: translate google.protobuf.Struct to an open struct by @mvdan in ef3e0ee
• internal/core/adt: report true element count for list length mismatch by @mvdan in d474938
• cue/testdata: add test for list-length error with comprehensions by @mvdan in 40961bb
• cue: fix Value.ReferencePath after Eval when sharing is disabled by @mvdan in 9a6d76d
• cue: clarify Value.ReferencePath path semantics by @mvdan in 0adb8dd
• pkg/list: report a missing less field as a fatal error by @mvdan in 6aa4a11
• cmd/cue: fix vet -d resolving a hidden constraint by @mvdan in 5651def
• cmd/cue: add test for vet -d with a hidden constraint by @mvdan in 1a0c02c
• pkg/encoding: report every Validate conflict by @mvdan in 81f9d1b
• pkg/encoding: add tests for Validate reporting a single conflict by @mvdan in 5310062
• mod/modconfig: delete the dummy $DOCKER_CONFIG dir when the tests are done by @mvdan in ffb2fbd
• cue/errors: deduplicate without rendering errors unnecessarily by @mvdan in e9f02ca
• cue/errors: report all distinct errors at the same position by @mvdan in 774942d
• cue/errors: add a test recording how often removeMultiples renders errors by @mvdan in 2ba0d46
• cue/errors: add tests for distinct errors dropped at the same position by @mvdan in a753484
• modconfig: update ociregistry to pick up ociauth fix by @mvdan in e5e958e
• internal/core/debug: only print integer-labeled arcs of a list value by @mvdan in 8fdf9d5
• pkg/list: add a regression test for list error printing hidden arcs by @mvdan in f9b4c66
• internal/filetypes: clarify error for combined file type and file name by @mvdan in b15022d
• cmd/cue: add a regression test for issue 3187 by @mvdan in 8273d6f
• cue: avoid panic in Value.Path for dereferenced let bindings by @mvdan in 58f2356
• internal/core/adt: recompute cached let results that resolved to a cycle by @mvdan in 4a67df9
• cue/testdata/cycle: add regression test for issue 4357 by @mvdan in ffc0541
• cue/testdata: add #4149 regression test for or structural cycle by @mvdan in 803c837
• internal/cuetxtar: keep nested inline positions relative by @mpvl in dede65a
• internal/core/adt: detect structural cycle through inline conjunction by @mvdan in f518389
• internal/core/compile: update compile file comments by @mpvl in 5a6110a
• internal/core/adt: loosen structure-sharing skip in cycle detection by @mpvl in aae3830
• internal/core/adt: bound self-recursion in cycle detection skip by @mpvl in 297d254
• internal/core/adt: do not treat structure sharing as a cycle by @mpvl in c37cf24
• internal/core/adt: scope task context error before deferred tasks by @mpvl in 697512f
• cue/testdata: add #4367 regression tests by @mpvl in 2735d5a
• internal/core/adt: skip typo check on cross-context Finalize by @mpvl in a9f3f2a
• all: adopt the cueckoo @-import guidance mechanism by @myitcv in 5f10676
• all: fix reversed argument order in cmp.Diff calls by @mvdan in 82d70cb
• cue/testdata/cycle: add regression test for issue 3364 by @mvdan in 40caafe
• encoding/protobuf: respect lexical scoping rules by @SteveRuble in d34b9f5
• internal/mod/modregistry: bump ociregistry to merge auth sources by @mvdan in 033671e
• cmd/cue: add test for mixing Docker and Podman auth files by @mvdan in 268fe24
• internal/core/adt: skip in-flight nodes when reclaiming buffers by @mpvl in 489f4a9
• cmd/cue: preserve mtimes in cue fix and cue trim no-op rewrites by @mvdan in 28b3474
• cmd/cue: document mtime drift in fix and trim by @mvdan in e56df9e
• cue/parser: allow a newline before the closing bracket of an index expression by @mvdan in fa44ce4
• cue/testdata: add regression test for self-referential builtin cycles by @mvdan in abe46a1
• internal/core/compile: include label-aliased fields in cross-file scope by @mvdan in 4157262
• cue/testdata: add test for issue #4312 by @mvdan in 9888e6f
• internal/core/export: fix label references in pattern constraints by @mvdan in 0c639f4
• internal/core/compile: strip @test attributes from mirrored inputs by @mpvl in b343757
• internal/core/adt: flush label-only cyclic CallExpr deferments by @mpvl in dd5b4c0
• update dependencies ahead of the next alpha release by @mvdan in 2fddd86
• cmd/cue: fix json error tests on Go tip by @mvdan in bd45f3e
• cue/testdata: add comprehension pushdown regression for inline conjunction iterator by @mpvl in 29b71ea
• encoding/ini: make dotted section-name nesting configurable by @ReginaZhangMS in cd0f418
• internal/core/adt: remove unused nodeContextState.hasOpenValidator by @mvdan in ae29eac
• internal/core/adt: remove unused Bottom.Permanent field by @mvdan in 8f8a581
• internal/core/adt: remove unused Bottom.ForCycle field by @mvdan in b24e6fd
• internal/core/adt: remove unused StructLit.isComprehension field by @mvdan in 0e0dbc1
• internal/core/adt: remove unused StructLit.IsOpen field by @mvdan in 023bcd0
• internal/ci: set GORACE in the base config by @mvdan in 0e2745d
• internal/core/adt: fix data race in concurrent FillPath by @mvdan in 06056b9
• pkg/tool/exec: default env to an empty struct by @mvdan in 74211d7
• cmd/cue/cmd: add test for exec.Run JSON marshaling by @mvdan in f44f49a
• all: make use of strings.CutPrefix by @mvdan in 34f13a2
• cue/test...

v0.17.0-alpha.1

Changes which may break some users are marked below with: ⚠️

Language

The active try experiment renames the new fallback keyword, used with for comprehensions, to otherwise. fallback continues to be accepted for now, but is rewritten to the new form.

The active aliasv2 experiment now allows ~(X) as an alternative to ~X for the single postfix alias form. ~X is also rewritten as ~(X) for the sake of consistency and clarity.

Language versions v0.17.0 and later allow omitting commas in multi-line lists. Just like a newline after a struct field implies a comma, a newline after a list element now implies a comma as well.

The language spec is tweaked to make $ a valid identifier, which was already allowed by the parser and evaluator.

⚠️ Support for the infix div, mod, quo, and rem operators has been removed. Since late 2020, these infix forms have been undocumented and rewritten by cue fix to the new function calls.

The new shortcircuit experiment

This release introduces the shortcircuit experiment, which changes the && and || operators to not evaluate the right operand if the left operand alone determines the result.

This matches the behavior already documented in the CUE spec and is consistent with most mainstream languages, but for the sake of a smooth transition for end users, we are rolling out this change via an experiment.

You can try this experiment via the @experiment(shortcircuit) file attribute. To mimic the old behavior with the experiment, you can use a hidden field:

_y: Y
if X && _y {}

Evaluator

Fix a number of issues where cue def could produce invalid CUE output, such as due to name conflicts.

Fix an evaluator regression where embedded disjunctions across packages may not correctly apply closedness.

Fix an evaluator bug where cue.Context.BuildExpr of close({}) did not actually result in a closed struct.

Fix a bug where some calls to standard library functions or validators did not include the "error in call to pkg.Func" error context, or included it twice.

A few changes to the evaluator should reduce allocated objects by up to 16%, reducing GC overhead and memory usage.

cmd/cue

The new global -C or --chdir flag runs cue from the given working directory.

cue import --path now skips over null values in an input stream, such as empty documents in a YAML file.

The new cue exp gengotypes --outfile flag controls the output file path when generating a single package.

LSP server

Add an initial version of organize-imports, which sorts the existing imports and removes unneeded imports. It is not yet capable of suggesting missing imports.

Wait for a short period of inactivity before sending diagnostics to the editor. This "debounce" means that a user typing incomplete CUE syntax will not be distracted with syntax errors as much.

The aliasv2 experiment is now fully supported.

The rename function is fixed to distinguish between field names and aliases.

Improve field name analysis in general so that fields with multiple aliases (e.g. v=[k=string]: _) are properly supported.

Improve attribute handling for file-level embedded attributes, and to attach attributes within expressions to the correct struct.

Treat conjunctions (&) and disjunctions (|) the same way for goto-definition. With the cursor on a path, it returns all results that the path MAY resolve to. With the cursor on a field declaration name, it returns all results that the path constructed from the field's name, and its field's name (and so on) MAY resolve to.

Special-case close function calls so that paths can resolve through fields within the argument to close.

Encodings

The JSON Schema decoder is improved to better handle the prefixItems keyword.

The JSON Schema encoder is improved to support list.UniqueItems and standalone validators, to use maxItems and minItems instead of maxLength and minLength for lists with prefix elements, and to generate description keywords for doc comments.

Standard library

The net IP APIs now consistently return an error on invalid input types.

strconv.FormatFloat now accepts a string format parameter, like FormatFloat(3.14, "e", 4, 64).

list.MatchN now shows what expected value it's matching against when it fails.

Go API

Using cue.Values concurrently is now fully supported, which required deprecating cue.Value.Context. If you encounter any races or bugs, please report them.

cue/load now supports loading from an io/fs.FS, as outlined in proposal #4285. Loading file embeds through Config.Overlay and Config.FS is supported now as well.

cue/ast/astutil deprecates Sanitize in favor of the new SanitizeFiles API, given that Sanitize on a single file cannot know if another file in the same package shadows builtin names like self.

Clarify that cue/format indents with a tab width of 4 by default.

A new fuzzer has been introduced in the cue package, checking that the parser doesn't crash and that its results are consistent with the rest of the Go APIs like cue/literal. So far, it has already resulted in seventeen bug fixes.

The cue.Interpreter option API has been deprecated in favor of cue.WithInjection, which is a better name going forward.

⚠️ cue/ast.File.Imports, deprecated in mid 2025 in favor of cue/ast.File.ImportSpecs, is now removed.

⚠️ The long-deprecated and hidden cue.Instance methods Lookup, LookupDef, LookupField, and Fill are now removed.

Full list of changes since v0.16.0

• internal/ci: bump Go and goreleaser versions for v0.17.0-alpha.1 by @mvdan in d11a8f8
• cue/ast/astutil: deprecate Sanitize in favor of SanitizeFiles by @mvdan in 89b80ad
• cmd/cue/cmd: add regression test for hidden fields like _5 by @mvdan in 1ed8051
• cmd/cue/cmd: add regression test for vet list.Contains errors by @mvdan in c2f7338
• update dependencies ahead of v0.17.0-alpha.1 by @mvdan in 03f2868
• cue/testdata/cycle: add test for issue #4253 by @mvdan in f31ac4d
• encoding/ini: introduce an INI decoder by @ReginaZhangMS in e5482ee
• cue/load,internal/mod/modpkgload: respect nested cue.mod boundaries by @mvdan in de61149
• all: use slices and maps iterators for collect-and-sort patterns by @mvdan in 8345fc2
• cmd/cue/cmd: document wrong nested-module behavior for issue 2707 by @mvdan in 8ff6cee
• all: use strings.SplitSeq and strings.Cut to avoid intermediate slices by @mvdan in 1ea5ad5
• all: fix stray and misplaced doc comments by @mvdan in 64eaf2f
• cue/inject/embed: resolve files via cue/load.Config's FS or Overlay by @mvdan in b0ce1f5
• internal/core/export: sanitize Profile.Value output by @mvdan in d846deb
• cue: add regression test for predeclared builtin shadowing in %v by @mvdan in 6040780
• cmd/cue: list user-defined commands in cue cmd --help by @mvdan in fbcd9f7
• internal/core/export: mark predeclared builtin references as such by @mvdan in d3187e5
• internal/core/export: add test for predeclared builtin shadowing by @mvdan in 922493a
• internal/core/adt: fix conjunction semantics for opened embeddings by @mpvl in 619d46e
• tools/fix: extract and extend explicitopen fix by @mpvl in 349c457
• cmd/cue: add -C flag, like go and git by @mvdan in 079f1a3
• internal/core: __reclose: detect and restore non-recursive closing by @mpvl in 3091146
• tools/fix: add inline @test framework by @mpvl in f679d39
• cue/ast/astutil: detect aliasv2 postfix label-name redeclarations by @mvdan in 27b5e67
• cue/ast/astutil: add test coverage for redeclared alias errors by @mvdan in 6d45692
• internal/core/adt: document why toComplete hook must stay by @mpvl in 5ae2c12
• internal/core/adt: remove completeNodeTasks from doDisjunct by @mpvl in a6b5a9f
• internal/core/adt: strengthen field-set and arc-type checks by @mpvl in 5750aa5
• .claude: remove deny clause by @rogpeppe in aa0b641
• encoding/jsonschema: support description keyword by @rogpeppe in 70043a5
• cue: allow and enforce parens for single postfix alias by @mpvl in d05d75f
• internal/core/adt: remove dead code in process and evalStateCI by @mpvl in 1ebe938
• internal/core/adt: fix error propagation bug in inline structs by @mpvl in 881d9cf
• internal/core/adt: remove support for list task dependencies by @mpvl in 75af110
• internal/core/adt: remove taskPos field from scheduler by @mpvl in 003a182
• internal/core/adt: add handleParents and processAncestors by @mpvl in 61fb61b
• cue/ast/astutil,tools/fix: add cross-file shadowing detection for predeclared ide...

v0.16.1

Language

The fallback keyword in the aliasv2 experiment is replaced by otherwise, which is clearer. cue fmt or cue fix can be used to rewrite existing code.

Evaluator

Fix a regression where the compiler could add comments to the input AST value, which could lead to increased memory usage.

Fix a bug where exporting certain schemas could result in "cannot have both alias and field in same scope" errors.

cmd/cue

Fix a panic which could occur when using non-label expressions in the --path flag.

Teach cue login to give helpful errors when used with OCI registries which don't support the OAuth2 device flow.

Go API

Fix a regression where cue.Context.Encode could panic on custom marshaler types with pointer receivers.

Full list of changes since v0.16.0

• internal/cueversion: bump to v0.16.1 by @mvdan in 6d609d7
• internal/ci: build releases with Go 1.26.2 by @mvdan in cedf4c8
• update all golang.org/x/... dependencies by @mvdan in b4efeef
• all: rename fallback keyword to otherwise by @mpvl in f813811
• lsp/cache: improve rename by @cuematthew in 8e47027
• integration/workspace: add test showing bad behaviour by @cuematthew in a5e0ef5
• cmd/cue: suggest docker/podman login when OAuth2 device flow is unsupported by @mvdan in c169605
• cmd/cue: add testscript for cue login when device code endpoint is unsupported by @mvdan in d7c882a
• cmd/cue: clarify how to authenticate with standard OCI registries by @mvdan in 2613edf
• internal/core/compile: avoid mutating AST by @rogpeppe in e4b0516
• internal/core/export: fix alias/field name conflict in pattern constraints by @mvdan in 1e46409
• internal/core/export: add regression test for alias/field name conflict by @mvdan in 1654f66
• pkg: fix godoc mistakes across several packages by @mvdan in eae9aaf
• internal/core/convert: fix panic when encoding pointer-receiver marshalers by @mvdan in 8e39aec
• cmd/cue: return an error for non-label --path expressions instead of panicking by @mvdan in 5a55849
• encoding: add godoc hints for cue/ast result types by @mvdan in 682c663

v0.16.0

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ The cmdreferencepkg global experiment is now stable, meaning that CUE_EXPERIMENT=cmdreferencepkg is always enabled.

#"""# is now accepted as a string literal quoting a double quote, ".

Multiline string literals now require a trailing newline, matching the language spec.

The new try experiment

This release introduces the try experiment, which adds a try clause in comprehensions as well as the use of ? in field selectors. This addition to the language is intended to provide a more concise syntax for handling optional fields without the risk of unintentionally swallowing errors.

This experiment also introduces the else clause for if and try comprehensions, and the fallback clause for for comprehensions, which trigger when a comprehension produces zero values.

You can try this experiment by following our how-to guides on the try clause and the else clause. For more information, see the proposal on GitHub and the spec change patch.

Evaluator

Performance

Further improve the use of caching in the typochecker algorithm; this provides speed-ups of up to 80% on some large projects.

Very large structs (tested with 20,000 fields) are up to 80% faster now, as we were repeating some work unnecessarily.

A great deal of effort has gone into reducing the allocations and memory usage across a number of projects. For some of these, memory usage is down by as much as 60%.

These improvements were possible thanks to our Unity service, letting us analyze CUE's performance and test for regressions on third party projects. Contact @mvdan on Discord, Slack, or via the Unity page to ensure that your project is included or you are running into slowness.

A number of changes were made to improve support for using cue.Values concurrently; see Issue #2733 for more details and ongoing progress.

Other changes

Fix a regression introduced in v0.13 where the or built-in with literal arguments could stop behaving like a disjunction.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

Add support for $DOCKER_AUTH_CONFIG to directly provide the contents of $DOCKER_CONFIG/config.json to authenticate with module registries, matching Docker's current behavior.

The --outfile flag now works when given non-regular files such as named pipes or sockets.

⚠️ cue mod publish no longer ignores sub-directories containing a go.mod file.

⚠️ Using cue inside the cue.mod directory now fails consistently with a clear error message to not place CUE code there. Previously, some commands worked while others failed with confusing errors.

⚠️ The global --verbose and --trace flags have been moved to the cue get go and cue trim commands respectively, as they were the only ones actually using those flags, and this could be confusing to users.

Fix a bug where loading ./...:pkgname could lead to loading directories without CUE files as instances, which could cause poor performance for CUE packages with multiple parent directories.

cue exp writefs gains an encoding optional field for regular files, to specify an encoding rather than infer it from the filename extension.

LSP server

Initial LSP support for editing embedded JSON and YAML files. This feature provides completions and hover-docs when editing JSON or YAML files which are embedded into CUE via the @embed attribute. A teaser video is available on YouTube.

Code Actions: two code actions are now provided, Add surrounding struct braces and Remove surrounding struct braces, which convert between

a: b: c

and

a: {
	b: c
}

with the cursor on b.

A complete overhaul of how the LSP server suggests code completions. This solves the previous naïve implementation which would only make suggestions after a field name or path had been started. Now completions are available from within whitespace.

Embedded paths with mutual dependencies: embedded paths with multiple components (e.g. a.b.c) can in some cases only be fully resolved after the resolution of other embedded paths. The LSP server can now correctly handle these dependencies.

The LSP server now implements LSP Document Symbols functionality. This is often used by editors to provide light-weight breadcrumb navigation within a file.

Some preliminary diagnostics are now sent from the LSP server back to the editor. Initially this mainly indicates syntax errors in CUE files, but this can be extended in the future.

Many bug fixes, including better behaviour for files and directories with spaces; improvements for value aliases (foo: L=x); LSP rename now provides placeholder text; improved jump-to-definition behaviour for package-level fields; fixed issues around imports; path resolution; formatting of standalone CUE files; and others.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

Add support for encoding YAML tags like key: !Custom value by using CUE attributes like key: "value" @yaml(,tag="!Custom").

cue get go now detects which Go packages use Kubernetes type semantics via // +k8s:openapi-gen=true and obeys the field annotations // +optional and // +nullable.

cue get go gains a --codec flag to configure the use and priority of Go struct field tags like json or yaml.

Fix a bug where cue get go could skip over fields whose type implements one of the supported marshaling interfaces.

Fix a few bugs where cue get go could result in invalid or failing CUE code.

JSON Schema's Config.OpenOnlyWhenExplicit option is now exposed for the CLI via the filetype tag jsonschema+openOnlyWhenExplicit.

JSON Schema now properly encodes hash references for better compatibility with other tools.

Standard library

The strconv package adds ParseNumber, like ParseInt or ParseFloat but allowing other CUE number strings such as 1Ki.

The net package adds InCIDR to test whether an IP is contained by a CIDR string.

The net package adds ParseCIDR to extract useful information from a CIDR string.

The net package adds CompareIP to compare two IP addresses, which can be useful for computing with IP ranges.

The net/http package adds Serve as an experimental API to listen on a port and serve HTTP requests.

The tool/file package adds Symlink to create symbolic links.

Go API

cue.Value.Decode now supports the new cue.Unmarshaler interface, allowing Go types to implement their own CUE value decoding logic via an UnmarshalCUE(cue.Value) error method.

The new cue.IsIncomplete function reports whether the given value is a CUE incomplete error.

cue/ast gains the NewPredeclared and Ident.IsPredeclared to mark and detect identifiers referencing predeclared names like error or int rather than fields which may shadow those names in the current scope.

⚠️ cue.Value.Decode now uses cue.IsIncomplete to not treat incomplete errors as fatal, allowing the decoding to continue.

Fix a bug where cue.Value.Decode could behave incorrectly when decoding a CUE null or incomplete value.

⚠️ cue/token.Compare now sorts absolute paths before relative ones, to ensure consistent behavior between Unix-like systems and Windows.

⚠️ The long-deprecated cue/ast.Node.Comments and cue/ast.Node.AddComment interface methods are now removed; use cue/ast.Comments and cue/ast.AddComment respectively.

⚠️ The long-deprecated and unused cue/parser.FromVersion and cue/parser.DeprecationError APIs are now removed.

⚠️ The long-deprecated and hidden cue.Instance.Eval method is now removed.

Full list of changes since v0.15.0

• internal/ci: use OIDC with the Central Registry for the e2e tests by @mvdan in de47a5e
• re-enable sta...