@gd-kirie/alint-config 0.1.2

package/README.md

@@ -0,0 +1,65 @@
+# `@gd-kirie/alint-config`
+
+Alint rules and presets for Kirie repository review experiments.
+
+## Usage
+
+```ts
+import gdKirieAlintConfig from "@gd-kirie/alint-config";
+
+export default gdKirieAlintConfig;
+```
+
+## Rules
+
+### `@gd-kirie/no-stringified-rethrow`
+
+LLM-backed `onFile` rule that warns when a `catch` block formats the caught
+error into a string and throws a new error without preserving the original error
+as `cause`.
+
+Examples of incorrect code for this rule:
+
+```ts
+try {
+  await run();
+}
+catch (error) {
+  throw new Error(`Failed to run: ${error}`);
+}
+```
+
+Will output a warning like:
+
+```
+> alint /Path/to/file.ts
+
+/Path/to/file.ts
+  28:0  warning  Caught error is stringified into a new Error message without preserving the original error as cause.  @gd-kirie/no-stringified-rethrow
+
+
+1 warn / 0 error | 1,598 tokens
+```
+
+Examples of correct code for this rule:
+
+```ts
+try {
+  await run();
+}
+catch (error) {
+  throw new Error("Failed to run.", { cause: error });
+}
+```
+
+or a project-specific error type that preserves `cause`.
+
+## Planned Rules
+
+The following rules are intentionally documented but not implemented yet:
+
+- `@gd-kirie/no-lossy-record-narrowing`: detect broad `Record<string, unknown>`
+  narrowing helpers that erase expected payload or config structure.
+- `@gd-kirie/no-polling-wait-loop`: detect in-process readiness waits that use
+  sleep-loop polling instead of events, lifecycle hooks, or explicit readiness
+  promises.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+//#region src/types.d.ts
+type Awaitable<T> = Promise<T> | T;
+interface AlintConfig {
+  plugins?: PluginDefinition[];
+  rules?: Record<string, RuleConfigEntry>;
+}
+interface DiagnosticDescriptor {
+  evidence?: unknown;
+  filePath?: string;
+  loc?: DiagnosticLocation;
+  message: string;
+}
+interface DiagnosticLocation {
+  end?: SourcePosition;
+  start: SourcePosition;
+}
+interface InferenceUsageRecord {
+  inputTokens?: number;
+  modelId: string;
+  outputTokens?: number;
+  providerId: string;
+  totalTokens?: number;
+}
+interface PluginDefinition {
+  rules: Record<string, RuleDefinition>;
+  scope: string;
+}
+type RuleConfigEntry = [RuleSeverity] | RuleSeverity;
+interface RuleContext {
+  metering?: {
+    recordUsage: (usage: InferenceUsageRecord) => void;
+  };
+  model: () => Promise<ResolvedModel>;
+  report: (diagnostic: DiagnosticDescriptor) => void;
+}
+interface RuleDefinition {
+  cache?: boolean | {
+    level?: "target";
+  };
+  create: (context: RuleContext) => RuleHandlers;
+  model?: ModelRequirement;
+}
+interface RuleHandlers {
+  onFile?: (file: SourceFile) => Awaitable<void>;
+}
+type RuleSeverity = "error" | "off" | "warn";
+interface SourceFile {
+  language: "javascript" | "typescript" | "unknown";
+  lines: string[];
+  path: string;
+  text: string;
+}
+interface SourcePosition {
+  column: number;
+  line: number;
+}
+interface ResolvedModel {
+  id: string;
+  provider: {
+    endpoint: string;
+    headers?: Record<string, string>;
+    id: string;
+  };
+}
+interface ModelRequirement {
+  capabilities?: string[];
+  minContextWindow?: number;
+  params?: Record<string, unknown>;
+  size?: string;
+}
+//#endregion
+//#region src/config.d.ts
+declare const gdKirieAlintConfig: AlintConfig;
+//#endregion
+//#region src/plugin.d.ts
+declare const gdKirieAlintPlugin: PluginDefinition;
+//#endregion
+//#region src/rules/no-stringified-rethrow.d.ts
+interface ErrorWrappingReviewFinding {
+  evidence?: unknown;
+  line: number;
+  message?: string;
+}
+declare const noStringifiedRethrowRule: RuleDefinition;
+//#endregion
+export { type AlintConfig, type Awaitable, type DiagnosticDescriptor, type DiagnosticLocation, type ErrorWrappingReviewFinding, type InferenceUsageRecord, type ModelRequirement, type PluginDefinition, type ResolvedModel, type RuleConfigEntry, type RuleContext, type RuleDefinition, type RuleHandlers, type RuleSeverity, type SourceFile, type SourcePosition, gdKirieAlintConfig as default, gdKirieAlintConfig, gdKirieAlintPlugin, noStringifiedRethrowRule };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/config.ts","../src/plugin.ts","../src/rules/no-stringified-rethrow.ts"],"mappings":";KAAY,SAAA,MAAe,OAAA,CAAQ,CAAA,IAAK,CAAA;AAAA,UAEvB,WAAA;EACf,OAAA,GAAU,gBAAA;EACV,KAAA,GAAQ,MAAA,SAAe,eAAA;AAAA;AAAA,UAGR,oBAAA;EACf,QAAA;EACA,QAAA;EACA,GAAA,GAAM,kBAAA;EACN,OAAA;AAAA;AAAA,UAGe,kBAAA;EACf,GAAA,GAAM,cAAA;EACN,KAAA,EAAO,cAAA;AAAA;AAAA,UAGQ,oBAAA;EACf,WAAA;EACA,OAAA;EACA,YAAA;EACA,UAAA;EACA,WAAA;AAAA;AAAA,UAGe,gBAAA;EACf,KAAA,EAAO,MAAA,SAAe,cAAA;EACtB,KAAA;AAAA;AAAA,KAGU,eAAA,IAAmB,YAAA,IAAgB,YAAA;AAAA,UAE9B,WAAA;EACf,QAAA;IACE,WAAA,GAAc,KAAA,EAAO,oBAAA;EAAA;EAEvB,KAAA,QAAa,OAAA,CAAQ,aAAA;EACrB,MAAA,GAAS,UAAA,EAAY,oBAAA;AAAA;AAAA,UAGN,cAAA;EACf,KAAA;IAAoB,KAAA;EAAA;EACpB,MAAA,GAAS,OAAA,EAAS,WAAA,KAAgB,YAAA;EAClC,KAAA,GAAQ,gBAAA;AAAA;AAAA,UAGO,YAAA;EACf,MAAA,IAAU,IAAA,EAAM,UAAA,KAAe,SAAA;AAAA;AAAA,KAGrB,YAAA;AAAA,UAEK,UAAA;EACf,QAAA;EACA,KAAA;EACA,IAAA;EACA,IAAA;AAAA;AAAA,UAGe,cAAA;EACf,MAAA;EACA,IAAA;AAAA;AAAA,UAGe,aAAA;EACf,EAAA;EACA,QAAA;IACE,QAAA;IACA,OAAA,GAAU,MAAA;IACV,EAAA;EAAA;AAAA;AAAA,UAIa,gBAAA;EACf,YAAA;EACA,gBAAA;EACA,MAAA,GAAS,MAAA;EACT,IAAA;AAAA;;;cC5EW,kBAAA,EAAoB,WAAA;;;cCApB,kBAAA,EAAoB,gBAAA;;;UCChB,0BAAA;EACf,QAAA;EACA,IAAA;EACA,OAAA;AAAA;AAAA,cAOW,wBAAA,EAA0B,cAAA"}

