Skip to content

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

TypeScript
11.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file The build subject's environment access: the page templates a project
 * can scaffold, the components it can use, and the checked-in matcher weights.
 *
 * @input Template and component discovery for `cwd` — the CLI's own templates
 *   and Core's components, plus any that the project's configured integrations
 *   contribute.
 * @output Ready page templates as `{name, displayName, description, category,
 *   keywords, command}`, where `command` is the `astryx template` command that
 *   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
 *   from the template subject's, components from search's.
 */

import fs from 'node:fs';

import {discoverTemplates} from '../template/template.mjs';
import {componentKeywords} from '../search/search.mjs';
import {findCoreDir, requireCoreDir} from '../../foundation/fs/paths.mjs';
import {analyzeTemplateNeeds} from '../../foundation/discovery/template-needs.mjs';

/**
 * Runs one build with a single directory listing per path: the kit resolves
 * every candidate's source and docs by walking the same tree, which does not
 * change during the call.
 */
export {withListingCache} from '../../foundation/fs/listing-cache.mjs';

/**
 * A page template the kit can recommend starting from.
 * @typedef {object} PageTemplate
 * @property {string} name The template's own id, as search reports it.
 * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
 * @property {string} displayName Human-facing name.
 * @property {string} description What the page is and how it is laid out.
 * @property {string} package The npm package that owns this template.
 * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
 * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
 * @property {string} filePath Absolute path to the template source file on disk.
 */

/**
 * A component the project can use, as the ranker reads it.
 * @typedef {object} ComponentWords
 * @property {string} name The component's name, e.g. `DateRangeInput`.
 * @property {string[]} keywords The keywords its own doc declares.
 */

/**
 * Every ready page template the project can scaffold, in discovery order. This
 * is the default discovery view: an active integration replacement stands in
 * for the Core template it replaces, as it does for `astryx template <id>`.
 *
 * Discovery failures leave the kit without a start rather than failing the
 * command: the kit still carries its search matches, and `template --list`
 * reports what went wrong.
 *
 * @param {string} cwd
 * @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 {pages: [], blocks: []};
  }
  const pages = templates
    .filter(t => t.type === 'page' && t.isReady !== false)
    .map(t => ({
      name: t.dirName,
      displayName: t.displayName || t.name,
      description: t.description || '',
      package: t.package ?? '@astryxdesign/core',
      category: t.category || '',
      keywords: t.keywords ?? [],
      filePath: t.filePath,
      // The id `template()` resolves back to this entry: an active replacement
      // 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};
}

/**
 * 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
 * page from a page. Search's own discovery, so both agree on what exists; empty
 * when Core cannot be found.
 *
 * @param {string} cwd
 * @returns {Promise<ComponentWords[]>}
 */
export async function loadComponents(cwd) {
  const coreDir = findCoreDir(cwd);
  if (!coreDir) return [];
  try {
    return await componentKeywords(coreDir, cwd);
  } catch {
    return [];
  }
}

/** @type {import('./kit/weights.mjs').WeightsFile | null | undefined} */
let weights;

/**
 * The matcher weights checked in beside the kit (`kit/weights.json`), read
 * once; null when the file is absent or unreadable.
 * @returns {import('./kit/weights.mjs').WeightsFile | null}
 */
export function loadWeights() {
  if (weights === undefined) {
    try {
      const file = JSON.parse(
        fs.readFileSync(new URL('./kit/weights.json', import.meta.url), 'utf8'),
      );
      weights = isWeightsFile(file) ? file : null;
    } catch {
      weights = null;
    }
  }
  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
 * numbers per member (the tables plus the ranker) and one for the shell.
 * @param {any} file
 * @returns {file is import('./kit/weights.mjs').WeightsFile}
 */
export function isWeightsFile(file) {
  const n = Array.isArray(file?.candidates) ? file.candidates.length : 0;
  return (
    n > 0 &&
    Array.isArray(file.tables) &&
    file.tables.length > 0 &&
    file.tables.every(
      (/** @type {any} */ t) =>
        Array.isArray(t?.words) &&
        Array.isArray(t.rows) &&
        t.rows.length === t.words.length &&
        t.rows.every(
          (/** @type {any} */ r) => typeof r === 'string' && r.length === n,
        ) &&
        Array.isArray(t.bias) &&
        t.bias.length === n &&
        t.bias.every((/** @type {any} */ b) => Number.isFinite(b)) &&
        Number.isFinite(t.clip) &&
        Number.isFinite(t.step),
    ) &&
    Array.isArray(file.blend) &&
    file.blend.length === 3 * (file.tables.length + 1) + 1 &&
    file.blend.every((/** @type {any} */ x) => Number.isFinite(x))
  );
}

/** 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
 * file access is environment access (architecture:cli-surface INV21).
 *
 * @param {PageTemplate} template
 * @param {string} cwd Project directory
 * @returns {string[]} Setup notes (empty when the template needs nothing).
 */
export function templateSetupNotes(template, cwd) {
  try {
    const source = fs.readFileSync(template.filePath, 'utf-8');
    return analyzeTemplateNeeds(source, cwd).notes;
  } catch {
    // Best-effort: a read failure does not break the recommendation.
    return [];
  }
}

/**
 * The Core a build answers from: the project's, else the release's own,
 * installed into the per-user cache first when needed (a network install
 * and an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
 * @param {string} cwd
 * @returns {string}
 */
export function requireBuildCoreDir(cwd) {
  return requireCoreDir(cwd);
}