code-moniker

code-moniker extracts a symbol graph from source code.

It turns source files into stable symbol identities, then exposes the same graph through two surfaces:

• a CLI for inspecting code and enforcing architecture rules in hooks or CI;
• a PostgreSQL extension for storing and querying symbol graphs with SQL.

Supported languages: TypeScript / JavaScript / TSX / JSX, Rust, Java, Python, Go, C#, SQL, and PL/pgSQL.

At a glance

flowchart LR
  subgraph Input["Inputs"]
    S["Source code<br/>TS, Rust, Java, Python,<br/>Go, C#, SQL"]
    M["Build manifests<br/>Cargo.toml, package.json,<br/>pom.xml, pyproject.toml,<br/>go.mod, csproj"]
  end

  subgraph Model["Extraction model"]
    E["Language extractors"]
    G["Code graph<br/>defs, refs, monikers,<br/>positions, attributes"]
    D["Dependency rows<br/>package monikers"]
  end

  subgraph Tools["Tools"]
    C["CLI<br/>extract, check, manifest"]
    P["PostgreSQL extension<br/>moniker + code_graph types,<br/>SQL extractors, indexes"]
  end

  subgraph Uses["Uses"]
    I["Inspection<br/>tree, json, tsv"]
    R["Architecture rules<br/>hooks, CI, agent harnesses"]
    Q["SQL queries<br/>storage, joins, indexed lookup"]
  end

  S --> E --> G
  M --> D
  G --> C
  G --> P
  D --> C
  C --> I
  C --> R
  P --> Q

  classDef input fill:#eef6ff,stroke:#2f6f9f,color:#0b253a
  classDef model fill:#f1f8f4,stroke:#3a7d4f,color:#0f2a18
  classDef tool fill:#fff6e5,stroke:#9a6b12,color:#332100
  classDef use fill:#f7f1ff,stroke:#6f4aa1,color:#211232
  class S,M input
  class E,G,D model
  class C,P tool
  class I,R,Q use

First useful commands:

code-moniker extract src/order.ts --format tree
code-moniker check src/ --report
code-moniker manifest .

What it is for

Use code-moniker when text search is too weak because the question is about symbols and relationships:

• Which definitions live under src/domain/?
• Does domain code import infrastructure code?
• Which classes implement a port?
• Which refs point at a symbol family, even when the final segment kind differs across import and definition sites?
• Can this rule run after every edit, before commit, or in CI?

How extraction works

The unit of identity is a moniker: a URI-like path made of typed segments. Each segment says what the name means, not only where text was found.

For this file:

// src/domain/order.ts
export class OrderEntity {
  total() {
    return computeTotal();
  }
}

function computeTotal() {
  return 42;
}

extract emits definitions such as:

code+moniker://./lang:ts/dir:src/dir:domain/module:order/class:OrderEntity
code+moniker://./lang:ts/dir:src/dir:domain/module:order/function:computeTotal()

It also emits refs between those definitions. The call inside OrderEntity.total() points at the function:computeTotal() moniker, so rules and queries can reason over relationships instead of strings.

Common ref kinds include calls, imports, inheritance, implemented interfaces, type usage, annotations, and language-specific edges. In project scans, file paths are anchored relative to the scanned root: code-moniker extract src/ sees src/domain/order.ts as dir:domain/module:order.

Install

Install the standalone CLI:

cargo install code-moniker

Or install the latest main:

cargo install --git https://github.com/ng-galien/code-moniker code-moniker

From a local checkout:

cargo install --path crates/cli

First CLI run

Inspect a file:

code-moniker extract src/order.ts --format tree

Inspect a directory:

code-moniker extract src/

Filter by kind or shape:

code-moniker extract src/ --shape callable
code-moniker extract src/ --kind class,interface

Run the linter:

code-moniker check src/

Exit codes:

Configure rules

code-moniker check loads embedded defaults first. If a .code-moniker.toml file exists, it is merged on top.

[[refs.where]]
id      = "domain-no-infra"
expr    = "source ~ '**/dir:domain/**' => NOT target ~ '**/dir:infrastructure/**'"
message = "Domain code must not depend on infrastructure."

[[ts.class.where]]
id      = "no-god-class"
expr    = "count(method) <= 20 AND all(method, lines <= 60)"
message = "Class `{name}` exceeds the class budget."

[[ts.interface.where]]
id   = "repository-lives-in-domain"
expr = "name =~ Repository$ => moniker ~ '**/dir:domain/**'"

Rules evaluate symbols and refs, not source text. The path pattern must match the moniker encoding produced by the extractor. Check one file when in doubt:

code-moniker extract src/order.ts --format json

PostgreSQL extension

The extension installs native moniker and code_graph types, extractors, accessors, and indexes. It owns no application tables.

CREATE EXTENSION code_moniker;
SET search_path = code_moniker, public;

SELECT extract_typescript(
  'src/util.ts',
  'export class Util { run() { return 1; } }',
  'code+moniker://app'::moniker
);

Example indexed query:

SELECT id
FROM module
WHERE graph_root(graph) <@ 'code+moniker://app/lang:ts/dir:domain'::moniker;

Install and usage details live in the PostgreSQL docs.

Documentation

Start with the page that matches the task:

Full index: docs/.

Performance

The CLI is designed for hooks and CI. Project scans are parallel; per-file checks are bounded enough for edit hooks. Measurements and reproduction commands are in Performance.

License

Dual-licensed under MIT or Apache 2.0, at your option. Contributions are accepted under the same terms.