@alex-dbs/coderuler 1.3.1 → 1.5.0

package/skills/coderuler-new-rule/reference.md

@@ -1,4 +1,4 @@
-# Rule API reference
+ # Rule API reference
 
 Read the branch needed for the rule; use [SKILL.md](SKILL.md) for the authoring, test, and inspection workflow. All imports below use the public `@alex-dbs/coderuler` SDK.
 
@@ -173,18 +173,23 @@ The rule name is `proto-route-version`, saved as `.coderuler/proto-route-version
 The public shapes are:
 
 ```ts
-import type { Awaitable, JsonValue, SourceFile, ScopeMatch } from '@alex-dbs/coderuler';
+import type { Awaitable, JsonValue, LineRange, ProjectContext, SourceFile, ScopeMatch } from '@alex-dbs/coderuler';
 
 type ScopeSelector<T = JsonValue> =
-  (file: SourceFile) => Awaitable<readonly ScopeMatch<T>[]>;
+  (file: SourceFile, context?: ProjectContext) => Awaitable<readonly ScopeMatch<T>[]>;
 // SourceFile: { readonly filepath: string; readonly source: string }
 // ScopeMatch<T>: { readonly id: string; readonly source: string;
 //   readonly data?: T;
 //   readonly captures?: Readonly<Record<string, string | readonly string[]>>;
-//   readonly lines?: { readonly start: number; readonly end: number } }
+//   readonly lines?: LineRange }
 ```
 
-Return a dense array; `[]` means no matches. Use stable nonempty IDs and actual source text; line spans are 1-based inclusive. `data` must be finite, acyclic, JSON-compatible (including `null`, `false`, `0`, and `''`); captures contain only strings/string arrays.
+For `--diff` and `--pr`, CodeRuler selects changed files for the rule. It does not narrow custom scopes to changed lines. Your custom selector must use `changedLines` if it needs line-level filtering. A selector that ignores line ranges still checks every selected scope in each changed file.
+
+The engine passes `ProjectContext`; direct calls can omit it. Use stable nonempty IDs and actual source text. Line spans are 1-based and inclusive. `data` must be finite, acyclic, JSON-compatible (including `null`, `false`, `0`, and `''`); captures contain only strings/string arrays.
+When a selector reads diff fields, annotate its `context` parameter as `ProjectContext`. This lets direct callers omit the optional parameter.
+
+`changedFiles` and `changedLines` are `undefined` outside diff/PR checks. In those checks, an empty `changedFiles` set means no files changed. An empty `changedLines` map means there are no entries with line data. `changedLines.get(filepath)` returns added or replaced lines in that file. The ranges are 1-based and inclusive. A missing entry means line data is unavailable, for example for binary or conversion-attributed files. An entry with `[]` means the file changed but has no added lines.
 
 `Selection<T>` is `{ readonly files: readonly string[]; readonly exclude?: readonly string[]; readonly scope?: ScopeSelector<T> }`. `context.select<T>(selection)` returns `Promise<readonly ScopeSubject<T>[]>`. A scope subject adds `kind: 'scope'` and `filepath` to its match. Custom `select` returns flattened scope subjects, not group subjects.
 
@@ -197,14 +202,21 @@ import type {
   ScopeSubject, SelectionContext,
 } from '@alex-dbs/coderuler';
 
-const owners: ScopeSelector<string> = ({ source }) =>
-  source.split('\n').flatMap((line, index) => {
+const owners: ScopeSelector<string> = ({ filepath, source }, context: ProjectContext) => {
+  const candidates = source.split('\n').flatMap((line, index) => {
     const owner = /^# owner: (\S+)\s*$/.exec(line)?.[1];
     return owner === undefined ? [] : [{
       id: `owner:${index + 1}`, source: line, data: owner,
       lines: { start: index + 1, end: index + 1 },
     }];
   });
+  if (context.changedFiles === undefined) return candidates;
+  if (!context.changedFiles.has(filepath)) return [];
+  const ranges = context.changedLines?.get(filepath);
+  if (ranges === undefined) return candidates;
+  return candidates.filter(scope => scope.lines !== undefined && ranges.some(range =>
+    range.start <= scope.lines.end && scope.lines.start <= range.end));
+};
 
 export default class AssignedOwner extends Rule<string> {
   files = ['src/**/*.txt'];
@@ -316,9 +328,11 @@ Results validate; supplied messages survive reporting. Violations without a mess
 
 | Context                                                | Available members                                                                 |
 | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
-| `ProjectContext`                                       | `readonly project: Project`; `trace(message: string, details?: JsonValue): void`. |
+| `ProjectContext`                                       | `project`; optional `changedFiles: ReadonlySet<string>` and `changedLines: ReadonlyMap<string, readonly LineRange[]>`; `trace(message, details?)`. |
 | `SelectionContext extends ProjectContext`              | `select<T>(selection: Selection<T>): Promise<readonly ScopeSubject<T>[]>`.        |
-| `CheckContext<T = JsonValue> extends SelectionContext` | `readonly ruleName: string`; `ai(options: AiOptions<T>): Promise<CheckResult>`.   |
+| `CheckContext<T = JsonValue> extends SelectionContext` | `readonly ruleName: string`; `ai(options: AiOptions<T>): Promise<CheckResult>`. |
+
+`changedFiles` contains paths that changed in the project. `changedLines` maps changed paths to added or replaced lines. These values are absent outside `--diff` and `--pr` runs. In those runs, an empty set means no changed files. An empty map means no exact line ranges are available. A missing entry for a path means line data is unavailable, for example for binary or conversion-attributed files. An entry with `[]` means the file changed but has no added lines.
 
 
 Use `trace` for decision evidence visible during inspection; keep normal execution free of ad-hoc console output. AI/regex projection callbacks receive only `ProjectContext`, not the full check context.
@@ -344,85 +358,139 @@ Default input is `String(data)` for scalar/null data, otherwise source text. `in
 
 ## AI options, examples, and settings
 
