@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/lib/parse.mjs

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Consumer utilities for parsing Astryx CLI JSON output.
+ *
+ * Exported via `@astryxdesign/cli/json`:
+ *   import { parseResponse, isError, assertResponse } from '@astryxdesign/cli/json';
+ */
+
+/**
+ * Parse raw CLI output into a typed result.
+ * Consumer types are declared in types/base.d.ts — this is the runtime implementation.
+ * @param {unknown} raw
+ */
+export function parseResponse(raw) {
+  return typeof raw === 'string' ? JSON.parse(raw) : raw;
+}
+
+/**
+ * Type guard: returns true if result is a CLI error.
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+export function isError(result) {
+  return result != null && typeof result === 'object' && 'error' in result;
+}
+
+/**
+ * Assert a specific response type. Throws on error or type mismatch.
+ * Consumer types are declared in types/base.d.ts — this is the runtime implementation.
+ * @param {unknown} raw
+ * @param {string} expectedType
+ */
+export function assertResponse(raw, expectedType) {
+  const result = parseResponse(raw);
+  if (isError(result)) throw new Error(/** @type {any} */ (result).error);
+  if (/** @type {any} */ (result).type !== expectedType) {
+    throw new Error(
+      `Expected type "${expectedType}", got "${/** @type {any} */ (result).type}"`,
+    );
+  }
+  return result;
+}

package/src/lib/resolve-theme.mjs

