@urbicon-ui/i18n 6.3.7 → 6.3.9

package/dist/audit/scan/svelte-walker.js

@@ -0,0 +1,208 @@
+/**
+ * Svelte usage walker. `svelte/compiler.parse` (lazily imported) yields one AST
+ * whose Root holds the module/instance scripts (estree) *and* the template, so a
+ * single iterative walk reaches every translate call — script-level and inside
+ * markup expressions — with original-source offsets for accurate line numbers.
+ *
+ * On top of the estree handling (mirroring the TypeScript walker) it understands
+ * the `<T key="…">` component, the markup form of a translation render-call.
+ */
+import { createBindings, createScan, isFactoryName, isKeyMethod, isProbeMethod, isRenderMethod, makeContextAt, makeLineAt, recordKeyCall } from './recognize.js';
+import { asNode, asNodes, asString, cookedOf, loadParse, walkAst } from './svelte-ast.js';
+/** Peel `as`/`!`/`satisfies` (TS nodes present when `lang="ts"`) off an expression. */
+function unwrap(node) {
+    let current = node;
+    while (current &&
+        /^TS\w+(Expression|Assertion)$/.test(current.type) &&
+        asNode(current.expression)) {
+        current = asNode(current.expression);
+    }
+    return current;
+}
+function extractFromArg(raw) {
+    const node = unwrap(raw);
+    if (!node)
+        return [{ kind: 'opaque' }];
+    if (node.type === 'Literal') {
+        const value = asString(node.value);
+        return value !== undefined ? [{ kind: 'static', value }] : [{ kind: 'opaque' }];
+    }
+    if (node.type === 'TemplateLiteral') {
+        const head = cookedOf(asNodes(node.quasis)[0]) ?? '';
+        if (asNodes(node.expressions).length === 0)
+            return [{ kind: 'static', value: head }];
+        return head ? [{ kind: 'prefix', prefix: head }] : [{ kind: 'opaque' }];
+    }
+    if (node.type === 'ConditionalExpression') {
+        return [...extractFromArg(asNode(node.consequent)), ...extractFromArg(asNode(node.alternate))];
+    }
+    if (node.type === 'BinaryExpression' && node.operator === '+') {
+        const left = unwrap(asNode(node.left));
+        const value = left?.type === 'Literal' ? asString(left.value) : undefined;
+        // An empty static part (`'' + x`) is no prefix — `''` would shield every key.
+        return value ? [{ kind: 'prefix', prefix: value }] : [{ kind: 'opaque' }];
+    }
+    return [{ kind: 'opaque' }];
+}
+/** The rightmost callee name of a call (`x.useTranslate()` → `useTranslate`). */
+function calleeName(call) {
+    const callee = asNode(call.callee);
+    if (!callee)
+        return undefined;
+    if (callee.type === 'Identifier')
+        return asString(callee.name);
+    if (callee.type === 'MemberExpression' && callee.computed !== true) {
+        return asString(asNode(callee.property)?.name);
+    }
+    return undefined;
+}
+function factoryCallName(node) {
+    if (node?.type !== 'CallExpression')
+        return undefined;
+    const name = calleeName(node);
+    return name && isFactoryName(name) ? name : undefined;
+}
+function bindDeclarator(node, bindings) {
+    const init = asNode(node.init);
+    if (!init)
+        return;
+    const id = asNode(node.id);
+    if (factoryCallName(init)) {
+        if (id?.type === 'Identifier') {
+            const name = asString(id.name);
+            if (name)
+                bindings.render.add(name);
+        }
+        else if (id?.type === 'ObjectPattern') {
+            for (const prop of asNodes(id.properties)) {
+                if (prop.type !== 'Property')
+                    continue;
+                const method = asString(asNode(prop.key)?.name);
+                const local = asString(asNode(prop.value)?.name);
+                if (!method || !local)
+                    continue;
+                if (isProbeMethod(method))
+                    bindings.probe.add(local);
+                else if (isRenderMethod(method))
+                    bindings.render.add(local);
+            }
+        }
+        return;
+    }
+    // `const t = useI18n().t`
+    if (init.type === 'MemberExpression' && init.computed !== true && id?.type === 'Identifier') {
+        const method = asString(asNode(init.property)?.name);
+        const local = asString(id.name);
+        if (method && local && isKeyMethod(method) && factoryCallName(asNode(init.object))) {
+            if (isProbeMethod(method))
+                bindings.probe.add(local);
+            else
+                bindings.render.add(local);
+        }
+    }
+}
+function classifyCall(call, bindings) {
+    const callee = asNode(call.callee);
+    if (!callee)
+        return null;
+    if (callee.type === 'Identifier') {
+        const name = asString(callee.name);
+        if (!name)
+            return null;
+        if (bindings.render.has(name))
+            return { isProbe: false };
+        if (bindings.probe.has(name))
+            return { isProbe: true };
+        return null;
+    }
+    if (callee.type === 'MemberExpression' && callee.computed !== true) {
+        const name = asString(asNode(callee.property)?.name);
+        if (name && isRenderMethod(name))
+            return { isProbe: false };
+        if (name && isProbeMethod(name))
+            return { isProbe: true };
+    }
+    return null;
+}
+/** Resolve the key of a `<T key="…">` / `<T key={'…'}>` component usage. */
+function extractTComponentKey(component) {
+    const keyAttr = asNodes(component.attributes).find((attr) => attr.type === 'Attribute' && asString(attr.name) === 'key');
+    if (!keyAttr)
+        return [];
+    const values = Array.isArray(keyAttr.value)
+        ? asNodes(keyAttr.value)
+        : asNode(keyAttr.value)
+            ? [asNode(keyAttr.value)]
+            : [];
+    const out = [];
+    for (const value of values) {
+        if (value.type === 'Text') {
+            const text = asString(value.data);
+            if (text !== undefined)
+                out.push({ kind: 'static', value: text });
+        }
+        else if (value.type === 'ExpressionTag') {
+            out.push(...extractFromArg(asNode(value.expression)));
+        }
+    }
+    return out;
+}
+export async function scanSvelte(code, file, options = {}) {
+    const parse = await loadParse();
+    const ast = parse(code, { modern: true });
+    const bindings = createBindings(options.functionNames);
+    const lineAt = makeLineAt(code);
+    const contextAt = makeContextAt(code);
+    const siteAt = (offset) => {
+        const line = lineAt(offset ?? 0);
+        return { file, line, context: contextAt(line) };
+    };
+    // Pass 1 — bindings.
+    walkAst(ast, (node) => {
+        if (node.type === 'VariableDeclarator')
+            bindDeclarator(node, bindings);
+    });
+    // Pass 2 — usage + literal harvest.
+    const scan = createScan();
+    walkAst(ast, (node) => {
+        if (node.type === 'Literal') {
+            const value = asString(node.value);
+            if (value !== undefined)
+                scan.literalPool.add(value);
+        }
+        else if (node.type === 'Text') {
+            // Plain markup text and quoted attribute values (`<Foo labelKey="user.name"/>`,
+            // `<code>a.b.c</code>`) are Text, not Literal nodes — harvest for the loose layer.
+            const text = asString(node.data)?.trim();
+            if (text)
+                scan.literalPool.add(text);
+        }
+        else if (node.type === 'TemplateLiteral') {
+            const quasis = asNodes(node.quasis);
+            if (asNodes(node.expressions).length === 0) {
+                const cooked = cookedOf(quasis[0]);
+                if (cooked !== undefined)
+                    scan.literalPool.add(cooked);
+            }
+            else {
+                // Static head of any template literal → a dynamic prefix, so config-built
+                // keys (`col.${id}.label`) rendered elsewhere are shielded from "unused".
+                const head = cookedOf(quasis[0]);
+                if (head)
+                    scan.dynamicPrefixes.push({ prefix: head, site: siteAt(node.start) });
+            }
+        }
+        else if (node.type === 'CallExpression') {
+            const classification = classifyCall(node, bindings);
+            if (classification) {
+                const args = asNodes(node.arguments);
+                const extractions = args.length > 0 ? extractFromArg(args[0]) : [];
+                recordKeyCall(scan, extractions, siteAt(node.start), classification.isProbe);
+            }
+        }
+        else if (node.type === 'Component' && asString(node.name) === 'T') {
+            recordKeyCall(scan, extractTComponentKey(node), siteAt(node.start), false);
+        }
+    });
+    return scan;
+}

