docugate 0.1.2 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Gusenga Thierry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Gusenga Thierry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,44 +1,108 @@
 # docugate
 
-Command-line tools for [DocuGate](https://www.trydocugate.site), which publishes
-documentation straight from the markdown in your GitHub repository and decides
-who may read it.
+DocuGate publishes documentation straight from the markdown in your GitHub repositories and shows a walkthrough pill on your running app so any developer can see what each element on screen is and where its data comes from.
 
 ```sh
-npx docugate init     # set this repository up for DocuGate
-npx docugate check    # check the docs the way DocuGate will read them
-npx docugate openapi  # prepare an OpenAPI spec for the API reference
+npm i -g docugate
 ```
 
-Works with npm, pnpm, yarn and bun. Requires Node 18.17 or later. Run every
-command from the root of your repository.
+---
 
-## `init`
+## Quick start
 
-Creates a `docugate.json` and, if your docs folder has no markdown yet, a first
-`index.md`. It never overwrites a file, so it is safe to run in a repository
-that already has docs.
+`cd` into your app's repository, then run:
 
 ```sh
-npx docugate init --dir docs --title "Acme API"
+docugate init
 ```
 
-Then push, and publish the space from your
-[DocuGate dashboard](https://www.trydocugate.site/dashboard/new).
+It walks you through four steps:
 
-## `check`
+1. **Repository role.** Say whether this repository is the frontend, the backend, or both.
+2. **Sign in and connect.** Sign in to DocuGate with GitHub and connect this repository to a space.
+3. **IBM Bob writes the tour.** Bob reads the code and writes one `.docugate/tour/*.md` file for each screen it finds.
+4. **The pill is added to your app.** The dev-only loader snippet is inserted into your HTML or layout file.
 
-Reads your docs folder with DocuGate's own rules and reports what the
-published page would get wrong:
+Once that is done:
 
-- **Errors:** broken links between pages, links that leave the docs folder,
-  two files that become the same URL, an unreadable `docugate.json`, an empty
-  docs folder, or more than 300 pages.
-- **Warnings:** pages with no `# Title`, front matter, `.mdx` files, no landing
-  page, and `sidebar` entries that match nothing.
+```sh
+docugate tour serve
+```
+
+Start your app in another terminal, open it in the browser, and the pill appears in the corner.
+
+---
+
+## Tours
+
+A tour helps a developer who is new to a codebase see what each element on screen is and where its data comes from. For each screen there is one markdown file in `.docugate/tour/`. Each file has front matter with a `route` and a `title`, then one `##` section per stop.
+
+**Example stop:**
+
+```markdown
+---
+route: /invoices/:id
+title: Invoice detail
+---
+
+## Total
+target: [data-tour="invoice-total"]
+data: GET /api/invoices/:id → total
+code: frontend/src/screens/InvoiceDetail.tsx
+source: backend/src/billing.ts
+docs: https://example.com/docs/billing
+
+The amount due: the subtotal plus tax, computed by `totals()` in the backend.
+```
+
+Fields:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `target` | yes | CSS selector for the element. Prefer `[data-tour="…"]`. |
+| `data` | no | Request and field: `METHOD /path → field`. |
+| `code` | yes | File that renders the element, relative to the repository root. |
+| `source` | no | File where the value is computed, when that is elsewhere. |
+| `docs` | no | URL to relevant documentation. |
+
+The prose paragraph after the fields explains what the element is and why its value is what it is.
+
+Tour files are yours. `docugate tour init` never overwrites a file that already exists.
+
+---
 
-It exits with 1 when there are errors (add `--strict` to fail on warnings too),
-so it works as a CI step:
+## The pill
+
+When `docugate tour serve` is running, the pill appears in the corner of your app. It has two modes:
+
+- **Walkthrough.** Steps through every stop on the current screen in order, highlighting each element and showing its tour card.
+- **Inspector.** Hovering highlights an element; clicking it shows its stop: what it is and where its data comes from. An element with no stop yet offers **Add to tour**, a small form that saves the stop straight into the tour file, and tells you which `data-tour` attribute to add when the element has none.
+
+The pill stays on every page while the server runs, including pages with no tour yet, so their first stop can be added from the browser. Edits to the tour files show up on the page as you save them.
+
+`docugate tour install` adds the pill for you. It only loads when the app runs on `localhost` and the tour server answers, so it never shows in production.
+
+---
+
+## Keeping tours true
+
+A tour is only useful while it is true, so `docugate check` verifies every claim in `.docugate/tour/` against the code. For each stop it warns when:
+
+- the `code` file, or the `source` file, no longer exists;
+- the `code` file, and the files it imports, no longer mention the endpoint in `data`;
+- the `code` file no longer contains the `data-tour` value in `target` (a value passed through a prop counts);
+- a required field is missing, or two stops on one screen point at the same element.
+
+Rename `invoice-total` in a component and `check` tells you which stop went stale.
+
+It checks your docs folder too:
+
+- **Errors:** broken links between pages, links that leave the docs folder, two files that become the same URL, an unreadable `docugate.json`, an empty docs folder, or more than 300 pages.
+- **Warnings:** pages with no `# Title`, front matter, `.mdx` files, no landing page, and `sidebar` entries that match nothing.
+
+It exits with 1 when there are errors. Add `--strict` to fail on warnings too, which is how stale tour stops fail a build.
+
+Use it in CI:
 
 ```yaml
 # .github/workflows/docs.yml
@@ -52,30 +116,81 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npx docugate check
+      - run: npx docugate@0.2 check --strict
+```
+
+Pin the version in CI, as above. Without a pin, the rules being enforced can change between two runs of the same workflow, which turns a green build red with nothing in the commit to explain it.
+
+---
+
+## Commands
+
+| Command | Main flags | What it does |
+| --- | --- | --- |
+| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes` | Set up this repository for DocuGate (interactive). |
+| `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
+| `docugate openapi` | `--from`, `--out`, `--include`, `--exclude`, `--redact`, `--check` | Prepare an OpenAPI spec for the API reference. |
+| `docugate login` | | Sign in to DocuGate with GitHub. |
+| `docugate logout` | | Sign out and delete saved credentials. |
+| `docugate whoami` | | Print the currently signed-in user. |
+| `docugate tour init` | `--max-cost <n>`, `--team-id <id>` | Write the first tour with IBM Bob (uses Bob Shell). |
+| `docugate tour serve` | `--port <n>` (default 4178) | Start the local server that serves tour data for the pill. |
+| `docugate tour install` | `--port <n>`, `--remove` | Add (or remove) the pill loader from your app's HTML or layout. |
+| `docugate tour export <file>` | | Write every tour screen to a single JSON file. |
+
+Run every command from the root of your repository.
+
+---
+
+## Try it on the demo
+
+Clone [docugate-demo](https://github.com/Docugate/docugate-demo), a small full-stack app with a pre-written tour:
+
+```sh
+git clone https://github.com/Docugate/docugate-demo
+cd docugate-demo
+
+# install dependencies and start the app
+npm install
+npm run dev
+```
+
+In a second terminal:
+
+```sh
+cd docugate-demo
+docugate tour serve
 ```
 
+Open the app in the browser. The pill appears in the bottom-right corner.
+
+---
+
+## Several repositories in one space
+
+A space can merge docs from a frontend, a backend, and a mobile app into one set of pages. `docugate init` connects the repository it runs in to one of your spaces once you are signed in; you can also add repositories from a space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
+
+Run `init` and `check` in each repository that contributes docs, and answer the role question in each: the tour lives in the frontend, and its `source` lines can point into the backend. Every one gets its own `docugate.json`, naming its own docs folder. `check` reads the repository it is run in, which is why its 300-page limit is per repository rather than per space.
+
+See [Merging repositories](https://www.trydocugate.site/docs/merging-repositories).
+
+---
+
 ## `openapi`
 
-Takes the OpenAPI 3 spec your backend already produces and writes the version
-you want published: only the public paths, without sensitive fields, with keys
-in a stable order so it reviews cleanly in a pull request.
+Takes the OpenAPI 3 spec your backend already produces and writes the version you want published: only the public paths, without sensitive fields, with keys in a stable order so it reviews cleanly in a pull request.
 
 ```sh
-npx docugate openapi --from http://localhost:3000/openapi.json \
+docugate openapi --from http://localhost:3000/openapi.json \
   --exclude "/internal/**" --redact passwordHash --out openapi.json
 ```
 
 - `--from`: a `.json`, `.yaml` or `.yml` file, or a URL serving one.
-- `--include` / `--exclude`: path globs; `*` matches within one segment and
-  `**` matches across segments. Both can be repeated.
-- `--redact`: a property name to remove from every schema and example.
-  Can be repeated.
-- `--check`: don't write anything; exit with 1 if the committed file is out of
-  date. Useful in CI.
+- `--include` / `--exclude`: path globs; `*` matches within one segment and `**` matches across segments. Both can be repeated.
+- `--redact`: a property name to remove from every schema and example. Can be repeated.
+- `--check`: do not write anything; exit with 1 if the committed file is out of date. Useful in CI.
 
-Instead of passing flags every time, you can set the same options in
-`docugate.json`:
+Instead of passing flags every time, set the same options in `docugate.json`:
 
 ```json
 {
@@ -91,24 +206,46 @@ Instead of passing flags every time, you can set the same options in
 }
 ```
 
-The `openapi` command doesn't read your code to infer a spec. Frameworks that
-already know their schemas can export one: NestJS (`@nestjs/swagger`), Fastify
-(`@fastify/swagger`), FastAPI, and Hono (`@hono/zod-openapi`). Point `--from`
-at that output.
-
-DocuGate's API reference pages, which are built from this file, are coming
-soon. See the
-[changelog](https://www.trydocugate.site/resources/changelog).
+---
 
 ## `docugate.json`
 
+One per repository, at its root.
+
 | Key | Meaning |
 | --- | --- |
 | `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
 | `title` | The space's title. |
-| `sidebar` | File and folder names in the order the sidebar should show them. |
+| `role` | Repository role: `frontend`, `backend`, or `both`. Set by `docugate init`. |
+| `sidebar` | File and folder names in the order the sidebar should show them. Orders this repository's own pages, not the whole space. |
 | `api.generate` | Defaults for `docugate openapi`. |
 
+---
+
+## IBM Bob 2.0 hackathon
+
+This repository is DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026). To be clear about what was built when:
+
+**Before the event:** the CLI that was already in DocuGate's private repository: `docugate init`, `docugate check`, and `docugate openapi`. Moved here with its history.
+
+**During the event, with IBM Bob.** Each task has its session summary and export in `bob_sessions/`, and a plan where Bob planned first:
+
+| Task | What Bob built |
+| --- | --- |
+| 01 | The first tour: Bob read the Ledgerly demo and wrote `.docugate/tour/invoice-detail.md`, tracing each value to its endpoint and backend file. |
+| 02 | The tour format in code (`parseTourFile`, `serializeTourFile`, `loadTours`, `matchRoute`) and the tour checks in `docugate check`. |
+| 03 | `docugate tour serve` (tour data, live change events, saving stops) and `docugate tour export`. |
+| 04 | The pill: walkthrough, inspector and Add to tour, in a shadow DOM with no dependencies. |
+| 05 | One command: `docugate init` walks through the whole setup, and `docugate tour install` adds the pill to the app. |
+| 06 | `docugate login`, `logout` and `whoami`, and connecting the repository to a space during `init`. |
+| 07 | This README. |
+
+`docugate tour init` also runs IBM Bob itself, through Bob Shell. It installs a Tour Writer mode that may only edit `.docugate/tour/`, asks Bob to read the app's code, and never changes a tour file the user already has.
+
+**During the event, without Bob:** the Ledgerly demo app; the website side of `docugate login` on trydocugate.site; and fixes found while testing, such as Windows short paths in `tour serve` and the sign-in link on Windows.
+
+---
+
 ## Licence
 
 MIT

package/dist/api.js

@@ -0,0 +1,61 @@
+import { loadCredentials, saveCredentials } from './auth.js';
+/** Module-level default, captured at import time (used by CLI commands). */
+export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+const ERROR_MESSAGES = {
+    pro_required_sources: 'Connecting more than one repository to a space needs DocuGate Pro',
+};
+function friendlyError(code) {
+    return ERROR_MESSAGES[code] ?? `DocuGate said: ${code}`;
+}
+export async function apiFetch(path, init = {}) {
+    const creds = loadCredentials();
+    const headers = {
+        'Content-Type': 'application/json',
+        ...init.headers,
+    };
+    if (creds) {
+        headers['Authorization'] = `Bearer ${creds.token}`;
+    }
+    // Re-read the env at call time so tests that set DOCUGATE_URL after import work.
+    const base = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+    const res = await fetch(`${base}${path}`, { ...init, headers });
+    // Renew token if the server sent a fresh one.
+    const renewed = res.headers.get('x-docugate-token');
+    if (renewed)
+        saveCredentials(renewed);
+    if (res.status === 401) {
+        throw new Error('Run docugate login');
+    }
+    if (!res.ok) {
+        let code;
+        try {
+            const body = await res.clone().json();
+            if (body && typeof body === 'object' && !Array.isArray(body)) {
+                const b = body;
+                if (typeof b.error === 'string')
+                    code = b.error;
+            }
+        }
+        catch {
+            // ignore JSON parse failure
+        }
+        if (code)
+            throw new Error(friendlyError(code));
+        throw new Error(`DocuGate request failed with status ${res.status}`);
+    }
+    return res;
+}
+export async function getSession() {
+    const res = await apiFetch('/api/auth/session');
+    return res.json();
+}
+export async function getSpaces() {
+    const res = await apiFetch('/api/spaces/mine');
+    return res.json();
+}
+export async function connectRepo(spaceId, repo, docsDir) {
+    await apiFetch(`/api/spaces/${spaceId}/sources`, {
+        method: 'POST',
+        body: JSON.stringify({ repo, docsDir }),
+    });
+}

package/dist/auth.js

@@ -0,0 +1,97 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CREDENTIALS_DIR = join(homedir(), '.docugate');
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, 'credentials.json');
+export function credentialsPath() {
+    return CREDENTIALS_FILE;
+}
+export function loadCredentials() {
+    try {
+        const raw = readFileSync(CREDENTIALS_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const obj = parsed;
+            if (typeof obj.token === 'string')
+                return { token: obj.token };
+        }
+    }
+    catch {
+        // missing, unreadable, or not valid JSON
+    }
+    return null;
+}
+export function saveCredentials(token) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify({ token }) + '\n', { mode: 0o600 });
+}
+export function clearCredentials() {
+    rmSync(CREDENTIALS_FILE, { force: true });
+}
+// ---------------------------------------------------------------------------
+// Browser-based login
+// ---------------------------------------------------------------------------
+function openBrowserDefault(url) {
+    // Not `cmd /c start`: cmd reads the `&` between query parameters as a second
+    // command, so the browser got the URL cut off after `port=` and the site
+    // refused the link. rundll32 hands the URL over untouched.
+    const [cmd, args] = process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : process.platform === 'darwin' ? ['open', [url]]
+            : ['xdg-open', [url]];
+    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}
+/**
+ * Opens the browser at `baseUrl/api/auth/cli?port=…&state=…`, starts a local
+ * HTTP server to receive the callback, saves the token, and resolves once the
+ * user completes sign-in. Rejects after `timeoutMs` (default 5 minutes).
+ */
+export function login(baseUrl, opts = {}) {
+    const openBrowser = opts.openBrowser ?? openBrowserDefault;
+    const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000;
+    const state = randomBytes(24).toString('base64url');
+    // Must match cliCode() on the website character for character, or the page
+    // tells the person their codes differ when nothing is wrong.
+    const code = `${state.slice(0, 4)}-${state.slice(4, 8)}`.toUpperCase();
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            try {
+                const u = new URL(req.url ?? '/', `http://127.0.0.1`);
+                if (u.pathname !== '/callback') {
+                    res.writeHead(404).end('Not found');
+                    return;
+                }
+                // The browser is sent back to the website's own finish page, so every
+                // screen of the sign-in looks like DocuGate rather than a bare local one.
+                const done = `${baseUrl}/api/auth/cli/done`;
+                const token = u.searchParams.get('token') ?? '';
+                if (u.searchParams.get('state') !== state || !token) {
+                    res.writeHead(302, { Location: `${done}?error=state` }).end();
+                    return;
+                }
+                res.writeHead(302, { Location: done }).end();
+                clearTimeout(timer);
+                server.close();
+                saveCredentials(token);
+                resolve({ token });
+            }
+            catch (err) {
+                res.writeHead(500).end('Internal error');
+                reject(err);
+            }
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new Error('Sign-in timed out after 5 minutes.'));
+        }, timeoutMs);
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = addr && typeof addr === 'object' ? addr.port : 0;
+            const url = `${baseUrl}/api/auth/cli?port=${port}&state=${state}`;
+            console.log(`\nOpen this URL to sign in:\n  ${url}\n\nConfirmation code: ${code}\n`);
+            openBrowser(url);
+        });
+    });
+}

