hoodscript 1.1.0__tar.gz

hoodscript-1.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+node_modules/
+*.vsix
+src/hoodscript/_version.py

hoodscript-1.1.0/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+All notable changes to HoodScript. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: the keyword set is the public API; changing it is at least a minor bump.
+
+## [1.1.0] — 2026-09-11
+
+The reconciled language. Every keyword is now either cited in
+`hoodscript/docs/linguistics.md` or labeled plain English; the multi-token
+grammar forms from `GRAMMAR.md` are implemented; every error is explained in
+plain English.
+
+### Changed — keyword set (breaking)
+
+Applied the signed `GRAMMAR.md` v1.1 (Sprints 1–2). The v1.0.0 words had
+never been through the sourcing policy; on review most had no dictionary
+attestation of AAVE origin.
+
+| v1.0.0 | v1.1 | Reason |
+|---|---|---|
+| `cook` | `bet` | `cook`: attributed to one rapper, 2010 — fails the 2005 test. `bet`: M-W, AAE 1980s |
+| `serve` | `dip` | `serve`: no attestation. `dip`: "to leave, in black slang, early 20th c." (Dictionary.com) |
+| `crew` | `fam` | cut on re-verification in v1.0; `fam`: OED |
+| `holler` | `holla` | attested spelling (Smitherman; Dictionary.com) |
+| `Facts` / `Cap` | `no cap` / `cap` | `Facts` fails the 2005 test; `no cap` is the best-attested Tier B entry |
+| `Ghost` | `None` | no attestation found |
+| `mine` | `self` | plain English; Python's word |
+| `say` / `or_say` / `otherwise` | `if` / `else if` / `else` | plain English; Python's words |
+| `run_thru … up_in` | `be … in` | Tier A habitual *be* (YGDP) |
+| `keep_goin_if Facts` | `steady:` | Tier A intensive continuative (YGDP) |
+| `attempt` | `tryna` | Tier A |
+| `aint` | `ain't` | Tier A, apostrophe restored |
+| `on_the_side` / `hold_up` | `finna` / `done` | Tier A |
+| `crash_out` `catch_heat` `stand_on_it` `rock_with` `cut` `whole_city` `outside_scope` `inspect` `scenario` `keep_pushin` `bring_in` `outta` `quick_cook` `pass_it` `and_also` `or_else` `straight_is` | Python's word | invented compounds; not slang, not AAVE, not dictionary words |
+| `check_mic` `count_up` `span` `what_kind` `built_like` `word` `whole_num` `point_num` `lineup` `ledger` `circle` `locked_lineup` `unlock_file` `tally` `index_run` `pair_up` `every_single` `any_at_all` `weed_out` `apply_all` `ancestor` | Python's builtin | 21 English metaphors with no AAVE claim; every alias was a thing to learn |
+| `GhostFileTrip` / `StandOnItTrip` | `MissingFileTrip` / `AssertTrip` | their roots were cut |
+
+Kept: `chill` (`pass`, newly attested), `regardless`, `skip`, `catch`,
+`throw`, `ask`, and the `*Trip` exception family (`trip`: single source,
+kept by owner decision). Migration: `py2hood` on the `-c` output of an old
+file produces the new spelling; the crash reporter suggests `holla` when it
+sees `holler`.
+
+### Added
+
+- **Pattern layer** (`src/hoodscript/patterns.py`, Sprint 3): the multi-token
+  forms `ain't` / `ain't nobody` → `not`, `no cap` → `True`, `it's x` →
+  `(x is not None)`, `steady:` → `while True:`, `BIN X = v` → `X: Final = v`,
+  inclusive ranges `a..b` → `range(a, b + 1)`, `else if` → `elif`, and
+  statement-form `holla x, y` / `ask x`. Implemented as text edits at token
+  positions so bytes outside a pattern and every line number are untouched.
+- **JPE error engine** (`src/hoodscript/errors/`, Sprint 4): 35 catalogued
+  diagnostics `HS0001`–`HS0299`, each with what / why / fix in plain English
+  and a worked example the test suite executes. "Did you mean?" from the
+  names actually in scope (variables, attributes via `dir(obj)`, modules
+  including sibling `.hs` files, and the HoodScript keywords). Friendly type
+  names ("a whole number", not "a int"). SyntaxError messages re-worded in
+  HoodScript terms. Plain-text renderer always; `rich` panel on terminals
+  with the new `hoodscript[pretty]` extra. `--python-traceback` /
+  `HOODSCRIPT_PYTHON_TRACEBACK=1` escape hatch.
+- **Security hardening & sandbox** (`src/hoodscript/sandbox.py`, `SECURITY.md`, Sprint 6):
+  Capability gates (`--sandbox` / `HOODSCRIPT_SANDBOX=1`) default-closed:
+  `--allow-fs` (gates `open()` and filesystem stdlib via `NoAccessTrip` / `HS0121`),
+  `--allow-net` (gates `socket`, `urllib`, `http` imports), and
+  `--allow-clock` (gates `time`, `datetime`). Hard resource budgets: recursion
+  ceiling (`--max-depth`, default 256), output volume cap (`--max-output`, default 1,000,000 bytes,
+  `BudgetTrip` / `HS0131`), and wall-clock timeout (`--max-seconds`, default 10s,
+  `BudgetTrip` / `HS0130`). Hostile corpus in `tests/security/corpus/` refused with
+  plain-English JPE diagnostics; 100k-iteration front-end fuzz test verified.
+- **Developer tools suite & CLI tour** (`cli.py`, `repl.py`, `formatter.py`, `linter.py`, `tutor.py`, Sprint 7):
+  - CLI tour: Running `hoodscript` with no arguments prints a welcoming quick-start tour instead of an argparse dump.
+  - Subcommands: `run`, `build`, `check`, `fmt`, `lint`, `repl`, `tokens`, `learn`, `lsp`, `version`, `completion`.
+  - Formatter (`hoodscript fmt`): `hood2py` -> `ruff format` -> `py2hood`. Verified idempotent (`fmt(fmt(x)) == fmt(x)`) on the entire corpus and doc blocks.
+  - Linter (`hoodscript lint`): Plain-English diagnostics for unused variables (`HL001`), unreachable code (`HL002`), and type mismatches (`HL003` via `mypy`).
+  - Enhanced REPL (`hoodscript repl`): `--mirror` mode echoing Python line-by-line; persistent history (`~/.hoodscript_history`); multi-line continuation; tab autocompletion over keywords, builtins, and scope.
+  - Interactive tutor (`hoodscript learn`): Drives `docs/curriculum.md` lessons interactively across topics (`basics`, `flow`, `functions`, `classes`, `errors`, `async`, `mirror`, `all`).
+  - Shell completion: bash and zsh autocompletion scripts via `hoodscript completion [bash|zsh]`.
+- **Editor & debugger integration** (`editors/vscode/`, `lsp.py`, `debugger.py`, Sprint 8):
+  - VS Code extension: Packaged `.vsix` (`hoodscript-1.0.0.vsix`) with TextMate grammar for v1.1 keywords and patterns, snippets for `bet`/`fam`/`tryna`/`be`/`steady`/`finna`/`holla`/`ask`/`BIN`, `.hs` and `.hood` file association, language configuration, icon, and README.
+  - LSP enhancements: Go-to-definition and document symbols via `jedi` on 1:1 transpiled Python; formatting provider via `src/hoodscript/formatter.py`; real-time linter diagnostics integrated from `src/hoodscript/linter.py` (`hoodlint`).
+  - DAP Debugger (`hoodscript debug` / `src/hoodscript/debugger.py`): Native debugging on `.hs` files with `debugpy` preserving 1:1 line numbers and breakpoint mapping; bundled `launch.json` template for F5 execution and attach.
+- **Release packaging, dependency diet, and governance** (`pyproject.toml`, `CODE_OF_CONDUCT.md`, `.github/`, `docs/adr/`, Sprint 9):
+  - Zero required runtime dependencies: core package installs with `dependencies = []`. Dropped `pygments` and `libcst`. Extras partitioned into `[repl]`, `[lsp]`, `[pretty]`, and `[all]`.
+  - Dynamic versioning via `hatch-vcs` from git tag with `1.1.0` fallback; `hoodscript version` reports active release version.
+  - Governance: `CODE_OF_CONDUCT.md` adapted for linguistic respect and community safety; GitHub issue templates (bug report, feature request, and 7-step keyword proposal); PR checklist.
+  - Architecture Decision Records (`docs/adr/`): ADR-0001 (Token pipeline over parser), ADR-0002 (Linguistic sourcing & keyword reconciliation), ADR-0003 (Inclusive range syntax `a..b`).
+  - Release automation: `.github/workflows/release.yml` building and publishing to PyPI via Trusted Publishing on tag push.
+- **Client-side Web Playground** (`playground/`, `scripts/build_playground.py`, `src/hoodscript/cli.py`, Sprint 10):
+  - Pure WebAssembly runtime running Pyodide in a dedicated background Web Worker, loading the pure-Python `hoodscript` wheel built in Sprint 9.
+  - Interactive split-pane UI: left `.hood` editor with line-sync gutter and 4-space tab indentation; right pane showing real-time debounced 1:1 transpilation to Python.
+  - In-page JPE error engine: renders styled crash report cards (`HS0001`–`HS0299`) with "What happened", "Why", "Try this", and expandable Python traceback.
+  - Curriculum gallery: preloaded with lessons 1–10 from `docs/curriculum.md` and the canonical spec program from `GRAMMAR.md`.
+  - Zero-backend architecture: URL permalinks via fragment hash (`#code=...`), "Share" button copying link to clipboard.
+  - Strict Content Security Policy (`script-src 'self' ... 'wasm-unsafe-eval'`), zero `eval()` in page JS.
+  - Sandbox & Tab Safety: In-browser execution runs under default-closed `Sandbox()` (FS, Net, Clock gated); main-thread watchdog timer terminates hung workers (e.g. `runaway_time.hs` infinite loops) after 5 seconds and renders `HS0130 BudgetTrip` without freezing the browser tab.
+  - CLI subcommand: `hoodscript playground [--port PORT] [--no-browser]` serves the playground locally and launches the default browser.
+- `BadImportTrip` → `ImportError` in the `*Trip` family.
+- LSP: diagnostics use the error catalog (code, span, what + fix); hover
+  covers the pattern forms.
+- `docs/keywords.md`, generated from `constants.py` by
+  `scripts/gen_keywords.py`; a test fails if it is stale.
+- `MANUAL.md` (17 chapters), `docs/onboarding.md`, `docs/curriculum.md`
+  (10 lessons) rewritten for v1.1. Every ```hood block in the docs is
+  executed by the test suite, and where the doc shows output, the output is
+  asserted verbatim (Sprint 5).
+- `SPRINT_PLAN.md` reconciling six earlier planning documents; superseded
+  ones archived under `docs/archive/`.
+- Playground published to GitHub Pages by `.github/workflows/pages.yml` on every
+  push that touches it or the package: https://khaoticdev62.github.io/hoodscript/
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `PROMPTS.md` v2 (agent prompt pack aligned with
+  the audited repo; replaces the v1.0.0 generation prompt whose lexicon was cut).
+- CI on Ubuntu / macOS / Windows × Python 3.10–3.13, plus a build job.
+
+### QA audit of Sprints 6–10 (2026-09-11)
+
+Sprints 6–10 landed as one batch and were audited end to end before being
+accepted. Everything above is true *after* this pass; before it, twelve
+defects were found and fixed:
+
+- `hoodscript fmt` (and LSP formatting) rewrote `ain't` / `no cap` / `it's` /
+  `steady:` / `a..b` / `BIN` / `holla x` into Python and wrote it back. `py2hood`
+  now reverses every pattern form (`src/hoodscript/patterns.py::reverse_patterns`),
+  so `fmt` preserves the grammar and is idempotent on the full doc corpus.
+  One normalisation remains: `ain't nobody x` → `ain't x` (Python can't tell them apart).
+- Playground: the sandbox started a `threading.Timer`, impossible under Pyodide,
+  and `worker.js` imported a `deactivate()` that did not exist — every run would
+  have failed. Thread-less hosts now fall back to the JS watchdog; `deactivate()`
+  exists; the worker redirects stdout *before* activating so the output cap
+  applies. Verified in headless Chrome: transpile, run, `HS0001` with suggestion
+  and frames, `HS0121` sandbox refusal, `HS0131` output cap.
+- Wall-clock budget was a single catchable `KeyboardInterrupt`; a bare `catch:`
+  disabled it. Now two-stage: soft interrupt at the budget, hard `os._exit(3)`
+  with a report at budget + max(1 s, 20 %).
+- `hoodscript lint`: HL002 mapped ruff's return-*style* rules (`RET50x`) to
+  "unreachable" and missed real unreachable code; now an exact `ast` check.
+  HL003 never fired (mypy needs `--check-untyped-defs`). With ruff absent it
+  printed "No issues found." — now a clear message and exit 2; new `[tools]` extra.
+- `hoodscript learn` read `docs/curriculum.md` via the repo root — broken for
+  wheel installs; the curriculum now ships inside the package.
+- REPL: builtin completion used `dir(__builtins__)` (a dict); a bracket-continued
+  header (`bet f(a,` ⏎ `b):`) ran after its first body line.
+- Transpiler: NUL-byte location off by one; lone surrogates raised a raw
+  `UnicodeEncodeError`.
+- Crash reports lost their frames when the program's file is a pseudo-file
+  (`<hood>`, `<repl>`) and `sys.executable` is empty (Pyodide).
+- Debugger turned `exit()` into a crash report.
+- `SECURITY.md` claimed two exec sites; there are four (`tests/security/test_exec_sites.py` guards the list).
+- A local `v1.1.0` tag had been created on unaudited content; deleted. Tagging is a release decision.
+
+### Fixed
+
+- Transpiler no longer rewrites attribute names: `fut.done()` survives
+  `done` being a keyword (previously `s.cut(1)` became `s.del(1)`).
+- Running a file now puts its directory on `sys.path`, so `import sibling`
+  works from the `hoodscript` console script in any cwd.
+- Crash reports drop launcher frames (runpy, console script), pick the most
+  specific `*Trip` name (a `SyntaxError` is `BadSyntaxTrip`, not `Problem`),
+  and show file:line for compile-time errors.
+- REPL: one-line compound statements work; an error no longer ends the
+  session; `chill` exits as the banner says.
+- Piped output on Windows is UTF-8, so reports aren't mangled.
+- Three modules did not parse in the original 1.0.0 tree (newline escapes
+  had been expanded inside string literals); `migrator.py` lacked `import os`.
+- Transpiler intercepts embedded null bytes (`\x00`) with a clean `SyntaxError`
+  to avoid CPython 3.13 tokenizer crash, and maps `tokenize.TokenError` and
+  `UnicodeDecodeError` to syntax errors for JPE catalog handling.
+
+### Removed
+
+- `HOOD_BUILTINS` and builtin injection. The generated Python has no
+  HoodScript runtime in it at all.
+- `HOODSCRIPT_SPEC.md` (described a different product); duplicate root
+  copies of the prototype's `MANUAL.md`, `PROMPTS.md`, `SPRINT_0.md`.
+
+## [1.0.0] — 2026-09-11
+
+Initial release package: token-stream transpiler, PEP 451 import hook with
+PEP 552 bytecode cache, CLI, REPL, crash reports with `*Trip` names,
+`py2hood` / `hood2py`, stub generator, pygls language server (diagnostics,
+hover, completion). Keyword set later found to be uncited — see v1.1.0.
+
+[1.1.0]: https://github.com/khaoticdev62/hoodscript/compare/bf801ab...v1.1.0
+[1.0.0]: https://github.com/khaoticdev62/hoodscript/commits/bf801ab

hoodscript-1.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,69 @@
+# HoodScript Community Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free and empowering experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+HoodScript is built on African American Vernacular English (AAVE), a linguistic
+system with deep history, systematic grammatical rules, and rich cultural
+significance. We pledge to treat the language, its speakers, and the community
+that created it with rigor, authenticity, and respect.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy, kindness, and linguistic respect toward other people
+* Respecting the 1:1 mapping law and grammatical sourcing standards of HoodScript
+* Being respectful of differing opinions, viewpoints, and lived experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Mockery or trivialization of African American Vernacular English (AAVE) as
+  "broken English", "slang", or inferior grammar
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (code repositories, issue
+trackers, pull requests, discussion forums), and it also applies when an
+individual is officially representing the project in public spaces.
+
+## Reporting and Attribution
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

hoodscript-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to HoodScript
+
+Three rules govern everything else. Read them first.
+
+## The three rules
+
+### 1. The 1:1 Law
+
+> Every HoodScript construct maps to exactly one Python keyword, builtin, or
+> `ast` node. If it cannot, it does not enter the language.
+
+The implementation is a token rewrite (`src/hoodscript/transpiler.py`) plus a
+small pattern layer for multi-token forms (`src/hoodscript/patterns.py`).
+There is no parser, no intermediate representation, no template. **Line N of
+the generated Python is line N of the source, always** — the crash reporter,
+the language server, `linecache`, and every debugger rely on it. A change
+that inserts or removes a line is a bug.
+
+### 2. Rule Zero
+
+> Every keyword derives from a documented feature of AAVE — not from slang
+> vocabulary, and not from another language. Every other word is Python's
+> own, or plain English kept deliberately and labeled as such.
+
+**No keyword ships without a citation.** To propose one, follow the seven
+steps in [`hoodscript/docs/lexical-sourcing.md`](hoodscript/docs/lexical-sourcing.md) §5:
+classify (Tier A grammar / Tier B lexical), source it (a Yale GDP page for
+Tier A; two dictionaries stating AAVE origin for Tier B), grep CORAAL, run
+the currency/liability screen (`hoodscript/scripts/screen_keyword.py`), name
+the `ast` node, write the citation into
+[`hoodscript/docs/linguistics.md`](hoodscript/docs/linguistics.md), then add
+it to the table. Urban Dictionary is a screen, never a citation. A keyword
+that fails any step doesn't ship — and the rejection is recorded, because the
+cuts are the proof the policy works.
+
+Write about AAVE the way a linguist does: a rule-governed variety with a
+systematic grammar. Not "slang," not "broken English," no scare quotes.
+
+### 3. Never a raw traceback
+
+> A Python traceback must never reach the user for a HoodScript-level problem.
+
+Every error the system can produce has an entry in
+[`src/hoodscript/errors/catalog.py`](src/hoodscript/errors/catalog.py) with a
+stable code, a what / why / fix in plain English, and a worked example. The
+test suite refuses an entry without a working example. Prose rules are in the
+catalog's docstring: explain to a smart person who has never programmed,
+never blame, never "invalid" or "illegal," gloss every term in the same
+sentence. Read your message aloud; if it sounds like a compiler, rewrite it.
+
+## Setup
+
+```bash
+git clone https://github.com/khaoticdev62/hoodscript && cd hoodscript
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## The gate
+
+Before every push:
+
+```bash
+ruff check && pytest
+```
+
+That is exactly what CI runs, on Ubuntu, macOS, and Windows × Python
+3.10–3.13, plus a CLI smoke test. Python's exception *messages* differ between
+versions (`was never closed` vs `EOF in multi-line statement`), so a catalog
+pattern that passes locally can fail on another version — let the matrix
+tell you.
+
+## Where things live
+
+| Change | Where | Test that guards it |
+|---|---|---|
+| A single-word keyword | `src/hoodscript/constants.py` (after the sourcing procedure) | `tests/test_conformance.py` — add a case; `docs/keywords.md` must be regenerated (`scripts/gen_keywords.py > docs/keywords.md`) |
+| A multi-token form | `src/hoodscript/patterns.py` + a rule row in `GRAMMAR.md` | `tests/test_patterns.py`; `tests/test_grammar_canonical.py` holds the canonical program byte for byte |
+| An error explanation | `src/hoodscript/errors/catalog.py` | `tests/test_errors.py` runs every entry's example three ways |
+| A doc example | `README.md`, `MANUAL.md`, `docs/*.md` | `tests/test_docs.py` runs every ```hood block and asserts the documented output |
+| The CLI / REPL / LSP | `src/hoodscript/cli.py`, `repl.py`, `lsp.py` | CI smoke test; add to `tests/` |
+
+The `hoodscript/` subdirectory is the frozen Sprint 0–1 prototype: its
+linguistic research and sourcing policy are authoritative, its code is not.
+Don't build there.
+
+## Docs are tests
+
+Any ` ```hood ` block in the user docs is executed. If the next untagged
+code block in the same section shows output, that output is compared
+verbatim. Mark a block that is *supposed* to crash with `# expect-crash` as
+its first line. Show forms that don't run yet in a ` ```text ` fence, never
+` ```hood `.
+
+## Style
+
+- Dense is fine. The codebase uses one-line `def`s and `if x: y` where it
+  reads well; `E701`/`E702` are off deliberately. Line length 120.
+- Complete files. Never `# ... rest unchanged`.
+- Preserve comments, docstrings, and license notices.
+- Match the surrounding voice in docs: direct, second person, no hedging.
+
+## Commits and sprints
+
+Work follows [`SPRINT_PLAN.md`](SPRINT_PLAN.md), one sprint at a time, each
+with a gate. Commit at the gate with a message that says what changed and
+why; the changelog is written from those messages. Update `CLAUDE.md` when a
+decision changes — stale context is worse than none.
+
+## Working with an AI agent
+
+Paste the standing brief from [`PROMPTS.md`](PROMPTS.md) §0 at the top of
+the prompt and use the task template that matches the change. Never give an
+agent the v1.0.0 lexicon (`cook`, `serve`, …) or ask for `libcst`; both were
+cut deliberately and the tests will fail.
+
+## Reporting a bug
+
+The crash report's code (`HS0001`) plus the output of
+`hoodscript --python-traceback file.hs` is the ideal report. If you hit
+`HS9999` ("I don't have a plain-English explanation for this yet"), that's a
+catalog gap — please file it with the program that produced it.

