Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
de24f46
test(pluginkit): pin the list of installed plugins
SirLouen Nov 18, 2026
6ccc84f
feat(pluginkit): read a plugin's description from its manifest
SirLouen Nov 18, 2026
b9f10b0
feat(pluginkit): keep the step a plugin paused at apart from its own …
SirLouen Nov 18, 2026
3b39527
test(pluginkit): check that a store keeps the step a plugin paused at
SirLouen Nov 18, 2026
dbfceba
test(pluginkit): pause each failed plugin at its step in the boot sce…
SirLouen Nov 18, 2026
8f2630b
feat(pluginkit): list each installed plugin with its state and the st…
SirLouen Nov 18, 2026
4f58ed2
test(pluginkit): run the installed plugin scenarios
SirLouen Nov 18, 2026
0235895
docs(pluginkit): list descriptions, installed plugins and pause steps…
SirLouen Nov 18, 2026
f225c17
feat(gottext): read a plugin's name, description, labels and help fro…
SirLouen Nov 18, 2026
f634176
docs(gottext): list manifest keys under Unreleased
SirLouen Nov 18, 2026
2452b62
test(pluginkit): pin that a plugin whose error text panics is paused …
SirLouen Nov 18, 2026
6c42c52
fix(pluginkit): read a plugin's error text once inside the recover
SirLouen Nov 18, 2026
e1af7c7
test(pluginkit): pin that a menu entry key in another case or named t…
SirLouen Nov 18, 2026
5abd13a
feat(pluginkit): reject a manifest key in another case, a repeated ke…
SirLouen Nov 18, 2026
2cbc9eb
docs(pluginkit): list the strict manifest reading under Unreleased
SirLouen Nov 18, 2026
3ddc0ad
fix(gottext): keep messages named like Object members and read only o…
SirLouen Nov 18, 2026
496cc2a
docs(gottext): say manifest keys are read in lower case and list the …
SirLouen Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions gottext/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,16 @@ versioning follows [Semantic Versioning](https://semver.org/). While at 0.x,
minor releases may break. Releases are tagged `gottext/vX.Y.Z` and publish
from CI.

## [Unreleased]

### Added

- `pot` takes a `manifests` option, globs read from the root, and reads each plugin manifest's `name` and `description` and each setting's `label` and `help`, each key in lower case as pluginkit requires, with the manifest's path as the reference. A glob that matches no file and a manifest it cannot read are rejected. Before Node 22.17 its glob prints Node's experimental warning.

### Fixed

- `pot` keeps a message a Go marker or template names `__proto__`, which it used to leave out.

## [0.8.1] - 2026-11-09

### Fixed
Expand Down
19 changes: 19 additions & 0 deletions gottext/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,25 @@ template that writes a number through `%d`, `%i`, `%u`, `%e`, `%f` or
`%g`, upper case `%E` and `%G` and a length such as `%ld` included, so
each count reaches the reader through `formatNumber` and `%s`.

## Plugin manifests

The build entry's `pot` also reads plugin manifests. Hand its
`manifests` option the globs that name them, read from the root, such
as `plugins/*/plugin.json`. Each manifest gives the template its
`name` and `description`, and the `label` and `help` of each entry in
its `settings`, each key in lower case as pluginkit requires, with the
manifest's path as the reference. It reads no other key, and it leaves
out an empty or null value.

`pot` rejects a glob that matches no file, a path it cannot read as a
file, a manifest that is not a JSON object, a `settings` that is not a
list of objects, and any of those four keys holding something other
than text. The error names the glob or the manifest.

`manifests` reads its globs through Node's `fs.globSync`, which is
stable from Node 22.17. On Node 22.13 to 22.16 it works but prints
Node's experimental warning.

## License

Apache-2.0. See NOTICE for how the GPL licensed runtime peer is
Expand Down
193 changes: 183 additions & 10 deletions gottext/src/pot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

import { GettextExtractor, JsExtractors } from 'gettext-extractor'
import { po, type GetTextTranslation } from 'gettext-parser'
import { readFileSync, readdirSync } from 'node:fs'
import { join } from 'node:path'
import { globSync, readFileSync, readdirSync } from 'node:fs'
import { join, resolve } from 'node:path'

/** IGNORED is the set of paths that can never name a source, whatever a consumer ships. */
const IGNORED = ['**/node_modules/**', '**/*.d.ts', '**/*.test.ts', '**/*.test.tsx']
Expand All @@ -23,6 +23,29 @@ const MARKER_CALL = /\bMsgid\("((?:[^"\\]|\\.)*)"\)/g
/** DEFAULT_DOMAIN is the text domain a call naming none belongs to. */
const DEFAULT_DOMAIN = 'default'

