gt 0.10.0 → 2.7.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2025 General Translation, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,211 +1,39 @@
-# gt
-
-> JavaScript native QUnit runner with code coverage and multiple extensions
-
-[![NPM][gt-icon] ][gt-url]
-
-[![Build status][gt-ci-image] ][gt-ci-url]
-[![Coverage Status][gt-coverage-image] ][gt-coverage-url]
-[![dependencies][gt-dependencies-image] ][gt-dependencies-url]
-[![devdependencies][gt-devdependencies-image] ][gt-devdependencies-url]
-
-[gt-icon]: https://nodei.co/npm/gt.png?downloads=true
-[gt-url]: https://npmjs.org/package/gt
-[gt-ci-image]: https://travis-ci.org/bahmutov/gt.png?branch=master
-[gt-ci-url]: https://travis-ci.org/bahmutov/gt
-[gt-coverage-image]: https://coveralls.io/repos/bahmutov/gt/badge.png
-[gt-coverage-url]: https://coveralls.io/r/bahmutov/gt
-[gt-dependencies-image]: https://david-dm.org/bahmutov/gt.png
-[gt-dependencies-url]: https://david-dm.org/bahmutov/gt
-[gt-devdependencies-image]: https://david-dm.org/bahmutov/gt/dev-status.png
-[gt-devdependencies-url]: https://david-dm.org/bahmutov/gt#info=devDependencies
-
-
-
-## Install and run
-
-**gt** requires *nodejs* and a few modules to run. Assuming you wrote a few qunit tests in tests.js:
-
-```sh
-sudo npm install -g gt
-gt tests.js
-
-some of the options (-h for all):
-  -l <debug level> 0 = debug, 1 = default, 2 = warnings, 3 = errors
-  -r <report level> 0 = all (default), 1 = failed tests only
-```
-
-
-## Goals
-
-1. Make sure QUnit tests work with [istanbul](https://github.com/gotwarlost/istanbul "Istanbul at GitHub") JS coverage tool
-2. Experiment with JS unit testing by writing a framework from scratch.
-
-### Example
-
-A simple example is in [examples subfolder](gt/tree/master/examples/basic "gt Examples")
-
-Unit tests follow QUnit approach:
+<p align="center">
+  <a href="https://generaltranslation.com/docs/cli">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://generaltranslation.com/gt-logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://generaltranslation.com/gt-logo-light.svg">
+      <img alt="General Translation" src="https://generaltranslation.com/gt-logo-light.svg" width="100" height="100">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://generaltranslation.com/docs/cli"><strong>Documentation</strong></a> · <a href="https://github.com/generaltranslation/gt/issues">Report Bug</a>
+</p>
 
-```javascript
-gt.module("Basic tests");
-
-gt.test("get N '='", function () {
-	gt.ok(typeof getLines === "function", "getLines is a function");
-	gt.equal(getLines(0), "", "0 character");
-	gt.equal(getLines(1), "=", "1 character");
-});
-```
-
-Creates unit test report (stdout only) and JS code coverage (stdout plus Lines of Code + HTML in folder cover)
-
-	gt ./examples/basic/tests ./examples/basic/exceptionTests
-
-Sample unit test output [image](gt/blob/master/examples/example.png "Console screenshot")
-
-Sample JS coverage output [image](gt/blob/master/examples/coverage.png "Coverage page screenshot")
-
-### CoffeeScript support
-
-You can write your unit tests using [coffeescript](http://coffeescript.org/), which allows very concise code.
-So far, the code coverage does not include the unit test files themselves, they will be omitted from the coverage report.
-See *examples/coffee* folder.
-
-### Running in browser
-
-See example **examples/browser**
-
-### BDD support
-
-gt provides minimal BDD support and can run Mocha/Jasmine specs that have `describe` and `it` calls.
-See [spec example](examples/bdd/spec.js). You can run it using `gt --bdd spec.js` command.
-
-## API
-
-### module
-
-Creates new suite of tests with given name
+# gt
 
-```js
-gt.module('math tests');
-```
+Command-line tool for General Translation's i18n platform.
 
-You can specify additional functions to run before / after
-each unit tests. You can also specify a function to run once
-before any tests, and after all tests.
+## Installation
 
-```js
-gt.module('server tests', {
-    setupOnce: function () {
-        // setup server
-    },
-    setup: function () {
-        // clear data before each unit test
-    },
-    teardown: function () {
-        // clean up after each unit test
-    },
-    teardownOnce: function () {
-        // stop server
-    }
-});
+```bash
+npm install gt --save-dev
 ```
 
-See [module tests](examples/moduleSetupTeardown/test.js) for more information and examples.
-
-A very convenient feature: each method can return a promise object
-to tell the test engine when it is done. See [example](examples/async/asyncSetup.js)
+## Quick Start
 
+Set up your project:
 
-
-### exec
-
-Spawns new proces, waits for it to finish, then
-checks the exit code. Automatically restarts the test queue
-
-**Checking just the exit code**
-
-```js
-gt.async('run Nodejs program', function () {
-  gt.exec('node', ['index.js', 'arg1', 'arg2'], 0,
-    'expect "node index.js arg1 arg2" to exit with code 0');
-});
+```bash
+npx gt init
 ```
 
-**Checking the exit code and the output**
-
-```js
-gt.async('run a program', function () {
-  gt.exec('node', ['index.js', 'arg1', 'arg2'], 0,
-    function (stdout, stderr) {
-      if (/error/.test(stdout)) {
-        throw new Error('Errors in output ' + stdout);
-      }
-    });
-});
-```
-
-Full [exec unit test](examples/exec/tests.js)
-
-**shortcuts:**
-
-```js
-gt.exec(cmd, [...], 'msg');
-// same as
-gt.exec(cmd, [...], 0, 'msg');
+Generate translations:
 
-gt.exec(cmd, 'msg');
-// same as
-gt.exec(cmd, [], 0, msg);
-
-gt.exec(cmd);
-// same as
-gt.exec(cmd, [], 0);
+```bash
+npx gt translate
 ```
 
-
-
-### gt.equiv
-
-Performs deep equality comparison between two objects.
-
-
-
-
-
-
-
-## command line options
-
-### --no-cover part-of-path
-
-gt excludes certain common paths from coverage,
-speeding up the test runs: node_modules, bower_components, etc.
-You can add paths to this list, for example to exclude all files
-loaded from `vendor` folders:
-
-    gt --no-cover vendor src/*.js tests/*.js
-
-The option is used as case insensitive regular expression.
-
-
-
-### Small print
-
-Author: Gleb Bahmutov &copy; 2014
-
-* [@bahmutov](https://twitter.com/bahmutov)
-* [glebbahmutov.com](http://glebbahmutov.com)
-* [blog](http://bahmutov.calepin.co/)
-
-License: [MIT](MIT-License.txt) - do anything with the code, but don't blame me if it does not work.
-
-Spread the word: tweet, star on github, etc.
-
-Support: if you find any problems with this module, email / tweet /
-[open issue](https://github.com/bahmutov/gt/issues) on Github.
-
-
-
-[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/bahmutov/gt/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
-
+See the [full documentation](https://generaltranslation.com/docs/cli) for guides and API reference.

package/dist/api/collectUserEditDiffs.d.ts

@@ -0,0 +1,9 @@
+import { Settings } from '../types/index.js';
+import { FileReference } from 'generaltranslation/types';
+/**
+ * Collects local user edits by diffing the latest downloaded server translation version
+ * against the current local translation file, and submits the diffs upstream.
+ *
+ * Must run before enqueueing new translations so rules are available to the generator.
+ */
+export declare function collectAndSendUserEditDiffs(files: FileReference[], settings: Settings): Promise<void>;

package/dist/api/collectUserEditDiffs.js

@@ -0,0 +1,159 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getDownloadedVersions } from '../fs/config/downloadedVersions.js';
+import { createFileMapping } from '../formats/files/fileMapping.js';
+import { getGitUnifiedDiff } from '../utils/gitDiff.js';
+import { gt } from '../utils/gt.js';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { hashStringSync } from '../utils/hash.js';
+import { extractJson } from '../formats/json/extractJson.js';
+const findLatestDownloadedVersion = (downloadedVersions, branchId, fileId, locale) => {
+    const versionsForFile = downloadedVersions.entries?.[branchId]?.[fileId] ?? undefined;
+    if (!versionsForFile)
+        return null;
+    let latest = null;
+    for (const [versionId, locales] of Object.entries(versionsForFile)) {
+        const entry = locales?.[locale];
+        if (!entry)
+            continue;
+        const updatedAt = entry.updatedAt
+            ? Date.parse(entry.updatedAt)
+            : Number.NEGATIVE_INFINITY;
+        const latestUpdatedAt = latest?.entry.updatedAt
+            ? Date.parse(latest.entry.updatedAt)
+            : Number.NEGATIVE_INFINITY;
+        if (!latest || updatedAt > latestUpdatedAt) {
+            latest = { versionId, entry };
+        }
+    }
+    return latest;
+};
+/**
+ * Collects local user edits by diffing the latest downloaded server translation version
+ * against the current local translation file, and submits the diffs upstream.
+ *
+ * Must run before enqueueing new translations so rules are available to the generator.
+ */
+export async function collectAndSendUserEditDiffs(files, settings) {
+    if (!settings.files)
+        return;
+    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const downloadedVersions = getDownloadedVersions(settings.configDirectory);
+    const tempDir = path.join(os.tmpdir(), randomUUID());
+    if (!fs.existsSync(tempDir))
+        fs.mkdirSync(tempDir, { recursive: true });
+    const candidates = [];
+    for (const uploadedFile of files) {
+        for (const locale of settings.locales) {
+            const outputPath = fileMapping[locale]?.[uploadedFile.fileName] ?? null;
+            if (!outputPath)
+                continue;
+            if (!fs.existsSync(outputPath))
+                continue;
+            const latestDownloaded = findLatestDownloadedVersion(downloadedVersions, uploadedFile.branchId, uploadedFile.fileId, locale);
+            if (!latestDownloaded)
+                continue;
+            const downloadedVersion = latestDownloaded.entry;
+            // Skip if local file matches the last postprocessed content hash
+            if (downloadedVersion.postProcessHash) {
+                try {
+                    const localContent = await fs.promises.readFile(outputPath, 'utf8');
+                    const localHash = hashStringSync(localContent);
+                    if (localHash === downloadedVersion.postProcessHash) {
+                        continue;
+                    }
+                }
+                catch {
+                    // If hash check fails, fall through to diff
+                }
+            }
+            candidates.push({
+                branchId: uploadedFile.branchId,
+                fileName: uploadedFile.fileName,
+                fileId: uploadedFile.fileId,
+                versionId: latestDownloaded.versionId,
+                locale: locale,
+                outputPath,
+            });
+        }
+    }
+    const collectedDiffs = [];
+    if (candidates.length > 0) {
+        const fileQueryData = candidates.map((c) => ({
+            versionId: c.versionId,
+            locale: c.locale,
+            fileId: c.fileId,
+            branchId: c.branchId,
+        }));
+        // Single batched check to obtain translation IDs
+        const checkResponse = await gt.queryFileData({
+            translatedFiles: fileQueryData,
+        });
+        const translatedFiles = checkResponse.translatedFiles?.filter((t) => t.completedAt) ?? [];
+        const serverContentByKey = new Map();
+        try {
+            const resp = await gt.downloadFileBatch(translatedFiles.map((file) => ({
+                branchId: file.branchId,
+                fileId: file.fileId,
+                locale: file.locale,
+                versionId: file.versionId,
+            })));
+            const files = resp?.files || [];
+            for (const f of files) {
+                serverContentByKey.set(`${f.branchId}:${f.fileId}:${f.versionId}:${f.locale}`, f.data);
+            }
+        }
+        catch {
+            // Ignore chunk failures; proceed with what we have
+        }
+        // Compute diffs using fetched server contents
+        for (const c of candidates) {
+            const key = `${c.branchId}:${c.fileId}:${c.versionId}:${c.locale}`;
+            const serverContent = serverContentByKey.get(key);
+            if (!serverContent)
+                continue;
+            try {
+                const safeName = Buffer.from(`${c.branchId}:${c.fileId}:${c.versionId}:${c.locale}`)
+                    .toString('base64')
+                    .replace(/=+$/g, '');
+                const tempServerFile = path.join(tempDir, `${safeName}.server`);
+                await fs.promises.writeFile(tempServerFile, serverContent, 'utf8');
+                const diff = await getGitUnifiedDiff(tempServerFile, c.outputPath);
+                try {
+                    await fs.promises.unlink(tempServerFile);
+                }
+                catch { }
+                if (diff && diff.trim().length > 0) {
+                    const rawLocalContent = await fs.promises.readFile(c.outputPath, 'utf8');
+                    // For JSON files with jsonSchema config, extract to composite format
+                    let localContent = rawLocalContent;
+                    if (c.fileName.endsWith('.json') &&
+                        settings.options?.jsonSchema &&
+                        c.locale !== settings.defaultLocale) {
+                        const extractedContent = extractJson(rawLocalContent, c.fileName, settings.options, c.locale, settings.defaultLocale);
+                        if (extractedContent) {
+                            localContent = extractedContent;
+                        }
+                    }
+                    collectedDiffs.push({
+                        fileName: c.fileName,
+                        locale: c.locale,
+                        diff,
+                        branchId: c.branchId,
+                        versionId: c.versionId,
+                        fileId: c.fileId,
+                        localContent,
+                    });
+                }
+            }
+            catch {
+                // Ignore failures for this file
+            }
+        }
+    }
+    if (collectedDiffs.length > 0) {
+        await gt.submitUserEditDiffs({ diffs: collectedDiffs });
+    }
+}

package/dist/api/downloadFileBatch.d.ts

@@ -0,0 +1,23 @@
+import { Settings } from '../types/index.js';
+import type { FileStatusTracker } from '../workflows/steps/PollJobsStep.js';
+export type BatchedFiles = {
+    branchId: string;
+    fileId: string;
+    versionId: string;
+    locale: string;
+    outputPath: string;
+    inputPath: string;
+}[];
+export type DownloadFileBatchResult = {
+    successful: BatchedFiles;
+    failed: BatchedFiles;
+    skipped: BatchedFiles;
+};
+/**
+ * Downloads multiple translation files in a single batch request
+ * @param files - Array of files to download with their output paths
+ * @param maxRetries - Maximum number of retry attempts
+ * @param retryDelay - Delay between retries in milliseconds
+ * @returns Object containing successful and failed file IDs
+ */
+export declare function downloadFileBatch(fileTracker: FileStatusTracker, files: BatchedFiles, options: Settings, forceDownload?: boolean): Promise<DownloadFileBatchResult>;