@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/foundation/render/ts-paths.mjs

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A project's `compilerOptions.paths` (tsconfig.json or jsconfig.json),
+ * read and matched by TypeScript's rules, for `astryx experimental render`:
+ * an exact key matches only itself; a key may hold one `*` anywhere, and the
+ * longest matching prefix wins; a target may hold one `*`, which takes what
+ * the key's `*` matched; targets are tried in order, and when none exists the
+ * import resolves as a package. Only bare specifiers are matched. Targets
+ * resolve from `baseUrl` (default: the config's folder).
+ *
+ * @position foundation/render — used by page-worker.mjs and embedded-imports.mjs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * @typedef {object} PathPattern
+ * @property {string} key - The key as written.
+ * @property {string} prefix - What comes before the key's `*` (all of it, for an exact key).
+ * @property {string} suffix - What comes after the key's `*`.
+ * @property {boolean} wildcard - Whether the key holds a `*`.
+ * @property {string[]} targets - Absolute target patterns, in order.
+ */
+
+/** Extensions an extensionless candidate may stand for, in resolution order. */
+const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.mts', '.cts', '.json'];
+
+/**
+ * The path patterns of the config in `dir` (tsconfig.json, else
+ * jsconfig.json), or none. Comments and trailing commas are allowed.
+ * @param {string} dir
+ * @returns {PathPattern[] | null} null when neither file is there
+ */
+export function readPathsIn(dir) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    try {
+      const text = fs
+        .readFileSync(file, 'utf8')
+        .replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? '')
+        .replace(/,(\s*[}\]])/g, '$1');
+      const options = JSON.parse(text)?.compilerOptions ?? {};
+      const base = path.resolve(dir, typeof options.baseUrl === 'string' ? options.baseUrl : '.');
+      /** @type {PathPattern[]} */
+      const out = [];
+      for (const [key, targets] of Object.entries(options.paths ?? {})) {
+        if (!Array.isArray(targets)) continue;
+        const star = key.indexOf('*');
+        if (star !== key.lastIndexOf('*')) continue;
+        out.push({
+          key,
+          prefix: star === -1 ? key : key.slice(0, star),
+          suffix: star === -1 ? '' : key.slice(star + 1),
+          wildcard: star !== -1,
+          targets: targets
+            .filter(t => typeof t === 'string' && t.indexOf('*') === t.lastIndexOf('*'))
+            .map(t => path.resolve(base, t)),
+        });
+      }
+      return out;
+    } catch {
+      return [];
+    }
+  }
+  return null;
+}
+
+/**
+ * The pattern a specifier matches by TypeScript's rules, and what its `*`
+ * matched: an exact key first, else the wildcard key with the longest prefix.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {{pattern: PathPattern, capture: string} | null}
+ */
+export function matchPath(patterns, spec) {
+  // TypeScript applies `paths` only to bare specifiers.
+  if (/^\.{1,2}(\/|$)|^\//.test(spec)) return null;
+  const exact = patterns.find(p => !p.wildcard && p.key === spec);
+  if (exact) return {pattern: exact, capture: ''};
+  /** @type {{pattern: PathPattern, capture: string} | null} */
+  let best = null;
+  for (const p of patterns) {
+    if (!p.wildcard) continue;
+    if (spec.length < p.prefix.length + p.suffix.length) continue;
+    if (!spec.startsWith(p.prefix) || !spec.endsWith(p.suffix)) continue;
+    if (best && best.pattern.prefix.length >= p.prefix.length) continue;
+    best = {pattern: p, capture: spec.slice(p.prefix.length, spec.length - p.suffix.length)};
+  }
+  return best;
+}
+
+/**
+ * The absolute paths a match names, one per target, in order.
+ * @param {{pattern: PathPattern, capture: string}} match
+ * @returns {string[]}
+ */
+export const candidatesOf = match => match.pattern.targets.map(t => t.replace('*', match.capture));
+
+/**
+ * The file a candidate path stands for: itself, with an extension, or its
+ * folder's index; null when none exists.
+ * @param {string} candidate
+ * @returns {string | null}
+ */
+export function existingFile(candidate) {
+  const isFile = (/** @type {string} */ f) => {
+    try {
+      return fs.statSync(f).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (isFile(candidate)) return candidate;
+  for (const ext of EXTENSIONS) if (isFile(candidate + ext)) return candidate + ext;
+  for (const ext of EXTENSIONS) if (isFile(path.join(candidate, `index${ext}`))) return path.join(candidate, `index${ext}`);
+  return null;
+}
+
+/**
+ * Resolve a specifier through path patterns: the first target that names an
+ * existing file wins.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {string | null} the file, or null when the specifier matches no
+ *   pattern or no target exists
+ */
+export function resolvePath(patterns, spec) {
+  const match = matchPath(patterns, spec);
+  if (!match) return null;
+  for (const candidate of candidatesOf(match)) {
+    const file = existingFile(candidate);
+    if (file) return file;
+  }
+  return null;
+}

package/foundation/response/error-codes.doc.mjs

@@ -338,13 +338,13 @@ export const doc = {
       value: 'ERR_RENDER_NOT_ASTRYX',
       stability: 'experimental',
       description:
-        '`render --reverse` was given a file with no embedded source and no Astryx markup. Nothing was written. Raised only by the experimental render command.',
+        '`render --reverse` was given a file that a render did not write, with no embedded source and no Astryx markup. Nothing was written. Raised only by the experimental render command.',
     },
     {
       value: 'ERR_RENDER_SOURCE_DAMAGED',
       stability: 'experimental',
       description:
-        '`render --reverse` refused the received file, and nothing was written: its embedded source is damaged (not valid, or a file does not match its checksum), lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its own imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds: a dotfile or dot-folder, anything under node_modules, a package manifest, lockfile or tool configuration, a file a test, story or benchmark runner would run, or any kind but a page module, stylesheet, JSON file or image. Raised only by the experimental render command.',
+        '`render --reverse` refused the received file, and nothing was written: its embedded source was removed (a file a render wrote, with no Astryx components left to rebuild from) or is damaged (not valid, or a file does not match its checksum), lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its own imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds: a dotfile or dot-folder, anything under node_modules, a package manifest, lockfile or tool configuration, a file a test, story or benchmark runner would run, or any kind but a page module, stylesheet, JSON file or image. Raised only by the experimental render command.',
     },
   ],
 };

package/foundation/response/error-codes.mjs

@@ -298,8 +298,9 @@ export const ERROR_CODES = Object.freeze({
    */
   ERR_RENDER_FAILED: 'ERR_RENDER_FAILED',
   /**
-   * `render --reverse` was given an HTML file that holds no Astryx markup and
-   * no embedded source, so there is nothing to rebuild. Nothing was written.
+   * `render --reverse` was given an HTML file that a render did not write and
+   * that holds no Astryx markup and no embedded source, so there is nothing
+   * to rebuild. Nothing was written.
    */
   ERR_RENDER_NOT_ASTRYX: 'ERR_RENDER_NOT_ASTRYX',
   /**

package/foundation/text/levenshtein.d.mts

@@ -19,6 +19,11 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a: string, b: string, max?: number): number;
+export function levenshteinDistance(a: string, b: string, max?: number, { swaps }?: {
+    swaps?: boolean;
+}): number;

package/foundation/text/levenshtein.mjs

@@ -19,11 +19,15 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a, b, max) {
-  if (max !== undefined) return distanceWithin(a, b, max);
-  const m = a.length, n = b.length;
+export function levenshteinDistance(a, b, max, {swaps = false} = {}) {
+  if (max !== undefined) return distanceWithin(a, b, max, swaps);
+  const m = a.length,
+    n = b.length;
   // Early exit: the distance is always ≥ |m − n|, so once the length gap
   // exceeds the loosest fuzzy-match threshold any caller uses (the hook
   // suggester keeps distance ≤ 5) the pair can never match — skip the O(m·n)
@@ -36,9 +40,10 @@ export function levenshteinDistance(a, b, max) {
   for (let j = 0; j <= n; j++) dp[0][j] = j;
   for (let i = 1; i <= m; i++) {
     for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i-1] === b[j-1]
-        ? dp[i-1][j-1]
-        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
     }
   }
   return dp[m][n];
@@ -51,11 +56,13 @@ export function levenshteinDistance(a, b, max) {
  * @param {string} a
  * @param {string} b
  * @param {number} max
+ * @param {boolean} swaps - two adjacent letters swapped cost one edit
  * @returns {number}
  */
-function distanceWithin(a, b, max) {
+function distanceWithin(a, b, max, swaps) {
   const over = max + 1;
   if (Math.abs(a.length - b.length) > max) return over;
+  let before = new Array(b.length + 1).fill(over);
   let previous = new Array(b.length + 1).fill(over);
   let current = new Array(b.length + 1).fill(over);
   for (let j = 0; j <= Math.min(b.length, max); j++) previous[j] = j;
@@ -67,18 +74,27 @@ function distanceWithin(a, b, max) {
     let rowMin = current[0];
     for (let j = from; j <= to; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const value = Math.min(
+      let value = Math.min(
         previous[j - 1] + cost,
         previous[j] + 1,
         current[j - 1] + 1,
         over,
       );
+      if (
+        swaps &&
+        i > 1 &&
+        j > 1 &&
+        a[i - 1] === b[j - 2] &&
+        a[i - 2] === b[j - 1]
+      ) {
+        value = Math.min(value, before[j - 2] + 1);
+      }
       current[j] = value;
       if (value < rowMin) rowMin = value;
     }
     // Every later cell costs at least this row's least.
     if (rowMin >= over) return over;
-    [previous, current] = [current, previous];
+    [before, previous, current] = [previous, current, before];
   }
   return Math.min(previous[b.length], over);
 }

package/foundation/text/suggest-order.d.mts

@@ -18,15 +18,22 @@ export function nameWords(text: string): string[];
  * when it carries some of them, the items that carry none are left out. When
  * no item carries one, nothing is left out. The list only ever gets shorter,
  * and its order does not change.
+ *
+ * With `typos`, a near name (one or two slips from the typed name, as
+ * `ButonGroup` or `ButtonGorup` for ButtonGroup) ranks just below the names
+ * that carry every typed word and above the rest. With `closest` too, near
+ * names stay in the list whatever the cut leaves out, and the list is never
+ * longer than it is without `typos`.
  * @template T
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
- * @param {{closest?: boolean}} [options]
+ * @param {{closest?: boolean, typos?: boolean}} [options]
  * @returns {T[]}
  */
 export function orderByAffinity<T>(typedName: string, items: T[], namesOf: (item: T) => Array<string | undefined>, options?: {
     closest?: boolean;
+    typos?: boolean;
 }): T[];
 /**
  * Docs route suggestions, closest to the typed route first. When every

package/foundation/text/suggest-order.mjs

@@ -19,6 +19,12 @@
 
 import {levenshteinDistance} from './levenshtein.mjs';
 
+/**
+ * The score of a near name (nearNameSlips), less a little per slip: above any
+ * name that carries only some of the typed words, below one that carries all
+ * of them.
+ */
+const NEAR_NAME_SCORE = 19.6;
 /** The score a synonym match gets: an exact keyword's. */
 const SYNONYM_SCORE = 90;
 /** The score a name with exactly the typed words gets: an exact name's. */
@@ -59,17 +65,22 @@ export function nameWords(text) {
  * closer. Tiers, best first: the same words; every typed word present; some
  * typed word present; none. Within a tier, more of the typed words and more of
  * the candidate's own words matched rank higher, and a name that starts with
- * the typed name (or the reverse) gets a small lift.
+ * the typed name (or the reverse) gets a small lift. With `typos`, a near name
+ * (one or two slips from the typed name) ranks just below the names that
+ * carry every typed word.
  * @param {string[]} typed - {@link nameWords} of the typed name
  * @param {string} name
+ * @param {{typos?: boolean}} [options]
  * @returns {number}
  */
-function affinityOf(typed, name) {
+function affinityOf(typed, name, {typos = false} = {}) {
   const words = nameWords(name);
   if (typed.length === 0 || words.length === 0) return 0;
   const typedJoined = typed.join('');
   const joined = words.join('');
   if (joined === typedJoined) return 40;
+  const slips = typos ? nearNameSlips(typedJoined, joined) : 0;
+  const near = slips > 0 ? NEAR_NAME_SCORE - slips * 0.2 : 0;
   const have = new Set(words);
   const want = new Set(typed);
   const covered = typed.filter(w => have.has(w)).length / typed.length;
@@ -77,7 +88,29 @@ function affinityOf(typed, name) {
   const prefix =
     joined.startsWith(typedJoined) || typedJoined.startsWith(joined) ? 1 : 0;
   const tier = covered === 1 ? 2 : covered > 0 ? 1 : 0;
-  return tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01;
+  // A near name keeps its word score when that is higher: a name that also
+  // carries every typed word ranks among the other full matches.
+  return Math.max(
+    near,
+    tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01,
+  );
+}
+
+/**
+ * How many slips separate a typed name from a candidate, both with their
+ * words joined, when it is a near name: an edit or two adjacent letters
+ * swapped count as one slip, one slip is allowed from five letters and two from
+ * eight. Zero when it is not a near name.
+ * @param {string} typed
+ * @param {string} name
+ * @returns {number}
+ */
+function nearNameSlips(typed, name) {
+  const shorter = Math.min(typed.length, name.length);
+  const cap = shorter >= 8 ? 2 : shorter >= 5 ? 1 : 0;
+  if (cap === 0 || Math.abs(typed.length - name.length) > cap) return 0;
+  const slips = levenshteinDistance(typed, name, cap, {swaps: true});
+  return slips <= cap ? slips : 0;
 }
 
 /**
@@ -87,14 +120,15 @@ function affinityOf(typed, name) {
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{typos?: boolean}} [options]
  * @returns {Array<{item: T, best: number}>}
  */
-function scoreByAffinity(typedName, items, namesOf) {
+function scoreByAffinity(typedName, items, namesOf, options = {}) {
   const typed = nameWords(typedName);
   const scored = items.map((item, index) => {
     let best = 0;
     for (const name of namesOf(item)) {
-      if (name) best = Math.max(best, affinityOf(typed, name));
+      if (name) best = Math.max(best, affinityOf(typed, name, options));
     }
     return {item, index, best};
   });
@@ -112,14 +146,46 @@ function scoreByAffinity(typedName, items, namesOf) {
  * when it carries some of them, the items that carry none are left out. When
  * no item carries one, nothing is left out. The list only ever gets shorter,
  * and its order does not change.
+ *
+ * With `typos`, a near name (one or two slips from the typed name, as
+ * `ButonGroup` or `ButtonGorup` for ButtonGroup) ranks just below the names
+ * that carry every typed word and above the rest. With `closest` too, near
+ * names stay in the list whatever the cut leaves out, and the list is never
+ * longer than it is without `typos`.
  * @template T
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
- * @param {{closest?: boolean}} [options]
+ * @param {{closest?: boolean, typos?: boolean}} [options]
  * @returns {T[]}
  */
 export function orderByAffinity(typedName, items, namesOf, options = {}) {
+  if (!options.typos) return orderByWords(typedName, items, namesOf, options);
+  const scored = scoreByAffinity(typedName, items, namesOf, {typos: true});
+  if (!options.closest) return scored.map(s => s.item);
+  const kept = new Set(orderByWords(typedName, items, namesOf, options));
+  return scored
+    .filter(s => kept.has(s.item) || isNearScore(s.best))
+    .slice(0, kept.size)
+    .map(s => s.item);
+}
+
+/**
+ * Whether a score is a near name's.
+ * @param {number} score
+ */
+const isNearScore = score => score < 20 && score > NEAR_NAME_SCORE - 1;
+
+/**
+ * {@link orderByAffinity} without `typos`.
+ * @template T
+ * @param {string} typedName
+ * @param {T[]} items
+ * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{closest?: boolean}} options
+ * @returns {T[]}
+ */
+function orderByWords(typedName, items, namesOf, options) {
   const scored = scoreByAffinity(typedName, items, namesOf);
   if (!options.closest) return scored.map(s => s.item);
   // One-letter words (`a` in `a11y`, `use-a-theme`) say nothing about which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.ccb4a6d",
+  "version": "0.7.12-canary.da3dbdc",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -117,6 +117,7 @@
     "ignore": "^7.0.5",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
+    "linkedom": "^0.18.14",
     "node-diff3": "3.2.1",
     "postcss": "^8.5.23",
     "postcss-selector-parser": "^7.1.6",
@@ -124,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.12-canary.ccb4a6d"
+    "@astryxdesign/core": "0.7.12-canary.da3dbdc"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -132,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.ccb4a6d",
-    "@astryxdesign/core": "0.7.12-canary.ccb4a6d",
-    "@astryxdesign/lab": "0.7.12-canary.ccb4a6d",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.ccb4a6d",
+    "@astryxdesign/charts": "0.7.12-canary.da3dbdc",
+    "@astryxdesign/core": "0.7.12-canary.da3dbdc",
+    "@astryxdesign/lab": "0.7.12-canary.da3dbdc",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.da3dbdc",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",