package/dist/audit/scan/ts-walker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TypeScript/JavaScript usage walker. Uses the TypeScript compiler API (the repo
+ * precedent — docs-gen extracts props the same way), lazily imported so the
+ * dependency never touches the i18n runtime entry, only `@urbicon-ui/i18n/audit`.
+ *
+ * Two passes: collect the file-local translate-function bindings (B1), then walk
+ * calls + string literals (B2), emitting into a {@link UsageScan}.
+ */
+import type { ScanOptions, UsageScan } from './types.js';
+export declare function scanTs(code: string, file: string, options?: ScanOptions): Promise<UsageScan>;

package/dist/audit/scan/ts-walker.js

@@ -0,0 +1,183 @@
+/**
+ * TypeScript/JavaScript usage walker. Uses the TypeScript compiler API (the repo
+ * precedent — docs-gen extracts props the same way), lazily imported so the
+ * dependency never touches the i18n runtime entry, only `@urbicon-ui/i18n/audit`.
+ *
+ * Two passes: collect the file-local translate-function bindings (B1), then walk
+ * calls + string literals (B2), emitting into a {@link UsageScan}.
+ */
+import { createBindings, createScan, isFactoryName, isKeyMethod, isProbeMethod, isRenderMethod, makeContextAt, recordKeyCall } from './recognize.js';
+let tsPromise;
+async function loadTs() {
+    if (!tsPromise) {
+        tsPromise = (async () => {
+            let mod;
+            try {
+                mod = await import('typescript');
+            }
+            catch {
+                throw new Error('@urbicon-ui/i18n/audit needs the optional peer "typescript" to scan .ts/.js sources — install it (it ships with any SvelteKit/TS project).');
+            }
+            // typescript ships CJS; interop puts the namespace on `.default` or spreads it.
+            const candidate = mod;
+            return typeof candidate.createSourceFile === 'function'
+                ? candidate
+                : candidate.default;
+        })();
+    }
+    return tsPromise;
+}
+function scriptKindFor(ts, file) {
+    if (file.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    if (file.endsWith('.jsx'))
+        return ts.ScriptKind.JSX;
+    if (/\.(m|c)?js$/.test(file))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+function calleeName(ts, expr) {
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr))
+        return expr.name.text;
+    return undefined;
+}
+/** The factory-hook name when `node` is a call to one (`useTableI18n()` → `useTableI18n`). */
+function factoryCallName(ts, node) {
+    if (!ts.isCallExpression(node))
+        return undefined;
+    const name = calleeName(ts, node.expression);
+    return name && isFactoryName(name) ? name : undefined;
+}
+function bindDeclarationName(ts, name, bindings) {
+    if (ts.isIdentifier(name)) {
+        // `const bt = useTableI18n()` — the alias is a translate function.
+        bindings.render.add(name.text);
+        return;
+    }
+    if (ts.isObjectBindingPattern(name)) {
+        // `const { t, exists } = useI18n()` — only the known methods are key-calls.
+        for (const element of name.elements) {
+            const source = element.propertyName ?? element.name;
+            const method = ts.isIdentifier(source) ? source.text : undefined;
+            const local = ts.isIdentifier(element.name) ? element.name.text : undefined;
+            if (!method || !local)
+                continue;
+            if (isProbeMethod(method))
+                bindings.probe.add(local);
+            else if (isRenderMethod(method))
+                bindings.render.add(local);
+        }
+    }
+}
+function collectBindings(ts, sf, bindings) {
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) && node.initializer) {
+            const init = node.initializer;
+            if (factoryCallName(ts, init)) {
+                bindDeclarationName(ts, node.name, bindings);
+            }
+            else if (ts.isPropertyAccessExpression(init) &&
+                isKeyMethod(init.name.text) &&
+                factoryCallName(ts, init.expression) &&
+                ts.isIdentifier(node.name)) {
+                // `const t = useI18n().t`
+                if (isProbeMethod(init.name.text))
+                    bindings.probe.add(node.name.text);
+                else
+                    bindings.render.add(node.name.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+}
+function unwrap(ts, node) {
+    let current = node;
+    for (;;) {
+        // Per-guard so TypeScript narrows `current` to a node that has `.expression`.
+        if (ts.isParenthesizedExpression(current))
+            current = current.expression;
+        else if (ts.isAsExpression(current))
+            current = current.expression;
+        else if (ts.isNonNullExpression(current))
+            current = current.expression;
+        else if (ts.isSatisfiesExpression(current))
+            current = current.expression;
+        else
+            return current;
+    }
+}
+function extractFromArg(ts, raw) {
+    const node = unwrap(ts, raw);
+    if (ts.isStringLiteralLike(node))
+        return [{ kind: 'static', value: node.text }];
+    if (ts.isTemplateExpression(node)) {
+        // `` `filter.op.${x}` `` → prefix `filter.op.`; an empty head is unresolvable.
+        return node.head.text ? [{ kind: 'prefix', prefix: node.head.text }] : [{ kind: 'opaque' }];
+    }
+    if (ts.isConditionalExpression(node)) {
+        return [...extractFromArg(ts, node.whenTrue), ...extractFromArg(ts, node.whenFalse)];
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const left = unwrap(ts, node.left);
+        // An empty static part (`'' + x`) is no prefix — `''` would shield every key.
+        if (ts.isStringLiteralLike(left) && left.text)
+            return [{ kind: 'prefix', prefix: left.text }];
+        return [{ kind: 'opaque' }];
+    }
+    return [{ kind: 'opaque' }];
+}
+function classifyCall(ts, bindings, call) {
+    const callee = call.expression;
+    if (ts.isIdentifier(callee)) {
+        if (bindings.render.has(callee.text))
+            return { isProbe: false };
+        if (bindings.probe.has(callee.text))
+            return { isProbe: true };
+        return null;
+    }
+    if (ts.isPropertyAccessExpression(callee)) {
+        const name = callee.name.text;
+        if (isRenderMethod(name))
+            return { isProbe: false };
+        if (isProbeMethod(name))
+            return { isProbe: true };
+    }
+    return null;
+}
+export async function scanTs(code, file, options = {}) {
+    const ts = await loadTs();
+    const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true, scriptKindFor(ts, file));
+    const bindings = createBindings(options.functionNames);
+    collectBindings(ts, sf, bindings);
+    const scan = createScan();
+    const contextAt = makeContextAt(code);
+    const visit = (node) => {
+        if (ts.isStringLiteralLike(node))
+            scan.literalPool.add(node.text);
+        // Harvest the static head of EVERY template literal (not only those in a t()
+        // call) as a dynamic prefix — keys built in a config (`col.${id}.label`) and
+        // rendered elsewhere are then shielded from the unused list.
+        if (ts.isTemplateExpression(node) && node.head.text) {
+            const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+            scan.dynamicPrefixes.push({
+                prefix: node.head.text,
+                site: { file, line, context: contextAt(line) }
+            });
+        }
+        if (ts.isCallExpression(node)) {
+            const classification = classifyCall(ts, bindings, node);
+            if (classification) {
+                const arg = node.arguments[0];
+                const extractions = arg ? extractFromArg(ts, arg) : [];
+                const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+                recordKeyCall(scan, extractions, { file, line, context: contextAt(line) }, classification.isProbe);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+    return scan;
+}

package/dist/audit/scan/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared types for the usage scanner (Feature B/C of the i18n audit).
+ *
+ * A scan walks source files for translation-key *usage* — every way a key is
+ * referenced — so the reconciler can decide which defined keys are unused. The
+ * shapes here are AST-agnostic: the TypeScript walker and the Svelte walker both
+ * emit into a {@link UsageScan}.
+ */
+export interface KeyUsageSite {
+    /** Source file (as passed to the scanner — the caller decides absolute vs relative). */
+    file: string;
+    /** 1-based line of the call/usage. */
+    line: number;
+    /** Trimmed source line, for human-readable reports. */
+    context: string;
+}
+export interface UsageScan {
+    /** Static literal keys in render calls (`t`/`plural`/`translate`, `<T key>`), with their sites. */
+    staticKeys: Map<string, KeyUsageSite[]>;
+    /** Keys seen only in `exists()` probes — they count as *used* but are excluded from used-but-undefined. */
+    probeKeys: Set<string>;
+    /** Static prefixes from template-literal keys, e.g. `` `filter.op.${x}` `` → `filter.op.` (trailing dot kept). */
+    dynamicPrefixes: Array<{
+        prefix: string;
+        site: KeyUsageSite;
+    }>;
+    /** Translation calls whose key could not be resolved statically (`t(variable)`). */
+    opaqueSites: KeyUsageSite[];
+    /** Every string literal seen anywhere — the loose-literal harvest layer. */
+    literalPool: Set<string>;
+}
+export interface ScanOptions {
+    /** Extra bare-identifier names to treat as translation render-calls (the escape hatch). */
+    functionNames?: string[];
+}
+/**
+ * The classification of a translation call's first argument. A ternary expands to
+ * several; an unresolvable argument yields `opaque`.
+ */
+export type ExtractedKey = {
+    kind: 'static';
+    value: string;
+} | {
+    kind: 'prefix';
+    prefix: string;
+} | {
+    kind: 'opaque';
+};

package/dist/audit/scan/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the usage scanner (Feature B/C of the i18n audit).
+ *
+ * A scan walks source files for translation-key *usage* — every way a key is
+ * referenced — so the reconciler can decide which defined keys are unused. The
+ * shapes here are AST-agnostic: the TypeScript walker and the Svelte walker both
+ * emit into a {@link UsageScan}.
+ */
+export {};

package/dist/audit/translations.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `auditTranslations` — data-level translation quality & parity audit.
+ *
+ * The richer successor to {@link validatePackageTranslations}: a pure function
+ * over a package's locale bundles (no source scan, no I/O, deterministic, zero
+ * false positives) that reports structured findings instead of opaque strings.
+ *
+ * Consumers run it in a vitest test to fail CI on drift —
+ * `expect(auditTranslations('app', bundles).ok).toBe(true)` — or via the
+ * `urbicon i18n parity` CLI, which formats the same findings. Key parity is the
+ * baseline (missing/extra keys); on top of it sit the checks a structural diff
+ * can't see: empty values, interpolation-param drift between locales, malformed
+ * or CLDR-incomplete `_plural` objects, placeholder leftovers, and (opt-in)
+ * not-yet-translated strings identical to the base locale.
+ */
+import { type Locale } from '../i18n/types.js';
+/** A single audit check. Stable identifiers — safe to switch on in tooling/CI. */
+export type TranslationFindingCode = 'missing-key' | 'extra-key' | 'empty-value' | 'wrong-type' | 'param-mismatch' | 'plural-shape-invalid' | 'plural-category-incomplete' | 'value-equals-key' | 'same-as-base' | 'invalid-locale' | 'no-translations';
+export type TranslationFindingSeverity = 'error' | 'warning';
+export interface TranslationFinding {
+    /** Which check produced this finding. */
+    code: TranslationFindingCode;
+    severity: TranslationFindingSeverity;
+    /** The locale the finding belongs to (the base locale for base-only checks). */
+    locale: Locale;
+    /** Dotted leaf-key path, e.g. `dialog.close`. Empty for whole-bundle findings. */
+    key: string;
+    /** Human-readable message, prefixed with `[packageName]`. */
+    detail: string;
+}
+export interface AuditTranslationsOptions {
+    /** Base locale every other locale is diffed against. Default: `en` if present, else the first. */
+    baseLocale?: Locale;
+    /**
+     * Per-check toggles. Unlisted checks keep their default — all on EXCEPT
+     * `same-as-base`, which is FP-prone (brand names, "OK", shared tokens) and
+     * opt-in. `missing-key` cannot be disabled (it is the parity floor).
+     */
+    checks?: Partial<Record<TranslationFindingCode, boolean>>;
+    /** Leaf-key paths to skip across all checks. Exact, or a `prefix.*` glob. */
+    ignoreKeys?: string[];
+}
+export interface TranslationAuditReport {
+    /** True when there are no `error`-severity findings (warnings do not fail). */
+    ok: boolean;
+    /** All findings, sorted deterministically by locale → key → code. */
+    findings: TranslationFinding[];
+    /** The `error` subset, for a quick `expect(report.errors).toEqual([])`. */
+    errors: TranslationFinding[];
+    /** The `warning` subset. */
+    warnings: TranslationFinding[];
+}
+/**
+ * Audit a package's locale bundles for parity and translation-quality issues.
+ *
+ * @param packageName Used only to prefix `detail` messages (e.g. `[blocks]`).
+ * @param translations Per-locale bundles, exactly as passed to `createPackageI18n`.
+ */
+export declare function auditTranslations(packageName: string, translations: Partial<Record<Locale, Record<string, unknown>>>, options?: AuditTranslationsOptions): TranslationAuditReport;