@aiready/core 0.24.3 → 0.24.5

package/dist/chunk-XQSEJ7WN.mjs

@@ -0,0 +1,547 @@
+import {
+  BaseLanguageParser
+} from "./chunk-2N7ISIKE.mjs";
+
+// src/parsers/metadata-utils.ts
+function analyzeNodeMetadata(node, code, options) {
+  const metadata = {
+    isPure: true,
+    hasSideEffects: false
+  };
+  try {
+    let prev = node.previousSibling || null;
+    while (prev && /comment/i.test(prev.type)) {
+      const text = prev.text || "";
+      const loc = {
+        start: {
+          line: prev.startPosition.row + 1,
+          column: prev.startPosition.column
+        },
+        end: {
+          line: prev.endPosition.row + 1,
+          column: prev.endPosition.column
+        }
+      };
+      if (text.trim().startsWith("/**") || text.trim().startsWith("/*")) {
+        metadata.documentation = {
+          content: text.replace(/^[/*]+|[/*]+$/g, "").trim(),
+          type: "comment",
+          loc
+        };
+        break;
+      }
+      if (text.trim().startsWith("///")) {
+        metadata.documentation = {
+          content: text.replace(/^\/\/\//, "").trim(),
+          type: "xml-doc",
+          loc
+        };
+        break;
+      }
+      if (text.trim().startsWith("//")) {
+        metadata.documentation = {
+          content: text.replace(/^\/\//, "").trim(),
+          type: "comment",
+          loc
+        };
+        break;
+      }
+      prev = prev.previousSibling;
+    }
+    if (node.type === "function_definition" || node.type === "class_definition") {
+      const body2 = node.childForFieldName ? node.childForFieldName("body") : node.children.find((c) => c.type === "block");
+      if (body2 && body2.children.length > 0) {
+        const firstStmt = body2.children[0];
+        if (firstStmt.type === "expression_statement" && firstStmt.firstChild?.type === "string") {
+          metadata.documentation = {
+            content: firstStmt.firstChild.text.replace(/['"`]/g, "").trim(),
+            type: "docstring",
+            loc: {
+              start: {
+                line: firstStmt.startPosition.row + 1,
+                column: firstStmt.startPosition.column
+              },
+              end: {
+                line: firstStmt.endPosition.row + 1,
+                column: firstStmt.endPosition.column
+              }
+            }
+          };
+        }
+      }
+    }
+  } catch {
+  }
+  const defaultSignatures = [
+    "console.",
+    "fmt.",
+    "panic(",
+    "os.Exit",
+    "log.",
+    "Console.Write",
+    "File.Write",
+    "System.out",
+    "System.err",
+    "Files.write",
+    "process.exit",
+    "exit("
+  ];
+  const signatures = Array.from(
+    /* @__PURE__ */ new Set([...options?.sideEffectSignatures || [], ...defaultSignatures])
+  );
+  const walk = (n) => {
+    try {
+      const t = n.type || "";
+      if (/assign|assignment|assignment_statement|assignment_expression|throw|throw_statement|send_statement|global_statement|nonlocal_statement/i.test(
+        t
+      )) {
+        metadata.isPure = false;
+        metadata.hasSideEffects = true;
+      }
+      const text = n.text || "";
+      for (const s of signatures) {
+        if (text.includes(s)) {
+          metadata.isPure = false;
+          metadata.hasSideEffects = true;
+          break;
+        }
+      }
+      for (let i = 0; i < n.childCount; i++) {
+        const c = n.child(i);
+        if (c) walk(c);
+      }
+    } catch {
+    }
+  };
+  const body = node.childForFieldName?.("body") || node.children.find(
+    (c) => /body|block|class_body|declaration_list|function_body/.test(c.type)
+  );
+  if (body) walk(body);
+  return metadata;
+}
+
+// src/parsers/python-parser.ts
+var PYTHON_CONSTANTS = {
+  NODES: {
+    IMPORT_STATEMENT: "import_statement",
+    IMPORT_FROM_STATEMENT: "import_from_statement",
+    DOTTED_NAME: "dotted_name",
+    ALIASED_IMPORT: "aliased_import",
+    WILDCARD_IMPORT: "wildcard_import",
+    FUNCTION_DEFINITION: "function_definition",
+    CLASS_DEFINITION: "class_definition",
+    EXPRESSION_STATEMENT: "expression_statement",
+    ASSIGNMENT: "assignment",
+    IDENTIFIER: "identifier",
+    TYPED_PARAMETER: "typed_parameter",
+    DEFAULT_PARAMETER: "default_parameter"
+  },
+  FIELDS: {
+    NAME: "name",
+    MODULE_NAME: "module_name",
+    LEFT: "left",
+    PARAMETERS: "parameters"
+  },
+  SPECIAL: {
+    WILDCARD: "*",
+    DUNDER_ALL: "__all__",
+    DUNDER_VERSION: "__version__",
+    DUNDER_AUTHOR: "__author__",
+    DUNDER_INIT: "__init__",
+    DUNDER_STR: "__str__",
+    DUNDER_REPR: "__repr__",
+    DUNDER_NAME: "__name__",
+    DUNDER_MAIN: "__main__",
+    DUNDER_FILE: "__file__",
+    DUNDER_DOC: "__doc__",
+    DUNDER_DICT: "__dict__",
+    DUNDER_CLASS: "__class__",
+    DUNDER_MODULE: "__module__",
+    DUNDER_BASES: "__bases__",
+    MAIN_VAL: "__main__"
+  },
+  BUILTINS: {
+    PRINT: "print(",
+    INPUT: "input(",
+    OPEN: "open("
+  },
+  TYPES: {
+    FUNCTION: "function",
+    CLASS: "class",
+    VARIABLE: "variable",
+    CONST: "const",
+    DOCSTRING: "docstring"
+  }
+};
+var PythonParser = class extends BaseLanguageParser {
+  constructor() {
+    super(...arguments);
+    this.language = "python" /* Python */;
+    this.extensions = [".py"];
+  }
+  getParserName() {
+    return "python";
+  }
+  /**
+   * Analyze metadata for a Python node (purity, side effects).
+   */
+  analyzeMetadata(node, code) {
+    return analyzeNodeMetadata(node, code, {
+      sideEffectSignatures: [
+        PYTHON_CONSTANTS.BUILTINS.PRINT,
+        PYTHON_CONSTANTS.BUILTINS.INPUT,
+        PYTHON_CONSTANTS.BUILTINS.OPEN
+      ]
+    });
+  }
+  /**
+   * Extract import information using AST walk.
+   */
+  extractImportsAST(rootNode) {
+    const imports = [];
+    const processImportNode = (node) => {
+      if (node.type === PYTHON_CONSTANTS.NODES.IMPORT_STATEMENT) {
+        for (const child of node.children) {
+          if (child.type === PYTHON_CONSTANTS.NODES.DOTTED_NAME) {
+            const source = child.text;
+            imports.push({
+              source,
+              specifiers: [source],
+              loc: {
+                start: {
+                  line: child.startPosition.row + 1,
+                  column: child.startPosition.column
+                },
+                end: {
+                  line: child.endPosition.row + 1,
+                  column: child.endPosition.column
+                }
+              }
+            });
+          } else if (child.type === PYTHON_CONSTANTS.NODES.ALIASED_IMPORT) {
+            const nameNode = child.childForFieldName(
+              PYTHON_CONSTANTS.FIELDS.NAME
+            );
+            if (nameNode) {
+              const source = nameNode.text;
+              imports.push({
+                source,
+                specifiers: [source],
+                loc: {
+                  start: {
+                    line: child.startPosition.row + 1,
+                    column: child.startPosition.column
+                  },
+                  end: {
+                    line: child.endPosition.row + 1,
+                    column: child.endPosition.column
+                  }
+                }
+              });
+            }
+          }
+        }
+      } else if (node.type === PYTHON_CONSTANTS.NODES.IMPORT_FROM_STATEMENT) {
+        const moduleNameNode = node.childForFieldName(
+          PYTHON_CONSTANTS.FIELDS.MODULE_NAME
+        );
+        if (moduleNameNode) {
+          const source = moduleNameNode.text;
+          const specifiers = [];
+          for (const child of node.children) {
+            if (child.type === PYTHON_CONSTANTS.NODES.DOTTED_NAME && child !== moduleNameNode) {
+              specifiers.push(child.text);
+            } else if (child.type === PYTHON_CONSTANTS.NODES.ALIASED_IMPORT) {
+              const nameNode = child.childForFieldName(
+                PYTHON_CONSTANTS.FIELDS.NAME
+              );
+              if (nameNode) specifiers.push(nameNode.text);
+            } else if (child.type === PYTHON_CONSTANTS.NODES.WILDCARD_IMPORT) {
+              specifiers.push(PYTHON_CONSTANTS.SPECIAL.WILDCARD);
+            }
+          }
+          if (specifiers.length > 0) {
+            imports.push({
+              source,
+              specifiers,
+              loc: {
+                start: {
+                  line: node.startPosition.row + 1,
+                  column: node.startPosition.column
+                },
+                end: {
+                  line: node.endPosition.row + 1,
+                  column: node.endPosition.column
+                }
+              }
+            });
+          }
+        }
+      }
+    };
+    for (const node of rootNode.children) {
+      processImportNode(node);
+    }
+    return imports;
+  }
+  /**
+   * Extract export information using AST walk.
+   */
+  extractExportsAST(rootNode, code) {
+    const exports = [];
+    for (const node of rootNode.children) {
+      if (node.type === PYTHON_CONSTANTS.NODES.FUNCTION_DEFINITION) {
+        const nameNode = node.childForFieldName(PYTHON_CONSTANTS.FIELDS.NAME);
+        if (nameNode) {
+          const name = nameNode.text;
+          const isPrivate = name.startsWith("_") && !name.startsWith("__");
+          if (!isPrivate) {
+            const metadata = this.analyzeMetadata(node, code);
+            exports.push({
+              name,
+              type: PYTHON_CONSTANTS.TYPES.FUNCTION,
+              loc: {
+                start: {
+                  line: node.startPosition.row + 1,
+                  column: node.startPosition.column
+                },
+                end: {
+                  line: node.endPosition.row + 1,
+                  column: node.endPosition.column
+                }
+              },
+              parameters: this.extractParameters(node),
+              ...metadata
+            });
+          }
+        }
+      } else if (node.type === PYTHON_CONSTANTS.NODES.CLASS_DEFINITION) {
+        const nameNode = node.childForFieldName(PYTHON_CONSTANTS.FIELDS.NAME);
+        if (nameNode) {
+          const metadata = this.analyzeMetadata(node, code);
+          exports.push({
+            name: nameNode.text,
+            type: PYTHON_CONSTANTS.TYPES.CLASS,
+            loc: {
+              start: {
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column
+              },
+              end: {
+                line: node.endPosition.row + 1,
+                column: node.endPosition.column
+              }
+            },
+            ...metadata
+          });
+        }
+      } else if (node.type === PYTHON_CONSTANTS.NODES.EXPRESSION_STATEMENT) {
+        const assignment = node.firstChild;
+        if (assignment && assignment.type === PYTHON_CONSTANTS.NODES.ASSIGNMENT) {
+          const left = assignment.childForFieldName(
+            PYTHON_CONSTANTS.FIELDS.LEFT
+          );
+          if (left && left.type === PYTHON_CONSTANTS.NODES.IDENTIFIER) {
+            const name = left.text;
+            const isInternal = name === PYTHON_CONSTANTS.SPECIAL.DUNDER_ALL || name === PYTHON_CONSTANTS.SPECIAL.DUNDER_VERSION || name === PYTHON_CONSTANTS.SPECIAL.DUNDER_AUTHOR;
+            const isPrivate = name.startsWith("_") && !name.startsWith("__");
+            if (!isInternal && !isPrivate) {
+              exports.push({
+                name,
+                type: name === name.toUpperCase() ? PYTHON_CONSTANTS.TYPES.CONST : PYTHON_CONSTANTS.TYPES.VARIABLE,
+                loc: {
+                  start: {
+                    line: node.startPosition.row + 1,
+                    column: node.startPosition.column
+                  },
+                  end: {
+                    line: node.endPosition.row + 1,
+                    column: node.endPosition.column
+                  }
+                }
+              });
+            }
+          }
+        }
+      }
+    }
+    return exports;
+  }
+  /**
+   * Extract parameter names from a function definition node.
+   */
+  extractParameters(node) {
+    const paramsNode = node.childForFieldName(
+      PYTHON_CONSTANTS.FIELDS.PARAMETERS
+    );
+    if (!paramsNode) return [];
+    return paramsNode.children.filter(
+      (c) => c.type === PYTHON_CONSTANTS.NODES.IDENTIFIER || c.type === PYTHON_CONSTANTS.NODES.TYPED_PARAMETER || c.type === PYTHON_CONSTANTS.NODES.DEFAULT_PARAMETER
+    ).map((c) => {
+      if (c.type === PYTHON_CONSTANTS.NODES.IDENTIFIER) return c.text;
+      if (c.type === PYTHON_CONSTANTS.NODES.TYPED_PARAMETER || c.type === PYTHON_CONSTANTS.NODES.DEFAULT_PARAMETER) {
+        return c.firstChild?.text || "unknown";
+      }
+      return "unknown";
+    });
+  }
+  /**
+   * Fallback regex-based parsing when tree-sitter is unavailable.
+   */
+  parseRegex(code, filePath) {
+    try {
+      const imports = this.extractImportsRegex(code, filePath);
+      const exports = this.extractExportsRegex(code, filePath);
+      return {
+        exports,
+        imports,
+        language: "python" /* Python */,
+        warnings: [
+          "Python parsing is currently using regex-based extraction as tree-sitter wasm was not available."
+        ]
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to parse Python file ${filePath}: ${error.message}`
+      );
+    }
+  }
+  getNamingConventions() {
+    return {
+      variablePattern: /^[a-z_][a-z0-9_]*$/,
+      functionPattern: /^[a-z_][a-z0-9_]*$/,
+      classPattern: /^[A-Z][a-zA-Z0-9]*$/,
+      constantPattern: /^[A-Z][A-Z0-9_]*$/,
+      exceptions: [
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_INIT,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_STR,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_REPR,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_NAME,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_MAIN,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_FILE,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_DOC,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_ALL,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_VERSION,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_AUTHOR,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_DICT,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_CLASS,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_MODULE,
+        PYTHON_CONSTANTS.SPECIAL.DUNDER_BASES
+      ]
+    };
+  }
+  canHandle(filePath) {
+    return filePath.toLowerCase().endsWith(".py");
+  }
+  extractImportsRegex(code, _filePath) {
+    void _filePath;
+    const imports = [];
+    const lines = code.split("\n");
+    const importRegex = /^\s*import\s+([a-zA-Z0-9_., ]+)/;
+    const fromImportRegex = /^\s*from\s+([a-zA-Z0-9_.]+)\s+import\s+(.+)/;
+    lines.forEach((line, idx) => {
+      if (line.trim().startsWith("#")) return;
+      const importMatch = line.match(importRegex);
+      if (importMatch) {
+        const modules = importMatch[1].split(",").map((m) => m.trim().split(" as ")[0]);
+        modules.forEach((module) => {
+          imports.push({
+            source: module,
+            specifiers: [module],
+            loc: {
+              start: { line: idx + 1, column: 0 },
+              end: { line: idx + 1, column: line.length }
+            }
+          });
+        });
+        return;
+      }
+      const fromMatch = line.match(fromImportRegex);
+      if (fromMatch) {
+        const module = fromMatch[1];
+        const importsStr = fromMatch[2];
+        if (importsStr.trim() === PYTHON_CONSTANTS.SPECIAL.WILDCARD) {
+          imports.push({
+            source: module,
+            specifiers: [PYTHON_CONSTANTS.SPECIAL.WILDCARD],
+            loc: {
+              start: { line: idx + 1, column: 0 },
+              end: { line: idx + 1, column: line.length }
+            }
+          });
+          return;
+        }
+        const specifiers = importsStr.split(",").map((s) => s.trim().split(" as ")[0]);
+        imports.push({
+          source: module,
+          specifiers,
+          loc: {
+            start: { line: idx + 1, column: 0 },
+            end: { line: idx + 1, column: line.length }
+          }
+        });
+      }
+    });
+    return imports;
+  }
+  extractExportsRegex(code, _filePath) {
+    void _filePath;
+    const exports = [];
+    const lines = code.split("\n");
+    const funcRegex = /^def\s+([a-zA-Z0-9_]+)\s*\(/;
+    const classRegex = /^class\s+([a-zA-Z0-9_]+)/;
+    lines.forEach((line, idx) => {
+      const indent = line.search(/\S/);
+      if (indent !== 0) return;
+      const classMatch = line.match(classRegex);
+      if (classMatch) {
+        exports.push({
+          name: classMatch[1],
+          type: PYTHON_CONSTANTS.TYPES.CLASS,
+          visibility: "public",
+          isPure: true,
+          hasSideEffects: false,
+          loc: {
+            start: { line: idx + 1, column: 0 },
+            end: { line: idx + 1, column: line.length }
+          }
+        });
+        return;
+      }
+      const funcMatch = line.match(funcRegex);
+      if (funcMatch) {
+        const name = funcMatch[1];
+        if (name.startsWith("_") && !name.startsWith("__")) return;
+        let docContent;
+        const nextLines = lines.slice(idx + 1, idx + 4);
+        for (const nextLine of nextLines) {
+          const docMatch = nextLine.match(/^\s*"""([\s\S]*?)"""/) || nextLine.match(/^\s*'''([\s\S]*?)'''/);
+          if (docMatch) {
+            docContent = docMatch[1].trim();
+            break;
+          }
+          if (nextLine.trim() && !nextLine.trim().startsWith('"""') && !nextLine.trim().startsWith("'''"))
+            break;
+        }
+        const isImpure = name.toLowerCase().includes("impure") || line.includes(PYTHON_CONSTANTS.BUILTINS.PRINT) || idx + 1 < lines.length && lines[idx + 1].includes(PYTHON_CONSTANTS.BUILTINS.PRINT);
+        exports.push({
+          name,
+          type: PYTHON_CONSTANTS.TYPES.FUNCTION,
+          visibility: "public",
+          isPure: !isImpure,
+          hasSideEffects: isImpure,
+          documentation: docContent ? { content: docContent, type: PYTHON_CONSTANTS.TYPES.DOCSTRING } : void 0,
+          loc: {
+            start: { line: idx + 1, column: 0 },
+            end: { line: idx + 1, column: line.length }
+          }
+        });
+      }
+    });
+    return exports;
+  }
+};
+
+export {
+  PythonParser
+};

package/dist/index.d.mts

@@ -1104,7 +1104,7 @@ declare abstract class BaseLanguageParser implements LanguageParser {
  * Python Parser implementation using tree-sitter.
  * Handles AST-based and Regex-based extraction of imports and exports.
  *
- * @lastUpdated 2026-03-18
+ * @lastUpdated 2026-03-27
  */
 declare class PythonParser extends BaseLanguageParser {
     readonly language = Language.Python;
@@ -1112,40 +1112,22 @@ declare class PythonParser extends BaseLanguageParser {
     protected getParserName(): string;
     /**
      * Analyze metadata for a Python node (purity, side effects).
-     *
-     * @param node - Tree-sitter node to analyze.
-     * @param code - Source code for context.
-     * @returns Partial ExportInfo containing discovered metadata.
      */
     analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
     /**
      * Extract import information using AST walk.
-     *
-     * @param rootNode - Root node of the Python AST.
-     * @returns Array of discovered FileImport objects.
      */
     protected extractImportsAST(rootNode: Parser.Node): FileImport[];
     /**
      * Extract export information using AST walk.
-     *
-     * @param rootNode - Root node of the Python AST.
-     * @param code - Source code for documentation extraction.
-     * @returns Array of discovered ExportInfo objects.
      */
     protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     /**
      * Extract parameter names from a function definition node.
-     *
-     * @param node - Function definition node.
-     * @returns Array of parameter name strings.
      */
     private extractParameters;
     /**
      * Fallback regex-based parsing when tree-sitter is unavailable.
-     *
-     * @param code - Source code content.
-     * @param filePath - Path to the file being parsed.
-     * @returns Consolidated ParseResult.
      */
     protected parseRegex(code: string, filePath: string): ParseResult;
     getNamingConventions(): NamingConvention;

package/dist/index.d.ts

@@ -1104,7 +1104,7 @@ declare abstract class BaseLanguageParser implements LanguageParser {
  * Python Parser implementation using tree-sitter.
  * Handles AST-based and Regex-based extraction of imports and exports.
  *
- * @lastUpdated 2026-03-18
+ * @lastUpdated 2026-03-27
  */
 declare class PythonParser extends BaseLanguageParser {
     readonly language = Language.Python;
@@ -1112,40 +1112,22 @@ declare class PythonParser extends BaseLanguageParser {
     protected getParserName(): string;
     /**
      * Analyze metadata for a Python node (purity, side effects).
-     *
-     * @param node - Tree-sitter node to analyze.
-     * @param code - Source code for context.
-     * @returns Partial ExportInfo containing discovered metadata.
      */
     analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
     /**
      * Extract import information using AST walk.
-     *
-     * @param rootNode - Root node of the Python AST.
-     * @returns Array of discovered FileImport objects.
      */
     protected extractImportsAST(rootNode: Parser.Node): FileImport[];
     /**
      * Extract export information using AST walk.
-     *
-     * @param rootNode - Root node of the Python AST.
-     * @param code - Source code for documentation extraction.
-     * @returns Array of discovered ExportInfo objects.
      */
     protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     /**
      * Extract parameter names from a function definition node.
-     *
-     * @param node - Function definition node.
-     * @returns Array of parameter name strings.
      */
     private extractParameters;
     /**
      * Fallback regex-based parsing when tree-sitter is unavailable.
-     *
-     * @param code - Source code content.
-     * @param filePath - Path to the file being parsed.
-     * @returns Consolidated ParseResult.
      */
     protected parseRegex(code: string, filePath: string): ParseResult;
     getNamingConventions(): NamingConvention;