package/dist/index.js

@@ -0,0 +1,88 @@
+import { generateText } from "xsai";
+//#region src/rules/no-stringified-rethrow.ts
+const noStringifiedRethrowRule = { create: (ctx) => ({ async onFile(file) {
+	const findings = await reviewStringifiedRethrows(file, await ctx.model(), ctx.metering);
+	for (const finding of findings) ctx.report({
+		evidence: finding.evidence,
+		filePath: file.path,
+		loc: { start: {
+			column: 0,
+			line: finding.line
+		} },
+		message: finding.message ?? "Do not stringify and rethrow caught errors; preserve the original error as cause."
+	});
+} }) };
+async function reviewStringifiedRethrows(file, model, usage) {
+	const response = await generateText({
+		baseURL: model.provider.endpoint,
+		headers: model.provider.headers,
+		messages: createReviewMessages(file),
+		model: model.id,
+		response_format: { type: "json_object" },
+		temperature: 0
+	});
+	const content = response.text;
+	if (typeof content !== "string") throw new Error("alint model response did not include message content.");
+	recordUsage(usage, model, response);
+	const result = JSON.parse(content);
+	if (!Array.isArray(result.findings)) return [];
+	return result.findings.filter(isReviewFinding);
+}
+function createReviewMessages(file) {
+	return [{
+		content: [
+			"You are reviewing one JavaScript or TypeScript file.",
+			"",
+			"Task:",
+			"Find catch blocks that stringify, format, or otherwise collapse the caught error into a message string before throwing a new error, without preserving the original error as the error cause.",
+			"",
+			"Report only cases where the original caught error is not preserved through `cause` or an equivalent custom error cause field.",
+			"Do not report code that throws `new Error(message, { cause: error })`.",
+			"Do not report custom error classes that pass or store the caught error as cause.",
+			"Do not report code that logs an error and rethrows the same original error.",
+			"",
+			"Return JSON only with this shape:",
+			"{\"findings\":[{\"line\":1,\"message\":\"short diagnostic\",\"evidence\":{\"reason\":\"short reason\"}}]}",
+			"Use the line number of the throw statement.",
+			"Return an empty findings array when there is no issue."
+		].join("\n"),
+		role: "system"
+	}, {
+		content: `File: ${file.path}\n\n${formatSourceWithLineNumbers(file.text)}`,
+		role: "user"
+	}];
+}
+function formatSourceWithLineNumbers(source) {
+	return source.split("\n").map((line, index) => `${index + 1} | ${line}`).join("\n");
+}
+function isReviewFinding(value) {
+	if (!value || typeof value !== "object") return false;
+	const finding = value;
+	return typeof finding.line === "number" && Number.isInteger(finding.line) && finding.line > 0;
+}
+function recordUsage(metering, model, response) {
+	if (!metering) return;
+	metering.recordUsage({
+		inputTokens: response.usage.inputTokens,
+		modelId: model.id,
+		outputTokens: response.usage.outputTokens,
+		providerId: model.provider.id,
+		totalTokens: response.usage.totalTokens
+	});
+}
+//#endregion
+//#region src/plugin.ts
+const gdKirieAlintPlugin = {
+	rules: { "no-stringified-rethrow": noStringifiedRethrowRule },
+	scope: "@gd-kirie"
+};
+//#endregion
+//#region src/config.ts
+const gdKirieAlintConfig = {
+	plugins: [gdKirieAlintPlugin],
+	rules: { "@gd-kirie/no-stringified-rethrow": "warn" }
+};
+//#endregion
+export { gdKirieAlintConfig as default, gdKirieAlintConfig, gdKirieAlintPlugin, noStringifiedRethrowRule };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/rules/no-stringified-rethrow.ts","../src/plugin.ts","../src/config.ts"],"sourcesContent":["import type { GenerateTextResult } from \"xsai\";\nimport { generateText } from \"xsai\";\nimport type { ResolvedModel, RuleContext, RuleDefinition, SourceFile } from \"../types\";\n\nexport interface ErrorWrappingReviewFinding {\n  evidence?: unknown;\n  line: number;\n  message?: string;\n}\n\ninterface ReviewResponse {\n  findings?: ErrorWrappingReviewFinding[];\n}\n\nexport const noStringifiedRethrowRule: RuleDefinition = {\n  create: (ctx) => ({\n    async onFile(file) {\n      const model = await ctx.model();\n      const findings = await reviewStringifiedRethrows(file, model, ctx.metering);\n\n      for (const finding of findings) {\n        ctx.report({\n          evidence: finding.evidence,\n          filePath: file.path,\n          loc: {\n            start: {\n              column: 0,\n              line: finding.line,\n            },\n          },\n          message:\n            finding.message ??\n            \"Do not stringify and rethrow caught errors; preserve the original error as cause.\",\n        });\n      }\n    },\n  }),\n};\n\nasync function reviewStringifiedRethrows(\n  file: SourceFile,\n  model: ResolvedModel,\n  usage: RuleContext[\"metering\"],\n): Promise<ErrorWrappingReviewFinding[]> {\n  const response = await generateText({\n    baseURL: model.provider.endpoint,\n    headers: model.provider.headers,\n    messages: createReviewMessages(file),\n    model: model.id,\n    response_format: {\n      type: \"json_object\",\n    },\n    temperature: 0,\n  });\n  const content = response.text;\n\n  if (typeof content !== \"string\") {\n    throw new Error(\"alint model response did not include message content.\");\n  }\n\n  recordUsage(usage, model, response);\n\n  const result = JSON.parse(content) as ReviewResponse;\n\n  if (!Array.isArray(result.findings)) {\n    return [];\n  }\n\n  return result.findings.filter(isReviewFinding);\n}\n\nfunction createReviewMessages(\n  file: SourceFile,\n): Array<{ content: string; role: \"system\" | \"user\" }> {\n  return [\n    {\n      content: [\n        \"You are reviewing one JavaScript or TypeScript file.\",\n        \"\",\n        \"Task:\",\n        \"Find catch blocks that stringify, format, or otherwise collapse the caught error into a message string before throwing a new error, without preserving the original error as the error cause.\",\n        \"\",\n        \"Report only cases where the original caught error is not preserved through `cause` or an equivalent custom error cause field.\",\n        \"Do not report code that throws `new Error(message, { cause: error })`.\",\n        \"Do not report custom error classes that pass or store the caught error as cause.\",\n        \"Do not report code that logs an error and rethrows the same original error.\",\n        \"\",\n        \"Return JSON only with this shape:\",\n        '{\"findings\":[{\"line\":1,\"message\":\"short diagnostic\",\"evidence\":{\"reason\":\"short reason\"}}]}',\n        \"Use the line number of the throw statement.\",\n        \"Return an empty findings array when there is no issue.\",\n      ].join(\"\\n\"),\n      role: \"system\",\n    },\n    {\n      content: `File: ${file.path}\\n\\n${formatSourceWithLineNumbers(file.text)}`,\n      role: \"user\",\n    },\n  ];\n}\n\nfunction formatSourceWithLineNumbers(source: string): string {\n  return source\n    .split(\"\\n\")\n    .map((line, index) => `${index + 1} | ${line}`)\n    .join(\"\\n\");\n}\n\nfunction isReviewFinding(value: unknown): value is ErrorWrappingReviewFinding {\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  const finding = value as Partial<ErrorWrappingReviewFinding>;\n\n  return typeof finding.line === \"number\" && Number.isInteger(finding.line) && finding.line > 0;\n}\n\nfunction recordUsage(\n  metering: RuleContext[\"metering\"],\n  model: ResolvedModel,\n  response: GenerateTextResult,\n): void {\n  if (!metering) {\n    return;\n  }\n\n  metering.recordUsage({\n    inputTokens: response.usage.inputTokens,\n    modelId: model.id,\n    outputTokens: response.usage.outputTokens,\n    providerId: model.provider.id,\n    totalTokens: response.usage.totalTokens,\n  });\n}\n","import { noStringifiedRethrowRule } from \"./rules/no-stringified-rethrow\";\nimport type { PluginDefinition } from \"./types\";\n\nexport const gdKirieAlintPlugin: PluginDefinition = {\n  rules: {\n    \"no-stringified-rethrow\": noStringifiedRethrowRule,\n  },\n  scope: \"@gd-kirie\",\n};\n","import { gdKirieAlintPlugin } from \"./plugin\";\nimport type { AlintConfig } from \"./types\";\n\nexport const gdKirieAlintConfig: AlintConfig = {\n  plugins: [gdKirieAlintPlugin],\n  rules: {\n    \"@gd-kirie/no-stringified-rethrow\": \"warn\",\n  },\n};\n"],"mappings":";;AAcA,MAAa,2BAA2C,EACtD,SAAS,SAAS,EAChB,MAAM,OAAO,MAAM;CAEjB,MAAM,WAAW,MAAM,0BAA0B,MAAM,MADnC,IAAI,MAAM,GACgC,IAAI,QAAQ;CAE1E,KAAK,MAAM,WAAW,UACpB,IAAI,OAAO;EACT,UAAU,QAAQ;EAClB,UAAU,KAAK;EACf,KAAK,EACH,OAAO;GACL,QAAQ;GACR,MAAM,QAAQ;EAChB,EACF;EACA,SACE,QAAQ,WACR;CACJ,CAAC;AAEL,EACF,GACF;AAEA,eAAe,0BACb,MACA,OACA,OACuC;CACvC,MAAM,WAAW,MAAM,aAAa;EAClC,SAAS,MAAM,SAAS;EACxB,SAAS,MAAM,SAAS;EACxB,UAAU,qBAAqB,IAAI;EACnC,OAAO,MAAM;EACb,iBAAiB,EACf,MAAM,cACR;EACA,aAAa;CACf,CAAC;CACD,MAAM,UAAU,SAAS;CAEzB,IAAI,OAAO,YAAY,UACrB,MAAM,IAAI,MAAM,uDAAuD;CAGzE,YAAY,OAAO,OAAO,QAAQ;CAElC,MAAM,SAAS,KAAK,MAAM,OAAO;CAEjC,IAAI,CAAC,MAAM,QAAQ,OAAO,QAAQ,GAChC,OAAO,CAAC;CAGV,OAAO,OAAO,SAAS,OAAO,eAAe;AAC/C;AAEA,SAAS,qBACP,MACqD;CACrD,OAAO,CACL;EACE,SAAS;GACP;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EACF,CAAC,CAAC,KAAK,IAAI;EACX,MAAM;CACR,GACA;EACE,SAAS,SAAS,KAAK,KAAK,MAAM,4BAA4B,KAAK,IAAI;EACvE,MAAM;CACR,CACF;AACF;AAEA,SAAS,4BAA4B,QAAwB;CAC3D,OAAO,OACJ,MAAM,IAAI,CAAC,CACX,KAAK,MAAM,UAAU,GAAG,QAAQ,EAAE,KAAK,MAAM,CAAC,CAC9C,KAAK,IAAI;AACd;AAEA,SAAS,gBAAgB,OAAqD;CAC5E,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO;CAGT,MAAM,UAAU;CAEhB,OAAO,OAAO,QAAQ,SAAS,YAAY,OAAO,UAAU,QAAQ,IAAI,KAAK,QAAQ,OAAO;AAC9F;AAEA,SAAS,YACP,UACA,OACA,UACM;CACN,IAAI,CAAC,UACH;CAGF,SAAS,YAAY;EACnB,aAAa,SAAS,MAAM;EAC5B,SAAS,MAAM;EACf,cAAc,SAAS,MAAM;EAC7B,YAAY,MAAM,SAAS;EAC3B,aAAa,SAAS,MAAM;CAC9B,CAAC;AACH;;;ACnIA,MAAa,qBAAuC;CAClD,OAAO,EACL,0BAA0B,yBAC5B;CACA,OAAO;AACT;;;ACLA,MAAa,qBAAkC;CAC7C,SAAS,CAAC,kBAAkB;CAC5B,OAAO,EACL,oCAAoC,OACtC;AACF"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gd-kirie/alint-config",
+  "version": "0.1.2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moeru-ai/godot-kirie.git",
+    "directory": "packages/alint-config"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "xsai": "^0.5.0-beta.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}