Skip to content

Commit 747e3a5

Browse files
committed
Merge upstream/main into chore/deps-v1.12-simple
2 parents 74921e1 + 7d1eeb3 commit 747e3a5

173 files changed

Lines changed: 4854 additions & 429 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/rules/testing/typescript-tests.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,12 +86,17 @@ unitTest("feature - description", async () => {
8686

8787
Assertions come from `tests/asserts.ts` (relative path, e.g. `../asserts.ts` from `tests/unit/`), never from a std assertion module directly; the Runtime Boundary check flags a direct std import in tests. Exports: `assert`, `assertEquals`, `assertThrows`, `assertRejects`, `assertMatch`, `assertObjectMatch`, `assertStringIncludes`, `fail`, `AssertionError`
8888

89+
Tests follow the same runtime rule as `src/`: no new `Deno.*` calls, import the equivalent from `src/deno_ral/` (`fs.ts`, `temp.ts`, `path.ts`). The Runtime Boundary check counts `Deno.*` calls in `tests/` against a baseline and fails the PR on an increase. Before accepting an increase, check `src/deno_ral/` and `tests/utils.ts` (`writeFixture`, `withTempDir`) for an existing helper. See `.claude/rules/typescript/deno-ral.md`.
90+
8991
## Common Patterns
9092

9193
**Temp files:**
9294
```typescript
93-
const workingDir = Deno.makeTempDirSync({ prefix: "quarto-test" });
94-
// Use workingDir, clean up in teardown
95+
import { withTempDir } from "../utils.ts";
96+
97+
await withTempDir(async (workingDir) => {
98+
// Use workingDir; it is removed when the callback returns
99+
});
95100
```
96101

97102
**Fixtures:**

‎.claude/rules/typescript/deno-essentials.md‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -49,19 +49,15 @@ import { join } from "jsr:/@std/path";
4949

5050
## Deno APIs vs Node.js
5151

52-
Use Deno APIs directly:
52+
Import from the runtime layer (`src/deno_ral/`) instead of calling `Deno.*` directly:
5353

5454
```typescript
55-
// Correct - Deno APIs
56-
Deno.env.get("PATH");
57-
Deno.cwd();
58-
Deno.readTextFileSync(path);
59-
Deno.writeTextFileSync(path, content);
60-
Deno.makeTempDirSync({ prefix: "quarto" });
55+
// Correct - runtime layer
56+
import { readTextFileSync, writeTextFileSync } from "../deno_ral/fs.ts";
57+
import { makeTempDirSync } from "../deno_ral/temp.ts";
6158

62-
// Wrong - Node.js patterns
63-
process.env.PATH;
64-
fs.readFileSync(path);
59+
// Wrong - direct runtime calls (the CI ratchet counts these)
60+
Deno.readTextFileSync(path);
6561
```
6662

6763
## Sync vs Async
@@ -86,6 +82,7 @@ if (isWindows) {
8682
## Lint Directives
8783

8884
Common directives (use sparingly):
85+
8986
- `no-explicit-any` - For Cliffy options, JSON parsing
9087
- `no-control-regex` - For regex with control characters
9188

‎.claude/rules/typescript/deno-ral.md‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,16 @@ The `deno_ral/` directory provides a runtime abstraction layer over Deno's stand
99

1010
## Available Modules
1111

12-
| Module | Purpose | Key exports |
13-
|--------|---------|-------------|
14-
| `fs.ts` | File system | `existsSync`, `ensureDirSync`, `copySync`, `safeMoveSync`, `safeRemoveSync` |
15-
| `path.ts` | Path utilities | `join`, `dirname`, `basename`, `extname` |
16-
| `log.ts` | Logging | `debug`, `info`, `warning`, `error` |
17-
| `kv.ts` | Deno KV cache stores | `openKv`, `getKv`, `kvOp`, `KvDamagedError` |
18-
| `platform.ts` | Platform detection | `isWindows` |
19-
| `process.ts` | Process execution | Process utilities |
12+
| Module | Purpose | Key exports |
13+
| ------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| `fs.ts` | File system | `readTextFileSync`, `writeTextFileSync`, `statSync`, `readDirSync` (sorted), `removeSync`, `mkdirSync`, `copyFileSync`, `open`, `canonicalPathSync` (resolves symlinks), `existsSync`, `ensureDirSync`, `copySync`, `safeMoveSync`, `safeRemoveSync`; types `FileInfo`, `DirEntry`, `FsFile` |
15+
| `temp.ts` | Temp files/dirs (retry on AlreadyExists) | `makeTempDirSync`, `makeTempDir`, `makeTempFileSync`, `makeTempFile`; type `TempOptions` |
16+
| `errors.ts` | Runtime-neutral error predicates | `isNotFound`, `isAlreadyExists`, `isPermissionDenied`, `isAddrInUse`, `isConnectionRefused`, `isConnectionError`, `errorWithPath` |
17+
| `path.ts` | Path utilities | `join`, `dirname`, `basename`, `extname` |
18+
| `log.ts` | Logging | `debug`, `info`, `warning`, `error` |
19+
| `kv.ts` | Deno KV cache stores | `openKv`, `getKv`, `kvOp`, `KvDamagedError` |
20+
| `platform.ts` | Platform detection | `isWindows` |
21+
| `process.ts` | Process execution | Process utilities |
2022

2123
## Why Use deno_ral
2224

@@ -28,6 +30,7 @@ The `deno_ral/` directory provides a runtime abstraction layer over Deno's stand
2830
## Common Utilities
2931

3032
**Temp files** (`src/core/temp.ts`):
33+
3134
```typescript
3235
import { createTempContext } from "../core/temp.ts";
3336

@@ -40,6 +43,7 @@ try {
4043
```
4144

4245
**Process execution** (`src/core/process.ts`):
46+
4347
```typescript
4448
import { execProcess } from "../core/process.ts";
4549

@@ -60,8 +64,18 @@ const result = await execProcess({
6064
## Module Loading Order
6165

6266
`src/quarto.ts` loads monkey patches first:
67+
6368
```typescript
64-
import "./core/deno/monkey-patch.ts"; // Must be first!
69+
import "./core/deno/monkey-patch.ts"; // Must be first!
6570
```
6671

6772
This ensures compatibility shims load before any code runs.
73+
74+
## Moving code off `Deno.*`
75+
76+
Outside `deno_ral/`, never add new `Deno.*` calls; import the equivalent from `deno_ral/`. The `deno_ral/` modules themselves implement those functions with `Deno.*`. To migrate existing files mechanically:
77+
78+
quarto run --dev tools/codemod-deno-ral.ts --rules fs,temp --dir src/<dir> --dry-run
79+
quarto run --dev tools/codemod-deno-ral.ts --rules fs,temp --dir src/<dir>
80+
81+
The tool reports local-name collisions (left as `Deno.*`; fix with an alias import such as `import { stat as fsStat } ...`, which later runs reuse) and skips files that assign to `Deno.*`, `src/core/lib` and the standalone scripts. Replace `instanceof Deno.errors.X` with the predicates in `deno_ral/errors.ts`. After a rebase conflict in a codemodded file, reset the file to `main` and re-run the codemod; never resolve by hand. `--reverse` produces the `Deno.*` form for backports (`dev-docs/checklist-backport-a-pr.md`).

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ src/resources/library/dayjs/** linguist-vendored
3232

3333
# use lf line-endings for source files
3434
src/** text eol=lf
35+
# codemod fixtures and tests compare file bytes verbatim
36+
tools/codemod/** text eol=lf
3537

3638
# Denote all files that are truly binary and should not be modified.
3739
*.png binary

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ runs:
1616
uses: actions/cache@v5
1717
with:
1818
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') }}
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', 'deno.lock') }}
2020
restore-keys: |
2121
${{ runner.os }}-${{ runner.arch }}-deno-cache-v1-
2222

‎.github/workflows/runtime-boundary.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ on:
2121
- "tests/**"
2222
- "tools/check-runtime-boundary.ts"
2323
- "tools/runtime-boundary-baseline.json"
24+
- "tools/codemod-deno-ral.ts"
25+
- "tools/codemod/**"
2426
- ".github/workflows/runtime-boundary.yml"
2527
push:
2628
branches: [main]
@@ -30,6 +32,8 @@ on:
3032
- "tests/**"
3133
- "tools/check-runtime-boundary.ts"
3234
- "tools/runtime-boundary-baseline.json"
35+
- "tools/codemod-deno-ral.ts"
36+
- "tools/codemod/**"
3337
- ".github/workflows/runtime-boundary.yml"
3438

3539
permissions:
@@ -52,6 +56,9 @@ jobs:
5256
- name: Configure Quarto
5357
uses: ./.github/workflows/actions/quarto-dev
5458

59+
- name: Codemod contract test (tools/codemod)
60+
run: package/dist/bin/tools/x86_64/deno test --allow-all --import-map=src/import_map.json tools/codemod/
61+
5562
- name: Check runtime boundary
5663
shell: bash
5764
env:

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,13 @@ package/dist/**
1818
/tests/test-out.json
1919
*~
2020
.env
21+
# deno lock file generated by test runs (the root deno.lock is committed)
22+
tests/deno.lock
23+
2124
# deno_std library
2225
src/resources/deno_std/cache
2326
src/vendor-*
2427

25-
# deno lock file
26-
deno.lock
2728

2829
# windows configuration file
2930
win_configuration.bat

‎configure.cmd‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ POPD
9696

9797
REM download typescript dependencies
9898
CALL package\scripts\vendoring\vendor.cmd
99+
IF ERRORLEVEL 1 EXIT /B 1
99100

100101
ECHO Downloading Deno Stdlib
101102
CALL !QUARTO_PACKAGE_PATH!\scripts\deno_std\download.bat

‎deno.jsonc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"compilerOptions": {
55
"noErrorTruncation": true
66
},
7+
"lock": false,
78
"lint": {
89
"include": ["src/"],
910
"exclude": [

0 commit comments

Comments
 (0)