/** ManifestKey is a key of a plugin manifest whose text the template carries, in lower case. */
type ManifestKey = 'name' | 'description' | 'label' | 'help'

/** MANIFEST_TEXTS is the keys of a plugin manifest whose text the template carries. */
const MANIFEST_TEXTS: ManifestKey[] = ['name', 'description']

/** SETTING_TEXTS is the keys of each setting a plugin manifest declares whose text the template carries. */
const SETTING_TEXTS: ManifestKey[] = ['label', 'help']

/** Entry is one JSON object a plugin manifest holds, read key by key. */
type Entry = Record<string, unknown>

/** Manifest is one plugin manifest read whole. */
interface Manifest {
/** path is where the manifest sits, as its glob names it, and the reference its texts carry. */
path: string
/** entry is the top object the manifest holds. */
entry: Entry
}

/** Translations is every entry of a template, by context then message. */
type Translations = Record<string, Record<string, GetTextTranslation>>

/** Extractor is what the parser runs over every piece of a source. */
type Extractor = ReturnType<typeof JsExtractors.callExpression>

Expand Down Expand Up @@ -78,6 +101,8 @@ export interface PotOptions {
ignored?: string[]
/** goRoots are the directories a Go walk reads, none by default. */
goRoots?: string[]
/** manifests are the globs naming the plugin manifests to read, from the root, none by default. */
manifests?: string[]
}

/**
Expand Down Expand Up @@ -149,6 +174,156 @@ export function goMessages(root: string, dirs: string[]): string[] {
return [...held]
}

/**
* Returns whether a JSON value is an object, rather than a list, a text, a number or null.
* @param value - The value to check.
* @returns True when the value is an object.
*/
function isEntry(value: unknown): value is Entry {
return value instanceof Object && !Array.isArray(value)
}

/**
* Returns the value a manifest object holds under a key as its own, none when it only inherits one.
* @param entry - The object to read.
* @param key - The key to read.
* @returns The value, or nothing.
*/
function ownValue<K extends string>(entry: Partial<Record<K, unknown>>, key: K): unknown {
return Object.hasOwn(entry, key) ? entry[key] : undefined
}

/**
* Returns the text one key of a manifest object holds, none when the key is absent, null or empty.
* @param manifest - The manifest the object sits in, named in an error.
* @param entry - The object to read.
* @param key - The key to read.
* @returns The text, or nothing.
*/
function textOf(manifest: Manifest, entry: Entry, key: ManifestKey): string[] {
const text = ownValue(entry, key) ?? ''
if (typeof text !== 'string') {
throw new Error(`the manifest ${manifest.path} holds a ${key} that is not text`)
}
return text === '' ? [] : [text]
}

/**
* Returns the settings a manifest declares, none when it names none.
* @param manifest - The manifest to read.
* @returns The declared settings.
*/
function settingsOf(manifest: Manifest): Entry[] {
const settings = ownValue(manifest.entry, 'settings') ?? []
if (!Array.isArray(settings) || !settings.every(isEntry)) {
throw new Error(`the manifest ${manifest.path} holds settings that are not a list of objects`)
}
return settings
}

/**
* Returns the plugin manifest at one path, read whole.
* @param options - The root the path resolves against.
* @param path - The manifest's path, as its glob names it.
* @returns The manifest with its top object.
*/
function manifestAt(options: PotOptions, path: string): Manifest {
let body: string
try {
body = readFileSync(resolve(options.root, path), 'utf8')
} catch (cause) {
throw new Error(`the manifest ${path} cannot be read`, { cause })
}
let entry: unknown
try {
entry = JSON.parse(body)
} catch {
throw new Error(`the manifest ${path} holds JSON this extractor cannot read`)
}
if (!isEntry(entry)) {
throw new Error(`the manifest ${path} holds no JSON object`)
}
return { path, entry }
}

