@vadimcomanescu/nadicode-design-system 2.0.0

package/scripts/ds-check.mjs

@@ -0,0 +1,969 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+const root = process.cwd();
+const issues = [];
+const CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE = "2.0.0";
+const CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE = "file:.nadicode/packages/vadimcomanescu-nadicode-design-system-2.0.0.tgz";
+
+function normalizePath(filePath) {
+  return filePath.replaceAll("\\", "/");
+}
+
+function relativePath(filePath) {
+  const rel = relative(root, filePath);
+  return rel ? normalizePath(rel) : ".";
+}
+
+function addIssue(file, rule, detail) {
+  issues.push({ file, rule, detail });
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function maskNonCode(content, { preserveStrings = false } = {}) {
+  let result = "";
+  let state = "code";
+
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (state === "code") {
+      if (char === "/" && next === "/") {
+        result += "  ";
+        i += 1;
+        state = "line-comment";
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        result += "  ";
+        i += 1;
+        state = "block-comment";
+        continue;
+      }
+      if (char === "'") {
+        result += char;
+        state = "single-quote";
+        continue;
+      }
+      if (char === '"') {
+        result += char;
+        state = "double-quote";
+        continue;
+      }
+      if (char === "`") {
+        result += char;
+        state = "template";
+        continue;
+      }
+
+      result += char;
+      continue;
+    }
+
+    if (state === "line-comment") {
+      if (char === "\n") {
+        result += "\n";
+        state = "code";
+      } else {
+        result += " ";
+      }
+      continue;
+    }
+
+    if (state === "block-comment") {
+      if (char === "*" && next === "/") {
+        result += "  ";
+        i += 1;
+        state = "code";
+      } else {
+        result += char === "\n" ? "\n" : " ";
+      }
+      continue;
+    }
+
+    if (state === "single-quote") {
+      if (char === "\\") {
+        result += "\\";
+        if (next) {
+          result += preserveStrings ? next : " ";
+          i += 1;
+        }
+        continue;
+      }
+      if (char === "'") {
+        result += "'";
+        state = "code";
+      } else {
+        result += preserveStrings ? char : (char === "\n" ? "\n" : " ");
+      }
+      continue;
+    }
+
+    if (state === "double-quote") {
+      if (char === "\\") {
+        result += "\\";
+        if (next) {
+          result += preserveStrings ? next : " ";
+          i += 1;
+        }
+        continue;
+      }
+      if (char === '"') {
+        result += '"';
+        state = "code";
+      } else {
+        result += preserveStrings ? char : (char === "\n" ? "\n" : " ");
+      }
+      continue;
+    }
+
+    if (state === "template") {
+      if (char === "\\") {
+        result += "\\";
+        if (next) {
+          result += preserveStrings ? next : " ";
+          i += 1;
+        }
+        continue;
+      }
+      if (char === "`") {
+        result += "`";
+        state = "code";
+      } else {
+        result += preserveStrings ? char : (char === "\n" ? "\n" : " ");
+      }
+    }
+  }
+
+  return result;
+}
+
+function hasGetRequestConfigExport(content) {
+  const code = maskNonCode(content);
+  const codeWithoutComments = maskNonCode(content, { preserveStrings: true });
+  const importsGetRequestConfig = /^\s*import\s*{\s*getRequestConfig\s*}\s*from\s*["']next-intl\/server["']/m.test(codeWithoutComments);
+  if (!importsGetRequestConfig) {
+    return false;
+  }
+
+  if (/\bexport\s+default\s+getRequestConfig\s*\(/.test(code)) {
+    return true;
+  }
+
+  const assigned = code.match(
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*getRequestConfig\s*\(/,
+  );
+  if (!assigned) {
+    return false;
+  }
+
+  return new RegExp(`\\bexport\\s+default\\s+${escapeRegExp(assigned[1])}\\b`).test(code);
+}
+
+function getDefaultImportBinding(content, moduleSpecifier) {
+  const code = maskNonCode(content, { preserveStrings: true });
+  const match = code.match(
+    new RegExp(
+      String.raw`^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']${escapeRegExp(moduleSpecifier)}["']`,
+      "m",
+    ),
+  );
+  return match?.[1] ?? null;
+}
+
+function getNamedImportBinding(content, moduleSpecifier, importedName) {
+  const code = maskNonCode(content, { preserveStrings: true });
+  const importMatch = code.match(
+    new RegExp(
+      String.raw`^\s*import\s*{\s*([^}]+)\s*}\s*from\s*["']${escapeRegExp(moduleSpecifier)}["']`,
+      "m",
+    ),
+  );
+  if (!importMatch) {
+    return null;
+  }
+
+  for (const rawSpecifier of importMatch[1].split(",")) {
+    const specifier = rawSpecifier.trim();
+    if (!specifier) {
+      continue;
+    }
+
+    const [imported, local = imported] = specifier.split(/\s+as\s+/).map((part) => part.trim());
+    if (imported === importedName) {
+      return local;
+    }
+  }
+
+  return null;
+}
+
+function getCodeWithoutImports(content) {
+  return maskNonCode(content).replace(/^\s*import\s.+$/gm, "");
+}
+
+function bindingIsReferencedInDefaultExport(content, binding) {
+  if (!binding) {
+    return false;
+  }
+
+  const codeWithoutImports = getCodeWithoutImports(content);
+  const exportDefaultIndex = codeWithoutImports.indexOf("export default");
+  if (exportDefaultIndex < 0) {
+    return false;
+  }
+
+  return new RegExp(`\\b${escapeRegExp(binding)}\\b`).test(codeWithoutImports.slice(exportDefaultIndex));
+}
+
+function isSupportedRegistrySpec(spec) {
+  return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(spec);
+}
+
+function hasCalledBindingDefaultExport(content, binding) {
+  if (!binding) {
+    return false;
+  }
+
+  const code = maskNonCode(content);
+  if (new RegExp(`\\bexport\\s+default\\s+${escapeRegExp(binding)}\\s*\\(`).test(code)) {
+    return true;
+  }
+
+  const assigned = code.match(
+    new RegExp(
+      String.raw`\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*${escapeRegExp(binding)}\s*\(`,
+    ),
+  );
+  if (!assigned) {
+    return false;
+  }
+
+  return new RegExp(`\\bexport\\s+default\\s+${escapeRegExp(assigned[1])}\\b`).test(code);
+}
+
+function findExistingPath(candidates) {
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+
+function expectFile(candidates, rule, detail) {
+  const path = findExistingPath(candidates);
+  if (!path) {
+    addIssue(relativePath(candidates[0]), rule, detail);
+    return null;
+  }
+  return path;
+}
+
+function ensureFileContains(path, snippet, rule, detail) {
+  if (!path) {
+    return;
+  }
+
+  const content = readFileSync(path, "utf8");
+  if (!content.includes(snippet)) {
+    addIssue(relativePath(path), rule, detail);
+  }
+}
+
+function stripJsonComments(text) {
+  let result = "";
+  let inString = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    const next = text[i + 1];
+    const previous = text[i - 1];
+
+    if (inLineComment) {
+      if (char === "\n") {
+        inLineComment = false;
+        result += char;
+      }
+      continue;
+    }
+
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        inBlockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+
+    if (char === "\"" && previous !== "\\") {
+      inString = !inString;
+      result += char;
+      continue;
+    }
+
+    if (inString) {
+      result += char;
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      inLineComment = true;
+      i += 1;
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      inBlockComment = true;
+      i += 1;
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+function parseJsonc(text) {
+  const withoutComments = stripJsonComments(text);
+  const withoutTrailingCommas = withoutComments.replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(withoutTrailingCommas);
+}
+
+function isSourceRepo(packageJson) {
+  return packageJson?.name === "@vadimcomanescu/nadicode-design-system"
+    && existsSync(join(root, "src"))
+    && existsSync(join(root, "scripts", "ds-check.mjs"));
+}
+
+function checkSourceRepo(packageJson) {
+  if (!packageJson) {
+    addIssue("package.json", "seed-package-json-missing", "package.json must exist.");
+    return;
+  }
+
+  const packageFiles = new Set(packageJson.files ?? []);
+  for (const requiredFile of [
+    "dist",
+    "src/lib/tokens.config.js",
+    "eslint-rules/nadicode",
+    ".agents/skills/seed",
+    "scripts/ds-check.mjs",
+    "scripts/ds-update.mjs",
+    "scripts/sync-seed-skill.mjs",
+  ]) {
+    if (!packageFiles.has(requiredFile)) {
+      addIssue(
+        "package.json",
+        "seed-package-files-contract",
+        `package.json files must include ${requiredFile}.`,
+      );
+    }
+  }
+
+  if (packageFiles.has("src")) {
+    addIssue(
+      "package.json",
+      "seed-package-files-contract",
+      "package.json files must not publish the repo src/ tree. Ship built artifacts and explicit package assets only.",
+    );
+  }
+
+  const exportsMap = packageJson.exports ?? {};
+  for (const requiredExport of [
+    "./tokens.css",
+    "./tailwind",
+    "./eslint-config",
+    "./eslint-plugin",
+    "./ds-check",
+    "./ds-update",
+    "./test",
+    "./messages/en",
+    "./messages/it",
+  ]) {
+    if (!(requiredExport in exportsMap)) {
+      addIssue(
+        "package.json",
+        "seed-package-exports-contract",
+        `package.json exports must include ${requiredExport}.`,
+      );
+    }
+  }
+
+  if ("./tokens-config" in exportsMap) {
+    addIssue(
+      "package.json",
+      "seed-package-exports-contract",
+      "package.json exports must not expose ./tokens-config from raw source. Ship only the public package surface.",
+    );
+  }
+
+  if (!packageJson.peerDependencies?.tailwindcss) {
+    addIssue(
+      "package.json",
+      "seed-package-peer-contract",
+      "package.json peerDependencies must declare tailwindcss because the shipped Tailwind preset depends on the consumer's Tailwind runtime.",
+    );
+  }
+
+  if (packageJson.scripts?.prepack !== "npm run build:lib") {
+    addIssue(
+      "package.json",
+      "seed-package-pack-contract",
+      "package.json must define prepack as `npm run build:lib` so npm pack always ships a fresh package artifact.",
+    );
+  }
+
+  if (packageJson.scripts?.prepublishOnly !== "npm run release:check") {
+    addIssue(
+      "package.json",
+      "seed-package-pack-contract",
+      "package.json must define prepublishOnly as `npm run release:check` so npm publish runs the full local release gate before publishing.",
+    );
+  }
+
+  if (packageJson.scripts?.postpublish !== "npm run release:verify") {
+    addIssue(
+      "package.json",
+      "seed-package-pack-contract",
+      "package.json must define postpublish as `npm run release:verify` so npm publish always verifies the published package from a clean install.",
+    );
+  }
+
+  const lintShipped = packageJson.scripts?.["ds:lint-shipped"] ?? "";
+  if (!lintShipped.includes("src/messages")) {
+    addIssue(
+      "package.json",
+      "seed-source-i18n-contract",
+      'package.json must include src/messages in the ds:lint-shipped command.',
+    );
+  }
+}
+
+function checkSourceI18nContract() {
+  const typesConfigPath = expectFile(
+    [join(root, "tsconfig.types.json")],
+    "seed-types-config-missing",
+    "tsconfig.types.json must exist.",
+  );
+  if (!typesConfigPath) {
+    return;
+  }
+
+  try {
+    const typesConfig = parseJsonc(readFileSync(typesConfigPath, "utf8"));
+    const include = typesConfig.include ?? [];
+    if (!include.includes("src/messages/**/*")) {
+      addIssue(
+        relativePath(typesConfigPath),
+        "seed-source-i18n-contract",
+        'tsconfig.types.json must include "src/messages/**/*" so dist/messages/*.d.ts are emitted explicitly.',
+      );
+    }
+  } catch {
+    addIssue(
+      relativePath(typesConfigPath),
+      "seed-types-config-invalid",
+      "tsconfig.types.json must be valid JSON or JSONC.",
+    );
+  }
+}
+
+function checkRequiredScripts(packageJsonPath, packageJson) {
+  if (!packageJsonPath || !packageJson) {
+    addIssue("package.json", "seed-package-json-missing", "package.json must exist in the consumer root.");
+    return;
+  }
+
+  const scripts = packageJson.scripts ?? {};
+  const requiredScripts = {
+    "ds:check": "node scripts/ds-check.mjs",
+    "ds:update": "node scripts/ds-update.mjs",
+    "ds:validate": "npm run ds:check && npm run lint && tsc --noEmit && npm run build",
+  };
+
+  for (const [name, value] of Object.entries(requiredScripts)) {
+    if (scripts[name] !== value) {
+      addIssue(
+        relativePath(packageJsonPath),
+        "seed-script-contract",
+        `package.json must define ${name} as \`${value}\`.`,
+      );
+    }
+  }
+}
+
+function checkDependency(packageJsonPath, packageJson) {
+  const dependency = packageJson?.dependencies?.["@vadimcomanescu/nadicode-design-system"]
+    ?? packageJson?.devDependencies?.["@vadimcomanescu/nadicode-design-system"];
+
+  if (!dependency) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-missing",
+      `package.json must declare @vadimcomanescu/nadicode-design-system as a released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  const normalizedDependency = String(dependency).trim();
+  if (!normalizedDependency) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must declare @vadimcomanescu/nadicode-design-system as a non-empty released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  if (isSupportedRegistrySpec(normalizedDependency)) {
+    return;
+  }
+
+  const isLiveDirectorySource = (
+    normalizedDependency.startsWith("file:")
+    && !normalizedDependency.endsWith(".tgz")
+  )
+    || normalizedDependency.startsWith("link:")
+    || normalizedDependency.startsWith("workspace:")
+    || normalizedDependency.startsWith("portal:");
+
+  if (isLiveDirectorySource) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must not install @vadimcomanescu/nadicode-design-system from a live directory source. Use a released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  const isTarballSpec = normalizedDependency.startsWith("file:") && normalizedDependency.endsWith(".tgz");
+  if (!isTarballSpec) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must install @vadimcomanescu/nadicode-design-system from a released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  const tarballPath = normalizedDependency.slice("file:".length);
+  if (!tarballPath) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must install @vadimcomanescu/nadicode-design-system from a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  if (isAbsolute(tarballPath)) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must not point @vadimcomanescu/nadicode-design-system at an absolute tarball path. Use a released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  const resolvedTarballPath = resolve(root, tarballPath);
+  if (!resolvedTarballPath.startsWith(`${root}/`) && resolvedTarballPath !== root) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-source",
+      `package.json must not point @vadimcomanescu/nadicode-design-system at a tarball outside the app root. Use a released package version such as ${CANONICAL_SEED_REGISTRY_SPEC_EXAMPLE} or a relative tarball fallback such as ${CANONICAL_NADICODE_TARBALL_SPEC_EXAMPLE}.`,
+    );
+    return;
+  }
+
+  if (!existsSync(resolvedTarballPath)) {
+    addIssue(
+      relativePath(packageJsonPath),
+      "seed-package-dependency-missing-target",
+      `package.json points @vadimcomanescu/nadicode-design-system at a missing tarball: ${normalizePath(tarballPath)}.`,
+    );
+  }
+}
+
+function checkPaletteContract() {
+  const palettePath = expectFile(
+    [join(root, "src", "seed-palette.css"), join(root, "seed-palette.css")],
+    "seed-palette-missing",
+    "seed-palette.css must exist for consumer-owned branding overrides.",
+  );
+
+  if (!palettePath) {
+    return null;
+  }
+
+  const paletteContent = readFileSync(palettePath, "utf8");
+  if (/\[\s*data-theme\s*=/.test(paletteContent)) {
+    addIssue(
+      relativePath(palettePath),
+      "seed-palette-selector-contract",
+      "seed-palette.css must use class-based selectors (:root, :root.dark, :root.bloom), not [data-theme=...].",
+    );
+  }
+
+  return palettePath;
+}
+
+function checkSeedSkillContract() {
+  expectFile(
+    [join(root, ".agents", "skills", "seed", "SKILL.md")],
+    "seed-skill-missing",
+    ".agents/skills/seed/SKILL.md must exist so agents know how to use the design system.",
+  );
+  expectFile(
+    [join(root, ".agents", "skills", "seed", "contract.md")],
+    "seed-skill-contract-missing",
+    ".agents/skills/seed/contract.md must exist so agents know the DS rules.",
+  );
+  expectFile(
+    [join(root, ".agents", "skills", "seed", "intent-map.md")],
+    "seed-skill-intent-map-missing",
+    ".agents/skills/seed/intent-map.md must exist so agents can map intents to recipes.",
+  );
+}
+
+function checkForbiddenDuplicatedDocs() {
+  const forbiddenDocs = [
+    join(root, "docs", "nadicode", "README.md"),
+    join(root, "docs", "nadicode", "ADOPTION_PLAYBOOK.md"),
+    join(root, "docs", "nadicode", "SCAFFOLDING_PROCESS.md"),
+  ];
+
+  for (const filePath of forbiddenDocs) {
+    if (existsSync(filePath)) {
+      addIssue(
+        relativePath(filePath),
+        "seed-duplicated-ds-doc",
+        "DS-specific scaffolding and distribution docs must not be copied into consumer apps. Keep only the Seed usage skill locally.",
+      );
+    }
+  }
+}
+
+function checkGlobalsContract() {
+  const globalsPath = expectFile(
+    [join(root, "src", "app", "globals.css"), join(root, "app", "globals.css")],
+    "seed-globals-missing",
+    "App Router globals.css must exist.",
+  );
+
+  if (!globalsPath) {
+    return;
+  }
+
+  const globalsContent = readFileSync(globalsPath, "utf8");
+  const packageTokensImport = '@import "@vadimcomanescu/nadicode-design-system/tokens.css";';
+  const paletteMarkers = ["seed-palette.css"];
+
+  if (!globalsContent.includes(packageTokensImport)) {
+    addIssue(
+      relativePath(globalsPath),
+      "seed-globals-import-contract",
+      `globals.css must import ${packageTokensImport}.`,
+    );
+  }
+
+  if (!paletteMarkers.some((marker) => globalsContent.includes(marker))) {
+    addIssue(
+      relativePath(globalsPath),
+      "seed-globals-import-contract",
+      "globals.css must import seed-palette.css after the package tokens stylesheet.",
+    );
+  }
+
+  const paletteIndex = Math.max(...paletteMarkers.map((marker) => globalsContent.indexOf(marker)));
+  const packageTokensIndex = globalsContent.indexOf(packageTokensImport);
+  if (packageTokensIndex >= 0 && paletteIndex >= 0 && packageTokensIndex > paletteIndex) {
+    addIssue(
+      relativePath(globalsPath),
+      "seed-globals-import-order",
+      "globals.css must import @vadimcomanescu/nadicode-design-system/tokens.css before seed-palette.css.",
+    );
+  }
+}
+
+function checkTailwindContract() {
+  const tailwindPath = expectFile(
+    [
+      join(root, "tailwind.config.js"),
+      join(root, "tailwind.config.mjs"),
+      join(root, "tailwind.config.ts"),
+    ],
+    "seed-tailwind-config-missing",
+    "tailwind.config.* must exist.",
+  );
+
+  if (!tailwindPath) {
+    return;
+  }
+
+  const tailwindContent = readFileSync(tailwindPath, "utf8");
+  const tailwindBinding = getDefaultImportBinding(tailwindContent, "@vadimcomanescu/nadicode-design-system/tailwind");
+
+  if (!tailwindBinding) {
+    addIssue(
+      relativePath(tailwindPath),
+      "seed-tailwind-config-contract",
+      "tailwind.config.* must import the @vadimcomanescu/nadicode-design-system Tailwind preset.",
+    );
+    return;
+  }
+
+  if (!hasCalledBindingDefaultExport(tailwindContent, tailwindBinding)) {
+    addIssue(
+      relativePath(tailwindPath),
+      "seed-tailwind-config-contract",
+      "tailwind.config.* must export a config produced by the imported @vadimcomanescu/nadicode-design-system Tailwind preset.",
+    );
+  }
+}
+
+function checkEslintContract() {
+  const eslintPath = expectFile(
+    [join(root, "eslint.config.mjs"), join(root, "eslint.config.js")],
+    "seed-eslint-config-missing",
+    "eslint.config.* must exist.",
+  );
+
+  if (!eslintPath) {
+    return;
+  }
+
+  const eslintContent = readFileSync(eslintPath, "utf8");
+  const eslintConfigBinding = getDefaultImportBinding(eslintContent, "@vadimcomanescu/nadicode-design-system/eslint-config");
+  const eslintPluginBinding = getNamedImportBinding(
+    eslintContent,
+    "@vadimcomanescu/nadicode-design-system/eslint-plugin",
+    "nadicodePlugin",
+  );
+
+  if (!eslintConfigBinding) {
+    addIssue(
+      relativePath(eslintPath),
+      "seed-eslint-config-contract",
+      "eslint.config.* must import @vadimcomanescu/nadicode-design-system/eslint-config.",
+    );
+  } else if (!bindingIsReferencedInDefaultExport(eslintContent, eslintConfigBinding)) {
+    addIssue(
+      relativePath(eslintPath),
+      "seed-eslint-config-contract",
+      "eslint.config.* must use the imported @vadimcomanescu/nadicode-design-system/eslint-config binding in the default-exported config.",
+    );
+  }
+
+  if (!eslintPluginBinding) {
+    addIssue(
+      relativePath(eslintPath),
+      "seed-eslint-config-contract",
+      "eslint.config.* must import nadicodePlugin from @vadimcomanescu/nadicode-design-system/eslint-plugin.",
+    );
+  } else if (!bindingIsReferencedInDefaultExport(eslintContent, eslintPluginBinding)) {
+    addIssue(
+      relativePath(eslintPath),
+      "seed-eslint-config-contract",
+      "eslint.config.* must use the imported @vadimcomanescu/nadicode-design-system/eslint-plugin binding in the default-exported config.",
+    );
+  }
+}
+
+function checkProvidersContract() {
+  const providersPath = expectFile(
+    [join(root, "src", "app", "providers.tsx"), join(root, "app", "providers.tsx")],
+    "seed-providers-missing",
+    "App Router providers.tsx must exist.",
+  );
+
+  ensureFileContains(
+    providersPath,
+    "@vadimcomanescu/nadicode-design-system/theme-provider",
+    "seed-providers-contract",
+    "providers.tsx must import ThemeProvider from @vadimcomanescu/nadicode-design-system/theme-provider.",
+  );
+}
+
+function checkI18nContract() {
+  const requestPath = expectFile(
+    [join(root, "src", "i18n", "request.ts"), join(root, "i18n", "request.ts")],
+    "seed-i18n-request-missing",
+    "The app must own src/i18n/request.ts and merge package-backed Seed catalogs there.",
+  );
+
+  ensureFileContains(
+    requestPath,
+    "@vadimcomanescu/nadicode-design-system/messages/",
+    "seed-i18n-request-contract",
+    "src/i18n/request.ts must import Seed catalogs from @vadimcomanescu/nadicode-design-system/messages/<locale>.",
+  );
+  ensureFileContains(
+    requestPath,
+    "mergeSeedMessages",
+    "seed-i18n-request-contract",
+    "src/i18n/request.ts must merge package-backed Seed catalogs with app messages via mergeSeedMessages().",
+  );
+
+  if (requestPath) {
+    const requestContent = readFileSync(requestPath, "utf8");
+    const requestCodeWithoutImports = getCodeWithoutImports(requestContent);
+    if (requestContent.includes("seed-messages/")) {
+      addIssue(
+        relativePath(requestPath),
+        "seed-i18n-request-contract",
+        "src/i18n/request.ts must not import DS catalogs from repo-local seed-messages/*.json.",
+      );
+    }
+
+    if (!hasGetRequestConfigExport(requestContent)) {
+      addIssue(
+        relativePath(requestPath),
+        "seed-i18n-request-contract",
+        "src/i18n/request.ts must default-export a next-intl getRequestConfig(...) result.",
+      );
+    }
+
+    const appMessageBindings = [...requestContent.matchAll(
+      /import\s+([A-Za-z_$][\w$]*)\s+from\s+["'][^"']*messages\/[^"']+\.json["']/g,
+    )].map((match) => match[1]);
+
+    if (appMessageBindings.length === 0) {
+      addIssue(
+        relativePath(requestPath),
+        "seed-i18n-request-contract",
+        "src/i18n/request.ts must import app-owned locale catalogs from messages/<locale>.json.",
+      );
+    } else {
+      const unreferencedAppMessages = appMessageBindings.filter((binding) => {
+        return !new RegExp(`\\b${escapeRegExp(binding)}\\b`).test(requestCodeWithoutImports);
+      });
+
+      if (unreferencedAppMessages.length > 0) {
+        addIssue(
+          relativePath(requestPath),
+          "seed-i18n-request-contract",
+          `src/i18n/request.ts must wire every imported app-owned locale catalog into the Seed message merge path. Unused imports: ${unreferencedAppMessages.join(", ")}.`,
+        );
+      }
+    }
+  }
+
+  const messagesDir = expectFile(
+    [join(root, "messages")],
+    "seed-i18n-messages-missing",
+    "Consumer apps must keep app-owned translations in a messages/ directory.",
+  );
+  if (!messagesDir) {
+    return;
+  }
+
+  const localeMessageFiles = readdirSync(messagesDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"));
+  if (localeMessageFiles.length === 0) {
+    addIssue(
+      relativePath(messagesDir),
+      "seed-i18n-messages-missing",
+      "Consumer apps must keep at least one app-owned locale catalog in messages/<locale>.json.",
+    );
+  }
+}
+
+function checkDelegatorScripts() {
+  const dsCheckPath = expectFile(
+    [join(root, "scripts", "ds-check.mjs")],
+    "seed-ds-check-missing",
+    "scripts/ds-check.mjs must exist.",
+  );
+  ensureFileContains(
+    dsCheckPath,
+    "@vadimcomanescu/nadicode-design-system/ds-check",
+    "seed-ds-check-contract",
+    "scripts/ds-check.mjs must delegate to @vadimcomanescu/nadicode-design-system/ds-check.",
+  );
+
+  const dsUpdatePath = expectFile(
+    [join(root, "scripts", "ds-update.mjs")],
+    "seed-ds-update-missing",
+    "scripts/ds-update.mjs must exist.",
+  );
+  if (dsUpdatePath) {
+    ensureFileContains(
+      dsUpdatePath,
+      "@vadimcomanescu/nadicode-design-system/ds-update",
+      "seed-ds-update-contract",
+      "scripts/ds-update.mjs must delegate to @vadimcomanescu/nadicode-design-system/ds-update so the package owns the install-and-skill-sync flow.",
+    );
+  }
+}
+
+function checkTsConfigContract() {
+  const tsConfigPath = expectFile(
+    [join(root, "tsconfig.json")],
+    "seed-tsconfig-missing",
+    "tsconfig.json must exist.",
+  );
+  if (!tsConfigPath) {
+    return;
+  }
+
+  try {
+    const tsConfig = parseJsonc(readFileSync(tsConfigPath, "utf8"));
+    const compilerOptions = tsConfig.compilerOptions ?? {};
+    const paths = compilerOptions.paths ?? {};
+    if (compilerOptions.baseUrl !== ".") {
+      addIssue(
+        relativePath(tsConfigPath),
+        "seed-tsconfig-contract",
+        'tsconfig.json must set compilerOptions.baseUrl to ".".',
+      );
+    }
+    if (JSON.stringify(paths["@/*"]) !== JSON.stringify(["./src/*"])) {
+      addIssue(
+        relativePath(tsConfigPath),
+        "seed-tsconfig-contract",
+        'tsconfig.json must map compilerOptions.paths["@/*"] to ["./src/*"].',
+      );
+    }
+  } catch {
+    addIssue(relativePath(tsConfigPath), "seed-tsconfig-invalid", "tsconfig.json must be valid JSON or JSONC.");
+  }
+}
+
+const packageJsonPath = findExistingPath([join(root, "package.json")]);
+const packageJson = packageJsonPath
+  ? JSON.parse(readFileSync(packageJsonPath, "utf8"))
+  : null;
+
+if (isSourceRepo(packageJson)) {
+  checkSourceRepo(packageJson);
+  checkSourceI18nContract();
+} else {
+  checkRequiredScripts(packageJsonPath, packageJson);
+  checkDependency(packageJsonPath ?? join(root, "package.json"), packageJson);
+  checkSeedSkillContract();
+  checkForbiddenDuplicatedDocs();
+  checkPaletteContract();
+  checkGlobalsContract();
+  checkTailwindContract();
+  checkEslintContract();
+  checkProvidersContract();
+  checkI18nContract();
+  checkDelegatorScripts();
+  checkTsConfigContract();
+}
+
+if (issues.length > 0) {
+  console.error(`ds:check failed with ${issues.length} issue(s):`);
+  for (const issue of issues) {
+    console.error(`- ${issue.file} [${issue.rule}] ${issue.detail}`);
+  }
+  process.exit(1);
+}
+
+const successLabel = isSourceRepo(packageJson) ? "source contract verified" : "package scaffold contract verified";
+console.log(`ds:check passed (${successLabel})`);