diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index a27f5c4..34a32a0 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,30 +1,20 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Changelog: typedqliser -:toc: +== Changelog All notable changes to typedqliser will be documented in this file. -This format is based on https://keepachangelog.com/en/1.1.0/[Keep a Changelog], -and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning]. +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. -== [0.1.0] - 2026-03-21 +=== [0.1.0] - 2026-03-20 -=== Phase 1 — RSR Compliance Sweep +==== Added -=== Added -* Phase 1 complete — scaffold, CLI, manifest parser, codegen stubs, ABI types -* RSR compliance sweep — STATE.a2ml, contractiles, Justfile updated -* Bespoke contractile constraints for Query language type safety and formal verification domain -* Project-specific Justfile recipes - -== [0.0.1] - 2026-03-20 - -=== Added * Initial project scaffold from rsr-template-repo * CLI with subcommands (init, validate, generate, build, run, info) -* Manifest parser (`typedqliser.toml`) -* Codegen engine (stubs — target-language-specific implementation pending) +* Manifest parser (`+typedqliser.toml+`) +* Codegen engine (stubs — target-language-specific implementation +pending) * ABI module (Idris2 proof type definitions) * Library API for programmatic use * Full RSR template (17 CI workflows, governance docs, bot directives) diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8058b67..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,18 +0,0 @@ -# Changelog - -All notable changes to typedqliser will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [0.1.0] - 2026-03-20 - -### Added -- Initial project scaffold from rsr-template-repo -- CLI with subcommands (init, validate, generate, build, run, info) -- Manifest parser (`typedqliser.toml`) -- Codegen engine (stubs — target-language-specific implementation pending) -- ABI module (Idris2 proof type definitions) -- Library API for programmatic use -- Full RSR template (17 CI workflows, governance docs, bot directives) -- README.adoc with architecture overview and value proposition diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..82e6fd4 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,52 @@ +== PROOF-NEEDS.md + +=== Current State + +* *LOC*: ~6,000 +* *Languages*: Rust, Idris2, Zig +* *Existing ABI proofs*: `+src/interface/abi/*.idr+` (template-level) +* *Dangerous patterns*: None detected + +=== What Needs Proving + +==== Code Generation (src/codegen/) + +* Generates typed query code from schemas +* Prove: generated code is well-typed with respect to the input schema +* Prove: generated queries are equivalent to the schema specification + +==== Plugin System (src/plugins/) + +* `+sql.rs+` — SQL code generation +* `+wasm.rs+` — WASM code generation +* Prove: SQL generation produces valid SQL that matches the typed query +semantics +* Prove: WASM generation preserves query semantics + +==== ABI Module (src/abi/) + +* Rust ABI module — should have Idris2-backed contracts for type-safe +FFI + +==== Manifest Validation (src/manifest/) + +* Schema manifest parsing and validation +* Prove: manifest parsing is total and produces valid configurations + +=== Recommended Prover + +* *Idris2* for ABI contracts and codegen correctness specifications +* *Lean4* alternative for SQL equivalence proofs + +=== Priority + +*MEDIUM* — Code generator correctness is important but downstream of +VCL-total and TypeLL. Focus proofs on SQL generation first as it +directly affects data integrity. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 2c8d419..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,44 +0,0 @@ -# PROOF-NEEDS.md - - -## Current State - -- **LOC**: ~6,000 -- **Languages**: Rust, Idris2, Zig -- **Existing ABI proofs**: `src/interface/abi/*.idr` (template-level) -- **Dangerous patterns**: None detected - -## What Needs Proving - -### Code Generation (src/codegen/) -- Generates typed query code from schemas -- Prove: generated code is well-typed with respect to the input schema -- Prove: generated queries are equivalent to the schema specification - -### Plugin System (src/plugins/) -- `sql.rs` — SQL code generation -- `wasm.rs` — WASM code generation -- Prove: SQL generation produces valid SQL that matches the typed query semantics -- Prove: WASM generation preserves query semantics - -### ABI Module (src/abi/) -- Rust ABI module — should have Idris2-backed contracts for type-safe FFI - -### Manifest Validation (src/manifest/) -- Schema manifest parsing and validation -- Prove: manifest parsing is total and produces valid configurations - -## Recommended Prover - -- **Idris2** for ABI contracts and codegen correctness specifications -- **Lean4** alternative for SQL equivalence proofs - -## Priority - -**MEDIUM** — Code generator correctness is important but downstream of VCL-total and TypeLL. Focus proofs on SQL generation first as it directly affects data integrity. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/SECURITY.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index 0ceb28e..93bb0d0 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the typedqliser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..59df406 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,73 @@ +== TEST-NEEDS: typedqliser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +[width="100%",cols="40%,26%,34%",options="header",] +|=== +|Category |Count |Details +|*Source modules* |14 |Rust: main, lib, manifest/mod, codegen/mod, +abi/mod, plugins (mod, sql, wasm) + 3 Idris2 ABI + 3 Zig FFI + +|*Unit tests (inline)* |9 |All in plugins/wasm.rs + +|*Integration tests* |1 file |integration_test.rs (~76 #[test]) + +|*E2E tests* |0 |None + +|*Benchmarks* |0 |None +|=== + +=== What’s Missing + +==== E2E Tests + +* [ ] No test that generates code from a schema and validates the output +compiles +* [ ] No test for SQL plugin output against a real database +* [ ] No test for WASM plugin output in a WASM runtime + +==== Aspect Tests + +* [ ] *Security*: Code generator with no injection/escape tests – +generated SQL could be vulnerable +* [ ] *Performance*: No benchmarks for codegen throughput with large +schemas +* [ ] *Concurrency*: N/A +* [ ] *Error handling*: No tests for malformed schemas, circular +references, unsupported types + +==== Build & Execution + +* [ ] No Idris2 ABI compilation test +* [ ] Zig integration_test.zig likely template placeholder + +==== Benchmarks Needed + +* [ ] Codegen throughput (schemas with 10/100/1000 types) +* [ ] Generated code compilation time +* [ ] Plugin loading overhead + +==== Self-Tests + +* [ ] No self-diagnostic mode + +=== FLAGGED ISSUES + +* *76 integration tests is decent* but SQL plugin has 0 dedicated tests +* *Code generator with 0 output validation tests* – generates code that +may not compile +* *manifest module has 0 tests* – schema parsing untested +* *codegen module has 0 tests* – core functionality untested (only wasm +plugin tested) + +=== Priority: P1 (HIGH) + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index d0ad40d..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,51 +0,0 @@ -# TEST-NEEDS: typedqliser -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State - -| Category | Count | Details | -|----------|-------|---------| -| **Source modules** | 14 | Rust: main, lib, manifest/mod, codegen/mod, abi/mod, plugins (mod, sql, wasm) + 3 Idris2 ABI + 3 Zig FFI | -| **Unit tests (inline)** | 9 | All in plugins/wasm.rs | -| **Integration tests** | 1 file | integration_test.rs (~76 #[test]) | -| **E2E tests** | 0 | None | -| **Benchmarks** | 0 | None | - -## What's Missing - -### E2E Tests -- [ ] No test that generates code from a schema and validates the output compiles -- [ ] No test for SQL plugin output against a real database -- [ ] No test for WASM plugin output in a WASM runtime - -### Aspect Tests -- [ ] **Security**: Code generator with no injection/escape tests -- generated SQL could be vulnerable -- [ ] **Performance**: No benchmarks for codegen throughput with large schemas -- [ ] **Concurrency**: N/A -- [ ] **Error handling**: No tests for malformed schemas, circular references, unsupported types - -### Build & Execution -- [ ] No Idris2 ABI compilation test -- [ ] Zig integration_test.zig likely template placeholder - -### Benchmarks Needed -- [ ] Codegen throughput (schemas with 10/100/1000 types) -- [ ] Generated code compilation time -- [ ] Plugin loading overhead - -### Self-Tests -- [ ] No self-diagnostic mode - -## FLAGGED ISSUES -- **76 integration tests is decent** but SQL plugin has 0 dedicated tests -- **Code generator with 0 output validation tests** -- generates code that may not compile -- **manifest module has 0 tests** -- schema parsing untested -- **codegen module has 0 tests** -- core functionality untested (only wasm plugin tested) - -## Priority: P1 (HIGH) - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 69% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 88d6436..0b32362 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,19 @@ - - -# TOPOLOGY.md — typedqliser +== TOPOLOGY.md — typedqliser -## Purpose +=== Purpose -typedqliser adds formal type safety to any query language (SQL, GraphQL, Datalog, Cypher, and beyond) and is the #1 priority in the -iser family. It reads a `typedqliser.toml` manifest specifying the query language, database backend, and type-safety level (1–10), then type-checks queries against the database schema and generates typed query wrappers with optional proof certificates. typedqliser is designed for teams who need compile-time guarantees that queries are well-typed with respect to their schema, preventing entire classes of runtime errors. +typedqliser adds formal type safety to any query language (SQL, GraphQL, +Datalog, Cypher, and beyond) and is the #1 priority in the -iser family. +It reads a `+typedqliser.toml+` manifest specifying the query language, +database backend, and type-safety level (1–10), then type-checks queries +against the database schema and generates typed query wrappers with +optional proof certificates. typedqliser is designed for teams who need +compile-time guarantees that queries are well-typed with respect to +their schema, preventing entire classes of runtime errors. -## Module Map +=== Module Map -``` +.... typedqliser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, check, generate, build, run, info @@ -21,11 +26,11 @@ typedqliser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... typedqliser.toml manifest │ ┌────▼────┐ @@ -44,4 +49,4 @@ typedqliser.toml manifest ┌────▼────┐ │ CI gate │ exit 1 on type errors (--ci mode) └─────────┘ -``` +.... diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..4eb37dd --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — typedqliser (Developer) + +=== What is typedqliser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 46c13d4..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — typedqliser (Developer) - -## What is typedqliser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..b6da1a5 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — typedqliser (User) + +=== What is typedqliser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 395d06e..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — typedqliser (User) - -## What is typedqliser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture