agent-threat-rules 2.2.1 → 3.1.0

package/dist/measurement/schema.js

@@ -0,0 +1,178 @@
+/**
+ * src/measurement/schema.ts
+ *
+ * Schema for ATR benchmark measurement files.
+ *
+ * Every public ATR recall / precision / FP-rate claim must reference a
+ * measurement file conforming to this schema. The contract is documented in
+ * `data/measurements/README.md`.
+ *
+ * Design constraints:
+ *   - No external dependencies (no zod, no ajv). Schemas evolve slowly; the
+ *     dependency surface should not.
+ *   - Strict at the boundary. `parseMeasurement()` throws on any deviation;
+ *     it does not silently coerce, drop fields, or accept missing required
+ *     fields.
+ *   - Forward-compatible. `schema_version` is mandatory. Future readers can
+ *     decide how to handle older versions.
+ */
+// ─── Schema version ─────────────────────────────────────────────────────────
+/** Bump this when the schema breaks backward compatibility. */
+export const CURRENT_SCHEMA_VERSION = "1";
+// ─── Validation ─────────────────────────────────────────────────────────────
+/**
+ * Error thrown when a measurement file fails schema validation.
+ * Includes the field path and reason for fast debugging.
+ */
+export class MeasurementSchemaError extends Error {
+    path;
+    reason;
+    constructor(path, reason) {
+        super(`measurement schema: ${path}: ${reason}`);
+        this.path = path;
+        this.reason = reason;
+        this.name = "MeasurementSchemaError";
+    }
+}
+function assertString(v, path, opts) {
+    if (typeof v !== "string") {
+        throw new MeasurementSchemaError(path, `expected string, got ${typeof v}`);
+    }
+    if (opts?.nonEmpty && v.length === 0) {
+        throw new MeasurementSchemaError(path, "expected non-empty string");
+    }
+    return v;
+}
+function assertNumber(v, path, opts) {
+    if (typeof v !== "number" || Number.isNaN(v) || !Number.isFinite(v)) {
+        throw new MeasurementSchemaError(path, `expected finite number, got ${JSON.stringify(v)}`);
+    }
+    if (opts?.integer && !Number.isInteger(v)) {
+        throw new MeasurementSchemaError(path, `expected integer, got ${v}`);
+    }
+    if (opts?.min !== undefined && v < opts.min) {
+        throw new MeasurementSchemaError(path, `expected >= ${opts.min}, got ${v}`);
+    }
+    if (opts?.max !== undefined && v > opts.max) {
+        throw new MeasurementSchemaError(path, `expected <= ${opts.max}, got ${v}`);
+    }
+    return v;
+}
+function assertObject(v, path) {
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new MeasurementSchemaError(path, `expected object, got ${Array.isArray(v) ? "array" : typeof v}`);
+    }
+    return v;
+}
+function parseMetrics(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        recall: assertNumber(obj.recall, `${path}.recall`, { min: 0, max: 1 }),
+        precision: assertNumber(obj.precision, `${path}.precision`, { min: 0, max: 1 }),
+        f1: assertNumber(obj.f1, `${path}.f1`, { min: 0, max: 1 }),
+        fp_rate: assertNumber(obj.fp_rate, `${path}.fp_rate`, { min: 0, max: 1 }),
+    };
+}
+function parseConfusion(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        tp: assertNumber(obj.tp, `${path}.tp`, { min: 0, integer: true }),
+        fp: assertNumber(obj.fp, `${path}.fp`, { min: 0, integer: true }),
+        tn: assertNumber(obj.tn, `${path}.tn`, { min: 0, integer: true }),
+        fn: assertNumber(obj.fn, `${path}.fn`, { min: 0, integer: true }),
+    };
+}
+function parseLatency(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        p50: assertNumber(obj.p50, `${path}.p50`, { min: 0 }),
+        p95: assertNumber(obj.p95, `${path}.p95`, { min: 0 }),
+        p99: assertNumber(obj.p99, `${path}.p99`, { min: 0 }),
+        mean: assertNumber(obj.mean, `${path}.mean`, { min: 0 }),
+        max: assertNumber(obj.max, `${path}.max`, { min: 0 }),
+    };
+}
+const ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const SOURCE_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Parse a `Measurement` from an arbitrary value. Throws `MeasurementSchemaError`
+ * on any deviation from the schema. Returns a strongly-typed `Measurement`.
+ *
+ * Unknown extra top-level keys are allowed but ignored (forward-compat); they
+ * are NOT preserved in the returned object.
+ */
+export function parseMeasurement(raw) {
+    const obj = assertObject(raw, "$");
+    const schema_version = assertString(obj.schema_version, "$.schema_version", { nonEmpty: true });
+    if (schema_version !== CURRENT_SCHEMA_VERSION) {
+        throw new MeasurementSchemaError("$.schema_version", `expected "${CURRENT_SCHEMA_VERSION}", got "${schema_version}" — older formats need migration`);
+    }
+    const source = assertString(obj.source, "$.source", { nonEmpty: true });
+    if (!SOURCE_RE.test(source)) {
+        throw new MeasurementSchemaError("$.source", `must match /^[a-z0-9][a-z0-9-]*$/; got "${source}"`);
+    }
+    const measured_at = assertString(obj.measured_at, "$.measured_at", { nonEmpty: true });
+    if (!ISO8601_RE.test(measured_at)) {
+        throw new MeasurementSchemaError("$.measured_at", `must be ISO 8601 UTC (e.g. "2026-05-23T03:57:58Z"); got "${measured_at}"`);
+    }
+    const m = {
+        schema_version: CURRENT_SCHEMA_VERSION,
+        source,
+        source_version: assertString(obj.source_version, "$.source_version", { nonEmpty: true }),
+        atr_version: assertString(obj.atr_version, "$.atr_version", { nonEmpty: true }),
+        atr_commit: assertString(obj.atr_commit, "$.atr_commit", { nonEmpty: true }),
+        rules_loaded: assertNumber(obj.rules_loaded, "$.rules_loaded", { min: 1, integer: true }),
+        measured_at,
+        samples: assertNumber(obj.samples, "$.samples", { min: 0, integer: true }),
+        metrics: parseMetrics(obj.metrics, "$.metrics"),
+    };
+    if (obj.source_url !== undefined)
+        m.source_url = assertString(obj.source_url, "$.source_url", { nonEmpty: true });
+    if (obj.source_commit !== undefined)
+        m.source_commit = assertString(obj.source_commit, "$.source_commit", { nonEmpty: true });
+    if (obj.confusion !== undefined)
+        m.confusion = parseConfusion(obj.confusion, "$.confusion");
+    if (obj.latency_ms !== undefined)
+        m.latency_ms = parseLatency(obj.latency_ms, "$.latency_ms");
+    if (obj.breakdown !== undefined)
+        m.breakdown = assertObject(obj.breakdown, "$.breakdown");
+    if (obj.notes !== undefined)
+        m.notes = assertString(obj.notes, "$.notes");
+    return m;
+}
+/** Parse a `LatestPointer`. Throws on schema violation. */
+export function parseLatestPointer(raw) {
+    const obj = assertObject(raw, "$");
+    return {
+        source: assertString(obj.source, "$.source", { nonEmpty: true }),
+        file: assertString(obj.file, "$.file", { nonEmpty: true }),
+        measured_at: assertString(obj.measured_at, "$.measured_at", { nonEmpty: true }),
+        metrics: parseMetrics(obj.metrics, "$.metrics"),
+        source_version: assertString(obj.source_version, "$.source_version", { nonEmpty: true }),
+        atr_version: assertString(obj.atr_version, "$.atr_version", { nonEmpty: true }),
+        samples: assertNumber(obj.samples, "$.samples", { min: 0, integer: true }),
+    };
+}
+/**
+ * Compute the canonical filename for a measurement.
+ *
+ * Format: `<YYYY-MM-DD>_<source>-<source_version>_atr-<atr_version>.json`
+ *
+ * `source_version` and `atr_version` are slugified (lowercase, non-alphanumeric
+ * → `-`, leading/trailing `-` removed, collapsed runs of `-`).
+ */
+export function measurementFilename(m) {
+    const date = m.measured_at.slice(0, 10);
+    const sourceSlug = slugify(m.source);
+    const sourceVerSlug = slugify(m.source_version);
+    const atrVerSlug = slugify(m.atr_version);
+    return `${date}_${sourceSlug}-${sourceVerSlug}_atr-${atrVerSlug}.json`;
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+}
+//# sourceMappingURL=schema.js.map

