callograph 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 247TechBoss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# 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.
+
+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.
+
+---
+
+## Why Callograph?
+
+Modern TypeScript codebases suffer from:
+
+* Hidden side effects
+* Implicit mutation
+* Unintended global state access
+* Async misuse
+* Impure utilities leaking into shared modules
+* Lack of deterministic boundaries
+
+Callograph provides structural visibility into function relationships and propagates impurity across the call graph to surface real architectural risks.
+
+---
+
+## Core Capabilities (v0.1.0)
+
+### 1. Call Graph Construction
+
+Builds a full program-level call graph from your `tsconfig.json`.
+
+It identifies:
+
+* Function → function relationships
+* Cross-file calls
+* Imported symbol calls
+* Method calls (where statically resolvable)
+
+Example output:
+
+```
+Call Graph:
+
+calculateTotal → applyDiscount
+applyDiscount → fetchTaxRate
+fetchTaxRate → Date.now
+```
+
+---
+
+### 2. Function Purity Detection
+
+Callograph analyzes whether a function is:
+
+* Mutating its parameters
+* Writing to outer scope variables
+* Accessing global state
+* Calling impure functions
+
+Example:
+
+```
+src/utils/calc.ts:42
+Function: calculateTotal
+Status: ❌ Impure
+
+Reasons:
+  - Mutates parameter `items`
+  - Calls impure function `fetchTaxRate`
+```
+
+---
+
+### 3. Impurity Propagation
+
+If:
+
+```
+A → calls B
+B → impure
+```
+
+Then:
+
+```
+A becomes impure
+```
+
+This propagation makes Callograph significantly more powerful than simple AST pattern scanning.
+
+It reasons about effect chains.
+
+---
+
+### 4. Global State & Non-Determinism Detection
+
+Flags usage of:
+
+* `process.env`
+* `Date.now()`
+* `Math.random()`
+* `global`
+* `window`
+* Console writes (optional strict mode)
+
+Useful for teams enforcing deterministic or pure-core architectures.
+
+---
+
+### 5. Parameter Mutation Detection
+
+Detects:
+
+* Direct reassignment
+* Deep property mutation
+* Array mutation (`push`, `splice`, etc.)
+
+Example:
+
+```
+❌ Parameter mutation detected:
+updateUser(user) → user.name = "new"
+```
+
+---
+
+### 6. Async Safety Checks
+
+Flags:
+
+* Unawaited promises
+* Fire-and-forget async calls
+* Async functions lacking error handling (basic detection)
+
+---
+
+### 7. CI Integration
+
+Callograph can fail CI if impure functions are detected.
+
+```
+callograph analyze --fail-on-impure
+```
+
+This allows enforcement of architectural constraints.
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev callograph
+```
+
+Or use directly:
+
+```bash
+npx callograph analyze
+```
+
+---
+
+## Usage
+
+Analyze project based on `tsconfig.json`:
+
+```bash
+callograph analyze
+```
+
+JSON output:
+
+```bash
+callograph analyze --json
+```
+
+Fail CI if impurity detected:
+
+```bash
+callograph analyze --fail-on-impure
+```
+
+Export DOT graph:
+
+```bash
+callograph analyze --dot
+```
+
+---
+
+## Architecture
+
+Callograph uses:
+
+* TypeScript Compiler API
+* Program-level symbol resolution
+* TypeChecker-based call resolution
+* AST traversal via `ts.forEachChild`
+* Impurity propagation via call graph traversal
+
+Pipeline:
+
+```
+Load tsconfig
+↓
+Create Program
+↓
+Extract function symbols
+↓
+Build call graph
+↓
+Detect side effects
+↓
+Propagate impurity
+↓
+Report results
+```
+
+---
+
+## Design Philosophy
+
+Callograph does not attempt perfect purity inference.
+It aims to provide practical, high-signal diagnostics with minimal noise.
+
+It prioritizes:
+
+* Deterministic analysis
+* CI compatibility
+* Clear reasoning in output
+* Minimal false positives
+* Performance (<2s on mid-sized codebases)
+
+---
+
+## Limitations (v0.1.0)
+
+* Dynamic runtime dispatch cannot always be resolved.
+* Higher-order functions are partially supported.
+* Deep framework-specific analysis is not included.
+* No IDE integration yet.
+
+---
+
+## Roadmap
+
+* Shared mutable singleton detection
+* Closure-captured state analysis
+* Circular call detection
+* Effect scoring per module
+* Interactive HTML graph visualization
+* GitHub PR comment bot
+* Monorepo support with project references
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+* Open an issue to discuss architecture changes.
+* Keep changes deterministic and type-safe.
+* Add tests for new analysis rules.
+
+---
+
+## Vision
+
+Callograph aims to become:
+
+> A structural analysis tool that gives engineers clarity over side effects, purity, and call relationships in large TypeScript systems.
+
+---

package/dist/index.cjs

@@ -0,0 +1,30 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  version: () => version
+});
+module.exports = __toCommonJS(index_exports);
+var version = "0.0.1";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  version
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const version = \"0.0.1\";"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,UAAU;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,3 @@
+declare const version = "0.0.1";
+
+export { version };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const version = "0.0.1";
+
+export { version };

package/dist/index.js

@@ -0,0 +1,6 @@
+// src/index.ts
+var version = "0.0.1";
+export {
+  version
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const version = \"0.0.1\";"],"mappings":";AAAO,IAAM,UAAU;","names":[]}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "callograph",
+  "version": "0.0.1",
+  "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"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}