@fairfox/polly 0.11.0 → 0.12.1

package/dist/tools/analysis/src/extract/manifest.d.ts

@@ -0,0 +1,64 @@
+import type { ManifestInfo } from "../types/architecture";
+/**
+ * Parse manifest.json and extract context information
+ */
+export declare class ManifestParser {
+    private manifestPath;
+    private manifestData;
+    private baseDir;
+    constructor(projectRoot: string, optional?: boolean);
+    /**
+     * Check if manifest.json exists and was loaded
+     */
+    hasManifest(): boolean;
+    /**
+     * Parse manifest and extract all information
+     */
+    parse(): ManifestInfo;
+    /**
+     * Get context entry points from manifest
+     */
+    getContextEntryPoints(): Record<string, string>;
+    private addBackgroundEntryPoint;
+    private addContentScriptEntryPoint;
+    private addPopupEntryPoint;
+    private addOptionsEntryPoint;
+    private addDevtoolsEntryPoint;
+    /**
+     * Parse background configuration
+     */
+    private parseBackground;
+    /**
+     * Parse content scripts configuration
+     */
+    private parseContentScripts;
+    /**
+     * Parse popup configuration
+     */
+    private parsePopup;
+    /**
+     * Parse options configuration
+     */
+    private parseOptions;
+    /**
+     * Parse devtools configuration
+     */
+    private parseDevtools;
+    /**
+     * Find source file from manifest reference
+     * Tries multiple locations: exact path, src/ directory, .ts extension
+     */
+    private findSourceFile;
+    /**
+     * Find associated JavaScript/TypeScript file for an HTML file
+     */
+    private findAssociatedJS;
+}
+/**
+ * Parse manifest.json and extract information
+ */
+export declare function parseManifest(projectRoot: string): ManifestInfo;
+/**
+ * Get context entry points from manifest.json
+ */
+export declare function getContextEntryPoints(projectRoot: string): Record<string, string>;

package/dist/tools/analysis/src/extract/project-detector.d.ts

@@ -0,0 +1,103 @@
+import type { ProjectConfig } from "../types/architecture";
+/**
+ * Detect project type and generate configuration
+ * Falls back to tsconfig.json when manifest.json is not available
+ */
+export declare class ProjectDetector {
+    private projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Detect project type and return configuration
+     */
+    detect(): ProjectConfig;
+    /**
+     * Detect Chrome extension from manifest.json
+     */
+    private detectChromeExtension;
+    /**
+     * Detect background script entry point
+     */
+    private detectBackgroundEntry;
+    /**
+     * Detect content script entry point
+     */
+    private detectContentScriptEntry;
+    /**
+     * Detect popup entry point
+     */
+    private detectPopupEntry;
+    /**
+     * Detect options page entry point
+     */
+    private detectOptionsEntry;
+    /**
+     * Detect PWA from manifest.json
+     */
+    private detectPWA;
+    /**
+     * Detect Electron app
+     */
+    private detectElectron;
+    /**
+     * Detect WebSocket/server app with content analysis and confidence scoring
+     */
+    private detectWebSocketApp;
+    /**
+     * Score server candidates based on content analysis
+     * Returns sorted array with highest confidence first
+     */
+    private scoreServerCandidates;
+    /**
+     * Analyze server candidate content and return scoring details
+     */
+    private analyzeServerCandidate;
+    /**
+     * Get regex patterns for server framework detection
+     */
+    private getServerPatterns;
+    /**
+     * Detect frameworks in content and calculate score
+     */
+    private detectFrameworksInContent;
+    /**
+     * Score Bun framework patterns
+     */
+    private scoreBunFramework;
+    /**
+     * Score WebSocket library patterns
+     */
+    private scoreWebSocketLibraries;
+    /**
+     * Score HTTP framework patterns
+     */
+    private scoreHTTPFrameworks;
+    /**
+     * Score generic server patterns
+     */
+    private scoreGenericPatterns;
+    /**
+     * Score entry point indicators in content
+     */
+    private scoreEntryPointIndicators;
+    /**
+     * Score based on file name patterns
+     */
+    private scoreFileName;
+    /**
+     * Fallback: Generic TypeScript project
+     * Uses tsconfig.json to find entry points
+     */
+    private detectGenericProject;
+    /**
+     * Find source file from manifest reference
+     */
+    private findSourceFile;
+    /**
+     * Find associated JavaScript/TypeScript file for an HTML file
+     */
+    private findAssociatedJS;
+}
+/**
+ * Detect project configuration from project root
+ */
+export declare function detectProjectConfig(projectRoot: string): ProjectConfig;

package/dist/tools/analysis/src/extract/relationships.d.ts