package/dist/measurement/schema.js.map

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

package/dist/measurement/write.d.ts

@@ -0,0 +1,64 @@
+/**
+ * src/measurement/write.ts
+ *
+ * Atomic writer + helpers for ATR benchmark measurement files.
+ *
+ * Used by every eval script. Guarantees:
+ *   - Schema-valid output (calls `parseMeasurement` before write).
+ *   - Atomic write (tmp file + fsync + rename — no half-written files).
+ *   - `latest.json` is updated only after the underlying file is durable on disk.
+ *   - Caller-supplied measurements receive `schema_version`, `measured_at`,
+ *     `atr_version`, `atr_commit`, and `rules_loaded` autofills if omitted.
+ */
+import { type Measurement } from "./schema.js";
+/** Read the ATR version from `package.json`. */
+export declare function readATRVersion(): string;
+/** Read the current short git SHA. Falls back to `"unknown"` outside a git repo. */
+export declare function readATRCommit(): string;
+/** Best-effort: count `ATR-*.yaml` rule files under `rules/`. */
+export declare function countRules(rulesDir?: string): number;
+/**
+ * Caller-friendly subset of `Measurement`. The fields the eval script must
+ * provide; the rest (`schema_version`, `atr_version`, `atr_commit`,
+ * `rules_loaded`, `measured_at`) are autofilled by `writeMeasurement()`.
+ *
+ * Callers MAY override any autofill by setting the field explicitly.
+ */
+export type MeasurementInput = Omit<Measurement, "schema_version" | "measured_at" | "atr_version" | "atr_commit" | "rules_loaded"> & {
+    measured_at?: string;
+    atr_version?: string;
+    atr_commit?: string;
+    rules_loaded?: number;
+};
+/**
+ * Write a measurement file and update the source's `latest.json`.
+ *
+ * Returns the absolute path of the measurement file that was written.
+ *
+ * Behavior:
+ *   1. Autofill `schema_version`, `measured_at` (now, ISO UTC), `atr_version`,
+ *      `atr_commit`, `rules_loaded` if not provided.
+ *   2. Validate via `parseMeasurement()`. Throws on any schema violation.
+ *   3. Compute the canonical filename.
+ *   4. Refuse to overwrite an existing file unless `opts.force` is true. (We
+ *      maintain the append-only invariant by default.)
+ *   5. Atomic write the measurement file.
+ *   6. Update `latest.json` only if the new measurement is strictly newer.
+ *
+ * @param input  Measurement minus the autofilled fields.
+ * @param opts   Options. `force: true` allows overwriting an existing file
+ *               with the same filename (use with caution; breaks append-only).
+ */
+export declare function writeMeasurement(input: MeasurementInput, opts?: {
+    force?: boolean;
+    rulesDir?: string;
+}): {
+    measurementPath: string;
+    latestPath: string;
+    measurement: Measurement;
+};
+/** Resolve the absolute path of a source's `latest.json`. */
+export declare function latestPath(source: string): string;
+/** Absolute path of the measurements root directory. */
+export declare function measurementsDir(): string;
+//# sourceMappingURL=write.d.ts.map