-`ai<T = JsonValue>(options: AiOptions<T>): Evaluator<T>` accepts:
+`ai<T = JsonValue>(options: AiOptions<T>): Evaluator<T>` accepts exactly one of `rule` or `instruction`:
 
-- `rule: string`: nonempty semantic policy; include exceptions and what visible evidence permits a violation.
+- `rule: string`: nonempty policy text. This option is deprecated; use `instruction` for new rules.
+- `instruction: string`: nonempty text describing the expected behavior of the selected code. Write a direct requirement that the selected provider can judge as respected or broken.
 - `examples?: { readonly good?: readonly string[]; readonly bad?: readonly string[] }`: conditioning examples, dense arrays of nonempty strings; omitted/empty lists are valid.
 - `violationMessage?: string`: nonempty reporting-only message, not sent as instructions.
 - `input?: (subject: Subject<T>, context: ProjectContext) => Awaitable<JsonValue>`: replace the default projection; output validates as JSON-compatible.
 
-```ts
-import { Rule, ai, test } from '@alex-dbs/coderuler';
-import type { RuleSettings } from '@alex-dbs/coderuler';
+Jev and OpenAI use the fixed question "Is the rule respected?" A higher probability means the rule is respected. The configured threshold decides pass or violation.
 
-export default class ActionableInstructions extends Rule {
-  files = ['guides/**/*.md'];
-  settings: RuleSettings = { model: 'jev-latest', threshold: 0.5 };
-  check = ai({
-    rule: 'Instructions name a concrete action and its observable completion condition.',
-    examples: { good: ['Run the migration until it exits successfully.'], bad: ['Handle the migration.'] },
-    violationMessage: 'Name the action and how to recognize completion',
-  });
-}
-export const aiTests = [
-  test('an independent concrete instruction passes').withFiles({
-    'guides/cache.md': 'Delete the cache directory; finish when it no longer exists.',
-  }).passes(),
-];
-```
+### AI instruction style
 
-`examples` condition the model; `aiTests` assert outcomes on independent datasets. Ordinary `tests` are offline; live `aiTests` require explicit AI opt-in as described in [SKILL.md](SKILL.md). Keep deterministic applicability out of the prompt.
+Write the instruction as a requirement for the code, not directions for the reviewer. A direct requirement names the behavior compliant code must have. Add a boundary only when it says where the policy applies; include exceptions only when they are genuinely allowed. Keep each rule to one policy.
 
-Default AI input is `{ filepath, scope: { id, data, captures? } }` when data exists, or `{ filepath, scope: { id, source, captures? } }` otherwise. Data presence includes `null`, `false`, `0`, and `''`. Groups become `{ files: [{ filepath, scopes: [...] }] }`. Good: select enough context to judge meaning, or project a deliberate JSON input. Bad: expect source text alongside structured data without providing it via `input`.
+Weak: "Report a violation when a Go pointer is dereferenced without a nil check."
 
-Inside a custom check, `return context.ai({ rule: '...' })` evaluates its current subject with effective settings and preserves AI result metadata. Replacing that result requires intentionally preserving probability/model/threshold metadata; token accounting is automatic across all `context.ai` calls, even when returning a different result. `ai(...)` validates options when constructed but performs no loading-time network I/O.
+Better: "Check each Go pointer for nil before dereferencing it." For nested fields, add the needed boundary: "Check every pointer in the field path before dereferencing the field."
 
