scn-ts: Symbolic Context Notation for TypeScript & JavaScript

A hyper-efficient, language-agnostic representation of your codebase's structure, API, and inter-file relationships. Unlock unparalleled context for Large Language Models (LLMs) and advanced code analysis, using a fraction of the tokens.

🚀 Introduction

scn-ts is a powerful command-line interface (CLI) and programmatic API designed to extract the architectural essence of your TypeScript, JavaScript, JSX, and CSS projects. It transforms your raw source code into Symbolic Context Notation (SCN) – a highly compressed, human-readable, and machine-optimized format.

Built on top of the robust analysis engine, scn-ts provides:

• Extreme Token Efficiency: Represent complex code structures in a fraction of the tokens compared to raw source code.
• Comprehensive Structural Map: Understand classes, functions, variables, interfaces, HTML elements, and CSS rules.
• Inter-File Dependency Graphs: Clearly visualize how files and entities interact across your project.
• Rich Metadata: Qualifiers for public/private access, async/throw behavior, and even a heuristic for "pure" functions.
• Isomorphic: Browser & Node.js Support: Run analysis anywhere. Use the powerful CLI in your terminal or integrate the library directly into your web-based IDE or analysis tools.
• Language Agnostic Principles: While scn-ts focuses on JS/TS/JSX/CSS, the underlying SCN format is designed to unify concepts across any programming language.

SCN is the bridge between raw code and intelligent code assistants. It empowers LLMs to "see" your entire codebase's architecture, enabling them to generate more accurate, context-aware, and high-quality code.

🎯 The Problem: The "Context Chasm"

Large Language Models struggle with understanding large codebases. The core dilemma is the "Context Chasm":

• Too Little Code: LLMs hallucinate, misuse APIs, and miss critical connections between files and modules.
• Too Much Code: You hit token limits, incur high costs, and the LLM drowns in irrelevant implementation details, leading to slower, poorer responses.

Traditional representations like Abstract Syntax Trees (ASTs) are too verbose for project-wide context. They focus on every detail within a single file, not the relationships and high-level structure across many files.

SCN closes this chasm. It provides a compressed blueprint, revealing the graph of your project – which entity uses which, and which is used by which – at an unprecedented token-to-information ratio.

✨ How SCN-TS Works

scn-ts acts as a specialized serializer for the analysis engine.

1. File Discovery: scn-ts efficiently scans your project, respecting .gitignore and custom include/exclude patterns, to identify relevant source files.
2. Code Analysis (Tree-sitter): utilizes Tree-sitter, a high-performance parsing library, to build a detailed CodeGraph of your project. This graph contains nodes for files and all identified code entities (classes, functions, variables, etc.), along with edges representing dependencies (imports, calls, inheritance, JSX-CSS links).
3. Graph Ranking (Optional, but default): can apply ranking algorithms (like PageRank or Git commit frequency) to identify the most "important" files and symbols. While not directly used in the SCN output, this functionality is available via the underlying API.
4. SCN Serialization: This is where scn-ts shines. It traverses the CodeGraph generated by `` and translates it into the concise, symbolic SCN format, adhering strictly to the SCN Specification. It assigns unique, hierarchical IDs and applies specific symbols and qualifiers to represent meaning.

In essence: scn-ts = Powerful Code Analysis () + Ultra-Efficient Symbolic Representation (SCN Spec).

🌟 Key Features

1. Unified, Language-Agnostic Code Representation

SCN abstracts away language-specific syntax, presenting a unified view regardless of the underlying language.

• Symbols: Consistent symbols (◇ for containers, ~ for functions, @ for variables, ¶ for CSS rules, ⛶ for HTML elements) represent common programming concepts.
• Context: The format emphasizes what an entity is and how it relates to others, not its specific implementation details.

2. Deep Structural Analysis

scn-ts goes beyond simple file lists. It understands the internal structure of your files and represents:

• Classes, Interfaces, Structs (◇, {})
• Functions, Methods, Constructors (~)
• Variables, Properties, Fields (@)
• Enums, Type Aliases (☰, =:)
• HTML Elements and their attributes (⛶)
• CSS Rules and their semantic intents (¶, 📐, ✍, 💧)

3. Comprehensive Dependency Mapping

Visualize your project's architecture with clear dependency links:

• File-level Dependencies (->/<-): Shows which files import or are imported by others.
• Entity-level Dependencies (->/<-): Identifies which functions call which, which classes inherit from others, and even how JSX elements are styled by CSS rules.
• Hierarchical IDs: Unique IDs ((file_id.entity_id)) enable precise linking.

4. Rich Metadata & Qualifiers

SCN enriches symbols with crucial behavioral and visibility information:

