Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,19 @@
Each release of Locali, newest first. An entry is dated when its release is cut, and reads *Unreleased* until then.
The releases before `1.0.0-preview.11` are recorded by their [tags](https://github.com/FormaUI/Locali/tags) alone.

## `1.0.0-preview.23`

*November 17, 2026*

- Breaking: LOC0208, LOC0214 and LOC0215 are retired, LOC0208 at a library's public method included. A lookup the run
could not check is no diagnostic: one writing its key as an expression, one taking its key from a parameter some call
writes otherwise, and one from which no path reaches a type are counted unchecked, the console summary says how many,
and the JSON report's `coverage.uncheckedLookups` lists each with its place, its reasons, `keyNotWritten` and
`keyFromParameter` among them, and what kept it unchecked, naming for a library's public method the key hint that lets
its consumers' runs check the calls they make. `coverage.lookups` counts those two kinds of key as well.
- A linting configuration naming a retired rule in `ignoreDiagnostics` is reported as LOC0021, a warning, rather than
LOC0020, so a configuration written for an earlier release keeps its run passing until the line is dropped.

## `1.0.0-preview.22`

*November 17, 2026*
Expand Down
49 changes: 27 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,16 +145,18 @@ nothing disappears without a trace:

```text
Linted 658 file(s); 6 diagnostic(s).
12 of 840 lookup(s) went unchecked; pass --report to list each and why.

8 diagnostic(s) not shown:
- LOC0106 (1)
- LOC0204 (1), LOC0207 (4), LOC0208 (2)
- LOC0204 (1), LOC0207 (4), LOC0209 (2)
Pass --severity warning to read them.
```

The brief names each rule and how many it contributed, a line per family. Its closing line only
promises what raising `--severity` will reveal: where the linting configuration accounts for
some or all of what is left out, it says so instead.
some or all of what is left out, it says so instead. A lookup the run could not check is no
diagnostic, so the line after the summary counts those, and the JSON report lists each.

| Exit code | Meaning |
|-----------|---------|
Expand All @@ -165,15 +167,20 @@ some or all of what is left out, it says so instead.
`--report` writes a JSON report carrying `fileCount`, `diagnosticCount`, `suppressedCount`,
`ignoredCount` — how many of the suppressed diagnostics the linting configuration left out
rather than the severity — a `diagnostics` array of `path`, `line`, `column`, `severity`,
`code`, `message`, and a `coverage` object for the lookups writing their keys in the files the
run linted: `lookups`; `fullyChecked`, `partiallyChecked` and `unchecked`, as each was held to
every type it reads with entries the run could read, to some, or to none; `evidence`, how many
checked lookups rest on the flow alone (`analysis`), on a hint the flow confirmed
(`verifiedHint`), or on a hint alone (`hint`); and `reasons`, how many lookups each reason left
short of fully checked: the kind of place a path ended, as `customFactory` or `externalCallers`,
`approximate` alternatives, `unavailableEntries` for a type whose assembly no project of the run
builds, or `notFollowed` for a lookup found without a bound compilation, or in code no instance
runs.
`code`, `message`, and a `coverage` object for the lookups the run found in the files it linted:
`lookups`, among them those writing their key as an expression and those taking it from a
parameter some call writes otherwise; `fullyChecked`, `partiallyChecked` and `unchecked`, as
each was held to every type it reads with entries the run could read, to some, or to none;
`evidence`, how many checked lookups rest on the flow alone (`analysis`), on a hint the flow
confirmed (`verifiedHint`), or on a hint alone (`hint`); `reasons`, how many lookups each reason
left short of fully checked: the kind of place a path ended, as `customFactory` or
`externalCallers`, `approximate` alternatives, `unavailableEntries` for a type whose assembly no
project of the run builds, `notFollowed` for a lookup found without a bound compilation, or in
code no instance runs, `keyNotWritten` for a key written as an expression, or `keyFromParameter`
for a key a parameter takes that some call writes otherwise; and `uncheckedLookups`, each lookup
counted unchecked with its `path`, `line`, `column`, `reasons` and an `explanation` of what kept
it unchecked, which for a library's public method whose key its consumers write names the key
hint that lets their runs check the calls they make.

## How Callsites Are Found

Expand All @@ -198,12 +205,12 @@ is read through the method's paths with what it passes: a condition its constant
settle, such as an empty or null test of the key or a flag it passes as `false`, is followed the
one way it goes, so a call the method returns from before the lookup looks nothing up, and a
condition on anything but the key leaves the lookup as reachable as one written under it. The
key is reported as an expression where a call reaching the lookup writes it otherwise; where
calls the run cannot see may write it: through a delegate, a base or an interface method, or
from outside a library, unless a key hint the method's body bears out names it; and where a
call's text may not be what the lookup reads: a condition on the key the flow cannot settle,
such as `key.StartsWith("raw:")`, stands between the call and the lookup, or the method writes
the parameter first, or reads it in a lambda, a local function or a handler.
lookup is counted unchecked, and listed in the run's report, where a call reaching it writes the
key otherwise; where calls the run cannot see may write it: through a delegate, a base or an
interface method, or from outside a library, unless a key hint the method's body bears out names
it; and where a call's text may not be what the lookup reads: a condition on the key the flow
cannot settle, such as `key.StartsWith("raw:")`, stands between the call and the lookup, or the
method writes the parameter first, or reads it in a lambda, a local function or a handler.

A lookup through Microsoft's `IStringLocalizer`, written as `localizer["Checkout"]` with a
literal key, is a lookup of Forma's where the run has Forma's adapter answer it: its product
Expand All @@ -229,7 +236,8 @@ the walk cannot follow a value, such as a type chosen at run time, a factory the
itself, or a service registered in a way the walk cannot read, the path ends and the lookup is
held to no type along it; alternatives the walk cannot pair with the lookup, such as both sides
of a conditional, whether locales, objects holding them, or delegates returning them, are never
held to it for certain.
held to it for certain. A lookup held to no type is counted unchecked, and the report lists it
with where its path ended.

What the walk cannot read, a hint states: a member whose locale is read for the type another
member of the same instance returns, as `FormaComponentBase.L` is for `LocaleSourceType`, or a
Expand Down Expand Up @@ -261,7 +269,7 @@ under 100, a file rule in the 100s, and a callsite rule in the 200s.
| Code | Severity | Reports |
|------|----------|---------|
| LOC0020 | Error | The linting configuration is not readable JSON, does not follow its shape, or names a rule this linter does not define |
| LOC0021 | Warning | An entry in the linting configuration applied to no file the run reached |
| LOC0021 | Warning | An entry in the linting configuration applied to no file the run reached, or names a retired rule |
| LOC0022 | Error | The runtime's `.locale.json` is not readable, names a key the runtime does not read, gives a value it would refuse, is one of two for an assembly, sits anywhere but its project's root, or sits in a locale pack |
| LOC0023 | Warning | The root namespace the runtime counts a type's name from holds none of the project's types |
| LOC0024 | Error | A locale pack's file has a name starting with no assembly the solution builds or references |
Expand Down Expand Up @@ -302,14 +310,11 @@ under 100, a file rule in the 100s, and a callsite rule in the 200s.
| LOC0205 | Warning | A project's Razor markup went unchecked |
| LOC0206 | Error | A key writes text shaped like a hole the runtime cannot read |
| LOC0207 | Warning | A key is not answered in a culture its type is localized in |
| LOC0208 | Warning | A lookup writes its key as an expression |
| LOC0209 | Warning | A key carries holes but no words anywhere else |
| LOC0210 | Warning | An expression key carries no words in any field |
| LOC0211 | Error | A lookup writes its key as an interpolated string with holes |
| LOC0212 | Error | A lookup writes a key shaped like a reserved entry |
| LOC0213 | Error | A lookup supplies `string.Format`'s format text |
| LOC0214 | Warning | A lookup's type through a hinted member could not be read |
| LOC0215 | Warning | A lookup writing its key in a localized project reaches no type its locale is read for |
| LOC0216 | Error | A project referencing packages was loaded without its restore output |

## Contributing
Expand Down
Loading
Loading