@jjchill/probity-rules 0.1.0

package/dist/rules/acceptance-language.js

@@ -0,0 +1,443 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const DEFAULT_MAX_GLOSSARY_CHARS = 8000;
+const STRICT_VOCABULARY = `### Vocabulary — strict mode (overrides the leniency above)
+
+This project enforces "the glossary conversation happens first": when
+a glossary is provided, spec content that introduces a domain concept
+with NO glossary entry IS a violation. Name the missing term(s) in
+the reason so the entry can be added before the spec lands. Judge
+concepts, not words — articles, generic verbs, and quantities need no
+entry; nouns that carry domain meaning do.
+
+`;
+// reason comes FIRST in the shape: an autoregressive model commits to
+// each field in order, so kind-first forces the verdict before the
+// analysis — observed live producing a "violation" whose reason
+// reasoned its way to "Passing." Reason-first lets the model conclude,
+// then label.
+const RESPONSE_SPEC = `## Response format
+
+Respond with a single JSON object of exactly this shape:
+{"reason":"<your analysis>","kind":"pass"|"violation"}
+Write reason FIRST and set kind to the conclusion your reason reached —
+the two must agree. Keep reason brief on a clear pass ("" is fine).
+Return JSON only. No prose, no code fences.`;
+const PROCESS_INSTRUCTIONS = `## Role
+
+You are an acceptance-specification validator. Judge whether the
+pending write keeps executable specifications in the language of the
+problem domain, per the rules below.
+
+## Inputs
+
+You will see up to four inputs:
+
+1. "Ubiquitous language glossary" (optional) — the project's agreed
+   domain vocabulary.
+2. "Current file content" — what's on disk right now at the file the
+   agent is about to write. May be a parenthesized marker (e.g.
+   \`(file does not exist)\`).
+3. "Pending action" — the file path and what the agent is about to
+   write. Content may be raw file text or a patch/diff.
+
+## What you judge
+
+Judge only the specification content this write adds or changes, not
+pre-existing text it leaves untouched. This rule is scoped to
+specification files (layer 1 of the four-layer model). If the file is
+clearly NOT a test-case layer — it is a DSL implementation, a protocol
+driver, a step-definition file that only parses and delegates, or
+plain production code — pass: those layers are supposed to know about
+UI mechanics and protocols.
+
+A transient file state (unresolved import, half-finished scenario) is
+never itself a violation.
+
+A block recorded earlier in the session is a past verdict, not a rule.
+Re-derive your judgment from the rules below. When the user tells you
+in the session to let this change through, treat it as authoritative
+and pass.`;
+const DEFAULT_LANGUAGE_RULES = `## Specification language rules
+
+An acceptance test is an executable specification: a concrete example,
+in the language of the problem domain, that demonstrates a user's need
+is met. It states WHAT the system does for an external user and says
+nothing about HOW the system works.
+
+### The Language Test
+
+The least technical person who understands the problem domain must be
+able to read the specification and confirm it says what they want.
+Block spec content that mentions implementation mechanics:
+
+  - UI mechanics: clicking, typing into fields, pages, screens,
+    buttons, menus, CSS selectors, element IDs, XPath
+  - Protocol mechanics: URLs, endpoints, HTTP verbs, status codes,
+    JSON/XML payloads, headers, cookies
+  - Persistence mechanics: tables, rows, columns, SQL, cache keys
+  - Named internal services, queues, or modules
+
+The fix is always the same: state the outcome in domain terms and push
+the mechanics down into the DSL or a protocol driver.
+
+### One standard across artifacts
+
+A Markdown/Gherkin scenario and the test case that claims it are both
+layer 1 and are held to the SAME standard: wording that would violate
+in a test-case step ("the backend rejects creation") violates in a
+\`## Scenario:\` step too, and vice versa. Never pass mechanism
+language in a spec document on the grounds that it is prose — the
+spec is the source that tests transcribe, so a leak passed there
+resurfaces in every claiming test. Named internal actors — "the
+backend", "the server", "the gateway", "the database", "the API",
+"a queue", "the store" — are mechanism unless the glossary records
+them as domain concepts: state the condition as the user experiences
+it ("creation fails", "the parcel cannot be registered right now")
+and push what failed and why into the DSL, driver, or stub
+programming.
+
+### Structure
+
+  - Each specification asserts a single outcome. Block scenarios with
+    long When/Then chains asserting many unrelated outcomes.
+  - Express specifications as outcomes ("should ...", "is granted
+    access"), not procedures.
+  - No sleeps or fixed waits in specs — a delay is a race condition
+    with a timer on it; drivers poll for the concluding event.
+  - Test-case code talks only to the DSL. Block spec-layer code that
+    reaches the system directly (HTTP clients, page objects, database
+    handles imported into the spec file).
+
+### Vocabulary
+
+When a glossary is provided, use its terms verbatim — one term per
+concept. Block spec content that names a domain concept with a term
+that conflicts with the glossary (a synonym or a redefinition). A
+concept the glossary simply doesn't cover yet is NOT a violation on
+its own; mention it in the reason only alongside a real violation.
+
+%STRICT_VOCABULARY%### Judgment bar
+
+Block on clear mechanics leaking into a specification. Domain terms
+that happen to sound technical (the domain of a deployment tool
+includes "server"; a payments domain includes "card") are not
+violations — judge against the problem domain, not a banned-word list.
+Grammatical tense and phrasing preferences are not mechanism: a
+future- or conditional-tense precondition ("creation will fail",
+"the parcel is going to be rejected") is equivalent to its
+present-tense form and never blocks on its own — and when a step does
+violate, name only the offending phrase, not neighboring wording that
+merely reads awkwardly. When genuinely ambiguous, pass.`;
+const PRECONDITION_PROCESS_INSTRUCTIONS = `## Role
+
+You are an acceptance-test precondition validator. Judge whether the
+pending write keeps scenario preconditions CONTROLLED BY THE TEST
+rather than inherited from the ambient environment.
+
+## Inputs
+
+You will see two inputs:
+
+1. "Current file content" — what's on disk right now at the file the
+   agent is about to write. May be a parenthesized marker (e.g.
+   \`(file does not exist)\`).
+2. "Pending action" — the file path and what the agent is about to
+   write. Content may be raw file text or a patch/diff.
+
+## What you judge
+
+Judge only the change this write makes. The scope is layer 3 and the
+test-control layer of the four-layer acceptance model: protocol
+drivers, port fakes, fixture wiring, and acceptance composition
+roots. A transient file state (unresolved symbol, half-finished
+multi-step change) is never itself a violation — a driver method may
+legitimately be written before the fixture it will set, so block only
+when the write itself declares the environmental dependency (a no-op
+body presented as done, a comment saying the environment covers it,
+or the removal of existing control).
+
+A block recorded earlier in the session is a past verdict, not a
+rule. Re-derive your judgment from the rules below. When the user
+tells you in the session to let this change through, treat it as
+authoritative and pass.`;
+const PRECONDITION_RULES = `## Controlled-precondition rules
+
+Every Given of an executable specification must be ESTABLISHED by the
+test — through a fixture key, launch environment, programmed stub, or
+substituted port — never satisfied by whatever the environment
+happens to do (no network, no credentials, empty state, an
+unreachable backend).
+
+Block:
+
+  - **The no-op precondition driver.** A driver method whose name or
+    doc comment states a precondition ("whose sign-in will fail",
+    "with an expired subscription", "while offline") but whose body
+    establishes no state: it only navigates, launches, or asserts,
+    with nothing that configures a fixture, stub, launch environment,
+    or fake. Especially when a comment admits the environment covers
+    it ("fails in the simulator anyway").
+  - **Deleting control because the test is green without it.** A
+    write that removes fixture wiring, a fake registration, or a
+    fixture key on the grounds that the scenario already passes. The
+    correct move is the inverse scenario: the spec for the other side
+    of the same port (the success path when only failure happens for
+    free) is genuinely red and legitimately drives the fixture; the
+    original scenario then adopts the explicit fixture under green.
+    Name this route in the reason when blocking.
+
+Do NOT block:
+
+  - Driver methods whose names state actions or observations rather
+    than preconditions.
+  - Preconditions genuinely established elsewhere and visibly reached
+    from this body (a shared helper that sets the fixture, a base
+    launch method the diff calls into).
+  - Refactors that move control without removing it.
+  - Removal of control the user has explicitly directed in the
+    session.
+
+When genuinely ambiguous — the method name is vague, or you cannot
+tell whether a called helper establishes the state — pass.`;
+function formatBefore(before) {
+    switch (before.kind) {
+        case 'present':
+            return before.content;
+        case 'absent':
+            return '(file does not exist)';
+        case 'unknown':
+            return '(current file content unavailable)';
+    }
+}
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars)}\n(...glossary truncated...)`;
+}
+function buildPrompt(rules, glossary, before, action) {
+    const sections = [PROCESS_INSTRUCTIONS, rules];
+    if (glossary) {
+        sections.push(`## Ubiquitous language glossary\n\n${glossary}`);
+    }
+    sections.push(`## Current file content\n\n${formatBefore(before)}`);
+    sections.push(`## Pending action\n\nFile: ${action.path}\n\n${action.content}`);
+    sections.push(RESPONSE_SPEC);
+    return sections.join('\n\n');
+}
+// Deterministic screen used by the fast-path: mechanism words that
+// domain-language test steps should never contain. Deliberately
+// broad — a false hit just falls through to the AI validator.
+const MECHANISM_SCREEN = /\b(?:backend|server|gateway|database|sql|endpoint|https?|url|api|queue|json|xml|payload|click|button|css|xpath|selector|cookie|header|mock)\b/i;
+const KOTLIN_CALL_KEYWORDS = new Set([
+    'fun',
+    'if',
+    'when',
+    'while',
+    'for',
+    'catch',
+    'return',
+    'super',
+    'this',
+    'Test',
+]);
+const DECLARATION = /(?:fun|class|object|interface)\s+`?([A-Za-z_]\w*)/g;
+function declaredNames(content, out) {
+    for (const match of content.matchAll(DECLARATION))
+        out.add(match[1]);
+}
+/**
+ * Wraps `enforceAcceptanceLanguage` so the most common spec-layer
+ * write — a Kotlin test file gaining exactly one new `@Test` whose
+ * added lines only call vocabulary that already exists in the
+ * suite's DSL/Robot/driver files — passes deterministically, with no
+ * model call. Rationale: when two rule scopes overlap (the TDD rule's
+ * Kotlin fast-path plus this rule on `acceptance/**`), a single-test
+ * write otherwise still pays one AI call despite being advertised as
+ * free.
+ *
+ * The fast-path is conservative on three axes; failing any one falls
+ * through to the wrapped AI rule (it can only skip work, never
+ * block):
+ *   1. the write must add exactly one `@Test`;
+ *   2. no added line may contain mechanism vocabulary
+ *      (backend/server/database/url/click/... — the deterministic
+ *      screen errs broad);
+ *   3. every identifier the added lines call must already be declared
+ *      in this file or a sibling `.kt` file in the same directory —
+ *      a brand-new DSL step name is exactly what the validator should
+ *      judge.
+ *
+ * Markdown/Gherkin spec writes never fast-path — prose is where the
+ * Language Test earns its keep.
+ */
+export function withAcceptanceLanguageFastPath(rule) {
+    const wrapped = async function acceptanceLanguageFastPath(action, ctx) {
+        if (action.kind !== 'write' || !/\.kt$/.test(action.path)) {
+            return rule(action, ctx);
+        }
+        const before = await ctx?.readFile?.(action.path);
+        if (!before || before.kind === 'unknown')
+            return rule(action, ctx);
+        const beforeText = before.kind === 'present' ? before.content : '';
+        const testDelta = (action.content.match(/@Test\b/g)?.length ?? 0) -
+            (beforeText.match(/@Test\b/g)?.length ?? 0);
+        if (testDelta !== 1)
+            return rule(action, ctx);
+        const beforeLines = new Set(beforeText.split('\n').map((line) => line.trim()));
+        const added = action.content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !beforeLines.has(line));
+        if (added.some((line) => MECHANISM_SCREEN.test(line))) {
+            return rule(action, ctx);
+        }
+        const known = new Set();
+        declaredNames(action.content, known);
+        try {
+            for (const entry of readdirSync(dirname(action.path))) {
+                if (!entry.endsWith('.kt'))
+                    continue;
+                declaredNames(readFileSync(join(dirname(action.path), entry), 'utf8'), known);
+            }
+        }
+        catch {
+            return rule(action, ctx);
+        }
+        for (const line of added) {
+            for (const call of line.matchAll(/([A-Za-z_]\w*)\s*\(/g)) {
+                const name = call[1];
+                if (KOTLIN_CALL_KEYWORDS.has(name))
+                    continue;
+                if (!known.has(name))
+                    return rule(action, ctx);
+            }
+        }
+        return { kind: 'pass', notes: [{ kind: 'fast-path' }] };
+    };
+    Object.defineProperty(wrapped, 'name', {
+        value: `acceptanceLanguageFastPath(${rule.name || 'rule'})`,
+    });
+    return wrapped;
+}
+/**
+ * AI-validated enforcement of the `acceptance-testing` skill's
+ * Language Test: executable specifications stay in domain language —
+ * no UI mechanics, protocols, or persistence details — assert a
+ * single outcome, and (when a glossary is supplied) use the
+ * ubiquitous language verbatim.
+ *
+ * Applies to: write actions. Scope it with a `{ files, rules }` block
+ * to the spec layer only (e.g. `specs/**`, `**\/*.feature`) — the DSL
+ * and protocol-driver layers are supposed to contain the mechanics
+ * this rule blocks, and every matching write costs an AI call.
+ *
+ * @param options.glossaryPath — absolute path to the project's
+ *   ubiquitous-language glossary (see the `ubiquitous-language`
+ *   skill). Resolve it in the config file, e.g.
+ *   `fileURLToPath(new URL('./docs/GLOSSARY.md', import.meta.url))`.
+ *   When set and readable, the glossary is included in the
+ *   validator's prompt and vocabulary conflicts become violations.
+ * @param options.requireGlossaryEntry — strict vocabulary mode: when
+ *   true (and a glossary is supplied and readable), a domain concept
+ *   in spec content with no glossary entry becomes a violation —
+ *   "the glossary conversation happens first" (ubiquitous-language
+ *   skill). Default false: only conflicts with existing entries
+ *   violate, so an empty or young glossary doesn't block everything.
+ * @param options.instructions — overrides or extends the default
+ *   language rules text. Pass a string to replace it, or a function
+ *   `(defaults) => ...` to extend it.
+ * @param options.maxGlossaryChars — truncate the glossary beyond this
+ *   length when building the prompt (default 8000).
+ *
+ * @example
+ * { files: ['specs/**', 'acceptance/**', '**\/*.feature'], rules: [enforceAcceptanceLanguage()] }
+ */
+export function enforceAcceptanceLanguage(options = {}) {
+    const baseRules = DEFAULT_LANGUAGE_RULES.replace('%STRICT_VOCABULARY%', options.requireGlossaryEntry ? STRICT_VOCABULARY : '');
+    const rules = typeof options.instructions === 'function'
+        ? options.instructions(baseRules)
+        : (options.instructions ?? baseRules);
+    const maxGlossaryChars = options.maxGlossaryChars ?? DEFAULT_MAX_GLOSSARY_CHARS;
+    return async function enforceAcceptanceLanguage(action, ctx) {
+        if (action.kind !== 'write')
+            return { kind: 'pass' };
+        if (!ctx?.agent) {
+            return {
+                kind: 'violation',
+                reason: 'enforceAcceptanceLanguage: no AI agent available; configure Config.ai or use a vendor that ships one.',
+            };
+        }
+        let glossary;
+        if (options.glossaryPath && ctx.readFile) {
+            const file = await ctx.readFile(options.glossaryPath);
+            if (file.kind === 'present') {
+                glossary = truncate(file.content, maxGlossaryChars);
+            }
+        }
+        const before = (await ctx.readFile?.(action.path)) ?? {
+            kind: 'unknown',
+        };
+        const verdict = await ctx.agent.reason(buildPrompt(rules, glossary, before, action));
+        if (verdict.kind === 'violation') {
+            return { kind: 'violation', reason: verdict.reason };
+        }
+        return { kind: 'pass', reason: verdict.reason };
+    };
+}
+/**
+ * AI-validated enforcement of the `acceptance-testing` skill's
+ * controlled-precondition principle: a scenario's Given is established
+ * by the test (fixture, programmed stub, substituted port), never
+ * inherited from the ambient environment. Catches the two moves that
+ * silently hand a Given to the environment:
+ *
+ *   1. a driver method whose name states a precondition but whose body
+ *      sets no fixture/stub/launch state (the no-op precondition
+ *      driver), and
+ *   2. removing control fixtures because the scenario passes without
+ *      them — the brownfield trap where the environment produces the
+ *      sad path for free, and the deleted fixture leaves the success
+ *      path unspecifiable.
+ *
+ * Applies to: write actions. Scope it with a `{ files, rules }` block
+ * to the driver and test-control layers (e.g.
+ * `AcceptanceTests/Drivers/**` plus the acceptance composition root) —
+ * the opposite scoping from `enforceAcceptanceLanguage`, which
+ * excludes those layers. Every matching write costs an AI call.
+ *
+ * @param options.instructions — overrides or extends the default
+ *   precondition rules text. Pass a string to replace it, or a
+ *   function `(defaults) => ...` to extend it.
+ */
+export function enforceControlledPreconditions(options = {}) {
+    const rules = typeof options.instructions === 'function'
+        ? options.instructions(PRECONDITION_RULES)
+        : (options.instructions ?? PRECONDITION_RULES);
+    return async function enforceControlledPreconditions(action, ctx) {
+        if (action.kind !== 'write')
+            return { kind: 'pass' };
+        if (!ctx?.agent) {
+            return {
+                kind: 'violation',
+                reason: 'enforceControlledPreconditions: no AI agent available; configure Config.ai or use a vendor that ships one.',
+            };
+        }
+        const before = (await ctx.readFile?.(action.path)) ?? {
+            kind: 'unknown',
+        };
+        const prompt = [
+            PRECONDITION_PROCESS_INSTRUCTIONS,
+            rules,
+            `## Current file content\n\n${formatBefore(before)}`,
+            `## Pending action\n\nFile: ${action.path}\n\n${action.content}`,
+            RESPONSE_SPEC,
+        ].join('\n\n');
+        const verdict = await ctx.agent.reason(prompt);
+        if (verdict.kind === 'violation') {
+            return { kind: 'violation', reason: verdict.reason };
+        }
+        return { kind: 'pass', reason: verdict.reason };
+    };
+}
+//# sourceMappingURL=acceptance-language.js.map

