focused-spec 0.1.0

package/dist/validate.js

@@ -0,0 +1,107 @@
+import { parseEvidenceReference, STABLE_ID } from './parser.js';
+import { loadActiveChanges, loadChangeDocuments, loadCurrentDocuments, validateSourceSelection } from './sources.js';
+function diagnostic(scenario, message) {
+    return {
+        path: scenario.path,
+        line: scenario.line,
+        ...(scenario.ids[0] === undefined ? {} : { scenarioId: scenario.ids[0] }),
+        message,
+    };
+}
+export function validateDocuments(documents, config, options) {
+    const violations = [];
+    const identifiers = new Map();
+    for (const document of documents) {
+        for (const line of document.malformedScenarioHeadings) {
+            violations.push({ path: document.path, line, message: 'scenario headings must use exactly four hashes' });
+        }
+        for (const scenario of document.scenarios) {
+            if (scenario.ids.length !== 1) {
+                violations.push(diagnostic(scenario, `expected exactly one ID row, found ${scenario.ids.length}`));
+            }
+            else {
+                const id = scenario.ids[0];
+                if (!STABLE_ID.test(id))
+                    violations.push(diagnostic(scenario, `invalid stable ID ${id}`));
+                const previous = identifiers.get(id);
+                if (previous === undefined)
+                    identifiers.set(id, scenario);
+                else
+                    violations.push(diagnostic(scenario, `duplicate stable ID; first owned by ${previous.path}:${previous.line}`));
+            }
+            if (scenario.evidence.length === 0)
+                violations.push(diagnostic(scenario, 'expected at least one EVIDENCE row'));
+            if (scenario.whenCount !== 1)
+                violations.push(diagnostic(scenario, `expected exactly one WHEN row, found ${scenario.whenCount}`));
+            if (scenario.thenCount !== 1)
+                violations.push(diagnostic(scenario, `expected exactly one THEN row, found ${scenario.thenCount}`));
+            for (const raw of scenario.evidence) {
+                const reference = parseEvidenceReference(raw);
+                if ('error' in reference) {
+                    violations.push(diagnostic(scenario, `invalid evidence ${raw}: ${reference.error}`));
+                    continue;
+                }
+                if (reference.planned && !options.allowPlanned) {
+                    violations.push(diagnostic(scenario, `planned evidence is not allowed here: ${raw}; use non-strict validate --change <name> while planning, then replace planned evidence before strict validation or run`));
+                }
+                if (config.runners[reference.runnerId] === undefined) {
+                    violations.push(diagnostic(scenario, `unknown evidence runner ${reference.runnerId}`));
+                }
+            }
+        }
+    }
+    return { violations, identifiers };
+}
+function collisionViolations(current, documents) {
+    const violations = [];
+    for (const document of documents) {
+        for (const scenario of document.scenarios) {
+            const id = scenario.ids[0];
+            const owner = id === undefined ? undefined : current.get(id);
+            if (owner === undefined || scenario.operation === 'MODIFIED' || scenario.operation === 'REMOVED')
+                continue;
+            violations.push(diagnostic(scenario, `stable ID already belongs to current scenario ${owner.path}:${owner.line}`));
+        }
+    }
+    return violations;
+}
+export async function validateFocusedSpecs(projectRoot, config, options = {}) {
+    const violations = validateSourceSelection(config, options.changeName);
+    const currentDocuments = await loadCurrentDocuments(projectRoot, config);
+    const current = validateDocuments(currentDocuments, config, { allowPlanned: false });
+    violations.push(...current.violations);
+    if (options.changeName !== undefined) {
+        const changeDocuments = await loadChangeDocuments(projectRoot, config, options.changeName);
+        if (changeDocuments.length === 0) {
+            violations.push({ path: options.changeName, message: `OpenSpec change has no delta specifications: ${options.changeName}` });
+        }
+        const active = validateDocuments(changeDocuments, config, { allowPlanned: !options.strict });
+        violations.push(...active.violations, ...collisionViolations(current.identifiers, changeDocuments));
+        return {
+            violations: deduplicate(violations),
+            targetDocuments: changeDocuments,
+            resolutionDocuments: [...currentDocuments, ...changeDocuments],
+        };
+    }
+    const resolutionDocuments = [...currentDocuments];
+    if (config.specifications.source === 'openspec') {
+        for (const documents of (await loadActiveChanges(projectRoot, config)).values()) {
+            const active = validateDocuments(documents, config, { allowPlanned: true });
+            violations.push(...active.violations, ...collisionViolations(current.identifiers, documents));
+            resolutionDocuments.push(...documents);
+        }
+    }
+    return { violations: deduplicate(violations), targetDocuments: currentDocuments, resolutionDocuments };
+}
+function deduplicate(violations) {
+    const byKey = new Map();
+    for (const violation of violations) {
+        const key = `${violation.path}:${violation.line ?? ''}:${violation.scenarioId ?? ''}:${violation.message}`;
+        byKey.set(key, violation);
+    }
+    return [...byKey.values()].sort((left, right) => {
+        const path = left.path.localeCompare(right.path);
+        return path !== 0 ? path : (left.line ?? 0) - (right.line ?? 0);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="${FOCUSED_SPEC_PACKAGE:-focused-spec}"
+NPM_BIN="${NPM_BIN:-npm}"
+
+if ! command -v node >/dev/null 2>&1; then
+  printf '%s\n' 'focused-spec requires Node.js 24 or newer; node was not found.' >&2
+  exit 1
+fi
+
+node_major="$(node -p 'Number(process.versions.node.split(".")[0])')"
+if [[ "$node_major" -lt 24 ]]; then
+  printf 'focused-spec requires Node.js 24 or newer; found %s.\n' "$(node --version)" >&2
+  exit 1
+fi
+
+if ! command -v "$NPM_BIN" >/dev/null 2>&1; then
+  printf 'npm executable not found: %s\n' "$NPM_BIN" >&2
+  exit 1
+fi
+
+printf 'Installing %s as a development dependency...\n' "$PACKAGE_NAME"
+"$NPM_BIN" install --save-dev "$PACKAGE_NAME"
+
+
+printf '%s\n' 'focused-spec CLI installation complete.'

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "focused-spec",
+  "version": "0.1.0",
+  "description": "Executable evidence for focused behavioral specifications",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bamanoz/focused-spec.git"
+  },
+  "type": "module",
+  "bin": {
+    "focused-spec": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./runner": "./dist/runner-api.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "install.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "typecheck:tests": "tsc -p test/tsconfig.json && tsc -p examples/polyglot/tsconfig.json && tsc -p evals/tsconfig.json",
+    "test": "npm run build && npm run typecheck:tests && vitest run",
+    "check": "npm test",
+    "smoke": "node dist/cli.js run --root examples/polyglot",
+    "eval:agent": "node --experimental-strip-types evals/run.ts"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
+  },
+  "license": "MIT"
+}

package/skills/focused-spec/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: focused-spec
+description: MUST be used alongside any workflow that creates or changes behavioral specifications or scenarios, even when another skill owns that workflow. Enforces focused scenario IDs, executable evidence, on-demand configuration, and project-local runners.
+---
+
+# Focused Spec
+
+Any behavioral specification authored in a project is a focused specification. Keep the surrounding framework's document structure, but write every behavioral scenario in the format below.
+
+## Author a scenario
+
+1. Find the single capability that owns the behavior; do not create a parallel formulation.
+2. Protect the smallest product-boundary outcome that can fail independently.
+3. Give the scenario one repository-unique lowercase dotted `ID` and preserve it when ownership moves.
+4. Determine the execution environment, runner ID, and opaque selector shape before writing evidence.
+5. Add one or more `EVIDENCE` rows. Multiple rows form an AND contract.
+6. Write exactly one `WHEN` request and one independently failing `THEN` outcome.
+
+```markdown
+#### Scenario: Blocked account submits valid credentials
+- **ID**: `auth.login.blocked-account`
+- **EVIDENCE**: `go-unit::./internal/auth::TestBlockedAccount`
+- **EVIDENCE**: `pytest-functional::tests/test_auth.py::test_blocked_account`
+- **WHEN** a blocked account submits otherwise valid credentials
+- **THEN** authentication is rejected
+```
+
+Evidence is `[planned:]<runner-id>::<opaque selector>`. Only the first `::` separates the runner ID. Use `planned:` only while that exact test target does not exist; the runner ID, module path, and selector contract must already be chosen. Remove every `planned:` before completing implementation.
+
+## Configure on demand
+
+Create or update `.focused-spec/config.yaml` as soon as the first scenario names evidence. Keep runner modules in `.focused-spec/runners/`. Do not create root-level `focused-spec.yaml`.
+
+For Markdown files selected by glob:
+
+```yaml
+version: 1
+specifications:
+  source: files
+  paths: [specs/**/*.md]
+runners:
+  project-tests:
+    module: ./.focused-spec/runners/project-tests.ts
+    timeoutMs: 120000
+```
+
+For a framework-managed source supported by the CLI, select it instead; for example:
+
+```yaml
+specifications:
+  source: openspec
+  root: openspec # optional; defaults to openspec
+```
+
+`runners` is a map keyed by runner ID. Each entry requires `module`; optional fields are project-relative `cwd`, positive integer `timeoutMs`, and JSON-compatible `options`. `module` must be a project-contained `.ts`, `.mts`, `.js`, or `.mjs` file. Every runner ID referenced by evidence must be registered. For another specification framework, use `source: files` with paths targeting its Markdown scenario files unless the CLI supports a dedicated source.
+
+## Implement a runner
+
+Import types only from `focused-spec/runner`. A default-exported `RunnerPlugin` has `apiVersion: 1`, `resolve(request)`, and `run(request)`.
+
+- `resolve` receives `selectors`, `projectRoot`, resolved `cwd`, `runnerId`, JSON-compatible `options`, and abort `signal`.
+- For every selector, `resolve` returns exactly one target `{ selector, targetId, displayName, source?, data? }` or one error `{ selector, message }`.
+- Prove target existence through the real framework's collection/listing mechanism. Preserve the selector exactly and use deterministic target IDs.
+- `run` receives resolved `targets` plus the same context and returns exactly one `{ targetId, status, diagnostic? }` per target.
+- Status is `pass`, `fail`, or `skip`. Never return `pass` without executing and interpreting the selected test.
+- Spawn tools with executable/argument arrays, `shell: false`, supplied `cwd`, and supplied `signal`. Keep diagnostics bounded.
+
+The public shape is:
+
+```ts
+interface RunnerPlugin {
+  readonly apiVersion: 1
+  resolve(request: ResolveRequest): Promise<{ targets: ResolvedTarget[]; errors: ResolveError[] }>
+  run(request: RunRequest): Promise<{ results: TargetResult[] }>
+}
+```
+
+## Verify
+
+While a named change still contains `planned:` evidence, validate its structure with `focused-spec validate --change <name> --syntax-only` and its configuration with `focused-spec validate --change <name>` (without `--strict`). Planned targets are not resolved or executed; a successful planning check does not prove them.
+
+Only after implementing the tests and runner, replace all `planned:` references with concrete selectors. Then verify the completed change:
+
+```sh
+focused-spec validate --change <name> --strict
+focused-spec run --change <name>
+```
+
+For current specifications (no change):
+
+```sh
+focused-spec validate
+focused-spec run
+```
+
+Do not run `--strict` or `run` against a change that intentionally still contains `planned:`; their failure is expected, not a proposal defect. Full validation resolves non-planned evidence; `run` performs strict validation and executes it. `SKIP` and `ERROR` are not success. Use `--allow-skip` only when explicit project policy permits unavailable optional evidence.