callograph 0.0.8 → 1.0.0

package/README.md

@@ -1,40 +1,49 @@
+
+---
+
 # Callograph
 
-**Callograph** is a static analysis tool for TypeScript projects that builds a program-level call graph and detects side effects, impurity propagation, and unsafe async behavior.
+**Callograph** is a structural static analysis engine for TypeScript that builds a full program-level call graph and performs interprocedural purity and async safety analysis.
 
-It is designed for engineers who want deeper insight into how code behaves beyond lint rules, by analyzing symbol resolution and cross-file call relationships using the TypeScript Compiler API.
+It goes beyond lint rules by analyzing symbol resolution, cross-file relationships, and effect propagation using the TypeScript Compiler API.
+
+Callograph is built for engineers who want architectural clarity — not stylistic warnings.
 
 ---
 
-## Why Callograph?
+## 🚀 What Callograph Does
 
-Modern TypeScript codebases suffer from:
+Callograph analyzes your entire TypeScript program and answers questions like:
 
-* Hidden side effects
-* Implicit mutation
-* Unintended global state access
-* Async misuse
-* Impure utilities leaking into shared modules
-* Lack of deterministic boundaries
+* Which functions call which?
+* Where do side effects originate?
+* How does impurity propagate?
+* Are promises safely handled?
+* Are async boundaries enforced?
+* Are errors swallowed?
+* Are async effects escaping function boundaries?
 
-Callograph provides structural visibility into function relationships and propagates impurity across the call graph to surface real architectural risks.
+It provides structural reasoning about your system.
 
 ---
 
-## Core Capabilities (v0.0.8)
+# Core Capabilities (v1.0.0)
 
-### 1. Call Graph Construction
+---
 
-Builds a full program-level call graph from your `tsconfig.json`.
+## 1. Program-Level Call Graph Construction
 
-It identifies:
+Callograph builds a complete call graph from your `tsconfig.json`.
+
+It detects:
 
 * Function → function relationships
 * Cross-file calls
-* Imported symbol calls
-* Method calls (where statically resolvable)
+* Imported symbol resolution
+* Method calls (when statically resolvable)
+* Interprocedural call edges
 
-Example output:
+Example:
 
 ```
 Call Graph:
@@ -44,38 +53,64 @@ applyDiscount → fetchTaxRate
 fetchTaxRate → Date.now
 ```
 
+This graph becomes the foundation for structural effect analysis.
+
 ---
 
-### 2. Function Purity Detection
+## 2. Function Purity Analysis
+
+Callograph determines whether a function is pure or impure based on structural rules.
 
-Callograph analyzes whether a function is:
+It detects:
 
-* Mutating its parameters
-* Writing to outer scope variables
-* Accessing global state
-* Calling impure functions
+### Parameter Mutation
+
+* Direct reassignment
+* Deep property mutation
+* Array mutator calls (`push`, `splice`, etc.)
 
 Example:
 
 ```
-src/utils/calc.ts:42
-Function: calculateTotal
-Status: ❌ Impure
+❌ Mutates parameter `items`
+```
+
+---
+
+### Outer Scope Writes
+
+Detects writes to variables declared outside the function.
 
-Reasons:
-  - Mutates parameter `items`
-  - Calls impure function `fetchTaxRate`
+```
+❌ Writes to outer scope `cache`
 ```
 
 ---
 
-### 3. Impurity Propagation
+### Global State Access
+
+Flags access to:
+
+* `process`
+* `process.env`
+* `window`
+* `global`
+* `document`
+* Console writes
+* `Date.now()`
+* `Math.random()`
+
+These are marked as non-deterministic or impure operations.
+
+---
+
+## 3. Impurity Propagation (Interprocedural)
 
 If:
 
 ```
 A → calls B
-B → impure
+B is impure
 ```
 
 Then:
@@ -84,194 +119,314 @@ Then:
 A becomes impure
 ```
 
-This propagation makes Callograph significantly more powerful than simple AST pattern scanning.
+Callograph propagates impurity across the call graph using reverse-graph traversal and fixed-point propagation.
 
-It reasons about effect chains.
+This makes impurity structural, not local.
 
 ---
 
-### 4. Global State & Non-Determinism Detection
+## 4. Enterprise Async Safety Engine
 
-Flags usage of:
+Callograph includes a dedicated async analysis engine, separate from purity.
 
-* `process.env`
-* `Date.now()`
-* `Math.random()`
-* `global`
-* `window`
-* Console writes (optional strict mode)
+It performs structural async inference.
 
-Useful for teams enforcing deterministic or pure-core architectures.
+---
+
+### Floating Promise Detection
+
+Flags:
+
+* Unawaited promises
+* Fire-and-forget async calls
+* Promises ignored inside expressions
+* Promises ignored inside loops (loop-aware escalation)
+
+Example:
+
+```
+❌ Floating promise
+⚠️ Floating promise inside loop
+```
 
 ---
 
-### 5. Parameter Mutation Detection
+### Promise.all Structural Analysis
 
 Detects:
 
-* Direct reassignment
-* Deep property mutation
-* Array mutation (`push`, `splice`, etc.)
+* Unawaited `Promise.all`
+* Promise arrays containing unhandled async calls
+* Deep inspection of array elements
+
+---
+
+### Async Callback Detection
+
+Flags async callbacks in:
+
+* `forEach`
+* `map`
+* `filter`
+* `reduce`
+* `addEventListener`
 
 Example:
 
 ```
