vigiles 2.1.1 → 2.3.0

package/dist/spec.d.ts

@@ -135,7 +135,13 @@ export interface SkillRef {
     readonly _ref: "skill";
     readonly path: VerifiedRef;
 }
-export type Ref = FileRef | CmdRef | SkillRef;
+/** A typed symbol reference — the named file must define the named symbol. */
+export interface SymbolRef {
+    readonly _ref: "symbol";
+    readonly file: VerifiedPath;
+    readonly symbol: string;
+}
+export type Ref = FileRef | CmdRef | SkillRef | SymbolRef;
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -146,6 +152,13 @@ export declare function file(path: NoInfer<StrictFile>): FileRef;
  * When generated types are present, narrowed to known npm scripts.
  */
 export declare function cmd(command: NoInfer<StrictCmd>): CmdRef;
+/**
+ * Reference a symbol defined in a file — verified at compile time that the
+ * named file exists AND defines the named symbol (via ast-grep, cross-language).
+ * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
+ * `audit` / `refs-hook` re-verify the same reference.
+ */
+export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolRef;
 /**
  * Reference another skill or instruction file — verified to exist.
  * Compiles to a markdown link: [skill name](path)
@@ -214,18 +227,91 @@ type ClaudeSpecInput = ClaudeSpecBase & ClaudeSpecSections;
  *   export default claude({ commands: {...}, rules: {...} });
  */
 export declare function claude(spec: ClaudeSpecInput): ClaudeSpec;
