Skip to content

Commit b997760

Browse files
authored
Merge branch 'main' into feat/typst-annotation-filename
2 parents f7fd416 + 2355f22 commit b997760

47 files changed

Lines changed: 920 additions & 161 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.claude/CLAUDE.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ The feature format matrix in `dev-docs/feature-format-matrix/` documents and tes
163163
Comprehensive methodology for debugging flaky tests documented in [dev-docs/debugging-flaky-tests.md](../dev-docs/debugging-flaky-tests.md).
164164

165165
Key phases:
166+
166167
1. Reproduce locally (outside CI)
167168
2. Binary search to isolate culprit test
168169
3. Narrow down within test file
@@ -236,8 +237,8 @@ LaTeX error pattern maintenance is documented in [dev-docs/tinytex-pattern-maint
236237

237238
## Documentation
238239

239-
- Documentation is at <https://quarto.org> with a sitemap at <https://quarto.org/sitemap.xml>
240-
- Prerelease docs: <https://prerelease.quarto.org/> for features in dev versions
240+
- Documentation is at <https://quarto.org/llms.txt>
241+
- Prerelease docs: <https://prerelease.quarto.org/llms.txt> for features in dev versions
241242
- Dev documentation in `dev-docs/` includes:
242243
- Checklists for releases and backports
243244
- Dependency update procedures
@@ -246,7 +247,7 @@ LaTeX error pattern maintenance is documented in [dev-docs/tinytex-pattern-maint
246247

247248
## Contributing
248249

249-
See CONTRIBUTING.md for pull request guidelines. Significant changes require a signed contributor agreement (individual or corporate).
250+
See [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md) for contributing and pull request guidelines.
250251

251252
## Maintaining Memory Files
252253

@@ -258,11 +259,11 @@ This project uses Claude Code memory files for AI-assisted development. When upd
258259

259260
**Memory file types:**
260261

261-
| Location | When Loaded | Use For |
262-
|----------|-------------|---------|
263-
| `.claude/CLAUDE.md` | Always | Project overview, essential commands |
264-
| `.claude/rules/<feature>/` | When paths match | Feature-specific conventions |
265-
| `llm-docs/` | When explicitly read | Architectural deep dives |
262+
| Location | When Loaded | Use For |
263+
| -------------------------- | -------------------- | ------------------------------------ |
264+
| `.claude/CLAUDE.md` | Always | Project overview, essential commands |
265+
| `.claude/rules/<feature>/` | When paths match | Feature-specific conventions |
266+
| `llm-docs/` | When explicitly read | Architectural deep dives |
266267

267268
**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.
268269

.claude/rules/testing/typescript-tests.md

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,8 +104,11 @@ const markdown = asMappedString("");
104104
const markdownWithContent = asMappedString("# Title\nSome content");
105105
```
106106

107-
**Mock ProjectContext:**
108-
```typescript
109-
import { createMockProjectContext } from "./utils.ts"; // tests/unit/project/utils.ts
110-
const project = createMockProjectContext(); // Creates temp dir + FileInformationCacheMap
111-
```
107+
**Mock Contexts:**
108+
109+
Several subsystems use context interfaces passed to functions. For unit tests, create `createMock*()` helpers with no-op stubs. Key pattern: async callbacks (like `withSpinner`) should just `await op()` so errors propagate normally. Check existing test files for helpers before writing new ones.
110+
111+
| Context | Interface | Existing helpers |
112+
|---------|-----------|-----------------|
113+
| `ProjectContext` | `src/project/types.ts` | `tests/unit/project/utils.ts``createMockProjectContext()` |
114+
| `InstallContext` | `src/tools/types.ts` | `tests/unit/tools/chrome-headless-shell.test.ts``createMockContext()` |

.github/CODE_OF_CONDUCT.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,13 @@ Examples of unacceptable behavior include:
3636
* Other conduct which could reasonably be considered inappropriate in a
3737
professional setting
3838
* Providing bad information by copying output from AI assistants
39-
without verifying its validity. This _specifically_ includes autonomous agents
40-
from OpenClaw, etc. We consider these account-bannable on first offense.
39+
without verifying its validity.
40+
* Submitting issues or pull requests via autonomous AI agents acting without
41+
human oversight. This _specifically_ includes autonomous agents such as
42+
OpenClaw. AI assistants are accepted only when a human contributor has
43+
reviewed and verified the submission (see [CONTRIBUTING.md](CONTRIBUTING.md)).
44+
Autonomous agents deciding on their own to open issues or PRs in this
45+
repository are not. We consider these account-bannable on first offense.
4146
You have been warned.
4247

4348
## Enforcement Responsibilities

.github/CONTRIBUTING.md

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,23 @@ You can contribute in many ways:
99
- By submitting Pull Request (PR) to fix opened issues
1010
- By submitting Pull Request (PR) to suggest new features (it is considered good practice to open an issue for discussion before working on a pull request for a new feature).
1111

12+
## Opening an issue
13+
14+
Before opening an issue, please search [existing issues](https://github.com/quarto-dev/quarto-cli/issues) to avoid duplicates.
15+
16+
When reporting a bug, include a minimal reproducible example. For feature requests, describe the use case and expected behavior.
17+
18+
### Using AI tools to investigate
19+
20+
If you are using an AI assistant to help investigate a bug or prepare an issue, point it to the Quarto codebase before asking it to analyze the problem:
21+
22+
- **[DeepWiki](https://deepwiki.com/quarto-dev/quarto-cli)** — AI-indexed documentation for the repository. Available as a web UI for human queries and as an [MCP server](https://docs.devin.ai/work-with-devin/deepwiki-mcp) to give your AI assistant direct access. Useful for understanding architecture, finding relevant source files, and asking questions about how Quarto works internally.
23+
- **[Context7](https://context7.com)** — Provides up-to-date Quarto documentation and related tool docs. Available as a web UI, a [cli tool](https://context7.com/docs/clients/cli) and as an [MCP server](https://context7.com/docs/resources/all-clients) so AI assistants can fetch current docs on demand.
24+
- **`https://quarto.org/llms.txt`** — Machine-readable index of Quarto documentation, following the [llms.txt convention](https://llmstxt.org/). Point your AI assistant at this URL to give it a structured map of available documentation.
25+
- **Clone the repo** — AI tools that can run code or search files benefit from a local clone. Cloning the repository lets the AI search source files, trace code paths, and verify behavior directly rather than relying on potentially outdated training data.
26+
27+
Grounding your AI assistant in the actual codebase leads to more accurate root cause analysis and better-quality issue reports.
28+
1229
## To submit a contribution using a Pull Request
1330

1431
1. [Fork](https://github.com/quarto-dev/quarto-cli/fork) the repository, clone it locally, and make your changes in a new branch specific to the PR. For example:
@@ -25,8 +42,6 @@ You can contribute in many ways:
2542
$ git checkout -b bugfix/myfix
2643
```
2744

28-
2. For significant changes (e.g more than small bug fixes), ensure that you have signed the [individual](https://posit.co/wp-content/uploads/2023/04/2023-03-13_TC_Indiv_contrib_agreement.pdf) or [corporate](https://posit.co/wp-content/uploads/2023/04/2023-03-13_TC_Corp_contrib_agreement.pdf) contributor agreement as appropriate. You can send the signed copy to <[email protected]>.
29-
30-
3. Submit the [pull request](https://help.github.com/articles/using-pull-requests). It is ok to submit as a draft if you are still working on it but would like some feedback from us. It is always good to share in the open that you are working on it.
45+
2. Submit the [pull request](https://help.github.com/articles/using-pull-requests). It is ok to submit as a draft if you are still working on it but would like some feedback from us. It is always good to share in the open that you are working on it.
3146

3247
We'll try to be as responsive as possible in reviewing and accepting pull requests. Very much appreciate your contributions!

.github/ISSUE_TEMPLATE/bug_report.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ body:
2222
2323
Finally, so that we can get the most out of your bug report, consider reading our ["Bug Reports" guide](https://quarto.org/bug-reports.html).
2424
25+
**Using an AI assistant to investigate?** Point it to the codebase first — see [Using AI tools to investigate](https://github.com/quarto-dev/quarto-cli/blob/main/.github/CONTRIBUTING.md#using-ai-tools-to-investigate) in CONTRIBUTING.md.
26+
2527
Thank you for using Quarto!
2628
2729
---

.github/pull_request_template.md

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@ Welcome to the quarto GitHub repo!
22

33
We are always happy to hear feedback from our users.
44

5-
To file a _pull request_, please follow these instructions carefully: <https://yihui.org/issue/#bug-reports>
6-
7-
If you're a collaborator from outside `quarto-dev` making changes larger than a typo, please make sure you have filed an [individual](https://posit.co/wp-content/uploads/2023/04/2023-03-13_TC_Indiv_contrib_agreement.pdf) or [corporate](https://posit.co/wp-content/uploads/2023/04/2023-03-13_TC_Corp_contrib_agreement.pdf) contributor agreement. You can send the signed copy to <[email protected]>.
5+
To file a _pull request_, please follow these instructions : <https://github.com/quarto-dev/quarto-cli?tab=contributing-ov-file>
86

97
Also, please complete and keep the checklist below.
108

@@ -22,9 +20,23 @@ print("Hello Quarto!")
2220

2321
I have (if applicable):
2422

25-
- [ ] filed a [contributor agreement](https://github.com/quarto-dev/quarto-cli/blob/main/CONTRIBUTING.md).
2623
- [ ] referenced the GitHub issue this PR closes
2724
- [ ] updated the appropriate changelog in the PR
2825
- [ ] ensured the present test suite passes
2926
- [ ] added new tests
3027
- [ ] created a separate documentation PR in [Quarto's website repo](https://github.com/quarto-dev/quarto-web/) and linked it to this PR
28+
29+
<!-- If an AI assistant helped prepare this PR, uncomment and complete this section:
30+
31+
<details>
32+
<summary>AI-assisted PR</summary>
33+
34+
- **AI tool used**: e.g., Claude Code, Copilot, ChatGPT
35+
- **Codebase grounding**: e.g., DeepWiki MCP, Context7 MCP, local clone, llms.txt
36+
- **Human review**: I have reviewed, tested, and verified the AI-generated content before submitting.
37+
38+
Note: autonomous AI agents submitting PRs without human oversight are not permitted — see the [Code of Conduct](CODE_OF_CONDUCT.md).
39+
40+
</details>
41+
42+
-->

.github/workflows/actions/quarto-dev/action.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,28 @@ runs:
1212
restore-keys: |
1313
${{ runner.os }}-deno_std-2-
1414
15+
- name: Cache Deno development cache
16+
uses: actions/cache@v5
17+
with:
18+
path: ./package/dist/bin/deno_cache
19+
key: ${{ runner.os }}-${{ runner.arch }}-deno-cache-v1-${{ hashFiles('configuration', 'src/import_map.json', 'src/vendor_deps.ts', 'tests/test-deps.ts', 'package/scripts/deno_std/deno_std.ts') }}
20+
restore-keys: |
21+
${{ runner.os }}-${{ runner.arch }}-deno-cache-v1-
22+
1523
- name: Configure Quarto (.sh)
1624
if: runner.os != 'Windows'
1725
shell: bash
26+
env:
27+
QUARTO_SKIP_DENO_CACHE_WIPE: "1"
1828
run: |
1929
# install with symlink in /usr/local/bin which in PATH on CI
2030
./configure.sh
2131
2232
- name: Configure Quarto (.ps1)
2333
if: runner.os == 'Windows'
2434
shell: pwsh
35+
env:
36+
QUARTO_SKIP_DENO_CACHE_WIPE: "1"
2537
run: |
2638
./configure.cmd
2739
"$(Get-ChildItem -Path ./package/dist/bin/quarto.cmd | %{ $_.FullName } | Split-Path)" >> $env:GITHUB_PATH

.github/workflows/cleanup-caches.yml

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,23 @@
1-
name: Cleanup github runner caches on closed pull requests
1+
name: Cleanup github runner caches
22
on:
3-
pull_request:
3+
# pull_request_target is required so fork PRs can delete their own caches on close.
4+
# pull_request from a fork ships a read-only GITHUB_TOKEN regardless of the
5+
# permissions: block, causing gh cache delete to fail with HTTP 403.
6+
# Safe here: no PR code is checked out, the workflow only calls gh cache list/delete.
7+
pull_request_target:
48
types:
59
- closed
10+
# Daily cleanup of stale julia caches on long-lived branches. julia-actions/cache@v3
11+
# does not run delete-old-caches on the default branch (by design, to avoid races
12+
# between concurrent runs), so caches accumulate. This job keeps only the newest
13+
# cache per (workflow, os) tuple.
14+
schedule:
15+
- cron: "0 4 * * *"
16+
workflow_dispatch:
617

718
jobs:
8-
cleanup:
19+
cleanup-pr:
20+
if: github.event_name == 'pull_request_target'
921
runs-on: ubuntu-latest
1022
permissions:
1123
actions: write
@@ -61,3 +73,81 @@ jobs:
6173
GH_TOKEN: ${{ github.token }}
6274
GH_REPO: ${{ github.repository }}
6375
BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge
76+
77+
cleanup-branches:
78+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
79+
runs-on: ubuntu-latest
80+
permissions:
81+
actions: write
82+
strategy:
83+
fail-fast: false
84+
matrix:
85+
ref:
86+
- refs/heads/main
87+
- refs/heads/v1.9
88+
steps:
89+
- name: Cleanup stale julia caches on ${{ matrix.ref }}
90+
run: |
91+
echo "::group::Julia cache list for $REF"
92+
93+
# Filter at source with --key (prefix match) so non-julia caches
94+
# don't push stale julia entries past the --limit window.
95+
caches=$(gh cache list --ref "$REF" --key julia-cache --limit 100 --json id,key,createdAt,sizeInBytes)
96+
total=$(echo "$caches" | jq 'length')
97+
98+
echo "Found $total julia cache(s) on $REF"
99+
100+
if [ "$total" -eq 0 ]; then
101+
echo "::endgroup::"
102+
echo "::notice::No julia caches on $REF"
103+
exit 0
104+
fi
105+
106+
# Group key is the cache key with run_id=... onwards stripped.
107+
# Sort by createdAt descending so the newest cache per group comes first;
108+
# awk keeps the first occurrence of each group (newest) and prints the rest.
109+
toDelete=$(echo "$caches" \
110+
| jq -r '.[] | "\(.createdAt)|\(.id)|\(.sizeInBytes)|\(.key | split(";run_id=") | .[0])"' \
111+
| sort -r \
112+
| awk -F'|' 'seen[$4]++ { print $2 "|" $3 "|" $4 }')
113+
114+
deleteCount=$(echo "$toDelete" | grep -c '|' || true)
115+
keepCount=$((total - deleteCount))
116+
117+
echo "Will delete $deleteCount stale cache(s), keep $keepCount newest per (workflow, os)"
118+
echo "::endgroup::"
119+
120+
if [ "$deleteCount" -eq 0 ]; then
121+
echo "::notice::Nothing to delete on $REF - all caches are already the newest per (workflow, os)"
122+
exit 0
123+
fi
124+
125+
## Do not fail the workflow on a single delete error.
126+
set +e
127+
128+
echo "::group::Deleting stale caches"
129+
deleted=0
130+
failed=0
131+
freedMb=0
132+
133+
while IFS='|' read -r id size group; do
134+
[ -z "$id" ] && continue
135+
mb=$((size / 1024 / 1024))
136+
echo "Deleting cache $id (${mb}MB) - group: $group"
137+
if gh cache delete "$id"; then
138+
echo " ✓ deleted"
139+
deleted=$((deleted + 1))
140+
freedMb=$((freedMb + mb))
141+
else
142+
echo " ✗ failed"
143+
failed=$((failed + 1))
144+
fi
145+
done <<< "$toDelete"
146+
147+
echo "::endgroup::"
148+
149+
echo "::notice::Cleanup complete on $REF: $deleted deleted (${freedMb}MB freed), $failed failed"
150+
env:
151+
GH_TOKEN: ${{ github.token }}
152+
GH_REPO: ${{ github.repository }}
153+
REF: ${{ matrix.ref }}

.github/workflows/test-install.yml

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,14 @@ on:
1010
- "v1.*"
1111
paths:
1212
- "src/tools/**"
13+
- "src/core/download.ts"
14+
- "src/core/retry.ts"
1315
- ".github/workflows/test-install.yml"
1416
pull_request:
1517
paths:
1618
- "src/tools/**"
19+
- "src/core/download.ts"
20+
- "src/core/retry.ts"
1721
- ".github/workflows/test-install.yml"
1822
schedule:
1923
# Weekly Monday 9am UTC — detect upstream CDN/API breakage
@@ -40,11 +44,31 @@ jobs:
4044
env:
4145
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
4246
run: |
43-
quarto install tinytex
47+
for attempt in 1 2 3; do
48+
if quarto install tinytex; then
49+
exit 0
50+
fi
51+
if [ "$attempt" -lt 3 ]; then
52+
echo "::warning::Attempt $attempt failed, retrying in 15s..."
53+
sleep 15
54+
fi
55+
done
56+
echo "::error::TinyTeX install failed after 3 attempts"
57+
exit 1
4458
4559
- name: Install Chrome Headless Shell
4660
run: |
47-
quarto install chrome-headless-shell --no-prompt
61+
for attempt in 1 2 3; do
62+
if quarto install chrome-headless-shell --no-prompt; then
63+
exit 0
64+
fi
65+
if [ "$attempt" -lt 3 ]; then
66+
echo "::warning::Attempt $attempt failed, retrying in 15s..."
67+
sleep 15
68+
fi
69+
done
70+
echo "::error::Chrome Headless Shell install failed after 3 attempts"
71+
exit 1
4872
4973
- name: Verify tools with quarto check
5074
run: |

0 commit comments

Comments
 (0)