@lightnet/cli 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LightNet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# `@lightnet/cli`
+
+Command-line tools for working with LightNet projects.
+
+## Install
+
+```bash
+npm install --save-dev @lightnet/cli
+```
+
+You can also run the CLI without adding it to your project first:
+
+```bash
+npx @lightnet/cli --help
+```
+
+## Usage
+
+The package exposes the `lightnet` binary:
+
+```bash
+lightnet <command> [options]
+```
+
+Get the full command list at any time with:
+
+```bash
+lightnet --help
+```
+
+## Commands
+
+### `check-translations`
+
+Checks the translation data produced by the latest LightNet build and reports
+missing locale values.
+
+```bash
+lightnet check-translations
+```
+
+> [!NOTE]
+> `check-translations` only validates translations that were actually used
+> during the last build. For example, it would not report a missing category
+> label translation if that category label was never referenced while building
+> the site.
+
+What it does:
+
+- Reads the cached translation build output from `node_modules/.cache/lightnet/`
+- Verifies every translation has values for every configured locale
+- Groups missing translations by source to make follow-up work clearer
+
+When to use it:
+
+- After building a LightNet site
+- In CI to catch incomplete translations before deploys
+- While adding new locales or updating translation maps
+
+Expected setup:
+
+- Run your project build first so LightNet can generate its translation cache
+  If the cache is missing, the command will fail and prompt you to run a build
+  first.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@lightnet/cli",
+  "description": "CLI for managing LightNet projects",
+  "type": "module",
+  "license": "MIT",
+  "version": "4.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LightNetDev/lightnet",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/LightNetDev/lightnet/issues"
+  },
+  "bin": {
+    "lightnet": "./src/index.js"
+  },
+  "homepage": "https://lightnet.community",
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/check-translations.js

@@ -0,0 +1,135 @@
+// @ts-check
+
+import { readFile } from "node:fs/promises"
+import { resolve } from "node:path"
+import { cwd } from "node:process"
+
+const lightnetCachePath = resolve(cwd(), "node_modules", ".cache", "lightnet")
+
+/** @type {{type:Translation["type"], title:string, action:string}[]} */
+const translationSources = [
+  {
+    type: "lightnet",
+    title: "LightNet built-in translations",
+    action: "Add the missing entries in your /src/translations/*.yaml files.",
+  },
+  {
+    type: "user",
+    title: "User translation files",
+    action: "Add the missing entries in your /src/translations/*.yaml files.",
+  },
+  {
+    type: "map",
+    title: "Inline translation maps",
+    action:
+      "Update the inline translation map to include values for every configured site language.",
+  },
+]
+
+export async function checkTranslations() {
+  const translations = await readTranslations()
+  const languages = await readLanguages()
+  if (!translations || !languages || translations.length === 0) {
+    return false
+  }
+  const incompleteTranslations = translations
+    .map((translation) => ({
+      ...translation,
+      missingLocales: getMissingLocales(translation, languages),
+    }))
+    .filter((translation) => translation.missingLocales.length > 0)
+
+  if (incompleteTranslations.length === 0) {
+    return true
+  }
+
+  const grouped = Object.groupBy(
+    incompleteTranslations,
+    (translation) => translation.type,
+  )
+
+  console.log("Translation check failed")
+  for (const source of translationSources) {
+    printMissingTranslations(source, grouped[source.type])
+  }
+
+  console.log("\n\n")
+  return false
+}
+
+/**
+ *
+ * @param {{title:string, action:string}} source
+ * @param {(Translation & {missingLocales:string[]})[]|undefined} translations
+ */
+function printMissingTranslations(source, translations) {
+  if (!translations || translations.length === 0) {
+    return
+  }
+
+  console.log()
+  console.log(source.title)
+  translations
+    .toSorted(
+      (t1, t2) =>
+        t2.missingLocales.length - t1.missingLocales.length ||
+        t1.key.localeCompare(t2.key),
+    )
+    .forEach(({ key, missingLocales }) => {
+      console.log(`- ${key}`)
+      console.log(`  Missing locales: ${missingLocales.join(", ")}`)
+    })
+
+  console.log(`Action: ${source.action}`)
+}
+
+/**
+ *
+ * @param {Translation} translation
+ * @param {Languages} languages
+ * @returns {string[]}
+ */
+function getMissingLocales(translation, languages) {
+  return languages.locales.filter((locale) => !translation.values[locale])
+}
+
+/**
+ * @returns {Promise<Translation[]|undefined>}
+ */
+async function readTranslations() {
+  try {
+    const translationsText = await readFile(
+      resolve(lightnetCachePath, "translations.jsonl"),
+      "utf-8",
+    )
+    return translationsText
+      .split("\n")
+      .filter((line) => line.trim())
+      .map((line) => JSON.parse(line))
+  } catch {
+    console.error("No translation build cache found.")
+    console.error(
+      "Action: Run build and try lightnet check-translations again.",
+    )
+    return undefined
+  }
+}
+
+/**
+ * @returns {Promise<Languages|undefined>}
+ */
+async function readLanguages() {
+  try {
+    const languagesText = await readFile(
+      resolve(lightnetCachePath, "languages.json"),
+      "utf-8",
+    )
+    return JSON.parse(languagesText)
+  } catch {
+    console.error("No language manifest found from the last build.")
+    console.error(
+      "Action: Run build and try lightnet check-translations again.",
+    )
+    return undefined
+  }
+}

package/src/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { exit } from "node:process"
+
+import { Command } from "commander"
+
+import pkg from "../package.json" with { type: "json" }
+import { checkTranslations } from "./check-translations.js"
+const { version } = pkg
+
+const program = new Command()
+
+program
+  .name("lightnet-cli")
+  .description("CLI for managing LightNet projects")
+  .version(version)
+
+program
+  .command("check-translations")
+  .description("check if last build has been missing any translations")
+  .action(async () => {
+    const checkSuccessful = await checkTranslations()
+    exit(checkSuccessful ? 0 : 1)
+  })
+
+await program.parseAsync()

package/src/types.d.ts

@@ -0,0 +1,10 @@
+type Translation = {
+  type: "lightnet" | "user" | "map"
+  key: string
+  values: Record<string, string | undefined>
+}
+
+type Languages = {
+  defaultLocale: string
+  locales: string[]
+}