fix(cli): os lint surfaces ADR-0087 conversion notices — console notice + a conversions key in --json

.changeset/cli-lint-conversion-notices.md

@@ -0,0 +1,86 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `os lint` surfaces ADR-0087 conversion notices — a `conversions` key in `--json` and a printed notice for a human (#12297)
+
+**Machine-contract widening on the `os lint --json` payload.** A consumer that
+reads an exact key set from `os lint --json` sees one new key after this change.
+
+## Proposed grade, and why
+
+`minor`, matching the two nearest precedents on this lane rather than the
+bug/feature framing: #13347 (adding `code`/`httpStatus` to the CLI's
+`--format json` envelope) and the sibling `conversions` change on
+`os validate` / `os build` (#12125) were both graded `minor` as additive
+members on a published machine-readable surface. Triage graded this card a
+`Bug` on declared-not-enforced grounds, and that reading is not in conflict:
+restoring a parity contract can still widen a wire surface, and the grade
+follows the surface. Nothing here is breaking — no existing key changes
+meaning, none is removed, and the `total` / `errors` / `warnings` /
+`suggestions` counts are byte-for-byte what they were.
+
+## What was wrong
+
+`os lint` called `normalizeStackInput(config)` with **no options object**, so no
+`onConversionNotice` sink existed. The ADR-0087 D2 conversion layer runs inside
+that call and always did — `os lint` converted the author's metadata on every
+run — but with no sink the notices were never **produced**, in either face. An
+anchored count over the whole file said so in one number:
+
+```
+grep -cE 'onConversionNotice|conversions' packages/cli/src/commands/lint.ts
+0
+```
+
+This is the #3782 **parity** class, not the "computed, then dropped" family
+(#11643 / #11391 / #11772 / #12047 / #12125): nothing was computed and
+discarded, the producer was never wired. It is the exact gap `os build` was in
+before #11772 / PR #12079.
+
+`os lint` is one of the three authoring commands the #4409 registry holds to a
+single bar, and it was the only one telling an author nothing about a
+conversion its own load path had just applied. A conversion notice is the one
+advisory class carrying an **expiry** — `retiresIn` names the protocol major
+where the old shape stops loading, and five conversions are live today
+(protocol 11 and 15). An author or CI job whose only authoring gate is
+`os lint` got no signal at all, in either face, until the conversion retired
+and their metadata stopped loading.
+
+## What changed
+
+| face | before | after |
+| --- | --- | --- |
+| console (`os lint`) | nothing | one `⚠` line per notice: the path, `'from'` → `'to'`, the conversion id, and the protocol major it retires in |
+| `os lint --json` | no such key | `conversions`: the same structured notices, unconditionally present |
+| `os lint --json`, thrown / caught | no such key | what the run had computed — `[]` for a throw at load |
+
+The console wording is `compile.ts`'s, verbatim, so an author who runs two of
+the three commands over one tree is told the same thing in the same words. The
+`--json` key is the same `conversions` key `os validate --json` and
+`os build --json` publish, carrying the same structured entries, so one
+consumer reads all three authoring commands the same way.
+
+## What a consumer should know
+
+✅ `conversions` is **always an array** on `os lint --json`, success or
+failure, so it can be read unconditionally. Each entry keeps its structured
+`conversionId`, `surface`, `from`, `to`, `path`, `toMajor` and `retiresIn`
+fields, so a CI job can gate on `retiresIn` without a second run.
+
+⛔ `conversions: []` does **not** mean "this tree converts nothing" on the
+caught-error payload — it means the run stopped before the conversion layer
+ran. A config that fails to load reports `[]` by construction. Read the
+`error` key to tell the two apart.
+
+⛔ A consumer asserting an exact key set on `os lint --json` must add
+`conversions` to it. No existing key changed: `total`, `errors`, `warnings`
+and `suggestions` count exactly what they counted before, and exit codes are
+untouched (errors still exit 1).
+
+Conversion notices are **not** folded into `issues`. `issues` keeps meaning
+"something to fix"; an auto-converted key needs no action to keep loading. The
+related question raised on #12125 — whether `warnings` and `conversions` should
+become one field on the sibling commands — is open and was not settled by the
+2026-08-25 ruling, so this change mirrors the shipped sibling shape rather than
+merging anything.

packages/cli/src/commands/lint.ts

@@ -3,7 +3,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { bundleRequire } from 'bundle-require';
-import { normalizeStackInput } from '@objectstack/spec';
+import { normalizeStackInput, type ConversionNotice } from '@objectstack/spec';
 import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
 import { loadConfig, BUNDLE_REQUIRE_EXTERNALS } from '../utils/config.js';
 import { computeI18nCoverage, type CoverageIssue } from '../utils/i18n-coverage.js';
@@ -496,14 +496,65 @@ export default class Lint extends Command {
       printStep('Loading configuration...');
     }
 
+    // [#12297] The ADR-0087 D2 conversion notices this command raises.
+    //
+    // ⛔ This is the #3782 PARITY class, NOT the "computed, then dropped"
+    // family (#11643 / #11391 / #11772 / #12047 / #12125). Nothing was computed
+    // and discarded here: `normalizeStackInput` was called with no options
+    // object at all, so no sink existed and the notices were never PRODUCED —
+    // in either face. `os lint` is the third of the three authoring commands
+    // the #4409 registry holds to one bar, and it was the only one telling an
+    // author nothing about a conversion its own load path had just applied.
+    // That is the exact gap `os build` was in before #11772 / PR #12079.
+    //
+    // It bites harder than it reads: a conversion notice is the one advisory
+    // class carrying an EXPIRY — `retiresIn` names the protocol major where the
+    // old shape stops loading — and an author whose only authoring gate is
+    // `os lint` got no signal at all until the conversion retired and their
+    // metadata stopped loading.
+    //
+    // Declared above the `try` so the catch-all exit can read it, under the
+    // maintainer's 2026-08-25 ruling (#11772/#12047, applied to this field by
+    // #12125): every failure exit carries the lists the run has ALREADY
+    // COMPUTED, so the field means the same thing on every exit. The CALL that
+    // fills it stays below, at the step that owns it — a throw in `loadConfig`,
+    // above it, reports `[]` honestly.
+    //
+    // ⛔ NOT FOLDED INTO `issues`. Whether an auto-converted key should become
+    // a `LintIssue` — or, on the sibling commands, whether `warnings` and
+    // `conversions` should become one field — is an open question raised on
+    // #12125, left unsettled by the ruling there and explicitly withheld by
+    // that card's implementer. This change had no authority to settle it, so it
+    // mirrors the shipped sibling shape rather than merging: `issues` keeps
+    // meaning "something to fix", the notice keeps its structured
+    // `conversionId`/`surface`/`from`/`to`/`retiresIn` fields, and the
+    // `total`/`errors`/`warnings` counts keep counting exactly what they
+    // counted before.
+    const conversionNotices: ConversionNotice[] = [];
+
     try {
       const { config, absolutePath } = await loadConfig(configPath);
 
       if (!flags.json) {
         printInfo(`Config: ${chalk.white(absolutePath)}`);
       }
 
-      const normalized = normalizeStackInput(config as Record<string, unknown>);
+      // The ADR-0087 D2 conversion layer runs here, inside `normalizeStackInput`
+      // — it always did. Passing the sink is what makes the rewrites SAYABLE.
+      const normalized = normalizeStackInput(config as Record<string, unknown>, {
+        onConversionNotice: (n) => conversionNotices.push(n),
+      });
+      // The human face, mirroring the #11772 repair in `compile.ts` verbatim —
+      // same wording, so an author who runs two of the three commands over one
+      // tree is told the same thing in the same words.
+      if (conversionNotices.length > 0 && !flags.json) {
+        console.log('');
+        for (const n of conversionNotices) {
+          printWarning(
+            `${n.path}: '${n.from}' → '${n.to}' (converted at load; conversion '${n.conversionId}', retires in protocol ${n.retiresIn})`,
+          );
+        }
+      }
       const issues = lintConfig(normalized, { sduiManifest: resolveSduiManifest() });
 
       // ── Package docs (ADR-0046) ── collected src/docs/*.md + inline docs:
@@ -550,6 +601,14 @@ export default class Lint extends Command {
           ...(hiddenPlatform > 0 ? { hiddenPlatform } : {}),
           ...(score ? { score: score.score, grade: score.grade } : {}),
           issues,
+          // [#12297] The notices computed at `normalizeStackInput` above. Its
+          // own key, unconditionally present — the same `conversions` key
+          // `os validate --json` and `os build --json` publish, carrying the
+          // same structured notice objects, so one consumer reads all three
+          // authoring commands the same way. `[]` when nothing converted, never
+          // absent: a machine consumer keying off presence must not have to
+          // distinguish "did not convert" from "this command does not tell me".
+          conversions: conversionNotices,
           duration: timer.elapsed(),
         }, errors.length > 0 ? 1 : 0);
         return;
@@ -637,7 +696,16 @@ export default class Lint extends Command {
     } catch (error: any) {
       if (isExitSignal(error)) throw error;
       if (flags.json) {
-        await emitJson({ error: error.message, ...errorCodeFields(error) }, 0, { compact: true });
+        // [#12297] Whatever the run had reached before the throw, under the
+        // same 2026-08-25 ruling: `[]` for a throw in `loadConfig` — the
+        // normalize step never ran — and the notices in hand for any later one.
+        // Wiring the producer without this exit would ship a fresh instance of
+        // the #12125 defect one command over, on the day it was closed.
+        await emitJson(
+          { error: error.message, ...errorCodeFields(error), conversions: conversionNotices },
+          0,
+          { compact: true },
+        );
         process.exit(1);
       }
       console.log('');