intor-cli 0.0.1

package/src/core/extract-usages/collectors/utils/walk-translator-bindings.ts

@@ -0,0 +1,47 @@
+import type {
+  CallExpression,
+  ObjectBindingPattern,
+  SourceFile,
+} from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+
+export interface DestructuredVariableCallContext {
+  sourceFile: SourceFile;
+  call: CallExpression;
+  binding: ObjectBindingPattern;
+}
+
+/**
+ * Walk through destructured variable declarations initialized by a call.
+ */
+export function walkTranslatorBindings(
+  sourceFile: SourceFile,
+  visitor: (ctx: DestructuredVariableCallContext) => void,
+): void {
+  sourceFile.forEachDescendant((node) => {
+    // Only handle variable declarations (e.g. `const x = ...`)
+    if (!node.isKind(SyntaxKind.VariableDeclaration)) return;
+
+    // Ensure the declaration has an initializer (skip `let x;`)
+    const initializer = node.getInitializer();
+    if (!initializer) return;
+
+    // Unwrap awaited initializers (e.g. `await foo()` -> `foo()`)
+    const call = initializer.isKind(SyntaxKind.AwaitExpression)
+      ? initializer.getExpression()
+      : initializer;
+    if (!call.isKind(SyntaxKind.CallExpression)) return;
+
+    // Only support object destructuring bindings
+    // Supported: `const { t } = useTranslator()`
+    // Ignored: `const translator = useTranslator()` (no destructuring)
+    const binding = node.getNameNode();
+    if (!binding.isKind(SyntaxKind.ObjectBindingPattern)) return;
+
+    visitor({
+      sourceFile,
+      call,
+      binding,
+    });
+  });
+}

package/src/core/extract-usages/collectors/utils/walk-translator-method-calls.ts

@@ -0,0 +1,42 @@
+import type { TranslatorBinding, TranslatorBindingMap } from "../../types";
+import type { SourceFile, CallExpression } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+
+interface TranslatorCallContext {
+  sourceFile: SourceFile;
+  translatorUsage: TranslatorBinding;
+  call: CallExpression;
+  localName: string;
+}
+
+/**
+ * Walk through all static translator method calls within a source file.
+ */
+export function walkTranslatorMethodCalls(
+  sourceFile: SourceFile,
+  translatorBindingMap: TranslatorBindingMap,
+  visitor: (ctx: TranslatorCallContext) => void,
+): void {
+  sourceFile.forEachDescendant((node) => {
+    // Only care about call expressions (e.g. `t(...)`)
+    if (!node.isKind(SyntaxKind.CallExpression)) return;
+
+    // Only support direct identifier calls.
+    // Supported: `t("key")`
+    // Ignored: `translator.t("key")`, `getTranslator().t("key")`
+    const expr = node.getExpression();
+    if (!expr.isKind(SyntaxKind.Identifier)) return;
+
+    // Match against known translator bindings
+    const localName = expr.getText();
+    const translatorUsage = translatorBindingMap.get(localName);
+    if (!translatorUsage) return;
+
+    visitor({
+      sourceFile,
+      translatorUsage,
+      call: node,
+      localName,
+    });
+  });
+}

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

