@astryxdesign/cli 0.7.2 → 0.7.3-canary.04c7468

package/api/build/_adapter.d.mts

@@ -32,6 +32,27 @@
  * @returns {Promise<PageTemplate[]>}
  */
 export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * A block the kit can name, as search names a block result.
+ * @typedef {object} BlockTemplate
+ * @property {string} name The block's own id, as search reports it.
+ * @property {string} package The npm package that owns this block.
+ * @property {string} displayName Human-facing name.
+ * @property {string} description What the block is.
+ * @property {string} command `astryx template <id> --type block`, as search prints it.
+ */
+/**
+ * Every ready page template and every block the project can scaffold, from one
+ * discovery: pages as {@link loadPageTemplates} returns them, blocks as
+ * {@link BlockTemplate}. Discovery failures leave both empty.
+ *
+ * @param {string} cwd
+ * @returns {Promise<{pages: PageTemplate[], blocks: BlockTemplate[]}>}
+ */
+export function loadTemplates(cwd: string): Promise<{
+    pages: PageTemplate[];
+    blocks: BlockTemplate[];
+}>;
 /**
  * The components the project can use, Core's and its integrations', each with
  * the keywords its own doc declares: what the ranker reads to tell a part of a
@@ -48,6 +69,18 @@ export function loadComponents(cwd: string): Promise<ComponentWords[]>;
  * @returns {import('./kit/weights.mjs').WeightsFile | null}
  */
 export function loadWeights(): import("./kit/weights.mjs").WeightsFile | null;
+/**
+ * The classifier weights of build's root (tree.weights.json), read once.
+ * @returns {import('../../foundation/route/route.mjs').ClassifierWeights}
+ */
+export function loadTreeWeights(): import("../../foundation/route/route.mjs").ClassifierWeights;
+/**
+ * The block picker's weights (blocks/blocks.weights.json), read once; null
+ * when the file is absent, unreadable, or not the shape the picker reads, in
+ * which case build names its own blocks.
+ * @returns {import('./blocks/blocks.mjs').BlockPickerWeights | null}
+ */
+export function loadBlockPicker(): import("./blocks/blocks.mjs").BlockPickerWeights | null;
 /**
  * Whether a parsed weights file has the shape the kit reads: every row has a
  * weight per candidate, every bias a number per candidate, and three blend
@@ -125,3 +158,28 @@ export type ComponentWords = {
      */
     keywords: string[];
 };
+/**
+ * A block the kit can name, as search names a block result.
+ */
+export type BlockTemplate = {
+    /**
+     * The block's own id, as search reports it.
+     */
+    name: string;
+    /**
+     * The npm package that owns this block.
+     */
+    package: string;
+    /**
+     * Human-facing name.
+     */
+    displayName: string;
+    /**
+     * What the block is.
+     */
+    description: string;
+    /**
+     * `astryx template <id> --type block`, as search prints it.
+     */
+    command: string;
+};

package/api/build/_adapter.mjs

@@ -9,7 +9,9 @@
  *   contribute.
  * @output Ready page templates as `{name, displayName, description, category,
  *   keywords, command}`, where `command` is the `astryx template` command that
- *   selects exactly that template; components as `{name, keywords}`.
+ *   selects exactly that template; blocks as search names them; components as
+ *   `{name, keywords}`; the kit's matcher weights, the root's classifier
+ *   weights, and the block picker's weights.
  * @position Beside build.mjs (api/build/). The kit leaf reads templates and
  *   components only through here, because a subject's `_adapter.mjs` is its
  *   only environment access. This adds no discovery of its own: templates come
