@fairfox/polly 0.11.0 → 0.12.1

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

@@ -0,0 +1,28 @@
+import type { ArchitectureAnalysis } from "../../analysis/src/types/architecture.ts";
+export interface TeachingMaterial {
+    analysis: ArchitectureAnalysis;
+    visualization: string;
+    formattedOutput: string;
+}
+export interface TeachOptions {
+    projectRoot: string;
+    tsConfigPath?: string;
+}
+/**
+ * Generate teaching material for a Polly project
+ *
+ * @param options Configuration options
+ * @returns Teaching material including analysis, visualization, and formatted output
+ *
+ * @example
+ * ```typescript
+ * import { generateTeachingMaterial } from '@fairfox/polly/teach'
+ *
+ * const material = await generateTeachingMaterial({
+ *   projectRoot: process.cwd()
+ * })
+ *
+ * console.log(material.formattedOutput)
+ * ```
+ */
+export declare function generateTeachingMaterial(options: TeachOptions): Promise<TeachingMaterial>;

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

@@ -235845,9 +235845,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(`
@@ -235946,6 +235949,8 @@ class ContextAnalyzer {
     if (params.length === 0)
       return [];
     const propsParam = params[0];
+    if (!propsParam)
+      return [];
     const type2 = propsParam.getType();
     const props = [];
     for (const prop of type2.getProperties()) {
@@ -235961,6 +235966,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());
@@ -235968,10 +235975,15 @@ class ContextAnalyzer {
     return props;
   }
   extractJSDocDescription(node) {
+    if (!import_ts_morph.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) {
@@ -236055,7 +236067,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,
@@ -236075,7 +236090,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,
@@ -236145,7 +236163,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,
@@ -236198,10 +236219,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|$)/);
@@ -237001,7 +237029,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 (import_ts_morph4.Node.isBinaryExpression(node)) {
         this.checkBinaryExpressionMutation(node, firstAwaitPos, mutations);
@@ -237052,6 +237083,8 @@ class HandlerExtractor {
       return null;
     }
     const conditionArg = args[0];
+    if (!conditionArg)
+      return null;
     const expression = conditionArg.getText();
     let message;
     if (args.length >= 2 && import_ts_morph4.Node.isStringLiteral(args[1])) {
@@ -237357,12 +237390,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 (!import_ts_morph4.Node.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);
@@ -237701,7 +237739,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;
     }
@@ -237882,10 +237923,15 @@ class IntegrationAnalyzer {
     }
   }
   extractJSDocDescription(node) {
-    const jsDocs = node.getJsDocs?.() || [];
+    if (!import_ts_morph5.Node.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;
   }
 }
@@ -237927,17 +237973,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() {
@@ -238003,25 +238049,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;
@@ -238029,24 +238075,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
       };
     }
@@ -238055,7 +238101,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") {
@@ -238064,15 +238110,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 {
@@ -238207,25 +238254,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(join(this.projectRoot, popup));
@@ -238234,7 +238286,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(join(this.projectRoot, options));
@@ -238289,7 +238342,7 @@ class ProjectDetector {
   detectElectron(packageJson) {
     const entryPoints = {};
     const mainCandidates = [
-      packageJson.main,
+      packageJson["main"],
       "src/main/index.ts",
       "src/electron/main.ts",
       "electron/main.ts",
@@ -238323,9 +238376,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"]
       }
     };
   }
@@ -238384,9 +238437,9 @@ class ProjectDetector {
         client: "Client"
       },
       metadata: {
-        name: packageJson.name,
-        version: packageJson.version,
-        description: packageJson.description
+        name: packageJson["name"],
+        version: packageJson["version"],
+        description: packageJson["description"]
       }
     };
   }
@@ -238795,11 +238848,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
     };
   }
@@ -238901,7 +238963,7 @@ class TypeExtractor {
     if (type2.getAliasSymbol()) {
       return this.extractFromTypeAlias(type2, typeName, sourceFile, warnings);
     }
-    if (type2.isConditionalType?.()) {
+    if (typeof type2.isConditionalType === "function" && type2.isConditionalType()) {
       return this.extractFromConditionalType(type2, warnings);
     }
     if (type2.getText().includes("[K in ")) {
@@ -238966,7 +239028,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) {
@@ -239482,9 +239547,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,
@@ -240015,7 +240083,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++;
@@ -240096,7 +240165,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 = {
@@ -240105,7 +240174,7 @@ class StructurizrDSLGenerator {
       state: "Requests state",
       general: "Interacts"
     };
-    return actions[domain] || actions.general;
+    return actions[domain] || actions["general"] || "Interacts";
   }
   getMessageDescription(messageType) {
     const type2 = messageType.toLowerCase();
@@ -240344,11 +240413,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(`
@@ -240545,11 +240616,12 @@ Your project contains ${contexts2.length} context(s) and ${allHandlers.length} m
 ### Contexts
 
 ${contexts2.map(([name, ctx]) => {
+    const state = ctx.state;
     return `
 **${name}**
 Location: ${ctx.entryPoint}
 Handlers: ${ctx.handlers?.length || 0}
-State variables: ${Object.keys(ctx.state?.variables || {}).length}`;
+State variables: ${Object.keys(state?.variables || {}).length}`;
   }).join(`
 `)}
 
@@ -240566,8 +240638,9 @@ ${allHandlers.length > 0 ? `
 Consider this handler from your codebase:
 
 \`\`\`typescript
-// ${allHandlers[0].file}:${allHandlers[0].location?.line || "?"}
-${allHandlers[0].code || allHandlers[0].name || "Handler code not available"}
+// ${allHandlers[0]?.location?.file}:${allHandlers[0]?.location?.line || "?"}
+// Handler for message: ${allHandlers[0]?.messageType}
+// Node: ${allHandlers[0]?.node}
 \`\`\`
 
 Polly can translate this to TLA+ for formal verification.` : "No handlers detected in your project."}
@@ -240595,4 +240668,4 @@ export {
   generateTeachingMaterial
 };
 
-//# debugId=F2EE93360E450F6364756E2164756E21
+//# debugId=792122C317EE04F564756E2164756E21