@@ -0,0 +1,119 @@
+import { Node, type SourceFile } from "ts-morph";
+/**
+ * Represents a relationship between components detected from code analysis
+ */
+export interface DetectedRelationship {
+    /** Source component (handler, service, etc.) */
+    from: string;
+    /** Target component being called/used */
+    to: string;
+    /** Description of the relationship */
+    description: string;
+    /** Technology/method used (e.g., "Function Call", "Import", "SQL", "HTTP") */
+    technology?: string;
+    /** Confidence level of this detection */
+    confidence: "high" | "medium" | "low";
+    /** Evidence supporting this detection */
+    evidence: string[];
+}
+/**
+ * Extracts component relationships from handler code
+ */
+export declare class RelationshipExtractor {
+    /**
+     * Extract relationships from a function/handler body
+     */
+    extractFromHandler(handlerNode: Node, sourceFile: SourceFile, handlerName: string): DetectedRelationship[];
+    /**
+     * Recursively extract relationships from a node and follow function calls
+     */
+    private extractFromNode;
+    /**
+     * Process a single descendant node for relationship extraction
+     */
+    private processDescendantNode;
+    /**
+     * Process a call expression for relationship extraction
+     */
+    private processCallExpression;
+    /**
+     * Process an identifier call (local or imported function)
+     */
+    private processIdentifierCall;
+    /**
+     * Resolve function declaration from name
+     */
+    private resolveFunctionDeclaration;
+    /**
+     * Follow a function call recursively
+     */
+    private followFunctionCall;
+    /**
+     * Try to add a service call relationship based on function name
+     */
+    private tryAddServiceCallRelationship;
+    /**
+     * Extract relationship from a function call
+     */
+    private extractFromFunctionCall;
+    /**
+     * Extract relationship from property access chain
+     * Handles both simple (obj.method) and nested (obj.prop.method) patterns
+     */
+    private extractFromPropertyAccess;
+    /**
+     * Extract relationship from database call
+     */
+    private extractFromDatabaseCall;
+    /**
+     * Extract relationship from fetch/HTTP call
+     */
+    private extractFromFetchCall;
+    /**
+     * Infer component name from object.method pattern
+     */
+    private inferComponentFromCall;
+    /**
+     * Infer component name from function name patterns
+     * Detects patterns like getDatabase(), createRepositories(), etc.
+     */
+    private inferComponentFromFunctionName;
+    /**
+     * Match component patterns for get/create functions
+     */
+    private matchComponentPattern;
+    /**
+     * Match patterns for init/setup functions
+     */
+    private matchInitPattern;
+    /**
+     * Resolve component from import statement
+     */
+    private resolveComponentFromImport;
+    /**
+     * Infer component from module path
+     */
+    private inferComponentFromModulePath;
+    /**
+     * Resolve imported function to its declaration in another file
+     * This enables cross-file relationship detection for architectures where
+     * handlers are separated from routing logic
+     */
+    private resolveImportedFunction;
+    /**
+     * Find function declaration or arrow function in a module
+     */
+    private findFunctionInModule;
+    /**
+     * Infer database operation type
+     */
+    private inferDatabaseOperation;
+    /**
+     * Convert name to component ID format
+     */
+    private toComponentId;
+    /**
+     * Remove duplicate relationships
+     */
+    private deduplicateRelationships;
+}

package/dist/tools/analysis/src/extract/types.d.ts