@@ -63,13 +65,35 @@ export {withListingCache} from '../../foundation/fs/listing-cache.mjs';
  * @returns {Promise<PageTemplate[]>}
  */
 export async function loadPageTemplates(cwd) {
+  return (await loadTemplates(cwd)).pages;
+}
+
+/**
+ * A block the kit can name, as search names a block result.
+ * @typedef {object} BlockTemplate
+ * @property {string} name The block's own id, as search reports it.
+ * @property {string} package The npm package that owns this block.
+ * @property {string} displayName Human-facing name.
+ * @property {string} description What the block is.
+ * @property {string} command `astryx template <id> --type block`, as search prints it.
+ */
+
+/**
+ * Every ready page template and every block the project can scaffold, from one
+ * discovery: pages as {@link loadPageTemplates} returns them, blocks as
+ * {@link BlockTemplate}. Discovery failures leave both empty.
+ *
+ * @param {string} cwd
+ * @returns {Promise<{pages: PageTemplate[], blocks: BlockTemplate[]}>}
+ */
+export async function loadTemplates(cwd) {
   let templates;
   try {
     templates = await discoverTemplates(cwd);
   } catch {
-    return [];
+    return {pages: [], blocks: []};
   }
-  return templates
+  const pages = templates
     .filter(t => t.type === 'page' && t.isReady !== false)
     .map(t => ({
       name: t.dirName,
@@ -83,6 +107,16 @@ export async function loadPageTemplates(cwd) {
       // owns the Core id it names, so that id selects it, not its own.
       command: `astryx template ${t.replaces ?? t.dirName} --type page`,
     }));
+  const blocks = templates
+    .filter(t => t.type === 'block')
+    .map(t => ({
+      name: t.dirName,
+      package: t.package ?? '@astryxdesign/core',
+      displayName: t.name,
+      description: t.description || '',
+      command: `astryx template ${t.replaces ?? t.dirName} --type block`,
+    }));
+  return {pages, blocks};
 }
 
 /**
@@ -126,6 +160,48 @@ export function loadWeights() {
   return weights ?? null;
 }
 
+/** @type {import('../../foundation/route/route.mjs').ClassifierWeights | undefined} */
+let treeWeights;
+
+/**
+ * The classifier weights of build's root (tree.weights.json), read once.
+ * @returns {import('../../foundation/route/route.mjs').ClassifierWeights}
+ */
+export function loadTreeWeights() {
+  treeWeights ??= JSON.parse(
+    fs.readFileSync(new URL('./tree.weights.json', import.meta.url), 'utf8'),
+  );
+  return /** @type {import('../../foundation/route/route.mjs').ClassifierWeights} */ (
+    treeWeights
+  );
+}
+
+/** @type {import('./blocks/blocks.mjs').BlockPickerWeights | null | undefined} */
+let blockPicker;
+
+/**
+ * The block picker's weights (blocks/blocks.weights.json), read once; null
+ * when the file is absent, unreadable, or not the shape the picker reads, in
+ * which case build names its own blocks.
+ * @returns {import('./blocks/blocks.mjs').BlockPickerWeights | null}
+ */
+export function loadBlockPicker() {
+  if (blockPicker === undefined) {
+    try {
+      const file = JSON.parse(
+        fs.readFileSync(
+          new URL('./blocks/blocks.weights.json', import.meta.url),
+          'utf8',
+        ),
+      );
+      blockPicker = isBlockPickerWeights(file) ? file : null;
+    } catch {
+      blockPicker = null;
+    }
+  }
+  return blockPicker ?? null;
+}
+
 /**
  * Whether a parsed weights file has the shape the kit reads: every row has a
  * weight per candidate, every bias a number per candidate, and three blend
@@ -159,6 +235,54 @@ export function isWeightsFile(file) {
   );
 }
 
+/** The ranking coefficients the picker reads. */
+const PICKER_THETA = [
+  'g',
+  'grank',
+  'gmargin',
+  'seen',
+  'lex',
+  'sscore',
+  'scov',
+  'srank',
+  'inkit',
+  'kitpos',
+  'mention',
+  'show',
+];
+
+/**
+ * Whether a parsed block picker file has the shape the picker reads: a
+ * vocabulary with an idf per entry, two signed byte matrices of vocabulary x
+ * dims (base64) with their scales, the lexical weight, the known blocks, and
+ * the ranking coefficients.
+ * @param {any} w
+ * @returns {w is import('./blocks/blocks.mjs').BlockPickerWeights}
+ */
+function isBlockPickerWeights(w) {
+  const n = Array.isArray(w?.vocab) ? w.vocab.length : 0;
+  const size = (/** @type {unknown} */ s) =>
+    typeof s === 'string' ? Buffer.from(s, 'base64').length : -1;
+  return (
+    n > 0 &&
+    w.vocab.every((/** @type {unknown} */ t) => typeof t === 'string') &&
+    Array.isArray(w.idf) &&
+    w.idf.length === n &&
+    w.idf.every((/** @type {unknown} */ x) => Number.isFinite(x)) &&
+    Number.isInteger(w.dims) &&
+    w.dims > 0 &&
+    size(w.request) === n * w.dims &&
+    size(w.doc) === n * w.dims &&
+    Number.isFinite(w.requestScale) &&
+    Number.isFinite(w.docScale) &&
+    Number.isFinite(w.lexical) &&
+    Array.isArray(w.known) &&
+    w.known.every((/** @type {unknown} */ b) => typeof b === 'string') &&
+    !!w.theta &&
+    PICKER_THETA.every(k => Number.isFinite(w.theta[k]))
+  );
+}
+
 /**
  * Analyze what a start template needs that the project lacks. The kit leaf
  * calls this through the adapter rather than reading the file itself, because

package/api/build/blocks/blocks.d.mts

@@ -0,0 +1,92 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A word with a plural or verb ending removed (words over four letters):
+ * "-ies" becomes "-y"; "-es" goes only after s, x, z, ch, or sh; otherwise a
+ * final "s" goes, but never after another "s"; then "-ing" or "-ed".
+ * @param {string} w
+ * @returns {string}
+ */
+export function stemOf(w: string): string;
+/**
+ * An identifier's words, lowercase: "SideNavNestedItems" -> side, nav,
+ * nested, items.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function wordsOf(text: string): string[];
+/**
+ * A text's stemmed content words, then its adjacent pairs as `a_b`.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function termsOf(text: string): string[];
+/**
+ * The blocks build names for a request, ranked by the picker.
+ * @param {string} request
+ * @param {{kitBlocks: string[], searched: BlockScore[], foreign: string[], catalog: CatalogBlock[], components: CatalogComponent[]}} signals
+ * @param {BlockPickerWeights} weights
+ * @returns {{names: string[], entries: Map<string, SearchResultEntry>}} as
+ *   many names as build's own list, best first; an entry for each listed
+ *   block search did not return
+ */
+export function pickBlocks(request: string, signals: {
+    kitBlocks: string[];
+    searched: BlockScore[];
+    foreign: string[];
+    catalog: CatalogBlock[];
+    components: CatalogComponent[];
+}, weights: BlockPickerWeights): {
+    names: string[];
+    entries: Map<string, SearchResultEntry>;
+};
+export type BlockPickerWeights = {
+    /**
+     * stemmed words and `a_b` word pairs
+     */
+    vocab: string[];
+    /**
+     * one per vocab entry, x1024
+     */
+    idf: number[];
+    /**
+     * the width of the shared space
+     */
+    dims: number;
+    /**
+     * base64 bytes, vocab.length x dims, row-major, each a signed weight offset by 128
+     */
+    request: string;
+    requestScale: number;
+    /**
+     * base64 bytes, vocab.length x dims, row-major, each a signed weight offset by 128
+     */
+    doc: string;
+    docScale: number;
+    /**
+     * the weight of the plain overlap
+     */
+    lexical: number;
+    /**
+     * the blocks the matrices were fitted with
+     */
+    known: string[];
+    /**
+     * the ranking coefficients
+     */
+    theta: Record<string, number>;
+};
+export type BlockScore = import("../kit/signals.mjs").BlockScore;
+export type CatalogBlock = {
+    name: string;
+    package?: string;
+    displayName?: string;
+    description?: string;
+    command?: string;
+};
+export type CatalogComponent = {
+    name: string;
+    keywords?: string[];
+};
+export type SearchResultEntry = import("../../search/search.type.mjs").SearchResultEntry;