package/dist/check.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { loadConfig } from './config.js';
 import { MAX_FILES, firstHeading, landingPath, pathToSlug, resolveRelativeLink } from './rules.js';
+import { loadTours } from './tour.js';
 /** Never part of a repository on GitHub, and huge when present locally. */
 const SKIP = new Set(['node_modules', '.git']);
 /** Every file under `dir`, as forward-slash paths relative to it. */
@@ -133,5 +134,149 @@ export function check(root, dirOverride) {
             });
         }
     }
+    warnings.push(...checkTours(root));
     return { docsDir, pages: pages.length, errors, warnings };
 }
+/**
+ * Turn a data-tour route path (with :param segments) into a regex that matches
+ * the same path with any token in :param positions.
+ *
+ * The regex is intentionally loose so it matches template literals, Express
+ * route strings, Hono route strings, etc.
+ */
+function routeToRegex(routePath) {
+    // Split on :param segments, escape the literal parts, join with a wildcard
+    const parts = routePath.split(/:[\w]+/);
+    const escaped = parts.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(escaped.join('[^/\'"` ]+'));
+}
+/** Extract bare path from a data field like `GET /api/invoices/:id → total`. */
+function parseDataPath(data) {
+    const m = data.match(/\w+\s+(\/[^\s→]+)/);
+    return m ? m[1].trim() : null;
+}
+/** Resolve a single-level import path inside a source file. */
+function resolveImport(from, spec, root) {
+    if (!spec.startsWith('.'))
+        return null;
+    const dir = from.includes('/') ? from.slice(0, from.lastIndexOf('/')) : '';
+    const base = join(root, dir, spec);
+    for (const ext of ['.ts', '.tsx', '.js', '.jsx', '']) {
+        const full = base + ext;
+        if (existsSync(full))
+            return full;
+        // index file
+        const index = join(base, 'index') + ext;
+        if (existsSync(index))
+            return index;
+    }
+    return null;
+}
+/** All direct import specifiers found in a file. */
+function importsIn(text) {
+    const specs = [];
+    for (const m of text.matchAll(/^import\s+[^'"]*['"]([^'"]+)['"]/gm))
+        specs.push(m[1]);
+    return specs;
+}
+/**
+ * Run tour checks against every tour file found under `.docugate/tour/`.
+ * Issues are warnings: the docs still publish; the tour may just be wrong.
+ */
+function checkTours(root) {
+    const warnings = [];
+    let tours;
+    try {
+        tours = loadTours(root);
+    }
+    catch (err) {
+        warnings.push({ message: `tour: ${err.message}` });
+        return warnings;
+    }
+    if (tours.length === 0)
+        return warnings;
+    for (const tour of tours) {
+        const label = tour.file ?? `tour/${tour.route}`;
+        // required fields are validated by parseTourFile (throws); stops that
+        // survive parsing already have target and code.
+        // no two stops on a screen share a target
+        const seen = new Map();
+        for (const stop of tour.stops) {
+            const prev = seen.get(stop.target);
+            if (prev) {
+                warnings.push({
+                    file: label,
+                    message: `stops "${prev}" and "${stop.heading}" share the same target ${stop.target}.`,
+                });
+            }
+            else {
+                seen.set(stop.target, stop.heading);
+            }
+        }
+        for (const stop of tour.stops) {
+            const codeAbs = join(root, stop.code);
+            // code file must exist
+            if (!existsSync(codeAbs)) {
+                warnings.push({ file: label, message: `stop "${stop.heading}": code file "${stop.code}" does not exist.` });
+                continue;
+            }
+            // source file must exist if given
+            if (stop.source) {
+                const sourceAbs = join(root, stop.source);
+                if (!existsSync(sourceAbs)) {
+                    warnings.push({ file: label, message: `stop "${stop.heading}": source file "${stop.source}" does not exist.` });
+                }
+            }
+            const codeText = readFileSync(codeAbs, 'utf8');
+            // code file contains the data-tour value from target.
+            // Accepts either the full attribute (data-tour="value") or the value as
+            // any quoted string literal ("value" / 'value'), so that passing the
+            // value through a prop like tour="invoice-status" also passes the check.
+            // A renamed value (e.g. "invoice-total-RENAMED") must still warn.
+            const tourValueMatch = stop.target.match(/data-tour=["']([^"']+)["']/);
+            if (tourValueMatch) {
+                const tourValue = tourValueMatch[1];
+                const esc = tourValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const exactPattern = new RegExp(`["']${esc}["']`);
+                if (!exactPattern.test(codeText)) {
+                    warnings.push({
+                        file: label,
+                        message: `stop "${stop.heading}": "${stop.code}" does not contain data-tour value "${tourValue}".`,
+                    });
+                }
+            }
+            // code file (or a file it imports, one level deep) contains the endpoint path from data
+            if (stop.data) {
+                const endpointPath = parseDataPath(stop.data);
+                if (endpointPath) {
+                    // build a regex that matches the path with :param as wildcard
+                    const pathRegex = routeToRegex(endpointPath);
+                    const filesForEndpoint = [codeAbs];
+                    for (const spec of importsIn(codeText)) {
+                        const resolved = resolveImport(stop.code, spec, root);
+                        if (resolved)
+                            filesForEndpoint.push(resolved);
+                    }
+                    const found = filesForEndpoint.some((f) => {
+                        try {
+                            const t = readFileSync(f, 'utf8');
+                            // Check for literal path or a path where :param is present as /:id etc.
+                            // We look for any substring matching the regex pattern by scanning lines
+                            return t.split('\n').some((line) => pathRegex.test(line));
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                    if (!found) {
+                        warnings.push({
+                            file: label,
+                            message: `stop "${stop.heading}": endpoint "${endpointPath}" not found in "${stop.code}" or its imports.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return warnings;
+}