@wix/pathgrade 0.29.0

package/bin/pathgrade.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/pathgrade.js';

package/dist/affected/anchor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Skill-anchor resolution for affected-eval selection.
+ *
+ * Walks the directory tree upward from an eval file looking for the nearest
+ * `SKILL.md` file. The first ancestor directory containing `SKILL.md` is the
+ * **skill root**. Returns the skill root path repo-relative (forward slashes),
+ * or `null` if no ancestor has `SKILL.md`.
+ */
+/**
+ * Resolve the nearest SKILL.md ancestor directory for an eval file.
+ *
+ * @param evalFile  Absolute or repo-relative path to the `.eval.ts` file.
+ * @param repoRoot  Absolute path to the repo root. All returned paths are
+ *                  repo-root-relative with forward slashes.
+ * @returns the skill root directory path (e.g., `"skills/foo"`), or `null`
+ *          if no `SKILL.md` ancestor is found up to the repo root.
+ */
+export declare function findSkillRoot(evalFile: string, repoRoot: string): string | null;

package/dist/affected/anchor.js

@@ -0,0 +1,42 @@
+/**
+ * Skill-anchor resolution for affected-eval selection.
+ *
+ * Walks the directory tree upward from an eval file looking for the nearest
+ * `SKILL.md` file. The first ancestor directory containing `SKILL.md` is the
+ * **skill root**. Returns the skill root path repo-relative (forward slashes),
+ * or `null` if no ancestor has `SKILL.md`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+/**
+ * Resolve the nearest SKILL.md ancestor directory for an eval file.
+ *
+ * @param evalFile  Absolute or repo-relative path to the `.eval.ts` file.
+ * @param repoRoot  Absolute path to the repo root. All returned paths are
+ *                  repo-root-relative with forward slashes.
+ * @returns the skill root directory path (e.g., `"skills/foo"`), or `null`
+ *          if no `SKILL.md` ancestor is found up to the repo root.
+ */
+export function findSkillRoot(evalFile, repoRoot) {
+    const absEvalFile = path.isAbsolute(evalFile)
+        ? evalFile
+        : path.resolve(repoRoot, evalFile);
+    const absRepoRoot = path.resolve(repoRoot);
+    let current = path.dirname(absEvalFile);
+    while (true) {
+        if (fs.existsSync(path.join(current, 'SKILL.md'))) {
+            const rel = path.relative(absRepoRoot, current);
+            return rel === '' ? '.' : toPosix(rel);
+        }
+        if (current === absRepoRoot)
+            break;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return null;
+}

package/dist/affected/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Load `vitest.config.ts` at CLI time and extract the pathgrade plugin's
+ * `affected.global` configuration.
+ *
+ * Why this file exists: `pathgrade()` runs *inside* the vitest process, but
+ * `pathgrade affected` / `pathgrade run --changed` compute selection
+ * *before* vitest spawns. So the CLI must read the plugin's options itself.
+ * We do that by importing the user's `vitest.config.ts` via `jiti`
+ * (already a pathgrade dependency), walking the resulting plugin list, and
+ * finding the pathgrade plugin instance — which annotates itself with
+ * `__pathgradeOptions` so that pre-vitest tooling can extract its options
+ * without re-executing the plugin factory.
+ *
+ * v1 limitation: `vitest.workspace.ts` is detected and warned about, but
+ * not traversed. Affected-selection still works via per-eval deps; only
+ * the `affected.global` short-circuit is disabled in workspace mode.
+ * Documented in USER_GUIDE for Issue 14.
+ */
+export interface AffectedConfig {
+    global: string[];
+}
+export interface LoadOptions {
+    onWarning?: (message: string) => void;
+}
+export declare function loadAffectedConfig(repoRoot: string, options?: LoadOptions): Promise<AffectedConfig>;

package/dist/affected/config.js

@@ -0,0 +1,98 @@
+/**
+ * Load `vitest.config.ts` at CLI time and extract the pathgrade plugin's
+ * `affected.global` configuration.
+ *
+ * Why this file exists: `pathgrade()` runs *inside* the vitest process, but
+ * `pathgrade affected` / `pathgrade run --changed` compute selection
+ * *before* vitest spawns. So the CLI must read the plugin's options itself.
+ * We do that by importing the user's `vitest.config.ts` via `jiti`
+ * (already a pathgrade dependency), walking the resulting plugin list, and
+ * finding the pathgrade plugin instance — which annotates itself with
+ * `__pathgradeOptions` so that pre-vitest tooling can extract its options
+ * without re-executing the plugin factory.
+ *
+ * v1 limitation: `vitest.workspace.ts` is detected and warned about, but
+ * not traversed. Affected-selection still works via per-eval deps; only
+ * the `affected.global` short-circuit is disabled in workspace mode.
+ * Documented in USER_GUIDE for Issue 14.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createJiti } from 'jiti';
+const VITEST_CONFIG_CANDIDATES = [
+    'vitest.config.ts',
+    'vitest.config.mts',
+    'vitest.config.js',
+    'vitest.config.mjs',
+];
+const WORKSPACE_CANDIDATES = [
+    'vitest.workspace.ts',
+    'vitest.workspace.js',
+    'vitest.workspace.mts',
+    'vitest.workspace.mjs',
+];
+export async function loadAffectedConfig(repoRoot, options = {}) {
+    const warn = options.onWarning ?? (() => { });
+    // v1 limitation: workspace mode skips the short-circuit.
+    for (const candidate of WORKSPACE_CANDIDATES) {
+        if (fs.existsSync(path.join(repoRoot, candidate))) {
+            warn(`pathgrade: ${candidate} detected — v1 does not read affected.global from workspace configs; ` +
+                `selection will still work, but the repo-wide short-circuit is disabled.`);
+            return { global: [] };
+        }
+    }
+    const configPath = VITEST_CONFIG_CANDIDATES
+        .map(c => path.join(repoRoot, c))
+        .find(p => fs.existsSync(p));
+    if (!configPath)
+        return { global: [] };
+    let loaded;
+    try {
+        const jiti = createJiti(repoRoot, { interopDefault: true });
+        loaded = await jiti.import(configPath, { default: true });
+    }
+    catch (err) {
+        warn(`pathgrade: failed to load ${path.relative(repoRoot, configPath)}: ${errMsg(err)}`);
+        return { global: [] };
+    }
+    const plugins = findPluginsList(loaded);
+    if (!plugins) {
+        warn(`pathgrade: no plugin list found in ${path.relative(repoRoot, configPath)}`);
+        return { global: [] };
+    }
+    const pathgradePlugin = plugins.find(p => isPathgradePlugin(p));
+    if (!pathgradePlugin) {
+        warn(`pathgrade: no pathgrade plugin found in ${path.relative(repoRoot, configPath)} — ` +
+            `affected.global will be empty. Add \`pathgrade()\` to your vitest plugins list.`);
+        return { global: [] };
+    }
+    const opts = pathgradePlugin.__pathgradeOptions ?? {};
+    const global = opts.affected?.global;
+    return { global: Array.isArray(global) ? global : [] };
+}
+/**
+ * Given a loaded vitest config (either the raw export or a `defineConfig()`
+ * result), locate the plugin array. Supports both:
+ *   - `defineConfig({ plugins: [...] })`  (top-level)
+ *   - `defineConfig({ test: { plugins: [...] } })` (vitest convention)
+ */
+function findPluginsList(config) {
+    if (!config || typeof config !== 'object')
+        return null;
+    const c = config;
+    if (Array.isArray(c.plugins))
+        return c.plugins;
+    if (c.test && typeof c.test === 'object' && Array.isArray(c.test.plugins)) {
+        return c.test.plugins;
+    }
+    return null;
+}
+function isPathgradePlugin(plugin) {
+    if (!plugin || typeof plugin !== 'object')
+        return false;
+    const p = plugin;
+    return p.name === 'pathgrade' || '__pathgradeOptions' in p;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/affected/format.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Formatters for `pathgrade affected --explain` and `--json`.
+ *
+ * JSON wire-format uses snake_case; the TS interface uses camelCase.
+ * The enum values (`SelectionReason`) go on the wire as-is.
+ *
+ * This file stays pure — no fs, no process I/O — so it can be re-used by
+ * Issue 11's sidecar writer (which uses the same shape, except for the
+ * size-optimized `changed_files_count` summary).
+ */
+import type { SelectionResult } from './types.js';
+interface JsonSelectionEntry {
+    file: string;
+    reason: string;
+    matched_glob?: string;
+}
+interface JsonSelectionSkipped {
+    file: string;
+    reason: string;
+}
+export interface JsonSelectionResult {
+    base_ref: string;
+    changed_files: string[];
+    global_match?: string;
+    selected: JsonSelectionEntry[];
+    skipped: JsonSelectionSkipped[];
+    warnings: string[];
+}
+/**
+ * Transform `SelectionResult` (camelCase) into the snake_case wire shape
+ * consumed by `--json` and the sidecar-writer (Issue 11).
+ */
+export declare function toJsonShape(result: SelectionResult): JsonSelectionResult;
+/**
+ * Stable JSON: keys in a fixed order, arrays pre-sorted by `toJsonShape`.
+ * Emits a trailing newline so downstream tools can treat it like any other
+ * command output.
+ */
+export declare function formatJson(result: SelectionResult): string;
+/**
+ * Human-readable explanation for `--explain`. One section: base ref,
+ * changed files, per-eval decision with reason, warnings footer.
+ */
+export declare function formatExplain(result: SelectionResult): string;
+export {};

package/dist/affected/format.js

@@ -0,0 +1,87 @@
+/**
+ * Formatters for `pathgrade affected --explain` and `--json`.
+ *
+ * JSON wire-format uses snake_case; the TS interface uses camelCase.
+ * The enum values (`SelectionReason`) go on the wire as-is.
+ *
+ * This file stays pure — no fs, no process I/O — so it can be re-used by
+ * Issue 11's sidecar writer (which uses the same shape, except for the
+ * size-optimized `changed_files_count` summary).
+ */
+/**
+ * Transform `SelectionResult` (camelCase) into the snake_case wire shape
+ * consumed by `--json` and the sidecar-writer (Issue 11).
+ */
+export function toJsonShape(result) {
+    const out = {
+        base_ref: result.baseRef,
+        changed_files: [...result.changedFiles].sort(),
+        selected: result.selected.map(s => {
+            const entry = { file: s.file, reason: s.reason };
+            if (s.matchedGlob !== undefined)
+                entry.matched_glob = s.matchedGlob;
+            return entry;
+        }),
+        skipped: [...result.skipped].sort((a, b) => a.file.localeCompare(b.file)),
+        warnings: [...result.warnings],
+    };
+    if (result.globalMatch !== undefined)
+        out.global_match = result.globalMatch;
+    return out;
+}
+/**
+ * Stable JSON: keys in a fixed order, arrays pre-sorted by `toJsonShape`.
+ * Emits a trailing newline so downstream tools can treat it like any other
+ * command output.
+ */
+export function formatJson(result) {
+    return JSON.stringify(toJsonShape(result), null, 2) + '\n';
+}
+/**
+ * Human-readable explanation for `--explain`. One section: base ref,
+ * changed files, per-eval decision with reason, warnings footer.
+ */
+export function formatExplain(result) {
+    const lines = [];
+    lines.push(`base: ${result.baseRef}`);
+    lines.push(`changed files: ${result.changedFiles.length}`);
+    for (const f of result.changedFiles)
+        lines.push(`  - ${f}`);
+    if (result.globalMatch) {
+        lines.push('');
+        lines.push(`global trigger fired: \`${result.globalMatch}\` — all ${result.selected.length} evals selected`);
+    }
+    lines.push('');
+    lines.push(`selected: ${result.selected.length}`);
+    for (const s of result.selected) {
+        lines.push(`  + ${s.file} — ${reasonLabel(s.reason, s.matchedGlob)}`);
+    }
+    if (result.skipped.length > 0) {
+        lines.push('');
+        lines.push(`skipped: ${result.skipped.length}`);
+        for (const s of result.skipped) {
+            lines.push(`  - ${s.file} — ${s.reason}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        lines.push('');
+        lines.push('warnings:');
+        for (const w of result.warnings)
+            lines.push(`  ⚠  ${w}`);
+    }
+    return lines.join('\n') + '\n';
+}
+function reasonLabel(reason, matchedGlob) {
+    switch (reason) {
+        case 'deps-match':
+            return matchedGlob ? `deps match (${matchedGlob})` : 'deps match';
+        case 'always-run':
+            return 'selected: alwaysRun';
+        case 'global-match':
+            return matchedGlob ? `global match (${matchedGlob})` : 'global match';
+        case 'on-missing-fail-closed':
+            return 'selected: onMissing fail-closed';
+        default:
+            return reason;
+    }
+}

package/dist/affected/git.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Git-based change detection for affected-eval-selection.
+ *
+ * Resolves the base ref (merge-base preferred) and computes the repo-relative
+ * file list that changed between that base and HEAD. See PRD §"Change Detection".
+ *
+ * Three precedence branches for base-ref resolution, in order:
+ *   1. `GITHUB_BASE_REF` (GitHub Actions pull_request event) → merge-base
+ *      between `refs/remotes/origin/$GITHUB_BASE_REF` and `HEAD`.
+ *   2. `GITHUB_EVENT_BEFORE` (push event) if non-zero SHA → diff vs. that SHA.
+ *      The all-zero SHA (`000…000`) is emitted on branch-first-push and falls
+ *      through to branch 3.
+ *   3. Fallback: `git merge-base HEAD origin/main`.
+ *
+ * Merge-base (not plain two-dot) is critical for long-lived branches whose
+ * base has diverged. Vitest's built-in `--changed` gets this wrong; we must not.
+ */
+export type BaseRefResolution = {
+    base: string;
+    sha: string;
+} | {
+    error: string;
+};
+/**
+ * Resolve the git base ref to diff against. Accepts an env object (defaults
+ * to `process.env`) so tests can exercise each precedence branch.
+ */
+export declare function resolveBaseRef(env?: NodeJS.ProcessEnv): BaseRefResolution;
+/**
+ * Repo-relative file list changed between `<base>...HEAD`. The three-dot
+ * form covers adds, modifications, deletions, and both sides of renames.
+ */
+export declare function computeChangedFiles(base: string): string[];

package/dist/affected/git.js

@@ -0,0 +1,68 @@
+/**
+ * Git-based change detection for affected-eval-selection.
+ *
+ * Resolves the base ref (merge-base preferred) and computes the repo-relative
+ * file list that changed between that base and HEAD. See PRD §"Change Detection".
+ *
+ * Three precedence branches for base-ref resolution, in order:
+ *   1. `GITHUB_BASE_REF` (GitHub Actions pull_request event) → merge-base
+ *      between `refs/remotes/origin/$GITHUB_BASE_REF` and `HEAD`.
+ *   2. `GITHUB_EVENT_BEFORE` (push event) if non-zero SHA → diff vs. that SHA.
+ *      The all-zero SHA (`000…000`) is emitted on branch-first-push and falls
+ *      through to branch 3.
+ *   3. Fallback: `git merge-base HEAD origin/main`.
+ *
+ * Merge-base (not plain two-dot) is critical for long-lived branches whose
+ * base has diverged. Vitest's built-in `--changed` gets this wrong; we must not.
+ */
+import { execFileSync } from 'child_process';
+const ALL_ZERO_SHA = '0000000000000000000000000000000000000000';
+/**
+ * Resolve the git base ref to diff against. Accepts an env object (defaults
+ * to `process.env`) so tests can exercise each precedence branch.
+ */
+export function resolveBaseRef(env = process.env) {
+    const { GITHUB_BASE_REF, GITHUB_EVENT_BEFORE } = env;
+    if (GITHUB_BASE_REF) {
+        const ref = `refs/remotes/origin/${GITHUB_BASE_REF}`;
+        try {
+            const sha = runGit(['merge-base', ref, 'HEAD']);
+            return { base: ref, sha };
+        }
+        catch (err) {
+            return { error: formatMergeBaseError(err) };
+        }
+    }
+    if (GITHUB_EVENT_BEFORE && GITHUB_EVENT_BEFORE !== ALL_ZERO_SHA) {
+        // Explicit SHA: no merge-base resolution needed.
+        return { base: GITHUB_EVENT_BEFORE, sha: GITHUB_EVENT_BEFORE };
+    }
+    // Fallback: merge-base with origin/main.
+    try {
+        const sha = runGit(['merge-base', 'HEAD', 'origin/main']);
+        return { base: 'origin/main', sha };
+    }
+    catch (err) {
+        return { error: formatMergeBaseError(err) };
+    }
+}
+/**
+ * Repo-relative file list changed between `<base>...HEAD`. The three-dot
+ * form covers adds, modifications, deletions, and both sides of renames.
+ */
+export function computeChangedFiles(base) {
+    const output = runGit(['diff', '--relative', '--name-only', `${base}...HEAD`]);
+    return output
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+}
+function runGit(args) {
+    return execFileSync('git', args, { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+}
+function formatMergeBaseError(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return (`pathgrade: merge-base resolution failed — ensure \`actions/checkout@v4\` ` +
+        `has \`fetch-depth: 0\` (shallow clones break merge-base). ` +
+        `Underlying error: ${detail}`);
+}

package/dist/affected/glob.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Repo-root-relative glob matching helpers for the affected-selection pipeline.
+ *
+ * All paths — both globs and test paths — must be repo-root-relative with
+ * forward slashes. Callers are responsible for normalization.
+ */
+export interface GlobIntersection {
+    /** If any file matched any glob, which glob fired (first match wins). */
+    matchedGlob?: string;
+    matched: boolean;
+}
+/**
+ * Return `{ matched: true, matchedGlob }` if any path in `files` matches any
+ * glob in `globs`. Iteration order: globs outer, files inner — we surface the
+ * first glob (in declared order) that has at least one hit.
+ */
+export declare function intersect(globs: string[], files: string[]): GlobIntersection;

package/dist/affected/glob.js

@@ -0,0 +1,25 @@
+/**
+ * Repo-root-relative glob matching helpers for the affected-selection pipeline.
+ *
+ * All paths — both globs and test paths — must be repo-root-relative with
+ * forward slashes. Callers are responsible for normalization.
+ */
+import picomatch from 'picomatch';
+function toMatcher(glob) {
+    return picomatch(glob, { dot: true });
+}
+/**
+ * Return `{ matched: true, matchedGlob }` if any path in `files` matches any
+ * glob in `globs`. Iteration order: globs outer, files inner — we surface the
+ * first glob (in declared order) that has at least one hit.
+ */
+export function intersect(globs, files) {
+    for (const glob of globs) {
+        const match = toMatcher(glob);
+        for (const f of files) {
+            if (match(f))
+                return { matched: true, matchedGlob: glob };
+        }
+    }
+    return { matched: false };
+}

package/dist/affected/meta.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Static extraction of the `__pathgradeMeta` export from an eval file.
+ *
+ * The eval module is **never executed** — we parse it with the TypeScript
+ * compiler's syntax API and walk the AST to find `export const __pathgradeMeta`.
+ * This is critical: evals typically perform real work at module load
+ * (creating agents, hitting LLMs) and running them just to read a static
+ * declaration would defeat the purpose of affected-selection.
+ *
+ * Consequence: the value must be a literal expression. Dynamic composition
+ * (`deps: [...BASE, 'extra']`, spread, computed identifiers) is not supported.
+ * Users needing dedup should codegen the file from a build script.
+ *
+ * Returns `null` when the export is absent. Issue 7 will extend this to
+ * throw on malformed meta (non-array deps, invalid globs, path-escape).
+ */
+export interface ParsedMeta {
+    deps?: string[];
+    extraDeps?: string[];
+    alwaysRun?: boolean;
+}
+/**
+ * Parse `__pathgradeMeta` from an eval file's AST. Returns `null` if the
+ * export is not present.
+ */
+export declare function parsePathgradeMeta(evalFile: string): ParsedMeta | null;

package/dist/affected/meta.js

@@ -0,0 +1,158 @@
+/**
+ * Static extraction of the `__pathgradeMeta` export from an eval file.
+ *
+ * The eval module is **never executed** — we parse it with the TypeScript
+ * compiler's syntax API and walk the AST to find `export const __pathgradeMeta`.
+ * This is critical: evals typically perform real work at module load
+ * (creating agents, hitting LLMs) and running them just to read a static
+ * declaration would defeat the purpose of affected-selection.
+ *
+ * Consequence: the value must be a literal expression. Dynamic composition
+ * (`deps: [...BASE, 'extra']`, spread, computed identifiers) is not supported.
+ * Users needing dedup should codegen the file from a build script.
+ *
+ * Returns `null` when the export is absent. Issue 7 will extend this to
+ * throw on malformed meta (non-array deps, invalid globs, path-escape).
+ */
+import * as fs from 'fs';
+import * as ts from 'typescript';
+import picomatch from 'picomatch';
+/**
+ * Parse `__pathgradeMeta` from an eval file's AST. Returns `null` if the
+ * export is not present.
+ */
+export function parsePathgradeMeta(evalFile) {
+    const source = fs.readFileSync(evalFile, 'utf-8');
+    const sourceFile = ts.createSourceFile(evalFile, source, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, ts.ScriptKind.TS);
+    for (const stmt of sourceFile.statements) {
+        const initializer = findMetaInitializer(stmt);
+        if (initializer) {
+            return extractMeta(initializer, evalFile);
+        }
+    }
+    return null;
+}
+function findMetaInitializer(stmt) {
+    // Match: `export const __pathgradeMeta [: Type] = <expr>`
+    if (!ts.isVariableStatement(stmt))
+        return null;
+    const hasExport = stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!hasExport)
+        return null;
+    for (const decl of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name))
+            continue;
+        if (decl.name.text !== '__pathgradeMeta')
+            continue;
+        if (decl.initializer)
+            return decl.initializer;
+    }
+    return null;
+}
+function extractMeta(expr, evalFile) {
+    // Optionally unwrap a type assertion: `{...} as PathgradeMeta` / `<PathgradeMeta>{...}`.
+    let node = expr;
+    while (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node)) {
+        node = node.expression;
+    }
+    if (!ts.isObjectLiteralExpression(node)) {
+        throw new Error(`${evalFile}: __pathgradeMeta must be an object literal (got ${ts.SyntaxKind[node.kind]}).`);
+    }
+    const meta = {};
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const name = propertyKeyName(prop.name);
+        if (name === 'deps' || name === 'extraDeps') {
+            const globs = extractStringArray(prop.initializer, evalFile, name);
+            for (const g of globs)
+                validateGlob(g, evalFile, name);
+            meta[name] = globs;
+        }
+        else if (name === 'alwaysRun') {
+            meta.alwaysRun = extractBoolean(prop.initializer, evalFile);
+        }
+        // Unknown keys are silently ignored — forward-compatible.
+    }
+    return meta;
+}
+/**
+ * Validate a single glob entry. Catches three classes of error:
+ *   - Path-escape: `../` segments that would match outside the repo root.
+ *   - Unbalanced bracket / brace groups (unclosed `[`, `{` are
+ *     parse-level mistakes that picomatch silently tolerates but that the
+ *     PRD requires us to reject as user-intent errors).
+ *   - Empty string.
+ */
+function validateGlob(glob, evalFile, field) {
+    if (glob.length === 0) {
+        throw new Error(`${evalFile}: __pathgradeMeta.${field} contains an empty glob.`);
+    }
+    if (glob.startsWith('../') || glob.includes('/../') || glob === '..') {
+        throw new Error(`${evalFile}: __pathgradeMeta.${field} entry "${glob}" escapes the repo root — ` +
+            `globs must be repo-root-relative.`);
+    }
+    const brackets = countUnbalanced(glob, '[', ']');
+    const braces = countUnbalanced(glob, '{', '}');
+    if (brackets !== 0 || braces !== 0) {
+        throw new Error(`${evalFile}: __pathgradeMeta.${field} entry "${glob}" has invalid glob syntax ` +
+            `(unbalanced brackets or braces).`);
+    }
+    // Ask picomatch to compile — if it throws, surface the reason.
+    try {
+        picomatch(glob);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`${evalFile}: __pathgradeMeta.${field} entry "${glob}" has invalid glob syntax: ${msg}`);
+    }
+}
+function countUnbalanced(s, open, close) {
+    let depth = 0;
+    let escaped = false;
+    for (const ch of s) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (ch === open)
+            depth++;
+        else if (ch === close)
+            depth--;
+        if (depth < 0)
+            return depth;
+    }
+    return depth;
+}
+function propertyKeyName(name) {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name))
+        return name.text;
+    return null;
+}
+function extractStringArray(expr, evalFile, field) {
+    if (!ts.isArrayLiteralExpression(expr)) {
+        throw new Error(`${evalFile}: __pathgradeMeta.${field} must be an array of strings.`);
+    }
+    const out = [];
+    for (const el of expr.elements) {
+        if (!ts.isStringLiteral(el) && !ts.isNoSubstitutionTemplateLiteral(el)) {
+            throw new Error(`${evalFile}: __pathgradeMeta.${field} entries must be string literals.`);
+        }
+        out.push(el.text);
+    }
+    return out;
+}
+function extractBoolean(expr, evalFile) {
+    if (expr.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (expr.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    throw new Error(`${evalFile}: __pathgradeMeta.alwaysRun must be a boolean literal.`);
+}