package/dist/measurement/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/measurement/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAGL,KAAK,WAAW,EAIjB,MAAM,aAAa,CAAC;AASrB,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED,oFAAoF;AACpF,wBAAgB,aAAa,IAAI,MAAM,CAStC;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,QAAQ,SAA8B,GAAG,MAAM,CAKzE;AAoDD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,WAAW,EACX,gBAAgB,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,GAAG,cAAc,CACjF,GAAG;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,EACvB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAgD3E;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wDAAwD;AACxD,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/measurement/write.js

@@ -0,0 +1,163 @@
+/**
+ * src/measurement/write.ts
+ *
+ * Atomic writer + helpers for ATR benchmark measurement files.
+ *
+ * Used by every eval script. Guarantees:
+ *   - Schema-valid output (calls `parseMeasurement` before write).
+ *   - Atomic write (tmp file + fsync + rename — no half-written files).
+ *   - `latest.json` is updated only after the underlying file is durable on disk.
+ *   - Caller-supplied measurements receive `schema_version`, `measured_at`,
+ *     `atr_version`, `atr_commit`, and `rules_loaded` autofills if omitted.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { CURRENT_SCHEMA_VERSION, measurementFilename, parseLatestPointer, parseMeasurement, } from "./schema.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, "..", "..");
+const MEASUREMENTS_DIR = resolve(REPO_ROOT, "data", "measurements");
+// ─── Environment auto-detection ─────────────────────────────────────────────
+/** Read the ATR version from `package.json`. */
+export function readATRVersion() {
+    const pkg = JSON.parse(readFileSync(resolve(REPO_ROOT, "package.json"), "utf-8"));
+    if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+        throw new Error("package.json: missing or non-string `version`");
+    }
+    return pkg.version;
+}
+/** Read the current short git SHA. Falls back to `"unknown"` outside a git repo. */
+export function readATRCommit() {
+    try {
+        return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+            cwd: REPO_ROOT,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).toString().trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Best-effort: count `ATR-*.yaml` rule files under `rules/`. */
+export function countRules(rulesDir = resolve(REPO_ROOT, "rules")) {
+    const out = execFileSync("find", [rulesDir, "-name", "ATR-*.yaml"], {
+        stdio: ["ignore", "pipe", "ignore"],
+    }).toString();
+    return out.split("\n").filter((l) => l.trim().length > 0).length;
+}
+// ─── Atomic write primitives ────────────────────────────────────────────────
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * Implementation: write to `<targetPath>.<pid>.<nonce>.tmp`, `fsync()` the file
+ * descriptor, then `rename()` over the target. POSIX `rename(2)` is atomic; if
+ * the process dies between write and rename, the target is untouched and the
+ * tmp file can be cleaned up safely.
+ *
+ * If `fs.renameSync` fails (cross-device EXDEV, permissions), throws.
+ */
+function writeFileAtomic(targetPath, content) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const nonce = Math.random().toString(36).slice(2, 10);
+    const tmpPath = `${targetPath}.${process.pid}.${nonce}.tmp`;
+    const fd = openSync(tmpPath, "w");
+    try {
+        writeSync(fd, content);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmpPath, targetPath);
+}
+// ─── Latest pointer ─────────────────────────────────────────────────────────
+function deriveLatestPointer(m, filename) {
+    return {
+        source: m.source,
+        file: filename,
+        measured_at: m.measured_at,
+        metrics: m.metrics,
+        source_version: m.source_version,
+        atr_version: m.atr_version,
+        samples: m.samples,
+    };
+}
+/**
+ * Decide whether `candidate` is more recent than the existing `latest.json`.
+ * Pure function (no I/O); given two pointer-shaped objects, returns boolean.
+ */
+function isStrictlyNewer(candidate, existing) {
+    return candidate.measured_at > existing.measured_at;
+}
+/**
+ * Write a measurement file and update the source's `latest.json`.
+ *
+ * Returns the absolute path of the measurement file that was written.
+ *
+ * Behavior:
+ *   1. Autofill `schema_version`, `measured_at` (now, ISO UTC), `atr_version`,
+ *      `atr_commit`, `rules_loaded` if not provided.
+ *   2. Validate via `parseMeasurement()`. Throws on any schema violation.
+ *   3. Compute the canonical filename.
+ *   4. Refuse to overwrite an existing file unless `opts.force` is true. (We
+ *      maintain the append-only invariant by default.)
+ *   5. Atomic write the measurement file.
+ *   6. Update `latest.json` only if the new measurement is strictly newer.
+ *
+ * @param input  Measurement minus the autofilled fields.
+ * @param opts   Options. `force: true` allows overwriting an existing file
+ *               with the same filename (use with caution; breaks append-only).
+ */
+export function writeMeasurement(input, opts = {}) {
+    const measured_at = input.measured_at ?? new Date().toISOString();
+    const atr_version = input.atr_version ?? readATRVersion();
+    const atr_commit = input.atr_commit ?? readATRCommit();
+    const rules_loaded = input.rules_loaded ?? countRules(opts.rulesDir);
+    const measurement = parseMeasurement({
+        schema_version: CURRENT_SCHEMA_VERSION,
+        ...input,
+        measured_at,
+        atr_version,
+        atr_commit,
+        rules_loaded,
+    });
+    const sourceDir = join(MEASUREMENTS_DIR, measurement.source);
+    const filename = measurementFilename(measurement);
+    const measurementPath = join(sourceDir, filename);
+    const latestPath = join(sourceDir, "latest.json");
+    if (existsSync(measurementPath) && !opts.force) {
+        throw new Error(`measurement already exists: ${measurementPath}\n` +
+            `Re-running the same (source, source_version, atr_version) on the same day produces the same filename.\n` +
+            `Pass { force: true } to overwrite, or change one of the inputs.`);
+    }
+    const measurementJson = JSON.stringify(measurement, null, 2) + "\n";
+    writeFileAtomic(measurementPath, measurementJson);
+    // Update latest.json only if strictly newer than the existing pointer.
+    const newPointer = deriveLatestPointer(measurement, filename);
+    let shouldWriteLatest = true;
+    if (existsSync(latestPath)) {
+        try {
+            const existing = parseLatestPointer(JSON.parse(readFileSync(latestPath, "utf-8")));
+            shouldWriteLatest = isStrictlyNewer(newPointer, existing);
+        }
+        catch {
+            // Corrupt or missing latest.json — overwrite it.
+            shouldWriteLatest = true;
+        }
+    }
+    if (shouldWriteLatest) {
+        writeFileAtomic(latestPath, JSON.stringify(newPointer, null, 2) + "\n");
+    }
+    return { measurementPath, latestPath, measurement };
+}
+/** Resolve the absolute path of a source's `latest.json`. */
+export function latestPath(source) {
+    return join(MEASUREMENTS_DIR, source, "latest.json");
+}
+/** Absolute path of the measurements root directory. */
+export function measurementsDir() {
+    return MEASUREMENTS_DIR;
+}
+//# sourceMappingURL=write.js.map

