BlackLang

Quick Start

En küçük çalışan akış bir `.black` dosyası yazmak, validate etmek ve web çıktısı üretmektir. AI ajanı da insan geliştirici de aynı dosyayı okuyup aynı sonucu alır.

app Warehouse

entity Product {
  sku text required unique
  name text required
  stock number default 0
  price money
}

page Products {
  source Product

  table {
    columns sku, name, stock, price
    search sku, name
  }

  form {
    fields sku, name, stock, price
  }

  actions create, edit, delete
}

Bu blok Product verisini, Products ekranını, tablo kolonlarını, form alanlarını ve CRUD davranışlarını tek kaynakta toplar. Generator bu niyetten TypeScript, React, API, validation ve database tarafını üretir.

Kurulum

BlackLang'in hedef dağıtımı tek binary modelidir. Olgun sürümde kullanıcı sadece `black` komutunu indirip çalıştırabilmelidir; compiler için ayrıca Python veya Node.js zorunlu olmamalıdır.

black init
black format --check --json
black lint --json
black validate --json
black build

npm yolu da yaygınlaşma için planlanır. npm paketi platforma uygun binary'yi çağırır; BlackLang'in compiler mantığı yine tek binary içinde kalır.

Proje Yapısı

BlackLang projelerinde kaynak gerçekliği `.black` dosyalarıdır. Generated dosyalar compiler çıktısıdır ve normalde elle düzenlenmez.

blacklang/
  BLACKLANG.md
  SPEC.md
  AGENTS.md
  blacklang.toml
  examples/
    warehouse/
      app.black
  generated/
  packages/
    cli/

AI ajanı projeye girdiğinde önce yerel öğrenme dosyalarını ve `blacklang.toml` sürüm bilgisini okur. Sonra sadece gereken `.black` kaynaklarını değiştirir.

Syntax Temeli

Dil kısa olmalı ama şifreli olmamalıdır. `app`, `entity`, `page`, `table`, `form`, `actions`, `when` gibi tanıdık kelimeler AI'nin ilk okuma maliyetini düşürür.

app Warehouse

database {
  url env DATABASE_URL
}

entity Product {
  name text required
}

page Products {
  source Product
}

Her davranış için tek syntax hedeflenir. Bu, hem compiler hatalarını daha stabil yapar hem de AI ajanının "hangi kullanım doğru" diye tahmin yürütmesini azaltır.

app

`app`, uygulamanın adını belirler. Bir BlackLang projesinde tam olarak bir ana uygulama adı olmalıdır.

app Warehouse

Generator bu adı package metadata, arayüz başlığı ve çıktı dokümantasyonu gibi yerlerde kullanabilir. İsim PascalCase yazıldığında hem insan hem AI için daha okunaklı kalır.

entity

`entity`, saklanacak uygulama verisini anlatır. Normal web stack'te model, validation, database schema ve API type parçalarına bölünen niyet burada tek blokta ifade edilir.

entity Product {
  sku text required unique length 3..40
  name text required label "Product Name"
  stock number default 0 min 0
  price money min 0
}

Field adı solda, tipi yanında, kuralları ise aynı satırda yer alır. Bu sıra, AI'nin satırı tek seferde okuyup veri niyetini anlamasını kolaylaştırır.

Field Tipleri

Field tipi verinin nasıl saklanacağını ve hangi validation davranışlarının üretileceğini belirler.

name text required
stock number default 0
quantity integer min 1
price money min 0
email email unique
active boolean default true
createdAt datetime

v0.1 alan tipleri: `text`, `number`, `integer`, `decimal`, `money`, `email`, `boolean`, `date`, `datetime`. Entity adı da relation tipi olarak kullanılabilir.

sku text required unique length 3..40 regex "^[A-Z0-9]+$"
website text optional url
discount money min 0
name text required placeholder "Enter product name" help "Visible in lists"

page

`page`, generated web uygulamasındaki ekran niyetini anlatır. Sayfa hangi entity'den beslenecek, hangi tablo ve form alanlarını gösterecek, hangi aksiyonları açacak burada belirlenir.

page Products {
  source Product

  table {
    columns sku, name, stock, price
    search sku, name
  }

  form {
    fields sku, name, stock, price
  }

  actions create, edit, delete
}

`source`, var olan bir entity'yi göstermelidir. Table ve form alanları source entity içinde yoksa validator stabil hata kodu üretir.

table

`table`, listeleme yüzeyini tarif eder. Kolonlar, arama alanları, filtreler, sıralama ve pagination aynı blokta tutulur.

table {
  columns sku, name, stock, price
  search sku, name
  filter stock
  sort stock desc
  paginate 10
}

Generator table tanımından React liste görünümü, search state, filtre kontrolleri, pagination ve field bazlı görünürlük kontrollerini üretebilir.

