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
// Pure, dependency-free helpers for the `naming.dissimilar-names` editorial
// check (#1291). Everything here operates on plain strings so it can be unit
// tested in isolation and reused by any check that needs to reason about how
// confusable two character names are. No imports — keeps the registry pure.
// Lowercased letters only ("O'Brien" → "obrien"), the canonical IDENTITY form.
// Used as a dedup/identity key across the editorial checks, so it must NOT strip
// articles — "the reader" and "a reader" are distinct identities. The similarity
// check compares on `comparisonName` (below) instead.
export const normalizeName = (s) => String(s || '').toLowerCase().replace(/[^a-z]/g, '');
// Leading-article stripper for the *confusability* comparison only. A cast that
// uses epithet names ("THE CABARET SINGER", "THE CHAPTER SEVENTEEN READER") would
// otherwise read as 60+ names all starting with "the" — every pair sharing the
// first letter AND the 3-char opening, which on its own trips the 2-signal gate
// and floods the check. Comparing on the article-stripped form ("cabaret singer"
// / "chapter seventeen reader") judges the names readers actually disambiguate
// on. Only strips when something remains after the article (so a character
// literally named "The" still compares as "the").
const LEADING_ARTICLE_RE = /^(?:the|a|an)\s+/i;
export function stripLeadingArticle(s) {
const str = String(s || '').trim();
const stripped = str.replace(LEADING_ARTICLE_RE, '');
return stripped.trim() ? stripped : str;
}
// Normalized form the similarity signals compare against: article-stripped, then
// reduced to lowercased letters. ("THE CABARET SINGER" → "cabaretsinger".)
export const comparisonName = (s) => normalizeName(stripLeadingArticle(s));
// The ordered vowel skeleton ("Rachel" → "ae"). Two names sharing this read as
// rhythmically similar even when the consonants differ (Blake / Jane → "ae").
export const vowelSkeleton = (s) => normalizeName(s).replace(/[^aeiou]/g, '');
// Classic Soundex phonetic key (e.g. "Smith"/"Smyth" → "S530"). A cheap stand-in
// for full double-metaphone that needs no dependency: two names with the same key
// sound alike enough to be confused when read aloud. Returns '' for input with no
// letters so a nameless entry never collides with another.
const SOUNDEX_CODES = {
b: '1', f: '1', p: '1', v: '1',
c: '2', g: '2', j: '2', k: '2', q: '2', s: '2', x: '2', z: '2',
d: '3', t: '3',
l: '4',
m: '5', n: '5',
r: '6',
};
export function soundex(s) {
const letters = normalizeName(s);
if (!letters) return '';
const first = letters[0];
let out = '';
// Walk from the second letter, collapsing runs of the same digit. Per the
// standard (NARA) algorithm: a vowel (or y) separates a run so two same-coded
// consonants split by it both emit, while h and w are TRANSPARENT — they
// neither emit nor break a run, so consonants separated only by h/w collapse to
// one digit (e.g. "Ashcraft" → A261, the s/c pair split by h stays a single 2).
// The first letter's own code is dropped but seeds `prev` so an immediately
// following same-coded consonant collapses into it.
let prev = SOUNDEX_CODES[first];
for (let i = 1; i < letters.length && out.length < 3; i += 1) {
const ch = letters[i];
const code = SOUNDEX_CODES[ch];
if (code !== undefined) {
if (code !== prev) out += code;
prev = code;
} else if (ch !== 'h' && ch !== 'w') {
prev = undefined; // vowel or y — separator
}
// h / w: transparent — leave `prev` unchanged
}
return (first + out).padEnd(4, '0').toUpperCase();
}
// Levenshtein edit distance — the minimum single-character insert/delete/substitute
// edits to turn `a` into `b`. Operates on the normalized forms so casing and
// punctuation don't inflate the distance. O(min(a,b)) space.
export function levenshtein(a, b) {
const s = normalizeName(a);
const t = normalizeName(b);
if (s === t) return 0;
if (!s.length) return t.length;
if (!t.length) return s.length;
let prev = Array.from({ length: t.length + 1 }, (_, i) => i);
let curr = new Array(t.length + 1);
for (let i = 1; i <= s.length; i += 1) {
curr[0] = i;
for (let j = 1; j <= t.length; j += 1) {
const cost = s[i - 1] === t[j - 1] ? 0 : 1;
curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
}
[prev, curr] = [curr, prev];
}
return prev[t.length];
}
// Default thresholds for `nameSimilaritySignals` — mirrored by the registry
// check's configSchema defaults so the helper is usable standalone with sensible
// behavior and the UI knobs map 1:1 onto these option keys.
export const DEFAULT_SIGNAL_OPTS = Object.freeze({
minEditDistance: 1, // flag pairs within this Levenshtein distance (0 disables)
flagSameLength: true,
vowelSkeletonCollision: true,
usePhonetic: true,
});
// Reduce a normalized (letters-only) noun to a crude singular stem so a name and
// its own plural ("reader"/"readers", "poet"/"poets", "drone"/"drones",
// "city"/"cities") map to the same stem. Deliberately conservative — it only
// undoes the three common English plural inflections and never shortens below 3
// letters (so "is"/"" or "as"/"a" can't collapse). Not linguistically complete;
// just enough to recognize a singular/plural variant of the SAME word.
function singularStem(letters) {
if (typeof letters !== 'string' || letters.length < 4) return letters;
if (letters.endsWith('ies')) return `${letters.slice(0, -3)}y`; // cities → city
// `-es` only forms a plural after a sibilant (s/x/z, ch/sh): boxes→box,
// dishes→dish, churches→church. Gating on the sibilant (not just length)
// stops a singular name that merely ends in "es" from being over-stemmed —
// "James"→"jam", "Charles"→"charl" — which could then false-collapse onto an
// unrelated short name and wrongly suppress a real confusability pair.
if (letters.endsWith('es') && /(s|x|z|ch|sh)es$/.test(letters)) return letters.slice(0, -2);
if (letters.endsWith('s') && !letters.endsWith('ss')) return letters.slice(0, -1); // poets → poet
return letters;
}
// Are two normalized names singular/plural variants of the SAME noun (e.g.
// "reader"/"readers", "poet"/"poets")? Such a pair is a deliberate count
// distinction a reader parses effortlessly (an individual vs a crowd), NOT a
// confusable near-typo — so the check must not flag it. Requires the two to
// actually DIFFER (equal forms are handled separately) and to share a singular
// stem.
function isSingularPluralPair(la, lb) {
if (!la || !lb || la === lb) return false;
return singularStem(la) === singularStem(lb);
}
// Analyze a name pair in a single pass: the confusability `signals` (each one a
// reason a reader could blur the two on the page) plus the two metrics that also
// drive the check's severity — the Levenshtein `distance` and whether the names
// share a `phoneticMatch`. Computing them here once lets the caller score severity
// without re-running soundex/levenshtein. Returns empty/Infinity/false when either
// name has no letters, the two normalize equal, or they're singular/plural
// variants of the same noun.
export function analyzeNamePair(a, b, opts = {}) {
const { minEditDistance, flagSameLength, vowelSkeletonCollision, usePhonetic } = {
...DEFAULT_SIGNAL_OPTS,
...opts,
};
// Compare on the article-stripped form so epithet casts ("THE …") don't all
// collide on their leading article (see comparisonName).
const la = comparisonName(a);
const lb = comparisonName(b);
if (!la || !lb || la === lb) return { signals: [], distance: Infinity, phoneticMatch: false };
// A name and its own plural is a deliberate, readable count distinction, not a
// confusion — treat it as inert (same as equal forms).
if (isSingularPluralPair(la, lb)) return { signals: [], distance: Infinity, phoneticMatch: false };
const signals = [];
// "same opening" (first 3 chars) STRICTLY IMPLIES "same first letter", so
// counting both double-counts one similarity: any shared 3-char prefix would
// alone reach the default 2-signal gate. Emit the more specific signal when it
// applies, otherwise fall back to the first-letter signal — never both.
const sameOpening = la.length >= 3 && lb.length >= 3 && la.slice(0, 3) === lb.slice(0, 3);
if (sameOpening) signals.push('same opening');
else if (la[0] === lb[0]) signals.push('same first letter');
if (flagSameLength && la.length === lb.length) signals.push('same length');
if (vowelSkeletonCollision) {
const vsa = vowelSkeleton(la);
if (vsa && vsa === vowelSkeleton(lb)) signals.push('same vowel pattern');
}
if (la.length >= 2 && la.slice(-2) === lb.slice(-2)) signals.push('same ending');
const distance = levenshtein(la, lb);
if (minEditDistance > 0 && distance <= minEditDistance) {
signals.push(`near-identical spelling (edit distance ${distance})`);
}
const ka = usePhonetic ? soundex(la) : '';
const phoneticMatch = ka !== '' && ka === soundex(lb);
if (phoneticMatch) signals.push('same phonetic key');
return { signals, distance, phoneticMatch };
}
// The confusability signal list for a name pair — the `signals` view of
// analyzeNamePair, for callers (and tests) that only need the reasons.
export const nameSimilaritySignals = (a, b, opts = {}) => analyzeNamePair(a, b, opts).signals;
// A first-letter histogram over a list of names: Map<letter, name[]> keyed by the
// lowercased first letter of the article-stripped name (entries with no letters
// are skipped). The check uses this to spot first-letter crowding — a cast where
// many names start the same way. Keying on the article-stripped form keeps an
// epithet cast ("THE CABARET SINGER", "THE CHAPTER SEVENTEEN READER") from all
// crowding under "T" on their shared leading article.
export function firstLetterHistogram(names) {
const hist = new Map();
for (const name of names) {
const norm = comparisonName(name);
if (!norm) continue;
const letter = norm[0];
if (!hist.has(letter)) hist.set(letter, []);
hist.get(letter).push(name);
}
return hist;
}
// First-letter clusters worth flagging: letters shared by at least `minCount`
// names AND by at least `maxRatio` of the cast. Returns [{ letter, names, ratio }]
// sorted densest-first so the worst crowding surfaces as the first finding.
export function findFirstLetterClusters(names, { minCount = 3, maxRatio = 0.4 } = {}) {
const total = names.filter((n) => comparisonName(n)).length;
if (!total) return [];
const clusters = [];
for (const [letter, group] of firstLetterHistogram(names)) {
const ratio = group.length / total;
if (group.length >= minCount && ratio >= maxRatio) {
clusters.push({ letter, names: group, ratio });
}
}
return clusters.sort((x, y) => y.ratio - x.ratio || y.names.length - x.names.length);
}