@pikku/cli 0.12.159 → 0.12.162

package/dist/src/functions/commands/scenario-guide.js

@@ -0,0 +1,313 @@
+/**
+ * The user guide a scenario suite already contains.
+ *
+ * A feature reads as a page and a scenario as a section — `pikku scenario
+ * guide` is the compiler that joins that to the editorial prose an app checks
+ * in under `docs/`, and writes markdown. It renders no HTML, resolves no asset
+ * URLs and knows about no website: an image is an ordinary relative
+ * `![alt](path)`, and a consumer that needs a different path rewrites it.
+ *
+ * Nothing here reads the filesystem or the registry. The command assembles a
+ * {@link GuideFeature} per registered feature and a {@link GuidePage} per
+ * editorial source; everything below is a pure function of those, which is what
+ * makes the output byte-identical across runs.
+ */
+import { createHash } from 'node:crypto';
+import { parse, stringify } from 'yaml';
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/**
+ * Read one editorial source.
+ *
+ * A page cites a feature by leaving the marker pair where the block belongs —
+ * an author writing `<!-- pikku:guide feature=x -->` followed by
+ * `<!-- /pikku:guide -->` and nothing between them. That one line is both
+ * halves of the job: it says *where* the block goes, which a frontmatter list
+ * cannot express, and it is what the coverage gate counts to decide *whether* a
+ * feature is documented at all. The mapping stays many-to-many and falls out of
+ * the union of every marker in the tree, so a feature written about in three
+ * places needs no index to say so.
+ */
+export const parseGuidePage = (path, content) => {
+    const match = content.match(FRONTMATTER);
+    if (!match) {
+        throw new Error(`${path} has no frontmatter — a guide page opens with a \`---\` block carrying at least a title.`);
+    }
+    let frontmatter;
+    try {
+        frontmatter = parse(match[1]) ?? {};
+    }
+    catch (e) {
+        throw new Error(`${path} has unreadable frontmatter: ${e?.message ?? e}`);
+    }
+    if (frontmatter.features !== undefined) {
+        throw new Error(`${path} declares \`features:\` in its frontmatter. A page cites a feature by placing \`<!-- pikku:guide feature=<id> -->\` and \`<!-- /pikku:guide -->\` in the body where the block belongs.`);
+    }
+    const body = match[2] ?? '';
+    return {
+        path,
+        ...(typeof frontmatter.title === 'string'
+            ? { title: frontmatter.title }
+            : {}),
+        ...(typeof frontmatter.description === 'string'
+            ? { description: frontmatter.description }
+            : {}),
+        frontmatter,
+        features: citedFeatures(body),
+        body,
+    };
+};
+const CITATION = /<!--\s*pikku:guide\s+feature=([^\s]+)[^>]*-->/g;
+const citedFeatures = (body) => {
+    const seen = [];
+    for (const [, id] of body.matchAll(CITATION)) {
+        if (id && !seen.includes(id)) {
+            seen.push(id);
+        }
+    }
+    return seen;
+};
+/**
+ * The hash a page's prose is written against.
+ *
+ * The input is the feature's **step sentences and artifact ids**, and
+ * deliberately not the image bytes and not the prose: restyling a UI changes
+ * every screenshot and no sentence, while inserting, reordering or renaming a
+ * step changes the sentence list — and that is what actually invalidates a
+ * paragraph describing the flow. It watches something the reader never sees.
+ *
+ * Canonically, the hashed value is the JSON of
+ * `[[scenarioName, [sentence, …], [artifactId, …]], …]` where:
+ *
+ * - scenarios are sorted by name then title, because a run's order is a
+ *   property of how the suite was selected that day, not of the feature;
+ * - sentences keep their ladder order, keyword included, because that order is
+ *   the flow being described — the one thing a step change must move;
+ * - each sentence is whitespace-collapsed, so the reporter's column padding is
+ *   not part of the promise;
+ * - artifact ids are sorted, because artifacts are filed as they are finalised
+ *   rather than as they were taken.
+ *
+ * Seven hex characters, like a short commit hash: it is read by a human
+ * comparing two lines, not by a collision-resistant protocol.
+ */
+export const featureEvidence = (feature) => {
+    const scenarios = [...feature.scenarios]
+        .sort((a, b) => a.name.localeCompare(b.name) || a.title.localeCompare(b.title))
+        .map((scenario) => [
+        scenario.name,
+        scenario.steps.map((step) => [step.phase, step.sentence]
+            .filter(Boolean)
+            .join(' ')
+            .replace(/\s+/g, ' ')
+            .trim()),
+        scenario.screenshots
+            .map((shot) => shot.id ?? shot.name ?? shot.path)
+            .sort((a, b) => a.localeCompare(b)),
+    ]);
+    return createHash('sha256')
+        .update(JSON.stringify(scenarios))
+        .digest('hex')
+        .slice(0, 7);
+};
+export const parseGuideLock = (content) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (e) {
+        throw new Error(`The guide lock is unreadable: ${e?.message ?? e}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('The guide lock is not an object of feature id to evidence.');
+    }
+    const lock = {};
+    for (const [id, evidence] of Object.entries(parsed)) {
+        if (typeof evidence !== 'string') {
+            throw new Error(`The guide lock holds a non-string evidence for '${id}'.`);
+        }
+        lock[id] = evidence;
+    }
+    return lock;
+};
+export const renderGuideLock = (features, cited) => {
+    const documented = new Set(cited);
+    const lock = {};
+    for (const feature of [...features].sort((a, b) => a.id.localeCompare(b.id))) {
+        if (feature.document && documented.has(feature.id)) {
+            lock[feature.id] = featureEvidence(feature);
+        }
+    }
+    return `${JSON.stringify(lock, null, 2)}\n`;
+};
+export const checkGuideCoverage = (features, pages, lock = {}) => {
+    const byId = new Map(features.map((feature) => [feature.id, feature]));
+    const cited = new Set();
+    const unknown = [];
+    const optedOut = [];
+    const figureless = [];
+    const stale = [];
+    for (const page of [...pages].sort((a, b) => a.path.localeCompare(b.path))) {
+        for (const id of page.features) {
+            const feature = byId.get(id);
+            if (!feature) {
+                unknown.push({ path: page.path, featureId: id });
+                continue;
+            }
+            if (!feature.document) {
+                optedOut.push({ path: page.path, featureId: id });
+                continue;
+            }
+            cited.add(id);
+            const figures = feature.scenarios.reduce((total, scenario) => total + scenario.screenshots.length + (scenario.videos?.length ?? 0), 0);
+            if (figures === 0) {
+                figureless.push({ path: page.path, featureId: id });
+            }
+            const locked = lock[id];
+            const current = featureEvidence(feature);
+            if (locked !== undefined && locked !== current) {
+                stale.push({ path: page.path, featureId: id, locked, current });
+            }
+        }
+    }
+    return {
+        cited: [...cited].sort((a, b) => a.localeCompare(b)),
+        missing: features
+            .filter((feature) => feature.document && !cited.has(feature.id))
+            .map((feature) => feature.id)
+            .sort((a, b) => a.localeCompare(b)),
+        unknown,
+        optedOut,
+        figureless,
+        stale,
+    };
+};
+/**
+ * The marker a generated region opens with.
+ *
+ * An HTML comment, because it is the one thing every markdown renderer already
+ * agrees to ignore, and because a page that has been through the compiler still
+ * reads as an ordinary document in an editor, a diff and a preview. It carries
+ * the feature id and nothing else: a rebuild rewrites exactly the block for that
+ * feature and leaves every sentence a human wrote — before it, after it, or
+ * around another feature's block — untouched, and there is no value on the line
+ * anyone has to keep correct.
+ */
+const generatedOpen = (featureId) => `<!-- pikku:guide feature=${featureId} -->`;
+const GENERATED_CLOSE = '<!-- /pikku:guide -->';
+/**
+ * The `evidence=` attribute is still matched, never written: guides built
+ * before the hash moved into the lock carry it, and a rebuild is what removes
+ * it.
+ */
+const generatedRegion = (featureId) => new RegExp(`<!--\\s*pikku:guide\\s+feature=${escapeRegExp(featureId)}[^>]*-->[\\s\\S]*?${escapeRegExp(GENERATED_CLOSE)}`);
+/** Any region, for dropping the blocks of features a page no longer cites. */
+const ANY_GENERATED_REGION = /<!--\s*pikku:guide\s+feature=[^\s]+[^>]*-->[\s\S]*?<!-- \/pikku:guide -->/g;
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const GENERATED_FEATURE = /<!--\s*pikku:guide\s+feature=([^\s]+)/;
+/**
+ * One feature's generated region: the figures its run filed, and nothing else.
+ *
+ * Neither the steps nor the scenario's own title and description are rendered.
+ * All three are written to name and prove a test — third person, about the
+ * system, ending in the regression they guard — and a reader arriving at a
+ * documentation page wants none of it. The words on the page are the author's;
+ * what a run can contribute that no author can is the evidence that the words
+ * are still true, which is a picture of the thing actually doing it.
+ *
+ * A data-driven scenario runs once per row and so appears once per row in the
+ * record. The rows differ only in their inputs, so their figures are collected
+ * in run order and deduplicated by artifact id rather than repeated.
+ *
+ * A recording leads the scenario it belongs to, because it shows the whole flow
+ * the stills are moments of. It is emitted as an ordinary figure: this module
+ * writes no HTML, so what makes a `.webm` a player rather than a broken image
+ * is the consumer's renderer, the same way a consumer resolves the base.
+ */
+const renderFeature = (feature, artifactBase) => {
+    const figures = [];
+    const seen = new Set();
+    for (const scenario of feature.scenarios) {
+        for (const video of scenario.videos ?? []) {
+            const key = video.id ?? video.path;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            const caption = video.actor
+                ? `${scenario.title} — ${video.actor}`
+                : scenario.title;
+            figures.push(`![${caption}](${artifactBase}${video.path})`);
+        }
+        for (const shot of scenario.screenshots) {
+            const key = shot.id ?? shot.path;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            figures.push(`![${shot.name ?? scenario.title}](${artifactBase}${shot.path})`);
+        }
+    }
+    return figures.join('\n\n');
+};
+/**
+ * Merge one editorial source with the blocks its features generate.
+ *
+ * Hand-written prose and generated blocks stay separable, so a rebuild never
+ * clobbers writing: the body is the author's file, and only the regions between
+ * the markers are replaced. A block whose feature the page has stopped citing is
+ * dropped, since nothing would ever rewrite it again.
+ *
+ * `artifactBase` is prefixed onto every artifact key: the relative path from
+ * this page to the run's artifact root, which is all this module knows about
+ * where anything lives.
+ */
+export const renderGuidePage = (page, features, artifactBase) => {
+    const cited = page.features.filter((id) => features.has(id));
+    const first = cited[0] ? features.get(cited[0]) : undefined;
+    let body = page.body.replace(ANY_GENERATED_REGION, (region) => {
+        const id = region.match(GENERATED_FEATURE)?.[1];
+        return id && cited.includes(id) ? region : '';
+    });
+    for (const id of cited) {
+        const feature = features.get(id);
+        const block = [
+            generatedOpen(id),
+            renderFeature(feature, artifactBase),
+            GENERATED_CLOSE,
+        ]
+            .filter((part) => part.length > 0)
+            .join('\n\n');
+        body = body.replace(generatedRegion(id), block);
+    }
+    const title = page.title ?? first?.name;
+    const description = page.description ?? first?.description;
+    // Only `title` and `description` are the compiler's to fill in, and only when
+    // the page states neither; every other key the author wrote passes through in
+    // the order they wrote it.
+    const { title: _t, description: _d, ...rest } = page.frontmatter;
+    const frontmatter = {
+        ...(title ? { title } : {}),
+        ...(description ? { description } : {}),
+        ...rest,
+    };
+    const head = Object.keys(frontmatter).length > 0
+        ? `---\n${stringify(frontmatter, { lineWidth: 0 }).trimEnd()}\n---`
+        : '---\n---';
+    return `${head}\n\n${trim(body)}\n`;
+};
+const trim = (value) => value.replace(/^\n+/, '').replace(/\s+$/, '');
+/** The phase a recorded sentence opens with, split back off it. */
+const PHASE = /^(Given|When|Then|And)\s+([\s\S]*)$/;
+/**
+ * A recorded step sentence, split into its gherkin keyword and the rest.
+ *
+ * The run stores the composed sentence — `Given    yasser signs in`, padded to
+ * the reporter's keyword column — so the phase is already in it and is read
+ * back off the record rather than re-derived from today's source.
+ */
+export const guideStep = (sentence) => {
+    const match = sentence.trim().match(PHASE);
+    return match
+        ? { phase: match[1], sentence: match[2].replace(/\s+/g, ' ').trim() }
+        : { sentence: sentence.replace(/\s+/g, ' ').trim() };
+};

package/dist/src/functions/commands/scenario-ladder.d.ts

@@ -2,7 +2,7 @@ import type { ScenarioSurface, ScenarioStepPhase } from '@pikku/core/scenario';
 import type { WorkflowStepMeta } from '@pikku/core/workflow';
 import type { FunctionsMeta } from '@pikku/core/services';
 import type { PersonaDefinitions } from '@pikku/core/persona';
-import type { ScenarioFailureDetail, ScenarioStepRow } from '@pikku/core/scenario';
+import type { ScenarioFailureDetail, ScenarioStepRow, ScenarioStepVideoOffset } from '@pikku/core/scenario';
 export interface ScenarioStepProse {
     phase: ScenarioStepPhase;
     description: string;
@@ -25,6 +25,8 @@ export interface ScenarioStepOutcome {
     input?: unknown;
     /** The step function that ran it, as recorded on the run. */
     stepFunc?: string;
+    /** Where the step fell in each recorded actor's video, as the run stamped it. */
+    video?: ScenarioStepVideoOffset[];
 }
 /**
  * One scenario's prose, indexed the two ways a run step can be joined back to

package/dist/src/functions/commands/scenario-ladder.js

@@ -203,6 +203,7 @@ export const scenarioStepRows = (steps, prose) => {
             status: step.status,
             durationMs: step.durationMs,
             error: step.error,
+            ...(step.video?.length ? { video: step.video } : {}),
         };
     });
 };

package/dist/src/functions/commands/scenario-plan.d.ts

@@ -1,5 +1,5 @@
 import type { CoreWorkflow } from '@pikku/core/workflow';
-import type { CoreFeature } from '@pikku/core/scenario';
+import type { CoreFeature, ScenarioResult } from '@pikku/core/scenario';
 /** One scenario run: a scenario name and, for a feature's paired entry, its input. */
 export type ScenarioPlanEntry = {
     scenarioName: string;
@@ -60,3 +60,19 @@ export type ScenarioPlan = {
  * five scenarios still runs the feature's hooks exactly once around those two.
  */
 export declare const buildScenarioPlan: ({ scenarios, features, registrations, flows, featureIds, tags, excludeTags, }: ScenarioPlanInput) => ScenarioPlan;
+/** Which registration ran, and under which feature, as the registry names them. */
+export type ScenarioRunIdentity = {
+    scenarioName: string;
+    featureId?: string;
+    featureName?: string;
+    tags?: string[];
+};
+/**
+ * What a result carries beyond its own outcome.
+ *
+ * The ids come from the plan, which read them off the registry, rather than
+ * from the run's label: a label is assembled out of a feature's title and a
+ * scenario's prose, and both are rewritten freely, so nothing that outlives a
+ * run can be recovered from one.
+ */
+export declare const identifyScenarioResult: (result: ScenarioResult, identity: ScenarioRunIdentity) => ScenarioResult;

package/dist/src/functions/commands/scenario-plan.js

@@ -104,3 +104,18 @@ export const buildScenarioPlan = ({ scenarios, features, registrations, flows, f
     }
     return { groups, unresolved };
 };
+/**
+ * What a result carries beyond its own outcome.
+ *
+ * The ids come from the plan, which read them off the registry, rather than
+ * from the run's label: a label is assembled out of a feature's title and a
+ * scenario's prose, and both are rewritten freely, so nothing that outlives a
+ * run can be recovered from one.
+ */
+export const identifyScenarioResult = (result, identity) => ({
+    ...result,
+    scenarioName: identity.scenarioName,
+    ...(identity.featureId ? { featureId: identity.featureId } : {}),
+    ...(identity.featureName ? { feature: identity.featureName } : {}),
+    ...(identity.tags?.length ? { tags: identity.tags } : {}),
+});

package/dist/src/functions/commands/scenario.d.ts

@@ -49,3 +49,33 @@ export declare const scenarioRun: import("#pikku/function").PikkuFunctionConfig<
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
+/**
+ * `pikku scenario guide` — the suite, written out as markdown.
+ *
+ * Structure comes from the registry (which features exist, what their scenarios
+ * are called), and evidence from the latest run record (what the steps actually
+ * said, and what they filed). Editorial prose comes from the project's own
+ * `docs/` sources, which cite a feature by leaving the marker pair where its
+ * block belongs; this merges the three and writes one markdown file per source.
+ * It renders nothing, resolves no asset URLs and calls no model: the writing is
+ * somebody else's concern, and this is the compiler that keeps it honest.
+ */
+export declare const scenarioGuide: import("#pikku/function").PikkuFunctionConfig<{
+    docs?: string;
+    output?: string;
+    runId?: string;
+    allowUndocumented?: boolean;
+    artifactBase?: string;
+}, void, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    docs?: string;
+    output?: string;
+    runId?: string;
+    allowUndocumented?: boolean;
+    artifactBase?: string;
+}, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    docs?: string;
+    output?: string;
+    runId?: string;
+    allowUndocumented?: boolean;
+    artifactBase?: string;
+}, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;