• Access Modifiers: Public (+) or Private (-) for class members and exported entities.
• Asynchronous: Functions that are async (...).
• Error Handling: Functions that can throw exceptions (!).
• Pure Functions: A heuristic identifies functions without side effects (o).
• Type Signatures: Parameter types and return types are represented concisely with #.

5. Multi-Language Support

While scn-ts specifically targets JS/TS/JSX/CSS and HTML, the underlying `` engine supports a wide array of languages, making scn-ts extensible for future SCN generation from other ecosystems:

• JavaScript, TypeScript, TSX, JSX
• CSS
• Python
• Java
• C#, C, C++
• Go
• Rust
• PHP
• Ruby
• Solidity
• Swift
• Vue (basic script block parsing)

6. Hierarchical View with Indentation

SCN's structure uses indentation to naturally convey nesting and containment relationships within files (e.g., methods within classes, HTML elements within other HTML elements).

7. Extreme Token Efficiency

The most compelling feature for LLM integration. SCN drastically reduces the number of tokens required to represent a codebase's context, allowing LLMs to process much larger projects.

📦 Installation

To use scn-ts, ensure you have Node.js (or Bun) installed.

# Using npm
npm install -g scn-ts-core

# Using yarn
yarn global add scn-ts-core

# Using pnpm
pnpm install -g scn-ts-core

# Using Bun
bun install -g scn-ts

🚀 Usage

scn-ts can be used via its Command-Line Interface (CLI) or programmatically within your Node.js, Bun, or even browser applications.

CLI Usage

The scn-ts CLI offers a straightforward way to generate SCN maps from your terminal.

scn-ts [command] [options]

Commands:

• [globs...] (default): Analyze a repository by providing glob patterns.
• copy-wasm [destination]: Copy the necessary Tree-sitter WASM files to a specified directory for browser-based usage. The default destination is ./public/wasm.

Key Options:

• -o, --output <path>: Path to write the SCN output file. If omitted, the output is printed to stdout.
• -p, --project <path>: Path to your tsconfig.json file. This is crucial for correct TypeScript/JSX parsing.
• -c, --config <path>: Path to a custom config file (e.g., my-scn.js). Defaults to scn.config.js or scn.config.json.
• --max-workers <num>: Number of parallel workers for analysis. (Default: 1). Use higher values for faster analysis on multi-core machines.
• --watch: Watch files for changes and re-generate the SCN map automatically.
• -v, --version: Display the current version number.
• -h, --help: Display the help message.

CLI Examples

1. Generate SCN for all TypeScript files in src/ and print to console:

   scn-ts "src/**/*.ts"

2. Generate SCN for React components and save to context.scn:

   scn-ts "src/components/**/*.tsx" --output context.scn -p tsconfig.json

3. Prepare for browser usage by copying WASM files to your public directory:

   scn-ts copy-wasm ./public/wasm

4. Watch mode for continuous generation:

   scn-ts "src/**/*.ts" "src/**/*.tsx" --watch --output auto-update.scn

Configuration File (scn.config.js or scn.config.json)

For more complex configurations, scn-ts automatically looks for scn.config.js or scn.config.json in your project root.

scn.config.js example:

// scn.config.js
export default {
  // Glob patterns for files to include
  include: [
    'src/**/*.ts',
    'src/**/*.tsx',
  ],
  // Glob patterns for files to exclude
  exclude: [
    '**/*.test.ts',
    '**/node_modules/**',
  ],
  // Output file path (optional, will print to stdout if not set)
  output: 'project-map.scn',
  // Number of parallel workers (optional)
  maxWorkers: 4,
};

CLI arguments will override settings defined in the configuration file.

Programmatic API

Integrate scn-ts directly into your build scripts, custom tools, or even web applications.

Node.js Usage (File System)

import { generateScn, ScnTsConfig } from 'scn-ts-core';
import * as fs from 'node:fs/promises';

async function generateProjectScn() {
  const config: ScnTsConfig = {
    // File-system based analysis
    include: ['src/**/*.ts', 'src/**/*.tsx'],
    exclude: ['src/**/*.test.ts'],
    maxWorkers: 2,
  };

  try {
    const scnMap = await generateScn(config);
    await fs.writeFile('my-project-map.scn', scnMap);
    console.log('SCN map saved to my-project-map.scn');
  } catch (error) {
    console.error('Failed to generate SCN map:', error);
  }
}

generateProjectScn();

Browser Usage (In-Memory)

To use scn-ts in the browser, you must provide file content directly.

1. Copy WASM Files: First, copy the necessary parser files into your public web directory using the CLI. This only needs to be done once.