-❌ Parameter mutation detected:
-updateUser(user) → user.name = "new"
+⚠️ Async callback inside array method
 ```
 
 ---
 
-### 6. Async Safety Checks
+### Error Swallowing Detection
+
+Detects:
+
+* Empty `.catch()` blocks
+* Swallowed promise rejections
+
+Example:
+
+```
+❌ Error swallowed in .catch()
+```
+
+---
+
+### Async Boundary Enforcement
 
 Flags:
 
-* Unawaited promises
-* Fire-and-forget async calls
-* Async functions lacking error handling (basic detection)
+```
+async function foo() {
+  await fetchData();
+}
+```
+
+If no `try/catch` boundary exists:
+
+```
+⚠️ Async function contains await but has no error boundary
+```
+
+---
+
+### Interprocedural Async Propagation
+
+If:
+
+```
+A calls B
+B returns a promise
+A does not await B
+```
+
+Then:
+
+```
+A is async-unsafe
+```
+
+Callograph propagates async risk across the call graph.
 
 ---
 
-### 7. CI Integration
+### Severity Model
+
+Async issues are categorized:
+
+* `error`
+* `warning`
+* `info`
 
-Callograph can fail CI if impure functions are detected.
+You can configure thresholds:
+
+```
+--async-severity=warning
+--fail-on-async
+```
+
+---
+
+## 5. CI Integration
+
+Callograph supports CI enforcement:
 
 ```
 callograph analyze --fail-on-impure
+callograph analyze --fail-on-async
 ```
 
-This allows enforcement of architectural constraints.
+You can enforce architectural constraints in pipelines.
 
 ---
 
-## Installation
+## 6. JSON Output Mode
+
+Structured JSON output for automation:
 
-```bash
-npm install --save-dev callograph
 ```
+callograph analyze --json
+```
+
+Useful for:
+
+* CI dashboards
+* Custom reporting
+* PR bots
+* IDE integrations
+
+---
 
-Or use directly:
+## 7. Smart Ignore System
+
+Callograph automatically:
+
+* Ignores `node_modules`
+* Detects and ignores its own source when analyzing itself
+
+You can manually ignore paths:
 
-```bash
-npx callograph analyze
+```
+--ignore=src/generated,dist
 ```
 
 ---
 
-## Usage
+# CLI Usage
 
-Analyze project based on `tsconfig.json`:
+Analyze project:
 
-```bash
+```
 callograph analyze
 ```
 
-JSON output:
+Custom tsconfig:
 
-```bash
-callograph analyze --json
+```
+callograph analyze tsconfig.build.json
 ```
 
-Fail CI if impurity detected:
+Fail on impurity:
 
-```bash
+```
 callograph analyze --fail-on-impure
 ```
 
-Export DOT graph:
+Fail on async violations:
 
-```bash
-callograph analyze --dot
+```
+callograph analyze --fail-on-async
 ```
 
----
+Adjust async severity threshold:
 
-## Architecture
+```
+callograph analyze --async-severity=warning
+```
 
-Callograph uses:
+JSON output:
 
-* TypeScript Compiler API
-* Program-level symbol resolution
-* TypeChecker-based call resolution
-* AST traversal via `ts.forEachChild`
-* Impurity propagation via call graph traversal
+```
+callograph analyze --json
+```
 
-Pipeline:
+---
+
+# Architecture
+
+Callograph pipeline:
 
 ```
 Load tsconfig
 ↓
-Create Program
+Create TypeScript Program
+↓
+Collect function declarations (ignore-aware)
 ↓
-Extract function symbols
+Build call graph (TypeChecker-based resolution)
 ↓
-Build call graph
+Purity analysis
 ↓
-Detect side effects
+Impurity propagation
 ↓
-Propagate impurity
+Async flow analysis
 ↓
