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.mdnew file mode 100644index 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.++@josephfarinadiff --git a/packages/cli/api/build/kit/alternatives.test.mjs b/packages/cli/api/build/kit/alternatives.test.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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;