@appilots/cli 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { SourceControlCandidate } from './types/index.js';
+import * as t from '@babel/types';
+
 /**
  * Core types for the MCP Generator.
  */
@@ -16,6 +19,7 @@ interface ScreenDescriptor {
     filePath: string;
     title?: string;
     description?: string;
+    controlCandidates?: SourceControlCandidate[];
     components: ComponentDescriptor[];
     forms: FormDescriptor[];
     actions: ActionDescriptor[];
@@ -57,6 +61,36 @@ interface ScreenPermissionDescriptor {
     blockedActions?: string[];
     isPii?: boolean;
 }
+/**
+ * O que a varredura alcançou — para o relatório do CLI, não para o agente.
+ *
+ * Mora aqui e NÃO dentro do `MCPDocument`: o documento é contrato com o SDK,
+ * a API e o dashboard, e "quantos arquivos eu li" não é dado do app. Todo
+ * campo é opcional para quem consome, porque um analisador de plataforma
+ * pode não produzir nenhum — o relatório omite a seção em vez de mentir zeros.
+ */
+interface AnalysisDiagnostics {
+    navigation?: {
+        /** Arquivos que o glob de navegação alcançou. */
+        filesScanned: number;
+        /** Destes, quantos mencionam fábrica de navegador, ParamList, `.Navigator` ou `.Screen`. */
+        filesWithEvidence: number;
+        /** Fábricas reconhecidas atribuídas a um nome. Candidatos não contam. */
+        navigatorsDeclared: number;
+        /** Navegadores confirmados por `<X.Navigator>` no JSX. */
+        navigatorsWithJsx: number;
+        /** Rotas únicas no documento. */
+        routes: number;
+        /** Destas, quantas resolvem `component=` até um arquivo. */
+        routesLinkedToFile: number;
+        /** Roteador de arquivo encontrado, quando é o caso. */
+        fileBasedRouter?: {
+            kind: 'expo-router';
+            routeDir: string;
+            routes: number;
+        };
+    };
+}
 interface NavigationGraph {
     screens: Record<string, NavigationNode>;
     initialScreen: string;
@@ -167,6 +201,21 @@ interface ActionDescriptor {
     effect?: 'read' | 'write' | 'destructive' | string;
     riskLevel?: 'low' | 'medium' | 'high' | string;
     requiresConfirmation?: boolean;
+    /**
+     * How long this action's work takes, in milliseconds, as DECLARED by
+     * the app in `registerScreen()`. Read from the source, never inferred:
+     * the analyzer can prove a handler awaits something (see
+     * `appilotsInferred.isAsyncTrigger`) but never how long that await
+     * takes, and the gap between the two is what a wrong constant costs —
+     * the SDK stops waiting mid-operation and the agent plans against a
+     * loading screen with no controls on it.
+     *
+     * Carried into the document verbatim and into `waitPolicy.maxMs`,
+     * where it overrides the inferred 10s default. The SDK clamps it to
+     * its own ceiling; nothing here caps it, because the analyzer has no
+     * business overruling what the app said about its own operation.
+     */
+    asyncBudgetMs?: number;
     /**
      * Static-analysis hints derived by the MCP generator from the
      * action's handler body. Used by the SDK to refine waiting and
@@ -308,11 +357,23 @@ declare class ScreenAnalyzer {
     private strictScreens;
     /** Glob patterns that identify screen files in strict mode */
     private screenPatterns;
+    /**
+     * Arquivos que uma ROTA monta (`component={…}` resolvido pelo
+     * `NavigationAnalyzer`). Passam pelo filtro estrito sem depender de
+     * convenção de nome, porque um componente que uma rota monta É uma tela por
+     * definição — não é heurística, é o que o app declarou.
+     *
+     * É isto que resolve o caso `rocketchat`, cujas telas se chamam `*View.tsx`
+     * em `app/views/`, e o `coopcycle`, que não tem diretório `screens/` nenhum.
+     */
+    private routeTargetFiles;
     /** §D: Count of screens filtered out in strict mode (available after analyze()) */
     screensFilteredOut: number;
+    controlEvidenceFiles: Record<string, SourceControlCandidate[]>;
     constructor(config: AnalyzerConfig, options?: {
         strictScreens?: boolean;
         screenPatterns?: string[];
+        routeTargetFiles?: Set<string>;
     });
     /** Analyze all screens in the project */
     analyze(): Promise<ScreenDescriptor[]>;
@@ -446,6 +507,64 @@ declare class ScreenAnalyzer {
     private extractScreenName;
 }
 
+declare class ModuleGraph {
+    private readonly asts;
+    private readonly resolved;
+    /** `@src/*` → `<root>/src/*`, lido do tsconfig do app. */
+    private readonly aliases;
+    /** `uniswap` → `<repo>/packages/uniswap`, lido do workspace do monorepo. */
+    private readonly workspacePackages;
+    constructor(rootDir?: string);
+    /** AST de um arquivo, memoizada. `null` quando não parseia. */
+    parse(file: string): t.File | null;
+    /**
+     * `./account/Home` a partir de `src/navigation/index.tsx` → caminho absoluto.
+     * Só resolve caminho relativo: import de pacote (`@react-navigation/native`)
+     * é de terceiro e não tem tela nossa dentro.
+     */
+    resolve(fromFile: string, spec: string): string | null;
+    /** `import`s do arquivo, por nome local. */
+    private imports;
+    /** `const X = <init>` no topo do arquivo, incluindo `export const`. */
+    private topLevelInit;
+    /**
+     * Onde `name` é DEFINIDO — segue import e reexport de barrel.
+     * Devolve o arquivo e o nome sob o qual ele é definido lá.
+     */
+    resolveBinding(file: string, name: string, hops?: number): {
+        file: string;
+        name: string;
+    } | null;
+    /**
+     * O valor string de uma expressão de nome de rota, ou `null`.
+     *
+     * Cobre `"Chat"`, `ROUTES.CHAT`, `ROUTES.ONBOARDING.SPLASH` e `SOME_CONST` —
+     * seguindo import quando o objeto vem de outro arquivo. NÃO cobre template
+     * com interpolação nem valor calculado, de propósito.
+     */
+    stringConstant(file: string, node: t.Node | null | undefined, hops?: number): string | null;
+    /**
+     * O ARQUIVO onde vive o componente de uma rota, ou `null`.
+     *
+     * Aceita as três formas que o corpus mostrou: identificador
+     * (`component={Home}`), membro de barrel (`component={screens.AccountHome}`)
+     * e componente embrulhado em HOC (`component={gestureHandlerRootHOC(Chat)}`,
+     * que é como o `pocketpal` monta todas as telas do Drawer).
+     */
+    componentFile(file: string, node: t.Node | null | undefined, hops?: number): string | null;
+    /**
+     * Os arquivos DO PROJETO que este arquivo renderiza como JSX.
+     *
+     * `<ChatView …/>` em `ChatScreen.tsx` → `components/ChatView/ChatView.tsx`.
+     * Import de pacote devolve `null` no `resolve` e fica de fora: componente de
+     * terceiro não tem tela nossa dentro.
+     *
+     * Ignora `<X.Screen>` e `<X.Navigator>` de propósito — navegação é outro
+     * extractor, e um navegador não é conteúdo de tela.
+     */
+    renderedComponentFiles(file: string): string[];
+}
+
 /**
  * Analyzes React Navigation configuration to build a navigation graph.
  */
@@ -455,16 +574,140 @@ declare class NavigationAnalyzer {
     private navigationInclude;
     /** Extra glob patterns to exclude from navigation analysis */
     private navigationExclude;
+    /** Exposto para a composição reusar o cache de AST em vez de reparsear a árvore. */
+    readonly graph: ModuleGraph;
+    /**
+     * Rota → arquivo do componente que ela monta. É a única ligação entre o grafo
+     * de navegação e a árvore de telas; sem ela as duas metades do documento
+     * falam de coisas diferentes. Populada por `analyze()`.
+     */
+    readonly routeTargets: Map<string, string>;
+    /**
+     * Arquivos que DECLARAM uma fábrica de navegador.
+     *
+     * Um navegador aninhado é montado como `component=` de uma rota — no
+     * `apps/example-app`, `<Stack.Screen name="Main" component={MainTabNavigator} />`.
+     * Promover esse arquivo a tela criaria seis "telas" sem uma única ação, que é
+     * exatamente o falso positivo que o corpus existe para não repetir. Um
+     * navegador é um contêiner de rotas; a tela está um nível abaixo.
+     *
+     * Entram aqui os dois lados: o arquivo que CHAMA a fábrica e o arquivo que
+     * RENDERIZA `<X.Navigator>`. Não são o mesmo — `bluewallet` declara
+     * `DetailViewStack` num arquivo e escreve o JSX em
+     * `navigation/DetailViewScreensStack.tsx`, e checar só o primeiro deixava o
+     * segundo entrar como tela.
+     */
+    readonly navigatorFiles: Set<string>;
+    /** Preenchido por `analyze()`. Vazio antes disso. */
+    diagnostics: NonNullable<AnalysisDiagnostics['navigation']>;
     constructor(config: AnalyzerConfig, options?: {
         navigationInclude?: string[];
         navigationExclude?: string[];
     });
     /** Build the full navigation graph */
     analyze(): Promise<NavigationGraph>;
-    /** Find all navigation-related files */
+    /** Fase 1: as fábricas `create*Navigator()` atribuídas a um nome neste arquivo. */
+    private collectDeclarations;
+    /**
+     * As rotas de `createXNavigator({ screens: { … } })`.
+     *
+     * Quatro formas no corpus, todas em `rocketchat`:
+     *   `NewServerView`                                  — shorthand, nome = componente
+     *   `LoginView: createNativeStackScreen({ screen })` — embrulho da própria lib
+     *   `SelectListView: SelectListViewScreen`           — identificador direto
+     *   `ChatsStackNavigator: ChatsStack`                — navegador aninhado
+     *
+     * `groups: { G: { screens: { … } } }` também entra: faz parte da API estática
+     * e agrupar rotas não muda o que elas são.
+     */
+    private parseStaticScreens;
+    /**
+     * Todo arquivo-fonte do projeto — não os que ficam num diretório com o nome
+     * certo.
+     *
+     * POR QUE ISTO MUDOU. A lista anterior era `**\/navigation/**`,
+     * `**\/navigator*` e `**\/routes*`, o que fazia da descoberta de navegação uma
+     * convenção de caminho. Medido contra 20 apps React Native de terceiros
+     * (`qa/eval-corpus`), o filtro errava por motivos que nada têm a ver com o
+     * app não ter navegação:
+     *
+     *   - `pocketpal` declara 4 navegadores em `App.tsx` e dentro de `src/screens/`;
+     *   - `comapeo` usa `src/frontend/Navigation/` — `N` maiúsculo, e o glob é
+     *     sensível a caixa;
+     *   - `abacus` usa `src/routes/index.tsx` — `routes` é o DIRETÓRIO, e o glob
+     *     pedia um arquivo chamado `routes*`;
+     *   - `discourse` declara em `js/Discourse.js` — o glob só aceitava `.ts`/`.tsx`;
+     *   - `rainbow` tem 11 arquivos com navegador e o glob alcançava 1.
+     *
+     * Varrer tudo não custa uma varredura nova: `ReactNativePlatformAnalyzer` já
+     * globa e parseia a árvore inteira para `ComponentAnalyzer` e `FormAnalyzer`.
+     * O que segura o custo aqui é o portão por evidência em `analyze()`, que só
+     * parseia arquivo cujo texto menciona uma fábrica de navegador.
+     *
+     * Os globs antigos continuam na lista: se um projeto restringir `include`, o
+     * que era encontrado antes continua sendo.
+     */
     private findNavigationFiles;
-    /** Parse navigator definitions from a file */
-    private parseNavigators;
+    /**
+     * Fase 2: o JSX `<X.Navigator>` deste arquivo, ligado à declaração de `X` —
+     * que pode estar aqui ou em qualquer arquivo que este importe.
+     */
+    private parseNavigatorUsages;
+    /**
+     * Rotas declaradas FORA de qualquer `<X.Navigator>`.
+     *
+     * O CASO. A fase 2 desce a partir do `<X.Navigator>` e lê as `<X.Screen>`
+     * que estão DENTRO dele. Dois alvos do corpus não escrevem assim, e entre os
+     * dois são 171 rotas invisíveis:
+     *
+     *   `bluesky`  — `function commonScreens(Stack: typeof Flat) { return (<>
+     *                 <Stack.Screen name="NotFound" … /> … </>) }`, chamada de
+     *                dentro de seis navegadores diferentes. 70 rotas.
+     *   `comapeo`  — `export const createAppScreens = ({intl}) => (<>
+     *                 <RootStack.Group><RootStack.Screen … /></RootStack.Group></>)`,
+     *                num arquivo sem `<RootStack.Navigator>` nenhum. 101 rotas.
+     *
+     * A REGRA. Uma `<X.Screen name="…">` sem `<Y.Navigator>` ancestral é rota do
+     * navegador ao qual `X` se resolve. Não há palpite em jogo: o nome da rota é
+     * literal do fonte (ou constante que o resolvedor segue), e `X` precisa
+     * chegar a uma declaração de navegador que já existe. O que não resolve não
+     * vira nada.
+     *
+     * O ancestral é o que evita contar duas vezes — dentro do `<X.Navigator>` a
+     * fase 2 já leu, e somar aqui duplicaria cada rota do corpus inteiro.
+     *
+     * DUAS FORMAS DE RESOLVER `X`, e a segunda é o que o `bluesky` exige. A
+     * primeira é a de sempre (declaração local, ou `import` seguido até a
+     * origem) e resolve o `comapeo`. A segunda lê a ANOTAÇÃO DE TIPO do
+     * parâmetro: em `commonScreens(Stack: typeof Flat)`, quem diz que `Stack` é
+     * o navegador `Flat` é o próprio app, no fonte.
+     *
+     * O QUE ISTO NÃO FAZ. As 70 do `bluesky` ficam atribuídas a `Flat` — que as
+     * contém de fato (`{commonScreens(Flat, numUnread)}`) — e não aos outros
+     * cinco stacks que também chamam a mesma função. Seguir os seis pontos de
+     * chamada é análise interprocedural, e o ganho seria só de atribuição: o nome
+     * da rota e o arquivo da tela, que é o que o agente usa, já saem certos.
+     */
+    private parseDetachedScreens;
+    /**
+     * De um `X` usado como `<X.Screen>` até a declaração do navegador.
+     *
+     * Além do caminho normal — declaração local ou `import` seguido até a origem
+     * — aceita `X` como PARÂMETRO anotado com `typeof Y`. É o idioma do
+     * `bluesky`, e a anotação é declaração do app: nada aqui é inferido do nome.
+     */
+    private resolveDetachedNavigator;
+    /**
+     * De `<X.Navigator>` até a declaração de `X`.
+     *
+     * Primeiro no próprio arquivo; se não estiver, segue o `import` até onde `X`
+     * é definido. Resolver pelo import é o que torna a junção entre arquivos
+     * segura: dois `Stack` de arquivos diferentes nunca colidem, porque a chave
+     * é o arquivo de DEFINIÇÃO.
+     */
+    private resolveNavigator;
+    /** O valor string de um atributo JSX, resolvendo constante importada. */
+    private attributeString;
     /**
      * Is this JSX element `<navigatorVarName.MEMBER …>`?
      */
@@ -487,6 +730,14 @@ declare class NavigationAnalyzer {
     private collectScreenElements;
     /** Extract screens from a navigator JSX element */
     private extractScreensFromNavigator;
+    /**
+     * Uma `<X.Screen>` isolada até a rota que ela declara.
+     *
+     * Separado de `extractScreensFromNavigator` porque a MESMA leitura serve para
+     * a `<X.Screen>` que mora dentro do `<X.Navigator>` e para a que mora fora
+     * dele — só a forma de chegar até o elemento muda.
+     */
+    private parseScreenElement;
     /** Extract string attribute value from JSX attributes */
     private extractAttributeValue;
     /** Parse TypeScript type exports (ParamList types) */
@@ -565,12 +816,18 @@ interface PlatformAnalyzerOptions {
     navigationExclude?: string[];
 }
 interface PlatformAnalyzerResult {
+    controlEvidenceFiles?: Record<string, SourceControlCandidate[]>;
     screens: ScreenDescriptor[];
     navigation: NavigationGraph;
     /** Number of source files matched by glob (before screen filtering). */
     analyzedFiles: number;
     /** Number of files excluded by strict screen filtering, when applicable. */
     screensFilteredOut?: number;
+    /**
+     * O que a varredura alcançou. Opcional: o analisador web ainda não produz,
+     * e o relatório do CLI degrada omitindo a seção em vez de mentir zeros.
+     */
+    diagnostics?: AnalysisDiagnostics;
 }
 /**
  * Seam `MCPGenerator` consumes to turn a project's source tree into
@@ -907,6 +1164,14 @@ interface MCPOutput {
     filePath: string;
     format: 'json';
     checksum: string;
+    /**
+     * O que a varredura alcançou, para o relatório do CLI.
+     *
+     * Fica FORA do `MCPDocument` de propósito: o documento é contrato com o
+     * SDK, a API e o dashboard, e diagnóstico não é dado do app. Opcional
+     * porque o analisador web não produz — quem consome trata a ausência.
+     */
+    diagnostics?: AnalysisDiagnostics;
 }
 
 /**
@@ -1069,6 +1334,14 @@ interface AppilotsConfig {
     manifestPath?: string;
     /** `appilots eval` settings — see docs: Testing your agent between releases. */
     eval?: EvalConfig;
+    /** Knowledge base / RAG configuration — see docs: Knowledge base. */
+    knowledge?: KnowledgeConfig;
+}
+interface KnowledgeConfig {
+    /** Glob patterns for documentation files to index (e.g. "docs/*.md"). */
+    sources?: string[];
+    /** Glob patterns to exclude from indexing. */
+    exclude?: string[];
 }
 interface EvalConfig {
     /** Directory of `*.json` scenario files. Default: `<outputDir>/scenarios`. */
@@ -1117,7 +1390,20 @@ declare function getEnvOverrides(env?: NodeJS.ProcessEnv): EnvOverrides;
  * @returns AppilotsConfig if a file or APPILOTS_API_KEY exists, null otherwise
  * @throws when the file is unparseable or the merged config fails validation
  */
-declare function loadConfig(onWarn?: (message: string) => void): AppilotsConfig | null;
+interface LoadConfigOptions {
+    /**
+     * `false` quando o comando não fala com o servidor.
+     *
+     * `generate` é local: não precisa de `apiKey` e não deveria ser impedido por
+     * ela faltar. Com `requireApiKey: true` (o padrão), um `.appilotsrc` que só
+     * declara `screenPatterns` derruba a validação, `generate` engole o erro e
+     * IGNORA a config inteira — o comentário dele dizia "não pode bloquear" e o
+     * efeito real era "não pode ser lida". O resultado prático: `generate` e
+     * `sync` produzem documentos diferentes para o mesmo projeto.
+     */
+    requireApiKey?: boolean;
+}
+declare function loadConfig(onWarn?: (message: string) => void, options?: LoadConfigOptions): AppilotsConfig | null;
 /**
  * Saves configuration to .appilotsrc in the given directory
  *
@@ -1245,6 +1531,21 @@ interface StatusResult {
     };
     error?: string;
 }
+/**
+ * Result from a knowledge sync operation
+ */
+interface KnowledgeSyncResult {
+    success: boolean;
+    uploaded: number;
+    skipped: number;
+    errors: number;
+    error?: string;
+    details?: Array<{
+        filename: string;
+        status: 'uploaded' | 'skipped' | 'error';
+        error?: string;
+    }>;
+}
 /**
  * Appilots API client configuration
  */
@@ -1307,6 +1608,18 @@ declare class AppilotsAPIClient {
      *   EVAL_MAX_SCENARIOS_PER_RUN (currently 20) as a cost guard.
      */
     evalRun(scenarios: EvalScenarioRequest[]): Promise<EvalRunResult>;
+    /**
+     * Syncs knowledge documents with the Appilots backend.
+     *
+     * @param documents Array of documents to sync (filename, base64 content, mimeType, checksum)
+     * @returns KnowledgeSyncResult with counts of uploaded, skipped, and errored docs
+     */
+    knowledgeSync(documents: Array<{
+        filename: string;
+        content: string;
+        mimeType: string;
+        checksum: string;
+    }>): Promise<KnowledgeSyncResult>;
     /**
      * Checks if the Appilots API server is healthy
      *
@@ -1322,6 +1635,6 @@ declare class AppilotsAPIClient {
  * banner. Kept identical to package.json by the release flow;
  * `version.test.ts` fails if the two ever disagree.
  */
-declare const CLI_VERSION = "0.11.0";
+declare const CLI_VERSION = "0.13.0";
 
 export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, type AppilotsManifest, CLI_VERSION, ComponentAnalyzer, type ComponentDescriptor, DEFAULT_MANIFEST_FILENAME, DEFAULT_WEB_SCREEN_PATTERNS, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, GenericPlatformAnalyzer, type LoadManifestResult, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type PlatformAnalyzer, type PlatformAnalyzerOptions, type PlatformAnalyzerResult, ReactNativePlatformAnalyzer, ReactWebPlatformAnalyzer, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, WebNavigationAnalyzer, type WebNavigationResult, type WebRoute, WebScreenAnalyzer, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, loadManifest, mergeManifestNavigation, mergeManifestScreens, resolvePathToScreen, saveConfig, screenNameFromPath, validateConfig };