vigiles 38.2.0 → 39.0.0

package/dist/core/bash-effects.d.ts

@@ -225,61 +225,4 @@ export declare function leafCommandsNormalized(command: string): NormalizedLeaf[
  * Parse failure → `[]`.
  */
 export declare function leafArgvSource(command: string): string[][];
-/**
- * Every word of every simple command in `command` that could name a FILE, with
- * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
- * exist?".
- *
- * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
- * because "there is already one that returns words" is exactly the reasoning
- * that produced the bug this replaces.
- *
- *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
- *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
- *    disappears entirely. Unusable for a file question.
- *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
- *    `x.sh` and no resolver can find it.
- *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
- *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
- *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
- *    coverage attribution that abstention is correct; for "must this file
- *    exist?" it is a miss, because a conditionally-run script still has to be
- *    on disk.
- *
- * So this walks EVERY simple command, keeps every word at source level, and
- * subtracts only the words that are provably not paths.
- *
- * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
- * to run a regex over the raw command STRING. Against the standard portable
- * plugin idiom —
- *
- *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
- *
- * — it grabbed a character run ending at `.mjs` and reported the hook's script
- * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
- * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
- * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
- * parse the argument of `-e` is not a word the shell will ever resolve to a
- * file, so it is not returned.
- *
- * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
- * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
- * and re-auditing all three affected repos still yields ZERO false hook-script
- * findings, because both real payloads are single words that either contain
- * whitespace or do not end in a script extension, and the caller anchors its
- * match to a whole word. The table is kept because it is the difference
- * between a function whose contract ("words that could name a file") is true
- * and one whose contract is merely true-so-far: without it a JavaScript
- * program is handed to every caller as a candidate filename, and the next
- * caller inherits the bug. Recorded here so nobody reads a corpus number back
- * onto the wrong mechanism.
- *
- * Words beginning with `-` are dropped as flags: a flag is not a path, and the
- * one caller anchors its match to a whole word anyway.
- *
- * Returns `null` — not `[]` — when the text does not parse as shell, so a
- * caller can tell "no file operands" from "no analysis", and cannot silently
- * treat the second as the first.
- */
-export declare function commandWords(command: string): string[] | null;
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -31,7 +31,6 @@ exports.leafCommands = leafCommands;
 exports.stripWrappers = stripWrappers;
 exports.leafCommandsNormalized = leafCommandsNormalized;
 exports.leafArgvSource = leafArgvSource;
-exports.commandWords = commandWords;
 /**
  * The parser is loaded ON FIRST PARSE, not at module load — `sh()` memoizes it.
  *
@@ -1164,150 +1163,4 @@ function normalizeCallExpr(node, redirs) {
         chdir: stripped.chdir,
     };
 }
-// ===========================================================================
-// FILE-OPERAND extraction (the reference question, not the effect question)
-// ===========================================================================
-/**
- * Interpreters, and the flags after which the NEXT word is a PROGRAM rather
- * than a path. `node -e "<js>"`, `python -c "<py>"`, `perl -E "<pl>"`.
- *
- * Keyed by the head's basename, so `/usr/local/bin/node` and `node` behave the
- * same.
- */
-const INLINE_PROGRAM_FLAGS = new Map([
-    ["node", ["-e", "--eval", "-p", "--print"]],
-    ["nodejs", ["-e", "--eval", "-p", "--print"]],
-    ["bun", ["-e", "--eval", "-p", "--print"]],
-    ["deno", ["-e", "--eval", "-p", "--print"]],
-    ["python", ["-c"]],
-    ["python2", ["-c"]],
-    ["python3", ["-c"]],
-    ["ruby", ["-e"]],
-    ["perl", ["-e", "-E"]],
-    ["php", ["-r"]],
-]);
-/**
- * Shells, whose `-c` argument is a nested SHELL program. Not program text to be
- * discarded — program text to be PARSED, so `bash -c 'exec "$ROOT/hooks/x.sh"'`
- * still yields its script.
- */
-const SHELL_HEADS = new Set([
-    "sh",
-    "bash",
-    "zsh",
-    "dash",
-    "ksh",
-    "ash",
-    "busybox",
-]);
-/** Guard against a pathological `sh -c 'sh -c "sh -c …"'` nest. */
-const MAX_SHELL_NESTING = 3;
-/**
- * Every word of every simple command in `command` that could name a FILE, with
- * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
- * exist?".
- *
- * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
- * because "there is already one that returns words" is exactly the reasoning
- * that produced the bug this replaces.
- *
- *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
- *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
- *    disappears entirely. Unusable for a file question.
- *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
- *    `x.sh` and no resolver can find it.
- *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
- *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
- *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
- *    coverage attribution that abstention is correct; for "must this file
- *    exist?" it is a miss, because a conditionally-run script still has to be
- *    on disk.
- *
- * So this walks EVERY simple command, keeps every word at source level, and
- * subtracts only the words that are provably not paths.
- *
- * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
- * to run a regex over the raw command STRING. Against the standard portable
- * plugin idiom —
- *
- *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
- *
- * — it grabbed a character run ending at `.mjs` and reported the hook's script
- * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
- * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
- * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
- * parse the argument of `-e` is not a word the shell will ever resolve to a
- * file, so it is not returned.
- *
- * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
- * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
- * and re-auditing all three affected repos still yields ZERO false hook-script
- * findings, because both real payloads are single words that either contain
- * whitespace or do not end in a script extension, and the caller anchors its
- * match to a whole word. The table is kept because it is the difference
- * between a function whose contract ("words that could name a file") is true
- * and one whose contract is merely true-so-far: without it a JavaScript
- * program is handed to every caller as a candidate filename, and the next
- * caller inherits the bug. Recorded here so nobody reads a corpus number back
- * onto the wrong mechanism.
- *
- * Words beginning with `-` are dropped as flags: a flag is not a path, and the
- * one caller anchors its match to a whole word anyway.
- *
- * Returns `null` — not `[]` — when the text does not parse as shell, so a
- * caller can tell "no file operands" from "no analysis", and cannot silently
- * treat the second as the first.
- */
-function commandWords(command) {
-    return commandWordsAt(command, 0);
-}
-function commandWordsAt(command, depth) {
-    let file;
-    try {
-        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
-    }
-    catch {
-        return null;
-    }
-    const out = [];
-    sh().syntax.Walk(file, (node) => {
-        if (sh().syntax.NodeType(node) === "CallExpr" && node.Args?.length)
-            fileOperandsOf(node.Args, depth, out);
-        return true;
-    });
-    return out;
-}
-/**
- * The file-operand words of ONE simple command, appended to `out`.
- *
- * Wrappers are resolved through with the same table `leafArgvSource` uses (it
- * keys on the BASENAME head, and wrappers only ever drop words off the FRONT,
- * so a count maps the result back onto the original spellings — not a second
- * copy of the rule). Flags never name a file, so they are dropped; the word
- * AFTER an inline-program flag is dropped with them, and the word after a
- * shell's `-c` is parsed as shell instead.
- */
-function fileOperandsOf(args, depth, out) {
-    const raw = args.map((w) => sourceParts(w.Parts) ?? "");
-    const probe = [normalizeHead(raw[0] ?? ""), ...raw.slice(1)];
-    const argv = raw.slice(probe.length - stripWrappers(probe).argv.length);
-    const head = normalizeHead(argv[0] ?? "");
-    const programFlags = INLINE_PROGRAM_FLAGS.get(head);
-    const nestsShell = SHELL_HEADS.has(head) && depth < MAX_SHELL_NESTING;
-    for (let i = 0; i < argv.length; i++) {
-        const w = argv[i] ?? "";
-        if (w === "")
-            continue;
-        if (!w.startsWith("-")) {
-            out.push(w);
-            continue;
-        }
-        if (nestsShell && w === "-c") {
-            out.push(...(commandWordsAt(argv[++i] ?? "", depth + 1) ?? []));
-        }
-        else if (programFlags?.includes(w)) {
-            i++; // the program text — not a word any shell resolves to a file
-        }
-    }
-}
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/compile-generator.d.ts

@@ -48,16 +48,16 @@ export interface CompileGeneratorSkillResult {
  * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
  * hash), verifying gate references. This is the CLI entry for generator skills.
  */
-export declare function compileGeneratorSkill(source: string, options?: {
-    basePath?: string;
-    specFile?: string;
+export declare function compileGeneratorSkill(source: string, options: {
+    readonly basePath: string;
+    readonly specFile?: string;
 }): CompileGeneratorSkillResult;
 /**
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
  * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
  */
-export declare function compileGenerator(source: string, options?: {
-    basePath?: string;
-    frontmatter?: string;
+export declare function compileGenerator(source: string, options: {
+    readonly basePath: string;
+    readonly frontmatter?: string;
 }): CompileGeneratorResult;
 //# sourceMappingURL=compile-generator.d.ts.map

package/dist/core/compile-generator.js

@@ -263,8 +263,8 @@ function extractMeta(obj) {
  * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
  * hash), verifying gate references. This is the CLI entry for generator skills.
  */
-function compileGeneratorSkill(source, options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function compileGeneratorSkill(source, options) {
+    const basePath = options.basePath;
     const specFile = options.specFile ?? "SKILL.md.spec.ts";
     const sf = typescript_1.default.createSourceFile("s.ts", source, typescript_1.default.ScriptTarget.Latest, true);
     const call = findGenSkillCall(sf);
@@ -309,8 +309,8 @@ function compileGeneratorSkill(source, options = {}) {
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
  * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
  */
-function compileGenerator(source, options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function compileGenerator(source, options) {
+    const basePath = options.basePath;
     const sf = typescript_1.default.createSourceFile("skill.ts", source, typescript_1.default.ScriptTarget.Latest, true);
     const gen = findGenerator(sf);
     if (!gen?.body) {

package/dist/core/compile.d.ts

@@ -66,6 +66,46 @@ export declare function validateCommandRef(command: string, basePath: string): C
 export declare function validateSymbolRef(file: string, name: string, basePath: string): Promise<CompileError | null>;
 export declare function validateDirRef(dirPath: string, basePath: string): CompileError | null;
 export declare function validateGlobRef(pattern: string, basePath: string): CompileError | null;
+/**
+ * Why an `enforce()` reference was NOT verified. Separate members, not one
+ * "unknown", because the compile output turns each into a different instruction
+ * (make-the-distinction-a-type): a switch someone turned off is fixed by turning
+ * it on, an unset rule by setting it, an unreadable config by fixing the probe.
+ */
+export type UnverifiedReason = 
+/** `enforce(…, { verify: false })` on this rule. */
+"verify-false"
+/** `verifyLinters: false` for the whole compile. */
+ | "verification-off"
+/** `linterModes[<linter>] === false`. */
+ | "linter-off"
+/** catalog-only: the rule exists, the config was not read. */
+ | "config-not-read"
+/** the whole config was read and no block sets the rule. */
+ | "not-configured"
+/** the rule exists; whether the config switches it on could not be read. */
+ | "enabled-unknown"
+/** the rule does not exist (a compile error as well). */
+ | "not-found"
+/** the config switches the rule off (a compile error as well). */
+ | "disabled";
+/** What `compile` established about one `enforce()` reference. */
+export type EnforceVerdict = {
+    readonly kind: "verified";
+} | {
+    readonly kind: "unverified";
+    readonly reason: UnverifiedReason;
+};
+/** One `enforce()` reference and its verdict, in spec order. */
+export interface EnforceVerdictEntry {
+    readonly ref: string;
+    readonly verdict: EnforceVerdict;
+}
+/**
+ * The sentence the compile prints for an unverified reference: what happened
+ * and the one thing that turns it into "Enforced by".
+ */
+export declare function unverifiedAdvice(ref: string, reason: UnverifiedReason): string;
 export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];
@@ -86,10 +126,28 @@ export interface CompileClaudeResult {
      */
     budgetFindings: CompileError[];
     linterResults: LinterCheckResult[];
+    /**
+     * One entry per `enforce()` rule, in spec order: rendered "**Enforced by:**"
+     * exactly when `verdict.kind === "verified"`, "**Claimed (unverified):**"
+     * otherwise. The CLI's "N linter-verified" count is the verified entries.
+     */
+    enforceVerdicts: EnforceVerdictEntry[];
     /** Estimated token count of compiled output (~4 chars/token). */
     tokens: number;
     /** All targets from the spec (for multi-target compilation). */
     targets: string[];
+    /**
+     * Each target's file: its repo-relative path (a secondary target is named
+     * from the primary's directory) and its markdown, rendered for THAT path so
+     * every link resolves from where the file sits. The first is the primary,
+     * whose markdown is `markdown`.
+     */
+    outputs: CompiledOutput[];
+}
+/** One file a multi-target compile writes. */
+export interface CompiledOutput {
+    readonly path: string;
+    readonly markdown: string;
 }
 export interface CompileClaudeOptions {
     /**
@@ -107,7 +165,8 @@ export interface CompileClaudeOptions {
     maxSectionChars?: number;
     /** Character budget for the whole rendered Rules section (0 disables). */
     maxRulesChars?: number;
-    basePath?: string;
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    readonly basePath: string;
     specFile?: string;
     /** Injected harness dialect; its instructionTargets[0] is the default target. */
     dialect?: HarnessDialect;
@@ -166,13 +225,15 @@ export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
  * budget, which leaves the other half for everything else the file carries.
  */
 export declare const DEFAULT_MAX_RULES_CHARS = 20000;
+/** The compile options that decide how an `enforce()` reference is verified. */
+type LinterVerifyOptions = Pick<CompileClaudeOptions, "verifyLinters" | "linterModes" | "catalogOnly" | "linters">;
 /**
  * Compile a ClaudeSpec into markdown.
  *
  * Returns the compiled markdown, validation errors, and linter check results.
  * The markdown is generated even if there are errors (with warnings).
  */
-export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeOptions): Promise<CompileClaudeResult>;
+export declare function compileClaude(spec: ClaudeSpec, options: Readonly<CompileClaudeOptions>): Promise<CompileClaudeResult>;
 export interface CompileSkillResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -187,13 +248,14 @@ export interface CompileSkillResult {
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
  */
-export declare function compileSkill(spec: SkillSpec, options?: {
-    basePath?: string;
+export declare function compileSkill(spec: SkillSpec, options: Readonly<{
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    readonly basePath: string;
     specFile?: string;
     /** The harness dialect — supplies `skillFrontmatterKeys`. Omitting it emits
      *  every key the compiler can render, so existing callers are unchanged. */
     dialect?: HarnessDialect;
-}): Promise<CompileSkillResult>;
+}>): Promise<CompileSkillResult>;
 export interface CompileAgentResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -210,13 +272,14 @@ export interface CompileAgentResult {
  * Verifies the tool contract and the body's references; the marks the body
  * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
-export declare function compileAgent(spec: AgentSpec, options: {
-    basePath?: string;
+export declare function compileAgent(spec: AgentSpec, options: Readonly<{
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    basePath: string;
     specFile?: string;
     /** The harness dialect to verify the tool contract against (required — the
      *  core defines no default dialect; the adapter/composition root injects it). */
     dialect: HarnessDialect;
-}): Promise<CompileAgentResult>;
+} & LinterVerifyOptions>): Promise<CompileAgentResult>;
 export interface CompileRailwayOptions {
     /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
     knownAgents?: readonly string[];
@@ -261,4 +324,5 @@ export interface AdoptResult {
  * Returns the diff so users can see what was manually changed.
  */
 export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string, dialect: HarnessDialect): Promise<AdoptResult>;
+export {};
 //# sourceMappingURL=compile.d.ts.map