-Report results
+Async return propagation
+↓
+Async risk propagation
+↓
+Severity filtering
+↓
+Report (Text or JSON)
 ```
 
 ---
 
-## Design Philosophy
-
-Callograph does not attempt perfect purity inference.
-It aims to provide practical, high-signal diagnostics with minimal noise.
+# Design Philosophy
 
-It prioritizes:
+Callograph is designed for:
 
-* Deterministic analysis
-* CI compatibility
-* Clear reasoning in output
+* Structural clarity
+* Deterministic reasoning
 * Minimal false positives
-* Performance (<2s on mid-sized codebases)
+* Interprocedural analysis
+* CI enforcement
+* Performance on mid-sized codebases
+
+It does not aim for perfect theoretical purity inference.
+
+It aims for high-signal architectural diagnostics.
 
 ---
 
-## Limitations (v0.0.8)
+# Current Limitations
 
-* Dynamic runtime dispatch cannot always be resolved.
-* Higher-order functions are partially supported.
-* Deep framework-specific analysis is not included.
-* No IDE integration yet.
+* Dynamic runtime dispatch cannot always be resolved
+* Higher-order functional inference is partial
+* No race-condition modeling (sync/async timing hazards)
+* No async escape-boundary graph modeling yet
+* No IDE plugin yet
 
 ---
 
-## Roadmap
+# Roadmap
 
+Planned enhancements:
+
+* DOT graph export
+* Circular dependency detection
 * Shared mutable singleton detection
 * Closure-captured state analysis
-* Circular call detection
-* Effect scoring per module
-* Interactive HTML graph visualization
+* Module-level effect scoring
+* Async escape-boundary modeling
+* Mixed sync/async race detection
+* HTML graph visualization
 * GitHub PR comment bot
-* Monorepo support with project references
+* Monorepo project reference support
 
 ---
 
-## License
-
-MIT
+# Versioning
 
----
-
-## Contributing
+The current release introduces:
 
-Contributions are welcome.
+* Dedicated async engine
+* Interprocedural async propagation
+* Severity modeling
+* JSON output
+* Smart ignore system
+* Enterprise boundary detection
 
-* Open an issue to discuss architecture changes.
-* Keep changes deterministic and type-safe.
-* Add tests for new analysis rules.
+Callograph is evolving toward a structural effect analysis engine for TypeScript.
 
 ---
- 
-## Vision
+
+# Vision
 
 Callograph aims to become:
 
-> A structural analysis tool that gives engineers clarity over side effects, purity, and call relationships in large TypeScript systems.
+> A structural analysis engine that provides deep visibility into side effects, purity, async safety, and architectural boundaries in large TypeScript systems.
 
----
+---

package/dist/cli.cjs

@@ -1,8 +1,24 @@
 #!/usr/bin/env node
-"use strict";var se=Object.create;var G=Object.defineProperty;var ne=Object.getOwnPropertyDescriptor;var ie=Object.getOwnPropertyNames;var re=Object.getPrototypeOf,oe=Object.prototype.hasOwnProperty;var ae=(e,t,s,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of ie(t))!oe.call(e,i)&&i!==s&&G(e,i,{get:()=>t[i],enumerable:!(r=ne(t,i))||r.enumerable});return e};var S=(e,t,s)=>(s=e!=null?se(re(e)):{},ae(t||!e||!e.__esModule?G(s,"default",{value:e,enumerable:!0}):s,e));var y=S(require("typescript"),1);function R(e){let t=y.default.readConfigFile(e,y.default.sys.readFile);if(t.error)throw new Error(y.default.flattenDiagnosticMessageText(t.error.messageText,`
-`));let s=y.default.parseJsonConfigFileContent(t.config,y.default.sys,process.cwd());return y.default.createProgram({rootNames:s.fileNames,options:s.options})}var m=S(require("typescript"),1);function ce(e,t){let s=e;if(s.name&&m.default.isIdentifier(s.name))return s.name.text;if(s.name&&(m.default.isStringLiteral(s.name)||m.default.isNumericLiteral(s.name)))return String(s.name.text);let r=e.parent;if(r&&m.default.isVariableDeclaration(r)&&m.default.isIdentifier(r.name))return r.name.text;if(r&&m.default.isBinaryExpression(r)&&m.default.isPropertyAccessExpression(r.left))return r.left.name.text;let{line:i,character:o}=t.getLineAndCharacterOfPosition(e.getStart(t));return`<anonymous@${i+1}:${o+1}>`}function q(e){let t=[];for(let s of e.getSourceFiles())s.isDeclarationFile||s.fileName.includes("node_modules")||m.default.forEachChild(s,function r(i){let o=m.default.isFunctionDeclaration(i)&&!!i.name,f=m.default.isMethodDeclaration(i),x=i.parent,g=(m.default.isArrowFunction(i)||m.default.isFunctionExpression(i))&&!!x&&m.default.isVariableDeclaration(x)&&m.default.isIdentifier(x.name);if(o||f||g){let h=ce(i,s),A=`${s.fileName}:${i.pos}:${h}`;t.push({id:A,name:h,file:s.fileName,node:i})}m.default.forEachChild(i,r)});return t}var w=S(require("typescript"),1);function le(e){return!e.includes("node_modules")&&!e.endsWith(".d.ts")}function O(e,t){let s=e.getTypeChecker(),r=new Map,i=new Map;for(let f of t)r.set(f.id,new Set),i.set(f.node,f.id);for(let f of t){let g=function(h){if(w.default.isCallExpression(h)){let c=s.getResolvedSignature(h)?.getDeclaration();if(c&&le(c.getSourceFile().fileName)){let P=i.get(c);P&&r.get(x).add(P)}}w.default.forEachChild(h,g)};var o=g;let x=f.id;g(f.node)}return r}var a=S(require("typescript"),1);var W=new Set(["window","document","global","process","localStorage","sessionStorage"]),_=new Set(["push","pop","splice","shift","unshift","sort","reverse","copyWithin","fill"]);var p=S(require("typescript"),1);function B(e,t){return e.pos>=t.pos&&e.end<=t.end}function E(e){return p.default.isIdentifier(e)?e:p.default.isPropertyAccessExpression(e)||p.default.isElementAccessExpression(e)||p.default.isParenthesizedExpression(e)?E(e.expression):null}function z(e){return e===p.default.SyntaxKind.EqualsToken||e===p.default.SyntaxKind.PlusEqualsToken||e===p.default.SyntaxKind.MinusEqualsToken||e===p.default.SyntaxKind.AsteriskEqualsToken||e===p.default.SyntaxKind.SlashEqualsToken||e===p.default.SyntaxKind.PercentEqualsToken||e===p.default.SyntaxKind.AmpersandEqualsToken||e===p.default.SyntaxKind.BarEqualsToken||e===p.default.SyntaxKind.CaretEqualsToken||e===p.default.SyntaxKind.LessThanLessThanEqualsToken||e===p.default.SyntaxKind.GreaterThanGreaterThanEqualsToken||e===p.default.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken}var d=S(require("typescript"),1);function H(e,t){if(!e)return!1;let s=e.getProperty("then");if(!s)return!1;let r=s.valueDeclaration??s.declarations?.[0];return r?t.getTypeOfSymbolAtLocation(s,r).getCallSignatures().length>0:!1}function I(e){return d.default.isAwaitExpression(e.parent)}function F(e){return d.default.isReturnStatement(e.parent)}function U(e){if(!d.default.isPropertyAccessExpression(e.parent))return!1;let t=e.parent.name.text;return t==="then"||t==="catch"||t==="finally"}function j(e){if(!d.default.isPropertyAccessExpression(e.expression)||e.expression.name.text!=="forEach")return!1;let t=e.arguments[0];return t&&(d.default.isArrowFunction(t)||d.default.isFunctionExpression(t))?t.modifiers?.some(s=>s.kind===d.default.SyntaxKind.AsyncKeyword)??!1:!1}function J(e){if(!d.default.isPropertyAccessExpression(e.expression)||e.expression.name.text!=="addEventListener")return!1;let t=e.arguments[1];return t&&(d.default.isArrowFunction(t)||d.default.isFunctionExpression(t))?t.modifiers?.some(s=>s.kind===d.default.SyntaxKind.AsyncKeyword)??!1:!1}function V(e){return d.default.isPropertyAccessExpression(e.expression)&&d.default.isIdentifier(e.expression.expression)&&e.expression.expression.text==="Promise"&&e.expression.name.text==="all"}function Y(e,t){let s=e.getTypeChecker(),r=[];for(let o of t){let C=function(n){if(a.default.isBinaryExpression(n)&&z(n.operatorToken.kind)){let l=n.left,u=E(l);if(u&&A.has(u.text)&&c(`Mutates parameter \`${u.text}\``),a.default.isIdentifier(l)){let $=s.getSymbolAtLocation(l),v=$?.getDeclarations()??[],ee=v.some(te=>B(te,o.node));$&&v.length>0&&!ee&&c(`Writes to outer scope \`${l.text}\``)}a.default.isPropertyAccessExpression(l)&&l.expression.kind===a.default.SyntaxKind.ThisKeyword&&c(`Mutates \`this.${l.name.text}\``)}if(a.default.isCallExpression(n)&&a.default.isPropertyAccessExpression(n.expression)){let l=n.expression.name.text,u=E(n.expression.expression);u&&A.has(u.text)&&_.has(l)&&c(`Mutates parameter \`${u.text}\` via \`${l}()\``)}if(a.default.isIdentifier(n)){let l=s.getSymbolAtLocation(n);l&&W.has(l.getName())&&c(`Accesses global \`${l.getName()}\``)}if(a.default.isPropertyAccessExpression(n)){let l=E(n.expression);l?.text==="process"&&n.name.text==="env"&&c("Accesses `process.env` (non-deterministic)"),l?.text==="console"&&c("Writes to console")}if(a.default.isCallExpression(n)){let l=s.getTypeAtLocation(n),u=n.expression;a.default.isPropertyAccessExpression(u)&&a.default.isIdentifier(u.expression)&&u.expression.text==="Date"&&u.name.text==="now"&&c("Calls Date.now() (non-deterministic)"),a.default.isPropertyAccessExpression(u)&&a.default.isIdentifier(u.expression)&&u.expression.text==="Math"&&u.name.text==="random"&&c("Calls Math.random() (non-deterministic)"),H(l,s)&&!I(n)&&!F(n)&&!U(n)&&c("Floating Promise (result ignored)"),V(n)&&!I(n)&&!F(n)&&c("Unawaited Promise.all()"),j(n)&&c("Async callback inside forEach (not awaited)"),J(n)&&c("Async event listener without error boundary")}a.default.isNewExpression(n)&&a.default.isIdentifier(n.expression)&&n.expression.text==="Date"&&c("Instantiates Date (non-deterministic)"),a.default.isAwaitExpression(n)&&(P=!0),a.default.isTryStatement(n)&&n.catchClause&&(L=!0),a.default.isCatchClause(n)&&n.block.statements.length===0&&c("Empty catch block (error swallowed)"),a.default.forEachChild(n,C)};var i=C;let f=o.node.getSourceFile(),{line:x,character:g}=f.getLineAndCharacterOfPosition(o.node.getStart(f)),h=[],A=new Set;for(let n of o.node.parameters)a.default.isIdentifier(n.name)&&A.add(n.name.text);let c=n=>{h.includes(n)||h.push(n)},P=!1,L=!1,D=o.node.modifiers?.some(n=>n.kind===a.default.SyntaxKind.AsyncKeyword)??!1;C(o.node),D&&!P&&c("Async function without await"),D&&P&&!L&&c("Async function without error handling (no try/catch)"),r.push({id:o.id,name:o.name,file:o.file,line:x+1,character:g+1,isPure:h.length===0,reasons:h})}return r}function X(e,t){let s=new Map;for(let o of t)s.set(o.id,o);let r=new Map;for(let[o,f]of e.entries())for(let x of f)r.has(x)||r.set(x,new Set),r.get(x).add(o);let i=[];for(let o of t)o.isPure||i.push(o.id);for(;i.length>0;){let o=i.shift(),f=r.get(o);if(f)for(let x of f){let g=s.get(x);g&&g.isPure&&(g.isPure=!1,g.reasons.push("Calls impure function"),i.push(x))}}return Array.from(s.values())}var T=process.argv.slice(2),fe=T[0];fe!=="analyze"&&(console.log("Usage: callograph analyze [tsconfigPath] [--fail-on-impure]"),process.exit(1));var pe=T[1]&&!T[1].startsWith("--")?T[1]:"tsconfig.json",ue=T.includes("--fail-on-impure"),M=R(pe),b=q(M),Z=O(M,b),N=Y(M,b);N=X(Z,N);var Q=new Map(b.map(e=>[e.id,e]));console.log(`
+"use strict";var pe=Object.create;var q=Object.defineProperty;var me=Object.getOwnPropertyDescriptor;var ye=Object.getOwnPropertyNames;var ge=Object.getPrototypeOf,de=Object.prototype.hasOwnProperty;var he=(e,t,s,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of ye(t))!de.call(e,a)&&a!==s&&q(e,a,{get:()=>t[a],enumerable:!(n=me(t,a))||n.enumerable});return e};var C=(e,t,s)=>(s=e!=null?pe(ge(e)):{},he(t||!e||!e.__esModule?q(s,"default",{value:e,enumerable:!0}):s,e));var D=C(require("fs"),1),oe=C(require("path"),1);var P=C(require("typescript"),1);function z(e){let t=P.default.readConfigFile(e,P.default.sys.readFile);if(t.error)throw new Error(P.default.flattenDiagnosticMessageText(t.error.messageText,`
+`));let s=P.default.parseJsonConfigFileContent(t.config,P.default.sys,process.cwd());return P.default.createProgram({rootNames:s.fileNames,options:s.options})}var h=C(require("typescript"),1);function xe(e,t){let s=e;if(s.name&&h.default.isIdentifier(s.name))return s.name.text;if(s.name&&(h.default.isStringLiteral(s.name)||h.default.isNumericLiteral(s.name)))return String(s.name.text);let n=e.parent;if(n&&h.default.isVariableDeclaration(n)&&h.default.isIdentifier(n.name))return n.name.text;if(n&&h.default.isBinaryExpression(n)&&h.default.isPropertyAccessExpression(n.left))return n.left.name.text;let{line:a,character:o}=t.getLineAndCharacterOfPosition(e.getStart(t));return`<anonymous@${a+1}:${o+1}>`}function W(e,t=[]){let s=[],n=t.map(a=>a.replace(/\\/g,"/"));for(let a of e.getSourceFiles()){if(a.isDeclarationFile)continue;let o=a.fileName.replace(/\\/g,"/");n.some(l=>o.includes(l))||h.default.forEachChild(a,function l(c){let p=h.default.isFunctionDeclaration(c)&&!!c.name,m=h.default.isMethodDeclaration(c),g=c.parent,r=(h.default.isArrowFunction(c)||h.default.isFunctionExpression(c))&&!!g&&h.default.isVariableDeclaration(g)&&h.default.isIdentifier(g.name);if(p||m||r){let x=xe(c,a),i=`${o}:${c.pos}:${x}`;s.push({id:i,name:x,file:o,node:c})}h.default.forEachChild(c,l)})}return s}var $=C(require("typescript"),1);function Ae(e){return!e.includes("node_modules")&&!e.endsWith(".d.ts")}function _(e,t){let s=e.getTypeChecker(),n=new Map,a=new Map;for(let l of t)n.set(l.id,new Set),a.set(l.node,l.id);for(let l of t){let p=function(m){if($.default.isCallExpression(m)){let r=s.getResolvedSignature(m)?.getDeclaration();if(r&&Ae(r.getSourceFile().fileName)){let x=a.get(r);x&&n.get(c).add(x)}}$.default.forEachChild(m,p)};var o=p;let c=l.id;p(l.node)}return n}var y=C(require("typescript"),1);var B=new Set(["window","document","global","process","localStorage","sessionStorage"]),H=new Set(["push","pop","splice","shift","unshift","sort","reverse","copyWithin","fill"]);var d=C(require("typescript"),1);function j(e,t){return e.pos>=t.pos&&e.end<=t.end}function F(e){return d.default.isIdentifier(e)?e:d.default.isPropertyAccessExpression(e)||d.default.isElementAccessExpression(e)||d.default.isParenthesizedExpression(e)?F(e.expression):null}function J(e){return e===d.default.SyntaxKind.EqualsToken||e===d.default.SyntaxKind.PlusEqualsToken||e===d.default.SyntaxKind.MinusEqualsToken||e===d.default.SyntaxKind.AsteriskEqualsToken||e===d.default.SyntaxKind.SlashEqualsToken||e===d.default.SyntaxKind.PercentEqualsToken||e===d.default.SyntaxKind.AmpersandEqualsToken||e===d.default.SyntaxKind.BarEqualsToken||e===d.default.SyntaxKind.CaretEqualsToken||e===d.default.SyntaxKind.LessThanLessThanEqualsToken||e===d.default.SyntaxKind.GreaterThanGreaterThanEqualsToken||e===d.default.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken}function U(e,t){let s=e.getTypeChecker(),n=[];for(let o of t){let x=function(i){if(y.default.isBinaryExpression(i)&&J(i.operatorToken.kind)){let f=i.left,S=F(f);if(S&&g.has(S.text)&&r(`Mutates parameter \`${S.text}\``),y.default.isIdentifier(f)){let E=s.getSymbolAtLocation(f),v=E?.getDeclarations()??[],fe=v.some(ue=>j(ue,o.node));E&&v.length>0&&!fe&&r(`Writes to outer scope \`${f.text}\``)}y.default.isPropertyAccessExpression(f)&&f.expression.kind===y.default.SyntaxKind.ThisKeyword&&r(`Mutates \`this.${f.name.text}\``)}if(y.default.isCallExpression(i)&&y.default.isPropertyAccessExpression(i.expression)){let f=i.expression.name.text,S=F(i.expression.expression);S&&g.has(S.text)&&H.has(f)&&r(`Mutates parameter \`${S.text}\` via \`${f}()\``)}if(y.default.isIdentifier(i)){let f=s.getSymbolAtLocation(i);f&&B.has(f.getName())&&r(`Accesses global \`${f.getName()}\``)}if(y.default.isPropertyAccessExpression(i)){let f=F(i.expression);f?.text==="process"&&i.name.text==="env"&&r("Accesses `process.env` (non-deterministic)"),f?.text==="console"&&r("Writes to console")}if(y.default.isCallExpression(i)){let f=i.expression;y.default.isPropertyAccessExpression(f)&&y.default.isIdentifier(f.expression)&&f.expression.text==="Date"&&f.name.text==="now"&&r("Calls Date.now() (non-deterministic)"),y.default.isPropertyAccessExpression(f)&&y.default.isIdentifier(f.expression)&&f.expression.text==="Math"&&f.name.text==="random"&&r("Calls Math.random() (non-deterministic)")}y.default.isNewExpression(i)&&y.default.isIdentifier(i.expression)&&i.expression.text==="Date"&&r("Instantiates Date (non-deterministic)"),y.default.isCatchClause(i)&&i.block.statements.length===0&&r("Empty catch block (error swallowed)"),y.default.forEachChild(i,x)};var a=x;let l=o.node.getSourceFile(),{line:c,character:p}=l.getLineAndCharacterOfPosition(o.node.getStart(l)),m=[],g=new Set;for(let i of o.node.parameters)y.default.isIdentifier(i.name)&&g.add(i.name.text);let r=i=>{m.includes(i)||m.push(i)};x(o.node),n.push({id:o.id,name:o.name,file:o.file,line:c+1,character:p+1,isPure:m.length===0,reasons:m})}return n}function V(e,t){let s=new Map;for(let o of t)s.set(o.id,o);let n=new Map;for(let[o,l]of e.entries())for(let c of l)n.has(c)||n.set(c,new Set),n.get(c).add(o);let a=[];for(let o of t)o.isPure||a.push(o.id);for(;a.length>0;){let o=a.shift(),l=n.get(o);if(l)for(let c of l){let p=s.get(c);p&&p.isPure&&(p.isPure=!1,p.reasons.push("Calls impure function"),a.push(c))}}return Array.from(s.values())}var A=C(require("typescript"),1);var u=C(require("typescript"),1);function M(e,t){if(!e)return!1;let s=e.getProperty("then");if(!s)return!1;let n=s.valueDeclaration??s.declarations?.[0];return n?t.getTypeOfSymbolAtLocation(s,n).getCallSignatures().length>0:!1}function Se(e){let t=e.parent;if(!u.default.isPropertyAccessExpression(t))return!1;let s=t.name.text;return s==="then"||s==="catch"||s==="finally"}function R(e){let t=e.parent;return!!(u.default.isAwaitExpression(t)||u.default.isReturnStatement(t)||u.default.isVariableDeclaration(t)||u.default.isBinaryExpression(t)||u.default.isCallExpression(t)||Se(e))}var Ee=new Set(["forEach","map","filter","reduce"]);function Y(e){if(!u.default.isPropertyAccessExpression(e.expression))return!1;let t=e.expression.name.text;if(!Ee.has(t))return!1;let s=e.arguments[0];return s&&(u.default.isArrowFunction(s)||u.default.isFunctionExpression(s))?s.modifiers?.some(n=>n.kind===u.default.SyntaxKind.AsyncKeyword)??!1:!1}function Q(e){if(!u.default.isPropertyAccessExpression(e.expression)||e.expression.name.text!=="addEventListener")return!1;let t=e.arguments[1];return t&&(u.default.isArrowFunction(t)||u.default.isFunctionExpression(t))?t.modifiers?.some(s=>s.kind===u.default.SyntaxKind.AsyncKeyword)??!1:!1}function X(e){return u.default.isPropertyAccessExpression(e.expression)&&u.default.isIdentifier(e.expression.expression)&&e.expression.expression.text==="Promise"&&e.expression.name.text==="all"}function Z(e){return u.default.isForStatement(e)||u.default.isForOfStatement(e)||u.default.isForInStatement(e)||u.default.isWhileStatement(e)||u.default.isDoStatement(e)}function ee(e,t){let s=t.getTypeChecker(),n=[],a=[],o=!1,l=!1,c=!1,p=e.node.modifiers?.some(r=>r.kind===A.default.SyntaxKind.AsyncKeyword)??!1,m=(r,x)=>{n.push({message:r,severity:x})};function g(r,x=!1){if(Z(r)){A.default.forEachChild(r,i=>g(i,!0));return}if(A.default.isAwaitExpression(r)&&(l=!0),A.default.isTryStatement(r)&&r.catchClause&&(c=!0),A.default.isCallExpression(r)){let i=s.getTypeAtLocation(r);if(M(i,s)){o=!0,R(r)||m(x?"Floating promise inside loop":"Floating promise",x?"warning":"error");let E=s.getResolvedSignature(r)?.getDeclaration();if(E&&E.getSourceFile().fileName.includes(process.cwd())){let v=`${E.getSourceFile().fileName}:${E.pos}`;a.push(v)}}if(X(r)){R(r)||m("Unawaited Promise.all()","error");let f=r.arguments[0];if(f&&A.default.isArrayLiteralExpression(f))for(let S of f.elements){let E=s.getTypeAtLocation(S);M(E,s)&&(R(r)||m("Promise.all contains unhandled promise","error"))}}Y(r)&&m("Async callback inside array method","warning"),Q(r)&&m("Async event listener without boundary","warning")}if(A.default.isPropertyAccessExpression(r)&&r.name.text==="catch"&&A.default.isCallExpression(r.parent)){let i=r.parent.arguments[0];i&&(A.default.isArrowFunction(i)||A.default.isFunctionExpression(i))&&i.body&&A.default.isBlock(i.body)&&i.body.statements.length===0&&m("Error swallowed in .catch()","error")}A.default.forEachChild(r,i=>g(i,x))}return g(e.node),p&&l&&!c&&m("Async function contains await but has no error boundary (try/catch)","warning"),{issues:n,returnsPromise:o,callsReturningPromise:a}}function se(e,t){let s=[];for(let n of t){let a=n.node.getSourceFile(),{line:o,character:l}=a.getLineAndCharacterOfPosition(n.node.getStart()),c=ee(n,e);s.push({id:n.id,name:n.name,file:n.file,line:o+1,character:l+1,issues:c.issues})}return s}function te(e,t){let s=new Map(t.map(a=>[a.id,a])),n=!0;for(;n;){n=!1;for(let[a,o]of e.entries()){let l=s.get(a);if(l)for(let c of o){let p=s.get(c);if(!p)continue;p.issues.some(g=>g.message.includes("Floating")||g.message.includes("Promise"))&&(l.issues.some(r=>r.message==="Calls promise-returning function without await")||(l.issues.push({message:"Calls promise-returning function without await",severity:"error"}),n=!0))}}}return Array.from(s.values())}function ne(e,t){let s=new Map(t.map(o=>[o.id,o])),n=new Map;for(let[o,l]of e.entries())for(let c of l)n.has(c)||n.set(c,new Set),n.get(c).add(o);let a=t.filter(o=>o.issues.some(l=>l.severity==="error")).map(o=>o.id);for(;a.length;){let o=a.shift(),l=n.get(o);if(l)for(let c of l){let p=s.get(c);if(!p)continue;p.issues.some(g=>g.message==="Calls async-unsafe function")||(p.issues.push({message:"Calls async-unsafe function",severity:"error"}),a.push(c))}}return Array.from(s.values())}var w=process.argv.slice(2),L=w[0];function ie(){console.log(`
+Callograph \u2014 Structural TypeScript Analyzer
+
+Usage:
+  callograph analyze [tsconfigPath]
+
+Options:
+  --fail-on-impure                 Exit with code 1 if impurity detected
+  --fail-on-async                  Exit with code 1 if async issues detected
+  --async-severity=error|warning|info
+                                    Minimum async severity to report (default: error)
+  --ignore=pattern1,pattern2       Comma-separated path substrings to ignore
+  --json                           Output structured JSON
+  --help                           Show this help message
+`)}(!L||L==="--help")&&(ie(),process.exit(0));L!=="analyze"&&(ie(),process.exit(1));var Ce=w[1]&&!w[1].startsWith("--")?w[1]:"tsconfig.json",we=w.includes("--fail-on-impure"),Pe=w.includes("--fail-on-async"),Fe=w.includes("--json"),Te=w.find(e=>e.startsWith("--async-severity=")),ae=Te?.split("=")[1]??"error",b={error:3,warning:2,info:1},re=w.find(e=>e.startsWith("--ignore=")),Ie=re?re.split("=")[1].split(","):[],ce=["node_modules"];try{let e=oe.default.join(process.cwd(),"package.json");D.default.existsSync(e)&&JSON.parse(D.default.readFileSync(e,"utf-8")).name==="callograph"&&ce.push("src/analyzer","src/cli","dist")}catch{}var ve=[...ce,...Ie],k=z(Ce),K=W(k).filter(e=>!ve.some(t=>e.file.includes(t))),I=_(k,K),N=U(k,K);N=V(I,N);var T=se(k,K);T=te(I,T);T=ne(I,T);if(Fe){let e={callGraph:Array.from(I.entries()).map(([t,s])=>({caller:t,callees:Array.from(s)})),purity:N,async:T};console.log(JSON.stringify(e,null,2)),process.exit(0)}console.log(`
 Call Graph:
-`);var k=0;for(let[e,t]of Z.entries()){let s=Q.get(e),r=s?s.name:e;for(let i of t){let o=Q.get(i),f=o?o.name:i;console.log(`${r} \u2192 ${f}`),k++}}k===0&&console.log("(no project-level call edges found)");console.log(`
-Total call edges: ${k}`);console.log(`
+`);var le=0;for(let[e,t]of I.entries())for(let s of t)console.log(`${e} \u2192 ${s}`),le++;console.log(`
+Total call edges: ${le}`);console.log(`
 Purity Report:
-`);var K=N.filter(e=>!e.isPure);if(K.length===0)console.log("All analyzed functions are pure.");else for(let e of K){console.log(`${e.file}:${e.line}:${e.character}`),console.log(`Function: ${e.name}`),console.log("Status: X Impure"),console.log("Reasons:");for(let t of e.reasons)console.log(`  - ${t}`);console.log("")}ue&&K.length>0&&process.exit(1);
+`);var G=N.filter(e=>!e.isPure);if(G.length===0)console.log("All analyzed functions are pure.");else for(let e of G){console.log(`${e.file}:${e.line}:${e.character}`),console.log(`Function: ${e.name}`);for(let t of e.reasons)console.log(`  - ${t}`);console.log("")}we&&G.length>0&&process.exit(1);function Re(e){let t=new Map;for(let s of e){let n=`${s.severity}|${s.message}`;t.has(n)?t.get(n).count++:t.set(n,{severity:s.severity,count:1})}return Array.from(t.entries()).map(([s,n])=>{let[,a]=s.split("|");return{message:a,severity:n.severity,count:n.count}})}console.log(`
+Async Safety Report:
+`);var O=T.filter(e=>e.issues.some(t=>b[t.severity]>=b[ae]));if(O.length===0)console.log("No async issues detected.");else for(let e of O){console.log(`${e.file}:${e.line}:${e.character}`),console.log(`Function: ${e.name}`);let t=Re(e.issues);for(let s of t)if(b[s.severity]>=b[ae]){let n=s.count>1?` (${s.count} occurrences)`:"";console.log(`  [${s.severity.toUpperCase()}] ${s.message}${n}`)}console.log("")}Pe&&O.length>0&&process.exit(1);

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var s=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var i=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var v=(e,o)=>{for(var r in o)s(e,r,{get:o[r],enumerable:!0})},x=(e,o,r,t)=>{if(o&&typeof o=="object"||typeof o=="function")for(let n of i(o))!p.call(e,n)&&n!==r&&s(e,n,{get:()=>o[n],enumerable:!(t=c(o,n))||t.enumerable});return e};var a=e=>x(s({},"__esModule",{value:!0}),e);var d={};v(d,{version:()=>b});module.exports=a(d);var b="0.0.2";0&&(module.exports={version});
+"use strict";var s=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var i=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var v=(e,o)=>{for(var r in o)s(e,r,{get:o[r],enumerable:!0})},x=(e,o,r,t)=>{if(o&&typeof o=="object"||typeof o=="function")for(let n of i(o))!p.call(e,n)&&n!==r&&s(e,n,{get:()=>o[n],enumerable:!(t=c(o,n))||t.enumerable});return e};var a=e=>x(s({},"__esModule",{value:!0}),e);var d={};v(d,{version:()=>b});module.exports=a(d);var b="1.0.0";0&&(module.exports={version});

package/dist/index.d.cts

@@ -1,3 +1,3 @@
-declare const version = "0.0.2";
+declare const version = "1.0.0";
 
 export { version };

package/package.json

@@ -1,51 +1,41 @@
 {
   "name": "callograph",
-  "version": "0.0.8",
+  "version": "1.0.0",
   "description": "TypeScript call graph and side-effect analyzer.",
   "license": "MIT",
   "type": "module",
-
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
-
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "prepublishOnly": "npm run build"
   },
-
   "dependencies": {
     "typescript": "^5.9.3"
   },
-
   "devDependencies": {
     "@types/node": "^25.2.3",
     "tsup": "^8.5.1"
   },
-
   "bin": {
     "callograph": "dist/cli.cjs"
   },
-
   "engines": {
     "node": ">=18"
   },
-
   "repository": {
     "type": "git",
     "url": "git+https://github.com/miraclemarcel/callograph.git"
   },
-
   "bugs": {
     "url": "https://github.com/miraclemarcel/callograph/issues"
   },
-
   "homepage": "https://github.com/miraclemarcel/callograph#readme"
 }