@alex-dbs/coderuler 0.0.0-stage → 1.3.0

package/dist/infra/settings.js

@@ -0,0 +1,91 @@
+import { JevAdapter } from '../adapter/decision/jev.js';
+const DEFAULT_BACKEND = 'jev';
+const DEFAULT_MODEL = 'jev-latest';
+const DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+const DEFAULT_THRESHOLD = 0.4;
+const DEFAULT_INPUT_COST_PER_MILLION = 0.042;
+const DEFAULT_OUTPUT_COST_PER_MILLION = 0;
+const THRESHOLD_MESSAGE = 'must be a number between 0 and 1';
+const DECIMAL = /^(?:[0-9]+(?:\.[0-9]+)?|\.[0-9]+)$/;
+function validateThreshold(value, label) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new RangeError(`${label} ${THRESHOLD_MESSAGE}, got ${String(value)}`);
+    }
+    return value;
+}
+function parseThreshold(value, label) {
+    const trimmed = value.trim();
+    if (!DECIMAL.test(trimmed))
+        throw new RangeError(`${label} ${THRESHOLD_MESSAGE}, got ${JSON.stringify(value)}`);
+    return validateThreshold(Number(trimmed), label);
+}
+function validatePrice(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${label} must be a finite nonnegative number, got ${String(value)}`);
+    }
+    return value;
+}
+function price(override, ruleValue, env, name, fallback) {
+    if (override !== undefined)
+        return override;
+    if (ruleValue !== undefined)
+        return ruleValue;
+    const raw = setting(env, name);
+    if (raw === undefined)
+        return fallback;
+    if (!DECIMAL.test(raw))
+        throw new RangeError(`${name} must be a finite nonnegative decimal number`);
+    return validatePrice(Number(raw), name);
+}
+function setting(env, name) {
+    const value = env[name];
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        throw new Error(`${name} is set but empty`);
+    return trimmed;
+}
+export function createDecisionResolver(env, thresholdOverride, pricingOverrides) {
+    const flagThreshold = thresholdOverride === undefined ? undefined : validateThreshold(thresholdOverride, '--threshold');
+    const inputOverride = pricingOverrides?.inputCostPerMillion;
+    const outputOverride = pricingOverrides?.outputCostPerMillion;
+    if (inputOverride !== undefined)
+        validatePrice(inputOverride, '--input-cost-per-million');
+    if (outputOverride !== undefined)
+        validatePrice(outputOverride, '--output-cost-per-million');
+    return settings => {
+        const backend = settings.backend ?? setting(env, 'RK_BACKEND') ?? DEFAULT_BACKEND;
+        if (backend !== 'jev') {
+            throw new Error(`Unknown decision backend '${backend}'; supported backends: ${DEFAULT_BACKEND}`);
+        }
+        let threshold;
+        if (flagThreshold !== undefined) {
+            threshold = flagThreshold;
+        }
+        else if (settings.threshold !== undefined) {
+            threshold = validateThreshold(settings.threshold, 'rule.settings.threshold');
+        }
+        else {
+            const raw = setting(env, 'RK_THRESHOLD');
+            threshold = raw === undefined ? DEFAULT_THRESHOLD : parseThreshold(raw, 'RK_THRESHOLD');
+        }
+        if (settings.inputCostPerMillion !== undefined) {
+            validatePrice(settings.inputCostPerMillion, 'rule.settings.inputCostPerMillion');
+        }
+        if (settings.outputCostPerMillion !== undefined) {
+            validatePrice(settings.outputCostPerMillion, 'rule.settings.outputCostPerMillion');
+        }
+        const pricing = {
+            inputCostPerMillion: price(inputOverride, settings.inputCostPerMillion, env, 'RK_INPUT_COST_PER_MILLION', DEFAULT_INPUT_COST_PER_MILLION),
+            outputCostPerMillion: price(outputOverride, settings.outputCostPerMillion, env, 'RK_OUTPUT_COST_PER_MILLION', DEFAULT_OUTPUT_COST_PER_MILLION),
+        };
+        const model = settings.model ?? setting(env, 'TYPESAFE_DEFAULT_MODEL') ?? DEFAULT_MODEL;
+        const baseUrl = setting(env, 'TYPESAFE_BASE_URL') ?? DEFAULT_BASE_URL;
+        const apiKey = setting(env, 'TYPESAFE_API_KEY');
+        if (apiKey === undefined) {
+            throw new Error('No decision API key: set TYPESAFE_API_KEY');
+        }
+        return { backend: new JevAdapter({ model, baseUrl, apiKey }), threshold, pricing };
+    };
+}

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@alex-dbs/coderuler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-dbs/coderuler.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^24.15.0 || >=26.0.0"
+  },
+  "bin": {
+    "coderuler": "dist/cli.js"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills/coderuler-new-rule"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "npx tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node --test --test-concurrency=4 tests/*.test.ts",
+    "test:golden": "npm run build && node --test tests/golden.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ast-grep/lang-angular": "0.0.10",
+    "@ast-grep/lang-bash": "0.0.8",
+    "@ast-grep/lang-bicep": "0.0.2",
+    "@ast-grep/lang-c": "0.0.6",
+    "@ast-grep/lang-cpp": "0.0.6",
+    "@ast-grep/lang-csharp": "0.0.6",
+    "@ast-grep/lang-dart": "0.0.7",
+    "@ast-grep/lang-elixir": "0.0.7",
+    "@ast-grep/lang-glimmer-javascript": "0.0.2",
+    "@ast-grep/lang-glimmer-typescript": "0.0.2",
+    "@ast-grep/lang-go": "0.0.6",
+    "@ast-grep/lang-haskell": "0.0.7",
+    "@ast-grep/lang-java": "0.0.7",
+    "@ast-grep/lang-json": "0.0.7",
+    "@ast-grep/lang-kotlin": "0.0.7",
+    "@ast-grep/lang-lua": "0.0.7",
+    "@ast-grep/lang-markdown": "0.0.6",
+    "@ast-grep/lang-php": "0.0.7",
+    "@ast-grep/lang-python": "0.0.6",
+    "@ast-grep/lang-ruby": "0.0.7",
+    "@ast-grep/lang-rust": "0.0.7",
+    "@ast-grep/lang-scala": "0.0.7",
+    "@ast-grep/lang-sql": "0.0.8",
+    "@ast-grep/lang-swift": "0.0.8",
+    "@ast-grep/lang-toml": "0.0.9",
+    "@ast-grep/lang-yaml": "0.0.6",
+    "@ast-grep/napi": "0.50.0",
+    "@npmcli/arborist": "10.0.4",
+    "@npmcli/package-json": "8.0.0",
+    "axios": "1.20.0",
+    "commander": "15.0.0",
+    "csv-parse": "7.0.3",
+    "jsonc-parser": "3.3.1",
+    "jsonpath-plus": "11.2.1",
+    "npm-install-checks": "9.0.0",
+    "npm-package-arg": "14.0.0",
+    "pacote": "22.0.0",
+    "skills": "1.7.2",
+    "ssri": "14.0.0",
+    "string-width": "8.3.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "nock": "15.0.5",
+    "tar": "7.5.22",
+    "tsx": "4.23.15",
+    "typescript": "^7.0.2"
+  }
+}

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

@@ -0,0 +1,141 @@
+---
+name: coderuler-new-rule
+description: Create CodeRuler rules, including custom selection, filters and checks, inline tests, and inspection.
+---
+
+# Create a CodeRuler rule
+
+Use the installed `coderuler` CLI from the project root. In commands, `.` means this project. Import the public SDK from `@alex-dbs/coderuler`.
+
+For all rule options, read [reference.md](reference.md) when that branch is needed.
+
+## 1. Define the policy
+
+Establish:
+
+- **Applicability:** which files and scopes belong to this policy, and which data must exist?
+- **Decision:** what exact condition separates a pass from a violation?
+- **Evidence:** one realistic violation, one compliant counterpart, and the boundaries that could change the decision.
+
+Each rule must check exactly one thing. Split independent checks into separate rules.
+
+Use deterministic code for structural, numeric, equality, and pattern policies. Use AI when the decision genuinely requires semantic judgment; keep selection and applicability deterministic.
+
+## 2. Write the dataset, then the rule
+
+Create `.coderuler/<name>.rule.ts` and default-export a class extending `Rule`. The filename supplies the rule name. Supported module suffixes are `.rule.ts`, `.rule.mts`, `.rule.js`, and `.rule.mjs`; helper modules use ordinary filenames.
+
+Start the name with its language or technology prefix, such as `go-`, `ts-`, or `pg-`, followed by the policy.
+
+Keep rules short, with only a few lines of policy code. Reuse built-in selectors, evaluators, and standard libraries before writing custom logic. Add helpers only for real reuse.
+
+Add a named `tests` export in the same file. Use `.passes()` and `.violates()` cases that exercise the policy. Omit `.skips()` assertions when creating a rule: skipped inputs never reach the check and provide no evidence of policy behavior.
+
+Run the relevant cases before the policy change and require an assertion mismatch for the intended violation, not a loading error. Implement the policy, then require every case to pass.
+
+This complete example requires at least two replicas whenever `spec.replicas` is an integer:
+
+```ts
+import { Rule, pass, scopes, test, violation } from '@alex-dbs/coderuler';
+import type { Evaluator, ScopeSubject } from '@alex-dbs/coderuler';
+
+type Deployment = { replicas: number };
+
+export default class ReplicaFloor extends Rule<Deployment> {
+  files = ['deploy/**/*.yml'];
+  scope = scopes.yaml<Deployment>({ path: '$.spec' });
+
+  filter({ data }: ScopeSubject<Deployment>) {
+    return {
+      applies: data !== null && typeof data === 'object'
+        && Number.isInteger(data.replicas),
+      reason: 'Requires an integer spec.replicas',
+    };
+  }
+
+  check: Evaluator<Deployment> = subject => {
+    const { replicas } = (subject as ScopeSubject<Deployment>).data!;
+    return replicas >= 2 ? pass() : violation(`Set spec.replicas to at least 2; found ${replicas}`);
+  };
+}
+
+export const tests = [
+  test('the minimum replica count passes').withFiles({
+    'deploy/api.yml': { spec: { replicas: 2 } },
+  }).passes(),
+  test('one replica violates').withFiles({
+    'deploy/api.yml': { spec: { replicas: 1 } },
+  }).violates(),
+  test('zero is a real value, not missing data').withFiles({
+    'deploy/api.yml': { spec: { replicas: 0 } },
+  }).violates(),
+];
+```
+
+Save it as `.coderuler/k8s-replica-floor.rule.ts`. The scope cast reflects the fixed default `group = 'scope'`; the non-null assertion reflects the filter's required-data precondition. A TypeScript generic describes expected data; the filter still establishes that shape at runtime. If a missing or malformed field is itself a violation, select its enclosing object and check that requirement instead of filtering it away.
+
+## 3. Validate and run the tests
+
+For the example:
+
+```sh
+coderuler validate .coderuler/k8s-replica-floor.rule.ts
+coderuler test .coderuler/k8s-replica-floor.rule.ts
+```
+
+Then run the project's rules and their datasets:
+
+```sh
+coderuler validate
+coderuler test
+```
+
+`validate` checks the module contract, not policy behavior or TypeScript semantics. `check` and `validate` do not execute inline tests. `test` with no selected cases is an error, not success.
+
+Useful test options:
+
+```sh
+coderuler test . --failures-only
+coderuler test . --concurrency 4 --timeout 30s
+coderuler test .coderuler/k8s-semantic-policy.rule.ts --ai --timeout 45s
+```
+
+Replace the semantic-policy filename with the actual AI rule. `--ai` authorizes live provider calls for `aiTests`, requires provider configuration, and may incur charges. Outcomes can vary; provider errors are errors, not passes.
+
+## 4. Inspect the rule on the project
+
+Tests use temporary fixtures. Inspection uses actual files under `.`; create representative project data there if none exists yet.
+
+```sh
+coderuler inspect .coderuler/k8s-replica-floor.rule.ts .
+coderuler inspect k8s-replica-floor . --json
+```
+
+An exact rule name uses discovery; a module path selects that file directly. Inspection accepts one rule, not a directory. Use one output format at a time (`--json`, `--jsonl`, or `--raw`).
+
+Follow the pipeline:
+
+`enabled → when → select → filter → group → check`
+
+- **No files/scopes:** check globs, exclusions, selector paths, and the inspected root.
+- **Filtered scopes:** read the applicability reason; confirm the filter excludes only out-of-policy data.
+- **Unexpected decision:** inspect selected `data`/`source`, captures, group membership, and the result. Use `context.trace(message, details)` inside hooks/checks when intermediate domain values would explain the decision.
+- **Runtime error:** fix invalid data, parsing, or implementation behavior; converting an error into a pass hides a broken rule.
+
+Inspection runs the actual check, including live AI calls when present.
+
+Finally exercise normal evaluation:
+
+```sh
+coderuler check . --rules .coderuler/k8s-replica-floor.rule.ts --output-all
+```
+
+## Good and bad practices
+
+| Prefer | Avoid |
+| --- | --- |
+| Narrow selection, applicability in `when`/`filter`, policy in `check` | Repeating guards in the check or filtering out the violations the rule should report |
+| A function-valued `check = ...` or typed `check: Evaluator<T> = ...` | A `check(...)` method instead of the required property |
+| Actionable violations naming the field/value and required correction | Generic messages with no location-specific reason |
+| Pure per-subject decisions and local state | Results depending on concurrent check order or mutable module caches |
+| Real failing-before/passing-after datasets and an inspected applicable subject | Merely validating imports, running without selected subjects, or treating a skip as a pass |