-`RuleSettings` supports backend `'jev'`, model (default `'jev-latest'`), finite threshold in `[0, 1]` (default `0.4`), and finite nonnegative `inputCostPerMillion` / `outputCostPerMillion` prices (USD per million tokens; defaults `0.042` / `0`). Threshold precedence is CLI override → rule setting → `RK_THRESHOLD` → default; backend/model use rule setting → environment (`RK_BACKEND` / `TYPESAFE_DEFAULT_MODEL`) → default. AI passes only when probability is **strictly greater** than threshold; equality violates. Results include the effective threshold. Provider environment/key resolution is lazy at the first AI call; deterministic/skipped/filtered paths need no key. Live calls require `TYPESAFE_API_KEY`; use release configuration guidance for transport setup.
+Keep reporting language in `violationMessage`, conditioning examples in `examples`, and test fixtures in `aiTests`; they do not belong in the instruction. Use selectors and filters for deterministic applicability. Keep provider input to the smallest scope that still supports a correct decision. For function-local code policies, use `scopes.astGrep` to select one function or method per scope, then filter for relevant syntax such as pointer dereferences. Include surrounding context only when needed to judge the policy.
 
-Inspection reports per-verification `usage: AiUsage` and a final recap: `calls`, `unreportedCalls`, `inputTokens`, `outputTokens`, `inputCost`, and `outputCost` (USD). Counts come from provider responses; missing counts remain unreported and totals cover reported calls only. Configure prices through rule settings or `RK_INPUT_COST_PER_MILLION` / `RK_OUTPUT_COST_PER_MILLION`; inspect flags `--input-cost-per-million` / `--output-cost-per-million` override both. Prices change estimates, not decisions.
+Compare wording with the policy and dataset held fixed:
 
-AI rules, under the hood, are using TypeSafe Jev model and `noul` question (yes/no probabilistc answer). The rule must clearly explain what is checked. A global/generic rule won't match. A dedicated rule will perform better. The example bellow will check a particular usage of go slice `append` function.
+1. Save the current instruction and its scores as the baseline.
+2. Change only the instruction. Keep the model version, examples, input, fixtures, and threshold unchanged.
+3. Run every affected `aiTests` case with `--ai --ai-scores`. Include compliant cases and violations, especially policy boundaries.
+4. Compare compliant scores toward `1` and violation scores toward `0` separately. Inspect individual regressions and the weakest score in each group, not just averages.
+5. Keep wording that improves separation without changing the policy or introducing wrong decisions. Repeat a close comparison before treating a small gain as reliable.
+
+`PASS` in test output means the expected result matched. A passing violation test still needs a low AI score. Do not lower the threshold, relabel fixtures, or copy test cases into the instruction to improve the comparison. Results on a tuning dataset do not prove performance on unseen code.
 
-```
-import { Rule, ai, scopes, test } from '@alex-dbs/coderuler';
 
-export default class GoAppendSlice extends Rule {
+This rule checks Go pointer dereferences, including nested fields:
+
+```ts
+import { Rule, ai, scopes, test, type ScopeSubject } from '@alex-dbs/coderuler';
+
+export default class GoDereferenceGuard extends Rule {
   files = ['**/*.go'];
+  settings = { threshold: 0.7 };
 
   scope = scopes.astGrep({
     language: 'go',
     rule: {
       any: [{ kind: 'function_declaration' }, { kind: 'method_declaration' }],
       has: {
-        kind: 'for_statement',
+        kind: 'unary_expression',
         stopBy: 'end',
         has: {
-          pattern: 'append($SLICE,$$$ARGS)',
-          stopBy: 'end',
+          field: 'operator',
+          regex: '^\\*$',
         },
       },
     },
   });
 
   check = ai({
-    rule: `A slice freshly allocated for a loop whose final element count is exactly known must be allocated at that final length and filled by index or with copy;
-growing it with append is a violation even when capacity was preallocated with make([]T, 0, n)
-and even when it was first created with make([]T, n) and then reset to length zero.
-
-Append in a loop is valid only when the final count is not known before the loop,
-such as elements appended under a condition so the count varies within an upper bound that capacity merely reserves,
-or when the slice already holds a deliberately assigned prefix written before the loop.
-
-Appending after a length that was allocated but never assigned,
-or assigning elements by index and also appending them, is a violation.`,
+    instruction: `Check each Go pointer for nil before dereferencing it. For nested fields, check every pointer in the field path.`,
     examples: {
-      good: [/* Some examples, not shown here to keep it short*/],
-      bad: [/* Some examples, not shown here to keep it short*/],
+      good: [
+        `func configName(config *Config) string {
+    if config != nil {
+        return (*config).Name
+    }
+    return ""
+}`,
+        `func (config *Config) name() string {
+    if config == nil {
+        return ""
+    }
+    return (*config).Name
+}`
+      ],
+      bad: [
+        `func configName(config *Config) string {
+    return (*config).Name
+}`,
+        `func configName(config *Config) string {
+    if config == nil {
+        logMissingConfig()
+    }
+    return (*config).Name
+}`
+      ],
     },
+    input: async (subject, { project }) => {
+      const scope = subject as ScopeSubject;
+      return {
+        function: scope.source,
+        file: await project.readText(scope.filepath),
+      };
+    },
+    violationMessage: 'Check each pointer for nil before using *.',
   });
 }