/**
* Returns the texts one plugin manifest hands the template.
* @param manifest - The manifest to read.
* @returns The plugin's name and description, then each setting's label and help.
*/
function manifestTexts(manifest: Manifest): string[] {
return [
...MANIFEST_TEXTS.flatMap((key) => textOf(manifest, manifest.entry, key)),
...settingsOf(manifest).flatMap((setting) => SETTING_TEXTS.flatMap((key) => textOf(manifest, setting, key))),
]
}

/**
* Returns the paths the manifest globs match, rejecting a glob that matches none.
* @param options - The root and the manifest globs to read.
* @returns The paths found, as the globs name them, in a settled order.
*/
function manifestPaths(options: PotOptions): string[] {
return (options.manifests ?? []).flatMap((pattern) => {
const found = globSync(pattern, { cwd: options.root })
if (found.length === 0) {
throw new Error(`no manifest matches ${pattern}`)
}
return found
}).sort()
}

/**
* Returns each text the plugin manifests hand the template, with the manifests holding it.
* @param options - The root and the manifest globs to read.
* @returns The texts found, each with the paths of its manifests in a settled order.
*/
function manifestMessages(options: PotOptions): Map<string, Set<string>> {
const held = new Map<string, Set<string>>()
for (const path of manifestPaths(options)) {
for (const text of manifestTexts(manifestAt(options, path))) {
held.set(text, (held.get(text) ?? new Set<string>()).add(path))
}
}
return held
}

/**
* Returns the value a table owns under a key, first defining a made one as its own when it owns none.
* @param table - The table to read.
* @param key - The key to read, which may name an Object member such as __proto__ that every table inherits.
* @param made - Returns the value to define when the table owns none.
* @returns The value the table owns under the key.
*/
function owned<K extends string, T>(table: Record<K, T>, key: K, made: () => NoInfer<T>): T {
if (!Object.hasOwn(table, key)) {
Object.defineProperty(table, key, { value: made(), enumerable: true, writable: true, configurable: true })
}
return table[key]
}

/**
* Returns the entries a template holds under one context, starting them when it holds none.
* @param translations - The template entries, by context then message.
* @param context - The context, which may name an Object member.
* @returns The entries under the context, by message.
*/
function contextOf(translations: Translations, context: string): Record<string, GetTextTranslation> {
return owned(translations, context, () => ({}))
}

/**
* Adds each text the plugin manifests hold to the template, naming its manifests as its reference.
* @param translations - The template entries, by context then message.
* @param options - The root and the manifest globs to read.
*/
function addManifests(translations: Translations, options: PotOptions): void {
for (const [text, paths] of manifestMessages(options)) {
const entry = owned(contextOf(translations, ''), text, () => ({ msgid: text, msgstr: [''] }))
entry.comments = { reference: [...paths].join('\n') }
}
}

/**
* Returns the key an entry is ordered by.
* @param entry - The entry to key.
Expand Down Expand Up @@ -248,16 +423,14 @@ function entryOf(message: Found): GetTextTranslation {
* @returns The template as UTF-8 bytes.
*/
export function pot(options: PotOptions): Buffer {
const translations: Record<string, Record<string, GetTextTranslation>> = {}
for (const text of goMessages(options.root, options.goRoots ?? [])) {
translations[''] ??= {}
translations[''][text] = { msgid: text, msgstr: [''] }
}
const translations: Translations = {}
for (const message of messages(options)) {
const context = message.context ?? ''
translations[context] ??= {}
translations[context][message.text] = entryOf(message)
owned(contextOf(translations, message.context ?? ''), message.text, () => entryOf(message))
}
for (const text of goMessages(options.root, options.goRoots ?? [])) {
owned(contextOf(translations, ''), text, () => ({ msgid: text, msgstr: [''] }))
}
addManifests(translations, options)
return po.compile(
{
charset: 'UTF-8',
Expand Down
Loading
Loading