Metadata-Version: 2.4
Name: sinew
Version: 1.0.2
Summary: Structural dependency graph for codebases - the memory layer for developers and AI agents
Author: Sinew Team
License: MIT
Keywords: ai-agents,code-analysis,code-map,dependency-graph,developer-tools,static-analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: mcp>=1.0
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: toml>=0.10
Requires-Dist: tree-sitter>=0.21
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sinew 🗺️

> **The structural memory of your codebase. For developers. For AI agents. Forever.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Languages](https://img.shields.io/badge/languages-10-blue)]()
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)]()

---

Sinew is a CLI tool that converts any codebase into a living, machine-readable dependency graph — a structural map of how every file, module, class, function, variable, and relationship in your project connects.

It is not a documentation tool. It is not a search tool. It is not a visualization tool.

It is the **ground truth** of your codebase's structure — always current, always queryable, readable by humans and AI agents equally.

The output is a JSON graph that powers:

- A **2D architectural map** — layered topology of your system
- A **spider-web dependency graph** — every relationship visualized as a dense, interactive web
- A **developer CLI** — query, trace, search, and understand any part of your codebase in seconds
- An **agent infrastructure layer** — structural context, hallucination guards, territory maps, and session memory for any AI coding agent

---

## Why Sinew Exists

Modern repositories contain thousands of files and deeply tangled dependencies. The questions developers and AI agents ask most often have no fast answer:

- Where is this function first defined?
- What breaks if I change this variable?
- Which files import this module?
- Has this function been duplicated somewhere?
- What is the full call chain for this feature?
- Has an agent touched this file already?
- What does this codebase's architecture actually look like?

Every existing tool answers these by re-scanning the codebase on demand — which is slow, incomplete, and stateless. Sinew pre-computes the answer to all of them once, stores it as a structural graph, and makes every answer instant.

