@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src/api → api/search}/search.mjs

@@ -33,19 +33,34 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {findCoreDir, CLI_ROOT} from '../../utils/paths.mjs';
 import {
   discoverComponents,
   findComponentReadme,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {discoverHooks, findHookDoc} from '../lib/hook-discovery.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {discoverTemplates, extractComponents} from './template.mjs';
-import {AstryxError} from './error.mjs';
+} from '../../lib/component-discovery.mjs';
+import {discoverHooks, findHookDoc} from '../../lib/hook-discovery.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {discoverTemplates, extractComponents} from '../template/template.mjs';
+import {AstryxError} from '../error.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * A search candidate gathered from one content domain. Extra underscore-
+ * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ * @typedef {object} Candidate
+ * @property {'component'|'hook'|'doc'|'template'} domain
+ * @property {string} name
+ * @property {string[]} [keywords]
+ * @property {string} [description]
+ * @property {string[]} [prose]
+ * @property {string} [_import]
+ * @property {string} [_title]
+ * @property {string} [_displayName]
+ * @property {'page'|'block'} [_kind]
+ */
+
 /**
  * Synonym / intent map: product-language terms an agent is likely to type,
  * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
@@ -72,10 +87,19 @@ const SYNONYMS = {
 
 // Flatten into a token -> Set(expansions) lookup (bidirectional).
 const SYNONYM_INDEX = (() => {
+  /** @type {Map<string, Set<string>>} */
   const idx = new Map();
