@sanoma-ai/workflows 0.8.2 → 0.9.0

package/src/run.ts

@@ -46,8 +46,6 @@ export interface WorkerState {
   drivers: Map<string, DriverFn>;
   /** The makers of the config's fake vendors, by vendor id: a sandbox run makes its own of each when it is seeded. */
   fakes: Map<string, () => Fake<any, any>>;
-  /** The instance's fakes, by vendor id, when it runs on them (`fakes: "instance"`): its sandbox runs seed and call these, not fakes of their own. */
-  instanceFakes?: ReadonlyMap<string, Fake<any, any>>;
   /** Where sandbox runs' scenarios are, the resource types their steps may name, and the steps the connectors ship. */
   scenarios?: URL;
   /** The worker's `source`, when it was given one. */

package/src/sandbox.ts

@@ -4,7 +4,7 @@ import { opIdsOf } from "./define.ts";
 import { SanomaError } from "./errors.ts";
 import type { Fake, ResourceFake } from "./fake.ts";
 import { entry, type LedgerRecord, write } from "./ledger.ts";
-import type { CallContext, DriverFn, Op } from "./op.ts";
+import type { DriverFn } from "./op.ts";
 import type { Run } from "./run.ts";
 import { memorySecrets } from "./secret.ts";
 import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
@@ -58,7 +58,7 @@ export function seedResource(
   scenario: string,
   copy: ResourceFake,
   given: Extract<Given, { resource: string }>,
-): Seeds[number] {
+): Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"][number] {
   const { resource, type, name } = given;
   try {
     if ("gone" in given) {
@@ -77,81 +77,16 @@ export function seedResource(
   }
 }
 
-/** What a scenario's `Given` steps seeded, as its `scenario.seeded` record has it. */
-export type Seeds = Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"];
-
-/**
- * Where a scenario's `Given` steps go (`applyGivens`): a sandbox run's own fakes (`run`), or the
- * instance a demo runs (`instance`), its collections in the config's database and every vendor
- * on its one fake, which every run shares, so a fault, injected into a call some other run would
- * make, is refused there.
- */
-export interface GivenTarget {
-  kind: "run" | "instance";
-  /** What a `Given` operation is called through, by operation id. */
-  drivers: ReadonlyMap<string, DriverFn>;
-  /** The fakes, by vendor id: what a `Given` resource is put in, and a `run`'s faults injected into. */
-  fakes: ReadonlyMap<string, Fake<unknown>>;
-  /** The operations by id, for a fault's vendor. */
-  ops: ReadonlyMap<string, Op>;
-  /** The context of the call the `i`th `Given` makes. */
-  call(i: number, op: string): CallContext;
-}
-
-/**
- * Applies the scenario's `Given` steps to the target: calls each operation through its drivers,
- * puts or removes each resource in its vendor's fake, then, for a `run`, injects the faults.
- * Checks first that every operation it seeds has a driver there, that every resource's vendor has
- * a fake holding resources, and, for an `instance`, that it injects no fault. Returns what it
- * seeded, in order.
- */
-export async function applyGivens(scenario: Pick<Scenario, "name" | "given">, target: GivenTarget): Promise<Seeds> {
-  const { name, given } = scenario;
-  const fault = given.find((g) => "fault" in g);
-  if (fault && target.kind === "instance") {
-    throw new SanomaError(
-      "invalid_input",
-      `Scenario "${name}" injects a fault ("${fault.step}"), but its Givens go to the instance, whose fakes every run shares`,
-      { scenario: name, step: fault.step },
-    );
-  }
-  const missing = [...new Set(given.flatMap((g) => ("op" in g && !target.drivers.has(g.op) ? [g.op] : [])))];
-  if (missing.length) {
-    throw new SanomaError(
-      "invalid_input",
-      `Scenario "${name}" seeds ${missing.join(", ")}, but no fake its connectors attach implements ${missing.length > 1 ? "them" : "it"}`,
-      { scenario: name, missing },
-    );
-  }
-  const plain = missingResourceFake(scenario, target.fakes);
-  if (plain) throw plain;
-  const seeded: Seeds = [];
-  for (const [i, g] of given.entries()) {
-    if ("fault" in g) continue;
-    if ("op" in g) {
-      const output = await target.drivers.get(g.op)!(g.input, target.call(i, g.op));
-      seeded.push({ op: g.op, input: g.input, output });
-      continue;
-    }
-    // Checked above: the vendor's fake holds resources.
-    seeded.push(seedResource(name, target.fakes.get(g.vendor) as Fake<unknown> & ResourceFake, g));
-  }
-  for (const g of given) {
-    if ("fault" in g) target.fakes.get(target.ops.get(g.op)!.vendor)![g.fault](g.op);
-  }
-  return seeded;
-}
-
 /**
  * Seeds a sandbox run of the scenario `name`, from the worker, in one step: reads the scenario,
- * checks that it runs this workflow, picks the run's fakes, checks that every operation the
- * workflow uses has one, then applies the scenario's `Given` steps to them
- * (`applyGivens`) and puts their functions on the run. The run then calls those only. Its fakes
- * are its own (each vendor's maker, called once for the run), so sandbox runs share no state when
- * the makers make a new fake each; on an instance that runs on fakes (`instanceFakes`) they are
- * the instance's, which its sandbox runs share, as its live drivers are. The step's checkpoint
- * never stands in for a run's own: a run whose seeding is replayed from it has none, and fails,
- * since a sandbox run does not survive a worker restart; on an instance's fakes it goes on with them.
+ * checks that it runs this workflow, makes the run's own fakes (each vendor's maker, called once
+ * for the run), checks that every operation the workflow uses or the scenario seeds has one and
+ * that every resource it seeds has a fake holding resources, calls each `Given` operation
+ * through them, puts or removes each `Given` resource in them, injects the faults into them,
+ * then puts their functions on the run. The run then calls those only, so sandbox runs share no
+ * state when the makers make a new fake each. The step's checkpoint never stands in for them: a
+ * run whose seeding is replayed from it has none, and fails, since a sandbox run does not
+ * survive a worker restart.
  */
 export async function seedSandbox(run: Run, name: string): Promise<void> {
   const { state } = run;
@@ -168,19 +103,16 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
         throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
       }
       if (scenario.workflow !== run.workflow) {
-        const runs = scenario.workflow === undefined ? "is a world, which runs nothing" : `runs ${scenario.workflow}`;
-        throw new SanomaError("invalid_input", `Scenario "${name}" ${runs}, not ${run.workflow}`, {
+        throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
           scenario: name,
-          ...(scenario.workflow !== undefined && { workflow: scenario.workflow }),
+          workflow: scenario.workflow,
         });
       }
-      const instance = state.instanceFakes;
-      const fakes = instance ?? new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
-      const drivers = instance
-        ? state.drivers
-        : indexDrivers([...Array.from(fakes.values(), (f) => f.driver), ...sandboxDrivers], state.ops);
-      // What the scenario seeds is checked by `applyGivens`.
-      const missing = opIdsOf(state.workflows.get(run.workflow)!).filter((id) => !drivers.has(id));
+      const fakes = new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
+      const drivers = indexDrivers([...Array.from(fakes.values(), (f) => f.driver), ...sandboxDrivers], state.ops);
+      const uses = opIdsOf(state.workflows.get(run.workflow)!);
+      const seeding = scenario.given.flatMap((g) => ("op" in g ? [g.op] : []));
+      const missing = [...new Set([...uses, ...seeding])].filter((id) => !drivers.has(id));
       if (missing.length) {
         throw new SanomaError(
           "invalid_input",
@@ -188,20 +120,28 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
           { scenario: name, missing },
         );
       }
-      const seeded = await applyGivens(scenario, {
-        kind: instance ? "instance" : "run",
-        drivers,
-        fakes,
-        ops: state.ops,
-        call: (i, opId) => ({ idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId, attempt: 1, secrets }),
-      });
+      const plain = missingResourceFake(scenario, fakes);
+      if (plain) throw plain;
+      const seeded: Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"] = [];
+      for (const [i, given] of scenario.given.entries()) {
+        if ("fault" in given) continue;
+        if ("op" in given) {
+          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1, secrets };
+          const output = await drivers.get(given.op)!(given.input, call);
+          seeded.push({ op: given.op, input: given.input, output });
+          continue;
+        }
+        // Checked above: the vendor's fake holds resources.
+        seeded.push(seedResource(name, fakes.get(given.vendor) as Fake<unknown> & ResourceFake, given));
+      }
+      for (const given of scenario.given) {
+        if ("fault" in given) fakes.get(state.ops.get(given.op)!.vendor)![given.fault](given.op);
+      }
       copies = drivers;
       return { seeds: seeded };
     },
     { name: "sandbox:seed" },
   );