package/dist/measurement/write.js.map

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

package/dist/rule-scaffolder.d.ts

@@ -3,15 +3,34 @@
  * @module agent-threat-rules/rule-scaffolder
  */
 import type { ATRCategory, ATRSeverity, ATRSourceType } from './types.js';
+export type ScaffoldDetectionMethod = 'pattern' | 'semantic';
+export interface SemanticScaffoldOptions {
+    threshold?: number;
+    fallbackMethod?: 'pattern' | 'none';
+    judgeModelClass?: string;
+    includePatternFallback?: boolean;
+}
+export interface ScaffoldEvasionTestInput {
+    input: string;
+    expected?: 'triggered' | 'not_triggered';
+    bypass_technique: string;
+    notes?: string;
+}
 export interface ScaffoldInput {
     title: string;
     category: ATRCategory;
     severity?: ATRSeverity;
     attackDescription: string;
+    notDetectedDescription?: string;
     examplePayloads: string[];
+    negativePayloads?: string[];
+    evasionTests?: ScaffoldEvasionTestInput[];
+    falsePositiveScenarios?: string[];
     agentSourceType?: ATRSourceType;
     owaspRefs?: string[];
     mitreRefs?: string[];
+    detectionMethod?: ScaffoldDetectionMethod;
+    semantic?: SemanticScaffoldOptions;
 }
 export interface ScaffoldResult {
     yaml: string;
@@ -44,6 +63,13 @@ export declare class RuleScaffolder {
      * Returns a ScaffoldResult with the YAML string, generated ID, and any warnings.
      */
     scaffold(input: ScaffoldInput, existingIds?: ReadonlySet<string>): ScaffoldResult;
+    /**
+     * Generate a draft semantic ATR YAML rule from structured examples.
+     *
+     * This is deterministic template generation, not model-authored production
+     * rule creation. Generated semantic rules are intentionally draft artifacts.
+     */
+    scaffoldSemantic(input: ScaffoldInput, existingIds?: ReadonlySet<string>): ScaffoldResult;
     /**
      * Validate scaffold input, throwing on invalid required fields
      * and returning warnings for non-critical issues.

package/dist/rule-scaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-scaffolder.d.ts","sourceRoot":"","sources":["../src/rule-scaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwCD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C,CAqFA,CAAC;AAsEF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,GAAE,eAAoB;IAOzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,cAAc;IAwF5F;;;OAGG;IACH,OAAO,CAAC,aAAa;CAwBtB"}
+{"version":3,"file":"rule-scaffolder.d.ts","sourceRoot":"","sources":["../src/rule-scaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,WAAW,GAAG,eAAe,CAAC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAC1C,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwCD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C,CAqFA,CAAC;AAsJF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,GAAE,eAAoB;IAOzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,cAAc;IAiG5F;;;;;OAKG;IACH,gBAAgB,CACd,KAAK,EAAE,aAAa,EACpB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,cAAc;IA+JjB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAwBtB"}