@wads.dev/i18n-editor 0.0.1-alpha.0 → 0.0.1-beta.0

package/README.md

@@ -2,9 +2,9 @@
 
 Local web editor for typed i18n projects.
 
-This first alpha compiles the existing browser editor and its reusable operations from TypeScript, then serves the generated application through a local Fastify server.
+The package compiles the browser editor and its reusable operations from TypeScript, then serves the generated application through a local Fastify server.
 
-> Status: `0.0.1-alpha.0`. The package is under active development and has not been published to npm yet.
+> Status: prerelease. The package is under active development.
 
 ## Wads i18n ecosystem
 
@@ -12,10 +12,13 @@ This first alpha compiles the existing browser editor and its reusable operation
 | --- | --- |
 | [`@wads.dev/i18n-ts`](https://github.com/wads-dev/i18n-ts) | Framework-independent contracts, language loading, project configuration and portable bundles. |
 | [`@wads.dev/i18n-react`](https://github.com/wads-dev/i18n-react) | Optional React Provider, hooks and rich translation rendering. |
+| [`@wads.dev/i18n-html`](https://github.com/wads-dev/i18n-html) | Optional DOM bindings and static HTML translation-reference discovery. |
 | [`@wads.dev/i18n-editor`](https://github.com/wads-dev/i18n-editor) | Local bundle and project editor. This repository. |
 
 The Editor consumes the bundle and `i18n.config.json` formats defined by `i18n-ts`. It is framework-independent: React projects may use `i18n-react`, but the Editor does not require it.
 
+The interface itself uses the `i18n-ts` runtime with a zero-level English and Portuguese catalog. The browser locale selects the initial language, and the explicit choice is persisted locally for future sessions. The runtime bootstrap exposes the selected, deeply frozen tree as the typed global `Lang`, so editor modules access translations without importing the catalog. Static DOM bindings use `@wads.dev/i18n-html`.
+
 ## Development
 
 ```sh
@@ -24,6 +27,15 @@ npm run check
 npm run build
 ```
 
+Run the editor itself in development mode:
+
+```sh
+npm start
+npm start -- --port 4300
+```
+
+The server runs directly from TypeScript with `nodemon` and `tsx`, while a second `nodemon` process runs `build:web` whenever the HTML, CSS or browser TypeScript files change.
+
 Run the generated executable from this repository:
 
 ```sh
@@ -93,9 +105,22 @@ i18n-edit sync --output review.bundle.json
 
 `sync` is equivalent to running `bundle` followed by `export` with the same bundle path. It preserves the export confirmation and accepts `--yes`, `--delete` and `--no-diff` when automation is intentional.
 
+Analyze typed static references to every translation leaf:
+
+```sh
+i18n-edit usage
+i18n-edit usage --json
+i18n-edit usage --refresh
+i18n-edit usage --fail-on-unreferenced
+```
+
+The report separates exact references from uncertain dynamic collection access. Exact entries include reference and file counts plus every source location. `unreferenced` means no static reference or known dynamic access was found; it is a diagnostic and never authorizes automatic deletion. Use `--fail-on-unreferenced` for an opt-in CI check.
+
+Usage analysis is cached per project at `node_modules/.cache/@wads.dev/i18n-editor/usage.json`. The CLI reuses a structurally verified cache and regenerates a missing or unverified one; pass `--refresh` to incorporate source-only changes explicitly. The Web Editor renders the latest cached report immediately on startup. If its translation structure is unverified, the browser keeps that data visible while explicitly requesting a fresh analysis. No-wait cache reads never start analysis on the server.
+
 Each configured `i18n` directory is checked against the generated plan. Generated `base.ts`, language files and the configured root catalog are written; other files become deletion candidates unless their extensions are ignored by project configuration. Set `deletion` to `false` to disable this detection entirely. Files outside configured `i18n` directories are never candidates. Writes are restricted to the selected project directory and use a temporary file followed by an atomic rename.
 
-After the npm package is published, its binaries will be named `i18n-edit` and `i18n-editor`.
+The package binaries are named `i18n-edit` and `i18n-editor`.
 
 The shortest npm invocation will be:
 
@@ -113,4 +138,4 @@ Because the npm package is scoped, `npx i18n-editor` would refer to a different,
 
 ## Current boundary
 
-The server reads project configuration and bundles through `GET /api/project`. It can generate a missing bundle through `POST /api/bundle`; this is currently its only project write. The Web Editor can explicitly request a read-only filesystem comparison through `POST /api/export-preview`. Source regeneration is available explicitly through the CLI `export` command and is not exposed as a browser route yet.
+The server reads project configuration and bundles through `GET /api/project` and can generate a missing bundle through `POST /api/bundle`. The Web Editor requests filesystem comparisons through `POST /api/export-preview`, performs confirmed source regeneration through `POST /api/export`, and reads or refreshes typed usage analysis through `POST /api/usage-analysis`. Project roots and arbitrary output paths cannot be selected by browser requests.

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { Command, InvalidArgumentError } from 'commander';
 import { createServer } from '../server/createServer.js';
 import { applyProjectExport, planProjectExport } from '../server/exportProject.js';
 import { createProjectContext } from '../server/projectContext.js';
+import { analyzeTranslationUsageCached } from '../server/usageAnalysis.js';
 function parsePort(value) {
     const port = Number(value);
     if (!Number.isInteger(port) || port < 0 || port > 65_535) {
@@ -120,6 +121,50 @@ async function exportBundle(command, options) {
     await applyProjectExport(plan, { deleteObsolete });
     console.log(`${writeCount} files written, ${appliedDeletionCount} deleted.`);
 }
+function printUsageReport(report) {
+    Object.entries(report.entries).forEach(([key, usage]) => {
+        const status = usage.status === 'used'
+            ? colorize('used        ', 'green')
+            : usage.status === 'uncertain'
+                ? colorize('uncertain   ', 'yellow')
+                : colorize('unreferenced', 'red');
+        console.log(`${status}  ${String(usage.referenceCount).padStart(3)} refs  ${String(usage.fileCount).padStart(3)} files  ${key}`);
+        usage.references.forEach((reference) => {
+            console.log(`                ${reference.file}:${reference.line}:${reference.column}`);
+        });
+        if (usage.status === 'uncertain')
+            usage.uncertainReferences.forEach((reference) => {
+                console.log(`                ? ${reference.file}:${reference.line}:${reference.column}`);
+            });
+    });
+    const values = Object.values(report.entries);
+    const used = values.filter(({ status }) => status === 'used').length;
+    const uncertain = values.filter(({ status }) => status === 'uncertain').length;
+    const unreferenced = values.filter(({ status }) => status === 'unreferenced').length;
+    console.log(`\n${values.length} keys analyzed across ${report.sourceFileCount} source files: ${used} used, ${uncertain} uncertain, ${unreferenced} unreferenced.`);
+}
+async function analyzeUsage(command, options) {
+    const projectOptions = getProjectOptions(command, options.file);
+    const project = createProjectContext(projectOptions);
+    const info = await project.getInfo();
+    if (!info.config)
+        throw new Error('Could not find i18n.config.json. Pass --config with the project configuration path.');
+    if (!info.bundle)
+        throw new Error(`Could not find the bundle at ${info.bundlePath}. Run the bundle command first or pass --file.`);
+    const report = await analyzeTranslationUsageCached({
+        projectDirectory: project.projectDirectory,
+        bundle: info.bundle,
+        config: info.config,
+    }, options.refresh === true);
+    if (options.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        printUsageReport(report);
+    if (options.failOnUnreferenced
+        && Object.values(report.entries).some(({ status }) => status === 'unreferenced')) {
+        process.exitCode = 1;
+    }
+}
 function createProgram() {
     const packageJson = createRequire(import.meta.url)('../../package.json');
     const program = new Command();
@@ -180,6 +225,16 @@ function createProgram() {
         await generateBundle(command, options.output);
         await exportBundle(command, { ...options, file: options.output });
     });
+    program
+        .command('usage')
+        .description('analyze static references to every translation key')
+        .option('-f, --file <path>', 'input bundle path', 'i18n.bundle.json')
+        .option('--json', 'print the usage report as JSON')
+        .option('--refresh', 'ignore the disk cache and rebuild the usage report')
+        .option('--fail-on-unreferenced', 'exit with code 1 when a key has no static references')
+        .action(async (options, command) => {
+        await analyzeUsage(command, options);
+    });
     return program;
 }
 try {

package/dist/core/keyPath.js

@@ -31,16 +31,30 @@ export function getKeyPathValue(root, segments) {
     return { found: true, value: current };
 }
 export function deleteKeyPathValue(root, segments) {
-    const parentPath = segments.slice(0, -1);
-    const property = segments.at(-1);
+    const containers = [];
     let parent = root;
-    for (const segment of parentPath) {
+    for (const segment of segments.slice(0, -1)) {
+        containers.push({ container: parent, segment });
         const nested = asRecord(parent)[segment];
         if (!isContainer(nested))
             throw new Error(`The key path is invalid at ${String(segment)}.`);
         parent = nested;
     }
-    delete asRecord(parent)[property];
+    const property = segments.at(-1);
+    if (Array.isArray(parent) && typeof property === 'number')
+        parent.splice(property, 1);
+    else
+        delete asRecord(parent)[property];
+    for (let index = containers.length - 1; index >= 0; index -= 1) {
+        const { container, segment } = containers[index];
+        const child = asRecord(container)[segment];
+        if (!isContainer(child) || Object.keys(child).length > 0)
+            break;
+        if (Array.isArray(container) && typeof segment === 'number')
+            container.splice(segment, 1);
+        else
+            delete asRecord(container)[segment];
+    }
 }
 export function setKeyPathValue(root, segments, value) {
     const property = segments.at(-1);

package/dist/core/projectApi.d.ts

@@ -17,6 +17,9 @@ export type ProjectExportPreviewRequest = {
     bundle: I18nBundle;
     config: EditorProjectConfig;
 };
+export type ProjectExportRequest = ProjectExportPreviewRequest & {
+    deleteObsolete?: boolean;
+};
 export type ProjectExportPreviewChange = {
     kind: 'base' | 'index' | 'language' | 'obsolete';
     path: string;
@@ -26,6 +29,36 @@ export type ProjectExportPreviewChange = {
 export type ProjectExportPreviewResult = {
     changes: ProjectExportPreviewChange[];
 };
+export type ProjectExportResult = ProjectExportPreviewResult & {
+    written: number;
+    deleted: number;
+    preserved: number;
+};
+export type TranslationUsageReference = {
+    file: string;
+    line: number;
+    column: number;
+};
+export type TranslationUsageEntry = {
+    status: 'used' | 'unreferenced' | 'uncertain';
+    referenceCount: number;
+    uncertainReferenceCount: number;
+    fileCount: number;
+    references: TranslationUsageReference[];
+    uncertainReferences: TranslationUsageReference[];
+};
+export type TranslationUsageReport = {
+    analyzedAt: number;
+    sourceFileCount: number;
+    entries: Record<string, TranslationUsageEntry>;
+};
+export type TranslationUsageRequest = ProjectExportPreviewRequest & {
+    wait?: boolean;
+};
+export type TranslationUsageResponse = {
+    cacheStatus: 'missing' | 'verified' | 'unverified';
+    report: TranslationUsageReport | null;
+};
 export type ApiError = {
     error: string;
 };

package/dist/core/removeKey.d.ts

@@ -0,0 +1,5 @@
+import { type I18nBundle } from '@wads.dev/i18n-ts/bundle';
+export type RemoveKeyOptions = {
+    key: string;
+};
+export declare function removeKey(bundle: I18nBundle, { key }: RemoveKeyOptions): I18nBundle;

package/dist/core/removeKey.js

@@ -0,0 +1,16 @@
+import { assertBundle } from '@wads.dev/i18n-ts/bundle';
+import { deleteKeyPathValue, getKeyPathValue, parseKeyPath } from './keyPath.js';
+export function removeKey(bundle, { key }) {
+    const validBundle = assertBundle(bundle);
+    const segments = parseKeyPath(key, 'key');
+    Object.entries(validBundle.languages).forEach(([languageKey, language]) => {
+        if (!getKeyPathValue(language.translations, segments).found) {
+            throw new Error(`Key "${key}" does not exist in language "${languageKey}".`);
+        }
+    });
+    const nextBundle = structuredClone(validBundle);
+    Object.values(nextBundle.languages).forEach((language) => {
+        deleteKeyPathValue(language.translations, segments);
+    });
+    return nextBundle;
+}