focused-spec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 focused-spec contributors
+
+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

@@ -0,0 +1,21 @@
+# focused-spec
+
+`focused-spec` connects small behavioral scenarios to exact executable evidence. The core is language- and test-framework-agnostic; projects provide local runner plugins for their own test stacks.
+
+## Start here
+
+- [Documentation map](docs/README.md)
+- [Concepts](docs/concepts/README.md)
+- [Install the CLI and agent skill](docs/guides/install.md)
+- [Configure scenarios](docs/guides/configuration.md)
+- [Implement runners](docs/guides/runners.md)
+- [CLI reference](docs/reference/cli.md)
+- [Development workflow](docs/development/README.md)
+- [Agent evals](docs/development/agent-evals.md)
+
+## Installation
+
+```sh
+npm install --save-dev focused-spec
+npx --yes skills add bamanoz/focused-spec --skill focused-spec
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { isAbsolute, resolve } from 'node:path';
+import { loadConfig } from './config.js';
+import { executePlan } from './executor.js';
+import { parseEvidenceReference } from './parser.js';
+import { planEvidence } from './planner.js';
+import { validateFocusedSpecs } from './validate.js';
+const USAGE = `Usage:
+  focused-spec validate [--root <path>] [--config <path>] [--change <name>] [--strict] [--syntax-only] [--json]
+  focused-spec run [--root <path>] [--config <path>] [--change <name>] [--scenario <id>] [--allow-skip] [--json]
+`;
+function parseArguments(argumentsList) {
+    const command = argumentsList[0];
+    if (command !== 'validate' && command !== 'run')
+        throw new Error(USAGE);
+    let root = process.cwd();
+    let configPath;
+    let changeName;
+    let strict = false;
+    let syntaxOnly = false;
+    let json = false;
+    let allowSkip = false;
+    let scenarioId;
+    for (let index = 1; index < argumentsList.length; index += 1) {
+        const argument = argumentsList[index];
+        if (argument === '--strict')
+            strict = true;
+        else if (argument === '--syntax-only')
+            syntaxOnly = true;
+        else if (argument === '--json')
+            json = true;
+        else if (argument === '--allow-skip')
+            allowSkip = true;
+        else if (argument === '--root' || argument === '--config' || argument === '--change' || argument === '--scenario') {
+            const value = argumentsList[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                throw new Error(`missing value for ${argument}\n${USAGE}`);
+            index += 1;
+            if (argument === '--root')
+                root = resolve(value);
+            else if (argument === '--config')
+                configPath = value;
+            else if (argument === '--change')
+                changeName = value;
+            else
+                scenarioId = value;
+        }
+        else {
+            throw new Error(`unknown argument ${String(argument)}\n${USAGE}`);
+        }
+    }
+    if (command === 'validate' && (allowSkip || scenarioId !== undefined)) {
+        throw new Error(`--allow-skip and --scenario are valid only for run\n${USAGE}`);
+    }
+    if (command === 'run' && (strict || syntaxOnly))
+        throw new Error(`run is always strict and cannot be syntax-only\n${USAGE}`);
+    return {
+        command,
+        root,
+        ...(configPath === undefined ? {} : { configPath }),
+        ...(changeName === undefined ? {} : { changeName }),
+        strict,
+        syntaxOnly,
+        json,
+        allowSkip,
+        ...(scenarioId === undefined ? {} : { scenarioId }),
+    };
+}
+function runContext(options) {
+    return {
+        validationScope: {
+            current: true,
+            changes: options.changeName === undefined
+                ? { mode: 'all-active' }
+                : { mode: 'selected', name: options.changeName },
+        },
+        executionSelection: {
+            source: options.changeName === undefined ? 'current' : 'change',
+            ...(options.changeName === undefined ? {} : { change: options.changeName }),
+            ...(options.scenarioId === undefined ? {} : { scenario: options.scenarioId }),
+        },
+    };
+}
+function displayRunContext(context) {
+    const changes = context.validationScope.changes;
+    const validation = changes.mode === 'all-active'
+        ? 'current specifications and all active changes'
+        : `current specifications and selected change ${changes.name}`;
+    const selection = context.executionSelection;
+    const execution = selection.source === 'current'
+        ? 'current specifications'
+        : `change ${String(selection.change)}`;
+    const scenario = selection.scenario === undefined ? '' : `, scenario ${selection.scenario}`;
+    return `validation scope: ${validation}\nexecution selection: ${execution}${scenario}\n`;
+}
+function displayViolation(violation) {
+    const location = violation.line === undefined ? violation.path : `${violation.path}:${violation.line}`;
+    return `${location}: ${violation.message}`;
+}
+function printViolations(violations, json, context) {
+    if (json) {
+        const output = context === undefined
+            ? { valid: false, violations }
+            : { valid: false, executionStarted: false, ...context, violations };
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        return;
+    }
+    if (context !== undefined)
+        process.stderr.write(`${displayRunContext(context)}execution did not start\n`);
+    for (const violation of violations)
+        process.stderr.write(`${displayViolation(violation)}\n`);
+}
+function printExecution(result, json, context) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ...result, executionStarted: result.targetCount > 0, ...context }, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(displayRunContext(context));
+    for (const scenario of result.scenarios) {
+        process.stdout.write(`${scenario.status} ${scenario.id}\n`);
+        for (const evidence of scenario.evidence) {
+            process.stdout.write(`  ${evidence.status} ${evidence.reference}\n`);
+            if (evidence.diagnostic !== undefined)
+                process.stdout.write(`    ${evidence.diagnostic.split('\n').join('\n    ')}\n`);
+        }
+    }
+    const counts = { PASS: 0, FAIL: 0, SKIP: 0, ERROR: 0 };
+    for (const scenario of result.scenarios)
+        counts[scenario.status] += 1;
+    process.stdout.write(`summary: ${counts.PASS} PASS, ${counts.FAIL} FAIL, ${counts.SKIP} SKIP, ${counts.ERROR} ERROR; ${result.targetCount} unique targets\n`);
+}
+function validationCounts(documents, plan) {
+    let scenarios = 0;
+    let plannedEvidence = 0;
+    for (const document of documents) {
+        scenarios += document.scenarios.length;
+        for (const scenario of document.scenarios) {
+            for (const raw of scenario.evidence) {
+                const reference = parseEvidenceReference(raw);
+                if (!('error' in reference) && reference.planned)
+                    plannedEvidence += 1;
+            }
+        }
+    }
+    return { scenarios, plannedEvidence, targets: plan.targets.length };
+}
+async function main(argumentsList) {
+    const options = parseArguments(argumentsList);
+    const context = options.command === 'run' ? runContext(options) : undefined;
+    const projectRoot = isAbsolute(options.root) ? options.root : resolve(options.root);
+    const loaded = await loadConfig(projectRoot, options.configPath);
+    if (loaded.config === undefined) {
+        printViolations(loaded.violations, options.json, context);
+        return 1;
+    }
+    const validation = await validateFocusedSpecs(projectRoot, loaded.config, {
+        ...(options.changeName === undefined ? {} : { changeName: options.changeName }),
+        strict: options.command === 'run' || options.strict,
+    });
+    if (validation.violations.length > 0) {
+        printViolations(validation.violations, options.json, context);
+        return 1;
+    }
+    if (options.syntaxOnly) {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ valid: true, mode: 'syntax-only' }, null, 2)}\n`);
+        else
+            process.stdout.write('focused specifications are structurally valid\n');
+        return 0;
+    }
+    const resolution = await planEvidence(projectRoot, loaded.config, validation.resolutionDocuments);
+    if (resolution.violations.length > 0) {
+        printViolations(resolution.violations, options.json, context);
+        return 1;
+    }
+    if (options.command === 'validate') {
+        if (resolution.plan === undefined)
+            throw new Error('evidence validation did not produce a resolution plan');
+        const counts = validationCounts(validation.resolutionDocuments, resolution.plan);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ valid: true, ...counts }, null, 2)}\n`);
+        else
+            process.stdout.write(`focused specifications are valid: ${counts.scenarios} scenarios, ${counts.plannedEvidence} planned evidence, ${counts.targets} unique targets\n`);
+        return 0;
+    }
+    const planned = await planEvidence(projectRoot, loaded.config, validation.targetDocuments, {
+        ...(options.scenarioId === undefined ? {} : { scenarioId: options.scenarioId }),
+    });
+    if (planned.violations.length > 0 || planned.plan === undefined) {
+        printViolations(planned.violations, options.json, context);
+        return 1;
+    }
+    const result = await executePlan(planned.plan, { allowSkip: options.allowSkip });
+    printExecution(result, options.json, context);
+    return result.success ? 0 : 1;
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { FocusedSpecConfig, Violation } from './model.js';
+import type { JsonValue } from './runner-api.js';
+export declare function isJsonValue(value: unknown): value is JsonValue;
+export declare function loadConfig(projectRoot: string, explicitPath?: string): Promise<{
+    config?: FocusedSpecConfig;
+    path: string;
+    violations: readonly Violation[];
+}>;

package/dist/config.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { parse } from 'yaml';
+const RUNNER_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const PARENT_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/u;
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    const record = object(value);
+    return record !== undefined && Object.values(record).every(isJsonValue);
+}
+function parseRunner(id, value, path, violations) {
+    const record = object(value);
+    if (!RUNNER_ID.test(id)) {
+        violations.push({ path, message: `invalid runner ID ${id}` });
+        return undefined;
+    }
+    if (record === undefined || typeof record.module !== 'string' || record.module.length === 0) {
+        violations.push({ path, message: `runner ${id} must define a non-empty module path` });
+        return undefined;
+    }
+    if (record.cwd !== undefined && (typeof record.cwd !== 'string' || record.cwd.length === 0)) {
+        violations.push({ path, message: `runner ${id} cwd must be a non-empty relative path` });
+        return undefined;
+    }
+    if (record.timeoutMs !== undefined && (!Number.isInteger(record.timeoutMs) || record.timeoutMs <= 0)) {
+        violations.push({ path, message: `runner ${id} timeoutMs must be a positive integer` });
+        return undefined;
+    }
+    if (record.options !== undefined && !isJsonValue(record.options)) {
+        violations.push({ path, message: `runner ${id} options must be JSON-compatible` });
+        return undefined;
+    }
+    return {
+        module: record.module,
+        ...(record.cwd === undefined ? {} : { cwd: record.cwd }),
+        ...(record.timeoutMs === undefined ? {} : { timeoutMs: record.timeoutMs }),
+        ...(record.options === undefined ? {} : { options: record.options }),
+    };
+}
+export async function loadConfig(projectRoot, explicitPath) {
+    const path = explicitPath === undefined
+        ? resolve(projectRoot, '.focused-spec/config.yaml')
+        : isAbsolute(explicitPath) ? explicitPath : resolve(projectRoot, explicitPath);
+    let source;
+    try {
+        source = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        return { path, violations: [{ path, message: `cannot read configuration: ${error instanceof Error ? error.message : String(error)}` }] };
+    }
+    let value;
+    try {
+        value = parse(source);
+    }
+    catch (error) {
+        return { path, violations: [{ path, message: `invalid YAML: ${error instanceof Error ? error.message : String(error)}` }] };
+    }
+    const violations = [];
+    const root = object(value);
+    if (root === undefined || root.version !== 1) {
+        return { path, violations: [{ path, message: 'configuration version must be 1' }] };
+    }
+    const specifications = object(root.specifications);
+    let specificationConfig;
+    if (specifications?.source === 'openspec') {
+        if (specifications.root !== undefined && (typeof specifications.root !== 'string' || specifications.root.length === 0 || isAbsolute(specifications.root) || PARENT_SEGMENT.test(specifications.root))) {
+            violations.push({ path, message: 'specifications.root must be a non-empty relative path' });
+        }
+        else {
+            specificationConfig = {
+                source: 'openspec',
+                ...(specifications.root === undefined ? {} : { root: specifications.root }),
+            };
+        }
+    }
+    else if (specifications?.source === 'files') {
+        if (!Array.isArray(specifications.paths) || specifications.paths.length === 0 || !specifications.paths.every(item => typeof item === 'string' && item.length > 0 && !isAbsolute(item) && !PARENT_SEGMENT.test(item))) {
+            violations.push({ path, message: 'file specifications require a non-empty paths string array' });
+        }
+        else {
+            specificationConfig = { source: 'files', paths: specifications.paths };
+        }
+    }
+    else {
+        violations.push({ path, message: 'specifications.source must be openspec or files' });
+    }
+    const runnerValues = object(root.runners);
+    if (runnerValues === undefined)
+        violations.push({ path, message: 'runners must be an object' });
+    const runners = {};
+    for (const [id, runner] of Object.entries(runnerValues ?? {})) {
+        const parsed = parseRunner(id, runner, path, violations);
+        if (parsed !== undefined)
+            runners[id] = parsed;
+    }
+    if (specificationConfig === undefined || violations.length > 0)
+        return { path, violations };
+    return {
+        path,
+        violations,
+        config: { version: 1, specifications: specificationConfig, runners },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAA;AAI5B,MAAM,SAAS,GAAG,gCAAgC,CAAA;AAClD,MAAM,cAAc,GAAG,6BAA6B,CAAA;AAEpD,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAC,KAAgC;QAClC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAC1F,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;AACzE,CAAC;AAGD,SAAS,WAAW,CAAC,EAAU,EAAE,KAAc,EAAE,IAAY,EAAE,UAAuB;IACpF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC,CAAA;QAC7D,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5F,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,sCAAsC,EAAE,CAAC,CAAA;QACtF,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAC5F,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,wCAAwC,EAAE,CAAC,CAAA;QACxF,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,IAAK,MAAM,CAAC,SAAoB,IAAI,CAAC,CAAC,EAAE,CAAC;QACjH,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,uCAAuC,EAAE,CAAC,CAAA;QACvF,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACjE,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,kCAAkC,EAAE,CAAC,CAAA;QAClF,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAa,EAAE,CAAC;QAClE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAmB,EAAE,CAAC;QACpF,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAoB,EAAE,CAAC;KAClF,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,WAAmB,EAAE,YAAqB;IAKzE,MAAM,IAAI,GAAG,YAAY,KAAK,SAAS;QACrC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,2BAA2B,CAAC;QACnD,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;IAChF,IAAI,MAAc,CAAA;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,8BAA8B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;IAC1I,CAAC;IAED,IAAI,KAAc,CAAA;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;IAC7H,CAAC;IAED,MAAM,UAAU,GAAgB,EAAE,CAAA;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC,EAAE,CAAA;IACrF,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAClD,IAAI,mBAAoE,CAAA;IACxE,IAAI,cAAc,EAAE,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1C,IAAI,cAAc,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,cAAc,CAAC,IAAI,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACtM,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,uDAAuD,EAAE,CAAC,CAAA;QAC7F,CAAC;aAAM,CAAC;YACN,mBAAmB,GAAG;gBACpB,MAAM,EAAE,UAAU;gBAClB,GAAG,CAAC,cAAc,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,IAAc,EAAE,CAAC;aACtF,CAAA;QACH,CAAC;IACH,CAAC;SAAM,IAAI,cAAc,EAAE,MAAM,KAAK,OAAO,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACrN,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,4DAA4D,EAAE,CAAC,CAAA;QAClG,CAAC;aAAM,CAAC;YACN,mBAAmB,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,CAAC,KAAiB,EAAE,CAAA;QACpF,CAAC;IACH,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,iDAAiD,EAAE,CAAC,CAAA;IACvF,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACzC,IAAI,YAAY,KAAK,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC,CAAA;IAC/F,MAAM,OAAO,GAAiC,EAAE,CAAA;IAChD,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAA;QACxD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,GAAG,MAAM,CAAA;IAChD,CAAC;IAED,IAAI,mBAAmB,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;IAC3F,OAAO;QACL,IAAI;QACJ,UAAU;QACV,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,mBAAmB,EAAE,OAAO,EAAE;KACrE,CAAA;AACH,CAAC"}

package/dist/executor.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutionPlan, ExecutionResult } from './model.js';
+export declare function executePlan(plan: ExecutionPlan, options?: {
+    readonly allowSkip?: boolean;
+}): Promise<ExecutionResult>;

package/dist/executor.js

@@ -0,0 +1,45 @@
+import { runRunnerTargets } from './runner-client.js';
+function aggregate(statuses) {
+    if (statuses.includes('ERROR'))
+        return 'ERROR';
+    if (statuses.includes('FAIL'))
+        return 'FAIL';
+    if (statuses.includes('SKIP'))
+        return 'SKIP';
+    return 'PASS';
+}
+export async function executePlan(plan, options = {}) {
+    const resultByKey = new Map();
+    for (const group of plan.groups) {
+        try {
+            const output = await runRunnerTargets(plan.projectRoot, group.runnerId, group.config, group.targets.map(target => target.target));
+            const outputById = new Map(output.results.map(result => [result.targetId, result]));
+            for (const target of group.targets) {
+                const result = outputById.get(target.target.targetId);
+                if (result === undefined) {
+                    resultByKey.set(target.key, { status: 'ERROR', diagnostic: 'runner omitted the target result' });
+                    continue;
+                }
+                resultByKey.set(target.key, {
+                    status: result.status === 'pass' ? 'PASS' : result.status === 'fail' ? 'FAIL' : 'SKIP',
+                    ...(result.diagnostic === undefined ? {} : { diagnostic: result.diagnostic }),
+                });
+            }
+        }
+        catch (error) {
+            const diagnostic = error instanceof Error ? error.message : String(error);
+            for (const target of group.targets)
+                resultByKey.set(target.key, { status: 'ERROR', diagnostic });
+        }
+    }
+    const scenarios = plan.scenarios.map(scenario => {
+        const evidence = scenario.evidence.map(item => {
+            const result = resultByKey.get(item.key) ?? { status: 'ERROR', diagnostic: 'execution plan lost the evidence result' };
+            return { reference: item.reference, ...result };
+        });
+        return { id: scenario.id, status: aggregate(evidence.map(item => item.status)), evidence };
+    });
+    const success = scenarios.every(scenario => scenario.status === 'PASS' || (options.allowSkip === true && scenario.status === 'SKIP'));
+    return { success, scenarios, targetCount: plan.targets.length };
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { loadConfig } from './config.js';
+export { executePlan } from './executor.js';
+export { parseEvidenceReference, parseFocusedSpecDocument } from './parser.js';
+export { planEvidence } from './planner.js';
+export type { ExecutionPlan, ExecutionResult, FocusedSpecConfig, Scenario, SpecDocument, Violation, } from './model.js';
+export type { ResolveRequest, ResolveResponse, ResolvedTarget, RunnerPlugin, RunRequest, RunResponse, TargetResult, } from './runner-api.js';
+export { validateDocuments, validateFocusedSpecs } from './validate.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { loadConfig } from './config.js';
+export { executePlan } from './executor.js';
+export { parseEvidenceReference, parseFocusedSpecDocument } from './parser.js';
+export { planEvidence } from './planner.js';
+export { validateDocuments, validateFocusedSpecs } from './validate.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAkB3C,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA"}

package/dist/model.d.ts

@@ -0,0 +1,94 @@
+import type { JsonValue, ResolvedTarget, TargetResult } from './runner-api.js';
+export type SpecOperation = 'CURRENT' | 'ADDED' | 'MODIFIED' | 'REMOVED' | 'RENAMED';
+export interface Scenario {
+    readonly path: string;
+    readonly line: number;
+    readonly name: string;
+    readonly requirement?: string;
+    readonly operation: SpecOperation;
+    readonly ids: readonly string[];
+    readonly evidence: readonly string[];
+    readonly whenCount: number;
+    readonly thenCount: number;
+}
+export interface SpecDocument {
+    readonly path: string;
+    readonly scenarios: readonly Scenario[];
+    readonly malformedScenarioHeadings: readonly number[];
+}
+export interface Violation {
+    readonly path: string;
+    readonly line?: number;
+    readonly scenarioId?: string;
+    readonly message: string;
+}
+export interface RunnerConfig {
+    readonly module: string;
+    readonly cwd?: string;
+    readonly timeoutMs?: number;
+    readonly options?: JsonValue;
+}
+export interface OpenSpecSourceConfig {
+    readonly source: 'openspec';
+    readonly root?: string;
+}
+export interface FileSourceConfig {
+    readonly source: 'files';
+    readonly paths: readonly string[];
+}
+export interface FocusedSpecConfig {
+    readonly version: 1;
+    readonly specifications: OpenSpecSourceConfig | FileSourceConfig;
+    readonly runners: Readonly<Record<string, RunnerConfig>>;
+}
+export interface EvidenceReference {
+    readonly raw: string;
+    readonly planned: boolean;
+    readonly runnerId: string;
+    readonly selector: string;
+}
+export interface PlannedTarget {
+    readonly key: string;
+    readonly runnerId: string;
+    readonly config: RunnerConfig;
+    readonly target: ResolvedTarget;
+    readonly references: readonly string[];
+}
+export interface PlannedEvidence {
+    readonly key: string;
+    readonly reference: string;
+}
+export interface PlannedScenario {
+    readonly id: string;
+    readonly evidence: readonly PlannedEvidence[];
+}
+export interface RunnerGroup {
+    readonly runnerId: string;
+    readonly config: RunnerConfig;
+    readonly targets: readonly PlannedTarget[];
+}
+export interface ExecutionPlan {
+    readonly projectRoot: string;
+    readonly scenarios: readonly PlannedScenario[];
+    readonly targets: readonly PlannedTarget[];
+    readonly groups: readonly RunnerGroup[];
+}
+export type EvidenceStatus = 'PASS' | 'FAIL' | 'SKIP' | 'ERROR';
+export interface EvidenceResult {
+    readonly reference: string;
+    readonly status: EvidenceStatus;
+    readonly diagnostic?: string;
+}
+export interface ScenarioResult {
+    readonly id: string;
+    readonly status: EvidenceStatus;
+    readonly evidence: readonly EvidenceResult[];
+}
+export interface ExecutionResult {
+    readonly success: boolean;
+    readonly scenarios: readonly ScenarioResult[];
+    readonly targetCount: number;
+}
+export interface RunnerRunOutput {
+    readonly results: readonly TargetResult[];
+}

package/dist/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":""}

package/dist/parser.d.ts

@@ -0,0 +1,6 @@
+import type { EvidenceReference, SpecDocument } from './model.js';
+export declare const STABLE_ID: RegExp;
+export declare function parseFocusedSpecDocument(path: string, source: string): SpecDocument;
+export declare function parseEvidenceReference(raw: string): EvidenceReference | {
+    readonly error: string;
+};