+
+export const aiTests = [
+  test('an early return guards a pointer parameter').withFiles({
+    'quota.go': `package example
+
+func remainingQuota(quota *int, used int) int {
+    if quota == nil {
+        return 0
+    }
+    return *quota - used
+}`,
+  }).passes(),
+  test('a root nil check does not guard a nested pointer field').withFiles({
+    'config.go': `package example
+
+type Config struct { Child *Child }
+type Child struct { Value *int }
+
+func nestedValue(config *Config) int {
+    if config == nil {
+        return 0
+    }
+    return *config.Child.Value
+}`,
+  }).violates(),
+] as const;
 ```
 
+`examples` condition the model; `aiTests` assert outcomes on independent datasets. Put every test case for an AI rule in `aiTests`, without a separate `tests` export. Ordinary `tests` are offline; live `aiTests` require `--ai`. Use `instruction` and follow [AI instruction style](#ai-instruction-style). Add `--ai-scores` to inspect probabilities, not just test outcomes.
+
+Default AI input is `{ filepath, scope: { id, data, captures? } }` when data exists, or `{ filepath, scope: { id, source, captures? } }` otherwise. Data presence includes `null`, `false`, `0`, and `''`. Groups become `{ files: [{ filepath, scopes: [...] }] }`. Good: select enough context to judge meaning, or project a deliberate JSON input. Bad: expect source text alongside structured data without providing it via `input`.
+
+Inside a custom check, `return context.ai({ instruction: '...' })` evaluates its current subject with effective settings and preserves AI result metadata. The deprecated `rule` option remains accepted for existing rules. Replacing that result requires intentionally preserving probability/model/threshold metadata; token accounting is automatic across all `context.ai` calls, even when returning a different result. `ai(...)` validates options when constructed but performs no loading-time network I/O.
+
+`RuleSettings.backend` supports `'jev'` and `'openai'`; Jev is the default. Set `model`, threshold, `inputCostPerMillion`, or `outputCostPerMillion` in `settings` to override defaults. Both providers use a threshold of `0.4`; AI passes only when probability is **strictly greater** than threshold, and equality violates. Threshold precedence is CLI override → rule setting → `RK_THRESHOLD` → `0.4`. Backend precedence is rule setting → `RK_BACKEND` → `jev`. Model precedence is rule setting → selected provider's model variable → provider default. Jev uses `TYPESAFE_DEFAULT_MODEL` (default `jev-latest`) and `TYPESAFE_API_KEY`; OpenAI uses `OPENAI_DEFAULT_MODEL` (default `gpt-6-luna`) and `OPENAI_API_KEY`. The base URL variables are `TYPESAFE_BASE_URL` and `OPENAI_BASE_URL`, defaulting to `https://api.typesafe.ai` and `https://api.openai.com/v1`. Provider configuration and credentials are read only when an AI call selects that backend. Deterministic, skipped, and filtered paths need no key.
+
+Inspection reports per-verification `usage: AiUsage` and a final recap: `calls`, `unreportedCalls`, `inputTokens`, `outputTokens`, `inputCost`, and `outputCost` (USD). Counts come from provider responses; missing counts remain unreported and totals cover reported calls only. Default input prices are `$0.042` per million tokens for Jev and `$0.10` for OpenAI; both output prices default to `$0`. Price precedence is inspection override → rule setting → `RK_INPUT_COST_PER_MILLION` / `RK_OUTPUT_COST_PER_MILLION` → selected provider default. Prices change estimates, not decisions.
+
+
 ## Project readers
 
 Public signatures (import `Project`, `CsvOptions`, `CsvRow`, and `JsonValue` as types from `@alex-dbs/coderuler`):