@prompt-lint/rules 1.0.0

package/dist/helpers/pii.js

@@ -0,0 +1,36 @@
+import { findAllMatches } from "./regex.js";
+/**
+ * Patterns for detecting personally-identifiable information (PII) inside
+ * prompt bodies. The rule fires once per **unique kind** of detection
+ * (e.g. one `email`, one `phone`) so the configured severity is not
+ * multiplied by repetition in tests.
+ *
+ * Each pattern uses non-greedy matching with unicode-aware boundaries.
+ * URLs containing PII (e.g. `mailto:` links) intentionally still match
+ * because the rule targets raw payload bytes, not transport.
+ *
+ * Each pattern is exposed via {@link PII_PATTERNS} so reporters can
+ * surface the matched pattern type in the message.
+ */
+export const PII_PATTERNS = {
+    email: /[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/gu,
+    phone: /(?:\+?\d{1,3}[\s.\-]?)?\(?\d{3}\)?[\s.\-]?\d{3}[\s.\-]?\d{4}/g,
+    ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
+    creditCard: /\b(?:\d[ -]?){13,16}\b/g,
+};
+/**
+ * Detect all PII matches in `body`. Returns one entry per pattern kind.
+ * Duplicate matches of the same kind are kept so the rule implementation
+ * can decide whether to dedupe.
+ */
+export function detectPiiMatches(body) {
+    const matches = [];
+    for (const kind of Object.keys(PII_PATTERNS)) {
+        const pattern = PII_PATTERNS[kind];
+        for (const m of findAllMatches(pattern, body)) {
+            matches.push({ ...m, kind });
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=pii.js.map

package/dist/helpers/pii.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.js","sourceRoot":"","sources":["../../src/helpers/pii.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,oDAAoD;IAC3D,KAAK,EAAE,+DAA+D;IACtE,GAAG,EAAE,wBAAwB;IAC7B,UAAU,EAAE,yBAAyB;CAC7B,CAAA;AAQV;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,OAAO,GAAe,EAAE,CAAA;IAC9B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAc,EAAE,CAAC;QAC1D,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QAClC,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YAC9C,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/helpers/regex.d.ts

@@ -0,0 +1,53 @@
+import type { SourceLocation } from "@prompt-lint/types";
+/**
+ * Lightweight regex utilities used by security and quality rules. Each
+ * helper is deterministic and rejects multi-line scans to keep the
+ * resulting locations accurate.
+ *
+ * Source-location computation uses the same 1-indexed line/column
+ * convention as `@prompt-lint/parser`.
+ */
+export interface RegexMatch {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly location: SourceLocation;
+}
+/**
+ * Build a fresh global regex from `pattern` and `flags`. This helper
+ * guarantees a new `RegExp` instance every time so callers never hold
+ * onto a shared `lastIndex` cursor.
+ */
+export declare function compileWordPattern(pattern: string, flags?: string): RegExp;
+/**
+ * Build a whole-word-aware regex from the provided identifier list. The
+ * match is wrapped with `\b` word boundaries using ASCII-only matching
+ * (`\b` ASCII implementation) and uses the unicode flag so non-ASCII
+ * identifiers can be detected when callers pass them.
+ *
+ * The pattern is anchored loosely: callers decide whether to wrap the
+ * result with `^` or `$`.
+ */
+export declare function compileWordRegex(words: readonly string[], flags?: string): RegExp;
+/**
+ * Escape a literal string for safe inclusion in a `RegExp` pattern.
+ */
+export declare function escapeRegex(value: string): string;
+/**
+ * Run a regex against `body` and emit deterministic
+ * `{ start, end, text, location }` matches in source order.
+ *
+ * If the supplied regex does not carry the `g` flag, this helper wraps
+ * a clone that does. Use this for every "find all" path so callers do
+ * not have to remember the global requirement of `String.matchAll`.
+ */
+export declare function findAllMatches(regex: RegExp, body: string): readonly RegexMatch[];
+/**
+ * Compute the 1-indexed `SourceLocation` covering `body[start..end)`.
+ *
+ * If `body` ends with a newline at `end`, the returned `endColumn` is
+ * `1` — the start of the next line — to match the LSP convention used
+ * by `@prompt-lint/parser`.
+ */
+export declare function locationForRange(body: string, start: number, end: number): SourceLocation;
+//# sourceMappingURL=regex.d.ts.map

package/dist/helpers/regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/helpers/regex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAO,GAAG,MAAM,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,SAAO,GAAG,MAAM,CAK/E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,UAAU,EAAE,CAiBjF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAgBzF"}

package/dist/helpers/regex.js

@@ -0,0 +1,79 @@
+/**
+ * Build a fresh global regex from `pattern` and `flags`. This helper
+ * guarantees a new `RegExp` instance every time so callers never hold
+ * onto a shared `lastIndex` cursor.
+ */
+export function compileWordPattern(pattern, flags = "gu") {
+    return new RegExp(pattern, flags);
+}
+/**
+ * Build a whole-word-aware regex from the provided identifier list. The
+ * match is wrapped with `\b` word boundaries using ASCII-only matching
+ * (`\b` ASCII implementation) and uses the unicode flag so non-ASCII
+ * identifiers can be detected when callers pass them.
+ *
+ * The pattern is anchored loosely: callers decide whether to wrap the
+ * result with `^` or `$`.
+ */
+export function compileWordRegex(words, flags = "gu") {
+    const sorted = [...words].sort((a, b) => b.length - a.length);
+    const escaped = sorted.map(escapeRegex);
+    const body = escaped.map((w) => `\\b${w}\\b`).join("|");
+    return new RegExp(body, flags);
+}
+/**
+ * Escape a literal string for safe inclusion in a `RegExp` pattern.
+ */
+export function escapeRegex(value) {
+    return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+}
+/**
+ * Run a regex against `body` and emit deterministic
+ * `{ start, end, text, location }` matches in source order.
+ *
+ * If the supplied regex does not carry the `g` flag, this helper wraps
+ * a clone that does. Use this for every "find all" path so callers do
+ * not have to remember the global requirement of `String.matchAll`.
+ */
+export function findAllMatches(regex, body) {
+    const flags = regex.flags.includes("g") ? regex.flags : `${regex.flags}g`;
+    const pattern = new RegExp(regex.source, flags);
+    pattern.lastIndex = 0;
+    const out = [];
+    for (const match of body.matchAll(pattern)) {
+        const text = match[0] ?? "";
+        const start = match.index ?? 0;
+        const end = start + text.length;
+        out.push({
+            start,
+            end,
+            text,
+            location: locationForRange(body, start, end),
+        });
+    }
+    return out;
+}
+/**
+ * Compute the 1-indexed `SourceLocation` covering `body[start..end)`.
+ *
+ * If `body` ends with a newline at `end`, the returned `endColumn` is
+ * `1` — the start of the next line — to match the LSP convention used
+ * by `@prompt-lint/parser`.
+ */
+export function locationForRange(body, start, end) {
+    const before = body.slice(0, start);
+    const beforeLines = before.split("\n");
+    const startLine = beforeLines.length;
+    const startColumn = (beforeLines[beforeLines.length - 1]?.length ?? 0) + 1;
+    const span = body.slice(start, end);
+    const spanLines = span.split("\n");
+    const endLine = startLine + spanLines.length - 1;
+    let endColumn = spanLines[spanLines.length - 1]?.length ?? 0;
+    if (span.includes("\n") && endColumn === 0) {
+        endColumn = 1;
+    }
+    if (endColumn === 0)
+        endColumn = 1;
+    return { line: startLine, column: startColumn, endLine, endColumn };
+}
+//# sourceMappingURL=regex.js.map

package/dist/helpers/regex.js.map

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

package/dist/helpers/structured-data.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Phrase vocabulary used to detect whether a prompt requests structured
+ * output (JSON, YAML, tables, etc.) without a corresponding schema
+ * declaration in frontmatter.
+ *
+ * The check is intentionally permissive: any natural-language signal
+ * that the user expects a structured response triggers the rule. Only
+ * the rule implementation decides whether the prompt qualifies for a
+ * finding — see {@link hasStructuredDataKeyword}.
+ */
+export declare const STRUCTURED_DATA_KEYWORDS: readonly string[];
+/**
+ * Return `true` if `body` contains any signal that the prompt
+ * requests structured output. Matching is case-insensitive and
+ * uses ASCII word boundaries; multi-word phrases are matched as a
+ * longest-first sequence.
+ */
+export declare function hasStructuredDataKeyword(body: string): boolean;
+//# sourceMappingURL=structured-data.d.ts.map

package/dist/helpers/structured-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-data.d.ts","sourceRoot":"","sources":["../../src/helpers/structured-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EA0CpD,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAW9D"}

package/dist/helpers/structured-data.js

@@ -0,0 +1,72 @@
+/**
+ * Phrase vocabulary used to detect whether a prompt requests structured
+ * output (JSON, YAML, tables, etc.) without a corresponding schema
+ * declaration in frontmatter.
+ *
+ * The check is intentionally permissive: any natural-language signal
+ * that the user expects a structured response triggers the rule. Only
+ * the rule implementation decides whether the prompt qualifies for a
+ * finding — see {@link hasStructuredDataKeyword}.
+ */
+export const STRUCTURED_DATA_KEYWORDS = Object.freeze([
+    "json",
+    "json object",
+    "json array",
+    "json schema",
+    "json-schema",
+    "yaml",
+    "toml",
+    "csv",
+    "table",
+    "markdown table",
+    "structured output",
+    "structured response",
+    "structured format",
+    "structured form",
+    "structured data",
+    "with fields",
+    "as an object",
+    "as a json",
+    "as json",
+    "as a csv",
+    "as csv",
+    "as an array",
+    "as a list",
+    "as a table",
+    "list of",
+    "array of",
+    "schema",
+    "jsonobject",
+    "jsonresponse",
+    "respond with json",
+    "respond in json",
+    "reply with json",
+    "reply in json",
+    "return json",
+    "return as json",
+    "return a json",
+    "return a yaml",
+    "return as yaml",
+    "return yaml",
+    "fields:",
+    "properties:",
+]);
+/**
+ * Return `true` if `body` contains any signal that the prompt
+ * requests structured output. Matching is case-insensitive and
+ * uses ASCII word boundaries; multi-word phrases are matched as a
+ * longest-first sequence.
+ */
+export function hasStructuredDataKeyword(body) {
+    const lowerBody = body.toLowerCase();
+    const sorted = [...STRUCTURED_DATA_KEYWORDS].sort((a, b) => b.length - a.length);
+    for (const phrase of sorted) {
+        const escaped = phrase.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+        const re = new RegExp(`(?:^|[^a-z0-9])${escaped}(?:[^a-z0-9]|$)`, "u");
+        if (re.test(lowerBody)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=structured-data.js.map

package/dist/helpers/structured-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-data.js","sourceRoot":"","sources":["../../src/helpers/structured-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACvE,MAAM;IACN,aAAa;IACb,YAAY;IACZ,aAAa;IACb,aAAa;IACb,MAAM;IACN,MAAM;IACN,KAAK;IACL,OAAO;IACP,gBAAgB;IAChB,mBAAmB;IACnB,qBAAqB;IACrB,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,aAAa;IACb,cAAc;IACd,WAAW;IACX,SAAS;IACT,UAAU;IACV,QAAQ;IACR,aAAa;IACb,WAAW;IACX,YAAY;IACZ,SAAS;IACT,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,cAAc;IACd,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,aAAa;IACb,SAAS;IACT,aAAa;CACd,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IACpC,MAAM,MAAM,GAAG,CAAC,GAAG,wBAAwB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;IAChF,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;QAC7D,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,kBAAkB,OAAO,iBAAiB,EAAE,GAAG,CAAC,CAAA;QACtE,IAAI,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/helpers/tokens.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token estimation.
+ *
+ * `estimateTokens` is intentionally simple: it approximates the count
+ * Claude-family models produce for English-heavy natural language. The
+ * heuristic splits on whitespace, then applies a per-token ratio that
+ * accounts for the fact that whitespace-delimited words frequently split
+ * into multiple tokens at subword boundaries.
+ *
+ * The function is pure, deterministic, and operates on a string that may
+ * contain unicode characters. It is designed to be sufficient for V1
+ * budget enforcement — not to replace a model-specific tokenizer.
+ */
+/**
+ * Estimate the number of tokens produced by `body`.
+ *
+ * Empty or whitespace-only inputs return `0`. Inputs that contain no
+ * alphanumeric characters return `1` because the engine still has to
+ * transmit at least the placeholder token.
+ *
+ * @example
+ *   estimateTokens("Hello, world!")          // ~3
+ *   estimateTokens("The quick brown fox")   // ~4
+ */
+export declare function estimateTokens(body: string): number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/helpers/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/helpers/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsCnD"}

package/dist/helpers/tokens.js

@@ -0,0 +1,63 @@
+/**
+ * Token estimation.
+ *
+ * `estimateTokens` is intentionally simple: it approximates the count
+ * Claude-family models produce for English-heavy natural language. The
+ * heuristic splits on whitespace, then applies a per-token ratio that
+ * accounts for the fact that whitespace-delimited words frequently split
+ * into multiple tokens at subword boundaries.
+ *
+ * The function is pure, deterministic, and operates on a string that may
+ * contain unicode characters. It is designed to be sufficient for V1
+ * budget enforcement — not to replace a model-specific tokenizer.
+ */
+const AVERAGE_CHARS_PER_TOKEN = 4;
+/**
+ * Estimate the number of tokens produced by `body`.
+ *
+ * Empty or whitespace-only inputs return `0`. Inputs that contain no
+ * alphanumeric characters return `1` because the engine still has to
+ * transmit at least the placeholder token.
+ *
+ * @example
+ *   estimateTokens("Hello, world!")          // ~3
+ *   estimateTokens("The quick brown fox")   // ~4
+ */
+export function estimateTokens(body) {
+    if (body.length === 0)
+        return 0;
+    const trimmed = body.trim();
+    if (trimmed.length === 0)
+        return 0;
+    let hasAlphanumeric = false;
+    let letterCount = 0;
+    for (let i = 0; i < body.length; i += 1) {
+        const code = body.charCodeAt(i);
+        if (
+        // ASCII digits
+        (code >= 0x30 && code <= 0x39) ||
+            // ASCII letters
+            (code >= 0x41 && code <= 0x5a) ||
+            (code >= 0x61 && code <= 0x7a) ||
+            // Latin-1 supplement letters
+            (code >= 0xc0 && code <= 0xff && code !== 0xd7 && code !== 0xf7) ||
+            // Latin Extended A
+            (code >= 0x100 && code <= 0x17f) ||
+            // Cyrillic block
+            (code >= 0x400 && code <= 0x4ff) ||
+            // Greek block
+            (code >= 0x370 && code <= 0x3ff) ||
+            // CJK ideographs (partial — covers BMP core)
+            (code >= 0x4e00 && code <= 0x9fff) ||
+            // Hiragana / Katakana
+            (code >= 0x3040 && code <= 0x30ff)) {
+            hasAlphanumeric = true;
+            letterCount += 1;
+        }
+    }
+    if (!hasAlphanumeric)
+        return 1;
+    const approx = Math.max(1, Math.ceil(letterCount / AVERAGE_CHARS_PER_TOKEN));
+    return approx;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/helpers/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/helpers/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAE/B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAElC,IAAI,eAAe,GAAG,KAAK,CAAA;IAC3B,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QAC/B;QACE,eAAe;QACf,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC;YAC9B,gBAAgB;YAChB,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC;YAC9B,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC;YAC9B,6BAA6B;YAC7B,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC;YAChE,mBAAmB;YACnB,CAAC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC;YAChC,iBAAiB;YACjB,CAAC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC;YAChC,cAAc;YACd,CAAC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC;YAChC,6CAA6C;YAC7C,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC;YAClC,sBAAsB;YACtB,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,EAClC,CAAC;YACD,eAAe,GAAG,IAAI,CAAA;YACtB,WAAW,IAAI,CAAC,CAAA;QAClB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,eAAe;QAAE,OAAO,CAAC,CAAA;IAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,uBAAuB,CAAC,CAAC,CAAA;IAC5E,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/helpers/vague-quantifiers.d.ts

@@ -0,0 +1,20 @@
+import type { RegexMatch } from "./regex.js";
+/**
+ * Vague quantifier vocabulary.
+ *
+ * The list captures the canonical patterns the V1 docs cite ("a few",
+ * "various", "etc.", "and so on") plus additional phrases whose
+ * cardinality is genuinely ambiguous when authoring prompts. A test
+ * corpus Appendix in the README enumerates the exact list.
+ */
+export declare const VAGUE_QUANTIFIER_TERMS: readonly string[];
+export interface VagueQuantifierMatch extends RegexMatch {
+    readonly term: string;
+}
+/**
+ * Scan `body` for vague-quantifier phrasing. The term associated with
+ * each match is normalized (lower-case, trimmed) so callers can group
+ * duplicates deterministically.
+ */
+export declare function findVagueQuantifierMatches(body: string): readonly VagueQuantifierMatch[];
+//# sourceMappingURL=vague-quantifiers.d.ts.map

package/dist/helpers/vague-quantifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vague-quantifiers.d.ts","sourceRoot":"","sources":["../../src/helpers/vague-quantifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAG5C;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAuClD,CAAA;AAqBF,MAAM,WAAW,oBAAqB,SAAQ,UAAU;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,oBAAoB,EAAE,CAUxF"}

package/dist/helpers/vague-quantifiers.js

@@ -0,0 +1,83 @@
+import { findAllMatches } from "./regex.js";
+/**
+ * Vague quantifier vocabulary.
+ *
+ * The list captures the canonical patterns the V1 docs cite ("a few",
+ * "various", "etc.", "and so on") plus additional phrases whose
+ * cardinality is genuinely ambiguous when authoring prompts. A test
+ * corpus Appendix in the README enumerates the exact list.
+ */
+export const VAGUE_QUANTIFIER_TERMS = Object.freeze([
+    "a few",
+    "a couple of",
+    "a couple",
+    "various",
+    "various kinds of",
+    "various types of",
+    "various things",
+    "several",
+    "some",
+    "some kind of",
+    "some sort of",
+    "some number of",
+    "many",
+    "many things",
+    "lots of",
+    "lots",
+    "dozens of",
+    "dozens",
+    "a bunch of",
+    "a bunch",
+    "etc",
+    "etc.",
+    "and so on",
+    "and so forth",
+    "and others",
+    "and the like",
+    "and more",
+    "such as",
+    "for example",
+    "e.g.",
+    "i.e.",
+    "or something",
+    "or something like that",
+    "or so",
+    "things like that",
+    "stuff like that",
+    "whatnot",
+    "yada yada",
+]);
+/**
+ * Build the regex used to match vague quantifier phrases. Longer terms
+ * are matched first to ensure that "various kinds of" wins over
+ * "various", and term boundaries use the ASCII word boundary `\b`.
+ *
+ * Special characters in terms (`.`, `?`, etc.) are escaped before
+ * inclusion in the alternation.
+ */
+function buildVagueQuantifierRegex() {
+    const sorted = [...VAGUE_QUANTIFIER_TERMS].sort((a, b) => b.length - a.length);
+    const escaped = sorted.map((term) => {
+        const escapedTerm = term.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+        return `\\b${escapedTerm}\\b`;
+    });
+    return new RegExp(`(?:${escaped.join("|")})`, "giu");
+}
+const VAGUE_QUANTIFIER_REGEX = buildVagueQuantifierRegex();
+/**
+ * Scan `body` for vague-quantifier phrasing. The term associated with
+ * each match is normalized (lower-case, trimmed) so callers can group
+ * duplicates deterministically.
+ */
+export function findVagueQuantifierMatches(body) {
+    const out = [];
+    for (const m of findAllMatches(VAGUE_QUANTIFIER_REGEX, body)) {
+        const term = m.text
+            .trim()
+            .toLowerCase()
+            .replace(/[.,;:!?]+$/u, "");
+        out.push({ ...m, term });
+    }
+    return out;
+}
+//# sourceMappingURL=vague-quantifiers.js.map

package/dist/helpers/vague-quantifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vague-quantifiers.js","sourceRoot":"","sources":["../../src/helpers/vague-quantifiers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,OAAO;IACP,aAAa;IACb,UAAU;IACV,SAAS;IACT,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;IAChB,SAAS;IACT,MAAM;IACN,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,MAAM;IACN,aAAa;IACb,SAAS;IACT,MAAM;IACN,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,SAAS;IACT,KAAK;IACL,MAAM;IACN,WAAW;IACX,cAAc;IACd,YAAY;IACZ,cAAc;IACd,UAAU;IACV,SAAS;IACT,aAAa;IACb,MAAM;IACN,MAAM;IACN,cAAc;IACd,wBAAwB;IACxB,OAAO;IACP,kBAAkB;IAClB,iBAAiB;IACjB,SAAS;IACT,WAAW;CACZ,CAAC,CAAA;AAEF;;;;;;;GAOG;AACH,SAAS,yBAAyB;IAChC,MAAM,MAAM,GAAG,CAAC,GAAG,sBAAsB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;IAC9E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAClC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;QAC/D,OAAO,MAAM,WAAW,KAAK,CAAA;IAC/B,CAAC,CAAC,CAAA;IACF,OAAO,IAAI,MAAM,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AACtD,CAAC;AAED,MAAM,sBAAsB,GAAG,yBAAyB,EAAE,CAAA;AAM1D;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,sBAAsB,EAAE,IAAI,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI;aAChB,IAAI,EAAE;aACN,WAAW,EAAE;aACb,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;QAC7B,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/helpers/variables.d.ts

@@ -0,0 +1,36 @@
+import type { PromptFile, SourceLocation } from "@prompt-lint/types";
+/**
+ * Variable inspection helpers used by the `structure/unused-variable` and
+ * `structure/undefined-variable` rules.
+ *
+ * The parser already produces `{ name, locations }` groups via
+ * `@prompt-lint/parser`. We re-expose the underlying data here in stable
+ * helpers so rule implementations do not have to touch the parser types
+ * directly.
+ */
+export interface VariableReference {
+    readonly name: string;
+    readonly firstLocation: SourceLocation;
+}
+/**
+ * Return the set of variable names declared in the frontmatter `variables`
+ * array. Names that do not satisfy the parser's identifier rules are
+ * skipped silently — the parser already surfaces a frontmatter error for
+ * those, and re-flagging them here would create duplicate findings.
+ */
+export declare function collectDeclaredVariables(file: PromptFile): readonly string[];
+/**
+ * Return every `{{ var }}` occurrence in the prompt body, in source order,
+ * with deduplicated variable names. The first reported location per name
+ * is the first one the parser recorded.
+ */
+export declare function collectBodyVariables(file: PromptFile): readonly VariableReference[];
+/**
+ * Test whether `name` is referenced anywhere in the parsed `PromptFile`.
+ */
+export declare function findVariableOccurrences(file: PromptFile, name: string): readonly SourceLocation[];
+/**
+ * Convenience: declare-detection with case-sensitive semantics.
+ */
+export declare function isVariableMissing(file: PromptFile, name: string): boolean;
+//# sourceMappingURL=variables.d.ts.map

package/dist/helpers/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/helpers/variables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEpE;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAA;CACvC;AAID;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAY5E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAiBnF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAKjG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzE"}

package/dist/helpers/variables.js

@@ -0,0 +1,66 @@
+const FRONTMATTER_VARIABLE_NAME = /^[a-zA-Z_][a-zA-Z0-9_.\-]*$/;
+/**
+ * Return the set of variable names declared in the frontmatter `variables`
+ * array. Names that do not satisfy the parser's identifier rules are
+ * skipped silently — the parser already surfaces a frontmatter error for
+ * those, and re-flagging them here would create duplicate findings.
+ */
+export function collectDeclaredVariables(file) {
+    const declared = file.frontmatter.variables;
+    if (declared === undefined)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const name of declared) {
+        if (!FRONTMATTER_VARIABLE_NAME.test(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+/**
+ * Return every `{{ var }}` occurrence in the prompt body, in source order,
+ * with deduplicated variable names. The first reported location per name
+ * is the first one the parser recorded.
+ */
+export function collectBodyVariables(file) {
+    const seen = new Set();
+    const out = [];
+    for (const variable of file.variables) {
+        if (seen.has(variable.name))
+            continue;
+        seen.add(variable.name);
+        const first = variable.locations[0];
+        if (first !== undefined) {
+            out.push({ name: variable.name, firstLocation: first });
+        }
+        else {
+            out.push({
+                name: variable.name,
+                firstLocation: { line: 1, column: 1, endLine: 1, endColumn: 1 },
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Test whether `name` is referenced anywhere in the parsed `PromptFile`.
+ */
+export function findVariableOccurrences(file, name) {
+    for (const variable of file.variables) {
+        if (variable.name === name)
+            return variable.locations;
+    }
+    return [];
+}
+/**
+ * Convenience: declare-detection with case-sensitive semantics.
+ */
+export function isVariableMissing(file, name) {
+    const declared = collectDeclaredVariables(file);
+    return !declared.includes(name);
+}
+//# sourceMappingURL=variables.js.map

package/dist/helpers/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../src/helpers/variables.ts"],"names":[],"mappings":"AAiBA,MAAM,yBAAyB,GAAG,6BAA6B,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAgB;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,SAAS,CAAA;IAC3C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAQ;QACnD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACd,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACnD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,GAAG,GAAwB,EAAE,CAAA;IACnC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAQ;QACrC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAA;QACzD,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;aAChE,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAgB,EAAE,IAAY;IACpE,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACtC,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC,SAAS,CAAA;IACvD,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAgB,EAAE,IAAY;IAC9D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAA;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC"}