feat: preferred terminology

[simoncodes-ca]

Closes #107.

Teams have words they'd rather authors used: Investment, not Expenditure. This adds a rule file that records those preferences and surfaces them wherever base-locale copy is written. The warnings are advisory — nothing here ever blocks a save, an import, or a build.

What's in it

• Rule file .lingo-tracker-preferred-terminology.json beside .lingo-tracker.json, overridable via preferredTerminologyFile. A rule is discouraged → preferred, with an optional reason.
• Matching is case-insensitive and whole-word. capital expenditure matches; Expenditures and ExpenditureType do not. Only visible text is scanned — never ICU argument names, selectors, or HTML tags.
• Resource editor shows one advisory per match under the base-locale field, with a Use "…" button that rewrites the field. It does not save.
• Settings has a Preferred terminology section that shares the Save bar with protected terms.
• CLI lingo-tracker preferred-terminology --list | --add | --remove.
• validate reports the warnings without failing; import, add-resource, and edit-resource warn on base-locale values.

A broken rule file warns and skips the checks everywhere except validate, which fails on it.

Behaviour change worth flagging

Importing into a collection that sets its own baseLocale used to write the value to the wrong field. It now writes the base value, like every other base-locale import. That is a bug fix, but it changes what an existing import does.

Review notes

This was built as seven phases, one commit series each: domain matching → rule file → CLI → validate/import/authoring → API + Settings → editor → docs. Reading the commits in order is easier than reading the diff.

Full spec, including the settled edge cases, is in docs/features/preferred-terminology.md.

Testing

All suites pass: domain, core, cli, api, tracker. The editor and Settings screens were checked in a browser in light and dark themes.

🤖 Generated with Claude Code

Note

Add preferred terminology feature across CLI, API, validation, and UI

• Adds a domain module with rule normalization, validation, visible-text extraction, whole-word matching, and replacement in preferred-terminology.ts
• Adds a preferred-terminology CLI command for listing, adding, updating, and removing rules, plus advisory warnings in validate, edit-resource, and import commands
• Adds API support in config.controller.ts for reading and writing rules, with per-row 400 validation errors
• Adds a Settings editor in settings.ts for viewing and editing rules with live validation, and a translation-editor advisory component that surfaces findings with a one-click apply action
• Adds core file loading/writing in preferred-terminology-file.ts with an in-process mtime/size cache; findings are advisory (warnings only) while an unloadable rule file is a validation failure
• Behavioral Change: validate and import now scan base-locale source values for discouraged terms; validate exit code is unchanged for findings but fails on an unreadable rule file; import prepends a terminology warning to the summary only for base-locale imports

📊 Macroscope summarized f358790. 52 files reviewed, 19 issues evaluated, 9 issues filtered, 9 comments posted

🗂️ Filtered Issues

apps/api/src/app/config/config.controller.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 35: getConfig calls loadPreferredTerminology without handling filesystem failures. loadPreferredTerminology begins with statSync, which can throw (for example EACCES when the configured rule file or one of its directories is unreadable) before its in-band { error } result is constructed. Thus a merely unreadable terminology file makes GET /config fail instead of returning the documented load error that Settings needs to display and repair it. [ Cross-file consolidated ]

apps/cli/src/add-resource/add-resource.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 109: warnAboutPreferredTerminology runs after addResource has synchronously written both resource files, but it remains inside the operation's try block. If an explicitly configured terminology path cannot be statted (for example an inaccessible parent directory), the statSync in loadPreferredTerminology throws; the command then prints a failed-add error even though the resource was already persisted. The advisory failure should be caught/skipped independently of the completed write. [ Cross-file consolidated ]

apps/cli/src/commands/validate.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 192: loadPreferredTerminology is invoked outside any error handling. Its readStamp calls statSync, which throws (rather than returning undefined) when an explicitly configured terminology file, or one of its parent directories, is inaccessible. Thus lingo-tracker validate rejects before creating the intended validation result/summary for a broken rule file instead of reporting the configuration failure cleanly and exiting with code 1. [ Cross-file consolidated ]

apps/tracker/src/app/settings/settings.html — 0 comments posted, 1 evaluated, 1 filtered

• line 414: The new Add rule control is enabled while the initial configuration is still absent. A user can add and type a terminology rule during the initial load, but the settings seeding effect unconditionally calls terminology.seed(config.preferredTerminology ?? []) on that first config arrival, replacing the draft and silently discarding the entered rule. Disable or defer this control until config is loaded, or preserve a pre-load draft. [ Cross-file consolidated ]

docs/cli.md — 0 comments posted, 1 evaluated, 1 filtered

• line 666: The new note says warnings are printed only when the base value changes, but editResourceCommand emits them whenever editOptions.baseValue is supplied and any edit succeeds. For example, passing an unchanged discouraged --base-value together with a changed --comment yields result.updated === true and prints the terminology warning although the base value was not changed. [ Out of scope (post-validation triage) ]

docs/features/preferred-terminology.md — 0 comments posted, 2 evaluated, 2 filtered