@@ -0,0 +1,88 @@
+import type { ExtractedUsages } from "./types";
+import pc from "picocolors";
+import { createLogger } from "../scan-logger";
+import {
+  collectTranslatorBindings,
+  collectKeyUsages,
+  collectReplacementUsages,
+  collectRichUsages,
+  collectPreKeys,
+} from "./collectors";
+import { loadSourceFilesFromTsconfig } from "./load-source-files-from-tscofnig";
+
+export interface ExtractUsagesOptions {
+  tsconfigPath?: string;
+  debug?: boolean;
+}
+
+/**
+ * Extract all static translator usages from a TypeScript project.
+ */
+export function extractUsages(options?: ExtractUsagesOptions): ExtractedUsages {
+  const { tsconfigPath = "tsconfig.json", debug = false } = options || {};
+  const log = createLogger(debug);
+
+  const result: ExtractedUsages = {
+    keys: [],
+    replacements: [],
+    rich: [],
+  };
+
+  let scannedFiles = 0;
+  let matchedFiles = 0;
+
+  const sourceFiles = loadSourceFilesFromTsconfig(tsconfigPath, debug);
+
+  // Process each source file independently
+  for (const sourceFile of sourceFiles) {
+    scannedFiles++;
+    log("scan", sourceFile.getFilePath());
+
+    // -----------------------------------------------------------------------
+    // Translator binding
+    // -----------------------------------------------------------------------
+    const translatorBindingMap = collectTranslatorBindings(sourceFile);
+    if (translatorBindingMap.size === 0) continue;
+    matchedFiles++;
+
+    // -----------------------------------------------------------------------
+    // Key usages
+    // -----------------------------------------------------------------------
+    const keyUsages = collectKeyUsages(sourceFile, translatorBindingMap);
+
+    // -----------------------------------------------------------------------
+    // Replacement usages
+    // -----------------------------------------------------------------------
+    const replacementUsages = collectReplacementUsages(
+      sourceFile,
+      translatorBindingMap,
+    );
+
+    // -----------------------------------------------------------------------
+    // Rich usages
+    // -----------------------------------------------------------------------
+    const richUsages = collectRichUsages(sourceFile, translatorBindingMap);
+
+    // -----------------------------------------------------------------------
+    // PreKey values
+    // -----------------------------------------------------------------------
+    const preKeyMap = collectPreKeys(sourceFile, translatorBindingMap);
+
+    // Attach preKey to all usages that support it
+    for (const usage of [...keyUsages, ...replacementUsages, ...richUsages]) {
+      usage.preKey = preKeyMap.get(usage.localName);
+    }
+
+    result.keys.push(...keyUsages);
+    result.replacements.push(...replacementUsages);
+    result.rich.push(...richUsages);
+  }
+
+  if (debug) {
+    console.log(
+      pc.dim(` › Scanned ${scannedFiles} files, matched ${matchedFiles} \n`),
+    );
+  }
+
+  return result;
+}

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

@@ -0,0 +1,13 @@
+export { extractUsages } from "./extract-usages";
+
+export type {
+  ExtractedUsages,
+  KeyUsage,
+  ReplacementUsage,
+  RichUsage,
+} from "./types";
+
+export type {
+  TranslatorFactory,
+  TranslatorMethod,
+} from "./translator-registry";