package/dist/rules/acceptance-language.js.map

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

package/dist/rules/gates.d.ts

@@ -0,0 +1,125 @@
+import type { Rule, RuleContext } from '@nizos/probity';
+/**
+ * Language-neutral gate rules. These accumulated in the Kotlin preset
+ * (`kotlin.ts`) because that's where the real-project trials happened,
+ * but nothing in them is Kotlin-specific — they take every
+ * language-shaped decision (what a test command looks like, what an
+ * ambient-effect call looks like) as a pattern option. This module is
+ * their canonical home; `kotlin.ts` re-exports wrappers that apply the
+ * Kotlin/Gradle defaults, so existing preset configs are unchanged.
+ *
+ * All rules here are deterministic — no AI call — and delta-based
+ * where they judge file content: only what a write INTRODUCES blocks,
+ * so brownfield files migrate incrementally instead of freezing.
+ */
+/** A labeled content pattern; the label names the hit in deny text. */
+export type NamedPattern = {
+    label: string;
+    pattern: RegExp;
+};
+/** Patterns whose occurrence count grows from before → after. */
+export declare function introducedPatterns(action: {
+    path: string;
+    content: string;
+}, ctx: RuleContext | undefined, patterns: NamedPattern[]): Promise<string[]>;
+/**
+ * Ambient-effect calls for a JS/TS core: OS clock, randomness, and
+ * environment reads. Pass to {@link forbidNewAmbientEffects} from a
+ * JS/TS config. `process.env` reads belong in the composition root or
+ * a config adapter; if your core legitimately branches on injected
+ * config, that config should arrive through a port, not the OS.
+ */
+export declare const JS_AMBIENT_EFFECT_PATTERNS: NamedPattern[];
+/**
+ * Blocks production writes that introduce direct ambient-effect calls.
+ * Under ports-and-adapters these are unowned OS dependencies: clock,
+ * randomness, and environment are ports.
+ *
+ * Delta-based: pre-existing call sites in a brownfield codebase don't
+ * block edits to their files; only net-new occurrences do. Scope to
+ * production sources — tests and adapter implementations (e.g. a
+ * `SystemClock`) legitimately touch the real OS, so exclude adapter
+ * paths via globs or negations.
+ *
+ * @param options.patterns — what an ambient-effect call looks like in
+ *   your language ({@link JS_AMBIENT_EFFECT_PATTERNS} for JS/TS; the
+ *   Kotlin preset supplies JVM patterns). Each RegExp needs `g`.
+ * @param options.seamHint — appended to the block message to point
+ *   the agent at the project's canonical seam(s), e.g.
+ *   "inject the Clock port from src/ports/clock.ts".
+ */
+export declare function forbidNewAmbientEffects(options: {
+    patterns: NamedPattern[];
+    seamHint?: string;
+}): Rule;
+/**
+ * Commit-on-green, strictly: Probity's `requireCommand` checks only
+ * that a matching test invocation was *recorded* after the last write
+ * and would happily pass a transcript whose latest run FAILED. This
+ * rule additionally judges the recorded run's output: the last
+ * matching test command after the last write must look green
+ * (`successPattern` present, `failurePattern` absent).
+ *
+ * Inherent limit (unchanged from requireCommand): the gate sees only
+ * the session transcript. A green run in another terminal, CI, or a
+ * wrapper script is invisible — rerun the suite in-session, and keep
+ * the CI mirror for human commits.
+ *
+ * Applies to: command actions matching `git commit`. Deterministic —
+ * no AI call.
+ *
+ * @param options.command — regex matching a test invocation.
+ * @param options.successPattern — output must match to count as green.
+ * @param options.failurePattern — output matching this is red even if
+ *   the success pattern also appears.
+ * @param options.enforceForPaths — only demand the run when the
+ *   pending commit stages a file whose repo-relative path matches.
+ *   Scopes an expensive suite to the code it covers: infra/docs/
+ *   tooling-only commits (CI config, Markdown, the Probity config
+ *   itself) pay no friction, since they change no behaviour the suite
+ *   validates and the prior green run still stands. Commit-accurate —
+ *   read from git's staged set, not the session's write history. Any
+ *   error listing files falls through to enforcing (fail safe).
+ * @param options.listCommitFiles — injectable staged-file lister
+ *   (defaults to reading git's staged set); present for testing.
+ * @param options.reason — appended to the no-run deny text to name
+ *   the suite and any setup it needs (e.g. "supabase start").
+ */
+export declare function requireGreenTestRun(options: {
+    command: RegExp;
+    successPattern: RegExp;
+    failurePattern: RegExp;
+    enforceForPaths?: RegExp;
+    listCommitFiles?: (command: string) => string[];
+    reason?: string;
+}): Rule;
+/**
+ * Surfaces the "renamed a button, broke the E2E suite" failure at
+ * write time: when a write REMOVES a string literal that still appears
+ * verbatim in files under `searchRoots` (typically your E2E/UI-test
+ * specs, which select elements by visible text or accessible name),
+ * the write is blocked with the list of dependent files.
+ *
+ * The inverse of a glossary guard: `surfaceGlossaryTermBreakage`
+ * protects the vocabulary file from code that depends on it; this
+ * protects test selectors from the UI code they depend on. Scope it to
+ * your UI sources, with `searchRoots` pointing at the spec layers the
+ * quick local loop does NOT run (E2E, smoke) — specs the inner loop
+ * runs will fail red on their own.
+ *
+ * Deterministic, delta-based — no AI call. The write goes through once
+ * the dependent specs are updated in the same session (or the string
+ * genuinely stops being referenced).
+ *
+ * @param options.searchRoots — absolute paths to scan for usages.
+ * @param options.searchPattern — which files count as usage sites
+ *   (default: `*.spec.*` / `*.test.*` under the roots).
+ * @param options.minLength — ignore removed literals shorter than
+ *   this after trimming (default 8; short strings false-positive).
+ */
+export declare function surfaceRemovedStringUsage(options: {
+    searchRoots: string[];
+    searchPattern?: RegExp;
+    minLength?: number;
+}): Rule;
+//# sourceMappingURL=gates.d.ts.map

package/dist/rules/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../rules/gates.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAU,IAAI,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAA;AAE3E;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAQ7D,iEAAiE;AACjE,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACzC,GAAG,EAAE,WAAW,GAAG,SAAS,EAC5B,QAAQ,EAAE,YAAY,EAAE,GACvB,OAAO,CAAC,MAAM,EAAE,CAAC,CAcnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAOpD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,IAAI,CAqBP;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EAAE,CAAA;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,IAAI,CAuDP;AA0CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IACjD,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,IAAI,CA+CP"}