Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): build keeps a leading variant when its family base matches only the family word (#10431)

Cindy Zhangb6c103808e86
diff --git a/.changeset/ranker-family-base-start-terms.md b/.changeset/ranker-family-base-start-terms.md
new file mode 100644
index 0000000000..b0ee1f4a67
--- /dev/null
+++ b/.changeset/ranker-family-base-start-terms.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx build`: when an idea names a family only after its head ("a saml for a login") and the family's base template matches no other word, the variant that outranks the base now stays the start (`login-sso`, not `login`), so adding page templates no longer flips such ideas to the base. Ideas that name the family in their head ("saml login") start as before.
+
+@mego1123
diff --git a/packages/cli/api/build/kit/rank.mjs b/packages/cli/api/build/kit/rank.mjs
index 72b1d07a7c..182d11042b 100644
--- a/packages/cli/api/build/kit/rank.mjs
+++ b/packages/cli/api/build/kit/rank.mjs
@@ -41,7 +41,9 @@
* `settings`) is that family's default. A variant displaces it only with two
* matched terms of its own ("a small comparison note" does not make a
* dashboard the comparison dashboard), and a base too weak to start on its
- * own displaces no variant ("a funnel for a dashboard" is the funnel).
+ * own displaces no variant ("a funnel for a dashboard" is the funnel) —
+ * unless the idea names its family in the head, which is start evidence on
+ * its own ("saml login" stays the login page).
*/
import {
@@ -219,7 +221,8 @@ export function rankPages(query, pages) {
}
}
const familyNamed = namedFamilies.has(family);
- if (headFamilies.has(family)) score += HEAD_FAMILY;
+ const headNamed = headFamilies.has(family);
+ if (headNamed) score += HEAD_FAMILY;
else if (familyNamed) score += BODY_FAMILY;
const base = normalized(page.name) === normalized(family);
if (familyNamed && base) score += FAMILY_BASE;
@@ -228,6 +231,7 @@ export function rankPages(query, pages) {
score,
hits,
familyNamed,
+ headNamed,
containerMatched,
family,
base,
@@ -246,7 +250,14 @@ export function rankPages(query, pages) {
/**
* Put a named family's base template ahead of the variant that outranks it,
* unless the variant matched START_TERMS terms the base did not, or the base
- * scores too little to start on its own.
+ * cannot start on its own: too little score, or too few matched terms. The
+ * head names the exception: a family word in the idea's head is start
+ * evidence on its own — the same evidence pickStart accepts in place of a
+ * second term — so a head-named one-term base can still take the lead ("saml
+ * login" is the login page, not the SSO flow). A base whose family the idea
+ * names only elsewhere still needs a second term: score alone drifts upward
+ * as the catalog grows (idf rises with page count) and would eventually let a
+ * one-term base displace its variant, while hits do not drift.
* @param {RankedPage[]} ranked
* @returns {RankedPage[]}
*/
@@ -254,7 +265,13 @@ function baseFirst(ranked) {
const top = ranked[0];
if (!top || top.base || !top.familyNamed) return ranked;
const base = ranked.find(r => r.base && r.family === top.family);
- if (!base || base.score < START_SCORE) return ranked;
+ if (
+ !base ||
+ base.score < START_SCORE ||
+ (base.hits < START_TERMS && !base.headNamed)
+ ) {
+ return ranked;
+ }
const own = [...top.matched].filter(t => !base.matched.has(t)).length;
return own >= START_TERMS
? ranked
diff --git a/packages/cli/api/build/kit/rank.test.mjs b/packages/cli/api/build/kit/rank.test.mjs
index 648fe6aa78..2c3ea88e30 100644
--- a/packages/cli/api/build/kit/rank.test.mjs
+++ b/packages/cli/api/build/kit/rank.test.mjs
@@ -97,6 +97,23 @@ describe('rankPages on the shipped page templates', () => {
);
});
+ it('keeps that variant, and lets a head-named base lead, as the catalog grows', async () => {
+ // More pages raise every word's rarity weight, so a one-word base gains
+ // score with each new template. Matched terms do not grow.
+ const filler = [1, 2, 3].map(n =>
+ page(`filler-${n}`, `Content - Filler ${n}`, `A page about topic${n}.`),
+ );
+ const pages = [...(await loadPageTemplates(REPO)), ...filler];
+ /** @param {string} query */
+ const grownStart = query => pickStart(rankPages(query, pages))?.name;
+ expect(grownStart('a funnel for a dashboard')).toBe(
+ 'dashboard-cohort-funnel',
+ );
+ expect(grownStart('a saml for a login')).toBe('login-sso');
+ // The family word in the head is start evidence on its own.
+ expect(grownStart('saml login')).toBe('login');
+ });
+
it('does not start from one rare word', async () => {
// "board" is the kanban board's own word; a game board is not a kanban.
expect(
diff --git a/packages/cli/api/build/kit/words.mjs b/packages/cli/api/build/kit/words.mjs
index 4eb0c0ac64..f45176e8b7 100644
--- a/packages/cli/api/build/kit/words.mjs
+++ b/packages/cli/api/build/kit/words.mjs
@@ -163,7 +163,7 @@ export const SYNONYMS_OF = (() => {
/**
* @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
* @typedef {import('../_adapter.mjs').ComponentWords} ComponentWords
- * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
+ * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, headNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
* @typedef {'page' | 'part' | 'edit'} IdeaKind
*/