package/src/core/extract-usages/load-source-files-from-tscofnig.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { Project, type SourceFile } from "ts-morph";
+
+/**
+ * Load source files from a tsconfig.
+ *
+ * Strategy:
+ * 1. Try loading source files from the given tsconfig directly.
+ * 2. If no source files are found, follow project references (one level).
+ * 3. Return the collected source files for further static analysis.
+ *
+ * Notes:
+ * - This is designed to support Vite-style tsconfig setups
+ *   where the root tsconfig only contains references.
+ * - References are followed non-recursively on purpose.
+ */
+export function loadSourceFilesFromTsconfig(
+  tsconfigPath: string,
+  debug: boolean,
+): SourceFile[] {
+  // ---------------------------------------------------------------------------
+  // 1. Try loading source files directly from the given tsconfig
+  // ---------------------------------------------------------------------------
+  const project = new Project({ tsConfigFilePath: tsconfigPath });
+  const files = project.getSourceFiles();
+  if (files.length > 0) return files;
+
+  // ---------------------------------------------------------------------------
+  // 2. No source files found → attempt to follow project references
+  // ---------------------------------------------------------------------------
+  const configDir = path.dirname(tsconfigPath);
+  const rawConfig = JSON.parse(fs.readFileSync(tsconfigPath, "utf8"));
+  const references: { path: string }[] = rawConfig.references ?? [];
+
+  if (references.length === 0) return [];
+
+  if (debug) {
+    console.log(
+      pc.dim(" (info)") +
+        pc.gray(" no source files found, following project references"),
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // 3. Load source files from each referenced tsconfig
+  // ---------------------------------------------------------------------------
+  const collected: SourceFile[] = [];
+
+  for (const ref of references) {
+    const refPath = path.resolve(configDir, ref.path);
+
+    // Skip missing referenced tsconfig files
+    if (!fs.existsSync(refPath)) {
+      if (debug) {
+        console.log(
+          pc.dim(" (warn)") +
+            pc.gray(` referenced tsconfig not found: ${refPath}`),
+        );
+      }
+      continue;
+    }
+
+    if (debug) {
+      console.log(
+        pc.dim(" (ref)") + pc.gray(` ${path.relative(process.cwd(), refPath)}`),
+      );
+    }
+
+    const refProject = new Project({ tsConfigFilePath: refPath });
+    collected.push(...refProject.getSourceFiles());
+  }
+
+  return collected;
+}

package/src/core/extract-usages/translator-registry.ts

@@ -0,0 +1,20 @@
+/**
+ * Registry of supported Intor translator factories and methods for static key extraction.
+ */
+
+// Factories
+export const TRANSLATOR_FACTORY = {
+  getTranslator: "getTranslator",
+  useTranslator: "useTranslator",
+} as const;
+export const TRANSLATOR_FACTORIES = Object.values(TRANSLATOR_FACTORY);
+export type TranslatorFactory = (typeof TRANSLATOR_FACTORIES)[number];
+
+// Methods
+export const TRANSLATOR_METHOD = {
+  hasKey: "hasKey",
+  t: "t",
+  tRich: "tRich",
+} as const;
+export const TRANSLATOR_METHODS = Object.values(TRANSLATOR_METHOD);
+export type TranslatorMethod = (typeof TRANSLATOR_METHODS)[number];

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

@@ -0,0 +1,53 @@
+import type {
+  TranslatorFactory,
+  TranslatorMethod,
+} from "./translator-registry";
+
+/** Describes a local translator binding resolved from a factory and method. */
+export interface TranslatorBinding {
+  configKey?: string;
+  factory: TranslatorFactory;
+  method: TranslatorMethod;
+}
+
+/** Map of local binding names to their translator bindings. */
+export type TranslatorBindingMap = Map<string, TranslatorBinding>;
+
+/** Map of local binding names to their resolved preKey context. */
+export type PreKeyMap = Map<string, string>;
+
+interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/** Static translation key usage extracted from a source file. */
+export interface KeyUsage extends TranslatorBinding, SourceLocation {
+  localName: string; // local binding name (e.g. `t`, `hasKey`)
+  key: string;
+  preKey?: string;
+}
+
+/** Static replacement usage extracted from a translation call. */
+export interface ReplacementUsage extends TranslatorBinding, SourceLocation {
+  localName: string;
+  key: string;
+  replacements: string[];
+  preKey?: string;
+}
+
+/** Static rich-tag usage extracted from a rich translation call. */
+export interface RichUsage extends TranslatorBinding, SourceLocation {
+  localName: string;
+  key: string;
+  rich: string[];
+  preKey?: string;
+}
+
+/** Aggregated static translator usages extracted from a project. */
+export interface ExtractedUsages {
+  keys: KeyUsage[];
+  replacements: ReplacementUsage[];
+  rich: RichUsage[];
+}

package/src/core/index.ts

@@ -0,0 +1,13 @@
+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";
+export {
+  readGeneratedSchema,
+  type ReadGeneratedSchemaOptions,
+} from "./read-generated-schema";
+
+export { EXTRA_EXTS, type ExtraExt } from "./constants";

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

@@ -0,0 +1,3 @@
+export { inferSchemas } from "./infer-schemas";
+export type { InferNode, InferredSchemas } from "./types";
+export { buildSchemas } from "../../build/build-schemas/build-schemas";

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

@@ -0,0 +1,16 @@
+import type { InferredSchemas } from "./types";
+import type { MessageObject } from "intor";
+import { inferMessagesSchema } from "./messages";
+import { inferReplacementsSchema } from "./replacements";
+import { inferRichSchema } from "./rich";
+
+/**
+ * Infer all semantic schemas from messages.
+ */
+export function inferSchemas(messages: MessageObject): InferredSchemas {
+  return {
+    messagesSchema: inferMessagesSchema(messages),
+    replacementsSchema: inferReplacementsSchema(messages),
+    richSchema: inferRichSchema(messages),
+  };
+}

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

@@ -0,0 +1 @@
+export { inferMessagesSchema } from "./infer-messages-schema";

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

@@ -0,0 +1,64 @@
+import type { InferNode } from "../types";
+import type { MessageObject, MessageValue } from "intor";
+import { inferObject } from "../utils/infer-object";
+import { isMessageObject } from "../utils/is-message-object";
+
+/**
+ * Infer message value types from a message object.
+ *
+ * Traverses message values and derives a semantic schema tree.
+ * Rendering to TypeScript type string should be done in a later stage.
+ */
+export function inferMessagesSchema(messages: MessageObject): InferNode {
+  if (!isMessageObject(messages) || Object.keys(messages).length === 0) {
+    return { kind: "none" };
+  }
+  return inferValue(messages);
+}
+
+/**
+ * Infer a semantic node from a single message value.
+ *
+ * - Primitive values → primitive node
+ * - Arrays → array node (first-element policy)
+ * - Objects → object node (recursive, empty pruned)
+ * - Unsupported → none
+ */
+function inferValue(value: MessageValue): InferNode {
+  // ----------------------------------------------------------------------
+  // Primitive values
+  // ----------------------------------------------------------------------
+  if (typeof value === "string") return { kind: "primitive", type: "string" };
+  if (typeof value === "number") return { kind: "primitive", type: "number" };
+  if (typeof value === "boolean") return { kind: "primitive", type: "boolean" };
+  if (value === null) return { kind: "primitive", type: "null" };
+
+  // ----------------------------------------------------------------------
+  // Array values
+  // ----------------------------------------------------------------------
+  if (Array.isArray(value)) {
+    // empty array → unknown element
+    if (value.length === 0) {
+      return { kind: "array", element: { kind: "none" } };
+    }
+
+    return { kind: "array", element: inferValue(value[0]) };
+  }
+
+  // ----------------------------------------------------------------------
+  // Object values
+  // ----------------------------------------------------------------------
+  if (isMessageObject(value)) {
+    const result = inferObject(value, inferValue);
+
+    // empty object → fallback record
+    if (result.kind === "none") {
+      return { kind: "record" };
+    }
+
+    return result;
+  }
+
+  // Fallback
+  return { kind: "none" };
+}

package/src/core/infer-schema/replacements/extract-interpolation-names.ts

@@ -0,0 +1,70 @@
+/**
+ * Extract interpolation argument names from a message string.
+ *
+ * Policy:
+ * - Only the outermost `{ ... }` blocks are considered
+ * - Nested `{}` are treated as part of the same block
+ * - For each block, only the identifier before the first `,` is extracted
+ * - Unmatched `{` or `}` are ignored
+ * - No ICU syntax parsing or semantic validation is performed
+ *
+ * This function is syntax-aware but not syntax-validating.
+ *
+ * @example
+ * ```ts
+ * extractInterpolationNames("Hello, {name}.")
+ * // => ["name"]
+ *
+ * extractInterpolationNames(
+ *   "{name} has {count, plural, =0 {no messages} one {1 message} other {# messages}}."
+ * )
+ * // => ["name", "count"]
+ * ```
+ */
+export function extractInterpolationNames(message: string): string[] {
+  const result = new Set<string>();
+
+  let depth = 0;
+  let start = -1;
+
+  for (let i = 0; i < message.length; i++) {
+    const char = message[i];
+
+    if (char === "{") {
+      if (depth === 0) {
+        start = i + 1;
+      }
+      depth++;
+      continue;
+    }
+
+    if (char === "}") {
+      depth--;
+
+      // Unbalanced closing brace → reset state
+      if (depth < 0) {
+        depth = 0;
+        start = -1;
+        continue;
+      }
+
+      if (depth === 0 && start !== -1) {
+        const raw = message.slice(start, i).trim();
+
+        // ICU invariant:
+        // argument name is always the first segment
+        const name = raw.split(",", 1)[0].trim();
+
+        if (name) {
+          result.add(name);
+        }
+
+        start = -1;
+      }
+
+      continue;
+    }
+  }
+
+  return [...result];
+}

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

@@ -0,0 +1 @@
+export { inferReplacementsSchema } from "./infer-replacements-schema";

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

@@ -0,0 +1,63 @@
+import type { InferNode } from "../types";
+import type { MessageObject, MessageValue } from "intor";
+import { inferObject } from "../utils/infer-object";
+import { isMessageObject } from "../utils/is-message-object";
+import { extractInterpolationNames } from "./extract-interpolation-names";
+
+/**
+ * Infer interpolation replacement schema from a message object.
+ *
+ * Traverses message values and extracts `{...}` interpolation names
+ * into a semantic schema tree.
+ */
+export function inferReplacementsSchema(messages: MessageObject): InferNode {
+  if (!isMessageObject(messages) || Object.keys(messages).length === 0) {
+    return { kind: "none" };
+  }
+  return inferValue(messages);
+}
+
+/**
+ * Infer replacement information from a single message value.
+ *
+ * - Strings are scanned for `{...}` interpolations
+ * - Objects are traversed recursively
+ * - Arrays and unsupported values are ignored
+ */
+function inferValue(value: MessageValue): InferNode {
+  // ----------------------------------------------------------------------
+  // String values (replacement source)
+  // ----------------------------------------------------------------------
+  if (typeof value === "string") {
+    const names = extractInterpolationNames(value);
+
+    // No replacements found
+    if (names.length === 0) {
+      return { kind: "none" };
+    }
+
+    const properties: Record<string, InferNode> = {};
+    for (const name of names) {
+      properties[name] = { kind: "primitive", type: "string" };
+    }
+
+    return { kind: "object", properties };
+  }
+
+  // ----------------------------------------------------------------------
+  // Array values (semantically irrelevant for replacements)
+  // ----------------------------------------------------------------------
+  if (Array.isArray(value)) {
+    return { kind: "none" };
+  }
+
+  // ----------------------------------------------------------------------
+  // Object values (delegate aggregation & pruning)
+  // ----------------------------------------------------------------------
+  if (isMessageObject(value)) {
+    return inferObject(value, inferValue);
+  }
+
+  // Fallback
+  return { kind: "none" };
+}

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

@@ -0,0 +1 @@
+export { inferRichSchema } from "./infer-rich-schema";

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

@@ -0,0 +1,66 @@
+import type { InferNode } from "../types";
+import type { MessageObject, MessageValue } from "intor";
+import { tokenize, type Token } from "intor";
+import { inferObject } from "../utils/infer-object";
+import { isMessageObject } from "../utils/is-message-object";
+
+/**
+ * Infer rich tag schema from a message object.
+ *
+ * Traverses message values and extracts rich tag names
+ * into a semantic schema tree.
+ */
+export function inferRichSchema(messages: MessageObject): InferNode {
+  if (!isMessageObject(messages) || Object.keys(messages).length === 0) {
+    return { kind: "none" };
+  }
+  return inferValue(messages);
+}
+
+/**
+ * Infer rich tag information from a single message value.
+ *
+ * - Strings are tokenized and analyzed for rich tags
+ * - Objects are traversed recursively
+ * - Arrays and unsupported values are ignored
+ */
+function inferValue(value: MessageValue): InferNode {
+  // ----------------------------------------------------------------------
+  // String values (rich source)
+  // ----------------------------------------------------------------------
+  if (typeof value === "string") {
+    const tokens: Token[] = tokenize(value);
+
+    // Collect unique rich tag names
+    const properties: Record<string, InferNode> = {};
+
+    for (const token of tokens) {
+      if (token.type !== "tag-open") continue;
+      properties[token.name] = { kind: "none" };
+    }
+
+    // No rich tags found
+    if (Object.keys(properties).length === 0) {
+      return { kind: "none" };
+    }
+
+    return { kind: "object", properties };
+  }
+
+  // ----------------------------------------------------------------------
+  // Array values (semantically irrelevant for rich tags)
+  // ----------------------------------------------------------------------
+  if (Array.isArray(value)) {
+    return { kind: "none" };
+  }
+
+  // ----------------------------------------------------------------------
+  // Object values (delegate aggregation & pruning)
+  // ----------------------------------------------------------------------
+  if (isMessageObject(value)) {
+    return inferObject(value, inferValue);
+  }
+
+  // Fallback
+  return { kind: "none" };
+}