Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
// @vitest-environment node
/**
* Repo-wide guard: `formatCount` (`utils/formatters.js`) is the canonical
* grouped-integer renderer; a bare `.toLocaleString()` on a number is not.
*
* The two disagree in a user-visible way, not just stylistically (#7433):
*
* - Locale. `formatCount` pins `en-US` so a grouped count matches the `$`
* beside it (`formatUsd` also pins `en-US`). A bare `.toLocaleString()`
* follows the BROWSER locale, so on a non-`en` browser the same screen
* renders "1.234" in one span and "1,234" in the next.
* - Fractions. `.toLocaleString()` defaults to up to 3 fraction digits;
* `formatCount` rounds to 0.
* - Missing vs. zero. `formatCount(x)` renders '—' for an unmeasured count
* and takes `{ fallback: '0' }` where a measured zero is meant. The
* `.toLocaleString()` call sites each hand-rolled their own `?? 0` / `|| 0`
* coalesce, inconsistently.
*
* `new Date(x).toLocaleString()` is the same anti-pattern for a date/time
* render — root `AGENTS.md` forbids the inline form; route it through
* `formatDateTime` or the date helper matching the shape wanted.
*
* The rule is therefore structural rather than per-site: any `.toLocaleString(`
* call outside the allowlist fails this suite.
*
* Percent and USD have the same shape of drift (#9951): a hand-rolled
* `` `${x.toFixed(1)}%` `` renders `%` for a missing value and keeps trailing
* zeros, and `` `$${x.toFixed(2)}` `` drops thousands grouping and the sign
* handling `formatUsd` owns. Both route through `formatPercent` / `formatUsd`;
* a `toFixed(...)` whose next token is `%`, or whose result is the amount
* after a `$`, fails this suite. `formatters.js` is exempt (it implements them).
*
* ## Allowlist
*
* - `src/utils/formatters.js` — it IS the canonical implementation (`formatCount`
* grouping numbers; `formatDateTime`/`formatWeekdayTime`/`formatEventDateTime`
* rendering dates through the browser locale on purpose).
* - `src/components/usage/UsageMeter.jsx` — `formatResetsAt` renders a quota
* reset as a compact "Sep 16, 1:30 AM" (month + day + time, no year, no
* weekday). No existing helper matches that shape, and it has exactly one
* caller — same reasoning `storageConventions.test.js` uses to allowlist
* `timeWindow.js` rather than add a single-caller helper. Move it off this
* allowlist (into a named `utils/formatters.js` helper) the day a second
* caller wants the same shape.
*
* ## What this guard CANNOT see
*
* It is a source grep, not an AST pass. Comments are stripped (both forms,
* with a `:` lookbehind so a `https://` URL is not read as a line comment) so
* prose mentioning "toLocaleString" does not trip the guard; string literals
* are NOT stripped. Aliasing (`const f = n.toLocaleString`), a computed
* member (`n['toLocaleString']()`), or a call funneled through a helper in
* another file all slip through. Those are unusual enough here that the grep
* earns its keep; closing them means moving to an AST pass.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { trackedSourceFiles } from './test/trackedFiles.js';
import { stripComments } from './test/stripComments.js';
const CLIENT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const WRAPPER_FILE = 'src/utils/formatters.js';
const ALLOWED = [
WRAPPER_FILE,
'src/components/usage/UsageMeter.jsx',
];
const isAllowed = (file) => ALLOWED.includes(file);
/**
* `.toLocaleString(` preceded by a member-access dot or `?.`. Matches with or
* without call arguments — a locale-pinned `.toLocaleString('en-US')` is the
* same anti-pattern as a bare `.toLocaleString()`, just already half-fixed.
*/
const RAW_TO_LOCALE_STRING = /\??\.\s*toLocaleString\s*\(/g;
/** Raw `.toLocaleString(` calls in `src`, as matched snippets. */
export function findRawToLocaleString(src) {
return [...stripComments(src).matchAll(RAW_TO_LOCALE_STRING)].map((m) => m[0].trim());
}
/**
* `toFixed(n)` immediately followed by a `%` — in a template (`${x.toFixed(1)}%`),
* in JSX text (`{x.toFixed(1)}%`), or concatenated (`x.toFixed(1) + '%'`).
*/
const HAND_ROLLED_PERCENT = /\.toFixed\s*\([^)]*\)\s*(?:\}|\+\s*['"`])\s*%/g;
/**
* `toFixed(n)` rendered as a dollar amount: `$${x.toFixed(2)}` in a template, or
* JSX text `${x.toFixed(2)}` (a `$` right before the expression container). The
* JSX form is only read on a line with no backtick before it, because inside a
* template literal a bare `${x.toFixed(2)}` is ordinary interpolation.
*/
const TEMPLATE_USD = /\$\$\{[^}]*\.toFixed\s*\(/g;
const JSX_USD = /^[^`]*\$\{[^}]*\.toFixed\s*\(/;
/** Hand-rolled `toFixed` percent / USD renders in `src`, as matched snippets. */
export function findHandRolledPercentOrUsd(src) {
const code = stripComments(src);
const hits = [...code.matchAll(HAND_ROLLED_PERCENT), ...code.matchAll(TEMPLATE_USD)].map((m) => m[0].trim());
for (const line of code.split('\n')) {
if (JSX_USD.test(line)) hits.push(line.trim());
}
return hits;
}
describe('Number/date formatting goes through utils/formatters', () => {
it('has no raw .toLocaleString( calls outside the wrapper and its allowlist', () => {
const files = trackedSourceFiles(CLIENT_ROOT);
// A broken `git ls-files` (wrong cwd, detached checkout) would otherwise make
// this guard pass by scanning nothing at all.
expect(files.length).toBeGreaterThan(100);
const violations = [];
for (const file of files) {
if (isAllowed(file)) continue;
const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
for (const hit of findRawToLocaleString(src)) violations.push(`${file}: ${hit}`);
}
expect(
violations,
'These files call `.toLocaleString(` directly. A NUMBER should render through '
+ '`formatCount` (thousands-grouped, en-US-pinned, matches the `$` beside it) — '
+ 'pass `{ fallback: \'0\' }` only where an ABSENT count should read as zero. A '
+ 'DATE should render through `formatDateTime` or the helper matching the shape '
+ 'wanted (see the exports list in `utils/formatters.js`).\n'
+ `Offenders:\n ${violations.join('\n ')}`,
).toEqual([]);
});
it('has no hand-rolled toFixed percent or USD outside utils/formatters', () => {
const files = trackedSourceFiles(CLIENT_ROOT);
expect(files.length).toBeGreaterThan(100);
const violations = [];
for (const file of files) {
if (file === WRAPPER_FILE) continue;
const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
for (const hit of findHandRolledPercentOrUsd(src)) violations.push(`${file}: ${hit}`);
}
expect(
violations,
'These files format a percentage or dollar amount with `toFixed`. Use '
+ '`formatPercent(value, { decimals })` (value already 0–100; multiply a fraction by 100 first) '
+ 'or `formatUsd(value)` from `utils/formatters` — they render a missing value as `—`, '
+ 'drop float noise, and group thousands.\n'
+ `Offenders:\n ${violations.join('\n ')}`,
).toEqual([]);
});
it('flags a hand-rolled percent or USD shape and accepts the formatters', () => {
expect(findHandRolledPercentOrUsd('const s = `${x.toFixed(1)}%`;')).toHaveLength(1);
expect(findHandRolledPercentOrUsd('<span>{p.cpu?.toFixed(0)}% CPU</span>')).toHaveLength(1);
expect(findHandRolledPercentOrUsd("const s = x.toFixed(1) + '%';")).toHaveLength(1);
expect(findHandRolledPercentOrUsd('parts.push(`$${usage.costUsd.toFixed(4)}`);')).toHaveLength(1);
expect(findHandRolledPercentOrUsd('<b>${spend.spentUsd.toFixed(2)}</b>')).toHaveLength(1);
expect(findHandRolledPercentOrUsd('formatPercent(x * 100, { decimals: 0 })')).toEqual([]);
expect(findHandRolledPercentOrUsd('formatUsd(spend.spentUsd)')).toEqual([]);
// Non-percent / non-currency `toFixed` uses stay legal: seconds, SVG coordinates,
// and a plain template interpolation of a number.
expect(findHandRolledPercentOrUsd('`${t.toFixed(2)}s / ${d.toFixed(1)}s`')).toEqual([]);
expect(findHandRolledPercentOrUsd('`${x.toFixed(1)},${y.toFixed(1)}`')).toEqual([]);
expect(findHandRolledPercentOrUsd('// shows `${x.toFixed(1)}%` today')).toEqual([]);
});
// Guards the guard: if the detector stops recognizing the call, the scan
// above goes vacuously green and the bug class walks straight back in.
it('flags every call shape and ignores prose that merely names the method', () => {
expect(findRawToLocaleString('n.toLocaleString()')).toEqual(['.toLocaleString(']);
expect(findRawToLocaleString("n.toLocaleString('en-US')")).toEqual(['.toLocaleString(']);
expect(findRawToLocaleString('count?.toLocaleString()')).toEqual(['?.toLocaleString(']);
expect(findRawToLocaleString('d.toLocaleString(undefined, { month: "short" })')).toEqual(['.toLocaleString(']);
expect(findRawToLocaleString('formatCount(n)')).toEqual([]);
expect(findRawToLocaleString('formatDateTime(d)')).toEqual([]);
// A comment naming the method is not a call.
expect(findRawToLocaleString(
'// prefer formatCount over toLocaleString() for a user-facing count\nconst x = 1;',
)).toEqual([]);
});
// The allowlist must keep naming files that really exist and really carry the
// shape — otherwise a rename turns an exemption into silent dead config.
it('allowlists only files that exist and still call toLocaleString directly', () => {
const tracked = trackedSourceFiles(CLIENT_ROOT);
for (const file of ALLOWED) {
expect(tracked, `${file} is allowlisted but no longer tracked`).toContain(file);
const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
expect(
findRawToLocaleString(src).length,
`${file} no longer calls toLocaleString directly — drop it from the allowlist`,
).toBeGreaterThan(0);
}
});
});