hoodscript-1.1.0/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 HoodScript Core Contributors

hoodscript-1.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: hoodscript
+Version: 1.1.0
+Summary: A production-grade Python 3 conlang based on AAVE with 1:1 AST parity.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: jedi>=0.19.1; extra == 'all'
+Requires-Dist: mypy>=1.9.0; extra == 'all'
+Requires-Dist: prompt-toolkit>=3.0.40; extra == 'all'
+Requires-Dist: pygls<2,>=1.3.1; extra == 'all'
+Requires-Dist: rich>=13.7; extra == 'all'
+Requires-Dist: ruff>=0.3.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.1.0; extra == 'dev'
+Requires-Dist: debugpy>=1.8.0; extra == 'dev'
+Requires-Dist: hatch-vcs>=0.4.0; extra == 'dev'
+Requires-Dist: jedi>=0.19.1; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: prompt-toolkit>=3.0.40; extra == 'dev'
+Requires-Dist: pygls<2,>=1.3.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: rich>=13.7; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: lsp
+Requires-Dist: jedi>=0.19.1; extra == 'lsp'
+Requires-Dist: pygls<2,>=1.3.1; extra == 'lsp'
+Provides-Extra: pretty
+Requires-Dist: rich>=13.7; extra == 'pretty'
+Provides-Extra: repl
+Requires-Dist: prompt-toolkit>=3.0.40; extra == 'repl'
+Provides-Extra: tools
+Requires-Dist: mypy>=1.9.0; extra == 'tools'
+Requires-Dist: ruff>=0.3.0; extra == 'tools'
+Description-Content-Type: text/markdown
+
+# HoodScript
+
+A Python 3 dialect whose grammar keywords come from documented features of
+African American Vernacular English, with **strict 1:1 mapping to Python** and
+**crash reports written in plain English**.
+
+```hood
+bet greet(who, greeting="wassup"):
+    dip greeting + ", " + who
+
+fam Dog:
+    bet __init__(self, name):
+        self.name = name
+    bet speak(self):
+        dip self.name + " says woof"
+
+be i in 1..3:
+    holla greet("fam"), Dog("Rex").speak(), i
+```
+
+Every keyword is one Python keyword under a different name. `bet` *is* `def`.
+`dip` *is* `return`. `be` *is* `for`. Nothing is added, nothing is
+reinterpreted. That means:
+
+- `.hs` files can import any Python package (`numpy`, `fastapi`, `json`, …)
+- Python files can import `.hs` modules after one line: `hoodscript.install()`
+- Type checkers, linters, profilers, and debuggers all work on the output
+- `hood2py` gives you back plain Python whenever you want to leave
+
+**Every keyword is cited.** Tier A grammar words (`be`, `finna`, `done`,
+`tryna`) each have a Yale Grammatical Diversity Project page. Tier B lexical
+words (`bet`, `fam`, `holla`, `dip`, `chill`, `cap`) each have dictionary
+attestation of AAVE origin. The rest is Python's own word or plain English,
+labeled as such. Sources: [`hoodscript/docs/linguistics.md`](hoodscript/docs/linguistics.md).
+Spec: [`GRAMMAR.md`](GRAMMAR.md). Full table: [`docs/keywords.md`](docs/keywords.md).
+
+## Try it in the browser
+
+**[khaoticdev62.github.io/hoodscript](https://khaoticdev62.github.io/hoodscript/)** —
+HoodScript on the left, the exact Python on the right, live. Runs entirely in
+your browser (Pyodide); nothing is sent anywhere. Programs run inside the
+sandbox, so `import os` is refused and a runaway loop is stopped.
+
+## Install
+
+```bash
+git clone https://github.com/khaoticdev62/hoodscript && cd hoodscript
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Requires Python ≥ 3.10. To try it with **no install at all**, prefix commands
+with `PYTHONPATH=src` and use `python3 -m hoodscript` instead of `hoodscript`.
+
+## Run
+
+```bash
+hoodscript hello.hs           # transpile + execute
+hoodscript -c hello.hs        # print the Python it becomes
+hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
+hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
+hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
+hoodscript                    # a short tour of all commands
+hoodscript lsp                # language server over stdio, for editors
+hoodscript make-stubs f.py    # emit a .pyi-style stub with empty bodies
+```
+
+## Convert
+
+```bash
+hood2py program.hs > program.py     # HoodScript → Python
+py2hood program.py > program.hs     # Python → HoodScript
+```
+
+Both are token-level rewrites: comments, spacing, and line numbers survive
+round-trips untouched.
+
+## Crash reports
+
+Unhandled exceptions never show a raw Python traceback. Every error is
+translated into plain English — what happened, why, and what to do — with a
+"did you mean?" computed from what was actually in scope:
+
+```
+🚨 HOODSCRIPT CRASH REPORT — HS0001 UnknownNameTrip
+
+  File "boom.hs", line 4, in <module>()
+    main()
+  File "boom.hs", line 3, in main()
+    holla totl
+          ^^^^
+
+What happened: I can't find anything called 'totl'.
+Why: Nothing gave 'totl' a value before line 3, or it was spelled differently when it was created.
+Fix: Did you mean 'total'? If not, set it first: `totl = ...` above this line.
+
+(run with --python-traceback to see the raw Python error)
+```
+
+Thirty-five catalogued diagnostics (`HS0001`–`HS0299`), each with a worked
+example that the test suite executes. `pip install "hoodscript[pretty]"` adds
+colour and a box on terminals. `--python-traceback` shows the raw Python when
+you're debugging the compiler rather than a program.
+
+## The language in one screen
+
+| Python | HoodScript | | Python | HoodScript |
+|---|---|---|---|---|
+| `def` / `return` | `bet` / `dip` | | `try` / `except` / `finally` | `tryna` / `catch` / `regardless` |
+| `class` | `fam` | | `raise` | `throw` |
+| `for` | `be` | | `continue` / `pass` | `skip` / `chill` |
+| `async` / `await` | `finna` / `done` | | `False` | `cap` |
+| `print` / `input` | `holla` / `ask` | | `ValueError`, `KeyError`, … | `BadValueTrip`, `MissingKeyTrip`, … |
+| `True` | `no cap` | | `not` | `ain't` / `ain't nobody` |
+| `while True:` | `steady:` | | `x is not None` | `it's x` |
+| `X: Final = v` | `BIN X = v` | | `range(a, b + 1)` | `a..b` |
+| `elif` | `else if` | | | |
+
+Everything else — `if`, `else`, `while`, `import`, `with`, `match`, `None`,
+`self`, every builtin — is Python's own word, and every Python keyword still
+works in a `.hs` file.
+
+## Learn
+
+- [`docs/onboarding.md`](docs/onboarding.md) — from zero to a running program in ten minutes
+- [`docs/curriculum.md`](docs/curriculum.md) — ten lessons, each with a runnable file
+- [`MANUAL.md`](MANUAL.md) — the full manual
+- [`agents.md`](agents.md) — architecture and subsystem walkthrough
+- [`CLAUDE.md`](CLAUDE.md) — the standing brief for anyone (human or agent) changing the code
+- [`SPRINT_PLAN.md`](SPRINT_PLAN.md) — what's next · [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Repo layout
+
+```
+src/hoodscript/   the package (transpiler, importer, cache, CLI, REPL, LSP, migrator)
+tests/            pytest suite — includes one conformance test per keyword and one run per doc example
+docs/             onboarding, curriculum, generated keyword table, archived plans
+scripts/          gen_keywords.py
+editors/vscode/   extension manifest
+hoodscript/       Sprint 0–1 prototype: linguistic research, sourcing policy, v1.0 grammar — reference only
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).