+/**
+ * A deterministic gate on a skill step or its final result. A gate is one of:
+ * a command (exit 0), a file (must exist), or a *project role* that resolves to
+ * the host project's real command at run time. cmd/file gates are verified
+ * against the repo at author time; role gates are portable — a skill that runs
+ * in other repos should prefer `project("test")` over a hard-coded `npm test`.
+ */
+export type Gate = CmdRef | FileRef | RoleGate;
+/** Project command roles, resolved per host project at run time. */
+export type ProjectRole = "test" | "build" | "lint";
+/** A portable gate that resolves to the host project's command for a role. */
+export interface RoleGate {
+    readonly _ref: "role";
+    readonly role: ProjectRole;
+}
+/**
+ * A portable gate that resolves to the host project's command for a role
+ * (e.g. `project("test")` → `npm test` / `pytest` / `cargo test`). Use this
+ * in skills meant to run across projects, instead of hard-coding a command.
+ */
+export declare function project(role: ProjectRole): RoleGate;
+/**
+ * A declared skill input. Compiles to the `argument-hint` frontmatter and a
+ * `## Arguments` section; referenced as `$1`/`$2`/`$ARGUMENTS` in the body.
+ */
+export interface SkillInput {
+    /** Argument name, e.g. "pattern". */
+    readonly name: string;
+    /** Human-readable hint shown in argument-hint and the Arguments section. */
+    readonly hint: string;
+    /** Required by default; set false to render as optional (`[<name>]`). */
+    readonly required?: boolean;
+}
+/** One step of a gated skill pipeline. */
+export interface SkillStep {
+    /** What the model should do — prose, optionally with typed refs. */
+    readonly do: string | InstructionFragment[];
+    /** Deterministic check that must pass before advancing to the next step. */
+    readonly gate?: Gate;
+    /** Max attempts to satisfy the gate before the step fails (default 1). */
+    readonly retry?: number;
+}
+/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
+export declare function input(name: string, hint: string, opts?: {
+    required?: boolean;
+}): SkillInput;
+/** Declare a gated pipeline step. */
+export declare function step(instr: string | InstructionFragment[], opts?: {
+    gate?: Gate;
+    retry?: number;
+}): SkillStep;
 export interface SkillSpec {
     readonly _specType: "skill";
     /** Skill name (used in frontmatter). */
     readonly name: string;
     /** Short description (used in frontmatter). */
     readonly description: string;
-    /** Hint for the argument (used in frontmatter). */
+    /**
+     * Hint for the argument (frontmatter). Ignored when `inputs` is set —
+     * `inputs` derive the argument-hint instead.
+     */
     readonly argumentHint?: string;
+    /** Typed inputs — compile to argument-hint + a `## Arguments` section. */
+    readonly inputs?: readonly SkillInput[];
     /** Whether to disable model invocation (frontmatter flag). */
     readonly disableModelInvocation?: boolean;
-    /** Instruction body — string or tagged template with typed refs. */
-    readonly body: string | InstructionFragment[];
+    /**
+     * Gated pipeline steps. When set, the skill compiles to a `## Steps`
+     * checklist with a deterministic gate per step. Use this OR `body`.
+     */
+    readonly steps?: readonly SkillStep[];
+    /**
+     * Terminal postcondition — the skill is "done" only when this gate passes.
+     * Compiles to a `## Result` section + a `vigiles:result` marker.
+     */
+    readonly result?: Gate;
+    /** Freeform instruction body (linear/unstructured skills). Use this OR `steps`. */
+    readonly body?: string | InstructionFragment[];
+    /**
+     * Max lines for an inline fenced code block before compilation errors,
+     * forcing the script into a file referenced via `file()` (default 20).
+     * Keeps big scripts out of the skill body (token budget + progressive
+     * disclosure). Set 0 to disable.
+     */
+    readonly maxInlineCodeLines?: number;
 }
 /**
  * Define a SKILL.md specification.

package/dist/spec.js

@@ -15,9 +15,13 @@ exports.guidance = guidance;
 exports.guard = guard;
 exports.file = file;
 exports.cmd = cmd;
+exports.symbol = symbol;
 exports.ref = ref;
 exports.instructions = instructions;
 exports.claude = claude;
+exports.project = project;
+exports.input = input;
+exports.step = step;
 exports.skill = skill;
 exports.defineConfig = defineConfig;
 // ---------------------------------------------------------------------------
@@ -81,6 +85,15 @@ function file(path) {
 function cmd(command) {
     return { _ref: "cmd", command: command };
 }
+/**
+ * Reference a symbol defined in a file — verified at compile time that the
+ * named file exists AND defines the named symbol (via ast-grep, cross-language).
+ * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
+ * `audit` / `refs-hook` re-verify the same reference.
+ */
+function symbol(file, name) {
+    return { _ref: "symbol", file: file, symbol: name };
+}
 /**
  * Reference another skill or instruction file — verified to exist.
  * Compiles to a markdown link: [skill name](path)
@@ -116,6 +129,22 @@ function instructions(strings, ...values) {
 function claude(spec) {
     return { _specType: "claude", ...spec };
 }
+/**
+ * A portable gate that resolves to the host project's command for a role
+ * (e.g. `project("test")` → `npm test` / `pytest` / `cargo test`). Use this
+ * in skills meant to run across projects, instead of hard-coding a command.
+ */
+function project(role) {
+    return { _ref: "role", role };
+}
+/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
+function input(name, hint, opts = {}) {
+    return { name, hint, required: opts.required };
+}
+/** Declare a gated pipeline step. */
+function step(instr, opts = {}) {
+    return { do: instr, gate: opts.gate, retry: opts.retry };
+}
 /**
  * Define a SKILL.md specification.
  *

package/dist/symbols.d.ts

@@ -0,0 +1,30 @@
+import { Lang } from "@ast-grep/napi";
+/** A language key accepted by ast-grep's `parse` (core enum or registered id). */
+type LangKey = Lang | string;
+/** The ast-grep language for a file, or null if unsupported (graceful skip). */
+export declare function langForFile(file: string): LangKey | null;
+/** A symbol definition found in a file. */
+export interface SymbolDef {
+    /** The defined identifier, e.g. "parseConfig". */
+    readonly name: string;
+    /** The tree-sitter node kind, e.g. "function_declaration" (raw, per-grammar). */
+    readonly kind: string;
+    /** Enclosing class/module name, or "" at top level. */
+    readonly scope: string;
+    /** 1-based line of the definition. */
+    readonly line: number;
+}
+/** Extract the symbols defined in a single file's source. */
+export declare function definedSymbols(code: string, lang: LangKey): SymbolDef[];
+/** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
+export declare function definedSymbolsInFile(file: string): SymbolDef[];
+/**
+ * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
+ * the whole check for a file-qualified reference (`path#symbol`): we parse the
+ * one named file — no project-wide index, no resolution across files. As a
+ * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
+ * typed dynamic symbols resolve without running Sorbet / the TS compiler.
+ */
+export declare function fileDefinesSymbol(file: string, name: string): boolean;
+export {};
+//# sourceMappingURL=symbols.d.ts.map

