vigiles 14.7.0 → 14.9.0

package/dist/posix-path.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * A tiny, node-free POSIX `path` — the browser-safe substitute for `node:path`
+ * inside the in-browser audit engine (`scan-core.ts` / `scan-files.ts` /
+ * `test-coverage-files.ts` and the core detectors they reach). A Vite bundle of
+ * that engine must not pull `node:path`, so these are pure string ops.
+ *
+ * The audit engine's file-map keys are always POSIX (`/`-separated), and the
+ * disk-side `scanPlugin` feeds it absolute POSIX roots (`resolve(dir)` on Linux),
+ * so a faithful port of Node's `path.posix` algorithm is byte-identical to
+ * `node:path` for every input the engine passes — which is exactly what the
+ * parity firewall (`scan-files.test.ts`) proves. `resolve` deliberately falls
+ * back to `/` (never `process.cwd()`) so it stays pure and process-free; every
+ * call site passes an absolute first segment, so the fallback is never reached.
+ *
+ * NOTE — the functions below are VERBATIM ports of Node's `lib/path.js` POSIX
+ * implementations (charCode scan, `normalizeString`, `basename`, `relative`).
+ * Their branch depth / cyclomatic complexity is inherent to that battle-tested
+ * algorithm; rewriting it to satisfy the complexity linters would risk a subtle
+ * behavioural divergence from `node:path` (which the disk-vs-browser parity gate
+ * relies on), so the metric rules are disabled for this file only.
+ */
+/* eslint-disable complexity, max-depth, sonarjs/cognitive-complexity, sonarjs/nested-control-flow */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbsolute = isAbsolute;
+exports.normalize = normalize;
+exports.join = join;
+exports.resolve = resolve;
+exports.dirname = dirname;
+exports.basename = basename;
+exports.relative = relative;
+const SLASH = 47; // '/'
+const DOT = 46; // '.'
+/**
+ * The core POSIX normalize pass (ported from Node's `normalizeString`): collapse
+ * `.`/`..`/`//` in a slash-separated path with no leading root. `allowAboveRoot`
+ * keeps leading `..` segments (used for a relative path).
+ */
+function normalizeString(path, allowAboveRoot) {
+    let res = "";
+    let lastSegmentLength = 0;
+    let lastSlash = -1;
+    let dots = 0;
+    let code = 0;
+    for (let i = 0; i <= path.length; ++i) {
+        if (i < path.length)
+            code = path.charCodeAt(i);
+        else if (code === SLASH)
+            break;
+        else
+            code = SLASH;
+        if (code === SLASH) {
+            if (lastSlash === i - 1 || dots === 1) {
+                // no-op: a `//` or `.` segment
+            }
+            else if (dots === 2) {
+                if (res.length < 2 ||
+                    lastSegmentLength !== 2 ||
+                    res.charCodeAt(res.length - 1) !== DOT ||
+                    res.charCodeAt(res.length - 2) !== DOT) {
+                    if (res.length > 2) {
+                        const lastSlashIndex = res.lastIndexOf("/");
+                        if (lastSlashIndex === -1) {
+                            res = "";
+                            lastSegmentLength = 0;
+                        }
+                        else {
+                            res = res.slice(0, lastSlashIndex);
+                            lastSegmentLength = res.length - 1 - res.lastIndexOf("/");
+                        }
+                        lastSlash = i;
+                        dots = 0;
+                        continue;
+                    }
+                    else if (res.length !== 0) {
+                        res = "";
+                        lastSegmentLength = 0;
+                        lastSlash = i;
+                        dots = 0;
+                        continue;
+                    }
+                }
+                if (allowAboveRoot) {
+                    res += res.length > 0 ? "/.." : "..";
+                    lastSegmentLength = 2;
+                }
+            }
+            else {
+                if (res.length > 0)
+                    res += "/" + path.slice(lastSlash + 1, i);
+                else
+                    res = path.slice(lastSlash + 1, i);
+                lastSegmentLength = i - lastSlash - 1;
+            }
+            lastSlash = i;
+            dots = 0;
+        }
+        else if (code === DOT && dots !== -1) {
+            ++dots;
+        }
+        else {
+            dots = -1;
+        }
+    }
+    return res;
+}
+/** POSIX `path.isAbsolute`. */
+function isAbsolute(path) {
+    return path.length > 0 && path.charCodeAt(0) === SLASH;
+}
+/** POSIX `path.normalize`. */
+function normalize(path) {
+    if (path.length === 0)
+        return ".";
+    const isAbs = path.charCodeAt(0) === SLASH;
+    const trailingSep = path.charCodeAt(path.length - 1) === SLASH;
+    path = normalizeString(path, !isAbs);
+    if (path.length === 0) {
+        if (isAbs)
+            return "/";
+        return trailingSep ? "./" : ".";
+    }
+    if (trailingSep)
+        path += "/";
+    return isAbs ? `/${path}` : path;
+}
+/** POSIX `path.join`. */
+function join(...parts) {
+    if (parts.length === 0)
+        return ".";
+    let joined;
+    for (const part of parts) {
+        if (part.length > 0) {
+            if (joined === undefined)
+                joined = part;
+            else
+                joined += `/${part}`;
+        }
+    }
+    if (joined === undefined)
+        return ".";
+    return normalize(joined);
+}
+/**
+ * POSIX `path.resolve`. Right-to-left until an absolute segment is found, then
+ * normalize. The `i === -1` fallback is `/` (not `process.cwd()`) so this stays
+ * pure; every engine call site passes an absolute first segment.
+ */
+function resolve(...parts) {
+    let resolvedPath = "";
+    let resolvedAbsolute = false;
+    for (let i = parts.length - 1; i >= -1 && !resolvedAbsolute; i--) {
+        const path = i >= 0 ? parts[i] : "/";
+        if (path.length === 0)
+            continue;
+        resolvedPath = `${path}/${resolvedPath}`;
+        resolvedAbsolute = path.charCodeAt(0) === SLASH;
+    }
+    resolvedPath = normalizeString(resolvedPath, !resolvedAbsolute);
+    if (resolvedAbsolute)
+        return `/${resolvedPath}`;
+    return resolvedPath.length > 0 ? resolvedPath : ".";
+}
+/** POSIX `path.dirname`. */
+function dirname(path) {
+    if (path.length === 0)
+        return ".";
+    const hasRoot = path.charCodeAt(0) === SLASH;
+    let end = -1;
+    let matchedSlash = true;
+    for (let i = path.length - 1; i >= 1; --i) {
+        if (path.charCodeAt(i) === SLASH) {
+            if (!matchedSlash) {
+                end = i;
+                break;
+            }
+        }
+        else {
+            matchedSlash = false;
+        }
+    }
+    if (end === -1)
+        return hasRoot ? "/" : ".";
+    if (hasRoot && end === 1)
+        return "//";
+    return path.slice(0, end);
+}
+/** POSIX `path.basename` (with an optional `suffix` to strip, like `node:path`). */
+function basename(path, suffix) {
+    let start = 0;
+    let end = -1;
+    let matchedSlash = true;
+    if (suffix !== undefined &&
+        suffix.length > 0 &&
+        suffix.length <= path.length) {
+        if (suffix === path)
+            return "";
+        let extIdx = suffix.length - 1;
+        let firstNonSlashEnd = -1;
+        for (let i = path.length - 1; i >= 0; --i) {
+            const code = path.charCodeAt(i);
+            if (code === SLASH) {
+                if (!matchedSlash) {
+                    start = i + 1;
+                    break;
+                }
+            }
+            else {
+                if (firstNonSlashEnd === -1) {
+                    matchedSlash = false;
+                    firstNonSlashEnd = i + 1;
+                }
+                if (extIdx >= 0) {
+                    if (code === suffix.charCodeAt(extIdx)) {
+                        if (--extIdx === -1) {
+                            end = i;
+                        }
+                    }
+                    else {
+                        extIdx = -1;
+                        end = firstNonSlashEnd;
+                    }
+                }
+            }
+        }
+        if (start === end)
+            end = firstNonSlashEnd;
+        else if (end === -1)
+            end = path.length;
+        return path.slice(start, end);
+    }
+    for (let i = path.length - 1; i >= 0; --i) {
+        if (path.charCodeAt(i) === SLASH) {
+            if (!matchedSlash) {
+                start = i + 1;
+                break;
+            }
+        }
+        else if (end === -1) {
+            matchedSlash = false;
+            end = i + 1;
+        }
+    }
+    if (end === -1)
+        return "";
+    return path.slice(start, end);
+}
+/** POSIX `path.relative`. */
+function relative(from, to) {
+    if (from === to)
+        return "";
+    from = resolve(from);
+    to = resolve(to);
+    if (from === to)
+        return "";
+    const fromStart = 1;
+    const fromEnd = from.length;
+    const fromLen = fromEnd - fromStart;
+    const toStart = 1;
+    const toLen = to.length - toStart;
+    const length = fromLen < toLen ? fromLen : toLen;
+    let lastCommonSep = -1;
+    let i = 0;
+    for (; i < length; i++) {
+        const fromCode = from.charCodeAt(fromStart + i);
+        if (fromCode !== to.charCodeAt(toStart + i))
+            break;
+        else if (fromCode === SLASH)
+            lastCommonSep = i;
+    }
+    if (i === length) {
+        if (toLen > length) {
+            if (to.charCodeAt(toStart + i) === SLASH)
+                return to.slice(toStart + i + 1);
+            if (i === 0)
+                return to.slice(toStart + i);
+        }
+        else if (fromLen > length) {
+            if (from.charCodeAt(fromStart + i) === SLASH)
+                lastCommonSep = i;
+            else if (i === 0)
+                lastCommonSep = 0;
+        }
+    }
+    let out = "";
+    for (i = fromStart + lastCommonSep + 1; i <= fromEnd; ++i) {
+        if (i === fromEnd || from.charCodeAt(i) === SLASH) {
+            out += out.length === 0 ? ".." : "/..";
+        }
+    }
+    return `${out}${to.slice(toStart + lastCommonSep)}`;
+}
+//# sourceMappingURL=posix-path.js.map