# This makes the parser files available at, e.g., http://localhost:3000/wasm/
npx scn-ts copy-wasm ./public/wasm

2. Initialize and Analyze: In your application code, initialize the parser with the location of the WASM files and then pass your in-memory file data to generateScn.

// my-browser-app.ts
import { initializeParser, generateScn, ScnTsConfig } from 'scn-ts-core';

// In-memory file data (e.g., from a file upload, API, or Monaco editor)
const files = [
  { path: 'src/index.ts', content: 'import { a } from "./utils";' },
  { path: 'src/utils.ts', content: 'export const a = 1;' },
];

async function runBrowserAnalysis() {
  try {
    // 1. Initialize parser with the path to your WASM files
    await initializeParser({ wasmBaseUrl: '/wasm/' });

    // 2. Analyze the in-memory files
    const config: ScnTsConfig = {
      files: files, // This bypasses file-system discovery
    };
    const scnMap = await generateScn(config);

    // 3. Display the SCN map in your app
    document.getElementById('scn-output').innerText = scnMap;
    console.log('✅ SCN map generated!');

  } catch (error) {
    console.error('Failed to run browser analysis:', error);
  }
}

runBrowserAnalysis();

ScnTsConfig Interface

interface ScnTsConfig {
  // For Node.js file system analysis
  root?: string;      // Root directory. Defaults to CWD.
  include?: string[]; // Glob patterns to include. Required for file-system mode.
  exclude?: string[]; // Glob patterns to exclude.

  // For Browser/In-Memory analysis
  files?: readonly { path: string; content: string }[]; // Provide file content directly.

  // Common options
  maxWorkers?: number; // Max parallel workers (Node.js only). Default: 1.
}

🔠 SCN Format Primer

SCN uses a concise set of single-character symbols to represent complex code structures. For the full specification, refer to docs/scn.readme.md.

| Category | Symbol | Meaning | Description | | :------- | :----: | :------ | :---------- | | General & Structural | § | File Path | Declares a new source file. | | | -> | Dependency | Points to an entity/file this entity uses. | | | <- | Caller | Points to an entity/file that uses this entity. | | Code Entities | ◇ | Container | Class, Struct, Module, Namespace, React Component. | | | ~ | Function | Function, Method, Procedure. | | | @ | Variable | Property, Field, Constant, State variable. | | | {} | Interface/Struct | Defines a data shape or complex object type. | | | ☰ | Enum | Defines a set of named constant values. | | | =: | Type Alias | Assigns a new name to an existing type. | | | ⛶ | HTML Element | Represents an HTML/JSX element tag. | | | ¶ | CSS Rule | Represents a CSS selector and its style. | | Type References | # | Type Reference | References an existing type in a signature/property. | | Qualifiers | + | Public | Public visibility/exported. | | | - | Private | Private/protected visibility. | | | ... | Async | The function is asynchronous. | | | ! | Throws | The function can throw an exception. | | | o | Pure | The function has no side effects (heuristic). | | CSS Intents | 📐 | Layout | CSS affects geometry. | | | ✍ | Text | CSS affects typography. | | | 💧 | Appearance| CSS affects color, background, border, etc. |

🖼️ Real-World Examples (Show and Tell)

See scn-ts in action and compare it to raw source code. Notice the drastic reduction in tokens while retaining critical architectural context.

Example 1: A Simple JavaScript Class

Before SCN: Raw Source Code (105 tokens)

// services/auth.js
import { findUserByEmail, hashPassword } from './utils';

/**
 * Manages user authentication.
 */
export class AuthService {
  constructor(database) {
    this.db = database;
  }

  // Tries to log a user in
  async login(email, password) {
    const user = await findUserByEmail(this.db, email);
    if (!user) {
      throw new Error('User not found');
    }

    const hash = hashPassword(password);
    if (user.passwordHash !== hash) {
      throw new Error('Invalid password');
    }

    return user;
  }
}

After SCN-TS: The Context Map (21 tokens)

