Codepot Language 0.3

Codepot is a strongly typed semantic application language implemented in Rust. It models world meaning, software intent, contracts, APIs, screens, workflows, security, and reusable project foundations without embedding TypeScript, SQL, ORM, or UI-framework syntax in application source.

Version 0.3 compiles .pot, .code, .codepot, and .cpt files into an in-memory semantic program and deterministic YAML IR. The interpreter and code-generation crates intentionally remain trait-first extension points for later releases.

Language principles

• Module identity comes from the filesystem and Codepot.toml; source files never declare a package.
• Every explicit import uses from <module> import ....
• Standard-library source is marked with library; and is either embedded or loaded from source, never both.
• Codepot is strongly and statically typed. Types, generic arguments, function receivers, function arguments, references, inheritance, projections, and rule changes are validated before IR is produced.
• Values such as Email, Slug, Username, Phone, and Url carry reusable default validation and normalization rules in std.
• A use may refine a default by applying the same function again, or remove it explicitly with without("ruleName"). Rule provenance remains visible in IR.
• ref() creates a semantic usage. It inherits safe value rules but does not blindly copy storage-only behavior.
• The Rust formatter is canonical for the CLI and language server.

Example

from app.foundation.state import SoftDeletableEntity;
from std.core import Bool, Text;
from std.software.contract import Input, Output;
from std.software.state import Entity;
from std.world.identity import Email, Name, Username;

/**
 * Application user account.
 *
 * @category identity
 * @security Public projections must never include secret fields.
 */
Entity User extends SoftDeletableEntity {
  name: Name required() max(120)
  username: Username required() unique()
  email: Email required() unique()
  active: Bool required() default(true)
  biography: Text optional() max(1000)
}

Input UpdateUser from User {
  use partial(ref(User)) {
    name
    username
    email
    biography
  }
}

Output UserResponse {
  user: ref(User).public()
}

Imports

from std.world.time import DateTime;
from std.world.time import Date, DateTime, Duration;
from std.world.time import (
  Date,
  DateRange,
  DateTime,
  Duration,
  Timezone,
);
from std.world.time import * as time;

A wildcard must have a namespace alias. Bare wildcard imports and named aliases are not supported. The formatter removes unnecessary parentheses and introduces them only when an import exceeds the configured line width.

Comments and documentation

# Ordinary single-line comment.

/* Ordinary block comment. */

## Documentation attached to the next declaration.

/**
 * Structured documentation attached to the next semantic declaration.
 *
 * @validation Describe portable rules.
 * @regex ^[a-z0-9-]+$
 * @example "example-value"
 */
value Example from Text {
}

Ordinary comments are excluded from semantic analysis but retained for formatting. Documentation comments are stored in the AST and IR and are surfaced by hover, completion, and signature help.

Project configuration

[project]
name = "my-codepot-project"
language-version = "0.3"

[packages]
app = "src/app"
vendor = "vendor"

[standard-library]
mode = "embedded"
# For Codepot compiler development instead:
# mode = "source"
# path = "stdlib/std"

[compiler]
entry = "src/app/main.codepot"
output = ".codepot/app.ir.yaml"

[format]
indent-width = 2
line-width = 100
trailing-commas = "multiline"
semicolons = "always"
sort-imports = true
group-imports = true
blank-lines-between-import-groups = true

CLI

codepot check
codepot check --format json
codepot format
codepot format --check
codepot compile
codepot inspect modules
codepot inspect imports src/app/main.codepot
codepot inspect symbols
codepot inspect ast src/app/main.codepot
codepot inspect ir src/app/main.codepot
codepot doctor
codepot lsp --stdio

codepot check is the no-output type-check command. The CLI and language server use the same analysis host and diagnostic model.

Workspace layout

crates/
  codepot-core          kernel identifiers, spans, constants, traits
  codepot-source        source readers, writers, and shared source storage
  codepot-config        Codepot.toml and formatting rules
  codepot-lexer         lossless tokenization including comments and docs
  codepot-parser        recoverable parser and AST construction
  codepot-packages      filesystem modules, imports, std source selection
  codepot-semantics     symbols, types, generics, rules, refs, inheritance
  codepot-ir            stable target-neutral semantic representation
  codepot-yaml          deterministic IR serialization
  codepot-analysis      persistent VFS-backed workspace analysis
  codepot-ide           editor-neutral language intelligence
  codepot-lsp           Language Server Protocol adapter
  codepot-formatter     canonical syntax-aware formatter
  codepot-compiler      one-shot compilation pipeline
  codepot-cli           CLI and LSP fallback command
  codepot-codegen       future deterministic generator traits
  codepot-interpreter   future interpreter traits
stdlib/std/             documented Codepot standard library
vcode/                  VS Code extension client and offline grammar

Build and verify

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo build --workspace
python scripts/static_check.py

cd vcode
pnpm install --frozen-lockfile
pnpm verify
pnpm package

See docs/LANGUAGE_REFERENCE.md, docs/ARCHITECTURE.md, and docs/EDITOR_TOOLING.md for the complete design.

codepot_lang