intor-cli 0.0.9 → 0.0.10

package/README.md

@@ -24,7 +24,13 @@ CLI tool for intor.
 </table>
 </div>
 
-## Usage
+## Overview
+
+- **generate** — message schema & types
+- **check** — usage analysis
+- **validate** — locale completeness
+
+## Commands
 
 #### generate
 
@@ -33,8 +39,8 @@ npx intor-cli generate
 ```
 
 - Generates TypeScript types and schema artifacts
-- Designed to be safe, deterministic, and non-intrusive
-- Displays runtime message override details during generation
+- Uses the default locale as the single source of truth
+- Reports message override behavior during generation
 
 #### check
 
@@ -42,13 +48,23 @@ npx intor-cli generate
 npx intor-cli check
 ```
 
-- Statically extracts translator usages from your codebase
-- Validates preKey, message keys, replacements, and rich tags
+- Statistically analyzes translator usage in your codebase
+- Detects incorrect keys, replacements, and rich tag usage
 - Reports diagnostics with precise source locations
 
+#### validate
+
+```bash
+npx intor-cli validate
+```
+
+- Validates locale message completeness against schemas
+- Checks missing keys, replacements, and rich tags
+- Reports issues grouped by config and locale
+
 ## Design Guarantees
 
 - Message types are inferred from the **_default locale_** only.
-- All locales are assumed to share the same message shape.
-- Locale is treated as a runtime dimension, not a structural one.
-- Generated types are intentionally conservative and do not validate locale completeness.
+- All locales are expected to share the same message shape.
+- Locale is treated strictly as a runtime dimension, not a structural one.
+- Generated types are intentionally conservative and do not enforce locale completeness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-cli",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "📟 CLI tool for intor",
   "author": "Yiming Liao",
   "homepage": "https://github.com/yiming-liao/intor-cli#readme",
