@konvert7/klint 0.29.0 → 0.31.0

package/README.md

@@ -209,6 +209,39 @@ arch:
 
 `klint.config.json` is still supported for backwards compatibility.
 
+### Editor support
+
+The package ships `klint.schema.json` and `klint.schema.yaml`, so the recommended
+setup points at the installed copy:
+
+```yaml
+$schema: ./node_modules/@konvert7/klint/klint.schema.json
+```
+
+That file is installed alongside klint itself, so it cannot drift — upgrading klint
+upgrades the schema with it. Both the inline `$schema` key above and the
+`# yaml-language-server: $schema=…` modeline work; when both are present the modeline
+wins. `klint.config.json` files are handled by the editor's built-in JSON support.
+
+### Pinning the schema version
+
+To pin a specific published schema instead, set `$schema` to a version-tagged URL:
+
+```yaml
+$schema: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.29.0/klint.schema.json
+```
+
+When the tagged version differs from the installed klint, the run reports a
+`klint/schema-version` warning naming both versions and the URL to move to. It is a
+warning, not an error — the exit code is unaffected. Local paths carry no version and
+are never checked, which is why the installed copy above never warns.
+
+This check runs when klint runs. Editors validate the config's *shape* against the
+schema, but have no way to compare it against the installed klint, so the warning
+appears in klint's output rather than as an editor diagnostic.
+
+`klint --version` prints the installed version.
+
 ## Architecture as Code
 
 The `arch:` section turns project boundaries into executable policy.

package/cli/output.ts

@@ -85,6 +85,25 @@ export function mergeJsonOutputs(...outputs: JsonPayload[]): JsonPayload {
   };
 }
 
