codemble 0.3.0__tar.gz

codemble-0.3.0/.env.example

@@ -0,0 +1,7 @@
+# Codemble — bring your own key (pick one provider; never commit real keys).
+# Keys can also live in ~/.codemble/config — see docs: https://udhawan97.github.io/Codemble/installation/
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+CODEMBLE_PROVIDER=
+CODEMBLE_ANTHROPIC_MODEL=claude-sonnet-5
+CODEMBLE_OPENAI_MODEL=gpt-5.4-mini

codemble-0.3.0/.gitattributes

@@ -0,0 +1,3 @@
+# Generated Vite bundles embed shader/source strings whose intentional spaces
+# should not make repository-wide `git diff --check` fail.
+codemble/web_dist/** -whitespace

codemble-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug report
+description: Something broke, rendered wrong, or taught wrong.
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Security problems? Use [SECURITY.md](../../SECURITY.md), not a public issue.
+        **A wrong explanation or wrong check answer is a bug** — report it! Accuracy is the product.
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      placeholder: codemble 0.2.0 / abc1234
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Where did it go wrong?
+      options:
+        - Parser / graph (wrong structure)
+        - Galaxy UI (rendering, zoom, camera)
+        - Explanation (wrong or ungrounded)
+        - Language lens (wrong idiom claim)
+        - Checks (wrong answer or unfair question)
+        - Install / CLI
+        - Docs / website
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: A minimal code snippet that reproduces a wrong parse/explanation is gold.
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      placeholder: OS, Python version, browser
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Confirmations
+      options:
+        - label: I am not pasting any API keys or private code I can't share.
+          required: true

codemble-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & ideas
+    url: https://github.com/udhawan97/Codemble/discussions
+    about: Ask anything, share what your galaxy looks like.
+  - name: Security report (private)
+    url: https://github.com/udhawan97/Codemble/security/advisories/new
+    about: Never report security issues in public issues.

codemble-0.3.0/.github/ISSUE_TEMPLATE/early_tester.yml

@@ -0,0 +1,54 @@
+name: v0.2.0 early-tester report
+description: Report your first unaided run without sharing private code.
+labels: ["feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you. Do not paste source, private project names, credentials, or API keys.
+        Quote your confusion in your own words—the rough edges are the evidence we need.
+  - type: dropdown
+    id: install
+    attributes:
+      label: Install route
+      options:
+        - pipx from v0.2.0 Git tag
+        - uvx from v0.2.0 Git tag
+        - source checkout
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: macOS / Linux / Windows, Python version, browser
+    validations:
+      required: true
+  - type: textarea
+    id: confusion
+    attributes:
+      label: First confusing moment, verbatim
+      description: What did you expect, and what did you see instead?
+    validations:
+      required: true
+  - type: dropdown
+    id: lit
+    attributes:
+      label: Did you light one system without help?
+      options:
+        - "Yes"
+        - "No"
+    validations:
+      required: true
+  - type: textarea
+    id: correctness
+    attributes:
+      label: Anything structurally or educationally wrong?
+      description: Describe identifiers and line numbers only when safe; never paste private source.
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy check
+      options:
+        - label: I removed private code, project names, credentials, and API keys.
+          required: true

codemble-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature request
+description: Propose something that helps a learner understand their code.
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What can't a learner do or understand today?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Parser / adapters (new language?)
+        - Galaxy / rendering
+        - Explanations / language lens
+        - Checks / game loop
+        - CLI / install
+        - Docs / website
+    validations:
+      required: true
+  - type: checkboxes
+    id: fit
+    attributes:
+      label: Fit with Codemble's principles
+      options:
+        - label: This helps a learner understand their code (not just decorate the galaxy).
+          required: true
+        - label: This keeps explanations grounded — no invented structure.

codemble-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!-- Thanks! Keep it small and runnable. Link the CLAUDE.md milestone this serves. -->
+
+## What & why
+
+## Type
+- [ ] feat  - [ ] fix  - [ ] docs  - [ ] refactor  - [ ] test  - [ ] chore
+
+## Checklist
+- [ ] `pytest` and `ruff check .` pass
+- [ ] Conventional Commit(s), signed off (`-s`)
+- [ ] No API keys, no proprietary code samples
+- [ ] Project runs end-to-end after this change
+
+## If this touches the parser / graph
+- [ ] Unit tests cover the new structure
+- [ ] Unresolved calls are flagged, not dropped or invented
+
+## If this touches explanations (LLM)
+- [ ] Output remains grounded (real identifiers, `file:line` links)
+- [ ] Check answers still come from the graph, never the model

codemble-0.3.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule: { interval: monthly }
+  - package-ecosystem: npm
+    directory: "/docs-site"
+    schedule: { interval: monthly }
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule: { interval: monthly }

codemble-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: astro check
+        run: |
+          cd docs-site
+          npm install
+          npm run check
+  web-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: build web app
+        run: |
+          cd web
+          npm install
+          npm run check
+  package-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel and verify packaged SPA
+        run: |
+          python -m pip wheel . --no-deps --wheel-dir /tmp/codemble-wheel
+          python -c 'import pathlib, zipfile; wheel = next(pathlib.Path("/tmp/codemble-wheel").glob("*.whl")); names = zipfile.ZipFile(wheel).namelist(); assert "codemble/web_dist/index.html" in names; assert any(name.startswith("codemble/web_dist/assets/") for name in names)'

codemble-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,45 @@
+name: Docs (GitHub Pages)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs-site/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - uses: actions/configure-pages@v5
+      - name: Build Astro site
+        run: |
+          cd docs-site
+          npm install
+          npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/dist
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

codemble-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Verify the wheel carries the packaged SPA
+        run: python -c 'import pathlib, zipfile; wheel = next(pathlib.Path("dist").glob("*.whl")); names = zipfile.ZipFile(wheel).namelist(); assert "codemble/web_dist/index.html" in names; assert any(name.startswith("codemble/web_dist/assets/") for name in names)'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

codemble-0.3.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node / docs-site & web
+node_modules/
+docs-site/dist/
+docs-site/.astro/
+web/dist/
+
+# Env & local state
+.env
+.DS_Store
+logs/
+*.log
+
+# Editors
+.idea/
+.vscode/
+_to_delete/

codemble-0.3.0/.hallmark/log.json

@@ -0,0 +1,37 @@
+[
+  {
+    "date": "2026-07-19",
+    "macrostructure": "Map / Diagram",
+    "theme": "Observatory Instrument",
+    "enrichment": "none",
+    "brief": "Codemble deterministic galaxy renderer",
+    "critique": "P5 H5 E5 S5 R5 V5",
+    "slop_test": "pass (1-57, including 38a)"
+  },
+  {
+    "date": "2026-07-19",
+    "macrostructure": "Progress Ledger",
+    "theme": "Observatory Instrument",
+    "enrichment": "none",
+    "brief": "Codemble language star chart",
+    "variation": "syntax inventory rows with graph-derived progress"
+  },
+  {
+    "date": "2026-07-19",
+    "macrostructure": "Focused Readout",
+    "theme": "Observatory Instrument",
+    "enrichment": "none",
+    "brief": "Codemble graph-only active recall",
+    "variation": "one-question system overlay with a single illumination payoff",
+    "slop_test": "pass (plain controls, complete states, 320 px verified)"
+  },
+  {
+    "date": "2026-07-19",
+    "macrostructure": "Calibration Readout",
+    "theme": "Observatory Instrument",
+    "enrichment": "real product demo GIF",
+    "brief": "Codemble ambiguous Home and Unchartable states",
+    "variation": "ranked evidence rows, raw-source failure state, one 420ms glow pulse",
+    "slop_test": "pass (desktop and 320 px, reduced motion, no new visual language)"
+  }
+]

codemble-0.3.0/.hallmark/preflight.json

@@ -0,0 +1,9 @@
+{
+  "date": "2026-07-19",
+  "design_system": "docs-site/design.md",
+  "font_stack": ["Sora", "Inter", "JetBrains Mono"],
+  "framework": "Vite + React",
+  "motion": "custom house easing; no motion library",
+  "palette": "locked Observatory Instrument tokens",
+  "spacing": "4-point scale"
+}

codemble-0.3.0/.remember/now.md

@@ -0,0 +1,3 @@
+
+## 07:08 | friendly-wizard-claude/work-planning-f2e933
+Committed modes & Ollama spec (3-tier: struct + Gemma 4 12B + cloud), reversed Non-Goal, fixed cache & endpoint bugs, phases 1-3 (backend) queued.

codemble-0.3.0/.remember/tmp/last-ndc.ts

@@ -0,0 +1 @@
+1784461401

codemble-0.3.0/.remember/tmp/last-save-ts

@@ -0,0 +1 @@
+1784462904

codemble-0.3.0/.remember/tmp/last-save.json

@@ -0,0 +1 @@
+{"session": "391dcaa8-2bc2-4cf0-b18d-6a3dca5df88e", "line": 354}

codemble-0.3.0/.remember/tmp/save-session.pid

@@ -0,0 +1 @@
+77217

codemble-0.3.0/.remember/today-2026-07-19.md

@@ -0,0 +1,10 @@
+## 01:49 | friendly-helper-claude/codemble-website-redesign-235ec9
+Codemble: hero→Edo atlas+tatebanko parallax (Tatebanko.astro, build-plates.mjs); expandable search+docs/nav (Search.astro); landing→numbered plates.
+## 01:50 | friendly-helper-claude/codemble-website-redesign-235ec9
+Redesigned Codemble website (Edo star atlas); SVG plates; Tatebanko parallax hero; expandable Search; Starlight docs
+## 04:35 | friendly-wizard-claude/what-to-work-on-next-c1f75f
+Dogfood learner loop; fixed checks/service.py (4+ ans → 0 distract); verified 5 TESTING.md steps; began UI palette
+```
+## 06:42 | friendly-wizard-claude/work-planning-f2e933
+Reopened #13; defer v0.2.1 pending web-app-install-ux merge; scope coverage: 4 streams (HTML/CSS adapters, deepen langs, lens enrichment, easy/expert modes)
+```

codemble-0.3.0/AGENTS.md

@@ -0,0 +1,6 @@
+# Codemble — agent instructions
+Read CLAUDE.md in this directory in full before doing anything.
+It is the operating guide: follow its Session Protocol, maintain its
+Current State checkboxes and Decision Log, respect its Non-Goals and
+Correctness Contract. CLAUDE.md is the single source of truth; this file
+only points to it. Keep the two in sync by editing CLAUDE.md only.

codemble-0.3.0/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to Codemble are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-19
+
+### Added
+- Bare `codemble` now opens the browser to an in-app project picker: browse
+  home folders, reopen recent projects, and re-scope over-cap projects without
+  touching the terminal.
+- The local server rejects foreign `Host` headers, keeping the picker API
+  reachable only from the learner's own machine.
+- Codemble is published to PyPI, so installing is `uvx codemble` or
+  `pipx install codemble` with no git URL or tag.
+
+### Changed
+- `codemble` with flags but no path serves the picker instead of the current
+  directory; pass a path (or `--path`) for the previous behaviour.
+- Rebuilt the packaged app on the Formal Edo palette, so the galaxy and the
+  public site finally share one set of values. The app's tokens already imported
+  the site's, but `codemble/web_dist` had not been rebuilt since before the
+  redesign, so every shipped build still rendered the retired palette.
+- Self-hosted Shippori Mincho and Zen Kaku Gothic New in the app and dropped
+  Sora and Inter. The site loads these faces from the Google Fonts CDN; the app
+  must not, because it runs locally and offline. Net bundle change is smaller.
+- Illumination now owns the top of the brightness range: the unlit centrality
+  ramp stops at `--cm-ink-2` (8.2:1) and a lit star uses `--cm-star-high`
+  (12.1:1). Previously a busy un-understood module outshone an understood one
+  17.4:1 to 8.5:1, which inverted the meaning of lighting a region.
+
+### Fixed
+- Canvas colours authored as `color-mix()` reached WebGL as unparsed text and
+  rendered black, because a custom property returns its authored value rather
+  than a resolved colour. Affected unchartable nodes and every "possible call"
+  edge — exactly the uncertainty the Correctness Contract requires to stay
+  visible. Palette values are now resolved to plain `rgb()` before rendering.
+- The partial-parse notice said "its language parser" when reporting more than
+  one file.
+- Multi-answer checks offered no wrong option once a question had four or more
+  correct answers, so selecting every option lit the region without proving
+  anything. Checks now always offer wrong options alongside their answers, and a
+  question the graph cannot supply a wrong option for is dropped rather than
+  asked. On this repository the change removed all 17 such questions out of 107
+  while leaving every region's check count unchanged.
+
+### Added
+- Expanding site search in the header of both the landing page and every docs
+  page, backed by Pagefind with keyboard shortcut, arrow-key navigation, and an
+  explicit message when the index has not been built yet.
+- Generated Edo star-atlas plate artwork (`docs-site/scripts/build-plates.mjs`),
+  emitted from a fixed seed so the same script always produces the same sky.
+- A standalone landing page at `docs-site/src/pages/index.astro`, structured as
+  four numbered plates in 起承転結 order with a layered tatebanko hero.
+
+### Changed
+- Centralized graph canonicalization, Home selection, centrality, annotation
+  normalization, edge deduplication, and deterministic layout behind one graph
+  finalization interface shared by every language adapter and project composition.
+- Moved scale guarding and scope selection into `ProjectParser`, with one
+  reusable project intake that preserves adapter file ownership through parsing
+  instead of rediscovering the same scope in each adapter.
+- Moved learner navigation, language focus, study/check/Home requests, progress
+  refresh, and illumination sequencing behind one testable learner-session
+  interface with HTTP and in-memory adapters, leaving React to render snapshots.
+- Reused one internal JavaScript/TypeScript syntax-evidence index across
+  entrypoint, concept, call, binding, and imported-symbol resolution passes,
+  eliminating repeated ownership maps and whole-graph symbol scans.
+- Rebuilt the public site on the Formal Edo palette (kachi indigo, ruri lapis,
+  kohaku amber, gofun white) with Shippori Mincho and Zen Kaku Gothic New. The
+  accent contracts are unchanged: kohaku still means understanding, ruri still
+  means interaction.
+
+### Fixed
+- The current docs page was marked with a filled kohaku pill, which claimed
+  "understood" about a navigation state; it now uses ruri, the interaction accent.
+- The landing hero overflowed a 320px viewport, putting a call to action and the
+  install command outside the clipped area where they could not be reached.
+
+### Removed
+- `docs-site/src/content/docs/index.mdx`, replaced by the standalone landing
+  page; its content moved there.
+
+## [0.2.0] - 2026-07-19
+
+### Added
+- Language-neutral `ProjectParser` discovery and graph composition with global
+  Home selection, adapter collision checks, and Python graph-byte compatibility.
+- Official tree-sitter JavaScript/TypeScript adapter for JS, JSX, MJS, CJS, TS,
+  TSX, MTS, and CTS modules, definitions, imports, calls, entrypoint ranking,
+  exact source spans, file hashes, and honest partial-parse recovery.
+- Language-tagged graph schema 4 concept annotations plus deterministic
+  JavaScript/TypeScript Lens notes for async/await, arrows, destructuring,
+  optional chaining, nullish coalescing, modules, types, interfaces, generics,
+  and JSX.
+- Accessible language focus for mixed galaxies, systems, Study navigation, and
+  the star chart. It filters a view of the graph without changing coordinates,
+  progress, source truth, uncertainty, or cross-language navigation.
+- Phase 1 mixed-project fixtures, pure frontend focus/chart contracts, packaged
+  production SPA, public documentation, and a versioned `v0.2.0` wheel.
+
+## [0.1.0] - 2026-07-19
+
+### Added
+- Repository scaffold: README, CLAUDE.md agent brief, docs, docs-site (Astro + Starlight), CI, community files.
+- Deterministic Python AST parser with language-neutral graph models, source spans,
+  imports and calls with explicit certainty, entrypoint ranking, render metadata,
+  file hashes, partial-parse reporting, and schema-versioned JSON.
+- `codemble parse <path> --out graph.json` CLI command.
+- Parser fixture suite covering exact resolution, ambiguity, external calls,
+  ignored files, syntax errors, entrypoints, centrality, and byte determinism.
+- Deterministic galaxy and system coordinates with one source module per region,
+  aggregated import routes, LOC sizing, centrality brightness, and Home markers.
+- `codemble <path>` local FastAPI server with graph/source APIs, production SPA
+  serving, scripted three-level semantic zoom, keyboard navigation, responsive
+  observatory UI, WebGL failure handling, and a 1,000-node renderer probe.
+- Web build gate in CI and `scripts/dev.sh` for the backend/Vite development loop.
+- Study payloads with exact source lines, parser-proven neighbor evidence, and
+  clickable `file:line` citations in the responsive study panel.
+- Deep narration module with direct Anthropic Messages and OpenAI Responses
+  adapters, environment/TOML BYO-key configuration, file-hash disk caching,
+  response grounding validation, and explicit no-key/error states.
+- Parser-proven Python concept annotations for decorators, comprehensions,
+  generators, context managers, async/await, dunder methods, exception handling,
+  and type hints, serialized in graph schema 2.
+- Python Lens notes anchored to exact source lines plus a language star chart
+  that separates concepts encountered, structures studied this session, and
+  graph-derived understanding without inventing progress.
+- Four deterministic active-check families derived and scored only from call
+  edges, import edges, direct callers, and parser-ranked entrypoints.
+- Region illumination persisted atomically under `~/.codemble/progress`, with
+  per-region file signatures so editing one file re-dims only its own system.
+- Responsive System check flow with explicit wrong-answer evidence, suite
+  progress, restart-safe completion, and star-chart understanding updates.
+- Honest Home calibration when top-ranked entrypoints are ambiguous, plus a
+  parser-validated `--entrypoint` override.
+- A 300-file Phase 0 guard with interactive subdirectory selection and an
+  explicit non-interactive `--path` route.
+- Unchartable syntax-error nodes, raw-source access, and model narration
+  suppression for partial parses.
+- Production SPA assets inside the Python wheel, versioned `pipx`/`uvx` Git
+  install routes, an automated real-app demo recorder, and the v0.1.0 GIF.