form

`form`, create ve edit işlemlerinde kullanılacak alanları belirler. Field metadata varsa label, placeholder, help ve inline validation mesajları buradan üretilir.

form {
  fields sku, name, stock, price
}

Relation field kullanıldığında generator select input üretir. Zorunlu relation için ilişkili kayıt yoksa submit kapatılıp kullanıcıya önce hangi kaydı oluşturması gerektiği gösterilir.

actions

`actions`, sayfada hangi veri işlemlerinin aktif olacağını söyler. Aynı liste, API route üretimini ve arayüz kontrol görünürlüğünü etkiler.

actions create, edit, delete, archive, restore

`archive`, soft delete mantığıyla `archivedAt` set eder. `restore`, kaydı tekrar görünür yapar. Role sistemi varsa action butonları izinlere göre gizlenir.

layout

`layout`, sayfaların generated uygulama kabuğunda hangi sırayla görüneceğini kontrol eder. Şimdilik sidebar odaklıdır.

layout AdminLayout {
  sidebar {
    item Products
    item Customers
    item Orders
  }
}

page Products {
  layout AdminLayout
  source Product
}

Explicit layout yoksa navigation sayfa tanım sırasından türetilebilir. Küçük ekranlarda generated app drawer menüye geçer.

auth

`auth`, giriş ve oturum niyetini kaynak dil seviyesinde tanımlar. v0.1 email ve password stratejisiyle cookie session üretimini destekler.

auth {
  strategy emailPassword
  session cookie

  user {
    name text required
    email email required unique
  }
}

Bu blok register, login, logout, `/api/auth/me`, password hashing ve cookie session davranışlarının üretilmesine temel olur.

role ve access

`role`, kullanıcı izinlerini tanımlar. `access`, sayfanın hangi role veya auth kapsamına açık olduğunu söyler.

role Admin {
  allow all
}

role Worker {
  allow read Product
  deny read Product price
  allow update Product stock
}

page Products {
  source Product
  access Admin, Worker
}

Generated API, sayfa ve action seviyesinde izinleri uygular. Field-level `deny` ile hassas alanlar API response ve React görünümünden gizlenebilir.

workflow

`workflow`, bir entity'nin iş süreci durumlarını ve geçişlerini tanımlar. Özellikle sipariş, destek talebi, onay akışı gibi sistemlerde kullanılır.

workflow OrderPreparation {
  source Order
  states draft, picking, verified, packaged, shipped

  transition ship {
    from packaged
    to shipped
    allow Admin
  }
}

Workflow source entity içinde `status text` olmalıdır. Generator transition route, permission check, status update, UI button ve audit log kaydı üretebilir.

state

`state`, generated React ekranında kullanılacak client-side UI durumunu ifade eder. Modal, seçili kayıtlar ve aktif filtre gibi davranışlar burada tanımlanabilir.

state OrdersPageState {
  selectedOrders Order[]
  activeFilter text
  modal createOrder closed
}

`OrdersPageState` veya `OrdersState`, `page Orders` ile eşleşebilir. Modal tanımı open/close helper üretimine temel olur.

component

`component`, tekrarlı UI niyetlerini kaynak seviyesinde tanımlar. İlk kullanımda field değerine göre variant seçimi desteklenir.

component StockBadge {
  input stock number

  variant low when stock < 10
  variant normal when stock >= 10
}

Tek input, entity field adı ve tipiyle eşleşirse generated table, detail ve form preview alanlarında otomatik kullanılabilir.

api

`api`, generated CRUD dışındaki contract-first endpoint niyetlerini anlatır. Runtime implementation daha sonra gelişebilir; v0.1 bu bilgiyi OpenAPI çıktısına taşır.

api LowStockReport {
  method GET
  path "/api/reports/low-stock/{warehouseId}"
  param warehouseId text
  query limit integer
  private
}

api StockWebhook {
  method POST
  path "/api/webhooks/stock"
  webhook
  public
}

`black build` generated OpenAPI contract oluşturur. Generated Express server bu contract'ı `/openapi.json` üzerinden servis edebilir.

security

BlackLang kaynak dosyaları yüksek değerli source asset olarak görülür. Secret, password, API key, token ve private key değerleri `.black` dosyasına yazılmamalıdır.

database {
  url env DATABASE_URL
}

database {
  url "postgres://user:password@example.com/app"
}

Production deployment için hedef, mümkünse `.black` kaynaklarını sunucuya taşımadan generated production artifact yayınlamaktır. `black security scan --json` olası hardcoded secret izlerini raporlar.

CLI

CLI, AI ajanlarının BlackLang projesini tahmin ederek değil compiler'dan öğrenerek değiştirmesini sağlar. Önemli komutlar JSON çıktı verebilmelidir.