+export function withAdvisories(
+  stdout: string,
+  advisories: Array<Omit<Violation, "fix">>
+): string {
+  if (advisories.length === 0) return stdout;
+  const payload = parseJsonPayload(stdout);
+  if (!isJsonPayload(payload)) return stdout;
+
+  const violations = [
+    ...payload.violations,
+    ...advisories.map((advisory) => ({ ...advisory, fix: null })),
+  ];
+  const errors = violations.filter((v) => v.severity === "error").length;
+  return JSON.stringify({
+    violations,
+    summary: { errors, warnings: violations.length - errors },
+  });
+}
+
 export function isJsonPayload(value: unknown): value is JsonPayload {
   if (!value || typeof value !== "object") return false;
   const candidate = value as Partial<JsonPayload>;

package/cli/rust-engine.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runKlint } from "../core/runner";
-import type { KlintRule, RuleConfigValue } from "../core/types";
+import type { KlintRule, RuleConfigValue, Violation } from "../core/types";
 import {
   emptyJsonPayload,
   isJsonPayload,
@@ -13,6 +13,7 @@ import {
   parseJsonPayload,
   toJsonCliResult,
   toJsonPayload,
+  withAdvisories,
   writeTextOutput,
 } from "./output";
 import { PACKAGE_ROOT } from "./paths";
@@ -25,6 +26,7 @@ import {
 } from "./rust-config";
 
 export function runRustEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -32,6 +34,7 @@ export function runRustEngine({
   rulesFile,
   startedAt,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -73,7 +76,7 @@ export function runRustEngine({
 
   if (result.stderr) process.stderr.write(result.stderr);
   if (json) {
-    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stdout) process.stdout.write(withAdvisories(result.stdout, advisories));
     process.exit(result.status ?? 1);
   }
 
@@ -82,10 +85,11 @@ export function runRustEngine({
     process.stderr.write("klint: --engine rust failed to parse Rust JSON output\n");
     process.exit(1);
   }
-  writeTextOutput(payload.violations, startedAt);
+  writeTextOutput([...payload.violations, ...advisories], startedAt);
 }
 
 export function runCompareEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -93,6 +97,7 @@ export function runCompareEngine({
   rulesFile,
   tsViolations,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -154,7 +159,7 @@ export function runCompareEngine({
     process.exit(1);
   }
 
-  process.stdout.write(tsResult.stdout);
+  process.stdout.write(withAdvisories(tsResult.stdout, advisories));
   process.exit(tsResult.status);
 }
 
@@ -188,6 +193,7 @@ function writeRustEngineConfig({
 }
 
 export function runAutoEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -197,6 +203,7 @@ export function runAutoEngine({
   customRules,
   customRulesMap,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -241,10 +248,10 @@ export function runAutoEngine({
   const tsOutput = toJsonPayload(tsViolations);
   const merged = mergeJsonOutputs(rustOutput, tsOutput);
   if (json) {
-    process.stdout.write(JSON.stringify(merged));
+    process.stdout.write(withAdvisories(JSON.stringify(merged), advisories));
     process.exit(merged.summary.errors > 0 ? 2 : 0);
   }
-  writeTextOutput(merged.violations, startedAt);
+  writeTextOutput([...merged.violations, ...advisories], startedAt);
 }
 
 function runAutoRustSubset({

package/cli.ts

@@ -8,14 +8,26 @@ import { installSkill } from "./cli/install-skill";
 import {
   formatDuration,
   toJsonCliResult,
+  withAdvisories,
   writeDebugEvent,
   writeTextOutput,
 } from "./cli/output";
+import { PACKAGE_ROOT } from "./cli/paths";
 import { runAutoEngine, runCompareEngine, runRustEngine } from "./cli/rust-engine";
 import { applyFixes } from "./core/fixer";
 import { runKlint } from "./core/runner";
+import { schemaVersionAdvisory } from "./core/schema-version";
 import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core/types";
 
+async function installedVersion(): Promise<string> {
+  const manifest = await readFile(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
+  try {
+    return (JSON.parse(manifest) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
 interface CliOptions {
   configDir?: string;
   rulesFile?: string;
@@ -52,6 +64,9 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     else if (args[i] === "--help" || args[i] === "-h") {
       printHelp();
       process.exit(0);
+    } else if (args[i] === "--version" || args[i] === "-V") {
+      process.stdout.write(`klint ${await installedVersion()}\n`);
+      process.exit(0);
     }
   }
 
@@ -70,6 +85,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   }
 
   interface RawConfig {
+    $schema?: string;
     root?: string;
     include?: string[];
     plugins?: string[];
@@ -77,17 +93,25 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     arch?: unknown;
   }
   let raw: RawConfig;
+  let configText = "";
   try {
-    const text = await readFile(configPath, "utf-8");
-    raw = (usingYaml ? parseYaml(text) : JSON.parse(text)) as RawConfig;
+    configText = await readFile(configPath, "utf-8");
+    raw = (usingYaml ? parseYaml(configText) : JSON.parse(configText)) as RawConfig;
   } catch {
     process.stderr.write(`klint: failed to parse ${configPath}\n`);
     process.exit(1);
   }
   const root = resolve(configDir, raw.root ?? ".");
 
+  const advisories = schemaVersionAdvisory({
+    schema: raw.$schema,
+    installed: await installedVersion(),
+    configFile: usingYaml ? "klint.yaml" : "klint.config.json",
+    configText,
+  });
+
   if (engine === "rust") {
-    runRustEngine({ fix, json, raw, root, rulesFile, startedAt });
+    runRustEngine({ advisories, fix, json, raw, root, rulesFile, startedAt });
     return;
   }
   if (
@@ -119,6 +143,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (engine === "auto") {
     runAutoEngine({
+      advisories,
       fix,
       json,
       raw,
@@ -145,6 +170,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (engine === "compare") {
     runCompareEngine({
+      advisories,
       fix,
       json,
       raw,
@@ -157,7 +183,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (json) {
     const tsResult = toJsonCliResult(violations);
-    process.stdout.write(tsResult.stdout);
+    process.stdout.write(withAdvisories(tsResult.stdout, advisories));
     process.exit(tsResult.status);
   }
 
@@ -189,7 +215,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     process.stdout.write(`${msg} Finished in ${formatDuration(startedAt)}.\n`);
     process.exit(0);
   }
-  writeTextOutput(violations, startedAt);
+  writeTextOutput([...violations, ...advisories], startedAt);
 }
 
 if (import.meta.main) await main();

package/core/arch-comments.ts

@@ -15,6 +15,8 @@ function collectComments(file: string, content: string): CommentSpan[] {
   const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, variant, content);
   const starts = lineStarts(content);
   const spans: CommentSpan[] = [];
+  const substitutionDepths: number[] = [];
+  let braceDepth = 0;
   let token = scanner.scan();
   while (token !== ts.SyntaxKind.EndOfFileToken) {
     if (
@@ -28,6 +30,18 @@ function collectComments(file: string, content: string): CommentSpan[] {
         endLine: lineAt(starts, Math.max(start, end - 1)),
         isDoc: isDocComment(content.slice(start, end)),
       });
+    } else if (token === ts.SyntaxKind.TemplateHead) {
+      substitutionDepths.push(braceDepth);
+    } else if (token === ts.SyntaxKind.OpenBraceToken) {
+      braceDepth += 1;
+    } else if (token === ts.SyntaxKind.CloseBraceToken) {
+      if (substitutionDepths.at(-1) === braceDepth) {
+        if (scanner.reScanTemplateToken(false) === ts.SyntaxKind.TemplateTail) {
+          substitutionDepths.pop();
+        }
+      } else {
+        braceDepth -= 1;
+      }
     }
     token = scanner.scan();
   }

package/core/config.schema.ts

@@ -244,7 +244,7 @@ const CountDocCommentsSchema = z
   .boolean()
   .optional()
   .describe(
-    "Count doc-comments toward the limit. Doc-comments are `/** … */` JSDoc blocks (TS/JS) and docstrings (Python); ordinary `//`, `/* */`, and `#` comments are always counted. Defaults to false, so documentation is exempt and only explanatory/inline comments are capped."
+    "Count doc-comments toward the limit. Doc-comments are `/** … */` JSDoc blocks (TS/JS), `///` (Swift), and `///` or `//!` (Rust); ordinary `//`, `/* */`, and `#` comments are always counted. Defaults to false, so documentation is exempt and only explanatory/inline comments are capped. Has no effect on Python: docstrings are string expressions rather than comments, so they never count toward either limit."
   );
 
 const CommentIgnoreSchema = StringOrStringArray.optional().describe(
@@ -377,7 +377,7 @@ export const KlintConfigSchema = z
       .string()
       .optional()
       .describe(
-        "JSON Schema reference. Use ./klint.schema.json for local validation or https://klint.dev/schema.json for the published schema."
+        "JSON Schema reference. Use ./klint.schema.json for local validation, or a version-tagged URL such as https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.29.0/klint.schema.json to pin the schema. A tagged URL naming a version other than the installed one raises a klint/schema-version warning."
       ),
     root: z
       .string()

package/core/schema-version.ts

@@ -0,0 +1,46 @@
+import type { Violation } from "./types";
+
+const SCHEMA_VERSION_RULE = "klint/schema-version";
+
+const TAGGED_SCHEMA_URL = /\/refs\/tags\/v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)\//;
+const UNRELEASED = "0.0.0";
+
+export function schemaUrlForVersion(version: string): string {
+  return `https://raw.githubusercontent.com/konvert7/klint/refs/tags/v${version}/klint.schema.json`;
+}
+
+export function declaredSchemaVersion(schema: string | undefined): string | undefined {
+  return schema?.match(TAGGED_SCHEMA_URL)?.[1];
+}
+
+export function schemaVersionAdvisory({
+  schema,
+  installed,
+  configFile,
+  configText,
+}: {
+  schema: string | undefined;
+  installed: string;
+  configFile: string;
+  configText: string;
+}): Array<Omit<Violation, "fix">> {
+  const declared = declaredSchemaVersion(schema);
+  if (declared === undefined || declared === installed || installed === UNRELEASED) {
+    return [];
+  }
+
+  return [
+    {
+      file: configFile,
+      line: schemaDeclarationLine(configText),
+      rule: SCHEMA_VERSION_RULE,
+      severity: "warn",
+      message: `config declares schema v${declared} but klint ${installed} is installed — update $schema to ${schemaUrlForVersion(installed)}`,
+    },
+  ];
+}
+
+function schemaDeclarationLine(configText: string): number {
+  const index = configText.split("\n").findIndex((line) => line.includes("$schema"));
+  return index === -1 ? 1 : index + 1;
+}

package/core/types.ts

@@ -108,7 +108,7 @@ interface ArchMaxLinesRule {
 interface ArchCommentRuleBase {
   limit: number;
   in: string | string[];
-  /** Count doc-comments (`/** *​/` JSDoc, Python docstrings) toward the limit. Defaults to false. */
+  /** Count doc-comments (`/** *​/` JSDoc, Swift `///`, Rust `///` and `//!`) toward the limit. Defaults to false. No effect on Python, whose docstrings are never counted. */
   countDocComments?: boolean;
   /** Comment lines matching these patterns count toward neither limit. Literal substring, or `re:` for a regex. */
   ignore?: string | string[];