@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/json/envelope-types.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The published `@astryxdesign/cli/json` envelope types carry
+ * `apiVersion`, the field every `--json` envelope has. Type-checks a consumer
+ * fixture that reads it from each envelope shape.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+
+const INDEX = fileURLToPath(new URL('./index.ts', import.meta.url));
+const TSC = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+
+const FIXTURE = `
+import type {
+  assertResponse,
+  CLIError,
+  CLIUnsupportedError,
+  parseResponse,
+} from ${JSON.stringify(INDEX)};
+
+declare const error: CLIError;
+declare const unsupported: CLIUnsupportedError;
+declare const parsed: Exclude<ReturnType<typeof parseResponse>, CLIError | CLIUnsupportedError>;
+declare const asserted: ReturnType<typeof assertResponse<'manifest'>>;
+
+export const versions: number[] = [
+  error.apiVersion,
+  unsupported.apiVersion,
+  parsed.apiVersion,
+  asserted.apiVersion,
+];
+`;
+
+describe('@astryxdesign/cli/json envelope types', () => {
+  it('declare apiVersion on the success and error envelopes', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-envelope-types-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'fixture.ts'), FIXTURE);
+      fs.writeFileSync(
+        path.join(dir, 'tsconfig.json'),
+        JSON.stringify({
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            allowImportingTsExtensions: true,
+            // index.ts re-exports JSDoc types from .type.mjs files; read them
+            // from source, as tsconfig.json-api.json does, not from generated
+            // declarations that exist only after a build.
+            allowJs: true,
+            types: [],
+          },
+          files: ['fixture.ts'],
+        }),
+      );
+      const res = spawnSync(process.execPath, [TSC, '-p', dir], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+      });
+      expect(res.stdout + res.stderr).toBe('');
+      expect(res.status).toBe(0);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});

package/api/json/index.ts

@@ -26,8 +26,9 @@ export type * from '../gap-report/gap-report.type.mjs';
 export type * from '../upgrade/upgrade.type.mjs';
 export type * from '../init/init.type.mjs';
 export type * from '../doctor/doctor.type.mjs';
-export type * from '../layout/layout.type.mjs';
 export type * from '../integration/validate-integration.type.mjs';
+export type * from '../integration/authoring-checks.type.mjs';
+export type * from '../integration/pack-check.type.mjs';
 export type * from '../../foundation/response/base';
 export type * from '../../foundation/response/error-codes';
 export type * from '../../clients/cli/lib/manifest';

package/api/json/isError.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'isError',
+  namespace: 'cli/api',
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:

package/api/json/parseResponse.doc.mjs

@@ -11,12 +11,13 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'parseResponse',
+  namespace: 'cli/api',
   displayName: 'parseResponse()',
   summary: 'Parse `astryx --json` stdout into the structural response envelope.',
   description:
     'The entry point for consuming the CLI as a subprocess. A JSON string is parsed; ' +
     'an already-parsed object is passed through unchanged, so it is safe to call on ' +
-    'either. It returns the structural { type, data, meta? } envelope without narrowing: ' +
+    'either. It returns the structural { apiVersion, type, data, meta? } envelope without narrowing: ' +
     '`data` stays unknown until you discriminate on `type` (or use assertResponse).',
   importPath: '@astryxdesign/cli/json',
   signature: 'parseResponse(raw: unknown): any',
@@ -34,7 +35,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { apiVersion, type, data, meta? } envelope, or a CLIError envelope ({ apiVersion, error, code, suggestions? }). The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/search/search-return-type.test.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The declared return type of `search()` is the canonical SearchResponse.
+ * Consumers of `@astryxdesign/cli/api` type-check against it; an `object` entry
+ * type erases every result field from their view.
+ */
+
+import {createRequire} from 'node:module';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SEARCH = path.join(HERE, 'search.mjs');
+const TYPES = path.join(HERE, 'search.type.mjs');
+
+describe('search() declared return type', () => {
+  it('types each result as the canonical SearchResultEntry', () => {
+    const program = ts.createProgram([SEARCH, TYPES], {
+      allowJs: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2022,
+    });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(SEARCH);
+    /** @param {string} file @param {string} name */
+    const exportOf = (file, name) =>
+      checker
+        .getExportsOfModule(checker.getSymbolAtLocation(program.getSourceFile(file)))
+        .find((/** @type {any} */ s) => s.name === name);
+    /** @param {any} type @param {string} name */
+    const prop = (type, name) =>
+      checker.getTypeOfSymbolAtLocation(type.getProperty(name), source);
+    /** @param {any} type */
+    const names = type => type.getProperties().map((/** @type {any} */ p) => p.name).sort();
+
+    const fn = checker.getTypeOfSymbolAtLocation(exportOf(SEARCH, 'search'), source);
+    const response = checker.getAwaitedType(fn.getCallSignatures()[0].getReturnType());
+    const data = prop(response, 'data');
+    expect(names(data)).toEqual(['matchCount', 'query', 'results']);
+    const entry = checker.getIndexTypeOfType(prop(data, 'results'), ts.IndexKind.Number);
+    const canonical = checker.getDeclaredTypeOfSymbol(exportOf(TYPES, 'SearchResultEntry'));
+    expect(names(canonical)).toContain('command');
+    expect(names(entry)).toEqual(names(canonical));
+  }, 30_000);
+});

