diff --git a/.github/workflows/repository.yml b/.github/workflows/repository.yml new file mode 100644 index 0000000..592175c --- /dev/null +++ b/.github/workflows/repository.yml @@ -0,0 +1,26 @@ +name: Engine repository checks + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + repository: + name: Engine repository + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + - name: Check whitespace + run: git diff --check "$(git hash-object -t tree /dev/null)" HEAD + - name: Verify foundation files + run: | + test -s README.md + test -s AGENTS.md + test -s LICENSE + test -s THIRD_PARTY_LICENSES.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..295d799 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# Repository Guide + +## Language + +Write repository content, code comments, commit messages, issues, and pull requests in English. + +## Architecture + +- Keep the engine and formatter pure, deterministic, and independent of host I/O. +- Reuse `stack-sh/compiler` for language parsing and compiler-stage diagnostics. +- Reuse `stack-sh/theme` for the versioned core catalog, icons, and font metrics. +- Keep layout and SVG rendering as internal `stack-engine` modules unless a proven public boundary requires otherwise. +- Keep the native and WASM adapters aligned through shared fixtures rather than duplicate implementations. +- Do not add CLI filesystem behavior, user authentication, billing, entitlement, paid-theme delivery, or network access. + +## Delivery + +- Use a topic branch and pull request; squash merge after approval. +- Work in small increments that keep the workspace buildable and tested. +- Add repository-specific formatting, linting, tests, target builds, and artifact checks with the code that needs them. +- Record third-party dependency and bundled-asset obligations in `THIRD_PARTY_LICENSES.md` before publishing native or WASM artifacts. +- Keep credentials, tokens, private keys, signing material, and customer data out of Git. diff --git a/README.md b/README.md new file mode 100644 index 0000000..29ef6fd --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# Stack Engine + +`stack-sh/engine` is the pure Rust execution engine for Stack architecture diagrams. + +This repository currently contains only its repository foundation. Its crates and public APIs will be introduced incrementally after the compiler, formatter, and theme contracts they depend on are stable. + +## Planned workspace + +- `stack-engine`: compilation orchestration, theme resolution, deterministic layout, validation beyond the compiler stage, and standalone SVG rendering; +- `stack-formatter`: comment-preserving canonical formatting for Stack source files; +- a WebAssembly adapter exposing the same pure operations to browser consumers. + +The native CLI will link the Rust engine directly. Web clients will use the WASM adapter. Shared fixtures will verify that both targets produce equivalent diagnostics, formatted source, and SVG output. + +## Boundaries + +The engine may depend on `stack-sh/compiler` and `stack-sh/theme`. Core operations must be deterministic and must not require filesystem, environment, clock, random, or network access. + +CLI filesystem behavior, process exit codes, user authentication, billing, entitlement checks, and paid-theme delivery are outside this repository. + +## Development + +Repository checks currently validate the foundation files on every push and pull request. Rust formatting, linting, tests, target builds, and WASM package validation will be added with the first workspace increment. + +## Licensing + +This repository is licensed under the [Apache License 2.0](./LICENSE). Third-party dependencies or bundled assets must be tracked in [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md) before a distributable native or WASM artifact is published. diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md new file mode 100644 index 0000000..47a5349 --- /dev/null +++ b/THIRD_PARTY_LICENSES.md @@ -0,0 +1,5 @@ +# Third-party licenses + +No third-party dependency artifacts or assets are bundled in a Stack Engine distribution yet. + +Before publishing a native library, binary-derived artifact, or WASM package, this inventory must list the shipped dependencies and assets, their pinned versions, exact licenses, required license texts, attribution, modifications, and redistribution conditions. Build-only dependencies that are not shipped should be distinguished from distributed code.