From 47430753281c8df37d1abf941caff31465e9fb52 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 14:49:52 +0200 Subject: [PATCH 1/7] Trim .claude/CLAUDE.md to cut always-loaded context cost The file sat well over the documented ~200-line guidance for an always-loaded memory file. Removed content derivable from the codebase (directory-walkthrough prose, the internal steps of configure.sh, the flaky-test phase list that already lives in its linked dev-doc) and redundant restatements, keeping the non-guessable commands, file paths, subsystem registration points, and gotchas. 276 to 85 lines; no guidance a reader still needs was dropped. --- .claude/CLAUDE.md | 281 ++++++++-------------------------------------- 1 file changed, 45 insertions(+), 236 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 4566a0de093..f4e24769e81 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -4,273 +4,82 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Quarto is an open-source scientific and technical publishing system built on Pandoc. The CLI is written in TypeScript/Deno with Lua filters for document processing. +Quarto is an open-source scientific and technical publishing system built on Pandoc. The CLI is TypeScript/Deno with Lua filters for document processing. -### Versions +- Latest stable version: +- Latest prerelease version: -Latest stable is the version at: . Latest prerelease is at: - -## Setup & Configuration - -### Initial Setup +## Setup ```bash -# Clone and configure (downloads Deno, dependencies, and sets up symlink) -./configure.sh # Linux/macOS -./configure.cmd # Windows - -# The configure script: -# - Downloads and installs Deno to package/dist/bin/tools/ -# - Downloads Deno standard library -# - Runs quarto-bld configure -# - Vendors TypeScript dependencies -# - Creates symlink to quarto in your PATH +./configure.sh # Linux/macOS +./configure.cmd # Windows ``` -After configuration, the development version can be run via: - -- `quarto` command (if symlink configured) -- `package/dist/bin/quarto` (Linux/macOS) or `package/dist/bin/quarto.cmd` (Windows) +Downloads Deno + dependencies, runs `quarto-bld configure`, vendors TypeScript deps, and symlinks `quarto` into PATH. After this, run the dev build via `package/dist/bin/quarto` (Linux/macOS) or `package/dist/bin/quarto.cmd` (Windows). -### Configuration Files +**Key config files:** -- `configuration` - Version numbers for all binary and JavaScript dependencies (Deno, Pandoc, Dart Sass, etc.) -- `deno.jsonc` - Auto-generated Deno configuration (see dev-docs/update-deno_jsonc.md) -- `src/import_map.json` - Deno import mappings -- `src/dev_import_map.json` - Development import mappings +- `configuration` — version numbers for all binary/JS dependencies (Deno, Pandoc, Dart Sass, …) and the `QUARTO_VERSION` field +- `deno.jsonc` — auto-generated (see `dev-docs/update-deno_jsonc.md`) +- `src/import_map.json` / `src/dev_import_map.json` — Deno import mappings (production / development) ## Building & Testing -### Build Commands - -```bash -# Run the build script (TypeScript-based) -package/src/quarto-bld configure # Configure/bootstrap -package/src/quarto-bld prepare # Prepare distribution -``` - -### Building Schemas and Artifacts - -Use the `dev-call` command with `build-artifacts` argument: - ```bash -# Linux/macOS -package/dist/bin/quarto dev-call build-artifacts - -# Windows -package/dist/bin/quarto.cmd dev-call build-artifacts +package/src/quarto-bld configure # bootstrap +package/src/quarto-bld prepare # prepare distribution +package/dist/bin/quarto dev-call build-artifacts # regenerate schemas + editor tooling (.cmd on Windows) ``` -This command regenerates: - -- JSON schemas in `src/resources/schema/json-schemas.json` -- Zod schemas in `src/resources/types/zod/schema-types.ts` -- TypeScript type definitions in `src/resources/types/schema-types.ts` -- Editor tooling files (VSCode IntelliSense, YAML intelligence) +Use `quarto-bld` for builds, not direct Deno commands. `dev-call build-artifacts` regenerates JSON schemas (`src/resources/schema/json-schemas.json`), Zod + TypeScript types (`src/resources/types/`), and editor tooling files (VSCode IntelliSense, YAML intelligence). -### Running Tests - -Tests live in `tests/` and require R, Python, and Julia. See `.claude/rules/testing/overview.md` for commands, test types, dependencies, and debugging tips. +**Tests** live in `tests/` and require R, Python, and Julia. See `.claude/rules/testing/overview.md` for commands, test types, dependencies, and debugging. ```bash cd tests -./run-tests.sh smoke/render/render.test.ts # Linux/macOS -.\run-tests.ps1 smoke/render/render.test.ts # Windows +./run-tests.sh smoke/render/render.test.ts # Linux/macOS +.\run-tests.ps1 smoke/render/render.test.ts # Windows ``` -### Feature Format Matrix - -The feature format matrix in `dev-docs/feature-format-matrix/` documents and tests feature support across all output formats. - -- Test documents organized by feature in `qmd-files/` subdirectories -- Quality ratings in format metadata: `0` (broken/partial), `1` (good), `2` (excellent) -- Runs on CI via `.github/workflows/test-ff-matrix.yml` +**Feature format matrix** (`dev-docs/feature-format-matrix/`) documents and tests feature support across output formats. Test documents live in `qmd-files/` subdirectories with quality ratings `0` (broken/partial), `1` (good), `2` (excellent) in format metadata. Runs on CI via `.github/workflows/test-ff-matrix.yml`. ## Architecture -### Entry Point & Commands - -- `src/quarto.ts` - Main CLI entry point -- `src/command/command.ts` - Command registration -- Commands are organized in `src/command/*/cmd.ts` files: - - `render/` - Core rendering functionality - - `preview/` - Live preview server - - `publish/` - Publishing to various platforms - - `create/` and `add/` - Project/extension scaffolding - - `tools/`, `install/`, `check/` - Utilities - -### Core Systems - -**Project System** (`src/project/`) - -- `types/` - Project type implementations (book, website, manuscript, etc.) -- Project types are registered via `project/types/register.ts` -- Each type defines metadata, rendering behavior, and output structure - -**Format System** (`src/format/`) - -- Format handlers for different output types (HTML, PDF, DOCX, reveal.js, etc.) -- `formats.ts` - Format registry and resolution -- `format-handlers.ts` - Common format handling logic - -**Filter System** (`src/resources/filters/`) - -- Lua filters process Pandoc AST during rendering -- `main.lua` - Entry point for filter chain -- Organized by function: `crossref/`, `layout/`, `quarto-pre/`, `quarto-post/`, `quarto-finalize/` -- Custom AST nodes in `customnodes/` -- Common utilities in `common/` - -**Execution Engines** (`src/execute/`) - -- Integration with Jupyter, Knitr, and Observable for code execution -- Engine-specific handling for Python, R, Julia, and JavaScript - -**Resources** (`src/resources/`) - -- Static assets, templates, and bundled libraries -- Format-specific resources (HTML, PDF, reveal.js templates) -- Extensions (Confluence, Docusaurus, etc.) -- Pandoc datadir customizations - -### Key Subsystems - -**Preview System** (`src/preview/`) - -- Development server with live reload -- Watches for file changes and re-renders - -**Publishing System** (`src/publish/`) - -- Platform-specific publishers (Netlify, GitHub Pages, Confluence, etc.) -- Account management and deployment logic +Entry point is `src/quarto.ts`; commands register in `src/command/command.ts`, each implemented in `src/command//cmd.ts` (`render/`, `preview/`, `publish/`, `create/`, `add/`, `tools/`, `install/`, `check/`). -**Extension System** (`src/extension/`) +Core systems, each with a registration point used to extend it: -- Quarto extensions (filters, formats, shortcodes) -- Extension discovery, installation, and management +- **Projects** (`src/project/`) — types (book, website, manuscript, …) in `types/`, registered in `types/register.ts` +- **Formats** (`src/format/`) — handlers per output type; registry in `formats.ts`, common handling in `format-handlers.ts`, register new formats in `imports.ts` +- **Filters** (`src/resources/filters/`) — Lua filters over the Pandoc AST, chained from `main.lua`; organized as `crossref/`, `layout/`, `quarto-pre/`, `quarto-post/`, `quarto-finalize/`; custom AST nodes in `customnodes/`, shared helpers in `common/` +- **Execution engines** (`src/execute/`) — Jupyter, Knitr, Observable (Python/R/Julia/JS) +- **Resources** (`src/resources/`) — templates, bundled libraries, extensions, Pandoc datadir customizations +- **Preview** (`src/preview/`) — dev server with live reload +- **Publishing** (`src/publish/`) — platform publishers (Netlify, GitHub Pages, Confluence, …), account management, deployment logic +- **Extensions** (`src/extension/`) — filter/format/shortcode discovery, install, management -### Package/Distribution +Packaging lives in `package/`; build orchestration in `package/src/quarto-bld` (TypeScript); platform packaging in `package/src/{linux,macos,windows}/`. -- `package/` - Packaging and distribution scripts -- `package/src/quarto-bld` - Build orchestration script (TypeScript) -- Platform-specific packaging in `package/src/{linux,macos,windows}/` +**Key paths:** dev binary `package/dist/bin/quarto[.cmd]`; Deno binary `package/dist/bin/tools//deno`; distribution output `package/dist/`; vendored deps `src/vendor/`; Lua API TypeScript types `src/resources/lua-types/`. ## Development Patterns -### Debugging Flaky Tests - -Comprehensive methodology for debugging flaky tests documented in [dev-docs/debugging-flaky-tests.md](../dev-docs/debugging-flaky-tests.md). - -Key phases: - -1. Reproduce locally (outside CI) -2. Binary search to isolate culprit test -3. Narrow down within test file -4. Understand state change -5. Identify root cause -6. Verify solution - -### TypeScript/Deno Conventions - -- Use Deno-native APIs (avoid Node.js APIs) -- Import maps resolve dependencies (see `src/import_map.json`) -- Cliffy library used for CLI parsing -- File paths in imports must include `.ts` extension - -### Lua Filter Development - -- Filters run during Pandoc processing pipeline -- Use `quarto` Lua module for Quarto-specific APIs -- Common utilities in `src/resources/filters/common/` -- Filters are chained together in `main.lua` -- Documentation: - -### Adding New Commands - -1. Create command file in `src/command//cmd.ts` -2. Export command using Cliffy's `Command` API -3. Register in `src/command/command.ts` - -### Adding New Project Types - -1. Create implementation in `src/project/types//` -2. Implement `ProjectType` interface -3. Register in `src/project/types/register.ts` - -### Adding New Formats - -1. Create format definition in `src/format//` -2. Implement format handler -3. Register in `src/format/imports.ts` - -### LaTeX Error Detection - -LaTeX error pattern maintenance is documented in [dev-docs/tinytex-pattern-maintenance.md](../dev-docs/tinytex-pattern-maintenance.md). - -- Patterns inspired by TinyTeX's comprehensive regex.json -- Automated daily verification workflow checks for TinyTeX pattern updates -- Pattern location: `src/command/render/latexmk/parse-error.ts` -- Verification workflow: `.github/workflows/verify-tinytex-patterns.yml` - -## Important Conventions - -- Main branch: `main` -- Version defined in `configuration` file in `QUARTO_VERSION` field -- Binary dependencies (Deno, Pandoc, etc.) versions in `configuration` -- Use `quarto-bld` for build operations, not direct Deno commands -- Lua filters use Pandoc's filter infrastructure -- TypeScript types for Lua APIs in `src/resources/lua-types/` - -### Changelog Conventions - -- Changelog files live in `news/changelog-{version}.md` (e.g., `changelog-1.9.md`) -- Check `configuration` file for current `QUARTO_VERSION` -- See `.claude/rules/changelog.md` for comprehensive conventions (section hierarchy, entry format, backports, regression fixes) - -## Key File Paths - -- Quarto binary: `package/dist/bin/quarto` (Linux/macOS) or `package/dist/bin/quarto.cmd` (Windows) -- Deno binary: `package/dist/bin/tools//deno` -- Distribution output: `package/dist/` -- Vendored dependencies: `src/vendor/` - -## Documentation - -- Documentation is at -- Prerelease docs: for features in dev versions -- Dev documentation in `dev-docs/` includes: - - Checklists for releases and backports - - Dependency update procedures - - Internals guides - - Performance monitoring - -## Contributing - -See [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md) for contributing and pull request guidelines. - -## Maintaining Memory Files - -This project uses Claude Code memory files for AI-assisted development. When updating memory files: - -- **Add new feature area?** Create `.claude/rules//feature-name.md` with `paths:` frontmatter -- **Update existing feature?** Edit the relevant rule file -- **Deep dive doc needed?** Place it in `llm-docs/` and reference from rules - -**Memory file types:** - -| Location | When Loaded | Use For | -| -------------------------- | -------------------- | ------------------------------------ | -| `.claude/CLAUDE.md` | Always | Project overview, essential commands | -| `.claude/rules//` | When paths match | Feature-specific conventions | -| `llm-docs/` | When explicitly read | Architectural deep dives | +- **TypeScript/Deno:** use Deno-native APIs (avoid Node.js APIs); imports must include the `.ts` extension; dependencies resolve via import maps; CLI parsing uses Cliffy. +- **Adding a command / project type / format:** create the implementation (`src/command//cmd.ts`; `src/project/types//` implementing the `ProjectType` interface; or `src/format//`) then register it (in `command.ts`, `project/types/register.ts`, or `format/imports.ts` respectively). +- **Lua filters:** run during Pandoc processing, use the `quarto` Lua module, share helpers in `filters/common/`. API docs: +- **LaTeX error detection:** patterns in `src/command/render/latexmk/parse-error.ts` (inspired by TinyTeX's `regex.json`); daily workflow `.github/workflows/verify-tinytex-patterns.yml` checks for upstream updates. See `dev-docs/tinytex-pattern-maintenance.md`. +- **Debugging flaky tests:** methodology in `dev-docs/debugging-flaky-tests.md`. -**Personal overrides:** Create `CLAUDE.local.md` (gitignored) for personal preferences like preferred shell syntax or workflow customizations. This file is loaded alongside the project CLAUDE.md but won't be committed. +## Conventions -For setup details, see [dev-docs/claude-code-setup.md](../dev-docs/claude-code-setup.md). +- Main branch is `main`. Version is the `QUARTO_VERSION` field in the `configuration` file. +- **Changelog:** files at `news/changelog-{version}.md` (check `configuration` for the current `QUARTO_VERSION`). Full conventions in `.claude/rules/changelog.md`. +- Contributing / PR guidelines: `.github/CONTRIBUTING.md`. -## Additional Resources +## Documentation & Memory Files -- **LLM Documentation**: `llm-docs/` contains AI-specific guidance for working with the codebase -- **Rules Files**: `.claude/rules/` contains conditional guidance for specific file patterns -- **DeepWiki**: for AI-indexed documentation +- Docs: (stable), (dev features). DeepWiki: . +- `dev-docs/` — release/backport checklists, dependency-update procedures, internals guides, performance monitoring. +- `llm-docs/` — architectural deep dives, read on demand when a rule or task points to them. +- **Memory file layout:** `.claude/CLAUDE.md` always loaded (overview + essential commands); `.claude/rules//*.md` loaded when their `paths:` frontmatter matches (feature conventions); `llm-docs/` read on demand (deep dives). Personal overrides go in gitignored `CLAUDE.local.md`. Setup + maintenance: `dev-docs/claude-code-setup.md`. From 146b3b829195be13a945696997395244ed44c940 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 14:50:12 +0200 Subject: [PATCH 2/7] Add llm-docs discovery pointers via path-scoped rules The llm-docs/ deep-dive docs had no mechanism steering a reader to the relevant one when a matching task came up. Each topical doc now has a one-line discovery pointer inside a rule under .claude/rules/ whose paths: frontmatter matches the doc's own source, so it surfaces lazily only when that area is edited, with no added always-loaded cost. Topic-specific docs with no sufficiently narrow existing rule get a small dedicated rule, so e.g. a reveal.js pointer never loads on unrelated format work. The convention is documented in llm-docs-maintenance.md for future docs. --- .claude/rules/formats/axe-accessibility.md | 12 ++++++++++++ .claude/rules/formats/callout-styling.md | 9 +++++++++ .claude/rules/formats/pandoc-templates.md | 11 +++++++++++ .claude/rules/formats/revealjs.md | 9 +++++++++ .claude/rules/llm-docs-maintenance.md | 8 ++++++++ .claude/rules/packaging/code-signing.md | 10 ++++++++++ .claude/rules/preview/overview.md | 10 ++++++++++ .claude/rules/publishing/overview.md | 9 +++++++++ .claude/rules/rendering/localization.md | 9 +++++++++ .claude/rules/rendering/render-pipeline.md | 2 ++ .claude/rules/testing/smoke-all-tests.md | 2 ++ .claude/rules/typescript/deno-essentials.md | 2 ++ .claude/rules/typescript/quarto-api.md | 9 +++++++++ 13 files changed, 102 insertions(+) create mode 100644 .claude/rules/formats/axe-accessibility.md create mode 100644 .claude/rules/formats/callout-styling.md create mode 100644 .claude/rules/formats/pandoc-templates.md create mode 100644 .claude/rules/formats/revealjs.md create mode 100644 .claude/rules/packaging/code-signing.md create mode 100644 .claude/rules/preview/overview.md create mode 100644 .claude/rules/publishing/overview.md create mode 100644 .claude/rules/rendering/localization.md create mode 100644 .claude/rules/typescript/quarto-api.md diff --git a/.claude/rules/formats/axe-accessibility.md b/.claude/rules/formats/axe-accessibility.md new file mode 100644 index 00000000000..a7b26e0062c --- /dev/null +++ b/.claude/rules/formats/axe-accessibility.md @@ -0,0 +1,12 @@ +--- +paths: + - "src/format/html/format-html-axe*" + - "src/resources/**/*axe*" + - "tests/integration/playwright/tests/*axe*" +--- + +# Axe Accessibility Checks + +For the axe-core integration architecture across build-time TypeScript, compile-time SCSS, and runtime JS layers, see `llm-docs/axe-accessibility-architecture.md`. + +For the axe accessibility testing workflow (scan config, runtime DOM markers, output-mode patching), see `llm-docs/axe-accessibility-testing.md`. diff --git a/.claude/rules/formats/callout-styling.md b/.claude/rules/formats/callout-styling.md new file mode 100644 index 00000000000..7326e4ae24b --- /dev/null +++ b/.claude/rules/formats/callout-styling.md @@ -0,0 +1,9 @@ +--- +paths: + - "src/resources/formats/**/*callout*" + - "src/resources/filters/**/callout*" +--- + +# Callout Styling + +For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`. diff --git a/.claude/rules/formats/pandoc-templates.md b/.claude/rules/formats/pandoc-templates.md new file mode 100644 index 00000000000..91805b71b5c --- /dev/null +++ b/.claude/rules/formats/pandoc-templates.md @@ -0,0 +1,11 @@ +--- +paths: + - "src/resources/formats/pdf/pandoc/**" + - "src/resources/formats/typst/pandoc/**" +--- + +# Pandoc Templates (LaTeX & Typst) + +For how Pandoc's LaTeX templates are copied into Quarto and restructured into a modular form (`latex.template`, `latex.common`, …), see `llm-docs/pandoc-quarto-latex-templates.md`. + +For the equivalent Typst template integration (`typst.template`, `template.typst`), see `llm-docs/pandoc-quarto-typst-templates.md`. diff --git a/.claude/rules/formats/revealjs.md b/.claude/rules/formats/revealjs.md new file mode 100644 index 00000000000..3e26cd32a8c --- /dev/null +++ b/.claude/rules/formats/revealjs.md @@ -0,0 +1,9 @@ +--- +paths: + - "src/format/reveal/**" + - "src/resources/formats/revealjs/**" +--- + +# RevealJS Format + +For reveal.js format internals — metadata normalization, the two template files (`revealjs.template` vs `template.html`), and the TypeScript/Pandoc division of responsibility — see `llm-docs/revealjs-format-architecture.md`. diff --git a/.claude/rules/llm-docs-maintenance.md b/.claude/rules/llm-docs-maintenance.md index 16d5b97dded..5e5f533a6c8 100644 --- a/.claude/rules/llm-docs-maintenance.md +++ b/.claude/rules/llm-docs-maintenance.md @@ -55,3 +55,11 @@ They are NOT: - User documentation (that's at quarto.org) - Code comments (those live in source files) - Issue-specific notes (those go in PR descriptions) + +## Discovery Pointers + +So a relevant deep-dive actually gets read when a matching task comes up, each `llm-docs/*.md` should be reachable from a **discovery pointer** — a one-line "see `llm-docs/.md`" reference — placed inside a path-scoped rule under `.claude/rules/` whose `paths:` frontmatter matches the doc's own source files. This reuses the existing lazy-load gate at zero baseline context cost. + +Granularity rule: the pointer inherits its host rule's `paths:`, so it must live in a rule scoped **no broader than the doc's topic** — otherwise it loads on unrelated work (a reveal.js pointer does not belong in a rule scoped to all of `src/format/**`). If the best existing rule is too generic, create a small dedicated rule scoped to that doc's source instead. + +**When adding a new `llm-docs/*.md`:** add its discovery pointer to a matching path-scoped rule, or create a narrowly-scoped rule for it. diff --git a/.claude/rules/packaging/code-signing.md b/.claude/rules/packaging/code-signing.md new file mode 100644 index 00000000000..28b0f9cfef6 --- /dev/null +++ b/.claude/rules/packaging/code-signing.md @@ -0,0 +1,10 @@ +--- +paths: + - "package/src/macos/installer.ts" + - "package/src/windows/installer.ts" + - ".github/workflows/create-release.yml" +--- + +# Code Signing for Installers + +For how release installers get signed and notarized on macOS and Windows (Gatekeeper, SmartScreen, and the keychain/signing actions in `create-release.yml`), see `llm-docs/code-signing-installers.md`. diff --git a/.claude/rules/preview/overview.md b/.claude/rules/preview/overview.md new file mode 100644 index 00000000000..9ddd0b58eae --- /dev/null +++ b/.claude/rules/preview/overview.md @@ -0,0 +1,10 @@ +--- +paths: + - "src/command/preview/**" + - "src/project/serve/**" + - "src/preview/**" +--- + +# Preview System + +For how `quarto preview` works end-to-end — CLI entry, the branching logic in `cmd.ts`, single-file vs project preview lifecycle, and file watching — see `llm-docs/preview-architecture.md`. diff --git a/.claude/rules/publishing/overview.md b/.claude/rules/publishing/overview.md new file mode 100644 index 00000000000..e3e0fb5f7b1 --- /dev/null +++ b/.claude/rules/publishing/overview.md @@ -0,0 +1,9 @@ +--- +paths: + - "src/publish/**" + - "src/command/publish/cmd.ts" +--- + +# Publishing System + +For how `quarto publish` works internally — the `PublishProvider` interface, account management, and the end-to-end publish flow — see `llm-docs/publishing-architecture.md`. diff --git a/.claude/rules/rendering/localization.md b/.claude/rules/rendering/localization.md new file mode 100644 index 00000000000..77b2bf410c9 --- /dev/null +++ b/.claude/rules/rendering/localization.md @@ -0,0 +1,9 @@ +--- +paths: + - "src/core/language.ts" + - "src/resources/language/**" +--- + +# Localization + +For how localized strings flow from `_language.yml` through metadata merging into Pandoc templates and the crossref/authors/callouts Lua filters, see `llm-docs/localization-architecture.md`. diff --git a/.claude/rules/rendering/render-pipeline.md b/.claude/rules/rendering/render-pipeline.md index 8f30f11c099..856caaa535b 100644 --- a/.claude/rules/rendering/render-pipeline.md +++ b/.claude/rules/rendering/render-pipeline.md @@ -86,6 +86,8 @@ if (context?.config && isProjectInputFile(path, context)) { } ``` +For the full synthetic project mechanism (`projectContextForDirectory()`) and why two single-file code paths exist, see `llm-docs/synthetic-project-context.md`. + ## Format Resolution Metadata merges in this order (later overrides earlier): diff --git a/.claude/rules/testing/smoke-all-tests.md b/.claude/rules/testing/smoke-all-tests.md index b23088856ea..6863ae55c09 100644 --- a/.claude/rules/testing/smoke-all-tests.md +++ b/.claude/rules/testing/smoke-all-tests.md @@ -63,6 +63,8 @@ _quarto: - ['\\begin\{figure\}'] ``` +**Details:** `llm-docs/ensure-pdf-text-positions.md` — the `ensurePdfTextPositions` verification function for asserting spatial text-position relationships in tagged PDFs (Typst only; LaTeX not yet supported). + ### Regex Match Array Format `ensureFileRegexMatches` (and variants like `ensureTypstFileRegexMatches`, `ensureLatexFileRegexMatches`) takes two arrays: diff --git a/.claude/rules/typescript/deno-essentials.md b/.claude/rules/typescript/deno-essentials.md index 65d4cc78feb..6fe7b83bc3a 100644 --- a/.claude/rules/typescript/deno-essentials.md +++ b/.claude/rules/typescript/deno-essentials.md @@ -92,3 +92,5 @@ Common directives (use sparingly): 3. **Import from deno_ral** - Not directly from std library 4. **Use Deno APIs** - No Node.js equivalents 5. **Prefer sync APIs** - Simpler code flow for CLI + +For the `error()` / `warning()` / `info()` one-line message-formatting convention, see `llm-docs/error-messages.md`. diff --git a/.claude/rules/typescript/quarto-api.md b/.claude/rules/typescript/quarto-api.md new file mode 100644 index 00000000000..1690ba17cf7 --- /dev/null +++ b/.claude/rules/typescript/quarto-api.md @@ -0,0 +1,9 @@ +--- +paths: + - "src/core/api/**" + - "packages/quarto-types/**" +--- + +# Quarto API + +For adding or modifying methods in the Quarto API (`src/core/api/`, `packages/quarto-types/`) consumed by external execution engines, see `llm-docs/quarto-api.md`. From f870ae6d95e6297fe414334e50f63ff5340cd556 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 15:04:59 +0200 Subject: [PATCH 3/7] Deduplicate rule content and fix accuracy issues from rules audit CLAUDE.md: correct the filter list to pipeline order (quarto-pre runs before crossref/layout) and drop a run-tests example that merely repeated the testing/overview.md pointer beside it. Converge rule-to-rule duplication to single sources: filters/overview.md and schemas/zod-usage.md now point to dev-tools/dev-call-commands.md for the dev-call commands instead of restating them (also fixing a bare 'quarto' invocation that bypassed the dev binary), and testing/typescript-tests.md references testing/overview.md for the shared core-files table. --- .claude/CLAUDE.md | 10 ++-------- .claude/rules/filters/overview.md | 14 +------------- .claude/rules/schemas/zod-usage.md | 7 +------ .claude/rules/testing/typescript-tests.md | 6 +----- 4 files changed, 5 insertions(+), 32 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index f4e24769e81..7192a3ec86c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -34,13 +34,7 @@ package/dist/bin/quarto dev-call build-artifacts # regenerate schemas + editor t Use `quarto-bld` for builds, not direct Deno commands. `dev-call build-artifacts` regenerates JSON schemas (`src/resources/schema/json-schemas.json`), Zod + TypeScript types (`src/resources/types/`), and editor tooling files (VSCode IntelliSense, YAML intelligence). -**Tests** live in `tests/` and require R, Python, and Julia. See `.claude/rules/testing/overview.md` for commands, test types, dependencies, and debugging. - -```bash -cd tests -./run-tests.sh smoke/render/render.test.ts # Linux/macOS -.\run-tests.ps1 smoke/render/render.test.ts # Windows -``` +**Tests** live in `tests/` and require R, Python, and Julia. See `.claude/rules/testing/overview.md` for run commands, test types, dependencies, and debugging. **Feature format matrix** (`dev-docs/feature-format-matrix/`) documents and tests feature support across output formats. Test documents live in `qmd-files/` subdirectories with quality ratings `0` (broken/partial), `1` (good), `2` (excellent) in format metadata. Runs on CI via `.github/workflows/test-ff-matrix.yml`. @@ -52,7 +46,7 @@ Core systems, each with a registration point used to extend it: - **Projects** (`src/project/`) — types (book, website, manuscript, …) in `types/`, registered in `types/register.ts` - **Formats** (`src/format/`) — handlers per output type; registry in `formats.ts`, common handling in `format-handlers.ts`, register new formats in `imports.ts` -- **Filters** (`src/resources/filters/`) — Lua filters over the Pandoc AST, chained from `main.lua`; organized as `crossref/`, `layout/`, `quarto-pre/`, `quarto-post/`, `quarto-finalize/`; custom AST nodes in `customnodes/`, shared helpers in `common/` +- **Filters** (`src/resources/filters/`) — Lua filters over the Pandoc AST, chained from `main.lua`; run in pipeline order `quarto-pre/`, `crossref/`, `layout/`, `quarto-post/`, `quarto-finalize/`; custom AST nodes in `customnodes/`, shared helpers in `common/` - **Execution engines** (`src/execute/`) — Jupyter, Knitr, Observable (Python/R/Julia/JS) - **Resources** (`src/resources/`) — templates, bundled libraries, extensions, Pandoc datadir customizations - **Preview** (`src/preview/`) — dev server with live reload diff --git a/.claude/rules/filters/overview.md b/.claude/rules/filters/overview.md index d9d48bd030a..01ec0601d6b 100644 --- a/.claude/rules/filters/overview.md +++ b/.claude/rules/filters/overview.md @@ -68,19 +68,7 @@ Reach for it when a Pandoc *parsing* behavior must change before any filter can ## Debugging -**Filter tracing (recommended):** -```bash -# Linux/macOS -package/dist/bin/quarto dev-call show-ast-trace document.qmd - -# Windows -package/dist/bin/quarto.cmd dev-call show-ast-trace document.qmd -``` - -**AST diagram:** -```bash -quarto dev-call make-ast-diagram document.qmd -``` +Visualize filter transformations with the `dev-call` tools `show-ast-trace` (interactive trace viewer) and `make-ast-diagram` (static AST diagram) — see `.claude/rules/dev-tools/dev-call-commands.md` for both. ## Related Documentation diff --git a/.claude/rules/schemas/zod-usage.md b/.claude/rules/schemas/zod-usage.md index 1c3f3e61bb1..c9fd9bf2bad 100644 --- a/.claude/rules/schemas/zod-usage.md +++ b/.claude/rules/schemas/zod-usage.md @@ -59,9 +59,4 @@ YAML schema validation happens at config load time, so downstream code doesn't n ## Regenerating Schemas -After modifying YAML schema definitions: - -```bash -package/dist/bin/quarto dev-call build-artifacts # Linux/macOS -package/dist/bin/quarto.cmd dev-call build-artifacts # Windows -``` +After modifying YAML schema definitions, run `dev-call build-artifacts` — see `.claude/rules/dev-tools/dev-call-commands.md` § build-artifacts. diff --git a/.claude/rules/testing/typescript-tests.md b/.claude/rules/testing/typescript-tests.md index 64a72136e24..d34043a4aae 100644 --- a/.claude/rules/testing/typescript-tests.md +++ b/.claude/rules/testing/typescript-tests.md @@ -22,11 +22,7 @@ TypeScript-based tests using Deno. Smoke tests render documents; unit tests veri ## Core Infrastructure -| File | Purpose | -|------|---------| -| `tests/test.ts` | `testQuartoCmd()`, `testRender()`, `unitTest()` | -| `tests/verify.ts` | Verification functions (`noErrors`, `fileExists`, etc.) | -| `tests/utils.ts` | `docs()`, `outputForInput()`, path utilities | +Core test files (`test.ts`, `verify.ts`, `utils.ts`) are described in `.claude/rules/testing/overview.md` § Core Files. ### Search for an existing verifier before writing one From 80c986fd05fc0679543a65eed3f084f9c48cc962 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 15:21:24 +0200 Subject: [PATCH 4/7] Move callout discovery pointer into the sass-theming rule The callout CSS the doc covers lives in shared scss (_bootstrap-rules.scss, revealjs/quarto.scss) that a callout-specific glob cannot match, so a standalone callout rule never surfaced when that CSS was edited. sass-theming's paths already cover those scss files and callout styling is theming work, so the pointer belongs there alongside the sass-theming-architecture pointer. --- .claude/rules/formats/callout-styling.md | 9 --------- .claude/rules/formats/sass-theming.md | 2 ++ 2 files changed, 2 insertions(+), 9 deletions(-) delete mode 100644 .claude/rules/formats/callout-styling.md diff --git a/.claude/rules/formats/callout-styling.md b/.claude/rules/formats/callout-styling.md deleted file mode 100644 index 7326e4ae24b..00000000000 --- a/.claude/rules/formats/callout-styling.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -paths: - - "src/resources/formats/**/*callout*" - - "src/resources/filters/**/callout*" ---- - -# Callout Styling - -For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`. diff --git a/.claude/rules/formats/sass-theming.md b/.claude/rules/formats/sass-theming.md index 2d08f263e43..99f421dc775 100644 --- a/.claude/rules/formats/sass-theming.md +++ b/.claude/rules/formats/sass-theming.md @@ -20,3 +20,5 @@ background-color: var(--r-background-color, $body-bg); ``` Read `llm-docs/sass-theming-architecture.md` for full compilation pipeline details. + +For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`. From 3b979a06c6ccdb04d409165be609532cb74c8e84 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 15:23:07 +0200 Subject: [PATCH 5/7] Make CLAUDE.md the primary trigger for consulting llm-docs Path-scoped discovery pointers only fire once a matching source file is being edited, so they miss the planning/investigation phase where a subsystem deep-dive is most useful. CLAUDE.md is always loaded, so it now states when (before non-trivial work on an unfamiliar area) and how (ls llm-docs/, read the topic-named doc) to consult llm-docs/ directly, with the path-scoped rules as the lazy backstop. --- .claude/CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 7192a3ec86c..8eff42ea1de 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -75,5 +75,5 @@ Packaging lives in `package/`; build orchestration in `package/src/quarto-bld` ( - Docs: (stable), (dev features). DeepWiki: . - `dev-docs/` — release/backport checklists, dependency-update procedures, internals guides, performance monitoring. -- `llm-docs/` — architectural deep dives, read on demand when a rule or task points to them. +- `llm-docs/` — architecture deep-dives for major subsystems. **Before non-trivial work on an unfamiliar area — especially when planning or investigating, before any matching file is open — run `ls llm-docs/` (files are topic-named, e.g. `preview-architecture.md`, `sass-theming-architecture.md`) and read the relevant one.** Path-scoped rules under `.claude/rules/` also surface the matching doc when you edit its source, but that is a lazy backstop, not the primary trigger. - **Memory file layout:** `.claude/CLAUDE.md` always loaded (overview + essential commands); `.claude/rules//*.md` loaded when their `paths:` frontmatter matches (feature conventions); `llm-docs/` read on demand (deep dives). Personal overrides go in gitignored `CLAUDE.local.md`. Setup + maintenance: `dev-docs/claude-code-setup.md`. From 4d75df7acf0625749da0735ef04ddb727439023a Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 15:35:44 +0200 Subject: [PATCH 6/7] Restore narrow callout rule for non-scss callout files Moving the callout pointer wholesale into sass-theming dropped discovery for the doc's non-scss key files (styles-callout.html, callout.lua), since sass-theming only matches scss/theming paths. Restore a callout rule scoped just to those callout-specific files; sass-theming keeps the pointer for the shared scss. Together they cover all four of the doc's key files with no cross-topic pollution. --- .claude/rules/formats/callout-styling.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .claude/rules/formats/callout-styling.md diff --git a/.claude/rules/formats/callout-styling.md b/.claude/rules/formats/callout-styling.md new file mode 100644 index 00000000000..8d266b1584f --- /dev/null +++ b/.claude/rules/formats/callout-styling.md @@ -0,0 +1,11 @@ +--- +paths: + - "src/resources/formats/**/*callout*" + - "src/resources/filters/**/callout*" +--- + +# Callout Styling + +For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`. + +The shared SCSS where callout CSS lives (`_bootstrap-rules.scss`, `revealjs/quarto.scss`) is covered by the `sass-theming` rule, which also points to this doc. From 40fd2868e1a42df7499521077b6112b6e67b4ba5 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Thu, 16 Jul 2026 16:07:38 +0200 Subject: [PATCH 7/7] Widen pandoc-template and code-signing rules to their docs key source files The branch review found these two discovery rules omitted narrow, topic-specific source files their linked llm-docs list as key: the pandoc-template rule missed package/src/common/update-pandoc.ts (the writePandocTemplates updater that copies the templates), and the code-signing rule missed the macOS entitlements/distribution files and the keychain/sign-files GitHub actions. Adding them keeps each scope tight to its own topic. --- .claude/rules/formats/pandoc-templates.md | 1 + .claude/rules/packaging/code-signing.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/.claude/rules/formats/pandoc-templates.md b/.claude/rules/formats/pandoc-templates.md index 91805b71b5c..68c8d56e80c 100644 --- a/.claude/rules/formats/pandoc-templates.md +++ b/.claude/rules/formats/pandoc-templates.md @@ -2,6 +2,7 @@ paths: - "src/resources/formats/pdf/pandoc/**" - "src/resources/formats/typst/pandoc/**" + - "package/src/common/update-pandoc.ts" --- # Pandoc Templates (LaTeX & Typst) diff --git a/.claude/rules/packaging/code-signing.md b/.claude/rules/packaging/code-signing.md index 28b0f9cfef6..f5dce1da41a 100644 --- a/.claude/rules/packaging/code-signing.md +++ b/.claude/rules/packaging/code-signing.md @@ -2,7 +2,11 @@ paths: - "package/src/macos/installer.ts" - "package/src/windows/installer.ts" + - "package/scripts/macos/entitlements.plist" + - "package/scripts/macos/distribution.xml" - ".github/workflows/create-release.yml" + - ".github/workflows/actions/keychain/action.yml" + - ".github/workflows/actions/sign-files/action.yml" --- # Code Signing for Installers