Files
giza-kmp/docs/scripts/m3-extract-strings.py
T
Kgothatso NgakoandClaude Opus 5 e6aee79282 refactor: rebrand curated to curare, and the one name that stays on disk
`com.it.curated.{compose,android,desktop}` becomes `to.curare.{compose,android,desktop}`
across 700 file moves, and the app is Curare everywhere a user can read it. This is the
third rename this tree has been through, so the question was never how to spell the new
name but which of the 5074 occurrences of the old one were the brand. `3bc8be53` and
`d26cf6c7` had already sorted most of that, which is why this rename is mechanical where
those two were not -- and why the interesting part is the one place it is still not.

**`APP_DIR_NAME` keeps the old brand, and is the only thing that does.** It names the
desktop app's data directory -- `~/.local/share/curated`, `Application Support/curated`,
`%LOCALAPPDATA%\curated` -- and that single directory holds the Room database, the marmot
group state and the phoenix wallet. Renaming it does not move an install: it silently
starts an empty one beside it and leaves the old chat history and the old seed sitting
where nothing reads them any more. That is the same class of silent failure as the
`mantra/` hash prefixes, so it gets the same treatment -- it stays, with a comment saying
what renaming it would cost and that doing it properly is a first-run migration rather
than a rebrand. The desktop app is `curated` on disk and `Curare` everywhere a user can
read.

**The applicationId and the namespace are one value again, at `to.curare.android`.**
`3bc8be53` split them precisely so `com.it.curated` could land verbatim as the store
identity while the namespace kept `.android`; the decision here was to collapse them, so
both read `to.curare.android` and the manifest's relative `android:name=".CurareApplication"`
and `BuildConfig` resolve against the same package they always did. Debug is
`to.curare.android.debug` through the existing suffix. Worth stating plainly because
nothing in the build will: an applicationId *is* the app's identity to Play, so this is a
new listing rather than an update, and no installed Curated can update into it.

**`CuratedDatabase` -> `CurareDatabase` moves a directory, never a table.** The `@Database`
class name picks the schema *directory*, so
`composeApp/schemas/com.it.curated.compose.database.CuratedDatabase/` becomes
`to.curare.compose.database.CurareDatabase/` and its 19 files move unmodified. What makes
that safe has not changed since last time: the 12 entity classes are still `Mantra*` and
still declare no `tableName`, so Room still takes their class names as the SQLite table
names -- and this rename does not touch one of them. The check is that Room found all 19
schemas at the new directory and generated no twentieth.

**The generated resources package moved because `rootProject.name` did, again.** Compose
Resources derives it from the root project, so `Curated` -> `Curare` silently turns
`curated.composeapp.generated.resources` into `curare.composeapp.generated.resources` and
breaks 72 files' imports at once. Rewritten with them: the two string keys that carried
the brand -- `curated` and `sign_in_is_not_yet_available_while_curated_is` -- their three
call sites, and the eight `docs/scripts/` tools that hardcode the UI source path. The
audit reporting 582 `stringResource` sites and 178 `Icon(` call sites is the evidence
those tools still see the whole tree rather than an empty directory.

**A global rename edits the sentences that describe the previous rename, and two of them
came out false.** `material-design-conformance.md` recorded that `TorchTheme` became
`CuratedTheme` and that `UserAgent` was moved off Torch "when the app was rebranded to
Curated" -- which a blanket sweep turns into a claim about a change that had not happened
when it was written. Same in `HomeScreen`, where "the brand before that one" meant Torch
while Curated was current, and quietly came to mean Curated while still naming
`TorchTheme`. Both now say what happened, in order. The three deliberate Torch records --
the finding at :278, that note, and `NavigationRoutingTest`'s fixture -- are intact.

**What was protected stays protected, and now says "two rebrands".** `TWEAK_TAG`,
`HOST_KEY_DERIVATION_TAG` and `wss://ephemeral.mantra.press` are byte-identical; only the
prose around them moved, because "survived the rebrand to Curated" had stopped being the
whole story. The tree's 1668 `Mantra` and 17 `Torch` tokens differ from the 1666 and 16
before this change only by the words those comments added.

**iOS is `Curare` / `to.curare.ios`**, with the three pbxproj product references renamed
to match, and is unverified here for the same reason as last time -- the build gates the
ios targets behind `isMacOsX` and this was built on linux. The bundle id takes a platform
segment rather than the bare base it translates from, so that it reads alongside an
android applicationId that now carries one: `to.curare.android` and `to.curare.ios`, and
`to.curare` left as the base neither store claims.

1226 tests pass -- 787 in `:composeApp:jvmTest`, 439 in `:composeApp:testDebugUnitTest` --
`:composeApp:compileDebugKotlinAndroid` is clean, and `m3Audit` meets every budget.

