intor-cli 0.0.1

package/src/core/diagnostics/collect.ts

@@ -0,0 +1,59 @@
+import type { Diagnostic } from "./types";
+import type { ExtractedUsages } from "../extract-usages";
+import type { InferredSchemas } from "../infer-schema/types";
+import { enforceMissingReplacements } from "./rules/enforce-missing-replacements";
+import { enforceMissingRich } from "./rules/enforce-missing-rich";
+import { keyEmpty, keyNotFound } from "./rules/key";
+import {
+  replacementsNotAllowed,
+  replacementsMissing,
+  replacementsUnused,
+} from "./rules/replacement";
+import { richMissing, richNotAllowed, richUnused } from "./rules/rich";
+import { indexUsagesByKey } from "./utils/index-usages-by-key";
+
+export function collectDiagnostics(
+  { messagesSchema, replacementsSchema, richSchema }: InferredSchemas,
+  usages: ExtractedUsages,
+) {
+  const diagnostics: Diagnostic[] = [];
+
+  // Key
+  for (const usage of usages.keys) {
+    diagnostics.push(...keyNotFound(usage, messagesSchema), ...keyEmpty(usage));
+  }
+
+  // Replacements
+  for (const usage of usages.replacements) {
+    diagnostics.push(
+      ...replacementsNotAllowed(usage, replacementsSchema),
+      ...replacementsMissing(usage, replacementsSchema),
+      ...replacementsUnused(usage, replacementsSchema),
+    );
+  }
+
+  // Rich
+  for (const usage of usages.rich) {
+    diagnostics.push(
+      ...richNotAllowed(usage, richSchema),
+      ...richMissing(usage, richSchema),
+      ...richUnused(usage, richSchema),
+    );
+  }
+
+  // Ensure required replacements / rich tags are detected even when no usage provides them
+  const replacementIndex = indexUsagesByKey(usages.replacements);
+  const richIndex = indexUsagesByKey(usages.rich);
+  for (const usage of usages.keys) {
+    diagnostics.push(
+      ...enforceMissingReplacements(
+        usage,
+        replacementIndex,
+        replacementsSchema,
+      ),
+      ...enforceMissingRich(usage, richIndex, richSchema),
+    );
+  }
+
+  return diagnostics;
+}

package/src/core/diagnostics/group.ts

@@ -0,0 +1,41 @@
+/* eslint-disable unicorn/no-array-sort */
+import type { Diagnostic, DiagnosticGroup } from "./types";
+
+export function groupDiagnostics(diagnostics: Diagnostic[]): DiagnosticGroup[] {
+  const map = new Map<string, DiagnosticGroup>();
+
+  for (const diagnostic of diagnostics) {
+    const { severity, method, message, messageKey, file, line, column } =
+      diagnostic;
+
+    const groupId = messageKey
+      ? `${file}::${messageKey}::${diagnostic.method}`
+      : `${file}::${line}:${column}`;
+
+    if (!map.has(groupId)) {
+      map.set(groupId, {
+        severity,
+        method,
+        messageKey,
+        problems: [],
+        file,
+        lines: [],
+      });
+    }
+    const group = map.get(groupId)!;
+
+    group.problems.push(message);
+    group.lines.push(line);
+
+    // severity upgrade (error > warn)
+    if (severity === "error") {
+      group.severity = "error";
+    }
+  }
+
+  for (const group of map.values()) {
+    group.lines = [...new Set(group.lines)].sort((a, b) => a - b);
+  }
+
+  return [...map.values()];
+}

package/src/core/diagnostics/index.ts

@@ -0,0 +1,2 @@
+export { collectDiagnostics } from "./collect";
+export { groupDiagnostics } from "./group";

package/src/core/diagnostics/messages.ts