For AI agents specifically, the problem is deeper. Agents forget everything between sessions. They hallucinate functions that don't exist. They violate architecture rules they were never told. They duplicate code that already exists three files away. They create merge conflicts with other agents running in parallel. Sinew is the structural layer that eliminates all of these failures — not by making agents smarter, but by giving them the structural knowledge they have no other way to access.

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [CLI Reference](#cli-reference)
- [Developer Features](#developer-features)
- [Agent Features](#agent-features)
- [sinew Schema](#sinew-schema)
- [Architecture Constitution](#architecture-constitution)
- [Configuration](#configuration)
- [JSON Graph Schema](#json-graph-schema)
- [Language Support](#language-support)
- [MCP Server](#mcp-server)
- [Integrations](#integrations)
- [Architecture](#architecture)
- [Roadmap](#roadmap)

---

## Installation

```bash
pip install sinew
```

Verify:

```bash
sinew --version
```

---

## Quick Start

Build a graph from any repository:

```bash
sinew build ./my-project
```

This scans the repository, parses all supported source files, and produces `sinew.json` in the project root.

Explore it immediately:

```bash
sinew web sinew.json      # opens spider-web graph in browser
sinew map sinew.json      # opens 2D architectural map in browser
sinew stats                   # prints repository health summary
```

Ask your first structural question:

```bash
sinew trace login             # full call chain from login
sinew impact verify_password  # what breaks if this changes
sinew search db_conn          # where is this used
```

---

## Core Concepts

### The Graph

Everything Sinew does derives from a single source of truth: the dependency graph. The graph is a collection of **nodes** (every code object — files, modules, classes, functions, variables) and **edges** (every relationship — calls, imports, inheritance, data flow).

The graph is stored as `sinew.json`. Every CLI command, every visualization, every agent feature, every query runs against this file. You never re-parse the codebase for a query. The graph already knows.

### Nodes

A node represents any named code object:

| Node Type | Examples |
|---|---|
| `file` | `auth/login.py`, `utils/crypto.js` |
| `module` | `database`, `os`, `express` |
| `class` | `AuthService`, `UserModel` |
| `function` | `verify_password`, `get_user` |
| `method` | `AuthService.login` |
| `variable` | `db_conn`, `MAX_RETRIES` |
| `interface` | `IAuthProvider` |
| `struct` | `UserConfig` |

### Edges

An edge represents a directional relationship between two nodes:

| Edge Type | Meaning |
|---|---|
| `calls` | Function A calls function B |
| `imports` | File A imports module B |
| `inherits` | Class A inherits from class B |
| `implements` | Class A implements interface B |
| `instantiates` | Code creates an instance of class B |
| `reads` | Code reads variable B |
| `writes` | Code writes variable B |
| `returns` | Function A returns type B |

Every edge carries a `confidence` score between 0 and 1. In dynamic languages like Python and JavaScript, some edges cannot be proven with certainty — an argument typed as `handler` could be any object at runtime. Sinew marks these inferred edges with lower confidence so you always know what is structural fact versus structural inference.

### Origin

Every node carries its **origin** — the exact file and line number where it was first defined, not where it was imported or re-exported. This eliminates confusion in large codebases where symbols travel through many files before being used.

### sinew Schema

An optional inline annotation system for enriching the graph with human intent. Developers leave structured notes directly in source code that Sinew reads into graph nodes. Details in the [sinew Schema](#sinew-schema) section.

---

## CLI Reference

### Build Commands

| Command | Description |
|---|---|
| `sinew build <path>` | Build full repository graph |
| `sinew build <file> --file` | Build graph for a single file only |
| `sinew build <path> --output <file>` | Custom output path for JSON |
| `sinew build <path> --ignore <paths>` | Ignore specific files or folders |
| `sinew watch <path>` | Watch mode — live rebuild on file changes |

### Visualization Commands

| Command | Description |
|---|---|
| `sinew map <json>` | Open 2D architectural layer map in browser |
| `sinew web <json>` | Open spider-web dependency graph in browser |
| `sinew web <json> --heatmap activity` | Web with runtime activity overlay |
| `sinew web <json> --heatmap coverage` | Web with test coverage overlay |
| `sinew web <json> --heatmap modification` | Web with git modification recency overlay |

### Query Commands

| Command | Description |
|---|---|
| `sinew search <symbol>` | Search graph and return matching nodes + subgraph |
| `sinew search <symbol> --save <file>` | Save temporary search map as JSON |
| `sinew trace <symbol>` | Trace full execution call chain |
| `sinew reverse <symbol>` | Show everything that depends on this symbol |
| `sinew impact <symbol>` | Blast radius analysis before a change |
| `sinew lineage <variable>` | Trace full birth-to-death path of a variable |
| `sinew origin <symbol>` | Find first definition of any symbol |
| `sinew explain <file>` | Graph-generated plain-language summary of a file |
| `sinew query "<expression>"` | Structured query against the graph |

### Listing Commands

| Command | Description |
|---|---|
| `sinew list functions` | All functions with file, line, origin |
| `sinew list classes` | All classes |
| `sinew list variables` | All variables |
| `sinew list modules` | All modules |
| `sinew list --group <name>` | All symbols tagged with sinew Schema group |
| `sinew list --critical` | All symbols marked `critical` in sinew Schema |
| `sinew list --deprecated` | All symbols marked `deprecated` |
| `sinew module <name>` | Full usage details for a module |

### Analysis Commands

| Command | Description |
|---|---|
| `sinew stats` | Full repository health metrics |
| `sinew score` | Structural debt score with trend |
| `sinew dead` | All unused symbols |
| `sinew phantoms` | All imported-but-never-used symbols |
| `sinew hotspots` | High-coupling nodes — architectural risk |
| `sinew clusters` | Auto-detected architectural domains |
| `sinew ownership` | Per-symbol ownership and bus factor |
| `sinew diff <a.json> <b.json>` | Structural diff between two graph snapshots |
| `sinew audit --since last-commit` | Structural audit of recent AI-generated code |
| `sinew review --base <branch> --head <branch>` | PR structural impact report |

### Snapshot Commands

| Command | Description |
|---|---|
| `sinew snapshot --tag <name>` | Save a named graph snapshot |
| `sinew diff --tag <a> --tag <b>` | Compare two named snapshots |
| `sinew timeline` | Show architectural history across all snapshots |

### Agent Commands

| Command | Description |
|---|---|
| `sinew agent-boot --task "<description>"` | Generate task-scoped agent boot payload |
| `sinew agent-boot --task "<description>" --resume <session>` | Resume a previous agent session |
| `sinew context "<task>" --tokens <n>` | Precision-scoped context payload within token budget |
| `sinew verify <file>` | Hallucination check — validate agent output against graph |
| `sinew preflight --changes "<description>"` | Risk report before any agent edit |
| `sinew territory claim --agent <id> --scope <path> --task "<description>"` | Claim territory for multi-agent coordination |
| `sinew territory status` | Show all active agent territories |
| `sinew territory release --agent <id>` | Release territory on task completion |
| `sinew agent-log mistake --node <id> --description "<text>" --severity <level>` | Attach a mistake memory to a graph node |
| `sinew session-snapshot save --session <id> --summary "<text>"` | Save agent session continuity state |
| `sinew agent-export` | Export full agent-optimized graph |

### Export Commands

| Command | Description |
|---|---|
| `sinew export --format dot` | Graphviz DOT format |
| `sinew export --format graphml` | GraphML for Gephi / yEd |
| `sinew export --format csv` | nodes.csv + edges.csv |
| `sinew export --format markdown` | Human-readable structural summary |
| `sinew tour --audience <type>` | Generate guided onboarding tour |

---

## Developer Features

### File-Specific sinew

Generate a graph for a single file without scanning the full repository. Useful for focused analysis, parser testing, or isolating a single module.

```bash
sinew build ./auth/login.py --file
```

### Origin Tracking

Every symbol in the graph carries its true first-definition location — the exact file and line where it was created, not where it was imported, re-exported, or re-assigned downstream. When a symbol travels through dozens of files, the origin tells you where it was born.

```json
{
  "id": "auth.verify_password",
  "type": "function",
  "origin": { "file": "auth/security.py", "line": 42 }
}
```

### Module Import Tracking

Sinew tracks the complete import chain for every module and symbol — which files import it, which specific symbols each file pulls from it, and the full usage locations of each imported symbol.

```bash
sinew module database
```

```
Module: database
─────────────────────────────────────────────
get_user        → auth.py (line 14), admin.py (line 8)
db_conn         → auth.py (line 22), session.py (line 11)
create_record   → records.py (line 5)
─────────────────────────────────────────────
Imported by 6 files. Used in 14 locations.
```

### Impact Analysis

Before modifying any symbol, evaluate its full blast radius — not just direct callers, but the complete transitive dependency chain across all files and modules.

```bash
sinew impact verify_password
```

```
Symbol         : verify_password
Risk           : HIGH
─────────────────────────────────────────────
Direct callers      : login, admin_login, reset_flow
Indirect chain      : token_check → reset_flow → verify_password
Affected functions  : 17
Affected files      : 6
Affected modules    : 3
Dependency depth    : 4 levels
Test coverage       : 4 of 17 callers have tests ⚠
Frozen downstream   : 0
Agent warnings      : 1
─────────────────────────────────────────────
Recommendation: 13 callers have no test coverage. Add tests before changing signature.
```

### Execution Tracing

Trace the complete call chain from any entry point, following every branch of execution across files and modules.

```bash
sinew trace login
```

```
login
  → verify_password
      → database.get_user
          → redis_cache.fetch
      → hash_password
  → session.create
      → token.generate
```

### Variable Lineage

Trace the complete life of any variable from first assignment through every read, write, pass, and mutation across every file it touches.

```bash
sinew lineage db_conn
```

```
db_conn
  born     → config.py line 12 (assigned from env)
  passed   → auth.py line 34 (constructor argument)
  read     → auth.py line 41 (used in query)
  passed   → session.py line 19 (argument to create_session)
  mutated  → session.py line 27 (reassigned to pool connection)
  dies     → session.py line 89 (out of scope)
```

### Graph Search and Temporary Search Maps

Search the graph for any symbol and receive a filtered subgraph — a temporary search map — showing only the nodes and edges connected to that symbol. Temporary maps can be saved and shared without affecting the main graph.

```bash
sinew search verify_password
sinew search verify_password --save search_verify.json
```

### sinew Query Language

Query the graph directly with structured expressions for precise filtering that simple search cannot achieve.

```bash
sinew query "calls(verify_password) AND file(auth.*)"
sinew query "type=function AND callers > 10"
sinew query "imports(database) AND NOT has_tests"
sinew query "confidence < 0.75 AND type=calls"
sinew query "modified_after(2026-01-01) AND hotspot=true"
```

Queries run against the JSON graph. No re-parsing. Instant results.

### `sinew explain`

The graph narrates any file to you in plain language — not by reading the code, but by analysing the node's structural properties in the graph.

```bash
sinew explain auth/login.py
```

```
auth/login.py
─────────────────────────────────────────────
Centrality     : HIGH — imported by 11 other files
Outgoing deps  : 4 modules (database, session, cache, config)
Most-called fn : verify_password (17 callers)
Dead code      : 2 functions with no callers
Circular deps  : 1 (auth ↔ session)
Confidence     : 3 edges below 0.75 (dynamic dispatch detected)
Bus factor     : 1 (Raj is sole knowledge owner) ⚠
Agent warnings : 1 on verify_password
─────────────────────────────────────────────
```

### Dead Code and Phantom Detection

Dead code — symbols defined but never called. Phantoms — symbols imported but never used within the importing file. Both add noise, slow parsers, and mislead agents.

```bash
sinew dead
sinew phantoms
```

### Hotspot Detection

Nodes with unusually high in-degree are silent architectural risks — functions called by many callers are single points of failure.

```bash
sinew hotspots
```

```
verify_password    → 17 callers    ⚠ HIGH COUPLING
db_conn            → 34 usages     ⚠ CRITICAL DEPENDENCY
config.load        → 28 callers    ⚠ HIGH COUPLING
```

### Cluster Auto-Detection

The graph builder automatically identifies natural architectural domains — groups of nodes that are densely connected internally and loosely connected externally — without requiring any manual labelling.

```bash
sinew clusters
```

```
Cluster 1 (12 files, 84 nodes)  — likely: authentication
Cluster 2 (7 files, 43 nodes)   — likely: database layer
Cluster 3 (19 files, 201 nodes) — likely: API routing
```

### Structural Debt Score

Technical debt expressed as a number, not a feeling — with trend tracking across builds so teams can see whether the codebase is improving or degrading over time.

```bash
sinew score
```

```
Sinew Structural Score : 68 / 100

Coupling      : 71/100  (3 modules with > 15 dependents)
Cohesion      : 83/100
Circularity   : 55/100  (4 circular dependency chains)
Testability   : 72/100  (19% of hotspot functions untested)
Dead code     : 61/100  (231 unused symbols)
Documentation : 45/100  (67% of public functions without notes)

Trend : ↓ dropped 4 points in the last 30 days
Cause : circular dependencies added in recent PRs
```

### Bus Factor and Ownership

By reading git history alongside the graph, Sinew calculates the bus factor of every node — how many developers need to leave before that piece of code has no knowledgeable owner.

```bash
sinew ownership
```

```
verify_password    → 1 owner (Raj)          BUS FACTOR: 1 ⚠ CRITICAL
auth cluster       → 2 owners (Raj, Priya)  BUS FACTOR: 2 ⚠
payment module     → 4 owners               BUS FACTOR: 4 ✓

Highest risk departure : Raj (sole owner of 14 nodes)
```

### PR Structural Review

```bash
sinew review --base main --head feature/password-reset
```

```
Sinew Structural Review
─────────────────────────────────────────────
Impact level           : MEDIUM
New functions          : 4
Removed functions      : 1
Hotspot nodes touched  : 2 (verify_password, session.create)
Circular deps added    : 1 ⚠
Untested new code      : 3 functions
Dead code introduced   : 0
Confidence degraded    : 4 edges now below 0.75

Action required: Review circular dependency between auth ↔ reset_service before merging.
─────────────────────────────────────────────
```

### AI Session Audit

After any AI coding session, audit the structural changes for violations, duplications, and regressions before they make it into a commit.

```bash
sinew audit --since last-commit
```

```
AI session audit
─────────────────────────────────────────────
Duplicate logic detected    : 3 functions already exist elsewhere
Architecture violations     : auth layer calling db directly (2 cases)
Naming inconsistencies      : camelCase in 4 files (project uses snake_case)
New circular dependencies   : 1 (auth ↔ session) ⚠
Dead code added             : 2 functions never called
Confidence warnings         : 6 edges below 0.75
─────────────────────────────────────────────
Estimated tech debt added   : HIGH
```

### Guided Onboarding Tour

Generate a curated walkthrough of any codebase that takes a new developer from zero to architectural understanding in under an hour.

```bash
sinew tour ./repo --audience new-developer
```

Produces `TOUR.md` or an interactive web sequence walking through entry points, core architecture, data flow, isolated clusters, and known complexity zones — all derived automatically from the graph.

### Heatmap Layers

Overlay different data dimensions onto the web or map visualization to reveal what structure alone cannot show.

```bash
sinew web sinew.json --heatmap activity     # runtime call frequency
sinew web sinew.json --heatmap coverage     # test coverage
sinew web sinew.json --heatmap modification # git modification recency
```

### Graph Snapshots and Timeline

Capture named snapshots of the graph at any point in time and compare them to understand how architecture evolved.

```bash
sinew snapshot --tag "before-refactor"
sinew snapshot --tag "after-refactor"
sinew diff --tag before-refactor after-refactor
sinew timeline
```

### Watch Mode

```bash
sinew watch ./repo
```

Monitors the filesystem and rebuilds only the affected portions of the graph as files change. The web and map views auto-refresh. The graph stays current during active development without a full rebuild.

---

## Agent Features

Sinew is agent-native infrastructure. Every feature in this section exists because AI coding agents face problems that are structurally different from what human developers face — and that require structural solutions, not prompting tricks.

### Agent Boot Payload

The most common agent failure: starting a session with no knowledge of the codebase's conventions, existing functions, architectural decisions, or past mistakes. Sinew generates a task-scoped boot payload that gives any agent complete structural orientation in under 1,000 tokens.

```bash
sinew agent-boot --task "add password reset to auth module"
```

Output `boot.json`:

```json
{
  "task_scope": {
    "relevant_files": ["auth/login.py", "auth/security.py", "models/user.py"],
    "entry_points": ["auth.login", "auth.logout"],
    "hotspots_in_scope": ["verify_password — 17 callers, HIGH RISK"]
  },
  "conventions": {
    "naming": "snake_case functions, PascalCase classes",
    "error_handling": "raise AuthError — never return None for auth failures",
    "patterns": ["no direct db calls from auth layer", "dependency injection via constructor"]
  },
  "what_already_exists": {
    "do_not_recreate": [
      "get_user — database/queries.py line 42",
      "hash_password — auth/security.py line 18"
    ]
  },
  "past_mistakes": [
    "verify_password was inlined into login on 2026-01-09 — broke 17 callers, reverted",
    "Circular dep introduced between auth ↔ session on 2026-02-14 — reverted"
  ],
  "frozen_zones": [
    "auth/legacy_sso.py — vendor contract, do not modify"
  ],
  "confidence_warnings": [
    "auth.middleware — 3 edges below 0.75, dynamic dispatch, tread carefully"
  ]
}
```

Every piece of this is derived entirely from the live graph. Nothing needs to be written manually. The agent loads this once, and it already knows the territory — before opening a single file.

### Precision Context Budgeting

More context does not always mean better agent output. Studies show agents perform worse, not better, when flooded with irrelevant context. Sinew generates a precision-scoped context payload calibrated to an exact token budget — containing only the structural information the agent actually needs for the stated task.

```bash
sinew context "fix bug in verify_password where locked accounts still authenticate" --tokens 4000
```

Sinew traverses the graph to determine the minimum structural knowledge needed — the 3 relevant files, 2 affected callers, the `User.is_locked` field origin, the test file, and any sinew Schema notes — and outputs exactly that. No noise. No irrelevant modules. Maximum agent focus.

### Hallucination Guard

Before an agent writes any file, validate its proposed output against the live graph. Sinew checks every function call, import, class reference, and method call for structural existence — in under a second, without executing any code.

```bash
sinew verify agent_output.py
```

```
Hallucination check
─────────────────────────────────────────────
auth.get_user_by_email     → NOT FOUND ⚠
                              Did you mean: database.get_user (takes username, not email)
session.create_secure()    → EXISTS ✓
User.is_locked             → EXISTS ✓
User.lock_account()        → NOT FOUND ⚠
                              User has: User.set_active(False) — same intent, different API
─────────────────────────────────────────────
2 hallucinations detected. Blocked before write.
```

The agent never runs. The developer never spends 20 minutes debugging why the agent's code throws `AttributeError`.

### Dependency Pre-Flight

Before any agent modification, generate a machine-readable risk report that the agent can incorporate into its plan. The agent receives structural risk information it had no other way to access.

```bash
sinew preflight --changes "modify verify_password signature to add mfa_token param"
```

```json
{
  "risk": "HIGH",
  "callers_affected": 17,
  "test_coverage_on_callers": "4 of 17 callers have tests",
  "frozen_nodes_touched": 0,
  "circular_deps_introduced": 0,
  "agent_warnings_on_node": 1,
  "confidence_warnings": 2,
  "recommendation": "13 untested callers. Add tests before changing signature."
}
```

### Multi-Agent Territory Map

When multiple agents work on the same codebase simultaneously, they have no shared awareness of each other. Sinew is the shared ground truth — a territory layer that all agents talk to so none collide.

```bash
sinew territory claim --agent "agent-auth" --scope "auth/" --task "refactor verify_password"
sinew territory claim --agent "agent-reset" --scope "auth/reset.py" --task "add password reset"
```

```
Territory conflict detected
─────────────────────────────────────────────
agent-auth    claims: auth/           (touches verify_password)
agent-reset   claims: auth/reset.py   (imports verify_password)

Shared dependency : verify_password
Resolution        : agent-reset should wait for agent-auth to complete,
                    or agent-auth should mark verify_password interface stable first.
─────────────────────────────────────────────
```

```bash
sinew territory status       # see all active agent territories
sinew territory release --agent "agent-auth"  # release on completion
```

### Mistake Memory

When an agent makes a mistake and a developer reverts it, that knowledge disappears. The next session — same agent, different agent — makes the same mistake again. Sinew attaches mistake memories permanently to graph nodes. Every future agent boot payload touching that node includes the warning automatically.

```bash
sinew agent-log mistake \
  --node "auth.verify_password" \
  --description "inlining this function breaks 17 callers — always keep it separate" \
  --severity high
```

The mistake is made once. Never again. Across all agents, all sessions, all time.

### Session Continuity Snapshots

When a long-horizon agent session ends, everything it learned — which files it read, which decisions it made, which dead ends it hit — evaporates. Sinew saves a continuity snapshot so the next session resumes with full context instead of starting from zero.

```bash
# At end of session
sinew session-snapshot save \
  --session "auth-refactor-session-1" \
  --summary "Refactored verify_password. Did not touch session.py yet — needs mfa_token propagated. Dead end: middleware approach creates circular dep with auth."

# At start of next session
sinew agent-boot --task "continue auth-refactor" --resume "auth-refactor-session-1"
```

No handoff document. No human memory required. The graph carries the session state forward.

### Agent Export

Export a complete agent-optimized representation of the repository — a single JSON structured for maximum agent utility.

```bash
sinew agent-export
```

Output `agent_graph.json`:

```json
{
  "function_index": { ... },
  "call_graph": { ... },
  "file_index": { ... },
  "dependency_index": { ... },
  "reverse_index": { ... },
  "origin_index": { ... },
  "sinew_notes": { ... },
  "frozen_zones": { ... },
  "mistake_memory": { ... },
  "architecture_constitution": { ... }
}
```

Any AI system can consume this file to understand full repository structure without scanning a single source file.

---

## sinew Schema

sinew Schema is Sinew's inline annotation system. Developers embed structured notes directly in source code to enrich the graph with human intent — for other developers, for AI agents, and for graph queries.

sinew Schema annotations use the `# @sinew:` prefix and appear as dedicated fields on graph nodes. They are distinct from regular comments and are written intentionally for graph consumers.

### Variables

```python
db_conn = get_connection()  # @sinew: note="primary db connection, do not reassign" critical=true
MAX_RETRIES = 3             # @sinew: note="tuned for production timeout budget" group="config"
temp_buffer = []            # @sinew: ignore
```

### Functions

```python
def verify_password(user, password):
    # @sinew: note="core auth primitive, 17 callers — never inline" critical=true owner="platform-team"
```

### Classes

```python
class AuthService:
    # @sinew: note="handles all authentication" group="auth" owner="platform-team"
```

### Frozen Zones

Marks a node as off-limits for any modification. Enforced in agent boot payloads, hallucination checks, and architecture constitution validation.

```python
class LegacySSOHandler:
    # @sinew: frozen reason="vendor contract" since="2024-03-01" owner="platform-team"
```

```python
PAYMENT_GATEWAY_VERSION = "2.1.4"  # @sinew: frozen reason="PCI-DSS certified, changes require re-audit"
```

### Supported Annotation Fields

| Field | Type | Description |
|---|---|---|
| `note` | string | Human-readable description for graph consumers |
| `critical` | bool | High-weight node — highlighted in visualizations and included in all agent payloads |
| `frozen` | bool/string | Off-limits for modification — enforced for agents |
| `reason` | string | Reason for frozen status |
| `deprecated` | bool | Marks node as deprecated in listings and agent payloads |
| `group` | string | Architectural group name for cluster queries |
| `owner` | string | Team or developer responsible for this symbol |
| `since` | date | Date annotation was added |
| `ignore` | bool | Exclude node from graph entirely |

### Querying sinew Schema

```bash
sinew list --critical                    # all critical symbols
sinew list --deprecated                  # all deprecated symbols
sinew list --group auth                  # all symbols in auth group
sinew list --owner platform-team         # all symbols owned by platform-team
sinew query "frozen=true"                # all frozen zones
```

---

## Architecture Constitution

The architecture constitution defines structural rules for your codebase that are machine-enforced on every build and on every agent output. Rules live in `.sinewconstitution` at the repository root and are committed alongside code.

### Example `.sinewconstitution`

```toml
[[rule]]
name        = "no-auth-to-db-direct"
description = "Auth layer must not call database layer directly. Use service layer."
forbid_edge = { from_pattern = "auth.*", to_pattern = "database.*", type = "calls" }
severity    = "error"

[[rule]]
name        = "no-circular-deps"
description = "No circular dependencies anywhere in the codebase."
forbid      = "circular_dependency"
severity    = "error"

[[rule]]
name        = "hotspot-functions-must-be-tested"
description = "Any function with more than 10 callers must have at least one test."
require     = "test_coverage"
when        = "callers > 10"
severity    = "error"

[[rule]]
name        = "services-must-be-tested"
description = "Every public function in services/ must have at least one test."
require     = "test_coverage"
scope       = "services/**"
severity    = "warning"

[[rule]]
name        = "no-god-files"
description = "No file may have more than 15 outgoing dependency edges."
max_outgoing_edges = 15
severity    = "warning"

[[rule]]
name        = "no-low-confidence-in-core"
description = "No inferred edges below 0.80 confidence in the auth or payment clusters."
max_confidence = 0.80
scope       = ["auth/**", "payment/**"]
severity    = "warning"
```

### Constitution Enforcement

Constitution violations are reported on every `sinew build`, every `sinew verify` on agent output, and every `sinew review` on a pull request. No agent violates architecture rules silently. No developer merges a constitution violation without knowing it.

```bash
sinew build ./repo
```

```
Constitution violations
─────────────────────────────────────────────
[error]   no-auth-to-db-direct    auth/login.py line 34 — direct call to database.get_user
[error]   no-circular-deps        auth ↔ session — circular dependency introduced
[warning] services-must-be-tested services/reset.py — 2 public functions with no tests
─────────────────────────────────────────────
Build completed with violations. Fix errors before committing.
```

---

## Configuration

Sinew is configured via `.sinewconfig` at the repository root. This file is committed to the repository so every developer, every agent, and every CI run produces identical output.

### `.sinewconfig`

```toml
[sinew]
languages             = ["python", "typescript", "javascript"]
output                = "./sinew/sinew.json"
confidence_threshold  = 0.75
entry_points          = ["main.py", "app/server.py"]

[sinew.ignore]
directories = [
  "__pycache__", ".venv", "venv", "env",
  "node_modules", ".git", "dist", "build",
  ".next", ".nuxt", ".pytest_cache", ".mypy_cache",
  "*.egg-info", "coverage"
]
files = ["*.min.js", "*.bundle.js", "config/secret.py"]
custom = ["tests/fixtures/", "scripts/legacy/"]

[sinew.schema]
require_annotations   = false
critical_symbols      = ["verify_password", "db_conn", "payment_gateway"]

[sinew.agents]
boot_token_budget     = 800
context_token_budget  = 4000
mistake_memory        = true
territory_map         = true
session_snapshots     = true

[sinew.constitution]
file                  = ".sinewconstitution"
enforce_on_build      = true
enforce_on_agent      = true
block_on_error        = false
```

### `.sinewignore`

For simpler ignore rules, Sinew also accepts a `.sinewignore` file using identical syntax to `.gitignore`.

```
tests/
scripts/legacy/
docs/
*.min.js
config/secret.py
build/
```

---

## JSON Graph Schema

### Node

```json
{
  "id": "auth.verify_password",
  "type": "function",
  "file": "auth/security.py",
  "line": 42,
  "origin": {
    "file": "auth/security.py",
    "line": 42
  },
  "notes": "Docstring or extracted comment attached here",
  "sinew_note": "core auth primitive, 17 callers — never inline",
  "sinew_critical": true,
  "sinew_frozen": false,
  "sinew_owner": "platform-team",
  "sinew_group": "auth",
  "agent_warnings": [
    {
      "description": "inlining this function breaks 17 callers",
      "severity": "high",
      "logged": "2026-01-09"
    }
  ],
  "callers": 17,
  "has_tests": true,
  "confidence_min": 0.91,
  "bus_factor": 1
}
```

### Edge

```json
{
  "from": "auth.login",
  "to": "auth.verify_password",
  "type": "calls",
  "file": "auth/login.py",
  "line": 55,
  "confidence": 0.97
}
```

---

## Language Support

Sinew uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for all language parsing, providing reliable AST access across every supported language.

### Phase 1

| Language | Parser | Status |
|---|---|---|
| Python | `tree-sitter-python` + `ast` fallback | ✅ Available |
| JavaScript | `tree-sitter-javascript` | ✅ Available |
| TypeScript | `tree-sitter-typescript` | ✅ Available |

### Phase 2

| Language | Parser | Status |
|---|---|---|
| Java | `tree-sitter-java` | 🔜 Planned |
| Go | `tree-sitter-go` | 🔜 Planned |
| Rust | `tree-sitter-rust` | 🔜 Planned |

### Phase 3

| Language | Parser | Status |
|---|---|---|
| C++ | `tree-sitter-cpp` | 🔜 Planned |
| C# | `tree-sitter-c-sharp` | 🔜 Planned |
| PHP | `tree-sitter-php` | 🔜 Planned |
| Swift | `tree-sitter-swift` | 🔜 Planned |

All parsers extract the same symbol and relationship types and produce the same intermediate schema, making the graph fully language-agnostic.

---

## MCP Server

Sinew exposes all graph capabilities as a native MCP server, making it directly consumable by any MCP-compatible agent tool — Cursor, Claude Code, Windsurf, and others.

### Starting the server

```bash
sinew serve --port 2048
```

### Connecting in your agent tool

```json
{
  "mcp_servers": [
    {
      "name": "sinew",
      "url": "http://localhost:2048/mcp"
    }
  ]
}
```

### Available MCP Tools

Once connected, agents can call Sinew tools natively during their reasoning without any CLI commands.

| Tool | Description |
|---|---|
| `sinew.get_boot(task)` | Task-scoped boot payload |
| `sinew.get_context(task, tokens)` | Precision-scoped context within token budget |
| `sinew.check_exists(symbol)` | Hallucination guard — instant structural existence check |
| `sinew.get_impact(symbol)` | Blast radius report |
| `sinew.get_preflight(changes)` | Risk report before any edit |
| `sinew.claim_territory(agent, scope, task)` | Multi-agent conflict prevention |
| `sinew.release_territory(agent)` | Release on task completion |
| `sinew.log_mistake(node, description, severity)` | Attach mistake memory to graph node |
| `sinew.verify_output(code)` | Constitution + hallucination check on agent output |
| `sinew.search(symbol)` | Graph search from within agent |
| `sinew.trace(symbol)` | Call chain from within agent |
| `sinew.get_impact(symbol)` | Impact analysis from within agent |

---

## Integrations

### VS Code Extension

The Sinew VS Code extension shows your structural position in the graph as you navigate files — callers, dependencies, hotspot status, confidence warnings, and sinew Schema notes — without running any command.

Install: search `Sinew` in the VS Code marketplace.

### Git Hook

The included git hook automatically rebuilds the affected graph portions on every commit and appends a structural summary to the commit message.

```bash
sinew install-hook
```

### CI Integration

Add structural validation to any CI pipeline.

```yaml
# GitHub Actions example
- name: Sinew structural check
  run: |
    sinew build ./
    sinew score --min 60
    sinew audit --since last-commit --fail-on-violations
```

---

## Architecture

```
CLI Entry
    │
    ▼
File Scanner
    │  (respects .sinewignore, .sinewconfig, auto-ignores cache/venv/node_modules)
    ▼
Language Detector
    │
    ▼
Tree-sitter Parser  (per language, parallel)
    │
    ▼
AST Traversal
    │
    ▼
Symbol Extractor
    │   ├─ Functions, classes, variables, interfaces
    │   ├─ Imports and exports
    │   ├─ Conditionals and try/except blocks
    │   ├─ Comments and docstrings → notes
    │   └─ sinew Schema annotations → sinew_* fields
    ▼
Relationship Extractor
    │   ├─ Call graph (with confidence scoring)
    │   ├─ Import graph
    │   ├─ Inheritance graph
    │   └─ Data flow graph
    ▼
Origin Resolver
    │
    ▼
Reverse Index Builder
    │
    ▼
Constitution Validator
    │
    ▼
Graph Builder → sinew.json
    │
    ├── Map Renderer          (2D architectural layout)
    ├── Web Renderer          (spider-web dependency graph)
    ├── Agent Exporter        (agent_graph.json)
    └── MCP Server            (live tool access for agents)
```

### Project Structure

```
sinew/
├── cli/
│   └── main.py
├── core/
│   ├── scanner.py
│   ├── detector.py
│   ├── graph.py
│   ├── origin.py
│   ├── reverse_index.py
│   ├── confidence.py
│   └── constitution.py
├── parsers/
│   ├── base.py               (shared interface)
│   ├── python/parser.py
│   ├── javascript/parser.py
│   ├── typescript/parser.py
│   └── ...
├── schema/
│   ├── sinew_schema.py
│   └── node.py
├── renderers/
│   ├── map.py
│   └── web.py
├── agents/
│   ├── boot.py
│   ├── context.py
│   ├── territory.py
│   ├── verify.py
│   ├── preflight.py
│   ├── session.py
│   └── export.py
├── mcp/
│   └── server.py
├── exporters/
│   ├── dot.py
│   ├── graphml.py
│   ├── csv.py
│   └── markdown.py
└── tests/
```

---

## Roadmap

### Phase 1 — Core Engine
- Python parser and symbol extractor
- Graph builder and JSON schema
- Origin tracking and reverse index
- Confidence scoring on all edges
- Comments and docstrings as notes
- sinew Schema annotations
- Ignore rules and `.sinewconfig`
- CLI: `build`, `search`, `trace`, `impact`, `stats`, `dead`, `list`, `explain`
- Architecture constitution and validation

### Phase 2 — Multi-Language and Visualization
- JavaScript and TypeScript parsers
- Java and Go parsers
- Map renderer (2D architectural layout)
- Web renderer (spider-web dependency graph)
- Heatmap layers (activity, coverage, modification)
- Diff mode and snapshots
- PR structural review
- Watch mode
- VS Code extension

### Phase 3 — Agent Infrastructure
- Full agent feature suite
- MCP server
- Multi-agent territory map
- Mistake memory
- Session continuity snapshots
- Hallucination guard
- Architecture constitution enforcement on agents
- Rust, C++, C#, PHP, Swift parsers

### Phase 4 — Scale and Ecosystem
- 100,000+ file repository support with incremental parsing
- Multi-repo federation
- Runtime profile overlay
- CI/CD integration suite
- Structural debt score trending
- sinew Query Language full implementation
- Open graph schema standard

---

## License

MIT

---

*Sinew is the structural memory that codebases have always needed and never had — for developers navigating complexity, and for agents navigating blindly.*