refactor: reduce core any usage (#216)

Author: jackwener

src/cli.ts

@@ -140,7 +140,7 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
         : undefined;
       const workspace = `explore:${inferHost(url, opts.site)}`;
       const result = await exploreUrl(url, {
-        BrowserFactory: getBrowserFactory() as any,
+        BrowserFactory: getBrowserFactory(),
         site: opts.site,
         goal: opts.goal,
         waitSeconds: parseFloat(opts.wait),
@@ -172,7 +172,7 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       const workspace = `generate:${inferHost(url, opts.site)}`;
       const r = await generateCliFromUrl({
         url,
-        BrowserFactory: getBrowserFactory() as any,
+        BrowserFactory: getBrowserFactory(),
         builtinClis: BUILTIN_CLIS,
         userClis: USER_CLIS,
         goal: opts.goal,

src/execution.ts

@@ -18,12 +18,17 @@ import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMM
 
 /** Set of TS module paths that have been loaded */
 const _loadedModules = new Set<string>();
+type CommandArgs = Record<string, unknown>;
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
 
 /**
  * Validates and coerces arguments based on the command's Arg definitions.
  */
-export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any> {
-  const result: Record<string, any> = { ...kwargs };
+export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
+  const result: CommandArgs = { ...kwargs };
 
   for (const argDef of cmdArgs) {
     const val = result[argDef.name];
@@ -72,9 +77,9 @@ export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any
 async function runCommand(
   cmd: CliCommand,
   page: IPage | null,
-  kwargs: Record<string, any>,
+  kwargs: CommandArgs,
   debug: boolean,
-): Promise<any> {
+): Promise<unknown> {
   // Lazy-load TS module on first execution (manifest fast-path)
   const internal = cmd as InternalCliCommand;
   if (internal._lazy && internal._modulePath) {
@@ -83,9 +88,9 @@ async function runCommand(
       try {
         await import(`file://${modulePath}`);
         _loadedModules.add(modulePath);
-      } catch (err: any) {
+      } catch (err) {
         throw new AdapterLoadError(
-          `Failed to load adapter module ${modulePath}: ${err.message}`,
+          `Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`,
           'Check that the adapter file exists and has no syntax errors.',
         );
       }
@@ -127,14 +132,14 @@ function resolvePreNav(cmd: CliCommand): string | null {
  */
 export async function executeCommand(
   cmd: CliCommand,
-  rawKwargs: Record<string, any>,
+  rawKwargs: CommandArgs,
   debug: boolean = false,
-): Promise<any> {
-  let kwargs: Record<string, any>;
+): Promise<unknown> {
+  let kwargs: CommandArgs;
   try {
     kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
-  } catch (err: any) {
-    throw new Error(`[Argument Validation Error]\n${err.message}`);
+  } catch (err) {
+    throw new Error(`[Argument Validation Error]\n${getErrorMessage(err)}`);
   }
 
   if (shouldUseBrowserSession(cmd)) {

src/explore.ts

@@ -9,10 +9,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { DEFAULT_BROWSER_EXPLORE_TIMEOUT, browserSession, runWithTimeout } from './runtime.js';
+import type { IBrowserFactory } from './runtime.js';
 import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_ROLES } from './constants.js';
 import { detectFramework } from './scripts/framework.js';
 import { discoverStores } from './scripts/store.js';
 import { interactFuzz } from './scripts/interact.js';
+import type { IPage } from './types.js';
 
 // ── Site name detection ────────────────────────────────────────────────────
 
@@ -68,7 +70,61 @@ interface InferredCapability {
   name: string; description: string; strategy: string; confidence: number;
   endpoint: string; itemPath: string | null;
   recommendedColumns: string[];
-  recommendedArgs: Array<{ name: string; type: string; required: boolean; default?: any }>;
+  recommendedArgs: Array<{ name: string; type: string; required: boolean; default?: unknown }>;
+  storeHint?: { store: string; action: string };
+}
+
+export interface ExploreManifest {
+  site: string;
+  target_url: string;
+  final_url: string;
+  title: string;
+  framework: Record<string, boolean>;
+  stores: Array<{ type: DiscoveredStore['type']; id: string; actions: string[] }>;
+  top_strategy: string;
+  explored_at?: string;
+}
+
+export interface ExploreAuthSummary {
+  top_strategy: string;
+  indicators: string[];
+  framework: Record<string, boolean>;
+}
+
+export interface ExploreEndpointArtifact {
+  pattern: string;
+  method: string;
+  url: string;
+  status: number | null;
+  contentType: string;
+  score: number;
+  queryParams: string[];
+  itemPath: string | null;
+  itemCount: number;
+  detectedFields: Record<string, string>;
+  authIndicators: string[];
+}
+
+export interface ExploreResult {
+  site: string;
+  target_url: string;
+  final_url: string;
+  title: string;
+  framework: Record<string, boolean>;
+  stores: DiscoveredStore[];
+  top_strategy: string;
+  endpoint_count: number;
+  api_endpoint_count: number;
+  capabilities: InferredCapability[];
+  auth_indicators: string[];
+  out_dir: string;
+}
+
+export interface ExploreBundle {
+  manifest: ExploreManifest;
+  endpoints: ExploreEndpointArtifact[];
+  capabilities: InferredCapability[];
+  auth: ExploreAuthSummary;
 }
 
 /**
@@ -167,7 +223,7 @@ function flattenFields(obj: unknown, prefix: string, maxDepth: number): string[]
   return names;
 }
 
-function scoreEndpoint(ep: { contentType: string; responseAnalysis: any; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
+function scoreEndpoint(ep: { contentType: string; responseAnalysis: AnalyzedEndpoint['responseAnalysis']; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
   let s = 0;
   if (ep.contentType.includes('json')) s += 10;
   if (ep.responseAnalysis) { s += 5; s += Math.min(ep.responseAnalysis.itemCount, 10); s += Object.keys(ep.responseAnalysis.detectedFields).length * 2; }
@@ -321,7 +377,7 @@ function inferCapabilitiesFromEndpoints(
 /** Write explore artifacts (manifest, endpoints, capabilities, auth, stores) to disk. */
 async function writeExploreArtifacts(
   targetDir: string,
-  result: Record<string, any>,
+  result: Omit<ExploreResult, 'out_dir'>,
   analyzedEndpoints: AnalyzedEndpoint[],
   stores: DiscoveredStore[],
 ): Promise<void> {
@@ -354,12 +410,12 @@ async function writeExploreArtifacts(
 export async function exploreUrl(
   url: string,
   opts: {
-    BrowserFactory: new () => any;
+    BrowserFactory: new () => IBrowserFactory;
     site?: string; goal?: string; authenticated?: boolean;
     outDir?: string; waitSeconds?: number; query?: string;
     clickLabels?: string[]; auto?: boolean; workspace?: string;
   },
-): Promise<Record<string, any>> {
+): Promise<ExploreResult> {
   const waitSeconds = opts.waitSeconds ?? 3.0;
   const exploreTimeout = Math.max(DEFAULT_BROWSER_EXPLORE_TIMEOUT, 45.0 + waitSeconds * 8.0);
 
@@ -467,7 +523,7 @@ export async function exploreUrl(
   }, { workspace: opts.workspace });
 }
 
-export function renderExploreSummary(result: Record<string, any>): string {
+export function renderExploreSummary(result: ExploreResult): string {
   const lines = [
     'opencli probe: OK', `Site: ${result.site}`, `URL: ${result.target_url}`,
     `Title: ${result.title || '(none)'}`, `Strategy: ${result.top_strategy}`,
@@ -492,7 +548,7 @@ export function renderExploreSummary(result: Record<string, any>): string {
   return lines.join('\n');
 }
 
-async function readPageMetadata(page: any /* IPage */): Promise<{ url: string; title: string }> {
+async function readPageMetadata(page: IPage): Promise<{ url: string; title: string }> {
   try {
     const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
     if (result && typeof result === 'object') return { url: String(result.url ?? ''), title: String(result.title ?? '') };

src/generate.ts

@@ -9,10 +9,59 @@
  */
 
 import { exploreUrl } from './explore.js';
-import { synthesizeFromExplore } from './synthesize.js';
+import type { IBrowserFactory } from './runtime.js';
+import { synthesizeFromExplore, type SynthesizeCandidateSummary, type SynthesizeResult } from './synthesize.js';
 
 // TODO: implement real CLI registration (copy candidate YAML to user clis dir)
-function registerCandidates(_opts: any): any { return { ok: true, count: 0 }; }
+interface RegisterCandidatesOptions {
+  target: string;
+  builtinClis?: string;
+  userClis?: string;
+  name?: string;
+}
+
+interface RegisterCandidatesResult {
+  ok: boolean;
+  count: number;
+}
+
+export interface GenerateCliOptions {
+  url: string;
+  BrowserFactory: new () => IBrowserFactory;
+  builtinClis?: string;
+  userClis?: string;
+  goal?: string | null;
+  site?: string;
+  waitSeconds?: number;
+  top?: number;
+  register?: boolean;
+  workspace?: string;
+}
+
+export interface GenerateCliResult {
+  ok: boolean;
+  goal?: string | null;
+  normalized_goal?: string | null;
+  site: string;
+  selected_candidate: SynthesizeCandidateSummary | null;
+  selected_command: string;
+  explore: {
+    endpoint_count: number;
+    api_endpoint_count: number;
+    capability_count: number;
+    top_strategy: string;
+    framework: Record<string, boolean>;
+  };
+  synthesize: {
+    candidate_count: number;
+    candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
+  };
+  register: RegisterCandidatesResult | null;
+}
+
+function registerCandidates(_opts: RegisterCandidatesOptions): RegisterCandidatesResult {
+  return { ok: true, count: 0 };
+}
 
 const CAPABILITY_ALIASES: Record<string, string[]> = {
   search:    ['search', '搜索', '查找', 'query', 'keyword'],
@@ -41,7 +90,7 @@ function normalizeGoal(goal?: string | null): string | null {
 /**
  * Select the best candidate matching the user's goal.
  */
-function selectCandidate(candidates: any[], goal?: string | null): any {
+function selectCandidate(candidates: SynthesizeResult['candidates'], goal?: string | null): SynthesizeCandidateSummary | null {
   if (!candidates.length) return null;
   if (!goal) return candidates[0]; // highest confidence first
 
@@ -58,12 +107,12 @@ function selectCandidate(candidates: any[], goal?: string | null): any {
   return partial ?? candidates[0];
 }
 
-export async function generateCliFromUrl(opts: any): Promise<any> {
+export async function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult> {
   // Step 1: Deep Explore
   const exploreResult = await exploreUrl(opts.url, {
     BrowserFactory: opts.BrowserFactory,
     site: opts.site,
-    goal: normalizeGoal(opts.goal) ?? opts.goal,
+    goal: normalizeGoal(opts.goal) ?? opts.goal ?? undefined,
     waitSeconds: opts.waitSeconds ?? 3,
     workspace: opts.workspace,
   });
@@ -75,10 +124,10 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
 
   // Step 3: Select best candidate for goal
   const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
-  const selectedSite = selected?.site ?? synthesizeResult.site ?? exploreResult.site;
+  const selectedSite = synthesizeResult.site ?? exploreResult.site;
 
   // Step 4: Register (if requested)
-  let registerResult: any = null;
+  let registerResult: RegisterCandidatesResult | null = null;
   if (opts.register !== false && synthesizeResult.candidate_count > 0) {
     try {
       registerResult = registerCandidates({
@@ -108,7 +157,7 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
     },
     synthesize: {
       candidate_count: synthesizeResult.candidate_count,
-      candidates: (synthesizeResult.candidates ?? []).map((c: any) => ({
+      candidates: (synthesizeResult.candidates ?? []).map((c) => ({
         name: c.name,
         strategy: c.strategy,
         confidence: c.confidence,
@@ -118,7 +167,7 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
   };
 }
 
-export function renderGenerateSummary(r: any): string {
+export function renderGenerateSummary(r: GenerateCliResult): string {
   const lines = [
     `opencli generate: ${r.ok ? 'OK' : 'FAIL'}`,
     `Site: ${r.site}`,