@@ -0,0 +1,51 @@
+export const DIAGNOSTIC_MESSAGES = {
+  // --------------------------------------------------
+  // Message key
+  // --------------------------------------------------
+  KEY_NOT_FOUND: {
+    code: "INTOR_KEY_NOT_FOUND",
+    message: () => "does not exist",
+  },
+
+  KEY_EMPTY: {
+    code: "INTOR_KEY_EMPTY",
+    message: () => "translation key cannot be empty",
+  },
+
+  // --------------------------------------------------
+  // Replacements
+  // --------------------------------------------------
+  REPLACEMENTS_NOT_ALLOWED: {
+    code: "INTOR_REPLACEMENTS_NOT_ALLOWED",
+    message: () => "does not accept replacements",
+  },
+
+  REPLACEMENTS_MISSING: {
+    code: "INTOR_REPLACEMENTS_MISSING",
+    message: (missing: string[]) =>
+      `missing replacements: ${missing.join(", ")}`,
+  },
+
+  REPLACEMENTS_UNUSED: {
+    code: "INTOR_REPLACEMENTS_UNUSED",
+    message: (extra: string[]) => `unused replacements: ${extra.join(", ")}`,
+  },
+
+  // --------------------------------------------------
+  // Rich tags
+  // --------------------------------------------------
+  RICH_NOT_ALLOWED: {
+    code: "INTOR_RICH_NOT_ALLOWED",
+    message: () => "does not accept rich tags",
+  },
+
+  RICH_MISSING: {
+    code: "INTOR_RICH_MISSING",
+    message: (missing: string[]) => `missing rich tags: ${missing.join(", ")}`,
+  },
+
+  RICH_UNUSED: {
+    code: "INTOR_RICH_UNUSED",
+    message: (extra: string[]) => `unused rich tags: ${extra.join(", ")}`,
+  },
+} as const;

package/src/core/diagnostics/rules/enforce-missing-replacements.ts

@@ -0,0 +1,55 @@
+import type { KeyUsage, ReplacementUsage } from "../../extract-usages";
+import type { InferNode } from "../../infer-schema";
+import type { Diagnostic } from "../types";
+import { DIAGNOSTIC_MESSAGES } from "../messages";
+import { getSchemaNodeAtPath } from "../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../utils/resolve-key-path";
+
+/**
+ * Detect missing replacements when no replacement usage exists anywhere.
+ *
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello", { name })
+ *
+ * // Received:
+ * t("hello") // Replacement usage cannot be detected
+ * ```
+ */
+export function enforceMissingReplacements(
+  usage: KeyUsage,
+  replacementIndex: Map<string, ReplacementUsage[]>,
+  replacementsSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+  const diagnostics: Diagnostic[] = [];
+
+  const keyPath = resolveKeyPath(key, preKey);
+
+  // Replacements provided elsewhere
+  if (replacementIndex.has(`${usage.method}::${keyPath}`)) return diagnostics;
+
+  const schemaNode = getSchemaNodeAtPath(replacementsSchema, keyPath);
+
+  // No replacement schema defined
+  if (!schemaNode || schemaNode.kind !== "object") return diagnostics;
+
+  const expected: string[] = Object.keys(schemaNode.properties);
+
+  // No required replacements
+  if (expected.length === 0) return diagnostics;
+
+  diagnostics.push({
+    severity: "warn",
+    method,
+    messageKey: keyPath,
+    code: DIAGNOSTIC_MESSAGES.REPLACEMENTS_MISSING.code,
+    message: DIAGNOSTIC_MESSAGES.REPLACEMENTS_MISSING.message(expected),
+    file,
+    line,
+    column,
+  });
+
+  return diagnostics;
+}

package/src/core/diagnostics/rules/enforce-missing-rich.ts

