cie

CIE — Code Intelligence Engine

A staged, evidence-backed code-analysis platform. CIE ingests code and documents, extracts typed facts, function summaries, contracts, concepts and hierarchy, verifies conformance mechanically, and reports document–code drift — with evidence, provenance, nanosecond timestamps, incremental correctness, and an LLM confined to the labeling layer.

This repository is the v0.2.0 contract-fidelity release: every instructor task marked partial in the 84-task cross-check is now implemented to its validation contract (identity newtypes, RevisionAllocator, §9 protocol + CieError/CI_TOLERANCE, typed relation graph + CSR freeze + FOW PDG, tombstones, per-file/per-symbol summary reuse, adapter semantics tables, the runnable 31-item acceptance harness, six-key concept persistence, cycle rejection, --max-depth, parent-edge invalidation, rst/adoc/html ingestion, persisted ClaimStore and recovery-lite findings). v0.1.0 implemented PRD slices 0–10; the plan and the 84-task disposition live in docs/V0_2_PLAN.md and docs/TRACEABILITY.md.

Quickstart

cargo build --release
export PATH="$PWD/target/release:$PATH"

# Ingest + analyze a folder (human report; exit code 2 on critical findings)
cie analyze examples/bankapp

# Unified streaming ingestion and a compatible web artifact bundle
cie ingest-polyglot examples/bankapp --web-out /tmp/bankapp-artifacts.json
# `cie ingest` remains a compatibility alias.

# Machine-readable outputs
cie analyze examples/bankapp --format sarif   # SARIF 2.1.0 for security tooling
cie analyze examples/bankapp --format json
cie analyze examples/bankapp --format md

# Hierarchical concept behavior tree (FR-44)
cie concepts examples/bankapp --with-behaviors --with-rules

# Document vs code drift (FR-31–39)
cie drift docs/prd.md --code examples/bankapp

# Blast radius + minimum test set for a change (CAP-10.3, CAP-17.3)
cie impact examples/bankapp --symbol auth.good_auth

# Static evidenced payment/recovery template (RFC-0020)
cie state-model examples/bankapp --json

# Bounded static-model fault hypotheses; does not execute the application
cie fault examples/bankapp --json --max-faults 2 --budget-ms 500

# Time-travel report (FR-23)
cie report examples/bankapp --as-of-rev 1

The current ingestion flow, memory boundaries, incremental behavior and clustering ownership are documented in Ingest-polyglot architecture. The storage module is linked into the same process and owns persistence policy behind typed APIs.

Architecture (PRD §6)

Layer	Crate	What ships in v0.1.0
L6 Output	cie-cli	CLI, JSON, Markdown, SARIF, DOT, Mermaid
L5 Capability	cie-analysis	Conformance, security (secrets, taint-lite, N+1), testing (test map, coverage gaps, min test set), dead code, layering
L4 Analysis	cie-analysis	Behavior summaries (fixpoint over call graph), conformance rules, FCA lattice, ConceptNode DAG + rollup, drift pipeline
L3 Foundation	cie-core	Semantic model, typed facts, summaries, contracts (authority-guarded), evidence/coverage, incremental engine
L2 Ingestion	cie-langs	Folder walk, hashing, tree-sitter adapters, cross-file call resolution
L1 Storage	cie-storage	Revisioned snapshots (rev:{id}), file index (file:{path}:hash), label cache, drift reports — PRD §57 namespaces as JSON

Languages

Language	Adapter	Depth
Python	tree-sitter-python	Deep: effects, exceptions + handler semantics, branches, loops, assignments, taint sources/sinks, f-string data flow, docstring contracts
TypeScript / TSX	tree-sitter-typescript	Light: symbols, calls, imports, loops, assignments, sources/sinks, tests
JavaScript	tree-sitter-javascript	Light (same)
Java	tree-sitter-java	Deep: classes/interfaces/enums, JVM dispatch, throws/catch contracts, annotations
Go	tree-sitter-go	Light (same)
Rust	tree-sitter-rust	Light (same)
C / C++ / C#	tree-sitter-c / -cpp / -c-sharp	Light (same)
PHP	tree-sitter-php	Light (same)
SQL	cie-adapter-sql	Deep: tables, views, procedures, foreign-key / read / write links
Shell	cie-adapter-shell	Deep: functions, sourcing, external commands + their effects
Kotlin (v1.2.2)	tree-sitter-kotlin-ng	Deep: classes/interfaces/objects, methods, imports, calls, throw/try/catch, coroutine spawn, val/var assignments
Lua (v1.2.2)	tree-sitter-lua	Deep: functions + table closures, require imports, calls with stdlib effect map, error()/pcall, loops, assignments, returns