@@ -39,11 +39,11 @@
     "intor": "src/cli/index.ts"
   },
   "dependencies": {
-    "@intor/reader-md": "0.1.1",
-    "@intor/reader-yaml": "0.1.0",
+    "@intor/reader-md": "0.1.4",
+    "@intor/reader-yaml": "0.1.1",
     "cac": "6.7.14",
     "fast-glob": "3.3.3",
-    "intor": "2.3.22",
+    "intor": "2.3.26",
     "logry": "2.1.6",
     "ora": "9.0.0",
     "picocolors": "1.1.1",

package/src/build/build-schemas/build-schemas.ts

@@ -1,6 +1,6 @@
-import type { BuildInput, GeneratedSchema } from "../types";
+import type { BuildInput, Schema } from "../types";
 
-export function buildSchemas(inputs: BuildInput[]): GeneratedSchema {
+export function buildSchemas(inputs: BuildInput[]): Schema {
   return {
     version: 1,
     generatedAt: new Date().toISOString(),

package/src/build/build-types/utils/render-infer-node.ts

@@ -1,4 +1,4 @@
-import type { InferNode } from "../../../core/infer-schema";
+import type { InferNode } from "../../../core";
 import { indent } from "./indent";
 
 export function renderInferNode(node: InferNode, indentLevel = 4): string {

package/src/build/index.ts

@@ -1,3 +1,3 @@
 export { buildTypes } from "./build-types";
 export { buildSchemas } from "./build-schemas";
-export type { BuildInput, GeneratedSchema } from "./types";
+export type { BuildInput, Schema } from "./types";

package/src/build/types.ts

@@ -7,12 +7,13 @@ export interface BuildInput {
 }
 
 // Schema
-export interface GeneratedSchema {
+export interface Schema {
   version: number;
   generatedAt: string;
-  configs: GeneratedSchemaConfig[];
+  configs: SchemaConfig[];
 }
-export interface GeneratedSchemaConfig {
+
+export interface SchemaConfig {
   id: string;
   locales: readonly string[];
   schemas: InferredSchemas;

package/src/cli/commands/check.ts

@@ -1,4 +1,3 @@
-import type { ReadGeneratedSchemaOptions } from "../../core";
 import type { ExtractUsagesOptions } from "../../core/extract-usages/extract-usages";
 import type { CAC } from "cac";
 import { check } from "../../features";
@@ -13,20 +12,6 @@ export function registerCheckCommand(cli: CAC) {
     // -----------------------------------------------------------------------
     // Option
     // -----------------------------------------------------------------------
-    // Read generated schema options
-    .option(
-      "--cwd <path>",
-      "Working directory for resolving intor config (default: process.cwd())",
-    )
-    .option(
-      "--file-name <name>",
-      "Generated schema file name (default: intor-generated.schema.json)",
-    )
-    .option(
-      "--out-dir <path>",
-      "Directory of generated schema output (default: .intor)",
-    )
-    // Extract usages options
     .option(
       "--tsconfig <path>",
       "Path to tsconfig.json (default: tsconfig.json)",
@@ -36,15 +21,13 @@ export function registerCheckCommand(cli: CAC) {
     // -----------------------------------------------------------------------
     // Action
     // -----------------------------------------------------------------------
-    .action(
-      async (options: ReadGeneratedSchemaOptions & ExtractUsagesOptions) => {
-        const { cwd, fileName, outDir, tsconfigPath, debug } = options;
-        try {
-          await check({ cwd, fileName, outDir }, { tsconfigPath, debug });
-        } catch (error) {
-          console.error(error);
-          process.exitCode = 1;
-        }
-      },
-    );
+    .action(async (options: ExtractUsagesOptions) => {
+      const { tsconfigPath, debug } = options;
+      try {
+        await check({ tsconfigPath, debug });
+      } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+      }
+    });
 }

package/src/cli/commands/generate.ts

@@ -1,6 +1,7 @@
 import type { ExtraExt } from "../../core";
 import type { CAC } from "cac";
 import { generate } from "../../features";
+import { normalizeReaderOptions } from "./utils/normalize-reader-options";
 
 export function registerGenerateCommand(cli: CAC) {
   cli
@@ -37,19 +38,7 @@ export function registerGenerateCommand(cli: CAC) {
         debug?: boolean;
       };
 
-      // Normalize exts
-      const exts = ext ? (Array.isArray(ext) ? ext : [ext]) : [];
-
-      // Parse customReaders: ["md=./my-md-reader.ts"] → { md: "./my-md-reader.ts" }
-      let customReaders: Record<string, string> | undefined;
-      if (reader && reader.length > 0) {
-        customReaders = {};
-        for (const item of reader) {
-          const [key, value] = item.split("=", 2);
-          if (!key || !value) continue;
-          customReaders[key] = value;
-        }
-      }
+      const { exts, customReaders } = normalizeReaderOptions({ ext, reader });
 
       try {
         await generate({ exts, customReaders, debug });

package/src/cli/commands/utils/normalize-reader-options.ts

@@ -0,0 +1,46 @@
+import type { ExtraExt } from "../../../core";
+
+export interface NormalizedReaderOptions {
+  exts: ExtraExt[];
+  customReaders?: Record<string, string>;
+}
+
+export interface RawReaderOptions {
+  ext?: string | string[];
+  reader?: string[];
+}
+
+/**
+ * Normalize CLI reader-related options:
+ * - ext: string | string[] → string[]
+ * - reader: ["md=./reader.ts"] → { md: "./reader.ts" }
+ */
+export function normalizeReaderOptions(
+  options: RawReaderOptions,
+): NormalizedReaderOptions {
+  // Normalize exts
+  const exts = options.ext
+    ? Array.isArray(options.ext)
+      ? options.ext
+      : [options.ext]
+    : [];
+
+  // Normalize custom readers
+  let customReaders: Record<string, string> | undefined;
+
+  if (options.reader && options.reader.length > 0) {
+    customReaders = {};
+
+    for (const item of options.reader) {
+      const [key, value] = item.split("=", 2);
+      if (!key || !value) continue;
+
+      customReaders[key] = value;
+    }
+  }
+
+  return {
+    exts: exts as ExtraExt[],
+    customReaders,
+  };
+}

package/src/cli/commands/validate.ts

@@ -0,0 +1,50 @@
+import type { ExtraExt } from "../../core";
+import type { CAC } from "cac";
+import { validate } from "../../features";
+import { normalizeReaderOptions } from "./utils/normalize-reader-options";
+
+export function registerValidateCommand(cli: CAC) {
+  cli
+    // -----------------------------------------------------------------------
+    // Command
+    // -----------------------------------------------------------------------
+    .command("validate", "Validate intor locale translations")
+
+    // -----------------------------------------------------------------------
+    // Option
+    // -----------------------------------------------------------------------
+    .option(
+      "--ext <ext>",
+      "Enable extra messages file extension (repeatable)",
+      { default: [] },
+    )
+    .option(
+      "--reader <mapping>",
+      "Custom reader mapping in the form <ext=path> (repeatable)",
+      { default: [] },
+    )
+    .option(
+      "--debug",
+      "Print debug information during config discovery and generation",
+    )
+
+    // -----------------------------------------------------------------------
+    // Action
+    // -----------------------------------------------------------------------
+    .action(async (options) => {
+      const { ext, reader, debug } = options as {
+        ext?: Array<ExtraExt>;
+        reader?: string[];
+        debug?: boolean;
+      };
+
+      const { exts, customReaders } = normalizeReaderOptions({ ext, reader });
+
+      try {
+        await validate({ exts, customReaders, debug });
+      } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/index.ts

@@ -3,6 +3,7 @@
 import { cac } from "cac";
 import { registerCheckCommand } from "./commands/check";
 import { registerGenerateCommand } from "./commands/generate";
+import { registerValidateCommand } from "./commands/validate";
 
 const cli = cac("intor");
 
@@ -11,6 +12,7 @@ const cli = cac("intor");
 // ---------------------------------------------------------------------
 registerGenerateCommand(cli);
 registerCheckCommand(cli);
+registerValidateCommand(cli);
 
 // ---------------------------------------------------------------------
 // Global options / help

package/src/core/collect-messages/collect-other-locale-messages.ts

@@ -0,0 +1,27 @@
+import type { ExtraExt } from "../constants";
+import type { IntorResolvedConfig, MessageObject } from "intor";
+import { collectRuntimeMessages } from "./collect-runtime-messages";
+
+export async function collectOtherLocaleMessages(
+  config: IntorResolvedConfig,
+  exts: Array<ExtraExt> = [],
+  customReaders?: Record<string, string>,
+): Promise<Record<string, MessageObject>> {
+  const { supportedLocales, defaultLocale } = config;
+
+  const result: Record<string, MessageObject> = {};
+
+  for (const locale of supportedLocales) {
+    if (locale === defaultLocale) continue;
+
+    const { messages } = await collectRuntimeMessages(
+      config,
+      locale,
+      exts,
+      customReaders,
+    );
+    result[locale] = messages[locale];
+  }
+
+  return result;
+}

package/src/core/collect-messages/index.ts

@@ -1 +1,2 @@
 export { collectRuntimeMessages } from "./collect-runtime-messages";
+export { collectOtherLocaleMessages } from "./collect-other-locale-messages";

package/src/core/constants/generated.ts

@@ -0,0 +1,5 @@
+export const DEFAULT_OUT_DIR = ".intor";
+export const DEFAULT_TYPES_FILE_NAME = "types.d.ts";
+export const DEFAULT_SCHEMA_FILE_NAME = "schema.json";
+
+export const DEFAULT_MESSAGES_SNAPSHOT_DIR = "messages-snapshot";

package/src/core/constants/index.ts

@@ -1,7 +1,8 @@
 export {
   DEFAULT_OUT_DIR,
-  DEFAULT_TYPES_FILE,
-  DEFAULT_SCHEMA_FILE,
-} from "./generated-files";
+  DEFAULT_TYPES_FILE_NAME,
+  DEFAULT_SCHEMA_FILE_NAME,
+  DEFAULT_MESSAGES_SNAPSHOT_DIR,
+} from "./generated";
 
 export { EXTRA_EXTS, type ExtraExt } from "./extra-exts";

package/src/core/extract-usages/index.ts

@@ -1,4 +1,4 @@
-export { extractUsages } from "./extract-usages";
+export { extractUsages, type ExtractUsagesOptions } from "./extract-usages";
 
 export type {
   ExtractedUsages,

package/src/core/generated/ensure-and-write.ts

@@ -0,0 +1,11 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureAndWrite(
+  filePath: string,
+  content: string,
+): Promise<string> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, "utf8");
+  return filePath;
+}

package/src/core/generated/index.ts

@@ -0,0 +1,6 @@
+export { writeTypes } from "./write-types";
+
+export { writeSchema } from "./write-schema";
+export { readSchema } from "./read-schema";
+
+export { writeMessagesSnapshot } from "./write-messages-snapshot";

package/src/core/generated/read-schema.ts

@@ -0,0 +1,33 @@
+import type { Schema } from "../../build";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_OUT_DIR, DEFAULT_SCHEMA_FILE_NAME } from "../constants";
+
+export async function readSchema(): Promise<Schema> {
+  const filePath = path.join(DEFAULT_OUT_DIR, DEFAULT_SCHEMA_FILE_NAME);
+
+  let raw: string;
+
+  // ------------------------------------------------------------------
+  // Read file
+  // ------------------------------------------------------------------
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch {
+    throw new Error(
+      `Failed to read Intor schema file at "${filePath}".\n` +
+        `Have you run "intor generate"?`,
+    );
+  }
+
+  // ------------------------------------------------------------------
+  // Parse JSON
+  // ------------------------------------------------------------------
+  try {
+    return JSON.parse(raw) as Schema;
+  } catch {
+    throw new Error(
+      `Invalid JSON format in Intor schema file at "${filePath}".`,
+    );
+  }
+}

package/src/core/generated/write-messages-snapshot.ts

@@ -0,0 +1,27 @@
+/* eslint-disable unicorn/no-array-sort */
+import type { MessageObject } from "intor";
+import path from "node:path";
+import { DEFAULT_OUT_DIR, DEFAULT_MESSAGES_SNAPSHOT_DIR } from "../constants";
+import { ensureAndWrite } from "./ensure-and-write";
+
+export async function writeMessagesSnapshot(
+  localeMessages: Record<string, MessageObject>,
+): Promise<string[]> {
+  const filePaths: string[] = [];
+
+  for (const locale of Object.keys(localeMessages).sort()) {
+    const messages = localeMessages[locale];
+
+    const filePath = path.join(
+      DEFAULT_OUT_DIR,
+      DEFAULT_MESSAGES_SNAPSHOT_DIR,
+      `${locale}.json`,
+    );
+
+    await ensureAndWrite(filePath, JSON.stringify(messages, null, 2));
+
+    filePaths.push(filePath);
+  }
+
+  return filePaths;
+}

package/src/core/generated/write-schema.ts

@@ -0,0 +1,9 @@
+import type { Schema } from "../../build";
+import path from "node:path";
+import { DEFAULT_OUT_DIR, DEFAULT_SCHEMA_FILE_NAME } from "../constants";
+import { ensureAndWrite } from "./ensure-and-write";
+
+export async function writeSchema(schema: Schema): Promise<string> {
+  const filePath = path.join(DEFAULT_OUT_DIR, DEFAULT_SCHEMA_FILE_NAME);
+  return await ensureAndWrite(filePath, JSON.stringify(schema, null, 2));
+}

package/src/core/generated/write-types.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+import { DEFAULT_OUT_DIR, DEFAULT_TYPES_FILE_NAME } from "../constants";
+import { ensureAndWrite } from "./ensure-and-write";
+
+export async function writeTypes(types: string): Promise<string> {
+  const filePath = path.join(DEFAULT_OUT_DIR, DEFAULT_TYPES_FILE_NAME);
+  return await ensureAndWrite(filePath, types);
+}

package/src/core/index.ts

@@ -1,13 +1,40 @@
+// discover-configs
 export { discoverConfigs } from "./discover-configs";
-export { collectRuntimeMessages } from "./collect-messages";
-export { inferSchemas, type InferredSchemas } from "./infer-schema";
-export { extractUsages } from "./extract-usages";
-export { collectDiagnostics, groupDiagnostics } from "./diagnostics";
 
-export { writeGeneratedFiles } from "./write-generated-files";
+// collect-messages
 export {
-  readGeneratedSchema,
-  type ReadGeneratedSchemaOptions,
-} from "./read-generated-schema";
+  collectRuntimeMessages,
+  collectOtherLocaleMessages,
+} from "./collect-messages";
 
-export { EXTRA_EXTS, type ExtraExt } from "./constants";
+// infer-schema
+export {
+  inferSchemas,
+  type InferNode,
+  type InferredSchemas,
+  extractInterpolationNames,
+} from "./infer-schema";
+
+// extract-usages
+export {
+  extractUsages,
+  type ExtractUsagesOptions,
+  type ExtractedUsages,
+  type TranslatorFactory,
+  type TranslatorMethod,
+  type ReplacementUsage,
+  type PreKeyUsage,
+  type KeyUsage,
+  type RichUsage,
+} from "./extract-usages";
+
+// generated
+export {
+  writeTypes,
+  writeSchema,
+  readSchema,
+  writeMessagesSnapshot,
+} from "./generated";
+
+// constants
+export { DEFAULT_OUT_DIR, EXTRA_EXTS, type ExtraExt } from "./constants";

package/src/core/infer-schema/index.ts

@@ -1,3 +1,4 @@
 export { inferSchemas } from "./infer-schemas";
 export type { InferNode, InferredSchemas } from "./types";
-export { buildSchemas } from "../../build/build-schemas/build-schemas";
+
+export { extractInterpolationNames } from "./replacements/extract-interpolation-names";

package/src/core/infer-schema/infer-schemas.ts

@@ -3,14 +3,18 @@ import type { MessageObject } from "intor";
 import { inferMessagesSchema } from "./messages";
 import { inferReplacementsSchema } from "./replacements";
 import { inferRichSchema } from "./rich";
+import { stripInternalKeys } from "./utils/strip-internal-keys";
 
 /**
  * Infer all semantic schemas from messages.
  */
 export function inferSchemas(messages: MessageObject): InferredSchemas {
-  return {
+  const schemas = {
     messagesSchema: inferMessagesSchema(messages),
     replacementsSchema: inferReplacementsSchema(messages),
     richSchema: inferRichSchema(messages),
   };
+
+  stripInternalKeys(schemas);
+  return schemas;
 }

package/src/core/infer-schema/messages/infer-messages-schema.ts

@@ -49,7 +49,7 @@ function inferValue(value: MessageValue): InferNode {
   // Object values
   // ----------------------------------------------------------------------
   if (isMessageObject(value)) {
-    const result = inferObject(value, inferValue);
+    const result = inferObject(value, inferValue, "messages");
 
     // empty object → fallback record
     if (result.kind === "none") {

package/src/core/infer-schema/replacements/infer-replacements-schema.ts

@@ -55,7 +55,7 @@ function inferValue(value: MessageValue): InferNode {
   // Object values (delegate aggregation & pruning)
   // ----------------------------------------------------------------------
   if (isMessageObject(value)) {
-    return inferObject(value, inferValue);
+    return inferObject(value, inferValue, "replacements");
   }
 
   // Fallback

package/src/core/infer-schema/rich/infer-rich-schema.ts

@@ -58,7 +58,7 @@ function inferValue(value: MessageValue): InferNode {
   // Object values (delegate aggregation & pruning)
   // ----------------------------------------------------------------------
   if (isMessageObject(value)) {
-    return inferObject(value, inferValue);
+    return inferObject(value, inferValue, "rich");
   }
 
   // Fallback

package/src/core/infer-schema/utils/infer-object.ts

@@ -1,5 +1,6 @@
 import type { InferNode } from "../types";
 import type { MessageObject, MessageValue } from "intor";
+import { shouldSkipKey } from "./should-skip-key";
 
 /**
  * Infer an object-like semantic node by aggregating inferred children.
@@ -8,13 +9,17 @@ import type { MessageObject, MessageValue } from "intor";
  * - Prunes branches without semantic meaning
  * - Returns `none` if no children remain
  */
+
 export function inferObject(
   value: MessageObject,
   inferChild: (value: MessageValue) => InferNode,
+  mode: "messages" | "replacements" | "rich",
 ): InferNode {
   const properties: Record<string, InferNode> = {};
 
   for (const [key, val] of Object.entries(value)) {
+    if (shouldSkipKey(key, mode)) continue;
+
     const child = inferChild(val);
 
     // Skip branches without semantic meaning
@@ -23,10 +28,7 @@ export function inferObject(
     properties[key] = child;
   }
 
-  // No inferred children => no semantic result
-  if (Object.keys(properties).length === 0) {
-    return { kind: "none" };
-  }
-
-  return { kind: "object", properties };
+  return Object.keys(properties).length === 0
+    ? { kind: "none" }
+    : { kind: "object", properties };
 }

package/src/core/infer-schema/utils/should-skip-key.ts

@@ -0,0 +1,15 @@
+/**
+ * Determine whether a message object key should be ignored during schema inference.
+ *
+ * - Internal Intor metadata keys (`__intor_*`) are never part of semantic schemas
+ * - Markdown payload (`content`) is only meaningful in Messages schema,
+ *   and must be excluded from Replacements / Rich inference
+ */
+export function shouldSkipKey(
+  key: string,
+  mode: "messages" | "replacements" | "rich",
+) {
+  if (key.startsWith("__intor_")) return true;
+  if (mode !== "messages" && key === "content") return true;
+  return false;
+}