@vizualmodel/vmblu-cli 0.3.1 → 0.3.2

package/commands/init/init-project.js

@@ -160,7 +160,7 @@ async function initProject(opts) {
 
   const absTarget = path.resolve(targetDir);
   const modelFile = path.join(absTarget, `${projectName}.vmblu`);
-  const docFile   = path.join(absTarget, `${projectName}-doc.json`);
+  const docFile   = path.join(absTarget, `${projectName}.prf.json`);
 
   const llmDir     = path.join(absTarget, 'llm');
   const sessionDir = path.join(llmDir, 'session');

package/commands/profile/profile.bundle.js

@@ -2855,23 +2855,23 @@ async getFolderContent(){
 const sourceMapHandling = {
 
 // reads the source doc file and parses it into documentation
-async handleSourceDoc() {
+async handleSourceMap() {
 
     // read the source doc file
-    const rawSourceDoc = await this.readSourceDoc();
+    const rawSourceMap = await this.readSourceMap();
 
     // check
-    if (! rawSourceDoc) return;
+    if (! rawSourceMap) return;
 
     // parse to extract the juicy bits
-    this.sourceMap = this.parseSourceDoc(rawSourceDoc);        
+    this.sourceMap = this.parseSourceMap(rawSourceMap);        
 
     // ok
-    // console.log('** SourceDoc **', this.sourceMap)
+    // console.log('** SourceMap **', this.sourceMap)
 },
 
 // Reads the sourceMap of the model
-async readSourceDoc() {
+async readSourceMap() {
 
     // get the full path
     const fullPath = this.arl?.getFullPath();
@@ -2880,7 +2880,7 @@ async readSourceDoc() {
     if (!fullPath) return null
 
     // make an arl 
-    const sourceMapArl = this.arl.resolve(removeExt(fullPath) + '-doc.json');
+    const sourceMapArl = this.arl.resolve(removeExt(fullPath) + '.prf.json');
 
     // get the file
     return await sourceMapArl.get('json')
@@ -2893,7 +2893,7 @@ async readSourceDoc() {
  * @param {Array<{node: string, handlers: Array}>} docEntries
  * @returns {Map<string, Map<string, object>>} Map of nodeName -> Map of pinName -> handler metadata
  */
-parseSourceDoc(raw) {
+parseSourceMap(raw) {
 
     // check
     if (!raw.entries) return null;
@@ -2944,7 +2944,7 @@ parseSourceDoc(raw) {
 /**
  * Optional helper to flatten the nested map into a plain array (useful for UI).
  */
-flattenSourceDoc(nodeMap) {
+flattenSourceMap(nodeMap) {
     const flatList = [];
     for (const [node, pins] of nodeMap.entries()) {
         for (const [pin, meta] of pins.entries()) {
@@ -3047,7 +3047,7 @@ makeMcpToolString(root) {
  * Generate MCP-compatible tool specs in an LLM-neutral format.
  * Only handlers with `mcp: true` will be included.
  *
- * @param {Map<string, Map<string, object>>} nodeMap - Output from parseSourceDoc
+ * @param {Map<string, Map<string, object>>} nodeMap - Output from parseSourceMap
  * @returns {Array<object>} - Abstract tool specs
  */
 generateToolSpecs() {
@@ -12010,6 +12010,9 @@ changeFactory: {
 
 };
 
+/**
+ * @node editor editor
+ */
 const redoxWidget = {
 
 newPin: {
@@ -22656,136 +22659,144 @@ async getFolderContent(){
 }
 };
 
-// extractHandlersFromFile.js
-
-
-let currentNode = null;
-let topLevelClass = null;
-let nodeMap = null;
-let filePath = null;
-
-function findHandlers(sourceFile, _filePath, _nodeMap) {
-  
-    // Reset any node context carried over from previous files.
-    currentNode = null;
-
-    // The fallback name is the top-level class
-    topLevelClass = sourceFile.getClasses()[0]?.getName?.() || null;
-    nodeMap = _nodeMap;
-    filePath = _filePath;
-
-    // Check all the functions in the sourcefile - typically generator functions
-    sourceFile.getFunctions().forEach(fn => {
-
-        // Capture node annotations on generator-style functions and harvest handlers returned from them.
-        const jsdoc = getFullJsDoc(fn);
-        updateNodeFromJsdoc(jsdoc);
-
-        const name = fn.getName();
-
-        if (isHandler(name)) {
-
-            const line = fn.getNameNode()?.getStartLineNumber() ?? fn.getStartLineNumber();
-            const docTags = getParamDocs(fn);
-            const params = fn.getParameters().flatMap(p => describeParam(p, docTags));
-
-            collect(name, params, line, jsdoc);
-        }
-
-        collectHandlersFromFunctionReturns(fn);
-    });
-
-    // Check the variable declarations in the sourcefile
-    sourceFile.getVariableDeclarations().forEach(decl => {
-
-        // check the name
-        const name = decl.getName();
-        const init = decl.getInitializer();
-        const line = decl.getStartLineNumber();
-        const jsdoc = getFullJsDoc(decl);
-        updateNodeFromJsdoc(jsdoc);
-
-        // check if the name is a handler and initialised with a function
-        if (isHandler(name) && init && init.getKindName().includes('Function')) {
-
-            const docTags = getParamDocs(decl);
-            const params = init.getParameters().flatMap(p => describeParam(p, docTags));
-
-            collect(name, params, line, jsdoc);
-        }
-
+// extractHandlersFromFile.js
+
+
+let currentNode = null;
+let topLevelClass = null;
+let nodeMap = null;
+let filePath = null;
+let nodeAliases = new Map();
+
+let knownIdentifiers = new Set();
+
+function findHandlers(sourceFile, _filePath, _nodeMap) {
+
+    // Reset any node context carried over from previous files.
+    currentNode = null;
+
+    // The fallback name is the top-level class
+    topLevelClass = sourceFile.getClasses()[0]?.getName?.() || null;
+    nodeMap = _nodeMap;
+    filePath = _filePath;
+    nodeAliases = new Map();
+    knownIdentifiers = collectKnownIdentifiers(sourceFile);
+
+    // Check all the functions in the sourcefile - typically generator functions
+    sourceFile.getFunctions().forEach(fn => {
+
+        // Capture node annotations on generator-style functions and harvest handlers returned from them.
+        const jsdoc = getFullJsDoc(fn);
+        updateNodeFromJsdoc(jsdoc);
+
+        const name = fn.getName();
+
+        if (isHandler(name)) {
+
+            const line = fn.getNameNode()?.getStartLineNumber() ?? fn.getStartLineNumber();
+            const docTags = getParamDocs(fn);
+            const params = fn.getParameters().flatMap(p => describeParam(p, docTags));
+
+            collect(name, params, line, jsdoc);
+        }
+
+        collectHandlersFromFunctionReturns(fn);
+    });
+
+    // Check the variable declarations in the sourcefile
+    sourceFile.getVariableDeclarations().forEach(decl => {
+
+        // check the name
+        const name = decl.getName();
+        const init = decl.getInitializer();
+        const line = decl.getStartLineNumber();
+        const declJsdoc = getFullJsDoc(decl);
+        const statement = decl.getFirstAncestorByKind?.(SyntaxKind.VariableStatement);
+        const statementJsdoc = statement ? getFullJsDoc(statement) : null;
+        const jsdoc = hasDocMetadata(declJsdoc) ? declJsdoc : statementJsdoc ?? declJsdoc;
+        updateNodeFromJsdoc(jsdoc);
+
+        // check if the name is a handler and initialised with a function
+        if (isHandler(name) && init && init.getKindName().includes('Function')) {
+
+            const docTags = getParamDocs(decl);
+            const params = init.getParameters().flatMap(p => describeParam(p, docTags));
+
+            collect(name, params, line, jsdoc);
+        }
+
         const objectLiteral = resolveObjectLiteralExpression(init);
         if (objectLiteral) {
             collectObjectLiteralHandlers(objectLiteral);
         }
-    });
-
-    // check all the classes in the file
-    sourceFile.getClasses().forEach(cls => {
-
-        // get the name of the node
-        cls.getName?.() || topLevelClass;
-
-        // check all the methods
-        cls.getMethods().forEach(method => {
-
-            // check the name
-            const name = method.getName();
-            if (!isHandler(name)) return;
-
-            // extract
-            const line = method.getNameNode()?.getStartLineNumber() ?? method.getStartLineNumber();
-            const jsdoc = getFullJsDoc(method);
-            const docTags = getParamDocs(method);
-            const params = method.getParameters().flatMap(p => describeParam(p, docTags));
-
-            // and collect
-            collect(name, params, line, jsdoc);
-        });
-    });
-
-    // check all the statements
-    sourceFile.getStatements().forEach(stmt => {
-
-        // only binary expressions
-        if (!stmt.isKind(ts.SyntaxKind.ExpressionStatement)) return;
-        const expr = stmt.getExpression();
-        if (!expr.isKind(ts.SyntaxKind.BinaryExpression)) return;
-
-        // get the two parts of the statement
-        const left = expr.getLeft().getText();
-        const right = expr.getRight();
-
-        // check for protype
-        if (left.includes('.prototype.') && right.isKind(ts.SyntaxKind.FunctionExpression)) {
-
-            // get the name and check
-            const parts = left.split('.');
-            const name = parts[parts.length - 1];
-            if (!isHandler(name)) return;
-
-            // extract
-            const line = expr.getStartLineNumber();
-            const params = right.getParameters().flatMap(p => describeParam(p));
-            const jsdoc = getFullJsDoc(expr);
-
-            // and save in nodemap
-            collect(name, params, line, jsdoc);
-        }
-
+    });
+
+    // check all the classes in the file
+    sourceFile.getClasses().forEach(cls => {
+
+        // get the name of the node
+        const nodeName = cls.getName?.() || topLevelClass;
+
+        // check all the methods
+        cls.getMethods().forEach(method => {
+
+            // check the name
+            const name = method.getName();
+            if (!isHandler(name)) return;
+
+            // extract
+            const line = method.getNameNode()?.getStartLineNumber() ?? method.getStartLineNumber();
+            const jsdoc = getFullJsDoc(method);
+            const docTags = getParamDocs(method);
+            const params = method.getParameters().flatMap(p => describeParam(p, docTags));
+
+            // and collect
+            collect(name, params, line, jsdoc, nodeName);
+        });
+    });
+
+    // check all the statements
+    sourceFile.getStatements().forEach(stmt => {
+
+        // only binary expressions
+        if (!stmt.isKind(SyntaxKind.ExpressionStatement)) return;
+        const expr = stmt.getExpression();
+        if (!expr.isKind(SyntaxKind.BinaryExpression)) return;
+
+        // get the two parts of the statement
+        const left = expr.getLeft().getText();
+        const right = expr.getRight();
+
+        // check for protype
+        if (left.includes('.prototype.') && right.isKind(SyntaxKind.FunctionExpression)) {
+
+            // get the name and check
+            const parts = left.split('.');
+            const name = parts[parts.length - 1];
+            if (!isHandler(name)) return;
+
+            // extract
+            const line = expr.getStartLineNumber();
+            const params = right.getParameters().flatMap(p => describeParam(p));
+            const jsdoc = getFullJsDoc(expr);
+
+            // and save in nodemap
+            collect(name, params, line, jsdoc);
+        }
+
         const objectLiteral = resolveObjectLiteralExpression(right);
         if (left.endsWith('.prototype') && objectLiteral) {
             collectObjectLiteralHandlers(objectLiteral);
         }
-    });
-}
-
-
-function collectHandlersFromFunctionReturns(fn) {
-
-    // Look for factory-style returns that expose handlers via object literals.
-    fn.getDescendantsOfKind(ts.SyntaxKind.ReturnStatement).forEach(ret => {
-        const expr = ret.getExpression();
+    });
+}
+
+
+function collectHandlersFromFunctionReturns(fn) {
+
+    // Look for factory-style returns that expose handlers via object literals.
+    fn.getDescendantsOfKind(SyntaxKind.ReturnStatement).forEach(ret => {
+        const expr = ret.getExpression();
         const objectLiteral = resolveObjectLiteralExpression(expr);
         if (!objectLiteral) return;
 
@@ -22802,16 +22813,16 @@ function resolveObjectLiteralExpression(expression) {
         return expression;
     }
 
-    if (expression.isKind?.(ts.SyntaxKind.ParenthesizedExpression)) {
+    if (expression.isKind?.(SyntaxKind.ParenthesizedExpression)) {
         return resolveObjectLiteralExpression(expression.getExpression());
     }
 
-    if (expression.isKind?.(ts.SyntaxKind.AsExpression)
-        || expression.isKind?.(ts.SyntaxKind.TypeAssertionExpression)
-        || expression.isKind?.(ts.SyntaxKind.SatisfiesExpression)
-        || expression.isKind?.(ts.SyntaxKind.NonNullExpression)
+    if (expression.isKind?.(SyntaxKind.AsExpression)
+        || expression.isKind?.(SyntaxKind.TypeAssertionExpression)
+        || expression.isKind?.(SyntaxKind.SatisfiesExpression)
+        || expression.isKind?.(SyntaxKind.NonNullExpression)
     ) {
-        return resolveObjectLiteralExpression(expression.getExpression());
+        return resolveObjectLiteralExpression(expression.getExpression?.());
     }
 
     return null;
@@ -22826,227 +22837,385 @@ function collectObjectLiteralHandlers(objectLiteral) {
 
         const propName = prop.getName?.();
         if (!isHandler(propName)) return;
-
-        let params = [];
-        if (prop.getKind() === ts.SyntaxKind.MethodDeclaration) {
-            const docTags = getParamDocs(prop);
-            params = prop.getParameters().flatMap(p => describeParam(p, docTags));
-        } else if (prop.getKind() === ts.SyntaxKind.PropertyAssignment) {
-            const fn = prop.getInitializerIfKind(ts.SyntaxKind.FunctionExpression) || prop.getInitializerIfKind(ts.SyntaxKind.ArrowFunction);
-            if (fn) {
-                const docTags = getParamDocs(fn);
-                params = fn.getParameters().flatMap(p => describeParam(p, docTags));
-            }
-        }
-
-        const jsdoc = getFullJsDoc(prop);
-        const line = prop.getStartLineNumber();
-
-        collect(propName, params, line, jsdoc);
-    });
-}
-
-function updateNodeFromJsdoc(jsdoc = {}) {
-
-    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
-    if (nodeTag) currentNode = nodeTag.trim();
-}
-
-function collect(rawName, params, line, jsdoc = {}) {
-
-    //if (!isHandler(rawName)) return;
-    const cleanHandler = rawName.replace(/^['"]|['"]$/g, '');
-
-    let pin = null;
-    let node = null;
-
-    const pinTag = jsdoc.tags?.find(t => t.tagName === 'pin')?.comment;
-    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
-    const mcpTag = jsdoc.tags?.find(t => t.tagName === 'mcp')?.comment ?? null;
-
-    // if there is a node tag, change the name of the current node
-    if (nodeTag) currentNode = nodeTag.trim();
-
-    // check the pin tag to get a pin name and node name
-    if (pinTag) {
-
-        if (pinTag.includes('@')) {
-            const [p, n] = pinTag.split('@').map(s => s.trim());
-            pin = p;
-            node = n;
-        }
-        else pin = pinTag.trim();
-
-        // Use the current context when the pin tag does not specify a node.
-        if (!node) node = currentNode || topLevelClass || null;
-    }
-
-    // check the pin tag to get a pin name and node name
-    // if (pinTag && pinTag.includes('@')) {
-    //     const [p, n] = pinTag.split('@').map(s => s.trim());
-    //     pin = p;
-    //     node = n;
-    // } 
-    else {
-
-        // no explicit tag - try these...
-        node = currentNode || topLevelClass || null;
-
-        // deduct the pin name from the handler name
-        if (cleanHandler.startsWith('on')) {
-            pin = cleanHandler.slice(2).replace(/([A-Z])/g, ' $1').trim().toLowerCase();
-        } else if (cleanHandler.startsWith('->')) {
-            pin = cleanHandler.slice(2).trim();
-        }
-    }
-
-    // if there is no node we just don't save the data
-    if (!node) return
-
-    // check if we have an entry for the node
-    if (!nodeMap.has(node)) nodeMap.set(node, { handles: [], transmits: [] });
-
-    // The handler data to save
-    const handlerData = {
-        pin,
-        handler: cleanHandler,
-        file: filePath,
-        line,
-        summary: jsdoc.summary || '',
-        returns: jsdoc.returns || '',
-        examples: jsdoc.examples || [],
-        params
-    };
-
-    // extract the data from an mcp tag if present
-    if (mcpTag !== null) {
-        handlerData.mcp = true;
-        if (mcpTag.includes('name:') || mcpTag.includes('description:')) {
-            const nameMatch = /name:\s*\"?([^\"]+)\"?/.exec(mcpTag);
-            const descMatch = /description:\s*\"?([^\"]+)\"?/.exec(mcpTag);
-            if (nameMatch) handlerData.mcpName = nameMatch[1];
-            if (descMatch) handlerData.mcpDescription = descMatch[1];
-        }
-    }
-
-    // and put it in the nodemap
-    nodeMap.get(node).handles.push(handlerData);
-  }
-// determines if a name is the name for a handler
-function isHandler(name) {
-    // must be a string
-    if (typeof name !== 'string') return false;
-
-    // get rid of " and '
-    const clean = name.replace(/^['"]|['"]$/g, '');
-
-    // check that it starts with the right symbols...
-    return clean.startsWith('on') || clean.startsWith('->');
-}
-
-// Get the parameter description from the function or method
-function getParamDocs(fnOrMethod) {
-
-    // extract
-    const docs = fnOrMethod.getJsDocs?.() ?? [];
-    const tags = docs.flatMap(d => d.getTags());
-    const paramDocs = {};
-
-    // check the tags
-    for (const tag of tags) {
-        if (tag.getTagName() === 'param') {
-            const name = tag.getNameNode()?.getText?.() || tag.getName();
-            const desc = tag.getComment() ?? '';
-            const type = tag.getTypeNode?.()?.getText?.() || tag.getTypeExpression()?.getTypeNode()?.getText();
-            paramDocs[name] = { description: desc, type };
-        }
-    }
-    return paramDocs;
-}
-
-// Get the jsdoc 
-function getFullJsDoc(node) {
-
-    const docs = node.getJsDocs?.() ?? [];
-    const summary = docs.map(d => d.getComment()).filter(Boolean).join('\n');
-    const tags = docs.flatMap(d => d.getTags()).map(t => ({
-        tagName: t.getTagName(),
-        comment: t.getComment() || ''
-    }));
-
-    const returns = tags.find(t => t.tagName === 'returns')?.comment || '';
-    const examples = tags.filter(t => t.tagName === 'example').map(t => t.comment);
-
-    return { summary, returns, examples, tags };
-}
-
-// make a parameter description
-function describeParam(p, docTags = {}) {
-
-    const nameNode = p.getNameNode();
-
-// const func = p.getParent();
-// const funcName = func.getName?.() || '<anonymous>';
-// console.log(funcName)
-
-    if (nameNode.getKindName() === 'ObjectBindingPattern') {
-
-        const objType = p.getType();
-        const properties = objType.getProperties();
-        const isTSFallback = objType.getText() === 'any' || objType.getText() === 'string' || properties.length === 0;
-
-        return nameNode.getElements().map(el => {
-
-            const subName = el.getName();
-            const doc = docTags[subName] ?? {};
-            let tsType = null;
-
-            if (!isTSFallback) {
-                const symbol = objType.getProperty(subName);
-                if (symbol) {
-                    const resolvedType = symbol.getTypeAtLocation(el);
-                    const text = resolvedType.getText();
-                    if (text && text !== 'any') {
-                        tsType = text;
-                    }
-                }
-            }
-
-            const type = tsType || doc.type || 'string';
-            const description = doc.description || '';
-            return { name: subName, type, description };
-        });
-    }
-
-    const name = p.getName();
-    const doc = docTags[name] ?? {};
-    const tsType = p.getType().getText();
-
-    // const isTSFallback = tsType === 'any' || tsType === 'string';
-    // if (isTSFallback && !doc.type) {
-    //   console.warn(`⚠️ No type info for param "${name}" in function "${funcName}"`);
-    // }
-
-    return {
-        name,
-        type: doc.type || tsType || 'string',
-        description: doc.description || '',
-    };
+
+        let params = [];
+        if (prop.getKind() === SyntaxKind.MethodDeclaration) {
+            const docTags = getParamDocs(prop);
+            params = prop.getParameters().flatMap(p => describeParam(p, docTags));
+        } else if (prop.getKind() === SyntaxKind.PropertyAssignment) {
+            const fn = prop.getInitializerIfKind(SyntaxKind.FunctionExpression) || prop.getInitializerIfKind(SyntaxKind.ArrowFunction);
+            if (fn) {
+                const docTags = getParamDocs(fn);
+                params = fn.getParameters().flatMap(p => describeParam(p, docTags));
+            }
+        }
+
+        const jsdoc = getFullJsDoc(prop);
+        const line = prop.getStartLineNumber();
+
+        collect(propName, params, line, jsdoc);
+    });
 }
 
-/**
- * Finds tx.send or this.tx.send calls and maps them to their node context.
- * 
- * @param {import('ts-morph').SourceFile} sourceFile - The source file being analyzed
+function updateNodeFromJsdoc(jsdoc = {}) {
+
+    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
+    if (nodeTag) {
+        applyNodeTag(nodeTag);
+    }
+}
+
+function collect(rawName, params, line, jsdoc = {}, defaultNode = null) {
+
+    const cleanHandler = rawName.replace(/^['"]|['"]$/g, '');
+
+    let pin = null;
+    let node = defaultNode || null;
+
+    const pinTag = jsdoc.tags?.find(t => t.tagName === 'pin')?.comment;
+    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
+    const mcpTag = jsdoc.tags?.find(t => t.tagName === 'mcp')?.comment ?? null;
+
+    if (nodeTag) {
+        const context = applyNodeTag(nodeTag);
+        if (context?.nodeName) {
+            node = context.nodeName;
+        }
+    }
+
+    if (pinTag) {
+
+        if (pinTag.includes('@')) {
+            const [p, n] = pinTag.split('@').map(s => s.trim());
+            pin = p;
+            node = n;
+        }
+        else pin = pinTag.trim();
+    }
+    else if (!node) {
+
+        // no explicit tag - try these...
+        node = currentNode || topLevelClass || null;
+
+        // deduct the pin name from the handler name
+        if (cleanHandler.startsWith('on')) {
+            pin = cleanHandler.slice(2).replace(/([A-Z])/g, ' $1').trim().toLowerCase();
+        } else if (cleanHandler.startsWith('->')) {
+            pin = cleanHandler.slice(2).trim();
+        }
+    }
+
+    // if there is no node we just don't save the data
+    if (!node) return;
+
+    // check if we have an entry for the node
+    if (!nodeMap.has(node)) nodeMap.set(node, { handles: [], transmits: [] });
+
+    // The handler data to save
+    const handlerData = {
+        pin,
+        handler: cleanHandler,
+        file: filePath,
+        line,
+        summary: jsdoc.summary || '',
+        returns: jsdoc.returns || '',
+        examples: jsdoc.examples || [],
+        params
+    };
+
+    // extract the data from an mcp tag if present
+    if (mcpTag !== null) {
+        handlerData.mcp = true;
+        if (mcpTag.includes('name:') || mcpTag.includes('description:')) {
+            const nameMatch = /name:\s*\"?([^\"]+)\"?/.exec(mcpTag);
+            const descMatch = /description:\s*\"?([^\"]+)\"?/.exec(mcpTag);
+            if (nameMatch) handlerData.mcpName = nameMatch[1];
+            if (descMatch) handlerData.mcpDescription = descMatch[1];
+        }
+    }
+
+    // and put it in the nodemap
+    nodeMap.get(node).handles.push(handlerData);
+}
+
+// determines if a name is the name for a handler
+function isHandler(name) {
+    if (typeof name !== 'string') return false;
+
+    const clean = name.replace(/^['"]|['"]$/g, '');
+    return clean.startsWith('on') || clean.startsWith('->');
+}
+
+// Get the parameter description from the function or method
+function getParamDocs(fnOrMethod) {
+
+    const docs = fnOrMethod.getJsDocs?.() ?? [];
+    const tags = docs.flatMap(d => d.getTags());
+    const paramDocs = {};
+
+    for (const tag of tags) {
+        if (tag.getTagName() === 'param') {
+            const name = tag.getNameNode()?.getText?.() || tag.getName();
+            const desc = tag.getComment() ?? '';
+            const type = tag.getTypeNode?.()?.getText?.() || tag.getTypeExpression()?.getTypeNode()?.getText();
+            paramDocs[name] = { description: desc, type };
+        }
+    }
+    return paramDocs;
+}
+
+// Get the jsdoc 
+function getFullJsDoc(node) {
+
+    const docs = node.getJsDocs?.() ?? [];
+    const summary = docs.map(d => d.getComment()).filter(Boolean).join('\n');
+    const tags = docs.flatMap(d => d.getTags()).map(t => ({
+        tagName: t.getTagName(),
+        comment: t.getComment() || ''
+    }));
+
+    const returns = tags.find(t => t.tagName === 'returns')?.comment || '';
+    const examples = tags.filter(t => t.tagName === 'example').map(t => t.comment);
+
+    return { summary, returns, examples, tags };
+}
+
+function hasDocMetadata(jsdoc) {
+    if (!jsdoc) return false;
+    if (jsdoc.summary && jsdoc.summary.trim()) return true;
+    return Array.isArray(jsdoc.tags) && jsdoc.tags.length > 0;
+}
+
+// make a parameter description
+function describeParam(p, docTags = {}) {
+
+    const nameNode = p.getNameNode();
+
+    if (nameNode.getKindName() === 'ObjectBindingPattern') {
+
+        const objType = p.getType();
+        const properties = objType.getProperties();
+        const isTSFallback = objType.getText() === 'any' || objType.getText() === 'string' || properties.length === 0;
+
+        return nameNode.getElements().map(el => {
+
+            const subName = el.getName();
+            const doc = docTags[subName] ?? {};
+            let tsType = null;
+
+            if (!isTSFallback) {
+                const symbol = objType.getProperty(subName);
+                if (symbol) {
+                    const resolvedType = symbol.getTypeAtLocation(el);
+                    const text = resolvedType.getText();
+                    if (text && text !== 'any') {
+                        tsType = text;
+                    }
+                }
+            }
+
+            const type = tsType || doc.type || 'string';
+            const description = doc.description || '';
+            return { name: subName, type, description };
+        });
+    }
+
+    const name = p.getName();
+    const doc = docTags[name] ?? {};
+    const tsType = p.getType().getText();
+
+    return {
+        name,
+        type: doc.type || tsType || 'string',
+        description: doc.description || '',
+    };
+}
+
+function applyNodeTag(rawTag) {
+    const { nodeName, aliases } = parseNodeTag(rawTag);
+    if (!nodeName) return null;
+    registerNodeContext(nodeName, aliases);
+    return { nodeName, aliases };
+}
+
+function registerNodeContext(nodeName, aliases = []) {
+    const normalizedNode = nodeName.trim();
+    if (!normalizedNode) return;
+    currentNode = normalizedNode;
+
+    aliases.forEach(alias => registerAlias(alias, normalizedNode));
+
+    const derivedAlias = deriveIdentifierFromNodeName(normalizedNode);
+    if (derivedAlias) registerAlias(derivedAlias, normalizedNode);
+}
+
+function registerAlias(alias, nodeName) {
+    const cleaned = alias?.trim();
+    if (!cleaned) return;
+    if (!isValidIdentifier(cleaned)) return;
+    if (!nodeAliases.has(cleaned)) {
+        nodeAliases.set(cleaned, nodeName);
+    }
+}
+
+function parseNodeTag(rawTag) {
+    if (!rawTag || typeof rawTag !== 'string') return { nodeName: null, aliases: [] };
+
+    let text = rawTag.trim();
+    if (!text) return { nodeName: null, aliases: [] };
+
+    let nodeName = text;
+    let aliasChunk = '';
+
+    const explicitMatch = text.match(/^(.*?)(?:\s+(?:@|as|=>|->|\||:)\s+)(.+)$/i);
+    if (explicitMatch) {
+        nodeName = explicitMatch[1].trim();
+        aliasChunk = explicitMatch[2].trim();
+    } else {
+        const quotedMatch = text.match(/^["']([^"']+)["']\s+(.+)$/);
+        if (quotedMatch) {
+            nodeName = quotedMatch[1].trim();
+            aliasChunk = quotedMatch[2].trim();
+        }
+    }
+
+    if (!aliasChunk) {
+        const parts = text.split(/\s+/);
+        if (parts.length > 1) {
+            const candidateAlias = parts[parts.length - 1];
+            const candidateNode = parts.slice(0, -1).join(' ');
+            if (isValidIdentifier(candidateAlias) && isKnownIdentifier(candidateAlias)) {
+                aliasChunk = candidateAlias;
+                nodeName = candidateNode.trim();
+            }
+        }
+    }
+
+    const aliases = aliasChunk
+        ? aliasChunk.split(/[,\s]+/).map(a => a.trim()).filter(Boolean)
+        : [];
+
+    return { nodeName, aliases };
+}
+
+function deriveIdentifierFromNodeName(name) {
+    const chunks = name.split(/[\s\-]+/).filter(Boolean);
+    if (chunks.length === 0) return null;
+    if (chunks.length === 1) {
+        const single = chunks[0];
+        return isValidIdentifier(single) ? single : null;
+    }
+    const [first, ...rest] = chunks;
+    const camel = first.toLowerCase() + rest.map(capitalize).join('');
+    return isValidIdentifier(camel) ? camel : null;
+}
+
+function capitalize(word) {
+    if (!word) return '';
+    return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function isValidIdentifier(value) {
+    return /^[A-Za-z_$][\w$]*$/.test(value);
+}
+
+function isKnownIdentifier(name) {
+    return knownIdentifiers.has(name);
+}
+
+function collectKnownIdentifiers(sourceFile) {
+    const identifiers = new Set();
+
+    sourceFile.getVariableDeclarations().forEach(decl => {
+        const name = decl.getName();
+        if (typeof name === 'string' && isValidIdentifier(name)) {
+            identifiers.add(name);
+        }
+    });
+
+    sourceFile.getFunctions().forEach(fn => {
+        const name = fn.getName?.();
+        if (name && isValidIdentifier(name)) identifiers.add(name);
+    });
+
+    sourceFile.getClasses().forEach(cls => {
+        const name = cls.getName?.();
+        if (name && isValidIdentifier(name)) identifiers.add(name);
+    });
+
+    if (typeof sourceFile.getInterfaces === 'function') {
+        sourceFile.getInterfaces().forEach(iface => {
+            const name = iface.getName?.();
+            if (name && isValidIdentifier(name)) identifiers.add(name);
+        });
+    }
+
+    if (typeof sourceFile.getTypeAliases === 'function') {
+        sourceFile.getTypeAliases().forEach(alias => {
+            const name = alias.getName?.();
+            if (name && isValidIdentifier(name)) identifiers.add(name);
+        });
+    }
+
+    if (typeof sourceFile.getEnums === 'function') {
+        sourceFile.getEnums().forEach(enm => {
+            const name = enm.getName?.();
+            if (name && isValidIdentifier(name)) identifiers.add(name);
+        });
+    }
+
+    sourceFile.getImportDeclarations().forEach(decl => {
+        const defaultImport = decl.getDefaultImport();
+        if (defaultImport) {
+            const name = defaultImport.getText();
+            if (isValidIdentifier(name)) identifiers.add(name);
+        }
+
+        const namespaceImport = decl.getNamespaceImport();
+        if (namespaceImport) {
+            const nsName = typeof namespaceImport.getText === 'function'
+                ? namespaceImport.getText()
+                : namespaceImport.getName?.();
+            if (nsName && isValidIdentifier(nsName)) identifiers.add(nsName);
+        }
+
+        decl.getNamedImports().forEach(spec => {
+            const alias = spec.getAliasNode()?.getText();
+            if (alias && isValidIdentifier(alias)) {
+                identifiers.add(alias);
+            } else {
+                const name = spec.getName();
+                if (isValidIdentifier(name)) identifiers.add(name);
+            }
+        });
+    });
+
+    return identifiers;
+}
+
+/**
+ * Finds tx.send or this.tx.send calls and maps them to their node context.
+ * 
+ * @param {import('ts-morph').SourceFile} sourceFile - The source file being analyzed
  * @param {string} filePath - The (relative) path of the source file
  * @param {Map} nodeMap - Map from node name to metadata
  * @param {string|null} currentNode - Explicitly set node name (takes priority)
  */
-function findTransmissions(sourceFile, filePath, nodeMap) {
-
-    // Search all call expressions
-    sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).forEach(node => {
-        const expr = node.getExpression();
+function findTransmissions(sourceFile, filePath, nodeMap) {
+
+    // Create a quick lookup from handler name + file to node name to attribute transmissions precisely.
+    const handlerToNode = new Map();
+    for (const [nodeName, meta] of nodeMap.entries()) {
+        for (const handle of meta.handles) {
+            if (!handle?.handler) continue;
+            const key = createHandlerKey(handle.file ?? filePath, handle.handler);
+            if (!handlerToNode.has(key)) handlerToNode.set(key, nodeName);
+        }
+    }
+
+    // Search all call expressions
+    sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).forEach(node => {
+        const expr = node.getExpression();
 
         // check
         if (expr.getKind() !== SyntaxKind.PropertyAccessExpression) return
@@ -23063,15 +23232,24 @@ function findTransmissions(sourceFile, filePath, nodeMap) {
         const pin = args[0].getLiteralText();
 
         // Try to infer the class context of the tx.send call
-        const method = node.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);
-        const classDecl = method?.getFirstAncestorByKind(SyntaxKind.ClassDeclaration) ?? node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
-        const className = classDecl?.getName?.();
-
-        // Priority order: currentNode > className > topLevelClass > 'global'
-        const nodeName = currentNode || className || topLevelClass || null;
-
-        // check
-        if (!nodeName) return
+        const method = node.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);
+        const classDecl = method?.getFirstAncestorByKind(SyntaxKind.ClassDeclaration) ?? node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+        const className = classDecl?.getName?.();
+        const handlerName = getEnclosingHandlerName(node);
+        const handlerKey = handlerName ? createHandlerKey(filePath, handlerName) : null;
+        const aliasCandidate = getAliasCandidate(expr);
+        const aliasNode = aliasCandidate ? nodeAliases.get(aliasCandidate) ?? null : null;
+
+        // Priority order: handler lookup > alias mapping > current context > class fallback
+        const nodeName = (handlerKey ? handlerToNode.get(handlerKey) : null)
+            || aliasNode
+            || currentNode
+            || className
+            || topLevelClass
+            || null;
+
+        // check
+        if (!nodeName) return
 
         // check if there is an entry for the node or create it 
         nodeMap.has(nodeName) || nodeMap.set(nodeName, { handles: [], transmits: [] });
@@ -23082,7 +23260,70 @@ function findTransmissions(sourceFile, filePath, nodeMap) {
             file: filePath,
             line: node.getStartLineNumber()
         });
-    });
+    });
+}
+
+function getAliasCandidate(propertyAccess) {
+    if (!propertyAccess || !propertyAccess.getExpression) return null;
+    const target = propertyAccess.getExpression();
+    const root = resolveRootIdentifier(target);
+    if (!root) return null;
+    if (root === 'tx' || root === 'this') return null;
+    return root;
+}
+
+function resolveRootIdentifier(expression) {
+    if (!expression) return null;
+    if (expression.isKind?.(SyntaxKind.Identifier)) {
+        return expression.getText();
+    }
+    if (expression.isKind?.(SyntaxKind.ThisKeyword)) {
+        return 'this';
+    }
+    if (expression.isKind?.(SyntaxKind.PropertyAccessExpression)) {
+        return resolveRootIdentifier(expression.getExpression());
+    }
+    if (expression.isKind?.(SyntaxKind.ElementAccessExpression)) {
+        return resolveRootIdentifier(expression.getExpression());
+    }
+    return null;
+}
+
+function createHandlerKey(file, handler) {
+    return `${file}::${handler}`;
+}
+
+function getEnclosingHandlerName(callExpression) {
+    const method = callExpression.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);
+    if (method?.getName?.()) return method.getName();
+
+    const funcDecl = callExpression.getFirstAncestorByKind(SyntaxKind.FunctionDeclaration);
+    if (funcDecl?.getName?.()) return funcDecl.getName();
+
+    const funcExpr = callExpression.getFirstAncestorByKind(SyntaxKind.FunctionExpression);
+    if (funcExpr) {
+        if (funcExpr.getName?.()) return funcExpr.getName();
+        const prop = funcExpr.getFirstAncestorByKind(SyntaxKind.PropertyAssignment);
+        if (prop?.getName?.()) return prop.getName();
+        const variable = funcExpr.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+        if (variable) return variable.getName();
+    }
+
+    const arrowFunc = callExpression.getFirstAncestorByKind(SyntaxKind.ArrowFunction);
+    if (arrowFunc) {
+        const prop = arrowFunc.getFirstAncestorByKind(SyntaxKind.PropertyAssignment);
+        if (prop?.getName?.()) return prop.getName();
+        const variable = arrowFunc.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+        if (variable) return variable.getName();
+    }
+
+    const propAssignment = callExpression.getFirstAncestorByKind(SyntaxKind.PropertyAssignment);
+    if (propAssignment?.getName?.()) return propAssignment.getName();
+
+    const varDecl = callExpression.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+    if (varDecl?.getName?.()) return varDecl.getName();
+
+    return null;
 }
 
 const SRC_DOC_VERSION = '0.2';
@@ -23109,7 +23350,7 @@ async function profile(argv = process.argv.slice(2)) {
         ? path.resolve(cli.outFile)
         : (() => {
             const { dir, name } = path.parse(absoluteModelPath);
-            return path.join(dir, `${name}-doc.json`);
+            return path.join(dir, `${name}.prf.json`);
         })();
 
     if (cli.deltaFile) cli.deltaFile = path.resolve(cli.deltaFile);
@@ -23145,6 +23386,9 @@ async function profile(argv = process.argv.slice(2)) {
     const generatedAt = new Date().toISOString();
     for (const sourceFile of sourceFiles) {
 
+        // display file scanned..
+        // console.log(sourceFile.getFilePath())
+
         // A file reference is always relative to the model file
         const filePath = path.relative(path.dirname(modelPath), sourceFile.getFilePath()).replace(/\\/g, '/');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizualmodel/vmblu-cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "bin": {
     "vmblu": "bin/vmblu.js"
@@ -24,6 +24,6 @@
   "scripts": {
     "vmblu": "vmblu",
     "local": "node ./bin/vmblu.js profile ../browser/vmblu.vmblu",
-    "build:profile": "rollup -c ./commands/profile/rollup.config.js"
+    "build": "rollup -c ./commands/profile/rollup.config.js"
   }
 }