@metaobjectsdev/cli 1.0.11 → 1.0.13

package/dist/src/lib/fmt-engine.js

@@ -0,0 +1,128 @@
+// server/typescript/packages/cli/src/lib/fmt-engine.ts
+//
+// `meta fmt` (#304) orchestration: resolve the project's own metadata files
+// (resolveCollection — never a hardcoded `metaobjects/`), format each one
+// standalone (@metaobjectsdev/metadata's formatMetadataFile — own-mode,
+// declared-here layer only), and gate every rewrite behind a whole-project
+// reload-and-compare safety check before it ever touches disk.
+//
+// The safety check (design rule 4): swap a candidate in via an in-memory
+// source carrying the SAME file id the real load would use, reload the WHOLE
+// project, and require both that it loads with no errors AND that its
+// canonical serialization is byte-identical to the untouched baseline. Only
+// then is the candidate written — so `--check` (which skips the write) and a
+// real run share one code path, and a bug in the formatter can only ever
+// leave a file unchanged plus an error, never a corrupted file.
+import { basename, extname, resolve as resolvePath } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { composeRegistry, MetaDataLoader, InMemoryStringSource, canonicalSerialize, formatMetadataFile, } from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolveCollection, defaultLoadMemoryProviders } from "@metaobjectsdev/sdk";
+import { loadMetaobjectsConfig, loadMemoryOptionsFrom } from "./load-metaobjects-config.js";
+async function projectProviders(collection) {
+    try {
+        const cfg = await loadMetaobjectsConfig(collection.configDir);
+        return loadMemoryOptionsFrom(cfg).providers ?? [];
+    }
+    catch {
+        // No metaobjects.config.ts (common for a non-TS-server project running
+        // `meta fmt` just for schema-neutral formatting) — format against the
+        // core vocabulary only, exactly like a project with no custom providers.
+        return [];
+    }
+}
+export async function runFmt(opts) {
+    let collection;
+    try {
+        collection = await resolveCollection(opts.projectRoot);
+    }
+    catch (err) {
+        return { files: [], fatal: err instanceof Error ? err.message : String(err) };
+    }
+    const providers = await projectProviders(collection);
+    const registry = composeRegistry([...defaultLoadMemoryProviders, ...providers]);
+    let targets;
+    if (opts.files !== undefined && opts.files.length > 0) {
+        const want = new Set(opts.files.map((f) => resolvePath(opts.projectRoot, f)));
+        const owned = new Set(collection.ownFiles);
+        const missing = [...want].filter((f) => !owned.has(f));
+        if (missing.length > 0) {
+            return {
+                files: [],
+                fatal: `not among this project's resolved metadata sources: ${missing.join(", ")}\n` +
+                    "meta fmt only formats files resolveCollection() already resolves — pass no " +
+                    "arguments to format every one of them.",
+            };
+        }
+        targets = collection.ownFiles.filter((f) => want.has(f));
+    }
+    else {
+        targets = collection.ownFiles;
+    }
+    const sourceId = (p) => collection.fileIds.get(p) ?? basename(p);
+    const libSources = collection.libraries.length > 0
+        ? (await import("@metaobjectsdev/metadata/library")).librarySources([...collection.libraries])
+        : [];
+    const buildSources = (overridePath, overrideText) => [
+        ...libSources,
+        ...collection.files.map((p) => {
+            const id = sourceId(p);
+            return overridePath !== undefined && p === overridePath
+                ? new InMemoryStringSource(overrideText ?? "", { id })
+                : new FileSource(p, { id });
+        }),
+    ];
+    const baseline = await new MetaDataLoader({ registry }).load(buildSources());
+    if (baseline.errors.length > 0) {
+        return {
+            files: [],
+            fatal: "this project's metadata does not currently load cleanly — fix the error(s) below, " +
+                "then re-run fmt:\n" +
+                baseline.errors.map((e) => `  ${e.message}`).join("\n"),
+        };
+    }
+    const baselineCanonical = canonicalSerialize(baseline.root);
+    const reports = [];
+    for (const path of targets) {
+        const ext = extname(path).toLowerCase();
+        if (ext === ".yaml" || ext === ".yml") {
+            reports.push({
+                path,
+                status: "skipped-yaml",
+                detail: "no canonical YAML emitter exists (ADR-0006: JSON is the canonical interchange form) — left untouched",
+            });
+            continue;
+        }
+        const content = await readFile(path, "utf8");
+        const formatted = formatMetadataFile(content, { registry, sourceId: sourceId(path) });
+        if (!formatted.ok) {
+            reports.push(formatted.overlay
+                ? { path, status: "skipped-overlay", detail: formatted.message }
+                : { path, status: "error", detail: formatted.message });
+            continue;
+        }
+        if (formatted.text === content) {
+            reports.push({ path, status: "unchanged" });
+            continue;
+        }
+        const testLoad = await new MetaDataLoader({ registry }).load(buildSources(path, formatted.text));
+        const safe = testLoad.errors.length === 0 && canonicalSerialize(testLoad.root) === baselineCanonical;
+        if (!safe) {
+            reports.push({
+                path,
+                status: "error",
+                detail: "formatting this file would change the loaded model's meaning — left unchanged",
+            });
+            continue;
+        }
+        if (opts.check) {
+            reports.push({ path, status: "would-format" });
+        }
+        else {
+            await writeFile(path, formatted.text, "utf8");
+            reports.push({ path, status: "formatted" });
+        }
+    }
+    return { files: reports };
+}
+//# sourceMappingURL=fmt-engine.js.map