-  // Replayed on an instance that runs on fakes: they are the instance's, still there in this process.
-  if (!copies && state.instanceFakes) copies = state.drivers;
   if (!copies) {
     // Replayed from its checkpoint (after a worker restart, or in a fork), so the run has no fakes.
     // The records written before the restart hold the seqs from here on: the failure goes after them.

package/src/scenario.ts

@@ -136,19 +136,7 @@ export interface Scenario {
   file: string;
   /** Its line in the file: its keyword's, or for an outline's row, the row's. */
   line: number;
-  /**
-   * The workflow its `When` runs. Absent for a scenario with no `When`, a *world*: its `Given`
-   * steps alone, which a demo applies to the instance (`applyGivens`) and nothing runs or checks.
-   */
-  workflow?: string;
-  /** Its tags, as written (`@slow`), the feature's and its own. */
-  tags: string[];
-  /**
-   * When it is tagged `@moment(<person>,<path>)` (no space: a Gherkin tag has none): a moment,
-   * which a demo starts as a sandbox run by `person`, a declared person, and leaves waiting, for
-   * a visitor signed in as them to land on at `path`.
-   */
-  moment?: Moment;
+  workflow: string;
   /**
    * The scenario's own lines of its feature file, for display: from its keyword line to the end
    * of its last step (a step's doc string or table included, and an outline's examples), less
@@ -171,12 +159,6 @@ export interface Scenario {
   expect: Expectation[];
 }
 
-/** A moment's visitor and where they land: `@moment(<person>,<path>)`. */
-export interface Moment {
-  person: string;
-  path: string;
-}
-
 /** The result of one expectation against a run's ledger. */
 export interface Check {
   step: string;
@@ -399,22 +381,6 @@ function builtFor(scope: Scope): Built {
 /** A `Then` step of the generic steps: its expectation, checked against the run's records. */
 const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
-/**
- * `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. The
- * people are the root's data files' (`readPeople`, read again only once a file changed): while
- * they declare no one, any id goes.
- */
-function actorNamed(scope: Scope, who: string): string {
-  const declared = readPeople(scope.root);
-  try {
-    return admit({ id: who }, declared).id;
-  } catch (err) {
-    if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
-    const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
-    throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
-  }
-}
-
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
   const { types, collections } = scope;
@@ -438,10 +404,20 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
   ];
   const opOf = (id: unknown) => scope.ops.get(id as string)!;
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
-  /**
-   * `group`, a declared group or `agents`, while the people's files have no problems (`readPeople`,
-   * read again only once a file changed): while they declare no one, any group goes.
-   */
+  // The people as the root's data files declare them when a step names one (`readPeople`, read
+  // again only once a file changed): while they declare no one, any id and any group go.
+  /** `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. */
+  const actorNamed = (who: string) => {
+    const declared = readPeople(scope.root);
+    try {
+      return admit({ id: who }, declared).id;
+    } catch (err) {
+      if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
+      const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
+      throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
+    }
+  };
+  /** `group`, a declared group or `agents`, while the people's files have no problems. */
   const groupNamed = (group: string) => {
     const { people, problems } = readPeople(scope.root);
     if (problems.length) {
@@ -459,7 +435,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
     return { resource: id as string, vendor, type, name: name as string };
   };
   const rules: Rule[] = [
-    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(scope, who as string) },
+    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
     // A visitor of a public site, as a login would vouch for one; `anonymous` is a `{who}`.
     { kind: "actor", source: "a visitor is acting", read: () => visitorPrincipal("scenario", "visitor").id },
     {
@@ -906,7 +882,7 @@ function namesOf(report: Report): Map<string, string> {
 }
 
 /** What one scenario's steps said, as compiling it records them. */
-type Spec = Omit<Scenario, "approvals" | "file" | "line" | "text" | "tags" | "moment">;
+type Spec = Omit<Scenario, "workflow" | "approvals" | "file" | "line" | "text"> & { workflow?: string };
 
 /** The run's records, as a `Then` step reads them. */
 function viewOf(records: readonly LedgerRecord[]): RunView {
@@ -1202,28 +1178,6 @@ function stepError(built: Built, result: StepResult | undefined, step: PickleSte
   }
 }
 
-/**
- * The moment its tags make a scenario (`@moment(<person>,<path>)`), the person admitted as a run's
- * starter is, or undefined for none; throws, at `where`, for a malformed one or a second.
- */
-function momentOf(scope: Scope, tags: readonly string[], where: string): Moment | undefined {
-  const tagged = tags.filter((t) => t === "@moment" || t.startsWith("@moment("));
-  if (tagged.length === 0) return undefined;
-  if (tagged.length > 1) throw new Error(`${where}: ${tagged.join(" and ")}: a moment has one person and one page`);
-  const [, person, path] = /^@moment\(([^,()]+),(\/[^()]*)\)$/.exec(tagged[0]!) ?? [];
-  if (person === undefined || path === undefined) {
-    throw new Error(
-      `${where}: ${tagged[0]} needs a person and a path, as in @moment(alex,/sites/portal/requests), with no space: a tag has none`,
-    );
-  }
-  try {
-    return { person: actorNamed(scope, person), path };
-  } catch (err) {
-    if (isBug(err)) throw err;
-    throw new Error(`${where}: ${tagged[0]}: ${errorMessage(err)}`, { cause: err });
-  }
-}
-
 /** The `.feature` files under `dir`, relative to it, with `/` between directories, in order. */
 function featureFiles(dir: string): string[] {
   return readdirSync(dir, { recursive: true, encoding: "utf8" })
@@ -1253,9 +1207,8 @@ const parseErrorOf = ({ uri, line, message }: Report["parseErrors"][number]) =>
 
 /**
  * Compiles the feature files `files` (relative to `dir`) into scenarios: Cucumber runs each,
- * and its steps record what they say. A file none of whose scenarios has a `When` is of worlds.
- * A file with an error has none of its scenarios: the
- * first error in it (a step that fails or matches no step or two, a scenario with no `When` beside one with,
+ * and its steps record what they say. A file with an error has none of its scenarios: the
+ * first error in it (a step that fails or matches no step or two, a scenario with no `When`,
  * a name used twice, a file Gherkin cannot parse, no scenarios at all) is its error.
  */
 async function compile(scope: Scope, dir: string, files: string[]): Promise<LoadedScenarios> {
@@ -1291,8 +1244,6 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
       try {
         const list = pickles.get(file) ?? [];
         if (list.length === 0) throw new Error(`${file}: no scenarios; add one with "Scenario: <name>"`);
-        // A feature none of whose scenarios has a When is of worlds; elsewhere a missing When is a mistake.
-        const ofWorlds = list.every((p) => specs.get(p.id)!.workflow === undefined);
         for (const pickle of list) {
           const line = lineOf(report, pickle);
           const scenario = query.findLineageBy(pickle)!.scenario!;
@@ -1301,37 +1252,16 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
             const error = stepError(built, results.get(step.id), step, whereOf(report, file, step));
             if (error) throw new Error(error);
           }
-          const spec = specs.get(pickle.id)!;
-          const { workflow } = spec;
+          const { workflow, ...spec } = specs.get(pickle.id)!;
           const name = names.get(pickle.id)!;
           if (inFile.some((s) => s.name === name)) {
             throw new Error(`${where}: a second scenario named "${name}"; give each its own name`);
           }
-          const tags = pickle.tags.map((t) => t.name);
-          const moment = momentOf(scope, tags, where);
-          const common = { name, file, line, tags, text: textOf(scenario, report.texts.get(file) ?? "") };
-          if (workflow === undefined && !ofWorlds) {
+          if (workflow === undefined) {
             throw new Error(
-              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with" (a feature with no When in any scenario is of worlds)`,
+              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`,
             );
           }
-          if (workflow === undefined) {
-            // A world: its Givens alone, which nothing runs or checks.
-            const runs = moment
-              ? "is a moment, which starts a run"
-              : spec.expect[0]
-                ? `checks a run ("${spec.expect[0].step}")`
-                : spec.decisions[0]
-                  ? `decides an approval ("${spec.decisions[0].step}")`
-                  : undefined;
-            if (runs) {
-              throw new Error(
-                `${where}: scenario "${name}" has no When, so it is a world, Givens only, but it ${runs}: say which workflow runs, such as "When <workflow> runs with"`,
-              );
-            }
-            inFile.push({ ...spec, ...common, approvals: [] });
-            continue;
-          }
           // A step about a declared resource reads the report of the built-in it is about.
           for (const e of spec.expect) {
             const reads: string = "declared" in e ? ("status" in e ? DRIFT_WORKFLOW : APPLY_WORKFLOW) : workflow;
@@ -1343,9 +1273,11 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
           }
           inFile.push({
             ...spec,
-            ...common,
+            name,
+            file,
+            line,
             workflow,
-            ...(moment && { moment }),
+            text: textOf(scenario, report.texts.get(file) ?? ""),
             approvals: approvalsOf(scope.workflows.get(workflow)!),
           });
         }
@@ -1436,11 +1368,10 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
  */
 export async function check(scope: Scope, scenario: Scenario, records: readonly LedgerRecord[]): Promise<Check[]> {
   if (!scope.scenarios) throw new Error(`No scenarios directory to check scenario "${scenario.name}" from`);
-  const { file, line, name, workflow } = scenario;
-  if (workflow === undefined) throw new Error(`Scenario "${name}" is a world: it runs nothing to check`);
   const built = builtFor(scope);
+  const { file, line, name } = scenario;
   const verdicts = new Map<string, string | undefined>();
-  const report = await runFeatures(built.library, checkWorld(built, workflow, viewOf(records), verdicts), {
+  const report = await runFeatures(built.library, checkWorld(built, scenario.workflow, viewOf(records), verdicts), {
     cwd: fileURLToPath(scope.scenarios),
     files: [file],
     line,

package/src/scenarios.ts

@@ -6,13 +6,11 @@ import { type Check, check, drive, loadScenarios, type Scenario, type Scope } fr
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
 
-export { type DemoState, demoState, reseed, type SeedHalf } from "./demo.ts";
-
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test
  * framework. Server-side only, like `./scenario`: it loads Cucumber and starts a worker.
  * `sanoma check` runs every scenario through `runScenarios`; `@sanoma-ai/testing/scenarios` wraps
- * `runScenario` in a vitest test per scenario. A demo seeds its instance with `reseed`.
+ * `runScenario` in a vitest test per scenario.
  */
 
 export interface RunScenarioOptions {
@@ -32,15 +30,12 @@ export interface RunScenarioOptions {
 /**
  * Runs a scenario as a sandbox run: starts its workflow with its input, as whoever it says is
  * acting, decides its approvals as it says, and checks the run's ledger against it (`check`:
- * Cucumber runs its `Then` steps). Refuses a world, which runs nothing.
+ * Cucumber runs its `Then` steps).
  */
 export async function runScenario(
   scenario: Scenario,
   { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
-  if (scenario.workflow === undefined) {
-    throw new Error(`Scenario "${scenario.name}" is a world: it seeds a demo's instance, and runs nothing`);
-  }
   const runId = await client.start(scenario.workflow, scenario.input, {
     startedBy: scenario.startedBy ?? startedBy,
     sandbox: scenario.name,
@@ -69,13 +64,6 @@ export interface RunScenariosOptions {
   log?: (line: string) => void;
 }
 
-/**
- * True for a scenario that is a test: one that runs a workflow (not a world), and not a moment
- * that decides nothing, which a demo leaves waiting at its first approval.
- */
-export const isTest = (scenario: Scenario): scenario is Scenario & { workflow: string } =>
-  scenario.workflow !== undefined && !(scenario.moment && scenario.decisions.length === 0);
-
 /**
  * Runs every scenario in `scenarios/` in the config's root, one after another, as sandbox runs
  * on a worker it starts on `databaseUrl` with an in-memory ledger (the config's `ledger` is not
@@ -84,7 +72,6 @@ export const isTest = (scenario: Scenario): scenario is Scenario & { workflow: s
  * could not be read, with why. A scenario whose run cannot be driven to its end (an approval
  * with no decision, a run still going after `timeoutMs`) fails with that error at its `When`
  * step. A config whose root has no `scenarios/`, or none in it, passes nothing and fails nothing.
- * Worlds and moments that decide nothing are no tests (`isTest`): they are left out, each logged as skipped.
  */
 export async function runScenarios(
   config: SanomaConfig,
@@ -92,9 +79,7 @@ export async function runScenarios(
 ): Promise<{ passed: string[]; failed: ScenarioFailure[] }> {
   const shared: SanomaConfig = { ...config, databaseUrl, ledger: memoryLedger() };
   const resolved = resolveConfig(shared);
-  const { scenarios: loaded, errors } = await loadScenarios(resolved);
-  const scenarios = loaded.filter(isTest);
-  for (const s of loaded) if (!isTest(s)) log?.(`skipped ${s.file} › ${s.name}: ${s.moment ? "a moment" : "a world"}`);
+  const { scenarios, errors } = await loadScenarios(resolved);
   const failed: ScenarioFailure[] = errors.map(({ file, message }) => ({
     scenario: file,
     step: "did not load",

package/src/sites.ts

@@ -63,6 +63,12 @@ export interface SitePage {
    * destructured) with `content` from `sanoma/site`.
    */
   content?: string;
+  /**
+   * `false` when its route says `staticData: { sitemap: false }`, written out: the sitemap leaves it
+   * out. Its index route's `sitemap` (`true` or `false`) decides over a layout's at its path; a
+   * pathless or group layout's says nothing.
+   */
+  sitemap?: false;
 }
 
 /** A site, `sites/<name>/` or an app's `apps/<app>/sites/<name>/`, and what it calls. */
@@ -225,12 +231,27 @@ export function readSites(
   });
 }
 
-/** A site's pages, by path, from its files: a layout's and its index's (one path) merged. */
-function pagesOf(read: readonly { route?: SitePage }[]): Map<string, SitePage> {
+/**
+ * What a route made by `createFileRoute(id)({ … })` says of the sitemap, `staticData`'s `sitemap`
+ * written out (a lazy route's options carry no `staticData`), and how much it is its page's own:
+ * an index (2) over a route at its path (1). A pathless or group layout's says nothing.
+ */
+type Says = { listed: boolean; rank: number };
+
+/** A route file's page, with what its route says of the sitemap. */
+type FileRoute = Omit<SitePage, "sitemap"> & { says?: Says };
+
+/** A site's pages, by path, from its files: a layout's and its index's (one path) merged, the most its own route that says deciding `sitemap`. */
+function pagesOf(read: readonly { route?: FileRoute }[]): Map<string, SitePage> {
   const pages = new Map<string, SitePage>();
+  const own = new Map<string, Says>();
   for (const { route } of read) {
-    if (route) pages.set(route.path, { ...pages.get(route.path), ...route });
+    if (!route) continue;
+    const { says, ...page } = route;
+    pages.set(page.path, { ...pages.get(page.path), ...page });
+    if (says && says.rank > (own.get(page.path)?.rank ?? 0)) own.set(page.path, says);
   }
+  for (const [path, { listed }] of own) if (!listed) pages.get(path)!.sitemap = false;
   return pages;
 }
 
@@ -318,13 +339,14 @@ type Written = Omit<SiteCall, "target"> & { name: string };
 
 /**
  * What one file holds: its uses, in its order, and the page it is, from its route's id, with the
- * content kind whose entry its one parameter names (`SitePage.content`). A file under `routes/` is
- * read whole; any other only when it imports `api` or `RunForm`.
+ * content kind whose entry its one parameter names (`SitePage.content`) and whether its route's
+ * options keep it out of the sitemap (`SitePage.sitemap`). A file under `routes/` is read whole;
+ * any other only when it imports `api` or `RunForm`.
  */
 function readSiteFile(
   { program, at }: SourceFile,
   file: string,
-): { uses: Written[]; route?: SitePage; warning?: LintProblem & { file: string } } {
+): { uses: Written[]; route?: FileRoute; warning?: LintProblem & { file: string } } {
   const api = importedAs(program, SITE_SOURCES, "api");
   const runForm = importedAs(program, SITE_SOURCES, "RunForm");
   const content = importedAs(program, SITE_SOURCES, "content");
@@ -333,6 +355,7 @@ function readSiteFile(
   /** Each `content.<kind>.get(arg)`: its kind, its argument and where it is. */
   const gets: { kind: string; arg: Node; start: number }[] = [];
   let page: string | undefined;
+  let says: Says | undefined;
   const visit = (node: Node) => {
     if (!node) return;
     if (node.type === "MemberExpression") {
@@ -341,6 +364,18 @@ function readSiteFile(
       if (named) return void found.push({ ...named, via: "api", file, ...at(node.start) });
     } else if (node.type === "CallExpression") {
       const callee = unwrap(node.callee);
+      // `createFileRoute(id)({ … })`: its page, and what its options say of the sitemap.
+      const maker = callee?.type === "CallExpression" ? unwrap(callee.callee) : undefined;
+      const madeId =
+        maker?.type === "Identifier" && ROUTE_MAKERS.has(maker.name) && page === undefined
+          ? stringValue(callee.arguments[0])
+          : undefined;
+      if (madeId !== undefined) {
+        page = pageOf(madeId);
+        const listed = maker.name === "createFileRoute" ? sitemapOf(node.arguments[0]) : undefined;
+        const rank = madeId.endsWith("/") ? 2 : isPathless(madeId.split("/").at(-1)!) ? 0 : 1;
+        if (listed !== undefined && rank) says = { listed, rank };
+      }
       if (callee?.type === "Identifier" && ROUTE_MAKERS.has(callee.name) && page === undefined) {
         const id = stringValue(node.arguments[0]);
         if (id !== undefined) page = pageOf(id);
@@ -360,9 +395,10 @@ function readSiteFile(
   visit(program);
   const uses = found.map((use) => (page === undefined ? use : { ...use, page }));
   if (page === undefined) return { uses };
+  const route: FileRoute = { path: page, ...(says && { says }) };
   // The one parameter's name (not a splat's), and the kinds whose `get` is given it (`params.slug`, or `slug` destructured).
   const params = page.split("/").filter((segment) => segment.startsWith("$"));
-  if (params.length !== 1 || params[0] === "$") return { uses, route: { path: page } };
+  if (params.length !== 1 || params[0] === "$") return { uses, route };
   const param = params[0]!.slice(1);
   const kinds = new Set(
     gets
@@ -373,16 +409,33 @@ function readSiteFile(
       )
       .map(({ kind }) => kind),
   );
-  if (kinds.size === 1) return { uses, route: { path: page, content: [...kinds][0]! } };
+  if (kinds.size === 1) return { uses, route: { ...route, content: [...kinds][0]! } };
   // A read by the parameter in a form the sitemap does not follow (`params.id.toLowerCase()`, two kinds).
   const unfollowed = gets.find(({ arg }) => mentions(arg, param));
-  if (!unfollowed) return { uses, route: { path: page } };
+  if (!unfollowed) return { uses, route };
   const message =
     `the sitemap lists none of this page's entries: it reads content by the page's parameter in a way it cannot follow. ` +
     `Read one kind by it as written, \`content.<kind>.get(params.${param})\` (or \`${param}\` destructured)`;
-  return { uses, route: { path: page }, warning: { file, ...at(unfollowed.start), message } };
+  return { uses, route, warning: { file, ...at(unfollowed.start), message } };
 }
 
+/** A route's `options`' `staticData: { sitemap }`, each written out, `sitemap` a boolean; undefined for any other. */
+const sitemapOf = (options: Node): boolean | undefined => {
+  const flag = unwrap(valueOf(valueOf(options, "staticData"), "sitemap"));
+  return flag?.type === "Literal" && typeof flag.value === "boolean" ? flag.value : undefined;
+};
+
+/**
+ * The value of an object literal's property `name`, its last, written out; undefined for anything
+ * else, or when a spread or a computed key after it could replace it.
+ */
+const valueOf = (object: Node, name: string): Node => {
+  const o = unwrap(object);
+  const last =
+    o?.type === "ObjectExpression" && o.properties.findLast((p: Node) => !isWritten(p) || keyName(p.key) === name);
+  return last && isWritten(last) ? last.value : undefined;
+};
+
 /** Whether `node` reads the parameter `param` anywhere in it: `params.<param>`, or `param` destructured (not another parameter, nor a property's name, `post.slug` or `{ slug: x }`). */
 const mentions = (node: Node, param: string): boolean => {
   if (!node) return false;
@@ -555,9 +608,12 @@ function siteOptionsOf(
 const pageOf = (id: string): string =>
   `/${id
     .split("/")
-    .filter((s) => s && !/^\(.*\)$/.test(s) && !s.startsWith("_"))
+    .filter((s) => s && !isPathless(s))
     .map((s) => s.replace(/_$/, ""))
     .join("/")}`;
 
+/** A route id's segment the router's path leaves out: a `(group)` or a `_pathless` one. */
+const isPathless = (segment: string): boolean => /^\(.*\)$/.test(segment) || segment.startsWith("_");
+
 /** A site's source file: `.ts` or `.tsx`, but a test or a declaration. */
 const isSource = (name: string) => /\.tsx?$/.test(name) && !/\.(test|d)\.tsx?$/.test(name);