§ (1) services/auth.js
  -> (utils.js)       // File-level dependency
  + ◇ (1.1) AuthService
    + @ db
    + ~ login(email: #, pass: #): #(User) ...!

Result: A 79% reduction in tokens. We've thrown away implementation details (if statements, internal calls) but preserved the essential API surface: the AuthService class has a public login method that is async, can throw, and returns a User.

Example 2: A React Component with CSS Integration

Before SCN: Raw Source Code (HTML, CSS - 131 tokens)

// Button.jsx
import './Button.css';

export function Button({ label, onClick }) {
  return (
    <button className="btn btn-primary" onClick={onClick}>
      {label}
    </button>
  );
}

// Button.css
.btn {
  padding: 8px 16px;
  border-radius: 4px;
  font-weight: bold;
}
.btn-primary {
  background-color: #007bff;
  color: white;
  border: none;
}

After SCN-TS: The Context Map (38 tokens)

§ (1) Button.css
  <- (2.0)
  ¶ (1.1) .btn { 📐 ✍ 💧 }
  ¶ (1.2) .btn-primary { 💧 }

§ (2) Button.tsx
  -> (1.0)
  + ◇ (2.1) Button { props: { label:#, onClick:# } }
    ⛶ (2.2) button [ class:.btn .btn-primary ]
      -> (1.1), (1.2)

Result: A 71% reduction. The SCN clearly shows that the Button component (2.1) has a button element (2.2) which is styled by two separate CSS rules (1.1, 1.2). The LLM now understands the structural link between the JSX and the CSS without seeing a single pixel value. Notice how scn-ts intelligently identifies the props used by the component and represents the CSS intents.

Example 3: A Multi-File TypeScript Application

Before SCN: Raw Source Code (118 tokens)

// models/user.ts
export interface User {
    id: string;
    name: string;
}

// services/user.ts
import { User } from '../models/user';
import { db } from '../data/database'; // Assume db is available globally or injected

export class UserService {
    async getUserById(id: string): Promise<User> {
        const user = await db.fetchUser(id);
        if (!user) {
            throw new Error('User not found');
        }
        return user;
    }
}

// main.ts
import { UserService } from './services/user';

async function bootstrap() {
    const userService = new UserService();
    try {
        const user = await userService.getUserById('123');
        console.log(user.name);
    } catch (error) {
        console.error(error);
    }
}

bootstrap();

After SCN-TS: The Context Map (53 tokens)

(Assuming data/database.ts exists but is not shown, and db is defined there)

§ (1) data/database.ts
  <- (3.1)
  + @ db

§ (2) main.ts
  -> (3.0)
  ~ (2.1) bootstrap() ...
    -> (3.1), (3.2)

§ (3) models/user.ts
  <- (4.1)
  + {} (3.1) User
    + @ id: #(string)
    + @ name: #(string)

§ (4) services/user.ts
  -> (3.1), (1.0)
  <- (2.1)
  + ◇ (4.1) UserService
    + ~ getUserById(id: #): #Promise<User> ...!
      -> (1.1)

Result: A 55% reduction. The SCN creates a complete dependency graph, showing file-level imports (main.ts -> services/user.ts, services/user.ts -> models/user.ts and data/database.ts) and entity-level calls (bootstrap() calls UserService and getUserById(), which in turn calls db). The LLM now has a full architectural view to reason about the application flow, data types, and potential error points.

✅ Benefits

For Large Language Models (LLMs)

• Enhanced Context: Provide LLMs with a high-level, structural overview of an entire project or subsystem, far beyond what typical context windows allow.
• Reduced Hallucinations: With precise API signatures and dependency maps, LLMs are less likely to invent functions or misuse existing ones.
• Lower Token Costs: Significant token reduction means more context for less cost, making LLM interactions more efficient and economical.
• Improved Code Generation: LLMs can generate code that better integrates with existing architecture, respects API contracts, and understands project flow.

For Developers

• Architecture Understanding: Quickly grasp the relationships between different parts of a large or unfamiliar codebase.
• Code Exploration: Navigate dependencies and understand system boundaries at a glance.
• Dependency Analysis: Identify coupling, potential refactoring targets, or impact of changes.
• Code Review: Use SCN maps as a high-level summary during code reviews.

For Tooling & Ecosystem

• Foundation for AI-Powered Dev Tools: SCN provides a standardized, compressed input format for a new generation of AI-driven software development tools.
• Lightweight Analysis: Perform rapid, high-level analysis without needing a full IDE or complex language server setup.

🛣️ Roadmap & Future Enhancements

scn-ts is continuously evolving. Planned enhancements include:

• Expanded Language Support: Deeper, more idiomatic SCN generation for other popular languages beyond JS/TS/CSS.
• More Granular Entity Information: Capturing more details like type parameters, decorators, or specific modifiers for certain languages.
• Performance Optimizations: Further improvements to parsing and serialization speed.
• Pre-built Binaries: Easier distribution without relying on Node.js/Bun directly.
• Integration with LLM Frameworks: Providing direct helpers for popular LLM APIs to inject SCN context.

🤝 Contributing

We welcome contributions! If you have ideas for new features, improvements, or bug fixes, please open an issue or submit a pull request on GitHub.

Before contributing, please read the SCN Specification to understand the core principles of Symbolic Context Notation.

📜 License

scn-ts is MIT licensed.