Skip to content

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

TypeScript

fix(cli): declare search() as returning SearchResponse (#6529)

Joey047b1cea6163
diff --git a/.changeset/cli-spec-search-return-type.md b/.changeset/cli-spec-search-return-type.md
new file mode 100644
index 0000000000..571d31c982
--- /dev/null
+++ b/.changeset/cli-spec-search-return-type.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `search()` from `@astryxdesign/cli/api` is now declared to return `SearchResponse`, as its docs say, so TypeScript sees each result's `SearchResultEntry` fields instead of a bare `object`.
+
+@josephfarina
diff --git a/packages/cli/api/search/search-return-type.test.mjs b/packages/cli/api/search/search-return-type.test.mjs
new file mode 100644
index 0000000000..1df71aa557
--- /dev/null
+++ b/packages/cli/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);
+});
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 20fb501371..40237e49a9 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -884,7 +884,7 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
* @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 async function search(query, options = {}) {
const {cwd = process.cwd(), type, limit = 20} = options;
@@ -971,7 +971,10 @@ export async function search(query, options = {}) {
data: {
query: String(query).trim(),
matchCount: scored.length,
- results: limited,
+ // toResult gives every domain its command and domain fields.
+ results: /** @type {import('./search.type.mjs').SearchResultEntry[]} */ (
+ limited
+ ),
},
};
}