package/api/search/search.d.mts

@@ -9,6 +9,13 @@
  * @returns {string}
  */
 export function stem(w: string): string;
+/**
+ * Whether two lowercase words are the same word, up to plural and stem form.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameWord(a: string, b: string): boolean;
 /**
  * Split a query into meaningful content tokens (lowercased, stopwords + very
  * short words removed). Empty for single-word queries (callers fall back to
@@ -47,6 +54,7 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {string} [candidate.description]
  * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
  * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
+ * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
 export function scoreCandidate(term: string, { name, keywords, weakKeywords, description, prose, guidance, }: {
@@ -56,6 +64,8 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
+}, { fuzzy }?: {
+    fuzzy?: boolean;
 }): {
     score: number;
     reason: string;
@@ -68,22 +78,38 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
-    type?: "component" | "hook" | "doc" | "template" | undefined;
+    type?: "component" | "hook" | "template" | "doc" | undefined;
     limit?: number | undefined;
-}): Promise<{
-    type: "search";
-    data: {
-        query: string;
-        matchCount: number;
-        results: Array<object>;
-    };
-}>;
+}): Promise<import("./search.type.mjs").SearchResponse>;
+export namespace SYNONYMS {
+    let dashboard: string[];
+    let login: string[];
+    let signup: string[];
+    let payment: string[];
+    let pricing: string[];
+    let chat: string[];
+    let settings: string[];
+    let calendar: string[];
+    let table: string[];
+    let gallery: string[];
+    let hero: string[];
+    let form: string[];
+    let profile: string[];
+    let documentation: string[];
+    let navigation: string[];
+}
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS: string[];
+/**
+ * Filler words stripped from multi-word queries so natural-language phrasing
+ * ("a page where you can see business stats") ranks on its content words.
+ * Exported for `build`, whose page ranker strips the same words.
+ */
+export const STOPWORDS: Set<string>;
 /**
  * A search candidate gathered from one content domain. Extra underscore-
  * prefixed fields carry domain-specific payload used only by {@link toResult}.
@@ -98,6 +124,31 @@ export type Candidate = {
     guidance?: string[] | undefined;
     _import?: string | undefined;
     _title?: string | undefined;
+    /**
+     * - A doc result's topic or docs-tree route.
+     */
+    _topic?: string | undefined;
+    /**
+     * - A doc result's section key, when it is one section.
+     */
+    _section?: string | undefined;
+    /**
+     * - The command that reads exactly this doc part.
+     */
+    _command?: string | undefined;
+    /**
+     * - The command that opens the level above a doc
+     * part: its topic's section list, or the docs-tree namespace it sits in.
+     */
+    _parent?: string | undefined;
+    /**
+     * - The npm package that authored a docs-tree
+     * doc part. Flat topics carry none: an extension's sections can come from
+     * another package.
+     */
+    _package?: string | undefined;
     _displayName?: string | undefined;
-    _kind?: "block" | "page" | undefined;
+    _kind?: "page" | "block" | undefined;
+    _resultName?: string | undefined;
+    _commandName?: string | undefined;
 };

package/api/search/search.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'search',
+  namespace: 'cli/api',
   displayName: 'search()',
   summary:
     'Unified ranked search across components, hooks, docs, and templates.',
@@ -46,14 +47,15 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Directory to resolve @astryxdesign/core from.',
+      description:
+        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it.",
     },
   ],
   returns: [
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from).',
     },
   ],
   throws: [
@@ -61,6 +63,10 @@ export const doc = {
       code: 'ERR_INVALID_ARGUMENT',
       when: 'the query is empty, --type is unknown, or --limit is not a positive integer',
     },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: '@astryxdesign/core cannot be found from the cwd, and the search reads it: every `type` but `doc`',
+    },
   ],
   examples: [
     {label: 'Find a component', code: "const r = await search('button');"},