Three stale things are left alone, because none of them is branding.
`.gitea/workflows/material-design-conformance.yml` still triggers on `branches: [mantra]`,
which stopped naming a branch that exists somewhere before this change and is now two
brands out; the three `torch_*` string keys still carry a brand two renames old, though
every value they hold reads Curare; and `androidMain/res/values/strings.xml` has opened
`<resources>a` since well before this. Each wants its own change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 13:33:47 +02:00

280 lines
11 KiB
Python
Executable File

#!/usr/bin/env python3
"""Move literal UI strings out of composables and into the resource catalogue.
Handles the simple case only: a `text = "..."` or `Text("...")` whose literal contains no
Kotlin interpolation. Interpolated strings need format placeholders and an argument order
decided per site, which is not something to do blind.
Resource names are derived from the string's content, snake_cased and truncated at a word
boundary. That is the conventional shape for an automated extraction and it has a known
cost: rewording the copy makes the name a little stale. The alternative -- a name derived
from the string's *purpose* -- needs somebody to read all 285 call sites, and a wrong
purpose in a name is worse than a slightly dated one.
Usage:
m3-extract-strings.py dry run, prints the plan
m3-extract-strings.py --apply
"""
import os, re, sys, io, collections
UI = 'composeApp/src/commonMain/kotlin/to/curare/compose/ui'
STRINGS = 'composeApp/src/commonMain/composeResources/values/strings.xml'
DRY = '--apply' not in sys.argv
# Literals inside a `Text(...)` call, with no `$` inside.
#
# The first version of this matched a bare `text = "…"` anywhere, which is wrong: `text`
# is an ordinary parameter name and the tree uses it on data classes too. It rewrote
# `NavigationUIState.Loading(text = "…")` -- not a composable -- and the compiler caught
# it with "@Composable invocations can only happen from the context of a @Composable
# function". So the call is brace-matched instead, and only literals genuinely inside a
# `Text(` are touched.
def text_call_spans(source):
"""Character ranges of every `Text(` / `BasicText(` call, brace-matched.
Anchoring to the call is what keeps `NavigationUIState.Loading(text = "…")` out of
the results. `text` is an ordinary parameter name and the tree uses it on data
classes too; an earlier version matched a bare `text = "…"` anywhere and rewrote a
non-composable, which the compiler caught with "@Composable invocations can only
happen from the context of a @Composable function".
"""
spans = []
for m in re.finditer(r'\b(?:Basic)?Text\s*\(', source):
depth, i = 0, m.end() - 1
while i < len(source):
if source[i] == '(':
depth += 1
elif source[i] == ')':
depth -= 1
if depth == 0:
spans.append((m.start(), i))
break
i += 1
return spans
def kotlin_strings(source):
"""Every top-level Kotlin string literal, as (start, end, body, interpolated).
A regex cannot do this. `"a ${if (n == 1) "chunk" else "chunks"} b"` contains two
inner literals that belong to the outer template, and matching quote pairs left to
right pulls them out as strings of their own -- which is how an earlier version of
this script decided "chunk" and "note" were UI strings worth translating.
So the source is scanned: on an opening quote, walk forward tracking `${` depth and
recursing over nested literals, and stop at the closing quote that is at depth zero.
Raw strings and escapes are skipped rather than parsed, which is enough here.
"""
out, i, n = [], 0, len(source)
while i < n:
c = source[i]
if c == '"' and source[i:i + 3] == '\"\"\"':
end = source.find('\"\"\"', i + 3)
i = n if end == -1 else end + 3
continue
if c != '"':
i += 1
continue
j, depth, interpolated = i + 1, 0, False
while j < n:
ch = source[j]
if ch == '\\':
j += 2
continue
if ch == '$' and j + 1 < n and (source[j + 1] == '{' or source[j + 1].isalpha()):
interpolated = True
if source[j + 1] == '{':
depth += 1
j += 2
continue
if depth > 0:
if ch == '{':
depth += 1
elif ch == '}':
depth -= 1
elif ch == '"':
# a literal inside the interpolation: skip it whole
k = j + 1
while k < n and source[k] != '"':
k += 2 if source[k] == '\\' else 1
j = k
j += 1
continue
if ch == '"':
break
if ch == '\n':
break
j += 1
if j < n and source[j] == '"':
out.append((i, j + 1, source[i + 1:j], interpolated))
i = j + 1
else:
i += 1
return out
def literals_in_text_calls(source):
"""(start, end, value) for each plain, whole literal inside a Text( call."""
spans = text_call_spans(source)
found = []
for start, end, value, interpolated in kotlin_strings(source):
if interpolated or not value.strip():
continue
if not any(a <= start <= b for a, b in spans):
continue
line_start = source.rfind('\n', 0, start) + 1
line = source[line_start:source.find('\n', start)]
if line.lstrip().startswith(('//', '*', '/*')):
continue
# A fragment of a concatenation. `"a " + x + " b"` is one sentence in three
# pieces, and " b" is not a translatable unit -- word order differs between
# languages, so a translator handed " b" has nothing to work with. These go with
# the interpolated strings, which need format placeholders and a human.
before = source[:start].rstrip()
after = source[end:].lstrip()
if before.endswith('+') or after.startswith('+'):
continue
if value != value.strip() or not any(c.isalpha() for c in value):
continue
if before.endswith('append('):
continue
# The same fragment problem one level out. A pluralisation reads
#
# (if (n == 2) "event" else "events") +
#
# so neither literal is adjacent to the `+` -- the parenthesis is. Testing the
# line instead catches those four sites while leaving a genuine either/or alone:
#
# text = if (session == null) "Start key ceremony" else "Try again"
#
# has no `+` on its line and both branches are whole strings.
stripped = line.strip()
if stripped.endswith('+') or stripped.startswith('+'):
continue
found.append((start, end, value))
return found
def resource_name(text, taken):
slug = re.sub(r'[^a-z0-9]+', '_', text.lower()).strip('_')
words = slug.split('_')
name, out = '', []
for w in words:
if len(name) + len(w) + 1 > 44:
break
out.append(w)
name = '_'.join(out)
name = name or 'string'
if name[0].isdigit():
name = 's_' + name
base, i = name, 2
while name in taken:
name = f'{base}_{i}'
i += 1
return name
def xml_escape(text):
"""XML entities only.
Compose Resources is not aapt, and the difference is a shipped bug rather than a
detail. An earlier version of this escaped apostrophes as `\\'` and doubled `%`, which
is what android's resource compiler requires. Compose Resources does neither:
`getString` returned `Don\\'t sign`, backslash included, and
StringCatalogueJvmTest caught it.
It *does* process `\\n`, which the same test asserts -- so escape handling here is
partial rather than absent, and worth checking per escape rather than assuming a
family.
`%` is left alone. Nothing in this catalogue contains one, and if something does
later it only matters for an entry passed through `getString(resource, args)`.
"""
return text.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
def has_import(source, statement):
"""Whole-line match.
`statement in source` is wrong here and silently so: the accessors are named after
their strings, so `...resources.translate` is a prefix of
`...resources.translate_into_which_dialect`, and a substring test decides the import
is already present. The compiler then reports "Unresolved reference 'translate'" in a
file whose imports look complete.
"""
return any(line.strip() == statement for line in source.split('\n'))
def main():
occurrences = collections.defaultdict(list)
for root, _, files in os.walk(UI):
for f in sorted(files):
if not f.endswith('.kt'):
continue
path = os.path.join(root, f)
src = open(path, encoding='utf-8').read()
for start, _end, value in literals_in_text_calls(src):
occurrences[value].append((path, src[:start].count('\n') + 1))
taken, names = set(), {}
for text in sorted(occurrences):
names[text] = resource_name(text, taken)
taken.add(names[text])
total = sum(len(v) for v in occurrences.values())
print(f'{len(occurrences)} distinct strings, {total} occurrences')
if DRY:
for text in sorted(occurrences)[:10]:
print(f' {names[text]:46s} {text[:60]!r}')
print(' ...')
return 0
# Rewrite the call sites.
rewritten = 0
for root, _, files in os.walk(UI):
for f in sorted(files):
if not f.endswith('.kt'):
continue
path = os.path.join(root, f)
src = io.open(path, encoding='utf-8').read()
found = literals_in_text_calls(src)
changed = len(found)
# Right to left, so earlier offsets stay valid.
for start, end, value in reversed(found):
src = src[:start] + f'stringResource(Res.string.{names[value]})' + src[end:]
if changed:
for imp in ('import curare.composeapp.generated.resources.Res',
'import org.jetbrains.compose.resources.stringResource'):
if not has_import(src, imp):
lines = src.split('\n')
idx = max(i for i, l in enumerate(lines) if l.startswith('import '))
lines.insert(idx + 1, imp)
src = '\n'.join(lines)
# the generated accessors are one per string, under the same package
need = sorted({names[t] for t in occurrences
if any(p == path for p, _ in occurrences[t])})
lines = src.split('\n')
idx = max(i for i, l in enumerate(lines) if l.startswith('import '))
for nm in reversed(need):
imp = f'import curare.composeapp.generated.resources.{nm}'
if not has_import(src, imp):
lines.insert(idx + 1, imp)
src = '\n'.join(lines)
io.open(path, 'w', encoding='utf-8').write(src)
rewritten += changed
print(f'{rewritten} call sites rewritten')
# Write the catalogue.
existing = io.open(STRINGS, encoding='utf-8').read()
entries = '\n'.join(
f' <string name="{names[t]}">{xml_escape(t)}</string>'
for t in sorted(occurrences, key=lambda x: names[x]))
io.open(STRINGS, 'w', encoding='utf-8').write(
existing.replace('</resources>', entries + '\n</resources>'))
print(f'{len(occurrences)} entries written to {STRINGS}')
return 0
if __name__ == '__main__':
sys.exit(main())