@@ -0,0 +1,55 @@
+import type { KeyUsage, RichUsage } from "../../extract-usages";
+import type { InferNode } from "../../infer-schema";
+import type { Diagnostic } from "../types";
+import { DIAGNOSTIC_MESSAGES } from "../messages";
+import { getSchemaNodeAtPath } from "../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../utils/resolve-key-path";
+
+/**
+ * Detect missing rich when no rich usage exists anywhere.
+ *
+ * @example
+ * ```ts
+ * // Expected:
+ * tRich("hello", { link })
+ *
+ * // Received:
+ * tRich("hello") // Rich usage cannot be detected
+ * ```
+ */
+export function enforceMissingRich(
+  usage: KeyUsage,
+  richIndex: Map<string, RichUsage[]>,
+  richSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+  const diagnostics: Diagnostic[] = [];
+
+  const keyPath = resolveKeyPath(key, preKey);
+
+  // Rich tags provided elsewhere
+  if (richIndex.has(`${method}::${keyPath}`)) return diagnostics;
+
+  const schemaNode = getSchemaNodeAtPath(richSchema, keyPath);
+
+  // No rich schema defined
+  if (!schemaNode || schemaNode.kind !== "object") return diagnostics;
+
+  const expected: string[] = Object.keys(schemaNode.properties);
+
+  // No required rich tags
+  if (expected.length === 0) return diagnostics;
+
+  diagnostics.push({
+    severity: "warn",
+    method,
+    messageKey: keyPath,
+    code: DIAGNOSTIC_MESSAGES.RICH_MISSING.code,
+    message: DIAGNOSTIC_MESSAGES.RICH_MISSING.message(expected),
+    file,
+    line,
+    column,
+  });
+
+  return diagnostics;
+}

package/src/core/diagnostics/rules/key/empty.ts