package/dist/src/lib/fmt-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmt-engine.js","sourceRoot":"","sources":["../../../src/lib/fmt-engine.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -51,15 +51,15 @@
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "1.0.11",
-    "@metaobjectsdev/codegen-ts-react": "1.0.11",
-    "@metaobjectsdev/codegen-ts-tanstack": "1.0.11",
-    "@metaobjectsdev/docs-site": "1.0.11",
-    "@metaobjectsdev/metadata": "1.0.11",
-    "@metaobjectsdev/migrate-ts": "1.0.11",
-    "@metaobjectsdev/render": "1.0.11",
-    "@metaobjectsdev/runtime-ts": "1.0.11",
-    "@metaobjectsdev/sdk": "1.0.11",
+    "@metaobjectsdev/codegen-ts": "1.0.13",
+    "@metaobjectsdev/codegen-ts-react": "1.0.13",
+    "@metaobjectsdev/codegen-ts-tanstack": "1.0.13",
+    "@metaobjectsdev/docs-site": "1.0.13",
+    "@metaobjectsdev/metadata": "1.0.13",
+    "@metaobjectsdev/migrate-ts": "1.0.13",
+    "@metaobjectsdev/render": "1.0.13",
+    "@metaobjectsdev/runtime-ts": "1.0.13",
+    "@metaobjectsdev/sdk": "1.0.13",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/fmt.ts

@@ -0,0 +1,90 @@
+// `meta fmt` (#304) — rewrite metadata files into the canonical form the
+// cross-port canonical serializer already produces. `--check` lists the
+// files that are not canonical and exits non-zero without changing anything.
+//
+// All of the actual work — file resolution, standalone per-file formatting,
+// the YAML skip, and the whole-project reload-and-compare safety check — lives
+// in `../lib/fmt-engine.js`, kept framework-free so it is unit-testable without
+// spawning the CLI. This module is the thin text/exit-code front end.
+import { relative } from "node:path";
+import { parseFmtArgs } from "../lib/args.js";
+import { log } from "../lib/log.js";
+import { describeError } from "../lib/error-text.js";
+import { runFmt, type FmtFileReport } from "../lib/fmt-engine.js";
+
+function describe(report: FmtFileReport, cwd: string, check: boolean): string {
+  const rel = relative(cwd, report.path) || report.path;
+  switch (report.status) {
+    case "formatted":
+      return `  reformatted  ${rel}`;
+    case "would-format":
+      return `  not canonical  ${rel}`;
+    case "unchanged":
+      return `  ok           ${rel}`;
+    case "skipped-yaml":
+      return `  skipped (yaml)     ${rel} — ${report.detail}`;
+    case "skipped-overlay":
+      return `  skipped (overlay)  ${rel} — this file declares an overlay fmt cannot resolve standalone`;
+    case "error":
+      return `  error        ${rel} — ${report.detail}`;
+    default: {
+      const _exhaustive: never = report.status;
+      return _exhaustive;
+    }
+  }
+}
+
+export async function fmtCommand(args: string[], cwd: string): Promise<number> {
+  let flags;
+  try {
+    flags = parseFmtArgs(args);
+  } catch (err) {
+    log.error(describeError(err));
+    return 2;
+  }
+
+  const result = await runFmt({
+    projectRoot: cwd,
+    check: flags.check,
+    files: flags.files,
+  });
+
+  if (result.fatal !== undefined) {
+    log.error(result.fatal);
+    return 1;
+  }
+
+  if (result.files.length === 0) {
+    log.info("meta fmt — no metadata files to format.");
+    return 0;
+  }
+
+  for (const report of result.files) {
+    log.info(describe(report, cwd, flags.check));
+  }
+
+  const errored = result.files.filter((f) => f.status === "error");
+  const needsFormat = result.files.filter((f) => f.status === "would-format");
+  const reformatted = result.files.filter((f) => f.status === "formatted");
+
+  if (flags.check) {
+    if (needsFormat.length > 0 || errored.length > 0) {
+      log.error(
+        `meta fmt --check — ${needsFormat.length} file(s) not canonical` +
+          (errored.length > 0 ? `, ${errored.length} error(s)` : "") +
+          `. Run \`meta fmt\` to fix.`,
+      );
+      return 1;
+    }
+    log.info("meta fmt --check — every file is already canonical.");
+    return 0;
+  }
+
+  if (errored.length > 0) {
+    log.error(`meta fmt — ${errored.length} file(s) could not be formatted safely (left unchanged).`);
+    return 1;
+  }
+
+  log.info(`meta fmt — ${reformatted.length} file(s) reformatted.`);
+  return 0;
+}