@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Theme resolution — resolve a theme from config or environment
+ *
+ * Resolution sources (in priority order):
+ * 1. ASTRYX_THEME environment variable
+ * 2. xds.theme field in package.json
+ *
+ * Resolution strategy for the value:
+ * - Starts with `.` or `/` → file path relative to cwd
+ * - Starts with `@` → npm package (require/import)
+ * - Otherwise → try `@astryxdesign/theme-{name}`, then try as bare package name
+ *
+ * Returns the theme object's `variants` and `fonts` if available,
+ * or null if no theme is configured or found.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+
+const _require = createRequire(import.meta.url);
+
+/**
+ * Try to load a module, returning the default export or the module itself.
+ * Returns null if the module cannot be found.
+ */
+function tryLoadModule(specifier, cwd) {
+  // For relative/absolute paths, resolve against cwd
+  if (specifier.startsWith('.') || specifier.startsWith('/')) {
+    const resolved = path.resolve(cwd, specifier);
+    try {
+      return _require(resolved);
+    } catch {
+      return null;
+    }
+  }
+
+  // For package specifiers, try require
+  try {
+    return _require(specifier);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract theme data from a loaded module.
+ * Handles both `module.default` and direct `module` patterns,
+ * as well as named exports like `module.theme` or `module.{name}Theme`.
+ */
+function extractTheme(mod) {
+  if (!mod || typeof mod !== 'object') return null;
+
+  // Check default export
+  const obj = mod.default || mod;
+
+  // If it looks like a theme (has name + tokens or variants), use it directly
+  if (obj.name && (obj.tokens || obj.variants)) {
+    return obj;
+  }
+
+  // Check for a `theme` named export
+  if (mod.theme && typeof mod.theme === 'object' && mod.theme.name) {
+    return mod.theme;
+  }
+
+  // Check for any export ending in 'Theme'
+  for (const key of Object.keys(mod)) {
+    if (key.endsWith('Theme') && typeof mod[key] === 'object' && mod[key]?.name) {
+      return mod[key];
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the active Astryx theme from config and environment.
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {{ variants?: Record<string, string[]>, fonts?: Record<string, string>, name?: string } | null}
+ */
+export function resolveTheme(cwd = process.cwd()) {
+  // 1. Determine theme specifier
+  let specifier = process.env.ASTRYX_THEME || null;
+
+  if (!specifier) {
+    // Read from package.json
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        specifier = pkg.astryx?.theme || null;
+      } catch {
+        // Ignore parse errors
+      }
+    }
+  }
+
+  if (!specifier) {
+    return null;
+  }
+
+  // 2. Resolve the specifier to a module
+  let mod;
+
+  if (specifier.startsWith('.') || specifier.startsWith('/')) {
+    // File path
+    mod = tryLoadModule(specifier, cwd);
+    if (!mod) {
+      console.warn(`⚠ theme: could not resolve file "${specifier}" from ${cwd}`);
+      return null;
+    }
+  } else if (specifier.startsWith('@')) {
+    // Scoped package
+    mod = tryLoadModule(specifier, cwd);
+    if (!mod) {
+      console.warn(`⚠ theme: could not resolve package "${specifier}"`);
+      return null;
+    }
+  } else {
+    // Convention: try @astryxdesign/theme-{name} first, then bare package
+    mod = tryLoadModule(`@astryxdesign/theme-${specifier}`, cwd);
+    if (!mod) {
+      mod = tryLoadModule(specifier, cwd);
+    }
+    if (!mod) {
+      console.warn(`⚠ theme: could not resolve "${specifier}" (tried @astryxdesign/theme-${specifier} and ${specifier})`);
+      return null;
+    }
+  }
+
+  // 3. Extract theme data
+  const theme = extractTheme(mod);
+  if (!theme) {
+    console.warn(`⚠ theme: loaded "${specifier}" but could not find a theme object`);
+    return null;
+  }
+
+  return {
+    name: theme.name || null,
+    variants: theme.variants || null,
+    fonts: theme.fonts || null,
+  };
+}

package/src/lib/string-utils.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file String utilities — fuzzy matching and semantic search for component names
+ */
+
+export function levenshteinDistance(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  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]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Find the closest component names to a given (possibly misspelled) name.
+ * Returns matches sorted by distance, filtered to maxDistance.
+ */
+export function findClosestComponents(name, components, maxDistance = 3) {
+  const allNames = Object.values(components).flat();
+  const needle = name.toLowerCase();
+
+  const matches = allNames
+    .map(comp => ({
+      name: comp,
+      distance: levenshteinDistance(needle, comp.toLowerCase()),
+    }))
+    .filter(m => m.distance <= maxDistance)
+    .sort((a, b) => a.distance - b.distance);
+
+  return matches;
+}
+
+/**
+ * Unified component search that scores matches across multiple signals:
+ * name similarity, keyword matches, and description/feature text search.
+ *
+ * Always returns results (top 5 minimum). Scores determine confidence:
+ *   100  exact name match
+ *    90  exact keyword match
+ *    80  name Levenshtein distance 1
+ *    70  keyword substring or Levenshtein distance 1
+ *    60  substring match on component name (min 4 chars, 50%+ coverage)
+ *    50  description or feature text contains the search term
+ *    40  name Levenshtein distance 2
+ *    30  keyword Levenshtein distance 2
+ *    20  name Levenshtein distance 3
+ *
+ * Each result: { name, score, reason }
+ */
+export async function searchComponents(needle, coreDir, components) {
+  const {pathToFileURL} = await import('node:url');
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+
+  const term = needle.toLowerCase();
+  const allNames = Object.values(components).flat();
+  const scored = new Map();
+
+  function addMatch(name, score, reason) {
+    const existing = scored.get(name);
+    if (!existing || score > existing.score) {
+      scored.set(name, {name, score, reason});
+    }
+  }
+
+  // --- Pass 1: Name matching (sync, fast) ---
+  for (const comp of allNames) {
+    const compLower = comp.toLowerCase();
+
+    // Exact name
+    if (compLower === term) {
+      addMatch(comp, 100, 'exact name');
+      continue;
+    }
+
+    // Substring match on name (both directions)
+    const shorter = term.length < compLower.length ? term : compLower;
+    const longer = term.length < compLower.length ? compLower : term;
+    if (shorter.length >= 4 && longer.includes(shorter)) {
+      const coverage = shorter.length / longer.length;
+      if (coverage >= 0.5) {
+        addMatch(comp, 60, 'name contains "' + shorter + '"');
+      }
+    }
+
+    // Levenshtein on name
+    const dist = levenshteinDistance(term, compLower);
+    if (dist === 1) addMatch(comp, 80, 'similar name (distance ' + dist + ')');
+    else if (dist === 2) addMatch(comp, 40, 'similar name (distance ' + dist + ')');
+    else if (dist === 3) addMatch(comp, 20, 'similar name (distance ' + dist + ')');
+  }
+
+  // --- Pass 2: Keyword + description matching (async, reads doc files) ---
+  for (const comp of allNames) {
+    const srcDir = path.join(coreDir, 'src');
+
+    let docPath = null;
+    const direct = path.join(srcDir, comp, comp + '.doc.mjs');
+    if (fs.existsSync(direct)) {
+      docPath = direct;
+    }
+    if (!docPath) {
+      const xdsDirect = path.join(srcDir, comp, 'XDS' + comp + '.doc.mjs');
+      if (fs.existsSync(xdsDirect)) {
+        docPath = xdsDirect;
+      }
+    }
+    if (!docPath && fs.existsSync(srcDir)) {
+      const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const nested = path.join(srcDir, entry.name, comp, comp + '.doc.mjs');
+        if (fs.existsSync(nested)) { docPath = nested; break; }
+      }
+    }
+
+    if (!docPath) continue;
+
+    try {
+      const mod = await import(pathToFileURL(docPath).href);
+      const docs = mod.docs;
+      if (!docs) continue;
+
+      // Keyword matching
+      if (docs.keywords && Array.isArray(docs.keywords)) {
+        for (const kw of docs.keywords) {
+          const kwLower = kw.toLowerCase();
+
+          // Exact keyword
+          if (kwLower === term) {
+            addMatch(comp, 90, 'keyword "' + kw + '"');
+            break;
+          }
+
+          // Substring: term contains keyword or keyword contains term
+          const s = term.length < kwLower.length ? term : kwLower;
+          const l = term.length < kwLower.length ? kwLower : term;
+          if (s.length >= 4 && l.includes(s)) {
+            const coverage = s.length / l.length;
+            if (coverage >= 0.5) {
+              addMatch(comp, 70, 'keyword "' + kw + '"');
+            }
+          }
+
+          const dist = levenshteinDistance(term, kwLower);
+          if (dist === 1) addMatch(comp, 70, 'keyword "' + kw + '" (distance ' + dist + ')');
+          else if (dist === 2) addMatch(comp, 30, 'keyword "' + kw + '" (distance ' + dist + ')');
+        }
+      }
+
+      // Description search (whole word boundary)
+      const searchDesc = docs.usage?.description || docs.description;
+      if (searchDesc && term.length >= 3) {
+        const descLower = searchDesc.toLowerCase();
+        const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const re = new RegExp('\\b' + escaped + '\\b');
+        if (re.test(descLower)) {
+          addMatch(comp, 50, 'description mentions "' + term + '"');
+        }
+      }
+
+      // Best practices search (whole word boundary)
+      const bestPractices = docs.usage?.bestPractices;
+      if (bestPractices && Array.isArray(bestPractices) && term.length >= 3) {
+        for (const bp of bestPractices) {
+          const bpLower = bp.description.toLowerCase();
+          const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+          const re = new RegExp('\\b' + escaped + '\\b');
+          if (re.test(bpLower)) {
+            addMatch(comp, 50, 'best practice mentions "' + term + '"');
+            break;
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  const results = Array.from(scored.values())
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+
+  return results;
+}

package/src/types/api.contract.assert.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Compile-time guard that the runtime @astryxdesign/cli/api implementation matches the
+ * declared programmatic API surface in api.d.ts.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `typecheck:json-api` historically only checked the `.d.ts` declarations plus a
+ * couple of `lib/*.mjs` helpers — it never looked at `src/api/*.mjs`. So the
+ * hand-written declarations in `api.d.ts` could (and did) silently drift from
+ * what the runtime functions actually accept: the runtime `component()` gained
+ * `package`/`blocks` options and a `component.detail.blocks` result, and
+ * `template()` gained a `type` filter, none of which were reflected in
+ * `api.d.ts`. CI never caught it.
+ *
+ * Turning on full `checkJs` over the api implementations surfaces ~140
+ * pre-existing implicit-any JSDoc errors in transitively-imported `lib/*` and
+ * `utils/*` files that have nothing to do with the public API contract — an
+ * unmanageable cleanup for one PR (see PR body). Instead, this file pins the
+ * *option surface and arity* of each runtime function against the declared
+ * types. The check runs under a dedicated tsconfig with `checkJs: false`, so
+ * the implementation bodies are not re-typechecked — only their JSDoc-derived
+ * export signatures are read and compared.
+ *
+ * The JSDoc `@param` annotations on each `src/api/*.mjs` export are the source
+ * TypeScript reads for the runtime side, so keeping them in sync with
+ * `api.d.ts` is exactly what this guard enforces. If a runtime function adds an
+ * option the `.d.ts` omits (or vice versa), the corresponding `MutuallyEqual`
+ * assertion below fails and `typecheck:json-api` goes red.
+ */
+
+import type * as Api from './api';
+import type {component} from '../api/component.mjs';
+import type {docs} from '../api/docs.mjs';
+import type {discover} from '../api/discover.mjs';
+import type {template} from '../api/template.mjs';
+
+/** Resolve to `true` only when `A` and `B` are mutually assignable. */
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
+    ? true
+    : false;
+
+/** Compile error unless `T` is exactly `true`. */
+type Expect<T extends true> = T;
+
+/** Drop `undefined` from an optional options parameter for comparison. */
+type Opt<T> = NonNullable<T>;
+
+// ── Option-bag parity: the declared options and the runtime JSDoc options
+// must describe the same set of keys/types, in both directions. ──────────────
+
+type _ComponentOptions = Expect<
+  Equal<Opt<Parameters<typeof Api.component>[1]>, Opt<Parameters<typeof component>[1]>>
+>;
+type _DocsOptions = Expect<
+  Equal<Opt<Parameters<typeof Api.docs>[2]>, Opt<Parameters<typeof docs>[2]>>
+>;
+type _DiscoverOptions = Expect<
+  Equal<Opt<Parameters<typeof Api.discover>[1]>, Opt<Parameters<typeof discover>[1]>>
+>;
+type _TemplateOptions = Expect<
+  Equal<Opt<Parameters<typeof Api.template>[1]>, Opt<Parameters<typeof template>[1]>>
+>;
+
+// ── Positional-argument parity: arity and positional types must match. ───────
+
+type _ComponentName = Expect<
+  Equal<Parameters<typeof Api.component>[0], Parameters<typeof component>[0]>
+>;
+type _DocsTopic = Expect<
+  Equal<Parameters<typeof Api.docs>[0], Parameters<typeof docs>[0]>
+>;
+type _DocsSection = Expect<
+  Equal<Parameters<typeof Api.docs>[1], Parameters<typeof docs>[1]>
+>;
+type _DiscoverQuery = Expect<
+  Equal<Parameters<typeof Api.discover>[0], Parameters<typeof discover>[0]>
+>;
+type _TemplateName = Expect<
+  Equal<Parameters<typeof Api.template>[0], Parameters<typeof template>[0]>
+>;
+
+// Surface the assertion aliases so the file has a value/type export and the
+// checks above are not tree-shaken away by `noUnusedLocals`.
+export type _ApiContractGuard = [
+  _ComponentOptions,
+  _DocsOptions,
+  _DiscoverOptions,
+  _TemplateOptions,
+  _ComponentName,
+  _DocsTopic,
+  _DocsSection,
+  _DiscoverQuery,
+  _TemplateName,
+];

package/src/types/api.d.ts

@@ -0,0 +1,206 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Programmatic API types for @astryxdesign/cli/api.
+ *
+ * Every function returns the same { type, data } envelope as `xds --json`.
+ * Errors throw AstryxError.
+ */
+
+import type {
+  ComponentListResponse,
+  ComponentBriefResponse,
+  ComponentFullResponse,
+  ComponentDetailResponse,
+  ComponentDetailPropsResponse,
+  ComponentDetailSourceResponse,
+  ComponentDetailShowcaseResponse,
+  ComponentDetailBlocksResponse,
+} from './component';
+import type {
+  DocsListResponse,
+  DocsDetailResponse,
+  DocsDetailSectionResponse,
+} from './docs';
+import type {
+  DiscoverListResponse,
+  DiscoverDetailResponse,
+  DiscoverDetailDocResponse,
+  DiscoverSearchResponse,
+} from './discover';
+import type {
+  TemplateListResponse,
+  TemplateShowResponse,
+  TemplateSkeletonResponse,
+  TemplateCopyResponse,
+  TemplateGetResponse,
+} from './template';
+import type {
+  HookListResponse,
+  HookBriefResponse,
+  HookFullResponse,
+  HookDetailResponse,
+  HookDetailParamsResponse,
+} from './hook';
+import type {SearchResponse, SearchDomain} from './search';
+import type {ErrorCode} from './error-codes';
+import type {DoctorResponse} from './doctor';
+
+/** Structured API error with a stable machine-readable code. */
+export declare class AstryxError extends Error {
+  /** Stable error code; consumers branch on this, never the message. */
+  code: ErrorCode;
+  suggestions?: Array<{name: string; reason: string}>;
+  constructor(
+    message: string,
+    suggestions?: Array<{name: string; reason: string}>,
+    code?: ErrorCode,
+  );
+}
+
+// ── Component ────────────────────────────────────────────────────────
+
+export interface ComponentOptions {
+  cwd?: string;
+  list?: boolean;
+  category?: string;
+  /** Scope lookup to a specific external package (e.g. '@acme/xds-widgets'). */
+  package?: string;
+  props?: boolean;
+  source?: boolean;
+  showcase?: boolean;
+  /** List example blocks for the component: showcase, examples, and related. */
+  blocks?: boolean;
+  detail?: 'full' | 'compact' | 'brief';
+  lang?: string;
+  zh?: boolean;
+  dense?: boolean;
+}
+
+type ComponentResult =
+  | ComponentListResponse
+  | ComponentBriefResponse
+  | ComponentFullResponse
+  | ComponentDetailResponse
+  | ComponentDetailPropsResponse
+  | ComponentDetailSourceResponse
+  | ComponentDetailShowcaseResponse
+  | ComponentDetailBlocksResponse;
+
+export declare function component(
+  name?: string,
+  options?: ComponentOptions,
+): Promise<ComponentResult>;
+
+// ── Docs ─────────────────────────────────────────────────────────────
+
+export interface DocsOptions {
+  lang?: string;
+  zh?: boolean;
+  dense?: boolean;
+}
+
+type DocsResult =
+  | DocsListResponse
+  | DocsDetailResponse
+  | DocsDetailSectionResponse;
+
+export declare function docs(
+  topic?: string,
+  section?: string,
+  options?: DocsOptions,
+): Promise<DocsResult>;
+
+// ── Discover ─────────────────────────────────────────────────────────
+
+export interface DiscoverOptions {
+  components?: boolean;
+  lang?: string;
+  zh?: boolean;
+}
+
+type DiscoverResult =
+  | DiscoverListResponse
+  | DiscoverDetailResponse
+  | DiscoverDetailDocResponse
+  | DiscoverSearchResponse;
+
+export declare function discover(
+  query?: string,
+  options?: DiscoverOptions,
+): Promise<DiscoverResult>;
+
+// ── Template ─────────────────────────────────────────────────────────
+
+export interface TemplateOptions {
+  list?: boolean;
+  skeleton?: boolean;
+  show?: boolean;
+  /** Filter templates by kind: 'page' or 'block'. Only applies to list views. */
+  type?: 'page' | 'block';
+  targetPath?: string;
+  cwd?: string;
+}
+
+type TemplateResult =
+  | TemplateListResponse
+  | TemplateShowResponse
+  | TemplateSkeletonResponse
+  | TemplateCopyResponse;
+
+export declare function template(
+  name?: string,
+  options?: TemplateOptions,
+): Promise<TemplateResult>;
+
+export declare function getTemplateById(
+  id: string,
+  options?: {cwd?: string},
+): Promise<TemplateGetResponse>;
+
+// ── Hook ─────────────────────────────────────────────────────────────
+
+export interface HookOptions {
+  cwd?: string;
+  list?: boolean;
+  category?: string;
+  params?: boolean;
+  detail?: 'full' | 'compact' | 'brief';
+  lang?: string;
+  zh?: boolean;
+}
+
+type HookResult =
+  | HookListResponse
+  | HookBriefResponse
+  | HookFullResponse
+  | HookDetailResponse
+  | HookDetailParamsResponse;
+
+export declare function hook(
+  name?: string,
+  options?: HookOptions,
+): Promise<HookResult>;
+
+// ── Search ───────────────────────────────────────────────────────────
+
+export interface SearchOptions {
+  cwd?: string;
+  type?: SearchDomain;
+  limit?: number;
+}
+
+export declare function search(
+  query: string,
+  options?: SearchOptions,
+): Promise<SearchResponse>;
+
+// ── Doctor ──────────────────────────────────
+
+export interface DoctorOptions {
+  cwd?: string;
+}
+
+export declare function doctor(
+  options?: DoctorOptions,
+): Promise<DoctorResponse>;