package/dist/symbols.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.langForFile = langForFile;
+exports.definedSymbols = definedSymbols;
+exports.definedSymbolsInFile = definedSymbolsInFile;
+exports.fileDefinesSymbol = fileDefinesSymbol;
+/**
+ * vigiles — cross-language symbol index (ast-grep / tree-sitter).
+ *
+ * The kernel of harness-pinned reference verification. Instruction files
+ * reference project symbols in prose (`parseConfig`, `User`, `create_docx.py`);
+ * authors never write a verifiable `file#symbol` form (corpus: ~0%). So instead
+ * of asking authors to annotate, the *harness* resolves a bare reference against
+ * the live code at write time and pins it. This module is the resolver: extract
+ * the symbols a file defines, and build a project-wide name → locations index.
+ *
+ * Boundary (see research/symbol-verification.md): we answer "does a definition
+ * with this name (in this scope) exist", NOT "does this reference resolve through
+ * imports / Zeitwerk / tsconfig". Resolution is per-language and architectural —
+ * delegated. Ambiguity (a name defined in several files) is reported, not guessed.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const napi_1 = require("@ast-grep/napi");
+const lang_python_1 = __importDefault(require("@ast-grep/lang-python"));
+const lang_rust_1 = __importDefault(require("@ast-grep/lang-rust"));
+const lang_ruby_1 = __importDefault(require("@ast-grep/lang-ruby"));
+let registered = false;
+function ensureRegistered() {
+    if (registered)
+        return;
+    // Non-web grammars ship as separate packages registered at runtime.
+    (0, napi_1.registerDynamicLanguage)({ python: lang_python_1.default, rust: lang_rust_1.default, ruby: lang_ruby_1.default });
+    registered = true;
+}
+const EXT_LANG = {
+    ".ts": napi_1.Lang.TypeScript,
+    ".tsx": napi_1.Lang.Tsx,
+    ".mts": napi_1.Lang.TypeScript,
+    ".cts": napi_1.Lang.TypeScript,
+    ".d.ts": napi_1.Lang.TypeScript,
+    ".js": napi_1.Lang.JavaScript,
+    ".jsx": napi_1.Lang.JavaScript,
+    ".mjs": napi_1.Lang.JavaScript,
+    ".cjs": napi_1.Lang.JavaScript,
+    ".css": napi_1.Lang.Css,
+    ".py": "python",
+    ".pyi": "python",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".rbi": "ruby",
+};
+/** The ast-grep language for a file, or null if unsupported (graceful skip). */
+function langForFile(file) {
+    if (file.endsWith(".d.ts"))
+        return napi_1.Lang.TypeScript;
+    return EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()] ?? null;
+}
+const ID_KINDS = new Set(["identifier", "constant", "type_identifier"]);
+const SCOPE_KINDS = new Set([
+    "class_declaration",
+    "class_definition",
+    "class",
+    "module",
+    "interface_declaration",
+    "enum_declaration",
+]);
+function recordNode(node, scope, out) {
+    const line = node.range().start.line + 1;
+    const nameNode = node.field("name");
+    if (nameNode) {
+        out.push({ name: nameNode.text(), kind: node.kind(), scope, line });
+    }
+    // Assignment-style constants (Python/Ruby `X = ...`): the identifier is the
+    // `left` field, not `name`.
+    const left = node.field("left");
+    if (left && ID_KINDS.has(left.kind())) {
+        out.push({ name: left.text(), kind: node.kind(), scope, line });
+    }
+}
+/** Extract the symbols defined in a single file's source. */
+function definedSymbols(code, lang) {
+    ensureRegistered();
+    const out = [];
+    const walk = (node, scope) => {
+        recordNode(node, scope, out);
+        const nameNode = node.field("name");
+        const nextScope = SCOPE_KINDS.has(node.kind()) && nameNode ? nameNode.text() : scope;
+        for (const child of node.children())
+            walk(child, nextScope);
+    };
+    walk((0, napi_1.parse)(lang, code).root(), "");
+    return out;
+}
+/** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
+function definedSymbolsInFile(file) {
+    const lang = langForFile(file);
+    if (!lang)
+        return [];
+    try {
+        return definedSymbols((0, node_fs_1.readFileSync)(file, "utf-8"), lang);
+    }
+    catch {
+        return [];
+    }
+}
+// A co-located declaration file that may declare symbols the source defines
+// dynamically (Sorbet `.rbi`, TypeScript `.d.ts`) — checked as a fallback so a
+// metaprogrammed `define_method` / ambient declaration still resolves.
+const DECL_SIBLING = {
+    ".ts": ".d.ts",
+    ".tsx": ".d.ts",
+    ".js": ".d.ts",
+    ".jsx": ".d.ts",
+    ".mjs": ".d.ts",
+    ".rb": ".rbi",
+};
+/**
+ * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
+ * the whole check for a file-qualified reference (`path#symbol`): we parse the
+ * one named file — no project-wide index, no resolution across files. As a
+ * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
+ * typed dynamic symbols resolve without running Sorbet / the TS compiler.
+ */
+function fileDefinesSymbol(file, name) {
+    if (definedSymbolsInFile(file).some((d) => d.name === name))
+        return true;
+    const ext = (0, node_path_1.extname)(file);
+    const decl = DECL_SIBLING[ext];
+    if (decl && !file.endsWith(decl)) {
+        const sibling = file.slice(0, -ext.length) + decl;
+        if ((0, node_fs_1.existsSync)(sibling) &&
+            definedSymbolsInFile(sibling).some((d) => d.name === name)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=symbols.js.map

package/dist/vitest.d.mts

@@ -0,0 +1,9 @@
+declare module "@vitest/expect" {
+    interface Matchers<T = any> {
+        toHaveCreated(path: string): T;
+        toBlock(): T;
+        toBeatBaseline(baseline: string, arm: string, metric: string, by?: number): T;
+    }
+}
+export {};
+//# sourceMappingURL=vitest.d.mts.map

package/dist/vitest.mjs

@@ -0,0 +1,22 @@
+/* eslint-disable max-params, @typescript-eslint/no-explicit-any --
+   The matcher signatures mirror the runtime vigilesMatchers (positional args),
+   and `Matchers<T = any>` must match @vitest/expect's generic default to merge. */
+/**
+ * vigiles — vitest integration (opt-in). ESM, because vitest is ESM-only.
+ *
+ * Importing this entry registers the vigiles matchers AND augments vitest's
+ * types so `toHaveCreated` / `toBeatBaseline` type-check.
+ *
+ *   // vitest.config.ts →  test: { setupFiles: ["vigiles/vitest"] }
+ *   // …or at the top of a test file:
+ *   import "vigiles/vitest";
+ *
+ *   expect(result).toHaveCreated("DONE");
+ *   expect(report).toBeatBaseline("vanilla", "gated", "caught");
+ *
+ * vitest is an optional peer dependency — only vitest users load this entry.
+ */
+import { expect } from "vitest";
+import { vigilesMatchers } from "./harness-assert.js";
+expect.extend(vigilesMatchers);
+//# sourceMappingURL=vitest.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
@@ -11,11 +11,25 @@
     ".": "./dist/spec.js",
     "./spec": "./dist/spec.js",
     "./compile": "./dist/compile.js",
-    "./linters": "./dist/linters.js"
+    "./linters": "./dist/linters.js",
+    "./eval": "./dist/eval.js",
+    "./harness-test": "./dist/harness-test.js",
+    "./harness-assert": "./dist/harness-assert.js",
+    "./run-hook": "./dist/run-hook.js",
+    "./plugin-loader": "./dist/plugin-loader.js",
+    "./judge": "./dist/judge.js",
+    "./mock-model": "./dist/mock-model.js",
+    "./vitest": {
+      "types": "./dist/vitest.d.mts",
+      "default": "./dist/vitest.mjs"
+    },
+    "./jest": "./dist/jest.js"
   },
   "files": [
     "dist/**/*.js",
+    "dist/**/*.mjs",
     "dist/**/*.d.ts",
+    "dist/**/*.d.mts",
     "!dist/**/*.test.js",
     "!dist/**/*.test.d.ts",
     "action.yml",
@@ -25,10 +39,16 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js dist/sidecar.test.js dist/coverage.test.js dist/session.test.js dist/orphans.test.js dist/cedar.test.js dist/doc-refs.test.js dist/frontmatter.test.js",
+    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js dist/sidecar.test.js dist/coverage.test.js dist/session.test.js dist/orphans.test.js dist/cedar.test.js dist/doc-refs.test.js dist/frontmatter.test.js dist/skill-pipeline.test.js dist/skill-runtime.test.js dist/skill-driver.test.js dist/skill-test.test.js dist/compile-generator.test.js dist/community-skills.test.js dist/action-gate.test.js dist/symbols.test.js dist/refs.test.js dist/harness-test.test.js dist/eval.test.js dist/run-scripts.test.js dist/plugin-loader.test.js dist/harness-assert.test.js dist/judge.test.js dist/run-hook.test.js",
     "lint": "eslint src/",
     "fmt": "prettier --write .",
-    "fmt:check": "prettier --check ."
+    "fmt:check": "prettier --check .",
+    "test:e2e": "bash test/e2e/run.sh",
+    "test:harness": "npm run build && node dist/cli.js test",
+    "test:eval": "npm run build && node dist/cli.js eval",
+    "test:vitest": "npm run build && vitest run",
+    "test:jest": "npm run build && jest",
+    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -40,15 +60,34 @@
     "eslint": "^10.1.0",
     "eslint-plugin-sonarjs": "^4.0.2",
     "globals": "^17.4.0",
+    "jest": "^30.4.2",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "jest": ">=28",
+    "vitest": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "dependencies": {
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/lang-ruby": "^0.0.7",
+    "@ast-grep/lang-rust": "^0.0.7",
+    "@ast-grep/napi": "^0.43.0",
     "@jackchuka/mdschema": "^0.12.8",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",
     "js-yaml": "^4.1.0",
-    "minimatch": "^10.0.1"
+    "minimatch": "^10.0.1",
+    "typescript": "^5.9.3"
   }
 }