@@ -0,0 +1,139 @@
+import type { CodebaseAnalysis } from "../types";
+export declare class TypeExtractor {
+    private project;
+    constructor(tsConfigPath: string);
+    /**
+     * Analyze the codebase and extract state types and message types
+     */
+    analyzeCodebase(stateFilePath?: string): Promise<CodebaseAnalysis>;
+    /**
+     * Extract handler analysis from the project
+     */
+    private extractHandlerAnalysis;
+    /**
+     * Filter and log message types, keeping only valid TLA+ identifiers
+     */
+    private filterAndLogMessageTypes;
+    /**
+     * Log warnings about invalid message types
+     */
+    private logInvalidMessageTypes;
+    /**
+     * Filter and log handlers, keeping only those with valid TLA+ identifier message types
+     */
+    private filterAndLogHandlers;
+    /**
+     * Log warnings about filtered handlers
+     */
+    private logInvalidHandlers;
+    /**
+     * Check if a string is a valid TLA+ identifier
+     * TLA+ identifiers must:
+     * - Start with a letter (a-zA-Z)
+     * - Contain only letters, digits, and underscores
+     * - Not be empty
+     */
+    private isValidTLAIdentifier;
+    /**
+     * Extract state type from a specific file
+     */
+    private extractStateType;
+    /**
+     * Find state type by searching common patterns
+     */
+    private findStateType;
+    /**
+     * Find message types by searching for type unions
+     * Handles:
+     * - Simple string literal unions
+     * - Discriminated unions ({ type: 'foo' } | { type: 'bar' })
+     * - Type aliases across files
+     * - Template literal types (with warning)
+     * - Conditional types (conservatively)
+     * - Mapped types
+     */
+    private findMessageTypes;
+    /**
+     * Extract message types from a TypeScript type
+     * Recursively handles unions, discriminated unions, aliases, etc.
+     */
+    private extractMessageTypesFromType;
+    /**
+     * Extract message types from union type
+     */
+    private extractFromUnionType;
+    /**
+     * Extract message types from a single union member
+     */
+    private extractFromUnionMember;
+    /**
+     * Extract message types from discriminated union
+     */
+    private extractFromDiscriminatedUnion;
+    /**
+     * Extract message types from type alias
+     */
+    private extractFromTypeAlias;
+    /**
+     * Extract message types from conditional type
+     */
+    private extractFromConditionalType;
+    /**
+     * Extract string literal from conditional branch
+     */
+    private extractStringLiteralFromBranch;
+    /**
+     * Extract message types from mapped type
+     */
+    private extractFromMappedType;
+    /**
+     * Warn about template literal types
+     */
+    private warnTemplateLiteral;
+    /**
+     * Convert ts-morph Type to our TypeInfo
+     */
+    private convertType;
+    /**
+     * Convert union type to TypeInfo
+     */
+    private convertUnionType;
+    /**
+     * Convert array type to TypeInfo
+     */
+    private convertArrayType;
+    /**
+     * Try to convert Map or Set type to TypeInfo
+     */
+    private tryConvertCollectionType;
+    /**
+     * Convert object type to TypeInfo
+     */
+    private convertObjectType;
+    /**
+     * Analyze fields and determine confidence/bounds
+     */
+    private analyzeFields;
+    /**
+     * Analyze a single field and determine configuration needs
+     */
+    private analyzeField;
+    private analyzeBooleanField;
+    private analyzeEnumField;
+    private analyzeArrayField;
+    private analyzeNumberField;
+    private analyzeStringField;
+    private analyzeMapSetField;
+    /**
+     * Try to find array bounds by searching for length checks
+     */
+    private findArrayBound;
+    /**
+     * Try to find number bounds by searching for comparisons
+     */
+    private findNumberBound;
+}
+export declare function analyzeCodebase(options: {
+    tsConfigPath: string;
+    stateFilePath?: string;
+}): Promise<CodebaseAnalysis>;

package/dist/tools/analysis/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./extract/index.ts";
+export * from "./types/index.ts";

package/dist/tools/analysis/src/types/adr.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Architecture Decision Record
+ * Based on Michael Nygard's ADR format
+ */
+export type ADR = {
+    /** ADR number/ID */
+    id: string;
+    /** Decision title */
+    title: string;
+    /** Status: proposed, accepted, deprecated, superseded */
+    status: ADRStatus;
+    /** Date of decision */
+    date: string;
+    /** Context - what is the issue motivating this decision */
+    context: string;
+    /** Decision - what is the change we're proposing */
+    decision: string;
+    /** Consequences - what becomes easier or more difficult */
+    consequences: string;
+    /** Optional: Alternatives considered */
+    alternatives?: string[];
+    /** Optional: Links to superseding/superseded ADRs */
+    links?: ADRLink[];
+    /** Source file path */
+    source: string;
+};
+export type ADRStatus = "proposed" | "accepted" | "deprecated" | "superseded";
+export type ADRLink = {
+    type: "supersedes" | "superseded-by" | "related-to";
+    adrId: string;
+    title?: string;
+};
+/**
+ * Collection of ADRs
+ */
+export type ADRCollection = {
+    adrs: ADR[];
+    directory: string;
+};

package/dist/tools/analysis/src/types/architecture.d.ts

