@fairfox/polly 0.11.0 → 0.12.1

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

@@ -0,0 +1,178 @@
+export type TypeKind = "boolean" | "string" | "number" | "enum" | "array" | "object" | "map" | "set" | "union" | "null" | "unknown";
+export type TypeInfo = {
+    name: string;
+    kind: TypeKind;
+    nullable: boolean;
+    elementType?: TypeInfo;
+    valueType?: TypeInfo;
+    properties?: Record<string, TypeInfo>;
+    enumValues?: string[];
+    unionTypes?: TypeInfo[];
+};
+/**
+ * A node represents an entity in the system that can send/receive messages.
+ *
+ * Examples:
+ * - Web extension: "background", "content", "popup"
+ * - Actor system: Individual actor instances
+ * - Event bus: Emitters/listeners
+ * - Worker threads: Main thread + worker instances
+ */
+export type NodeDefinition = {
+    /** Unique identifier for this node */
+    id: string;
+    /** Type of node (adapter-specific) */
+    type: string;
+    /** Which nodes can this send messages to? */
+    canSendTo: string[];
+    /** Which nodes can send messages to this? */
+    canReceiveFrom: string[];
+    /** Optional: Additional metadata */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Defines a type of message that flows through the system
+ */
+export type MessageTypeDefinition = {
+    /** Name/identifier of the message type */
+    name: string;
+    /** Schema of the message payload */
+    payload: TypeInfo;
+    /** Routing constraints */
+    routing: {
+        /** Which node types can send this message? */
+        from: string[];
+        /** Which node types can receive this message? */
+        to: string[];
+    };
+    /** Optional: Expected response type */
+    response?: TypeInfo;
+};
+/**
+ * Configuration for a state field
+ */
+export type FieldConfig = {
+    maxLength: number | null;
+} | {
+    min: number | null;
+    max: number | null;
+} | {
+    type: "enum";
+    values: string[];
+} | {
+    values: string[] | null;
+    abstract?: boolean;
+} | {
+    maxSize: number | null;
+    valueType?: unknown;
+} | {
+    abstract: boolean;
+};
+export type StateSchema = Record<string, FieldConfig>;
+/**
+ * Represents an assignment to a state field
+ */
+export type StateAssignment = {
+    /** Field path (e.g., "user.loggedIn") */
+    field: string;
+    /** The assigned value */
+    value: string | boolean | number | null;
+    /** Optional condition guard */
+    conditional?: string;
+};
+/**
+ * A verification condition (precondition or postcondition)
+ */
+export type VerificationCondition = {
+    /** The condition expression as a string */
+    expression: string;
+    /** Optional error message */
+    message?: string;
+    /** Source location */
+    location: {
+        line: number;
+        column: number;
+    };
+};
+/**
+ * Constraint declared at the state level.
+ * These are automatically wired to message handlers by the parser.
+ */
+export type StateConstraint = {
+    /** State field this constraint applies to */
+    field: string;
+    /** Message type this constraint applies to */
+    messageType: string;
+    /** Precondition expression (e.g., "loggedIn === true") */
+    requires?: string;
+    /** Postcondition expression */
+    ensures?: string;
+    /** Optional error message */
+    message?: string;
+    /** Source location */
+    location: {
+        file: string;
+        line: number;
+    };
+};
+/**
+ * Component relationship detected from code analysis
+ */
+export type ComponentRelationship = {
+    /** Source component */
+    from: string;
+    /** Target component */
+    to: string;
+    /** Description of the relationship */
+    description: string;
+    /** Technology/method used */
+    technology?: string;
+    /** Confidence level */
+    confidence: "high" | "medium" | "low";
+    /** Evidence supporting this detection */
+    evidence: string[];
+};
+/**
+ * Represents a message handler extracted from code
+ */
+export type MessageHandler = {
+    /** Which message type does this handle? */
+    messageType: string;
+    /** Which node handles this message? */
+    node: string;
+    /** State assignments made by this handler */
+    assignments: StateAssignment[];
+    /** Preconditions (requires() calls) */
+    preconditions: VerificationCondition[];
+    /** Postconditions (ensures() calls) */
+    postconditions: VerificationCondition[];
+    /** Source location */
+    location: {
+        file: string;
+        line: number;
+    };
+    /** Component relationships detected from this handler's code */
+    relationships?: ComponentRelationship[];
+};
+export type Confidence = "high" | "medium" | "low";
+export type FieldAnalysis = {
+    path: string;
+    type: TypeInfo;
+    confidence: Confidence;
+    evidence: string[];
+    suggestions: string[];
+    bounds?: {
+        min?: number;
+        max?: number;
+        maxLength?: number;
+        maxSize?: number;
+        values?: string[];
+    };
+};
+export type CodebaseAnalysis = {
+    stateType: TypeInfo | null;
+    messageTypes: string[];
+    fields: FieldAnalysis[];
+    handlers: MessageHandler[];
+    stateConstraints: StateConstraint[];
+};

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

@@ -0,0 +1,4 @@
+export * from "./adr";
+export * from "./architecture";
+export * from "./core";
+export type Context = "background" | "content" | "popup" | "devtools" | "options" | "offscreen" | "sidepanel";

package/dist/tools/teach/src/cli.js

@@ -94,25 +94,30 @@ class ProjectDetector {
     };
   }
   detectBackgroundEntry(manifest, entryPoints) {
-    const background = manifest.background;
+    const background = manifest["background"];
     if (!background)
       return;
-    const file = background.service_worker || background.scripts?.[0] || background.page;
+    const file = background["service_worker"] || background["scripts"]?.[0] || background["page"];
     if (file) {
       entryPoints["background"] = this.findSourceFile(file);
     }
   }
   detectContentScriptEntry(manifest, entryPoints) {
-    const contentScripts = manifest.content_scripts;
+    const contentScripts = manifest["content_scripts"];
     if (!contentScripts || contentScripts.length === 0)
       return;
-    const firstScript = contentScripts[0].js?.[0];
+    const firstScriptObj = contentScripts[0];
+    if (!firstScriptObj)
+      return;
+    const firstScript = firstScriptObj["js"]?.[0];
     if (firstScript) {
       entryPoints["content"] = this.findSourceFile(firstScript);
     }
   }
   detectPopupEntry(manifest, entryPoints) {
-    const popup = manifest.action?.default_popup || manifest.browser_action?.default_popup;
+    const action = manifest["action"];
+    const browserAction = manifest["browser_action"];
+    const popup = action?.["default_popup"] || browserAction?.["default_popup"];
     if (!popup)
       return;
     const jsFile = this.findAssociatedJS(path4.join(this.projectRoot, popup));
@@ -121,7 +126,8 @@ class ProjectDetector {
     }
   }
   detectOptionsEntry(manifest, entryPoints) {
-    const options = manifest.options_ui?.page || manifest.options_page;
+    const optionsUi = manifest["options_ui"];
+    const options = optionsUi?.["page"] || manifest["options_page"];
     if (!options)
       return;
     const jsFile = this.findAssociatedJS(path4.join(this.projectRoot, options));
@@ -176,7 +182,7 @@ class ProjectDetector {
   detectElectron(packageJson) {
     const entryPoints = {};
     const mainCandidates = [
-      packageJson.main,
+      packageJson["main"],
       "src/main/index.ts",
       "src/electron/main.ts",
       "electron/main.ts",
@@ -210,9 +216,9 @@ class ProjectDetector {
         renderer: "Renderer Process"
       },
       metadata: {
-        name: packageJson.name,
-        version: packageJson.version,
-        description: packageJson.description
+        name: packageJson["name"],
+        version: packageJson["version"],
+        description: packageJson["description"]
       }
     };
   }
@@ -271,9 +277,9 @@ class ProjectDetector {
         client: "Client"
       },
       metadata: {
-        name: packageJson.name,
-        version: packageJson.version,
-        description: packageJson.description
+        name: packageJson["name"],
+        version: packageJson["version"],
+        description: packageJson["description"]
       }
     };
   }