black version --json
black format --check --json
black lint --json
black parse examples/warehouse/app.black --json
black validate examples/warehouse/app.black --json
black build examples/warehouse/app.black --json
black inspect --ir
black docs --all --json
black explain entity --json
black security scan --json

`lint` format, parse, validate ve source-security bulgularını tek raporda toplar. `explain`, tek keyword için amaç, syntax, örnek, agent notu ve hata kodlarını döner.

Hata Çıktıları

Hatalar stabil code, dosya, satır, kolon ve öneri alanlarıyla dönmelidir. Böylece AI ajanı hata metnini yorumlamak yerine error code üzerinden doğru referansa gider.

{
  "success": false,
  "errors": [
    {
      "file": "examples/warehouse/app.black",
      "line": 17,
      "column": 13,
      "code": "UNKNOWN_FIELD",
      "message": "Page Products uses unknown field barcode.",
      "suggestion": "Add barcode to Product or remove it from columns."
    }
  ]
}

Bu model, insan için okunabilir; AI için de deterministik onarım akışı sağlar.

AI Agents

BlackLang yeni olduğu için modellerin eğitim verisinde bulunmayabilir. Bu normaldir. Dil, yerel öğrenme paketi ve küçük CLI açıklamalarıyla hızlı öğrenilecek şekilde tasarlanır.

1. Read AGENTS.md
2. Read BLACKLANG.md
3. Check blacklang.toml
4. Run black inspect --json or --ir
5. Edit only .black source files
6. Run black format --check --json
7. Run black lint --json
8. Run black build
9. Do not manually edit generated files

Hedef sıfır öğrenme maliyeti değildir. Hedef, ilk öğrenmeden sonra tekrar eden web geliştirme görevlerinin normal stack'e göre daha ucuz ve daha az hatalı hale gelmesidir.

Örnekler

İlk örnek Warehouse uygulamasıdır. Bu örnek auth, role, relation, workflow, state, component, table, form, validation ve API contract özelliklerini aynı kaynakta gösterir.

entity Order {
  customer Customer required label "Customer"
  total money default 0 min 0
  discount money default 0 min 0
  status text default draft
  trackingNumber text optional
  validate discount <= total message "Discount cannot exceed total"
  validate trackingNumber required when status == shipped message "Tracking number is required when shipped"
}

Uzun vadede CRM, inventory, helpdesk, invoice, appointment ve project management şablonları eklenerek gerçek uygulama desenleri ölçülebilir hale getirilir.

CRM Template

SalesCRM, gerçek uygulama şablonlarının ilkidir. Company, Contact, Deal ve Activity kayıtlarını tek `.black` kaynakta tanımlar; auth, role/access, workflow, state, component, validation ve OpenAPI contract davranışlarını birlikte gösterir.

app SalesCRM

entity Company {
  name text required unique label "Company Name"
  website text optional url
  segment text default prospect
  annualRevenue money default 0 min 0
}

entity Deal {
  company Company required
  contact Contact required
  name text required length 3..80
  expectedRevenue money default 0 min 0
  discount money default 0 min 0
  probability number default 25 min 0 max 100
  status text default lead
  validate discount <= expectedRevenue message "Discount cannot exceed expected revenue"
}

workflow DealPipeline {
  source Deal
  states lead, qualified, proposal, negotiation, won, lost
}

Bu şablon yeni syntax eklemeden bugünkü compiler kapasitesini kullanır. Template benchmark raporu `benchmarks/crm-v0.2.md` altında tutulur.

Inventory Template

InventoryControl, ikinci gerçek uygulama şablonudur. Warehouse, Supplier, Category, Item, PurchaseOrder ve StockMovement kayıtlarını tek `.black` kaynakta tanımlar; stok yönetimi, satın alma akışı, stok hareketi akışı, field-level access, validation ve API contract davranışlarını birlikte ölçer.

app InventoryControl

entity Item {
  warehouse Warehouse required
  supplier Supplier required
  category Category required
  sku text required unique length 3..40 regex "^[A-Z0-9-]+$"
  onHand number default 0 min 0
  reserved number default 0 min 0
  reorderPoint number default 5 min 0
  unitCost money default 0 min 0
  status text default active
  validate reserved <= onHand message "Reserved stock cannot exceed on-hand stock"
}

workflow PurchaseOrderFlow {
  source PurchaseOrder
  states draft, submitted, approved, received, closed, cancelled
}

page StockMovements {
  source StockMovement

  table {
    columns item, warehouse, type, quantity, reason, status, completed
  }

  form {
    fields item, warehouse, type, quantity, reason, status, completed
  }
  actions create, edit, delete, archive, restore
}