@@ -0,0 +1,198 @@
+import type { MessageHandler } from "./core";
+/**
+ * Information about an execution context (background, content, popup, etc.)
+ */
+export type ContextInfo = {
+    /** Type of context */
+    type: string;
+    /** Entry point file path */
+    entryPoint: string;
+    /** Message handlers defined in this context */
+    handlers: MessageHandler[];
+    /** Chrome APIs used in this context */
+    chromeAPIs: string[];
+    /** External APIs called from this context */
+    externalAPIs: ExternalAPICall[];
+    /** UI components rendered (for popup/options/devtools) */
+    components?: ComponentInfo[];
+    /** Dependencies/imports */
+    dependencies: string[];
+    /** JSDoc description if available */
+    description?: string;
+};
+/**
+ * Component information (for UI contexts)
+ */
+export type ComponentInfo = {
+    name: string;
+    type: "function" | "class";
+    filePath: string;
+    line: number;
+    props?: string[];
+    description?: string;
+};
+/**
+ * Represents a message flow between contexts
+ */
+export type MessageFlow = {
+    /** Message type identifier */
+    messageType: string;
+    /** Source context */
+    from: string;
+    /** Destination context(s) */
+    to: string[];
+    /** What triggers this flow (user action, event, etc.) */
+    trigger?: string;
+    /** Sequence of steps in this flow */
+    sequence: MessageStep[];
+    /** Flow name (from @flow annotation or inferred) */
+    flowName?: string;
+    /** Description (from JSDoc) */
+    description?: string;
+};
+/**
+ * A step in a message flow sequence
+ */
+export type MessageStep = {
+    /** Step number in sequence */
+    step: number;
+    /** Action description */
+    action: string;
+    /** Context where this step occurs */
+    context: string;
+    /** Source location */
+    location?: {
+        file: string;
+        line: number;
+    };
+};
+/**
+ * External system integration
+ */
+export type ExternalIntegration = {
+    /** Type of integration */
+    type: "api" | "storage" | "browser-api" | "external-script" | "websocket";
+    /** Name/identifier */
+    name: string;
+    /** Technology/protocol */
+    technology?: string;
+    /** Base URL or endpoint */
+    url?: string;
+    /** Where it's used (file paths) */
+    usedIn: string[];
+    /** Description (from JSDoc or inferred) */
+    description?: string;
+    /** Specific API calls made */
+    calls?: ExternalAPICall[];
+};
+/**
+ * A specific API call
+ */
+export type ExternalAPICall = {
+    /** HTTP method or API method name */
+    method: string;
+    /** Endpoint or resource */
+    endpoint: string;
+    /** Where this call is made */
+    location: {
+        file: string;
+        line: number;
+    };
+    /** Description */
+    description?: string;
+};
+/**
+ * Parsed manifest.json information
+ */
+export type ManifestInfo = {
+    /** Extension name */
+    name: string;
+    /** Version */
+    version: string;
+    /** Description */
+    description?: string;
+    /** Manifest version (2 or 3) */
+    manifestVersion: number;
+    /** Background script/service worker */
+    background?: {
+        type: "script" | "service_worker";
+        files: string[];
+    };
+    /** Content scripts */
+    contentScripts?: Array<{
+        matches: string[];
+        js: string[];
+        css?: string[];
+    }>;
+    /** Popup */
+    popup?: {
+        html: string;
+        default?: boolean;
+    };
+    /** Options page */
+    options?: {
+        page: string;
+        openInTab?: boolean;
+    };
+    /** DevTools page */
+    devtools?: {
+        page: string;
+    };
+    /** Permissions */
+    permissions?: string[];
+    /** Host permissions */
+    hostPermissions?: string[];
+};
+/**
+ * Project type identifier
+ */
+export type ProjectType = "chrome-extension" | "pwa" | "websocket-app" | "electron" | "generic";
+/**
+ * Project configuration with context mappings
+ * Allows visualization to work with any project type
+ */
+export type ProjectConfig = {
+    /** Type of project */
+    type: ProjectType;
+    /** Entry points for each context */
+    entryPoints: Record<string, string>;
+    /** Context type mapping (e.g., background → server, content → client) */
+    contextMapping?: Record<string, string>;
+    /** Project metadata */
+    metadata?: {
+        name?: string;
+        version?: string;
+        description?: string;
+    };
+};
+/**
+ * Complete architecture analysis result
+ */
+export type ArchitectureAnalysis = {
+    /** Project root directory (for relative paths) */
+    projectRoot: string;
+    /** Basic system information */
+    system: {
+        name: string;
+        version: string;
+        description?: string;
+    };
+    /** Project configuration (for non-extension projects) */
+    projectConfig?: ProjectConfig;
+    /** Manifest information (for Chrome extensions) */
+    manifest?: ManifestInfo;
+    /** All contexts found in the system */
+    contexts: Record<string, ContextInfo>;
+    /** Message flows between contexts */
+    messageFlows: MessageFlow[];
+    /** External integrations */
+    integrations: ExternalIntegration[];
+    /** Architecture Decision Records */
+    adrs?: ADRCollection;
+    /** Repository information */
+    repository?: {
+        url: string;
+        type: string;
+    };
+};
+import type { ADRCollection } from "./adr";