@@ -0,0 +1,34 @@
+import type { KeyUsage } from "../../../extract-usages";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello")
+ *
+ * // Received:
+ * t("")
+ * ```
+ */
+export function keyEmpty(usage: KeyUsage): Diagnostic[] {
+  const { method, key, file, line, column } = usage;
+
+  if (!key) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: key,
+        code: DIAGNOSTIC_MESSAGES.KEY_EMPTY.code,
+        message: DIAGNOSTIC_MESSAGES.KEY_EMPTY.message(),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/key/index.ts

@@ -0,0 +1,2 @@
+export { keyEmpty } from "./empty";
+export { keyNotFound } from "./not-found";

package/src/core/diagnostics/rules/key/not-found.ts

@@ -0,0 +1,43 @@
+import type { KeyUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello")
+ *
+ * // Received:
+ * t("missing")
+ * ```
+ */
+export function keyNotFound(
+  usage: KeyUsage,
+  messagesSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  if (!key) return [];
+
+  const keyPath = resolveKeyPath(key, preKey);
+  if (!getSchemaNodeAtPath(messagesSchema, keyPath)) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: key,
+        code: DIAGNOSTIC_MESSAGES.KEY_NOT_FOUND.code,
+        message: DIAGNOSTIC_MESSAGES.KEY_NOT_FOUND.message(),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/replacement/index.ts

@@ -0,0 +1,3 @@
+export { replacementsNotAllowed } from "./not-allowed";
+export { replacementsMissing } from "./missing";
+export { replacementsUnused } from "./unused";

package/src/core/diagnostics/rules/replacement/missing.ts

@@ -0,0 +1,48 @@
+import type { ReplacementUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello", { name, phone })
+ *
+ * // Received:
+ * t("hello", { name })
+ * ```
+ */
+export function replacementsMissing(
+  usage: ReplacementUsage,
+  replacementsSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(replacementsSchema, keyPath);
+  if (!schemaNode || schemaNode.kind !== "object") return [];
+
+  const expected = Object.keys(schemaNode.properties);
+  const actual = usage.replacements;
+  const missing = expected.filter((name) => !actual.includes(name));
+
+  if (missing.length > 0) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.REPLACEMENTS_MISSING.code,
+        message: DIAGNOSTIC_MESSAGES.REPLACEMENTS_MISSING.message(missing),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/replacement/not-allowed.ts

@@ -0,0 +1,43 @@
+import type { ReplacementUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello")
+ *
+ * // Received:
+ * t("hello", { name })
+ * ```
+ */
+export function replacementsNotAllowed(
+  usage: ReplacementUsage,
+  replacementsSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(replacementsSchema, keyPath);
+
+  if (!schemaNode || schemaNode.kind !== "object") {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.REPLACEMENTS_NOT_ALLOWED.code,
+        message: DIAGNOSTIC_MESSAGES.REPLACEMENTS_NOT_ALLOWED.message(),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/replacement/unused.ts

@@ -0,0 +1,48 @@
+import type { ReplacementUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello", { name })
+ *
+ * // Received:
+ * t("hello", { name, phone })
+ * ```
+ */
+export function replacementsUnused(
+  usage: ReplacementUsage,
+  replacementsSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(replacementsSchema, keyPath);
+  if (!schemaNode || schemaNode.kind !== "object") return [];
+
+  const expected = Object.keys(schemaNode.properties);
+  const actual = usage.replacements;
+  const extra = actual.filter((name) => !expected.includes(name));
+
+  if (extra.length > 0) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.REPLACEMENTS_UNUSED.code,
+        message: DIAGNOSTIC_MESSAGES.REPLACEMENTS_UNUSED.message(extra),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/rich/index.ts

@@ -0,0 +1,3 @@
+export { richNotAllowed } from "./not-allowed";
+export { richMissing } from "./missing";
+export { richUnused } from "./unused";

package/src/core/diagnostics/rules/rich/missing.ts

@@ -0,0 +1,48 @@
+import type { RichUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * tRich("hello", { link })
+ *
+ * // Received:
+ * tRich("hello", { link, b })
+ * ```
+ */
+export function richMissing(
+  usage: RichUsage,
+  richSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(richSchema, keyPath);
+  if (!schemaNode || schemaNode.kind !== "object") return [];
+
+  const expected = Object.keys(schemaNode.properties);
+  const actual = usage.rich;
+  const missing = expected.filter((tag) => !actual.includes(tag));
+
+  if (missing.length > 0) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.RICH_MISSING.code,
+        message: DIAGNOSTIC_MESSAGES.RICH_MISSING.message(missing),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/rich/not-allowed.ts

@@ -0,0 +1,43 @@
+import type { RichUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * tRich("hello")
+ *
+ * // Received:
+ * tRich("hello", { link })
+ * ```
+ */
+export function richNotAllowed(
+  usage: RichUsage,
+  richSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(richSchema, keyPath);
+
+  if (!schemaNode || schemaNode.kind !== "object") {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.RICH_NOT_ALLOWED.code,
+        message: DIAGNOSTIC_MESSAGES.RICH_NOT_ALLOWED.message(),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/rules/rich/unused.ts

@@ -0,0 +1,48 @@
+import type { RichUsage } from "../../../extract-usages";
+import type { InferNode } from "../../../infer-schema";
+import type { Diagnostic } from "../../types";
+import { DIAGNOSTIC_MESSAGES } from "../../messages";
+import { getSchemaNodeAtPath } from "../../utils/get-schema-node-at-path";
+import { resolveKeyPath } from "../../utils/resolve-key-path";
+
+/**
+ * @example
+ * ```ts
+ * // Expected:
+ * t("hello", { name })
+ *
+ * // Received:
+ * t("hello", { name, phone })
+ * ```
+ */
+export function richUnused(
+  usage: RichUsage,
+  richSchema: InferNode,
+): Diagnostic[] {
+  const { method, key, preKey, file, line, column } = usage;
+
+  const keyPath = resolveKeyPath(key, preKey);
+  const schemaNode = getSchemaNodeAtPath(richSchema, keyPath);
+  if (!schemaNode || schemaNode.kind !== "object") return [];
+
+  const expected = Object.keys(schemaNode.properties);
+  const actual = usage.rich;
+  const extra = actual.filter((tag) => !expected.includes(tag));
+
+  if (extra.length > 0) {
+    return [
+      {
+        severity: "warn",
+        method,
+        messageKey: keyPath,
+        code: DIAGNOSTIC_MESSAGES.RICH_UNUSED.code,
+        message: DIAGNOSTIC_MESSAGES.RICH_UNUSED.message(extra),
+        file,
+        line,
+        column,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/core/diagnostics/types.ts

@@ -0,0 +1,21 @@
+import type { TranslatorMethod } from "../extract-usages";
+
+export interface Diagnostic {
+  severity: "error" | "warn";
+  method: TranslatorMethod;
+  messageKey: string;
+  code: string;
+  message: string;
+  file: string;
+  line: number;
+  column: number;
+}
+
+export interface DiagnosticGroup {
+  severity: "error" | "warn";
+  method: TranslatorMethod;
+  messageKey: string;
+  problems: string[]; // list of bullet messages
+  file: string;
+  lines: number[]; // sorted, unique
+}