@@ -4645,9 +4651,12 @@ class ContextAnalyzer {
     const leadingComments = firstStatement.getLeadingCommentRanges();
     if (leadingComments.length === 0)
       return;
-    const comment = leadingComments[0].getText();
+    const firstComment = leadingComments[0];
+    if (!firstComment)
+      return;
+    const comment = firstComment.getText();
     const descMatch = comment.match(/@description\s+(.+?)(?:\n|$)/s);
-    if (descMatch) {
+    if (descMatch?.[1]) {
       return descMatch[1].trim();
     }
     const lines = comment.split(`
@@ -4746,6 +4755,8 @@ class ContextAnalyzer {
     if (params.length === 0)
       return [];
     const propsParam = params[0];
+    if (!propsParam)
+      return [];
     const type = propsParam.getType();
     const props = [];
     for (const prop of type.getProperties()) {
@@ -4761,6 +4772,8 @@ class ContextAnalyzer {
     if (typeArgs.length === 0)
       return [];
     const propsType = typeArgs[0];
+    if (!propsType)
+      return [];
     const props = [];
     for (const prop of propsType.getProperties()) {
       props.push(prop.getName());
@@ -4768,10 +4781,15 @@ class ContextAnalyzer {
     return props;
   }
   extractJSDocDescription(node) {
+    if (!Node.isJSDocable(node))
+      return;
     const jsDocs = node.getJsDocs();
     if (jsDocs.length === 0)
       return;
-    const description = jsDocs[0].getDescription().trim();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return;
+    const description = firstDoc.getDescription().trim();
     return description || undefined;
   }
   isUIContext(contextType) {
@@ -4853,7 +4871,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const msgType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const msgType = this.extractMessageTypeFromArg(firstArg);
     if (msgType === messageType) {
       senders.push({
         context,
@@ -4873,7 +4894,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const msgType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const msgType = this.extractMessageTypeFromArg(firstArg);
     if (msgType === messageType) {
       senders.push({
         context,
@@ -4943,7 +4967,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const messageType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const messageType = this.extractMessageTypeFromArg(firstArg);
     if (messageType) {
       sends.push({
         messageType,
@@ -4996,10 +5023,17 @@ class FlowAnalyzer {
     });
     if (!targetNode)
       return {};
-    const jsDocs = targetNode.getJsDocs?.() || [];
+    const nodeAny = targetNode;
+    if (!("getJsDocs" in nodeAny) || typeof nodeAny.getJsDocs !== "function") {
+      return {};
+    }
+    const jsDocs = nodeAny.getJsDocs();
     if (jsDocs.length === 0)
       return {};
-    const comment = jsDocs[0].getText();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return {};
+    const comment = firstDoc.getText();
     const flowMatch = comment.match(/@flow\s+([^\s]+)/);
     const flowName = flowMatch ? flowMatch[1] : undefined;
     const triggerMatch = comment.match(/@trigger\s+(.+?)(?:\n|$)/);
@@ -5802,7 +5836,10 @@ class HandlerExtractor {
     if (!body) {
       return;
     }
-    const firstAwaitPos = awaitExpressions[0].getStart();
+    const firstAwait = awaitExpressions[0];
+    if (!firstAwait)
+      return;
+    const firstAwaitPos = firstAwait.getStart();
     funcNode.forEachDescendant((node) => {
       if (Node4.isBinaryExpression(node)) {
         this.checkBinaryExpressionMutation(node, firstAwaitPos, mutations);
@@ -5853,6 +5890,8 @@ class HandlerExtractor {
       return null;
     }
     const conditionArg = args[0];
+    if (!conditionArg)
+      return null;
     const expression = conditionArg.getText();
     let message;
     if (args.length >= 2 && Node4.isStringLiteral(args[1])) {
@@ -6158,12 +6197,17 @@ class HandlerExtractor {
     return;
   }
   extractMessageTypeFromTypePredicateFunction(node, returnTypeNode) {
-    const typeNode = returnTypeNode.getTypeNode();
-    if (typeNode) {
-      const typeName = typeNode.getText();
-      const messageType = this.extractMessageTypeFromTypeName(typeName);
-      if (messageType) {
-        return messageType;
+    if (!Node4.isTypePredicate(returnTypeNode)) {
+      return null;
+    }
+    if ("getTypeNode" in returnTypeNode && typeof returnTypeNode.getTypeNode === "function") {
+      const typeNode = returnTypeNode.getTypeNode();
+      if (typeNode) {
+        const typeName = typeNode.getText();
+        const messageType = this.extractMessageTypeFromTypeName(typeName);
+        if (messageType) {
+          return messageType;
+        }
       }
     }
     return this.extractMessageTypeFromFunctionBodyText(node);
@@ -6495,7 +6539,10 @@ class IntegrationAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const url = this.extractURLFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const url = this.extractURLFromArg(firstArg);
     if (!url) {
       return;
     }
@@ -6676,10 +6723,15 @@ class IntegrationAnalyzer {
     }
   }
   extractJSDocDescription(node) {
-    const jsDocs = node.getJsDocs?.() || [];
+    if (!Node5.isJSDocable(node))
+      return;
+    const jsDocs = node.getJsDocs();
     if (jsDocs.length === 0)
       return;
-    const comment = jsDocs[0].getDescription().trim();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return;
+    const comment = firstDoc.getDescription().trim();
     return comment || undefined;
   }
 }
@@ -6718,17 +6770,17 @@ class ManifestParser {
     }
     const manifest = this.manifestData;
     return {
-      name: manifest.name || "Unknown Extension",
-      version: manifest.version || "0.0.0",
-      description: manifest.description,
-      manifestVersion: manifest.manifest_version || 2,
+      name: manifest["name"] || "Unknown Extension",
+      version: manifest["version"] || "0.0.0",
+      description: manifest["description"],
+      manifestVersion: manifest["manifest_version"] || 2,
       background: this.parseBackground(),
       contentScripts: this.parseContentScripts(),
       popup: this.parsePopup(),
       options: this.parseOptions(),
       devtools: this.parseDevtools(),
-      permissions: manifest.permissions || [],
-      hostPermissions: manifest.host_permissions || []
+      permissions: manifest["permissions"] || [],
+      hostPermissions: manifest["host_permissions"] || []
     };
   }
   getContextEntryPoints() {
@@ -6794,25 +6846,25 @@ class ManifestParser {
   parseBackground() {
     if (!this.manifestData)
       return;
-    const bg = this.manifestData.background;
+    const bg = this.manifestData["background"];
     if (!bg)
       return;
-    if (bg.service_worker) {
+    if (bg["service_worker"]) {
       return {
         type: "service_worker",
-        files: [bg.service_worker]
+        files: [bg["service_worker"]]
       };
     }
-    if (bg.scripts) {
+    if (bg["scripts"]) {
       return {
         type: "script",
-        files: bg.scripts
+        files: bg["scripts"]
       };
     }
-    if (bg.page) {
+    if (bg["page"]) {
       return {
         type: "script",
-        files: [bg.page]
+        files: [bg["page"]]
       };
     }
     return;
@@ -6820,24 +6872,24 @@ class ManifestParser {
   parseContentScripts() {
     if (!this.manifestData)
       return;
-    const cs = this.manifestData.content_scripts;
+    const cs = this.manifestData["content_scripts"];
     if (!cs || !Array.isArray(cs))
       return;
     return cs.map((script) => ({
-      matches: script.matches || [],
-      js: script.js || [],
-      css: script.css
+      matches: script["matches"] || [],
+      js: script["js"] || [],
+      css: script["css"]
     }));
   }
   parsePopup() {
     if (!this.manifestData)
       return;
-    const action = this.manifestData.action || this.manifestData.browser_action;
+    const action = this.manifestData["action"] || this.manifestData["browser_action"];
     if (!action)
       return;
-    if (action.default_popup) {
+    if (action["default_popup"]) {
       return {
-        html: action.default_popup,
+        html: action["default_popup"],
         default: true
       };
     }
@@ -6846,7 +6898,7 @@ class ManifestParser {
   parseOptions() {
     if (!this.manifestData)
       return;
-    const options = this.manifestData.options_ui || this.manifestData.options_page;
+    const options = this.manifestData["options_ui"] || this.manifestData["options_page"];
     if (!options)
       return;
     if (typeof options === "string") {
@@ -6855,15 +6907,16 @@ class ManifestParser {
         openInTab: false
       };
     }
+    const optionsObj = options;
     return {
-      page: options.page,
-      openInTab: options.open_in_tab
+      page: optionsObj["page"],
+      openInTab: optionsObj["open_in_tab"]
     };
   }
   parseDevtools() {
     if (!this.manifestData)
       return;
-    const devtools = this.manifestData.devtools_page;
+    const devtools = this.manifestData["devtools_page"];
     if (!devtools)
       return;
     return {
@@ -7060,11 +7113,20 @@ class TypeExtractor {
     const handlerAnalysis = this.extractHandlerAnalysis();
     const validMessageTypes = this.filterAndLogMessageTypes(messageTypes, handlerAnalysis.messageTypes);
     const validHandlers = this.filterAndLogHandlers(handlerAnalysis.handlers);
+    const completeHandlers = validHandlers.map((h) => ({
+      messageType: h.messageType,
+      node: h.node || "unknown",
+      assignments: h.assignments || [],
+      preconditions: h.preconditions || [],
+      postconditions: h.postconditions || [],
+      location: h.location,
+      relationships: h.relationships
+    }));
     return {
       stateType,
       messageTypes: validMessageTypes,
       fields,
-      handlers: validHandlers,
+      handlers: completeHandlers,
       stateConstraints: handlerAnalysis.stateConstraints
     };
   }
@@ -7166,7 +7228,7 @@ class TypeExtractor {
     if (type.getAliasSymbol()) {
       return this.extractFromTypeAlias(type, typeName, sourceFile, warnings);
     }
-    if (type.isConditionalType?.()) {
+    if (typeof type.isConditionalType === "function" && type.isConditionalType()) {
       return this.extractFromConditionalType(type, warnings);
     }
     if (type.getText().includes("[K in ")) {
@@ -7231,7 +7293,10 @@ class TypeExtractor {
     if (parts.length < 2) {
       return messageTypes;
     }
-    const branches = parts[1].split(":");
+    const secondPart = parts[1];
+    if (!secondPart)
+      return messageTypes;
+    const branches = secondPart.split(":");
     for (const branch of branches) {
       const extracted = this.extractStringLiteralFromBranch(branch);
       if (extracted) {
@@ -7693,9 +7758,12 @@ class StructurizrDSLGenerator {
     }
     for (const [messageType, handlers2] of handlersByType) {
       const componentName = this.toComponentName(messageType);
-      const description = this.generateComponentDescription(messageType, handlers2[0]);
-      const tags = this.getComponentTags(messageType, handlers2[0]);
-      const properties = this.getComponentProperties(messageType, handlers2[0], contextType);
+      const firstHandler = handlers2[0];
+      if (!firstHandler)
+        continue;
+      const description = this.generateComponentDescription(messageType, firstHandler);
+      const tags = this.getComponentTags(messageType, firstHandler);
+      const properties = this.getComponentProperties(messageType, firstHandler, contextType);
       componentDefs.push({
         id: this.toId(componentName),
         name: componentName,
@@ -8226,7 +8294,8 @@ class StructurizrDSLGenerator {
     let stepCount = 0;
     for (const { handler, contextName: _contextName } of handlers2) {
       const handlerComponentId = this.toId(`${handler.messageType}_handler`);
-      for (const rel of handler.relationships) {
+      const relationships = handler.relationships || [];
+      for (const rel of relationships) {
         const toComponent = this.toId(rel.to);
         parts.push(`      ${handlerComponentId} -> ${toComponent} "${rel.description}"`);
         stepCount++;
@@ -8307,7 +8376,7 @@ class StructurizrDSLGenerator {
       state: "Application state synchronization",
       general: "Message flow through the system"
     };
-    return descriptions[domain] || descriptions.general;
+    return descriptions[domain] || descriptions["general"] || "Message flow through the system";
   }
   getUserAction(domain) {
     const actions = {
@@ -8316,7 +8385,7 @@ class StructurizrDSLGenerator {
       state: "Requests state",
       general: "Interacts"
     };
-    return actions[domain] || actions.general;
+    return actions[domain] || actions["general"] || "Interacts";
   }
   getMessageDescription(messageType) {
     const type = messageType.toLowerCase();
@@ -8555,11 +8624,13 @@ class StructurizrDSLGenerator {
     }
     if (this.options.perspectives?.[comp.id]) {
       const perspectives = this.options.perspectives[comp.id];
-      parts.push(`${indent}  perspectives {`);
-      for (const perspective of perspectives) {
-        parts.push(`${indent}    "${this.escape(perspective.name)}" "${this.escape(perspective.description)}"`);
+      if (perspectives) {
+        parts.push(`${indent}  perspectives {`);
+        for (const perspective of perspectives) {
+          parts.push(`${indent}    "${this.escape(perspective.name)}" "${this.escape(perspective.description)}"`);
+        }
+        parts.push(`${indent}  }`);
       }
-      parts.push(`${indent}  }`);
     }
     parts.push(`${indent}}`);
     return parts.join(`
@@ -9508,4 +9579,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=CDFF2E3A99C1DA5C64756E2164756E21
+//# debugId=770FFA3847E6590364756E2164756E21