• line 164: Saving from Settings replaces the file with the rules on screen is not true for every Settings save. Settings.onSave() includes preferredTerminology only when the terminology draft changed; saving only protected-term edits while a terminology file is broken leaves that file untouched. Users following this recovery advice can save successfully but retain the broken file. [ Out of scope (post-validation triage) ]
• line 174: The claim that --add creates an absent rule file is false when preferredTerminologyFile points into a directory that does not yet exist (for example the documented config/preferred-terminology.json with no config/ directory). writePreferredTerminology rejects a missing parent directory, so the documented command exits with an error instead of creating the file. [ Out of scope (post-validation triage) ]

libs/core/src/lib/config/preferred-terminology-file.ts — 1 comment posted, 2 evaluated, 1 filtered

• line 186: readStamp lets statSync errors other than a missing entry escape. For example, if the configured file (or one of its parent directories) is unreadable, statSync(..., { throwIfNoEntry: false }) still throws EACCES; this bypasses loadPreferredTerminology's in-band error contract and aborts callers such as config loading/import instead of returning an advisory broken-file result. [ Cross-file consolidated ]

libs/core/src/lib/import/process-resource-group.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 383: warnAboutPreferredTerminology is called for every existing base-locale import result, including handleBaseLocaleUpdate results with type: 'updated' when oldValue === resource.value. Thus re-importing an unchanged, already-stored discouraged value emits a warning even though no base value was written (contrary to the import option's documented "value written" behavior), producing spurious terminology warnings on no-op imports. [ Out of scope (post-validation triage) ]

[macroscopeapp]

🟠 High commands/preferred-terminology.ts:69

--list, --add, and --remove terminate with an uncaught filesystem exception when the configured terminology file or its parent directory is unreadable, instead of reporting the file as an in-band load error. loadPreferredTerminology(config, cwd) can throw from its initial statSync; make that failure return the documented { error } result (or catch and translate it here) so the command reports the configuration problem cleanly.

Also found in 4 other location(s)

apps/api/src/app/config/config.controller.ts:35

getConfig calls loadPreferredTerminology without handling filesystem failures. loadPreferredTerminology begins with statSync, which can throw (for example EACCES when the configured rule file or one of its directories is unreadable) before its in-band { error } result is constructed. Thus a merely unreadable terminology file makes GET /config fail instead of returning the documented load error that Settings needs to display and repair it.

apps/cli/src/add-resource/add-resource.ts:109

warnAboutPreferredTerminology runs after addResource has synchronously written both resource files, but it remains inside the operation's try block. If an explicitly configured terminology path cannot be statted (for example an inaccessible parent directory), the statSync in loadPreferredTerminology throws; the command then prints a failed-add error even though the resource was already persisted. The advisory failure should be caught/skipped independently of the completed write.

apps/cli/src/commands/validate.ts:192

loadPreferredTerminology is invoked outside any error handling. Its readStamp calls statSync, which throws (rather than returning undefined) when an explicitly configured terminology file, or one of its parent directories, is inaccessible. Thus lingo-tracker validate rejects before creating the intended validation result/summary for a broken rule file instead of reporting the configuration failure cleanly and exiting with code 1.

libs/core/src/lib/config/preferred-terminology-file.ts:186

readStamp lets statSync errors other than a missing entry escape. For example, if the configured file (or one of its parent directories) is unreadable, statSync(..., { throwIfNoEntry: false }) still throws EACCES; this bypasses loadPreferredTerminology's in-band error contract and aborts callers such as config loading/import instead of returning an advisory broken-file result.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/cli/src/commands/preferred-terminology.ts around line 69:

`--list`, `--add`, and `--remove` terminate with an uncaught filesystem exception when the configured terminology file or its parent directory is unreadable, instead of reporting the file as an in-band load error. `loadPreferredTerminology(config, cwd)` can throw from its initial `statSync`; make that failure return the documented `{ error }` result (or catch and translate it here) so the command reports the configuration problem cleanly.

Also found in 4 other location(s):
- apps/api/src/app/config/config.controller.ts:35 -- `getConfig` calls `loadPreferredTerminology` without handling filesystem failures. `loadPreferredTerminology` begins with `statSync`, which can throw (for example `EACCES` when the configured rule file or one of its directories is unreadable) before its in-band `{ error }` result is constructed. Thus a merely unreadable terminology file makes `GET /config` fail instead of returning the documented load error that Settings needs to display and repair it.
- apps/cli/src/add-resource/add-resource.ts:109 -- `warnAboutPreferredTerminology` runs after `addResource` has synchronously written both resource files, but it remains inside the operation's `try` block. If an explicitly configured terminology path cannot be statted (for example an inaccessible parent directory), the `statSync` in `loadPreferredTerminology` throws; the command then prints a failed-add error even though the resource was already persisted. The advisory failure should be caught/skipped independently of the completed write.
- apps/cli/src/commands/validate.ts:192 -- `loadPreferredTerminology` is invoked outside any error handling. Its `readStamp` calls `statSync`, which throws (rather than returning `undefined`) when an explicitly configured terminology file, or one of its parent directories, is inaccessible. Thus `lingo-tracker validate` rejects before creating the intended validation result/summary for a broken rule file instead of reporting the configuration failure cleanly and exiting with code 1.
- libs/core/src/lib/config/preferred-terminology-file.ts:186 -- `readStamp` lets `statSync` errors other than a missing entry escape. For example, if the configured file (or one of its parent directories) is unreadable, `statSync(..., { throwIfNoEntry: false })` still throws `EACCES`; this bypasses `loadPreferredTerminology`'s in-band error contract and aborts callers such as config loading/import instead of returning an advisory broken-file result.

[macroscopeapp]

🟡 Medium lib/update-config.dto.ts:17

When a Save-bar request contains both preferredTerminology and protectedTerms, a failure writing the protected-terms file returns 400 even though the terminology rules were already persisted, leaving a partially applied update while the UI reports failure. The controller writes preferredTerminology before calling setGlobalProtectedTerms; make these writes atomic, or ensure the terminology write is rolled back when the protected-terms write fails.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @libs/data-transfer/src/lib/update-config.dto.ts around line 17:

When a Save-bar request contains both `preferredTerminology` and `protectedTerms`, a failure writing the protected-terms file returns `400` even though the terminology rules were already persisted, leaving a partially applied update while the UI reports failure. The controller writes `preferredTerminology` before calling `setGlobalProtectedTerms`; make these writes atomic, or ensure the terminology write is rolled back when the protected-terms write fails.

[macroscopeapp]

🟠 High commands/preferred-terminology.ts:131

Concurrent preferred-terminology --add or --remove invocations can silently lose one another’s rule changes: both read the same result.rules, and the later writePreferredTerminology replaces the file with its stale next. Serialize updates with a file lock or use compare-and-retry before writing.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/cli/src/commands/preferred-terminology.ts around line 131:

Concurrent `preferred-terminology --add` or `--remove` invocations can silently lose one another’s rule changes: both read the same `result.rules`, and the later `writePreferredTerminology` replaces the file with its stale `next`. Serialize updates with a file lock or use compare-and-retry before writing.

[macroscopeapp]

🟡 Medium config/preferred-terminology-file.ts:100

An out-of-band edit that keeps the same mtimeMs and JSON byte length leaves the cache serving the old rules, so the next load does not refresh terminology as documented. Compare a content fingerprint (or reread the file) in addition to the timestamp and size.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @libs/core/src/lib/config/preferred-terminology-file.ts around line 100:

An out-of-band edit that keeps the same `mtimeMs` and JSON byte length leaves the cache serving the old rules, so the next load does not refresh terminology as documented. Compare a content fingerprint (or reread the file) in addition to the timestamp and size.

[macroscopeapp]

🟠 High config/preferred-terminology-file.ts:95

loadPreferredTerminology throws a TypeError instead of returning an in-band error when preferredTerminologyFile is a non-string value such as 42 or null, causing callers like GET /config and CLI commands to abort. Validate the runtime value before calling resolvePreferredTerminologyFilePath and return a load error for invalid configuration.

-  const filePath = resolvePreferredTerminologyFilePath(config, cwd);
+  const configuredPointer = config.preferredTerminologyFile;
+  if (typeof configuredPointer !== 'undefined' && typeof configuredPointer !== 'string') {
+    return {
+      rules: [],
+      filePath: resolve(cwd, DEFAULT_PREFERRED_TERMINOLOGY_FILENAME),
+      error: 'Preferred terminology file path must be a string',
+    };
+  }
+  const filePath = resolvePreferredTerminologyFilePath(config, cwd);

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @libs/core/src/lib/config/preferred-terminology-file.ts around line 95:

`loadPreferredTerminology` throws a `TypeError` instead of returning an in-band `error` when `preferredTerminologyFile` is a non-string value such as `42` or `null`, causing callers like `GET /config` and CLI commands to abort. Validate the runtime value before calling `resolvePreferredTerminologyFilePath` and return a load error for invalid configuration.

[macroscopeapp]

🟠 High config/preferred-terminology-file.ts:181

writeFileSync can block the entire Node process indefinitely when filePath already points to a FIFO with no reader. The parent-directory check does not validate the target, so reject existing non-regular targets before the synchronous write.

  const parent = dirname(filePath);
+  if (existsSync(filePath) && !statSync(filePath).isFile()) {
+    throw new Error(`Cannot write preferred terminology file — target is not a regular file: ${filePath}`);
+  }
   if (!existsSync(parent)) {
     throw new Error(`Cannot write preferred terminology file — directory does not exist: ${parent}`);
   }

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @libs/core/src/lib/config/preferred-terminology-file.ts around lines 181-187:

`writeFileSync` can block the entire Node process indefinitely when `filePath` already points to a FIFO with no reader. The parent-directory check does not validate the target, so reject existing non-regular targets before the synchronous write.