+  /**
+   * @param {string} a
+   * @param {string} b
+   */
   const add = (a, b) => {
-    if (!idx.has(a)) idx.set(a, new Set());
-    idx.get(a).add(b);
+    let set = idx.get(a);
+    if (!set) {
+      set = new Set();
+      idx.set(a, set);
+    }
+    set.add(b);
   };
   for (const [key, vals] of Object.entries(SYNONYMS)) {
     for (const v of vals) {
@@ -159,6 +183,8 @@ const MIN_TOKEN_SCORE = 50;
 /**
  * Best score for a token against a candidate, fanning out through synonyms
  * (synonym hits are discounted so a direct hit always wins).
+ * @param {string} tok
+ * @param {Candidate} candidate
  * @returns {{score: number, reason: string} | null}
  */
 function bestForToken(tok, candidate) {
@@ -176,6 +202,12 @@ function bestForToken(tok, candidate) {
   return best;
 }
 
+/**
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
 export function scoreQuery(term, tokens, candidate) {
   const full = scoreCandidate(term, candidate);
 
@@ -192,6 +224,7 @@ export function scoreQuery(term, tokens, candidate) {
   // strong hits, then reward coverage so candidates matching more terms win.
   let sum = 0;
   let matched = 0;
+  /** @type {string[]} */
   const hitTerms = [];
   for (const tok of tokens) {
     const h = bestForToken(tok, candidate);
@@ -235,6 +268,10 @@ export function scoreQuery(term, tokens, candidate) {
 export function scoreCandidate(term, {name, keywords = [], description = '', prose = []}) {
   let best = 0;
   let reason = '';
+  /**
+   * @param {number} score
+   * @param {string} why
+   */
   const consider = (score, why) => {
     if (score > best) {
       best = score;
@@ -299,7 +336,12 @@ export function scoreCandidate(term, {name, keywords = [], description = '', pro
   return best > 0 ? {score: best, reason} : null;
 }
 
-/** Load a doc module's `docs`/`doc` export, swallowing errors. */
+/**
+ * Load a doc module's `docs`/`doc` export, swallowing errors.
+ * @param {string} docPath
+ * @param {string} [exportName]
+ * @returns {Promise<any>}
+ */
 async function loadModuleDoc(docPath, exportName = 'docs') {
   try {
     const mod = await import(pathToFileURL(docPath).href);
@@ -313,13 +355,16 @@ async function loadModuleDoc(docPath, exportName = 'docs') {
  * Build component candidates: name + keywords + usage/description from the
  * component's .doc.mjs.
  * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
  */
 async function gatherComponents(coreDir) {
   const grouped = discoverComponents(coreDir);
   const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const comp of names) {
     const readme = findComponentReadme(coreDir, comp);
+    /** @type {string[]} */
     let keywords = [];
     let description = '';
     if (readme && readme.endsWith('.doc.mjs')) {
@@ -344,13 +389,16 @@ async function gatherComponents(coreDir) {
  * Build hook candidates: name + keywords + usage/description from the hook's
  * .doc.mjs.
  * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
  */
 async function gatherHooks(coreDir) {
   const grouped = discoverHooks(coreDir);
   const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const hookName of names) {
     const docPath = findHookDoc(coreDir, hookName);
+    /** @type {string[]} */
     let keywords = [];
     let description = '';
     let importPath = '@astryxdesign/core/hooks';
@@ -373,9 +421,13 @@ async function gatherHooks(coreDir) {
   return candidates;
 }
 
-/** Build doc-topic candidates: topic name + description + section prose. */
+/**
+ * Build doc-topic candidates: topic name + description + section prose.
+ * @returns {Promise<Candidate[]>}
+ */
 async function gatherDocs() {
   if (!fs.existsSync(DOCS_DIR)) return [];
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const file of fs.readdirSync(DOCS_DIR)) {
     const match = file.match(/^([\w-]+)\.doc\.mjs$/);
@@ -383,6 +435,7 @@ async function gatherDocs() {
     const topic = match[1];
     const doc = await loadModuleDoc(path.join(DOCS_DIR, file));
     let description = '';
+    /** @type {string[]} */
     const prose = [];
     if (doc) {
       description = doc.description || '';
@@ -405,7 +458,11 @@ async function gatherDocs() {
   return candidates;
 }
 
-/** Build template candidates (page + block) from the template discovery API. */
+/**
+ * Build template candidates (page + block) from the template discovery API.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
 async function gatherTemplates(cwd) {
   let templates;
   try {
@@ -444,7 +501,7 @@ async function gatherTemplates(cwd) {
  * carries enough to act on it: the domain, name, a one-line description, and
  * the follow-up command (and import path where relevant).
  *
- * @param {object} c - candidate
+ * @param {Candidate} c - candidate
  * @param {number} score
  * @param {string} reason
  */
@@ -522,6 +579,7 @@ export async function search(query, options = {}) {
   }
 
   // Gather candidates from each requested domain in parallel.
+  /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
     wants('component') ? gatherComponents(coreDir) : [],
@@ -543,6 +601,7 @@ export async function search(query, options = {}) {
   }
 
   // Sort by score desc, then domain (stable order), then name.
+  /** @type {Record<string, number>} */
   const domainOrder = {component: 0, hook: 1, doc: 2, template: 3};
   scored.sort(
     (a, b) =>

package/api/swizzle/swizzle.mjs

@@ -0,0 +1,283 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swizzle API — copy a component's source into the consumer project for
+ * customization, rewriting escaping relative imports to the OWNER package's
+ * subpaths.
+ *
+ * Side-effecting: `swizzle(name, ...)` writes files and returns a
+ * `swizzle.copy` receipt describing what it did; with no name (or `list`) it
+ * returns `swizzle.list`. Errors throw AstryxError (stable code + suggestions).
+ * All human prose / package-manager prefixing lives in the CLI renderer.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir, listComponents} from '../../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../utils/path-safety.mjs';
+import {checkGhCli} from '../../utils/github.mjs';
+import {Project} from '../../lib/project.mjs';
+import {
+  CORE_PACKAGE,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
+} from '../../lib/component-discovery.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {AstryxError} from '../error.mjs';
+
+/** Default issue tracker for maintainer feedback after swizzling. */
+const DEFAULT_ISSUES_URL = 'https://github.com/facebook/astryx/issues/new';
+
+/**
+ * Rewrite relative imports that point outside the component directory to use
+ * the OWNER package's subpaths. Imports within the copied directory (./x) are
+ * left untouched.
+ *
+ * e.g. with ownerPackage '@astryxdesign/core':
+ *      '../theme/tokens.stylex' -> '@astryxdesign/core/theme'
+ *      '../utils/mergeProps'     -> '@astryxdesign/core/utils'
+ *
+ * @param {string} content
+ * @param {string} [ownerPackage]
+ */
+export function rewriteImports(content, ownerPackage = CORE_PACKAGE) {
+  return content.replace(
+    /(from\s+['"])(\.\.\/.+?)(['"])/g,
+    (match, prefix, importPath, suffix) => {
+      const parts = importPath.replace(/^\.\.\//, '').split('/');
+      const topDir = parts[0];
+      return `${prefix}${ownerPackage}/${topDir}${suffix}`;
+    },
+  );
+}
+
+/**
+ * Build the maintainer feedback note for a swizzled component.
+ * @param {string} component
+ * @param {string|undefined} issuesUrl
+ * @returns {{issuesUrl: string, ghCommand?: string} | null}
+ */
+function buildFeedback(component, issuesUrl) {
+  if (!issuesUrl) return null;
+  /** @type {{issuesUrl: string, ghCommand?: string}} */
+  const feedback = {issuesUrl};
+  const match = issuesUrl.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues(?:\/new)?\/?$/,
+  );
+  if (match && checkGhCli()) {
+    const [, owner, repo] = match;
+    feedback.ghCommand = `gh issue create --repo ${owner}/${repo} --title "[${component}] Swizzle feedback"`;
+  }
+  return feedback;
+}
+
+/**
+ * Load the configured integrations + core issues URL for `cwd`, swallowing any
+ * config errors so swizzle never hard-fails on a malformed/absent config.
+ * @param {string} cwd
+ * @returns {Promise<{loadedIntegrations: import('../../lib/integrations.mjs').LoadedIntegration[], issuesUrl: string|undefined, project: Project|null}>}
+ */
+async function loadConfigSafely(cwd) {
+  try {
+    const project = await Project.load(cwd);
+    return {
+      loadedIntegrations: project.loadedIntegrations,
+      issuesUrl: project.config.issuesUrl,
+      project,
+    };
+  } catch {
+    return {loadedIntegrations: [], issuesUrl: undefined, project: null};
+  }
+}
+
+/**
+ * Build the set of OWNER packages that provide a component named `name` across
+ * core + every loaded integration.
+ * @param {string} coreDir
+ * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
+ * @param {string} name
+ * @param {string|undefined} coreIssuesUrl
+ * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ */
+function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
+  const owners = [];
+  const coreComponentDir = path.join(coreDir, 'src', name);
+  if (fs.existsSync(coreComponentDir)) {
+    owners.push({
+      package: CORE_PACKAGE,
+      sourceDir: coreComponentDir,
+      ownerPackage: CORE_PACKAGE,
+      issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+    });
+  }
+  for (const integration of loadedIntegrations) {
+    const docPath = findIntegrationComponentDoc(integration, name);
+    if (!docPath) continue;
+    const sourcePath = findIntegrationComponentSource(integration, name);
+    owners.push({
+      package: integration.name,
+      sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+      ownerPackage: integration.name,
+      issuesUrl: integration.issuesUrl,
+    });
+  }
+  return owners;
+}
+
+/** @param {string} file */
+function isExcludedFromCopy(file) {
+  return (
+    file.includes('.test.') || file.includes('.doc.') || file === 'README.md'
+  );
+}
+
+/**
+ * List swizzlable components, or copy one component's source for customization.
+ *
+ * @param {string} [component] bare or XDS-prefixed component name; omit to list
+ * @param {{cwd?: string, output?: string, package?: string, list?: boolean, overwrite?: boolean}} [options]
+ * @returns {Promise<import('../../types/swizzle').SwizzleListResponse | import('../../types/swizzle').SwizzleCopyResponse>}
+ */
+export async function swizzle(component, options = {}) {
+  const {
+    cwd = process.cwd(),
+    output = './components/astryx',
+    package: pkg,
+    list = false,
+    overwrite = false,
+  } = options;
+
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.',
+      [],
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+
+  const components = listComponents(coreDir);
+
+  if (list || !component) {
+    return {type: 'swizzle.list', data: components};
+  }
+
+  const dirName = component.replace(/^XDS/, '');
+
+  const {loadedIntegrations, project} = await loadConfigSafely(cwd);
+  const coreIssuesUrl = project
+    ? project.issuesUrl({package: CORE_PACKAGE})
+    : undefined;
+  const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+
+  if (allOwners.length === 0) {
+    throw new AstryxError(
+      `Component "${component}" not found.`,
+      components.slice(0, 10).map(n => ({name: n})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  let owner;
+  if (pkg) {
+    owner = allOwners.find(o => o.package === pkg);
+    if (!owner) {
+      throw new AstryxError(
+        `Component "${dirName}" is not provided by package "${pkg}".`,
+        allOwners.map(o => ({name: o.package, reason: 'provides this component'})),
+        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+      );
+    }
+  } else if (allOwners.length > 1) {
+    throw new AstryxError(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      allOwners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_AMBIGUOUS_COMPONENT,
+    );
+  } else {
+    owner = allOwners[0];
+  }
+
+  if (!owner.sourceDir || !fs.existsSync(owner.sourceDir)) {
+    throw new AstryxError(
+      `No source found for "${dirName}" in package "${owner.package}".`,
+      [],
+      ERROR_CODES.ERR_NO_SOURCE,
+    );
+  }
+
+  const componentDir = owner.sourceDir;
+
+  // Path-safety: --output must resolve inside cwd.
+  let outputBase;
+  try {
+    outputBase = assertWithin(output, cwd, {label: 'output directory'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, [], ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+  const outputDir = path.join(outputBase, dirName);
+
+  // Pre-flight overwrite check before any mkdir/writeFile.
+  const sourceFiles = fs.readdirSync(componentDir).filter(file => {
+    if (isExcludedFromCopy(file)) return false;
+    return fs.statSync(path.join(componentDir, file)).isFile();
+  });
+  const existingFiles = sourceFiles.filter(f =>
+    fs.existsSync(path.join(outputDir, f)),
+  );
+  if (existingFiles.length > 0 && !overwrite) {
+    const relOutputForMsg = path.relative(cwd, outputDir) || '.';
+    throw new AstryxError(
+      `Refusing to overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/. ` +
+        `Re-run with --overwrite (or -f) to replace them.`,
+      [],
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
+
+  fs.mkdirSync(outputDir, {recursive: true});
+
+  const files = fs.readdirSync(componentDir);
+  let copied = 0;
+  let usesStyleX = false;
+  for (const file of files) {
+    if (isExcludedFromCopy(file)) continue;
+    const srcPath = path.join(componentDir, file);
+    if (!fs.statSync(srcPath).isFile()) continue;
+    let content = fs.readFileSync(srcPath, 'utf-8');
+    if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+      content = rewriteImports(content, owner.ownerPackage);
+    }
+    if (
+      (file.endsWith('.ts') || file.endsWith('.tsx')) &&
+      content.includes('@stylexjs/stylex')
+    ) {
+      usesStyleX = true;
+    }
+    fs.writeFileSync(path.join(outputDir, file), content);
+    copied++;
+  }
+
+  const relOutput = path.relative(cwd, outputDir);
+  const copiedFiles = files.filter(
+    f =>
+      !isExcludedFromCopy(f) &&
+      fs.statSync(path.join(componentDir, f)).isFile(),
+  );
+  const feedback = buildFeedback(dirName, owner.issuesUrl);
+
+  /** @type {import('../../types/swizzle').SwizzleCopyResponse['data']} */
+  const data = {
+    component: dirName,
+    package: owner.package,
+    outputDir: relOutput,
+    filesCopied: copied,
+    files: copiedFiles.map(f => f),
+    usesStyleX,
+  };
+  if (feedback) data.feedback = feedback;
+  return {type: 'swizzle.copy', data};
+}

package/{src/commands → api/swizzle}/swizzle.test.mjs

@@ -1,7 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {rewriteImports} from './swizzle.mjs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {rewriteImports, swizzle} from './swizzle.mjs';
+
+// api/swizzle/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 
 describe('rewriteImports', () => {
   it('rewrites ../theme/tokens to @astryxdesign/core/theme', () => {
@@ -51,3 +56,23 @@ describe('rewriteImports', () => {
     );
   });
 });
+
+describe('swizzle() API', () => {
+  it('no component → swizzle.list of core components', async () => {
+    const r = await swizzle(undefined, {cwd: REPO});
+    expect(r.type).toBe('swizzle.list');
+    expect(Array.isArray(r.data)).toBe(true);
+    expect(r.data).toContain('Button');
+  });
+
+  it('--list → swizzle.list even with a component arg', async () => {
+    const r = await swizzle('Button', {cwd: REPO, list: true});
+    expect(r.type).toBe('swizzle.list');
+  });
+
+  it('unknown component → AstryxError ERR_UNKNOWN_COMPONENT with suggestions', async () => {
+    await expect(swizzle('NotARealComponent99', {cwd: REPO})).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+  });
+});

package/{src/api → api/template}/template-integration.test.mjs

@@ -62,7 +62,7 @@ function writeTemplate(pkgDir, id, {kind, body, withSource = true}) {
   fs.writeFileSync(
     docPath,
     body ??
-      `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {${create}} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
   );
   if (withSource) {
@@ -166,7 +166,7 @@ describe('integration template discovery', () => {
     );
     fs.writeFileSync(
       path.join(pkg2, 'templates', 'hero.doc.mjs'),
-      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {createBlockTemplate} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default createBlockTemplate({name: 'Hero block', description: 'b'});\n`,
     );
     fs.writeFileSync(

package/{src/api → api/template}/template-suffix.test.mjs

@@ -21,7 +21,7 @@ import {
   findRelatedBlocks,
 } from './template.mjs';
 
-/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
+/** Absolute path to the CLI package so fixtures can import /authoring/template.mjs. */
 const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
 
 let tmpDir;
@@ -68,7 +68,7 @@ function writeTemplate(pkgDir, id, {kind, suffix}) {
     kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
   fs.writeFileSync(
     docPath,
-    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+    `import {${create}} from '${CLI_PKG}/authoring/template.mjs';\n` +
       `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
   );
   fs.writeFileSync(
@@ -177,7 +177,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     fs.mkdirSync(fooDir, {recursive: true});
     fs.writeFileSync(
       path.join(fooDir, 'FooShowcase.template.ts'),
-      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {createBlockTemplate} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default createBlockTemplate({\n` +
         `  name: 'Foo — Showcase',\n` +
         `  description: 'Foo showcase.',\n` +