An open source design system that's fully customizable and agent ready
TypeScript
build: a template the word weights do not list competes on its own words (#7901)
Joey425f762d673d
diff --git a/.changeset/build-unlisted-template-own-words.md b/.changeset/build-unlisted-template-own-words.mdnew file mode 100644index 0000000000..27055e877b--- /dev/null+++ b/.changeset/build-unlisted-template-own-words.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx build` starts from a page template its word weights do not list (an integration's template, or one added since the weights were fit) only when the request names as many words of that template's own display name, category and keywords (search's stopwords aside) as of the best listed template, or names that template's family (the first part of its category) before the listed template's family and at most two fewer of its words; otherwise it starts from that listed template and offers the other as the first alternative.++@josephfarinadiff --git a/packages/cli/api/build/kit/weights.mjs b/packages/cli/api/build/kit/weights.mjsindex bf499774ba..8cdadee6de 100644--- a/packages/cli/api/build/kit/weights.mjs+++ b/packages/cli/api/build/kit/weights.mjs@@ -14,11 +14,13 @@* from, null for the app shell, or undefined when no table is available, in* which case the ranker's own pick stands.* @position Beside rank.mjs (api/build/kit/); kit.mjs calls it for every- * whole page (a part or an edit follows the ranker's placement rules). The- * ranker's pick of a template the tables do not list stands, so a new- * template can start a build.+ * whole page (a part or an edit follows the ranker's placement rules). A+ * template the tables do not list competes on its own descriptor's words+ * (`ownWords`), so a new template can start a build.*/+import {STOPWORDS} from '../../search/search.mjs';+/** The app shell, as one candidate. */export const SHELL = 'SHELL';const SHELL_FAMILY = 'Shell';@@ -225,12 +227,65 @@ function memberFeatures(v) {]);}+/**+ * @typedef {object} DescribedTemplate+ * @property {string} name+ * @property {string} [displayName]+ * @property {string} [category]+ * @property {string[]} [keywords]+ */++/**+ * How many of the idea's stemmed words a template's own descriptor names: its+ * display name, its category, and its keywords, less search's stopwords.+ * @param {string} name+ * @param {DescribedTemplate[]} catalog+ * @param {Set<string>} words the idea's stemmed words, less search's stopwords+ */+function ownWords(name, catalog, words) {+ const t = catalog.find(c => c.name === name);+ if (!t) return 0;+ // Search's stopwords are no evidence: "to" in a "to-do list" keyword must+ // not answer the "to" of "rows to track orders".+ const own = new Set(+ weightWords(+ [t.displayName ?? '', t.category ?? '', ...(t.keywords ?? [])].join(' '),+ )+ .filter(w => !STOPWORDS.has(w))+ .map(stem),+ );+ let n = 0;+ for (const w of words) if (own.has(w)) n++;+ return n;+}++/** How many fewer own words a template whose family the idea names first may+ * name than the listed template it competes with, and still start. */+const FAMILY_SLACK = 2;++/**+ * Where the idea first names a template's family, the part of its category+ * before ` - ` ("Dashboard" in "Dashboard - Analytics"): the index of that+ * word among the idea's stemmed words, or Infinity when it does not.+ * @param {string} name+ * @param {DescribedTemplate[]} catalog+ * @param {string[]} order the idea's stemmed words, in order+ */+function familyAt(name, catalog, order) {+ const t = catalog.find(c => c.name === name);+ const family = weightWords(String(t?.category ?? '').split(' - ')[0]).map(+ stem,+ );+ const at = family.length ? order.findIndex(w => family.includes(w)) : -1;+ return at < 0 ? Infinity : at;+}+/*** 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 {{name: string}[]} catalog the project's ready page templates+ * @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,@@ -292,10 +347,34 @@ export function weighStart(pick && pick.family !== SHELL_FAMILY && cands.includes(pick.name)? pick.name: null;- // The tables cannot judge a template they do not list, and a template the- // ranker placed by its frame stays (spec:AST-048/FR3): the ranker's pick- // stands for both.- if (kept && (!position.has(kept) || pick?.containerMatched)) return kept;+ // A template the ranker placed by its frame stays (spec:AST-048/FR3).+ if (kept && pick?.containerMatched) return kept;+ // The tables cannot judge a template they do not list (an integration's+ // template, or one added since they were fit), so its own descriptor+ // decides: the ranker's pick stands when the idea names as many words of its+ // display name, category and keywords as of the tables' first listed+ // template's, or names its family first and nearly as many; otherwise that+ // listed template starts. Nothing learned about the template is involved,+ // so a new template competes on its own words.+ if (kept && !position.has(kept)) {+ const listed = best(c => c !== SHELL && position.has(c));+ if (!listed) return kept;+ // The idea's own words, less search's stopwords: "basically" must not+ // answer the "Basic" of a category.+ const content = weightWords(idea).filter(w => !STOPWORDS.has(w));+ const said = new Set(content.map(stem));+ const mine = ownWords(kept, catalog, said);+ const theirs = ownWords(listed, catalog, said);+ if (mine >= theirs) return kept;+ // An idea that names the template's family before the listed one's+ // ("a dashboard with a data table") is that family's page, unless it+ // names far more of the listed template's words.+ const order = content.map(stem);+ return familyAt(kept, catalog, order) < familyAt(listed, catalog, order) &&+ mine >= theirs - FAMILY_SLACK+ ? kept+ : listed;+ }const top = best(() => true);if (top !== SHELL) return top;// An idea that asks for a new page keeps the ranker's template rather thandiff --git a/packages/cli/api/build/kit/weights.test.mjs b/packages/cli/api/build/kit/weights.test.mjsindex 9dfb0dafab..b5ba41972e 100644--- a/packages/cli/api/build/kit/weights.test.mjs+++ b/packages/cli/api/build/kit/weights.test.mjs@@ -125,6 +125,102 @@ describe('weighStart', () => {expect(start).toBe('fresh');});+ describe('a template the tables do not list (cold start)', () => {+ // A made-up family the tables have never seen, described only by its own+ // descriptor, next to listed templates with descriptors of their own.+ const catalog = [+ {name: 'board', displayName: 'Kanban Board', keywords: ['kanban']},+ {name: 'charts', displayName: 'Charts', category: 'Charts - Overview'},+ {name: 'grid', displayName: 'Grid'},+ {+ name: 'gauge-fleet',+ displayName: 'Fleet Gauges',+ category: 'Gauges - Fleet',+ keywords: ['gauges', 'fleet', 'meters'],+ },+ ];++ it('starts from it when the idea names its own words', () => {+ const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];+ const start = weighStart(+ 'fleet gauges with meters per kanban lane',+ ranked,+ ranked[0],+ catalog,+ {weights: WEIGHTS},+ );+ expect(start).toBe('gauge-fleet');+ });++ it('starts from it when the idea names its family first', () => {+ const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];+ const start = weighStart(+ 'gauges page with a kanban board',+ ranked,+ ranked[0],+ catalog,+ {weights: WEIGHTS},+ );+ expect(start).toBe('gauge-fleet');+ });++ it("never counts a stopword from another template's keywords", () => {+ // "side" in grid's "side by side" keyword is one of search's stopwords;+ // it must not answer the idea's "sides", which is not.+ const own = [+ {name: 'board'},+ {name: 'charts'},+ {+ name: 'grid',+ displayName: 'Grid',+ keywords: ['side by side', 'orders'],+ },+ {name: 'fold', displayName: 'Folding Rows'},+ ];+ const ranked = [page('fold', 9, 'Fold'), ...RANKED];+ const start = weighStart(+ 'rows on two sides with orders on cards',+ ranked,+ ranked[0],+ own,+ {weights: WEIGHTS},+ );+ expect(start).toBe('fold');+ });++ it("never counts a stopword from the idea's words", () => {+ // "basically" is one of search's stopwords and stems to "basic", the+ // word of grid's category; it must not tip the count to grid.+ const own = [+ {name: 'board'},+ {name: 'charts'},+ {name: 'grid', displayName: 'Grid', category: 'Grid - Basic'},+ {name: 'fold', displayName: 'Folding Rows'},+ ];+ const ranked = [page('fold', 9, 'Fold'), ...RANKED];+ const start = weighStart(+ 'basically a grid of rows on cards',+ ranked,+ ranked[0],+ own,+ {weights: WEIGHTS},+ );+ expect(start).toBe('fold');+ });++ it('yields to the listed template whose own words the idea names more', () => {+ const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];+ const start = weighStart(+ 'a kanban board with a fleet column',+ ranked,+ ranked[0],+ catalog,+ {weights: WEIGHTS},+ );+ expect(start).toBe('board');+ });+ });+it("keeps the ranker's template for an idea that asks for a new page", () => {const start = weighStart('the existing page', RANKED, RANKED[0], CATALOG, {weights: WEIGHTS,