package/dist/scan-core.d.ts

@@ -0,0 +1,154 @@
+import { type DescriptionOverlap } from "./core/description-overlap.js";
+import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
+import type { PluginLayout } from "./core/layout.js";
+import type { HarnessDialect } from "./core/dialect.js";
+import type { HookRegistration } from "./core/hook-normalize.js";
+import type { HookScriptEntry } from "./core/hook-block-ineffective.js";
+import type { HookMatcherEntry } from "./core/hook-matcher.js";
+import type { ScanSkill, ScanAgent, ScanHook, FrontmatterIssue, FrontmatterValueIssue, FrontmatterParseIssue, ScanTrifectaFinding, ScanSkillResourceFinding, ScanSkillFenceFinding, ScanDelegationFinding } from "./scan.js";
+/**
+ * Per-kind surface classifiers, built from the harness `PluginLayout`'s
+ * `skillDir`/`agentDir`/`commandDir` — so adding a harness whose subagents live
+ * somewhere other than `agents/` (OpenCode's `.opencode/agent`) needs no change
+ * here. Each anchors on a real path boundary (start-of-path or a `/`), so a
+ * directory whose NAME merely ends in the keyword isn't misclassified — e.g. the
+ * skill `skills/dispatching-parallel-agents/SKILL.md` must NOT register as an
+ * agent named "SKILL" (the `-agents/` substring), which real plugins like
+ * obra/superpowers ship. See scan.test.ts for the regression cases.
+ */
+export interface SurfaceClassifier {
+    readonly isSkill: (f: string) => boolean;
+    readonly isAgent: (f: string) => boolean;
+    readonly isCommand: (f: string) => boolean;
+}
+export declare function makeClassifier(layout: PluginLayout): SurfaceClassifier;
+/** The plugin-root + materialize-root + dialect context skill scanning needs. */
+export interface SkillScanContext {
+    readonly root: string;
+    readonly materializeRoot: string;
+    readonly dialect: HarnessDialect;
+    /**
+     * Materialized-key → real on-disk path (from `loadPlugin`). A surface can be
+     * materialized under a canonical key while living at a different root (repo-root
+     * `skills/` vs project-level `.claude/skills/`), so bundled-resource resolution
+     * uses the true dir from here rather than reverse-guessing from the key.
+     */
+    readonly sources?: Record<string, string>;
+    /** OPT-IN top-level shared-resource dirs (`.vigilesrc.json` `sharedDirs`). */
+    readonly sharedDirs?: readonly string[];
+    /**
+     * The REPO root the `sharedDirs` are declared relative to (where `.vigilesrc.json`
+     * lives) — distinct from the scan `root`, which may be a scoped SUBDIR (e.g.
+     * `lint packages/foo`). A shared-dir ref resolves against THIS, not the subdir,
+     * so a scoped scan doesn't false-flag the top-level shared tree. Defaults to
+     * `root` (unchanged when scanning the repo root itself).
+     */
+    readonly sharedDirsRoot?: string;
+    /**
+     * REQUIRED existence check for bundled-resource resolution. The disk scan
+     * (`scanPlugin`) injects `node:fs` `existsSync`; the browser file-map engine
+     * (`scanFiles`) a map-backed impl — so the same `scanSkills` runs on disk OR
+     * in the browser with no `node:` import in this node-free module.
+     */
+    readonly existsSync: (p: string) => boolean;
+}
+export declare function scanSkills(files: Record<string, string>, cls: SurfaceClassifier, ctx: SkillScanContext): ScanSkill[];
+export declare function descriptionOverlapsFor(files: Record<string, string>, cls: SurfaceClassifier): DescriptionOverlap[];
+/**
+ * Model-invocable skills whose description is so long the trigger signal is
+ * buried (heuristic proxy; degrades recall + precision). Same surfaces as the
+ * overlap check. See skill-description-budget.ts.
+ */
+export declare function descriptionBudgetFor(files: Record<string, string>, cls: SurfaceClassifier): DescriptionBudgetIssue[];
+export declare function scanAgents(files: Record<string, string>, dialect: HarnessDialect, declaredServers: readonly string[], cls: SurfaceClassifier): ScanAgent[];
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+export declare function isManagedHookCommand(command: string): boolean;
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+export declare function preferCompiledHooksMessage(count: number): string;
+export declare function scanHooks(regs: readonly HookRegistration[], root: string, pluginRootToken: string, exists: (p: string) => boolean): {
+    hooks: ScanHook[];
+    inline: number;
+    manual: number;
+};
+/**
+ * Frontmatter-schema check — **subagents only**. Per the Claude Code docs, a
+ * subagent (`agents/*.md`) REQUIRES `name` + `description` (no fallback) or it
+ * won't register. A SKILL.md requires NOTHING: `name` falls back to the directory
+ * name and `description` to the first body paragraph, so a frontmatter-less skill
+ * still loads — flagging it would be a false positive (skill description QUALITY
+ * is a separate, behavioral concern). See https://code.claude.com/docs/en/skills
+ * and …/sub-agents.
+ */
+export declare function frontmatterIssuesFor(files: Record<string, string>, cls: SurfaceClassifier): FrontmatterIssue[];
+/**
+ * Agent frontmatter VALUE validity — a `model:` or `color:` that's a close typo
+ * of a real one. A bad `model:` silently falls back; a bad `color:` is ignored.
+ * High-precision (close-typo only); a full/dated model id is left alone. Folded
+ * into the `subagent-frontmatter` rule. Agents only (skills have no model/color).
+ */
+export declare function frontmatterValueIssuesFor(files: Record<string, string>, cls: SurfaceClassifier): FrontmatterValueIssue[];
+/**
+ * Frontmatter that EXISTS but isn't valid YAML — the `frontmatter-valid` signal.
+ * Reported for skills + agents via the shared reader's `malformed` flag. Honest
+ * caveat (see docs/rules/frontmatter-valid.md): js-yaml is stricter than some
+ * loaders, so a one-line `description:` containing a `: ` colon or an `<example>`
+ * block is flagged even though it may still load — which is why scan surfaces it
+ * as an informational note (NOT a structural defect) and the lint rule is a
+ * warn, not an error. The file's other fields are still salvaged.
+ */
+export declare function malformedFrontmatterFor(files: Record<string, string>, cls: SurfaceClassifier): FrontmatterParseIssue[];
+/**
+ * Skill-metadata RECOMMENDATION (not a correctness check): a `SKILL.md` loads
+ * fine without frontmatter (`name` ← dir, `description` ← first body paragraph),
+ * but relying on those fallbacks is fragile — the dir name may be unclear and the
+ * first paragraph is often a heading or boilerplate, making a weak trigger
+ * surface. Best practice is an EXPLICIT `name` + `description`. Flags skills
+ * missing either; surfaced as a soft note in scan (NOT a structural defect, NOT
+ * scored) and gated by the `skill-frontmatter` lint rule (warn by default).
+ */
+export declare function skillMetaIssuesFor(files: Record<string, string>, cls: SurfaceClassifier): FrontmatterIssue[];
+/**
+ * Flatten the per-surface lethal-trifecta + skill-resource findings into the
+ * path-tagged report lists the `audit` report AND the `lethal-trifecta` /
+ * `skill-resource-resolves` lint rules both consume (one detector, no drift).
+ */
+export declare function collectSurfaceFindings(agents: readonly ScanAgent[], skills: readonly ScanSkill[]): {
+    trifectaFindings: ScanTrifectaFinding[];
+    skillResourceFindings: ScanSkillResourceFinding[];
+    skillFenceFindings: ScanSkillFenceFinding[];
+};
+/**
+ * Build the subagent delegation graph and flag a lethal trifecta that EMERGES
+ * across an edge (own ∪ delegated-to capability) though no single unit trips it.
+ *
+ * Edge source (deterministic, audit-available): a subagent that lists the `Task`
+ * tool can dispatch any sibling subagent, so it `delegatesTo` every OTHER agent.
+ * An inherits-all agent (`tools === null`) carries the wildcard, which the
+ * detector's FP-safe guard skips (that maximal-blast case is the per-unit
+ * advisory's job). One detector, no drift. (Richer edge sources — a typed
+ * railway's `delegate()` chain, a Flue subagent inheritance tree — plug in here.)
+ */
+export declare function collectDelegationTrifecta(agents: readonly ScanAgent[], dialect: HarnessDialect): ScanDelegationFinding[];
+/**
+ * Build `hookBlockIssues` entries by walking the canonical object-keyed-by-event
+ * settings shape PER REGISTRATION — so a script registered under several events
+ * is inspected under EACH (no de-dup by script path), inline one-liners are
+ * included (script token → null, inspect the command), and a script token is
+ * resolved to its ABSOLUTE on-disk path against the plugin root (not the caller's
+ * cwd). Addresses the gaps a de-duplicated `ScanHook[]` would miss.
+ */
+export declare function collectHookBlockEntries(regs: readonly HookRegistration[], root: string, pluginRootToken: string, exists: (p: string) => boolean): HookScriptEntry[];
+/** Extract (event, matcher) pairs from the normalized hook registrations. */
+export declare function collectHookMatchers(regs: readonly HookRegistration[]): HookMatcherEntry[];
+/** Tally how many scanned agents fall into each purity rung (effectSurface). */
+export declare function summarizePurity(agents: readonly ScanAgent[]): {
+    pure: number;
+    bounded: number;
+    unrestricted: number;
+};
+//# sourceMappingURL=scan-core.d.ts.map