ontoref/adrs/adr-006-nushell-0111-string-interpolation-compat.ncl

let d = import "adr-defaults.ncl" in

d.make_adr {
  id     = "adr-006",
  title  = "Nushell 0.111 String Interpolation Compatibility Fix",
  status = 'Accepted,
  date   = "2026-03-14",

  context = "Nushell 0.111 introduced a breaking change in string interpolation parsing: expressions inside `$\"...\"` that match the pattern `(identifier: expr)` are now parsed as command calls rather than as record literals or literal text. This broke four print statements in reflection/bin/ontoref.nu that used patterns like `(kind: ($kind))`, `(logo: ($logo_file))`, `(parents: ($parent_slugs))`, and `(POST /actors/register)`. The bug manifested when running `ontoref setup` and `ontoref hooks-install` on any consumer project using Nu 0.111+. The minimum Nu version gate (>= 0.110.0) did not catch 0.111 regressions since it only guards the lower bound.",

  decision = "Fix all four affected print statements by removing the outer parentheses from label-value pairs inside string interpolations, or by removing the `$` prefix from strings that contain no variable interpolation. The fix is minimal and non-semantic: `(kind: ($kind))` becomes `kind: ($kind)` (literal label + variable), and `$\"(POST /actors/register)\"` becomes `\"(POST /actors/register)\"` (plain string). The fix is applied to both the dev repo (reflection/bin/ontoref.nu) and the installed copy (~/.local/bin/ontoref via just install-daemon). The minimum version gate remains >= 0.110.0 but 0.111 is now the tested floor.",

  rationale = [
    {
      claim  = "Minimal-diff fix over workarounds",
      detail = "The broken patterns were purely cosmetic print statements. The fix removes one level of parens — no logic change. Alternatives that added escape sequences or string concatenation would obscure the intent.",
    },
    {
      claim  = "Plain string for zero-interpolation prints",
      detail = "Strings with no variable interpolation (like the POST endpoint hint) should never use `$\"...\"`. Removing the `$` prefix makes them immune to any future interpolation parsing changes and is the correct Nushell idiom.",
    },
    {
      claim  = "just install-daemon as the sync mechanism",
      detail = "The installed copy at ~/.local/bin/ontoref is managed via just install-daemon. Patching both the dev repo and the installed copy via install-daemon is the established update path and keeps them in sync.",
    },
  ],

  consequences = {
    positive = [
      "ontoref setup and hooks-install work correctly on Nushell 0.111+",
      "All consumer projects (vapora, typedialog, evol-rustelo) can run setup without errors",
      "Plain-string fix removes implicit fragility from zero-interpolation print statements",
    ],
    negative = [
      "The 0.111 regression was not caught by the version gate — the gate only guards >= 0.110.0 and does not test 0.111 compatibility proactively",
    ],
  },

  alternatives_considered = [
    {
      option       = "Raise minimum Nu version to 0.111 and document the breaking change",
      why_rejected = "Does not fix the broken syntax — just makes the breakage explicit. Consumer projects already on 0.111 would still fail until the print statements are fixed.",
    },
    {
      option       = "Use escape sequences or string concatenation to embed literal parens",
      why_rejected = "Nushell has no escape for parens in string interpolation. String concatenation (e.g. `'(kind: ' + $kind + ')'`) works but is significantly less readable than bare `kind: ($kind)`.",
    },
  ],

  constraints = [
    {
      id       = "no-label-value-parens-in-interpolation",
      claim    = "String interpolations in ontoref.nu must not use `(identifier: expr)` patterns — use bare `identifier: (expr)` instead",
      scope    = "ontoref (reflection/bin/ontoref.nu, all .nu files)",
      severity = 'Hard,
      check    = 'Grep {
        pattern      = "\\([a-z_]+: \\(",
        paths        = ["reflection/bin/ontoref.nu"],
        must_be_empty = true,
      },
      rationale = "Nushell 0.111 parses (identifier: expr) inside $\"...\" as a command call. The fix pattern (bare label + variable interpolation) is equivalent visually and immune to this parser behaviour.",
    },
    {
      id       = "plain-string-for-zero-interpolation",
      claim    = "Print statements with no variable interpolation must use plain strings, not `$\"...\"`",
      scope    = "ontoref (all .nu files)",
      severity = 'Soft,
      check    = 'Grep {
        pattern      = "\\$\"[^%(]*\"",
        paths        = ["reflection"],
        must_be_empty = true,
      },
      rationale = "Zero-interpolation `$\"...\"` strings are fragile against future parser changes and mislead readers into expecting variable substitution.",
    },
  ],

  related_adrs = [],

  ontology_check = {
    decision_string    = "Fix four Nu 0.111 string interpolation regressions in ontoref.nu; enforce no (label: expr) inside interpolations; use plain strings for zero-interpolation prints",
    invariants_at_risk = [],
    verdict            = 'Safe,
  },
}