Bu şablon inventory alanında iki kelimeli entity adlarını da test eder: `PurchaseOrder` ve `StockMovement` generated TypeScript tarafında `purchaseOrder` ve `stockMovement` olarak doğru kullanılır. Benchmark raporu `benchmarks/inventory-v0.2.md` altında tutulur.

Helpdesk Template

SupportDesk, üçüncü gerçek uygulama şablonudur. Organization, Customer, Team, SupportAgent, ServiceLevelAgreement, Ticket, TicketComment ve KnowledgeArticle kayıtlarını tek `.black` kaynakta tanımlar; destek kuyruğu, SLA takibi, ticket lifecycle, bilgi bankası yayını, field-level access ve API contract davranışlarını birlikte ölçer.

app SupportDesk

entity Ticket {
  organization Organization required
  requester Customer required
  assignedTeam Team required
  assignedAgent SupportAgent optional
  sla ServiceLevelAgreement required
  ticketNumber text required unique length 3..40
  subject text required length 3..120
  description text required length 10..500
  priorityScore number default 2 min 1 max 5
  status text default open
  resolution text optional length 3..500
  internalNotes text optional length 3..500
  validate resolution required when status == resolved message "Resolution is required when ticket is resolved"
}

workflow TicketLifecycle {
  source Ticket
  states open, triaged, inProgress, waitingCustomer, resolved, closed
}

page Tickets {
  source Ticket

  table {
    columns organization, requester, assignedTeam, ticketNumber, subject, priorityScore, status
  }

  form {
    fields organization, requester, assignedTeam, sla, ticketNumber, subject, description, status
  }
  actions create, edit, delete, archive, restore
}

Bu şablon destek operasyonlarının yoğun ilişki yapısını test eder: müşteriler, ekipler, ajanlar, SLA kayıtları, ticket yorumları ve bilgi bankası aynı uygulama kabuğunda üretilir. Benchmark raporu `benchmarks/helpdesk-v0.2.md` altında tutulur.

Invoice Template

InvoiceFlow, dördüncü gerçek uygulama şablonudur. Client, BillingContact, TaxRate, CatalogItem, Invoice, InvoiceLine, Payment ve CreditNote kayıtlarını tek `.black` kaynakta tanımlar; fatura onayı, ödeme takibi, iade notları, field-level access, validation ve API contract davranışlarını birlikte ölçer.

app InvoiceFlow

entity Invoice {
  client Client required
  billingContact BillingContact optional
  invoiceNumber text required unique length 3..40
  issueDate date optional
  dueDate date optional
  currency text default USD
  subtotal money default 0 min 0
  taxTotal money default 0 min 0
  discountTotal money default 0 min 0
  grandTotal money default 0 min 0
  paidAmount money default 0 min 0
  balanceDue money default 0 min 0
  paymentStatus text default unpaid
  status text default draft
  validate discountTotal <= subtotal message "Discount cannot exceed subtotal"
  validate paidAmount <= grandTotal message "Paid amount cannot exceed grand total"
}

workflow InvoiceLifecycle {
  source Invoice
  states draft, approved, sent, partiallyPaid, paid, overdue, void
}

page Invoices {
  source Invoice

  table {
    columns client, invoiceNumber, dueDate, grandTotal, paidAmount, balanceDue, paymentStatus, status
  }

  form {
    fields client, invoiceNumber, dueDate, subtotal, taxTotal, discountTotal, grandTotal, paidAmount, balanceDue, status
  }
  actions create, edit, delete, archive, restore
}

Bu şablon para alanları, fatura satırları, ödeme workflow'u ve client görünürlüğü gibi finansal uygulama ihtiyaçlarını bugünkü compiler kapasitesiyle ölçer. Benchmark raporu `benchmarks/invoice-v0.2.md` altında tutulur.

Benchmarks

BlackLang'in iddiası ölçülmelidir: kaç satır `.black` yazıldı, kaç satır generated kod üretildi, normal web stack karşılığı ne olurdu ve AI kaç dosyaya dokundu?

Metric                 Normal Stack   BlackLang
Source lines                    TBD         TBD
Generated lines                 TBD         TBD
Files edited                    TBD         TBD
Input tokens                    TBD         TBD
Output tokens                   TBD         TBD
Build time                      TBD         TBD

Roadmap

v0.1 web MVP tamamlandı: parser, validator, generator, CRUD, relation, auth, role/access, workflow, state, component, validation, OpenAPI ve source security temelleri var.

Phase 18: Release and install path
Phase 19: Developer and AI ergonomics
Phase 20: UI and theme language
Phase 21: Query, actions, and data logic
Phase 22: Tests, benchmarks, and evals
Phase 23: Protected source mode
Phase 24: Documentation site
Phase 25: Real app templates

Bu site Phase 24'ün ilk yayınlanabilir sürümüdür. Dil büyüdükçe her yeni syntax, CLI davranışı ve migration notu burada güncellenecektir.