Extension path (PRD §67, acceptance #9): add a grammar crate to the workspace Cargo.toml, create an adapter crate implementing LanguageAdapter, add ONE registration line in cie-ingest::default_registry() — zero core changes (Kotlin and Lua each landed in v1.2.2 exactly this way).

Foundation guarantees (all enforced by construction)

• LLM labels, never decides — the LLM layer returns strings; Authority (Explicit / InferredCandidate / Verified) is only settable by mechanical checkers. Offline-first default; Ollama and OpenAI-compatible endpoints opt-in via --llm-provider; content-addressed cache (blake3); hard USD budget with automatic downgrade (§63).
• Timeout ≠ no defect — every stage is budget-aware; cuts mark coverage.complete = false and yield Unknown, never Implemented (acceptance #26).
• Explicit uncertainty — unresolved calls and unsupported constructs are recorded in Evidence, never silently dropped (acceptance #6).
• Incremental by construction — blake3 content hashes, ingest plans, deletion handling; unchanged re-ingest measured at ~3% of first-ingest wall time (acceptance #10).
• Every conclusion carries evidence — revision, provenance, assumptions, counterexample findings, coverage.

Acceptance suite coverage (PRD §70)

Suite	Status in v0.2.0
Foundation #1–#7 (authorize examples)	✅ crates/cie-cli/tests/acceptance.rs (+ tombstone assertions)
Ingestion #8, #10, #11 (polyglot, re-ingest, time travel)	✅
LLM #12–#14 (offline labels, cache, budget downgrade)	✅ pinned (cie-llm trio + harness dispatch)
Storage #15–#16 (latency targets)	✅ #15 shipped subset perf-gated (perf_suite.rs); #16 deferred → v1.0
Drift #17–#26	✅ all pinned — #17 ≥90% non-Unknown, #24 cached re-run ≤5%, #25 ≥60% LLM-off
Concepts #27–#31	✅ (+ six-key persistence, cycle rejection, parent-edge invalidation)
Runtime #32–#36 (OTel ingestion, FR-45)	⏳ Slice 19
Multi-repo #37–#40 (FR-46)	⚠️ basic merged-concept graph via cie ingest-org
Spot checks #41–#44, #46	✅ (layering, taint, N+1, dead code, min test set)
Spot checks #45, #47, #48, #49	⚠️ partial (impact, mermaid output)
Spot check #50 (SMT proofs)	⏳ CAP-13, v1.0 (needs PDG substrate — shipped in v0.2)

Run everything: cargo test (≈90 tests: acceptance + harness + sketch-fidelity + units; perf gates via cargo test --release -- --ignored). The registry of record is crates/cie-cli/tests/acceptance_harness.rs — 24 green / 2 deferred of the base 26, 29 green / 2 deferred of the TASK-084 extension to 31.

Example

The examples/bankapp project contains the canonical authorize() pathology set from the PRD:

• auth.authorize — print-only authorization (Critical)
• payments.charge — rejected authorization ignored, then DB writes (High)
• payments.refund — bare except converting failure to success (High)
• ui.delete_account — tainted request.args → SQL f-string, plus UI-layer DB access
• payments.API_KEY — hardcoded live-format secret (Critical)
• payments.list_purchases — N+1 query in a loop
• auth.good_auth — legitimate delegation, not flagged

Repository layout

crates/cie-core        # L3: types, facts, summaries, contracts, evidence, drift model
crates/cie-storage     # L1: revisioned store (PRD §57 namespaces)
crates/cie-langs       # L2: tree-sitter adapters + resolution
crates/cie-analysis    # L4/L5: analyses + capability slices
crates/cie-llm         # LLM providers, cache, budget
crates/cie-cli         # L6: `cie` binary + engine orchestration
tests/fixtures         # bankapp + polyglot + docs fixtures
docs/PRD-v1.0.md       # full product specification

License

MIT — see LICENSE.

RFC-0020 exports and their evidence boundaries are documented in the implementation record.