package/src/commands/verify.ts

@@ -40,6 +40,7 @@ import {
 import { lintRequirements } from "../lib/requirement-lint.js";
 import { lintOverlays } from "../lib/overlay-lint.js";
 import { lintNodeNames } from "../lib/name-lint.js";
+import { lintDeprecatedReferences } from "../lib/deprecation-lint.js";
 import { FileSource } from "@metaobjectsdev/metadata/core";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import {
@@ -356,6 +357,9 @@ export async function verifyCommand(
   // off the end of a capped run.
   let nameSection: AdvisorySection<AdvisoryDiagnosticRow> =
     skippedSection("the name lint did not run");
+  // #305 — the deprecated-reference authoring lint. Its own section, same reason.
+  let deprecationSection: AdvisorySection<AdvisoryDiagnosticRow> =
+    skippedSection("the deprecated-reference lint did not run");
   // The ledger counts `meta verify` prints on every run. Undefined for a project
   // declaring no requirement.* node at all (opt-in by declaration) — the payload
   // then omits the block rather than reporting zeroes that would read as an empty
@@ -396,6 +400,11 @@ export async function verifyCommand(
   // Runs on every `meta verify`; warnings ONLY, never changes the exit code.
   runNameLintAdvisory();
 
+  // #305 — a node that depends (extends/@objectRef/@references/origin
+  // @from/@of/@via) on a `deprecated` node. Runs on every `meta verify`;
+  // warnings ONLY, never changes the exit code.
+  runDeprecationLintAdvisory();
+
   // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
   // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
   // Suppressed with --no-antipatterns or META_NO_ANTIPATTERNS=1 for the rare
@@ -445,6 +454,7 @@ export async function verifyCommand(
         antiPatterns: antiPatternSection,
         overlays: overlaySection,
         names: nameSection,
+        deprecations: deprecationSection,
       }),
       fmt,
     );
@@ -842,6 +852,29 @@ export async function verifyCommand(
     }
   }
 
+  // -- deprecated-reference authoring lint (advisory) -------------------------
+  // #305 — reads the LOADED model (see deprecation-lint.ts). Its own section,
+  // its own cap, and a skip that carries its reason rather than looking clean.
+  function runDeprecationLintAdvisory(): void {
+    if (flags.noDeprecationLint) {
+      deprecationSection = skippedSection("suppressed by --no-deprecation-lint");
+      return;
+    }
+    if (process.env.META_NO_DEPRECATION_LINT === "1") {
+      deprecationSection = skippedSection("suppressed by META_NO_DEPRECATION_LINT=1");
+      return;
+    }
+    const findings = lintDeprecatedReferences(root);
+    deprecationSection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — deprecations: ${findings.length} reference(s) to a deprecated node ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
+    }
+  }
+
   // -- verify-as-teacher (advisory) ------------------------------------------
   // Records its result EITHER WAY — a skip carries its reason rather than looking
   // like a clean scan. Warnings only; nothing here reaches the exit code (the
