Skip to content

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

TypeScript

build: name the alternatives in the order the start is chosen from (#10357)

Joeydcafd9610043
diff --git a/.changeset/build-alternatives-blend-order.md b/.changeset/build-alternatives-blend-order.md
new file mode 100644
index 0000000000..8f27b596f8
--- /dev/null
+++ b/.changeset/build-alternatives-blend-order.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx build` names its two alternative page templates in the same order it chooses the start from, so the three templates it shows for a whole page are its best three. The start, the number of alternatives, the blocks and the JSON shape are unchanged.
+
+@josephfarina
diff --git a/packages/cli/api/build/kit/alternatives.test.mjs b/packages/cli/api/build/kit/alternatives.test.mjs
new file mode 100644
index 0000000000..19a96bad92
--- /dev/null
+++ b/packages/cli/api/build/kit/alternatives.test.mjs
@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A whole page's alternatives come from the same ranking as its start:
+ * the word weights' blend orders the ranker's candidates, so the three
+ * templates build names are the blend's best three. Parts keep the ranker's
+ * order, and the start and the number of alternatives are unchanged.
+ */
+
+import {describe, expect, it} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {build} from '../build.mjs';
+import {loadTemplates, loadWeights} from '../_adapter.mjs';
+import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
+import {blendOrder} from './weights.mjs';
+
+const REPO = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../../../..',
+);
+
+describe('build alternatives', () => {
+ it('follow the blend order for a whole page', async () => {
+ const idea = 'analytics dashboard with retention cohorts';
+ const {data} = await build(idea, {cwd: REPO});
+ const catalog = (await loadTemplates(REPO)).pages;
+ const ranked = rankPages(idea, catalog);
+ const order = blendOrder(
+ idea,
+ ranked,
+ pickStart(ranked, 'page'),
+ catalog,
+ loadWeights(),
+ );
+ expect(order).not.toBeNull();
+ const start = /** @type {NonNullable<typeof data.start>} */ (data.start);
+ const eligible = new Set(
+ pickAlternatives(ranked, start.name, ranked.length).map(r => r.name),
+ );
+ const expected = /** @type {string[]} */ (order)
+ .filter(name => eligible.has(name))
+ .slice(0, 2);
+ expect(start.alternatives.map(a => a.name)).toEqual(expected);
+ });
+
+ it('keep the ranker order for a part of a page', async () => {
+ const idea = 'a date range picker';
+ const {data} = await build(idea, {cwd: REPO});
+ const catalog = (await loadTemplates(REPO)).pages;
+ const ranked = rankPages(idea, catalog);
+ const start = /** @type {NonNullable<typeof data.start>} */ (data.start);
+ expect(start.alternatives.map(a => a.name)).toEqual(
+ pickAlternatives(ranked, start.name).map(r => r.name),
+ );
+ });
+
+ it('keep a template the weights do not list in its ranker slot', async () => {
+ const {pickStartAlternatives} = await import('./start.mjs');
+ const catalog = (await loadTemplates(REPO)).pages;
+ const listed = new Set(loadWeights()?.candidates ?? []);
+ const idea = 'compare plans side by side in a table';
+ const ranked = rankPages(idea, catalog);
+ const start = /** @type {any} */ (
+ (await build(idea, {cwd: REPO})).data.start
+ );
+ const byRanker = pickAlternatives(ranked, start.name);
+ const chosen = pickStartAlternatives(
+ ranked,
+ 'page',
+ start.name,
+ catalog,
+ idea,
+ ).map(r => r.name);
+ for (const r of byRanker)
+ if (!listed.has(r.name)) expect(chosen).toContain(r.name);
+ });
+});
diff --git a/packages/cli/api/build/kit/signals.mjs b/packages/cli/api/build/kit/signals.mjs
index 8a54fd4128..e46580538d 100644
--- a/packages/cli/api/build/kit/signals.mjs
+++ b/packages/cli/api/build/kit/signals.mjs
@@ -27,8 +27,8 @@ import {
templateSetupNotes,
} from '../_adapter.mjs';
import {ideaKind} from './kind.mjs';
-import {pickAlternatives, rankPages} from './rank.mjs';
-import {asTemplate, chooseStart} from './start.mjs';
+import {rankPages} from './rank.mjs';
+import {asTemplate, chooseStart, pickStartAlternatives} from './start.mjs';
/** A page at/above this score is a confident direct match. */
const PAGE_DIRECT = 95;
@@ -247,7 +247,13 @@ export async function kitSignals(query, options = {}) {
/** @type {BuildStart | null} */
const start = chosen && {
...chosen,
- alternatives: pickAlternatives(ranked, chosen.name).flatMap(r => {
+ alternatives: pickStartAlternatives(
+ ranked,
+ kind,
+ chosen.name,
+ catalog,
+ query,
+ ).flatMap(r => {
const t = catalog.find(c => c.name === r.name);
return t ? [asTemplate(t)] : [];
}),
diff --git a/packages/cli/api/build/kit/start.mjs b/packages/cli/api/build/kit/start.mjs
index 1e3cd9c6e9..26d922f673 100644
--- a/packages/cli/api/build/kit/start.mjs
+++ b/packages/cli/api/build/kit/start.mjs
@@ -7,8 +7,8 @@
import {loadWeights} from '../_adapter.mjs';
import {asksForNewPage} from './kind.mjs';
-import {pickStart} from './rank.mjs';
-import {weighStart} from './weights.mjs';
+import {pickAlternatives, pickStart} from './rank.mjs';
+import {blendOrder, weighStart} from './weights.mjs';
/**
* @typedef {import('../../search/search.type.mjs').SearchResultEntry} SearchResultEntry
@@ -161,3 +161,50 @@ export function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
}
return null;
}
+
+/**
+ * The next best page templates beside the start (spec:AST-048/FR7), in the
+ * order the start itself is chosen from. The candidates are the ranker's (a
+ * template with matched words and half a start's score); a whole page orders
+ * them by the word weights' blend, the same ranking that picks its start, so
+ * the templates build names are the blend's best. The blend knows only the
+ * templates its tables list: one it does not list (a shell, an integration's
+ * template, or one added since the tables were fit) keeps the place the ranker
+ * gives it, so a new template is never pushed out by tables that have not seen
+ * it. A part or an edit, or a project without weights, keeps the ranker's
+ * order.
+ * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').IdeaKind} kind
+ * @param {string} startName
+ * @param {PageTemplate[]} catalog
+ * @param {string} idea
+ * @returns {import('./rank.mjs').RankedPage[]}
+ */
+export function pickStartAlternatives(ranked, kind, startName, catalog, idea) {
+ const eligible = pickAlternatives(ranked, startName, ranked.length);
+ const byRanker = eligible.slice(0, 2);
+ if (kind !== 'page') return byRanker;
+ const weights = loadWeights();
+ const order = blendOrder(
+ idea,
+ ranked,
+ pickStart(ranked, kind),
+ catalog,
+ weights,
+ );
+ if (!weights || !order) return byRanker;
+ const listed = new Set(weights.candidates);
+ const at = new Map(order.map((name, i) => [name, i]));
+ // Unlisted templates keep their ranker slot; the rest follow the blend.
+ /** @type {(import('./rank.mjs').RankedPage | null)[]} */
+ const slots = byRanker.map(r => (listed.has(r.name) ? null : r));
+ const rest = eligible
+ .filter(r => listed.has(r.name) && at.has(r.name))
+ .sort(
+ (a, b) =>
+ /** @type {number} */ (at.get(a.name)) -
+ /** @type {number} */ (at.get(b.name)),
+ );
+ const out = slots.map(slot => slot ?? rest.shift() ?? null);
+ return /** @type {import('./rank.mjs').RankedPage[]} */ (out.filter(Boolean));
+}
diff --git a/packages/cli/api/build/kit/weights.mjs b/packages/cli/api/build/kit/weights.mjs
index 8cdadee6de..afda39f824 100644
--- a/packages/cli/api/build/kit/weights.mjs
+++ b/packages/cli/api/build/kit/weights.mjs
@@ -281,24 +281,16 @@ function familyAt(name, catalog, order) {
}
/**
- * Where an idea starts, by the blended weights.
+ * The blend's score for every candidate: the app shell and every ready,
+ * non-shell template, the table's first, then any the table does not list.
* @param {string} idea
- * @param {import('./rank.mjs').RankedPage[]} ranked the ranker's output for the idea
- * @param {import('./rank.mjs').RankedPage | null} pick the ranker's own start
- * @param {DescribedTemplate[]} catalog the project's ready page templates
- * @param {{weights?: WeightsFile | null, newPage?: boolean}} [options]
- * `newPage`: the idea asks for a new page (rank.mjs `asksForNewPage`)
- * @returns {string | null | undefined} a template id, null for the app shell,
- * undefined without weights
+ * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').RankedPage | null} pick
+ * @param {DescribedTemplate[]} catalog
+ * @param {WeightsFile} weights
+ * @returns {{cands: string[], scores: number[], position: Map<string, number>}}
*/
-export function weighStart(
- idea,
- ranked,
- pick,
- catalog,
- {weights = null, newPage = false} = {},
-) {
- if (!weights) return undefined;
+function blend(idea, ranked, pick, catalog, weights) {
const ready = new Set(catalog.map(t => t.name));
const shellIds = new Set(
ranked.filter(r => r.family === SHELL_FAMILY).map(r => r.name),
@@ -335,6 +327,50 @@ export function weighStart(
for (const f of feats) for (const x of f[i]) s += x * weights.blend[j++];
return s + (c === SHELL ? 1 : 0) * weights.blend[j];
});
+ return {cands, scores, position};
+}
+
+/**
+ * Every ready, non-shell template in the blend's own order, best first: the
+ * order the page start is chosen from, so the alternatives build names beside
+ * the start come from the same ranking. Null without weights.
+ * @param {string} idea
+ * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').RankedPage | null} pick
+ * @param {DescribedTemplate[]} catalog
+ * @param {WeightsFile | null} weights
+ * @returns {string[] | null}
+ */
+export function blendOrder(idea, ranked, pick, catalog, weights) {
+ if (!weights) return null;
+ const {cands, scores} = blend(idea, ranked, pick, catalog, weights);
+ return cands
+ .map((c, i) => ({c, s: scores[i], i}))
+ .filter(x => x.c !== SHELL)
+ .sort((x, y) => y.s - x.s || x.i - y.i)
+ .map(x => x.c);
+}
+
+/**
+ * Where an idea starts, by the blended weights.
+ * @param {string} idea
+ * @param {import('./rank.mjs').RankedPage[]} ranked the ranker's output for the idea
+ * @param {import('./rank.mjs').RankedPage | null} pick the ranker's own start
+ * @param {DescribedTemplate[]} catalog the project's ready page templates
+ * @param {{weights?: WeightsFile | null, newPage?: boolean}} [options]
+ * `newPage`: the idea asks for a new page (rank.mjs `asksForNewPage`)
+ * @returns {string | null | undefined} a template id, null for the app shell,
+ * undefined without weights
+ */
+export function weighStart(
+ idea,
+ ranked,
+ pick,
+ catalog,
+ {weights = null, newPage = false} = {},
+) {
+ if (!weights) return undefined;
+ const {cands, scores, position} = blend(idea, ranked, pick, catalog, weights);
/** @param {(c: string) => boolean} ok */
const best = ok => {
let at = -1;