Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Tutorial snapshots are compared byte for byte against a fresh runner tree by
# the drift cron, so they must not pick up CRLF on checkout.
src/data/tutorials/** text eol=lf
2 changes: 2 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ Use this chart to help you figure out where the right place for your content is:
| theoretical knowledge | work | [a reference](#reference) |
| theoretical knowledge | study | [a blog post](#blog-post) |

Some pages render their code blocks from verified tutorial manifests instead of fenced code: see [`src/data/tutorials/README.md`](../src/data/tutorials/README.md) before editing those blocks.

### Writing Style

**Dictionary**
Expand Down
7 changes: 7 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,13 @@
# Generated reference docs
src/content/docs/reference

# Emitted by `tatu schema --emit-ts` in the tutorial runner
src/components/tutorial/manifest-types.generated.ts

# Recorded by the tutorial runner, byte for byte; the drift cron compares these
# trees against a fresh run, so reformatting them reads as drift
src/data/tutorials/**

# Release notes: generated content and the committed data checkpoint
src/content/releases/**
# TODO: Prettier rewrites `{/* */}` MDX comments to `{/_ _/}`, so `index.mdx` stays ignored
Expand Down
6 changes: 4 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@
"dev": "astro dev",
"format": "prettier -w --cache --plugin prettier-plugin-astro .",
"format:check": "prettier -c --cache --plugin prettier-plugin-astro .",
"check": "pnpm build:releases && astro check",
"check": "pnpm check:tutorials && pnpm build:releases && astro check",
"check:tutorials": "node scripts/check-tutorial-steps.mjs",
"build:compatibility-table": "pnpm --filter compatibility-table run build",
"build:references": "pnpm --filter js-api-generator run build",
"build:config": "pnpm --filter config-generator run build",
"build:cli": "pnpm --filter cli-generator run build",
"build:releases": "pnpm --filter releases-site run generate",
"build:astro": "astro build",
"build:astro": "pnpm check:tutorials && astro build",
"build": "pnpm dev:setup && pnpm build:references && pnpm build:config && pnpm build:cli && pnpm build:releases && pnpm build:astro",
"preview": "astro preview",
"test": "node --test \"src/**/*.test.ts\""
Expand Down Expand Up @@ -56,6 +57,7 @@
},
"devDependencies": {
"@astrojs/check": "^0.9.9",
"diff": "^9.0.0",
"typescript": "^5.9.3"
}
}
9 changes: 9 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

199 changes: 199 additions & 0 deletions scripts/check-tutorial-steps.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
// Verifies that every page using <TutorialStep> or a <Tutorial> wrapper
// agrees with the committed tutorial trees
// (src/data/tutorials/<id>/manifest.json). For <TutorialStep>: referenced steps
// exist, every step of a referenced tutorial is present, and they appear in
// manifest order. For <Tutorial>: the wrapper renders every step in manifest
// order itself, so the page-side check reduces to slot names agreeing with
// the step ids. Default-locale pages hard-fail; translated copies only warn,
// because translation lag is expected and surfaced by Lunaria. The site build
// still fails on any page that references an unknown tutorial or step, so the
// leniency here only covers completeness and order.
//
// The tree checks mirror the runner's check_tree_consistent: the snapshot
// paths are a convention, not manifest fields, so both ends assert it.
//
// schemaVersion is enforced by the build gate in
// src/components/tutorial/manifests.ts, not here; this script only reads ids.
// The manifests are committed artifacts from the runner's CI; nothing here runs the runner.
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
const docsDir = path.join(root, 'src', 'content', 'docs');
const manifestDir = path.join(root, 'src', 'data', 'tutorials');

const locales = Object.keys(
JSON.parse(fs.readFileSync(path.join(root, 'locales.json'), 'utf8'))
).filter((l) => l !== 'root');

const errors = [];
const warnings = [];
const referenced = new Set();

// every file under a tutorial's base/ and steps/, relative to the tutorial dir
function readTree(dir) {
const files = new Set();
for (const sub of ['base', 'steps']) {
const root = path.join(dir, sub);
if (!fs.existsSync(root)) continue;
for (const entry of fs.readdirSync(root, { recursive: true })) {
const rel = String(entry).replaceAll('\\', '/');
if (fs.statSync(path.join(root, entry)).isFile()) files.add(`${sub}/${rel}`);
}
}
return files;
}

const manifests = new Map();
const trees = new Map();
if (fs.existsSync(manifestDir)) {
for (const entry of fs.readdirSync(manifestDir, { withFileTypes: true })) {
if (!entry.isDirectory()) continue;
const dir = path.join(manifestDir, entry.name);
if (!fs.existsSync(path.join(dir, 'manifest.json'))) {
errors.push(`src/data/tutorials/${entry.name}/ has no manifest.json`);
continue;
}
const m = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8'));
if (m.id !== entry.name) {
errors.push(`src/data/tutorials/${entry.name}/manifest.json declares id "${m.id}"`);
}
manifests.set(m.id, m);
trees.set(m.id, readTree(dir));
}
}

for (const entry of fs.readdirSync(docsDir, { recursive: true })) {
const rel = entry.replaceAll('\\', '/');
if (!/\.mdx?$/.test(rel)) continue;
const isTranslation = locales.includes(rel.split('/')[0]);
const report = isTranslation ? warnings : errors;

const text = fs.readFileSync(path.join(docsDir, entry), 'utf8');
const refs = [];
for (const tag of text.matchAll(/<TutorialStep\b[^>]*>/g)) {
const tutorial = tag[0].match(/tutorial="([^"]+)"/)?.[1];
const step = tag[0].match(/step="([^"]+)"/)?.[1];
if (!tutorial || !step) {
report.push(`${rel}: <TutorialStep> without tutorial= and step= props`);
continue;
}
refs.push({ tutorial, step });
}
const wrapperIds = [];
for (const tag of text.matchAll(/<Tutorial\b[^>]*>/g)) {
const id = tag[0].match(/id="([^"]+)"/)?.[1];
if (!id) {
report.push(`${rel}: <Tutorial> without an id= prop`);
continue;
}
wrapperIds.push(id);
}
for (const id of wrapperIds) {
referenced.add(id);
if (!manifests.has(id)) report.push(`${rel}: references unknown tutorial "${id}"`);
}
// with several wrappers on one page, slot names cannot be attributed to a
// tutorial without real JSX parsing; Tutorial.astro still checks at build time
if (wrapperIds.length === 1 && manifests.has(wrapperIds[0])) {
const order = manifests.get(wrapperIds[0]).steps.map((s) => s.id);
const slots = [...text.matchAll(/slot="([^"]+)"/g)].map((m) => m[1]);
for (const name of slots) {
if (!order.includes(name.replace(/-after$/, ''))) {
report.push(`${rel}: tutorial "${wrapperIds[0]}" has no step for slot "${name}"`);
}
}
for (const id of order) {
if (!slots.includes(id)) {
report.push(`${rel}: step "${id}" of "${wrapperIds[0]}" has no prose slot`);
}
}
}

if (!refs.length) {
// a tag Prettier wrapped across lines is invisible to the regex above;
// an import with zero matches is the tell
if (!wrapperIds.length && /import\s+Tutorial(Step)?\b/.test(text)) {
report.push(`${rel}: imports the tutorial components but no single-line tag matched`);
}
continue;
}

const byTutorial = Map.groupBy(refs, (r) => r.tutorial);
for (const [tutorial, used] of byTutorial) {
referenced.add(tutorial);
const manifest = manifests.get(tutorial);
if (!manifest) {
report.push(`${rel}: references unknown tutorial "${tutorial}"`);
continue;
}
const order = manifest.steps.map((s) => s.id);
const usedIds = used.map((r) => r.step);
for (const id of usedIds) {
if (!order.includes(id)) report.push(`${rel}: tutorial "${tutorial}" has no step "${id}"`);
}
for (const id of order) {
if (!usedIds.includes(id))
report.push(`${rel}: step "${id}" of "${tutorial}" is missing from the page`);
}
const positions = usedIds.map((id) => order.indexOf(id)).filter((i) => i >= 0);
if (positions.some((p, i) => i > 0 && p < positions[i - 1])) {
report.push(`${rel}: steps of "${tutorial}" are out of manifest order`);
}
}
}

for (const [id, manifest] of manifests) {
if (!referenced.has(id)) warnings.push(`manifest "${id}" is not referenced by any page`);

const files = trees.get(id);
const used = new Set();
const mutated = new Set();
for (const step of manifest.steps) {
for (const m of step.mutations) {
const where = `tutorial "${id}" step "${step.id}"`;
if (!m.file) {
// shell mutations stay file-blind: a command, no snapshot, no `created`
if (!m.command) errors.push(`${where}: mutation with neither file nor command`);
if (m.created !== undefined) errors.push(`${where}: command mutation carries created`);
continue;
}
if (typeof m.created !== 'boolean') {
errors.push(`${where}: mutation of "${m.file}" has no created flag`);
}
const after = `steps/${step.id}/${m.file}`;
if (files.has(after)) used.add(after);
else
errors.push(
`${where}: mutates "${m.file}" but src/data/tutorials/${id}/${after} is missing`
);
// only the first mutation of a file says anything about base/
if (!mutated.has(m.file)) {
mutated.add(m.file);
const base = `base/${m.file}`;
if (files.has(base)) used.add(base);
if (m.created === true && files.has(base)) {
errors.push(`${where}: creates "${m.file}" but src/data/tutorials/${id}/${base} exists`);
}
if (m.created === false && !files.has(base)) {
errors.push(
`${where}: first mutates "${m.file}" but src/data/tutorials/${id}/${base} is missing`
);
}
}
}
}
for (const f of files) {
if (!used.has(f)) warnings.push(`tutorial "${id}": snapshot "${f}" belongs to no mutation`);
}
}

for (const w of warnings) console.warn(`warn: ${w}`);
if (errors.length) {
for (const e of errors) console.error(`error: ${e}`);
process.exit(1);
}
console.log(
`tutorial steps consistent (${manifests.size} manifest(s), ${warnings.length} warning(s))`
);
76 changes: 76 additions & 0 deletions src/components/tutorial/Tutorial.astro
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
import TutorialStep from './TutorialStep.astro';
import { getTutorial } from './manifests';
import locales from '../../../locales.json';

interface Props {
/** tutorial id matching `src/data/tutorials/<id>/manifest.json` */
id: string;
/** hide every step's recorded code behind a Show-solution toggle (lab pages) */
solutions?: boolean;
}

const { id, solutions = false } = Astro.props;
// throws on unknown id, failing the build
const manifest = getTutorial(id);
const stepIds = manifest.steps.map((s) => s.id);

// Steps render in manifest order, one prose slot per step id, plus an
// optional `<id>-after` slot for prose that belongs below the step's code.
// Slot names are enumerable own properties of Astro.slots (astro
// core/render/slots.js defines one per provided slot), so a typo'd name is
// detectable here instead of silently dropping its prose.
const provided = Object.keys(Astro.slots).filter((n) => n !== 'default');

const problems: string[] = [];
for (const name of provided) {
if (!stepIds.includes(name.replace(/-after$/, ''))) {
problems.push(`unknown slot "${name}" (steps: ${stepIds.join(', ')})`);
}
}
for (const stepId of stepIds) {
if (!Astro.slots.has(stepId)) {
problems.push(`step "${stepId}" has no prose slot`);
}
}
// prose placed directly inside <Tutorial> lands in the default slot and
// would otherwise vanish; MDX always passes whitespace children, hence trim
if (((await Astro.slots.render('default')) ?? '').trim()) {
problems.push('prose outside a step slot: wrap it in <Fragment slot="<step id>">');
}

// translated copies lag behind the manifest by design (Lunaria tracks the
// gap), so under a locale prefix problems warn instead of failing the build
const localePrefix = Astro.url.pathname.split('/').filter(Boolean)[0] ?? '';
const isTranslation = localePrefix !== 'root' && localePrefix in locales;

if (problems.length) {
const message = `tutorial "${id}" on ${Astro.url.pathname}: ${problems.join('; ')}`;
if (isTranslation) {
console.warn(`warn: ${message}`);
} else {
throw new Error(message);
}
}

const steps = await Promise.all(
stepIds.map(async (stepId) => ({
id: stepId,
prose: Astro.slots.has(stepId) ? await Astro.slots.render(stepId) : undefined,
after: Astro.slots.has(`${stepId}-after`)
? await Astro.slots.render(`${stepId}-after`)
: undefined,
}))
);
---

{
steps.map((s) => (
<>
<TutorialStep tutorial={id} step={s.id} solution={solutions}>
{s.prose !== undefined && <Fragment set:html={s.prose} />}
</TutorialStep>
{s.after !== undefined && <Fragment set:html={s.after} />}
</>
))
}
Loading
Loading