@@ -1856,6 +1889,7 @@ function buildVerifyPayload(input: {
   antiPatterns: AdvisorySection<AdvisoryFindingRow>;
   overlays: AdvisorySection<AdvisoryDiagnosticRow>;
   names: AdvisorySection<AdvisoryDiagnosticRow>;
+  deprecations: AdvisorySection<AdvisoryDiagnosticRow>;
 }): Record<string, unknown> {
   const ran = input.gates.filter((g) => g.ran);
   const failed = ran.filter((g) => !g.ok);
@@ -1878,6 +1912,9 @@ function buildVerifyPayload(input: {
   if (input.names.status === "ran" && input.names.total > 0) {
     parts.push(`${input.names.total} name authoring finding(s)`);
   }
+  if (input.deprecations.status === "ran" && input.deprecations.total > 0) {
+    parts.push(`${input.deprecations.total} deprecated-reference finding(s)`);
+  }
 
   const help: string[] = [];
   if (failed.length > 0) {
@@ -1898,12 +1935,18 @@ function buildVerifyPayload(input: {
       `${input.names.total} node name(s) containing whitespace — see names.rows[]; rename each node, and pin @column on a field whose physical column must keep its name`,
     );
   }
+  if (input.deprecations.total > 0) {
+    help.push(
+      `${input.deprecations.total} reference(s) to a deprecated node — see deprecations.rows[]; each names the deprecated target and, where declared, its replacement`,
+    );
+  }
   if (
     failed.length === 0 &&
     input.antiPatterns.total === 0 &&
     input.requirements.total === 0 &&
     input.overlays.total === 0 &&
-    input.names.total === 0
+    input.names.total === 0 &&
+    input.deprecations.total === 0
   ) {
     help.push("no drift and nothing advisory to answer — nothing to do");
   }
@@ -1917,6 +1960,7 @@ function buildVerifyPayload(input: {
     requirements: input.requirements,
     overlays: input.overlays,
     names: input.names,
+    deprecations: input.deprecations,
     ...(input.requirementCounts !== undefined ? { requirementCounts: input.requirementCounts } : {}),
     // The honest boundary. Everything named here is REACHABLE — it is printed as
     // text on stderr — but it is not in this document, and a reader must not have

package/src/index.ts

@@ -41,6 +41,7 @@ COMMANDS:
   deps list             One line per locked dependency: name, version, hash, node/package summary
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
+  fmt [<file>...]       Rewrite metadata files into canonical form; --check lists drift, exits non-zero
   docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen / --docs / --deps (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
@@ -86,6 +87,21 @@ GEN FLAGS:
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
+FMT FLAGS:
+  [<file>...]           Optional explicit file(s) to format — must be members of this
+                        project's resolved metadata sources (resolveCollection()); omit
+                        to format every one of them.
+  --check               List files that are not canonical and exit non-zero; changes nothing.
+                        A file whose formatting would change the LOADED MODEL's meaning
+                        is never rewritten — reported as an error instead (safety check).
+                        A YAML file is always reported as skipped: no canonical YAML
+                        emitter exists yet (ADR-0006 — JSON is the canonical interchange
+                        form). A file declaring 'overlay: true' anywhere — whether or not
+                        a same-file base exists to merge into — is skipped too: a
+                        formatter never changes structure, and buildTree's ordinary
+                        find-or-reuse behavior would otherwise silently fold a same-file
+                        base + overlay into one node, dropping the overlay marker.
+
 DOCS FLAGS:
   [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
                         your metadata, NOT the metadata directory. Passing it SCOPES the run
@@ -129,6 +145,8 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
                         (never a gate — this lint can't fail the build)
   --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace
                         in a name; never a gate — this lint can't fail the build)
+  --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint
+                        (never a gate — this lint can't fail the build)
   --limit <n|all>       How many advisory lines TEXT output prints per section before
                         it truncates (default 20). Never applies to --format
                         toon/json, which carry every finding and every diagnostic.
@@ -324,6 +342,8 @@ FLAGS:
                         never a gate; this lint can't fail the build
   --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace in
                         a name) — never a gate; this lint can't fail the build
+  --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint —
+                        never a gate; this lint can't fail the build
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
                         (default 20; per-section so the authoring lint can never push
                         the gate's own warnings off the end)
@@ -361,6 +381,14 @@ Leading or trailing whitespace is almost certainly a copy-paste accident — ren
 the node, and pin @column on a field whose physical column must keep its name.
 Requirement names are left to the requirement lint above. Warnings only — it can
 never fail the build. Opt out with --no-name-lint or META_NO_NAME_LINT=1.
+
+verify also prints an ADVISORY deprecated-reference authoring lint, in its own
+section: any node that depends on a node carrying the documentation @deprecated
+attr, via extends, @objectRef, @references, or an origin's @from/@of/@via. Where
+the deprecated node also carries @replacedBy, the finding names the replacement.
+A node referencing itself (a recursive FK, a same-entity passthrough) is not a
+finding. Warnings only — it can never fail the build. Opt out with
+--no-deprecation-lint or META_NO_DEPRECATION_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -370,6 +398,39 @@ USAGE:
 FLAGS:
   --out <file>          Write output to a file (default: stdout)
   --help, -h            Print this help
+`,
+  fmt: `meta fmt — rewrite metadata files into canonical form
+
+USAGE:
+  meta fmt [<file>...] [flags]
+
+Formats every JSON metadata file this project's resolved sources contain
+(resolveCollection() — never a hardcoded default directory), or just the
+files named. Each file is formatted as its OWN content (own-mode,
+declared-here layer only) — never inlining an inherited member or another
+file's overlay.
+
+FLAGS:
+  [<file>...]           Optional explicit file(s) — must be members of this project's
+                        resolved metadata sources; omit to format every one of them.
+  --check               List files that are not canonical and exit non-zero; changes
+                        nothing on disk.
+  --help, -h            Print this help
+
+SAFETY: before writing any file, fmt reloads the whole project with that file's
+candidate content swapped in and requires the loaded model's canonical form to
+be byte-identical to the untouched baseline. A file that fails this check is
+left exactly as it was and reported as an error — fmt never changes meaning.
+
+YAML: left untouched and reported as skipped — no canonical YAML emitter
+exists yet (ADR-0006: JSON is the canonical interchange form; YAML is an
+authoring format).
+
+OVERLAY: a file declaring 'overlay: true' ANYWHERE in its tree is reported as
+skipped — not only when no base exists in the same file. A formatter never
+changes structure: even when a same-file base IS present, merging it with
+the overlay (what the ordinary loader would do) would drop the overlay
+marker from the output, so fmt refuses that too and leaves the file as-is.
 `,
   docs: `meta docs — generate neutral metadata documentation (entity + template pages)
 
@@ -645,6 +706,10 @@ export async function run(argv: string[]): Promise<number> {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);
     }
+    case "fmt": {
+      const { fmtCommand } = await import("./commands/fmt.js");
+      return fmtCommand(rest, cwd);
+    }
     case "types": {
       const { typesCommand } = await import("./commands/types.js");
       return typesCommand(rest, explicitFormat);

package/src/lib/args.ts

@@ -190,6 +190,35 @@ export function parseExportArgs(argv: string[]): ExportFlags {
   };
 }
 
+// ---------------------------------------------------------------------------
+// fmt flags (#304)
+// ---------------------------------------------------------------------------
+
+export interface FmtFlags {
+  check: boolean;
+  /** Optional explicit file list — narrows the run to these files (must be
+   *  members of the project's resolved metadata sources). Empty = every file. */
+  files: string[];
+}
+
+/** The flag table `parseFmtArgs` parses. Exported so the help text can be gated against it. */
+export const FMT_OPTIONS = {
+  check: { type: "boolean", default: false },
+} as const;
+
+export function parseFmtArgs(argv: string[]): FmtFlags {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: FMT_OPTIONS,
+    strict: true,
+    allowPositionals: true,
+  });
+  return {
+    check: !!values.check,
+    files: positionals,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // shared DB-connection vocab (used by both verify --db and migrate)
 // ---------------------------------------------------------------------------
@@ -369,6 +398,13 @@ export interface VerifyFlags {
    * the build.
    */
   noNameLint: boolean;
+  /**
+   * Suppress the advisory deprecated-REFERENCE authoring lint (#305) — a node
+   * depending (extends/@objectRef/@references/origin @from/@of/@via) on a
+   * `deprecated` node. Advisory only, like its siblings: it has no gate half
+   * and can never fail the build.
+   */
+  noDeprecationLint: boolean;
   /**
    * ADR-0023 strict-attr load opt-OUT (#96). `verify` is strict-by-default — an
    * undeclared/typo'd own `@attr` fails verify (ERR_UNKNOWN_ATTR). `--lax`
@@ -411,6 +447,7 @@ export const VERIFY_OPTIONS = {
   "no-requirement-lint": { type: "boolean", default: false },
   "no-overlay-lint": { type: "boolean", default: false },
   "no-name-lint": { type: "boolean", default: false },
+  "no-deprecation-lint": { type: "boolean", default: false },
   lax: { type: "boolean", default: false },
   "d1": { type: "string" },
   "remote": { type: "boolean", default: false },
@@ -496,6 +533,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     noRequirementLint: !!values["no-requirement-lint"],
     noOverlayLint: !!values["no-overlay-lint"],
     noNameLint: !!values["no-name-lint"],
+    noDeprecationLint: !!values["no-deprecation-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,