@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/core/smoke/scenario-parser.js

@@ -0,0 +1,316 @@
+/**
+ * Scenario DSL parser for the Pugi MCP test harness (BIG TRACK 10
+ * Phase 1, 2026-05-27).
+ *
+ * Background — CEO directive `feedback_live_console_test_every_publish`:
+ * every CLI publish must be smoke-tested against a fixed corpus of
+ * scripted dialogs before it is announced to the operator. The manual
+ * routine ("npm i -g + pugi --version + run identity prompt + verify
+ * Pugi self-id") is exactly the kind of toil a deterministic harness
+ * should automate. Phase 1 lays the foundation; the corpus + headless
+ * runner + CI gate.
+ *
+ * Format — one scenario per file, line-based, intentionally minimal so
+ * non-engineers can author cases. The grammar:
+ *
+ *   # comment        — ignored
+ *   # scenario: <id> — optional metadata
+ *   > "<input>"      — single user turn (the engine sees this verbatim)
+ *   EXPECT: <pred>   — positive assertion against the next persona-turn
+ *                      envelope OR a tool-call envelope. Multiple stack
+ *                      against the SAME prior `>` turn until the next
+ *                      `>` resets the cursor.
+ *   EXPECT_NOT:<pred>— negative assertion (same cursor semantics).
+ *   EXPECT_FILE:<file> exists [with content "<text>"]
+ *                    — filesystem assertion fired AFTER the scenario
+ *                      finishes. Matches both `exists` literal and a
+ *                      content substring check.
+ *
+ * The DSL parser is deliberately a pure function over the file contents:
+ * the runner module is the thing that spawns `pugi --headless` and
+ * matches assertions against the emitted envelope stream. Keeping the
+ * parser pure is what lets us spec it with no fixtures.
+ *
+ * Anti-design — we did NOT use YAML/JSON. The line-based form survives
+ * copy-paste from a chat transcript ("> 'ты кто?'" maps 1:1 to the way
+ * an operator sees a Pugi dialog), and prevents drift between scenario
+ * authoring style and how the operator actually drives the CLI.
+ */
+/**
+ * Parse a scenario file body into a `ParsedScenario`. Returns errors
+ * alongside the partial scenario so the runner can surface every issue
+ * in one pass rather than failing on the first malformed line. The
+ * shape mirrors what TypeScript's diagnostics array looks like —
+ * familiar pattern for any operator who has read a tsc error.
+ *
+ * `filePath` is informational; we ALSO consume it to derive the
+ * default scenario id when the file body does not declare one.
+ */
+export function parseScenario(filePath, body) {
+    const errors = [];
+    const steps = [];
+    let title;
+    let explicitId;
+    const lines = body.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        const lineNo = i + 1;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#')) {
+            // Metadata comments. `# scenario: <id>` populates the explicit
+            // id; `# title: <text>` populates the title. Plain `# anything`
+            // is a free-form comment.
+            const meta = /^#\s*(scenario|title)\s*:\s*(.+?)\s*$/i.exec(trimmed);
+            if (meta) {
+                const key = (meta[1] ?? '').toLowerCase();
+                const value = meta[2] ?? '';
+                if (key === 'scenario')
+                    explicitId = value;
+                else if (key === 'title')
+                    title = value;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('>')) {
+            const body = parseQuotedInput(trimmed.slice(1).trim());
+            if (body === null) {
+                errors.push({
+                    line: lineNo,
+                    message: 'user input line must be quoted (e.g. > "hello")',
+                });
+                continue;
+            }
+            steps.push({ kind: 'user-input', body, line: lineNo });
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT_FILE:')) {
+            const payload = trimmed.slice('EXPECT_FILE:'.length).trim();
+            const fileStep = parseExpectFile(payload, lineNo);
+            if (fileStep.errors.length > 0) {
+                errors.push(...fileStep.errors);
+                continue;
+            }
+            if (fileStep.step)
+                steps.push(fileStep.step);
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT_NOT:')) {
+            const payload = trimmed.slice('EXPECT_NOT:'.length).trim();
+            const parsed = parseAssertion(payload, lineNo);
+            if (parsed.errors.length > 0) {
+                errors.push(...parsed.errors);
+                continue;
+            }
+            if (parsed.pattern) {
+                steps.push({
+                    kind: 'expect',
+                    polarity: 'negative',
+                    pattern: parsed.pattern,
+                    anchor: 'last-user',
+                    line: lineNo,
+                });
+            }
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT:')) {
+            const payload = trimmed.slice('EXPECT:'.length).trim();
+            const parsed = parseAssertion(payload, lineNo);
+            if (parsed.errors.length > 0) {
+                errors.push(...parsed.errors);
+                continue;
+            }
+            if (parsed.pattern) {
+                steps.push({
+                    kind: 'expect',
+                    polarity: 'positive',
+                    pattern: parsed.pattern,
+                    anchor: 'last-user',
+                    line: lineNo,
+                });
+            }
+            continue;
+        }
+        errors.push({
+            line: lineNo,
+            message: `unrecognized directive (expected one of: > "...", EXPECT:, EXPECT_NOT:, EXPECT_FILE:, # comment): ${trimmed}`,
+        });
+    }
+    const id = explicitId ?? deriveDefaultId(filePath);
+    const scenario = {
+        id,
+        ...(title !== undefined ? { title } : {}),
+        filePath,
+        steps,
+    };
+    return { scenario, errors };
+}
+/**
+ * Strip the wrapping quotes from a `> "..."` user line. Returns the
+ * inner string when the input is properly quoted (single OR double),
+ * otherwise null so the parser can surface a diagnostic. Allowing both
+ * quote styles is a thoughtful nicety — Russian scenarios frequently
+ * embed double quotes inside a Cyrillic phrase, e.g. `> 'ты "сделай"
+ * хорошо'`.
+ */
+function parseQuotedInput(raw) {
+    if (raw.length < 2)
+        return null;
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        return raw.slice(1, -1);
+    }
+    // Permissive fallback — a bare unquoted line is still parsed as the
+    // user input (lets quick prototypes work). The runner does not
+    // distinguish between quoted and unquoted forms.
+    return raw;
+}
+/**
+ * Parse the right-hand side of an `EXPECT:` / `EXPECT_NOT:` directive.
+ * Discriminates between the three pattern kinds by looking at the
+ * leading keyword. Errors collect rather than throw so the runner can
+ * report multiple parse problems in one pass.
+ */
+function parseAssertion(payload, line) {
+    const errors = [];
+    if (payload.length === 0) {
+        return {
+            pattern: null,
+            errors: [{ line, message: 'EXPECT directive requires a pattern' }],
+        };
+    }
+    const personaMatch = /^persona-turn\s+contains\s+(.+)$/i.exec(payload);
+    if (personaMatch) {
+        const substrings = parseOrList(personaMatch[1] ?? '');
+        if (substrings.length === 0) {
+            errors.push({
+                line,
+                message: 'persona-turn contains requires one or more quoted substrings',
+            });
+            return { pattern: null, errors };
+        }
+        return {
+            pattern: { kind: 'persona-turn-contains', substrings },
+            errors,
+        };
+    }
+    const toolMatch = /^tool-call(?:\s+(.+))?$/i.exec(payload);
+    if (toolMatch) {
+        const remainder = (toolMatch[1] ?? '').trim();
+        const kv = parseKeyValuePairs(remainder);
+        const result = { kind: 'tool-call' };
+        if (kv.kind !== undefined)
+            result.tool = kv.kind;
+        const argsSubset = {};
+        for (const [k, v] of Object.entries(kv)) {
+            if (k === 'kind')
+                continue;
+            argsSubset[k] = v;
+        }
+        if (Object.keys(argsSubset).length > 0)
+            result.argsSubset = argsSubset;
+        return { pattern: result, errors };
+    }
+    const envelopeMatch = /^envelope\s+kind=([\w-]+)$/i.exec(payload);
+    if (envelopeMatch) {
+        return {
+            pattern: {
+                kind: 'envelope-kind',
+                envelopeKind: envelopeMatch[1] ?? '',
+            },
+            errors,
+        };
+    }
+    errors.push({
+        line,
+        message: `unrecognized EXPECT pattern: ${payload}`,
+    });
+    return { pattern: null, errors };
+}
+/**
+ * Parse the EXPECT_FILE payload. Grammar:
+ *
+ *   <relative path> exists
+ *   <relative path> exists with content "<text>"
+ *
+ * The path is unquoted (everything up to `exists`); the content phrase
+ * is double-quoted so it can include whitespace.
+ */
+function parseExpectFile(payload, line) {
+    const errors = [];
+    const match = /^(\S+)\s+exists(?:\s+with\s+content\s+"([^"]*)")?\s*$/.exec(payload);
+    if (!match) {
+        errors.push({
+            line,
+            message: 'EXPECT_FILE expects: <path> exists [with content "<text>"]',
+        });
+        return { step: null, errors };
+    }
+    const file = match[1];
+    if (!file) {
+        errors.push({ line, message: 'EXPECT_FILE missing file path' });
+        return { step: null, errors };
+    }
+    const content = match[2];
+    const step = content !== undefined
+        ? { kind: 'expect-file', file, content, line }
+        : { kind: 'expect-file', file, line };
+    return { step, errors };
+}
+/**
+ * Split a `"..." OR "..." OR "..."` list into the inner strings.
+ * Whitespace tolerant; the `OR` is case-insensitive so authors who
+ * type `or` lowercase are not punished.
+ */
+function parseOrList(raw) {
+    const parts = raw.split(/\s+OR\s+/i);
+    const result = [];
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0)
+            continue;
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            result.push(trimmed.slice(1, -1));
+        }
+        else {
+            // Permissive — accept unquoted token as a single substring. The
+            // parser does not enforce quotes here because scenario authors
+            // type Cyrillic without delimiters all the time.
+            result.push(trimmed);
+        }
+    }
+    return result;
+}
+/**
+ * Parse a whitespace-separated `key=value` list (e.g.
+ * `kind=Write file=hello.txt`) into a flat record. Values may be
+ * double-quoted to embed whitespace, though the corpus today uses bare
+ * tokens.
+ */
+function parseKeyValuePairs(raw) {
+    const out = {};
+    if (raw.length === 0)
+        return out;
+    const re = /(\w+)=(?:"([^"]*)"|(\S+))/g;
+    let match;
+    while ((match = re.exec(raw)) !== null) {
+        const key = match[1];
+        if (!key)
+            continue;
+        const value = match[2] !== undefined ? match[2] : (match[3] ?? '');
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Derive a default scenario id from the file path: strip the directory,
+ * drop the trailing `.scenario.txt` (or `.txt`) suffix.
+ */
+function deriveDefaultId(filePath) {
+    const base = filePath.split(/[/\\]/).pop() ?? filePath;
+    return base.replace(/\.scenario\.txt$/i, '').replace(/\.txt$/i, '');
+}
+//# sourceMappingURL=scenario-parser.js.map