@intentius/chant 0.0.5 → 0.0.9

package/src/cli/mcp/tools/scaffold.ts

@@ -0,0 +1,125 @@
+import type { LexiconPlugin } from "../../../lexicon";
+
+/**
+ * Scaffold tool definition for MCP
+ */
+export const scaffoldTool = {
+  name: "scaffold",
+  description: "Generate starter code for a common infrastructure pattern",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      pattern: {
+        type: "string",
+        description: "Infrastructure pattern to scaffold (e.g. 's3-bucket', 'lambda', 'pipeline')",
+      },
+      lexicon: {
+        type: "string",
+        description: "Lexicon to use for scaffolding (e.g. 'aws', 'gitlab'). Auto-detected if omitted.",
+      },
+      template: {
+        type: "string",
+        description: "Named init template (e.g. 'node-pipeline', 'docker-build'). When provided, returns the template's source files instead of pattern-matching.",
+      },
+    },
+    required: ["pattern"],
+  },
+};
+
+/**
+ * Create a scaffold handler with access to loaded plugins
+ */
+export function createScaffoldHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const pattern = params.pattern as string;
+    const lexiconName = params.lexicon as string | undefined;
+    const templateName = params.template as string | undefined;
+
+    // Try to find a matching plugin
+    const candidates = lexiconName
+      ? plugins.filter((p) => p.name === lexiconName)
+      : plugins;
+
+    // Search plugin init templates for a pattern match
+    for (const plugin of candidates) {
+      const templateSet = plugin.initTemplates?.(templateName);
+      if (!templateSet) continue;
+
+      // If a named template was requested, return all its source files
+      if (templateName) {
+        const files = Object.entries(templateSet.src).map(([filename, content]) => ({ filename, content }));
+        if (files.length > 0) {
+          return {
+            lexicon: plugin.name,
+            pattern,
+            template: templateName,
+            files,
+          };
+        }
+      }
+
+      // Match template filenames against the pattern (case-insensitive substring)
+      const lowerPattern = pattern.toLowerCase();
+      const matched: Array<{ filename: string; content: string }> = [];
+
+      for (const [filename, content] of Object.entries(templateSet.src)) {
+        if (filename.toLowerCase().includes(lowerPattern)) {
+          matched.push({ filename, content });
+        }
+      }
+
+      if (matched.length > 0) {
+        return {
+          lexicon: plugin.name,
+          pattern,
+          files: matched,
+        };
+      }
+    }
+
+    // Fall back to a generic skeleton
+    const configContent = `/**
+ * Shared configuration for ${pattern}
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+
+export const config = {
+  // Add shared configuration here
+};
+`;
+
+    const resourceContent = `/**
+ * ${pattern} resource definition
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+// import { config } from "./config";
+
+// export const ${toCamelCase(pattern)} = new ResourceType({
+//   // Add properties here
+// });
+`;
+
+    return {
+      lexicon: lexiconName ?? null,
+      pattern,
+      files: [
+        { filename: "config.ts", content: configContent },
+        { filename: `${pattern}.ts`, content: resourceContent },
+      ],
+      note: "No lexicon-specific template found. Generic skeleton provided — fill in imports and resource types.",
+    };
+  };
+}
+
+function toCamelCase(s: string): string {
+  return s
+    .split(/[-_]/)
+    .map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join("");
+}

package/src/cli/mcp/tools/search.ts

@@ -0,0 +1,98 @@
+import type { LexiconPlugin } from "../../../lexicon";
+
+/**
+ * Search tool definition for MCP
+ */
+export const searchTool = {
+  name: "search",
+  description: "Search the resource catalog across loaded lexicons by keyword",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query — matches against resource type, class name, and kind",
+      },
+      lexicon: {
+        type: "string",
+        description: "Filter results to a specific lexicon (e.g. 'aws', 'gitlab')",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of results to return (default: 20)",
+      },
+    },
+    required: ["query"],
+  },
+};
+
+interface CatalogEntry {
+  className: string;
+  resourceType: string;
+  kind?: string;
+}
+
+/**
+ * Create a search handler with access to loaded plugins
+ */
+export function createSearchHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const query = params.query as string;
+    const lexiconFilter = params.lexicon as string | undefined;
+    const limit = (params.limit as number) ?? 20;
+
+    const lowerQuery = query.toLowerCase();
+    const results: Array<CatalogEntry & { lexicon: string; score: number }> = [];
+
+    const candidates = lexiconFilter
+      ? plugins.filter((p) => p.name === lexiconFilter)
+      : plugins;
+
+    for (const plugin of candidates) {
+      const resources = plugin.mcpResources?.() ?? [];
+      const catalog = resources.find((r) => r.uri === "resource-catalog");
+      if (!catalog) continue;
+
+      let entries: CatalogEntry[];
+      try {
+        const raw = await catalog.handler();
+        entries = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+
+      for (const entry of entries) {
+        const fields = [
+          entry.resourceType?.toLowerCase() ?? "",
+          entry.className?.toLowerCase() ?? "",
+          entry.kind?.toLowerCase() ?? "",
+        ];
+
+        const match = fields.some((f) => f.includes(lowerQuery));
+        if (!match) continue;
+
+        // Score: prefix match on resourceType or className ranks higher
+        const isPrefix = fields.some((f) => f.startsWith(lowerQuery));
+        const score = isPrefix ? 1 : 0;
+
+        results.push({ ...entry, lexicon: plugin.name, score });
+      }
+    }
+
+    // Sort: prefix matches first, then alphabetical by resourceType
+    results.sort((a, b) => {
+      if (a.score !== b.score) return b.score - a.score;
+      return (a.resourceType ?? "").localeCompare(b.resourceType ?? "");
+    });
+
+    const limited = results.slice(0, limit);
+
+    return {
+      query,
+      total: results.length,
+      results: limited.map(({ score: _score, ...entry }) => entry),
+    };
+  };
+}

package/src/cli/registry.ts

@@ -14,6 +14,7 @@ export interface ParsedArgs {
   force?: boolean;
   fix: boolean;
   lexicon?: string;
+  template?: string;
   watch: boolean;
   verbose: boolean;
   help: boolean;

package/src/cli/reporters/stylish.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { formatStylish, formatSummary, formatJson, formatSarif } from "./stylish";
-import type { LintDiagnostic } from "../../lint/rule";
+import type { LintDiagnostic, LintRule } from "../../lint/rule";
 
 describe("formatStylish", () => {
   const originalNoColor = process.env.NO_COLOR;
@@ -279,4 +279,215 @@ describe("formatSarif", () => {
     // Should have 2 unique rules
     expect(parsed.runs[0].tool.driver.rules).toHaveLength(2);
   });
+
+  test("enriches rules with descriptions when LintRule objects are provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const rules: LintRule[] = [
+      {
+        id: "COR001",
+        severity: "warning",
+        category: "style",
+        description: "No inline objects in Declarable constructors",
+        check: () => [],
+      },
+    ];
+
+    const result = formatSarif(diagnostics, rules);
+    const parsed = JSON.parse(result);
+    const sarifRule = parsed.runs[0].tool.driver.rules[0];
+
+    expect(sarifRule.shortDescription.text).toBe("No inline objects in Declarable constructors");
+    expect(sarifRule.fullDescription.text).toBe("No inline objects in Declarable constructors");
+    expect(sarifRule.helpUri).toContain("cor001");
+    expect(sarifRule.defaultConfiguration.level).toBe("warning");
+    expect(sarifRule.properties.category).toBe("style");
+  });
+
+  test("includes fingerprints in results", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].fingerprints).toBeDefined();
+    expect(parsed.runs[0].results[0].fingerprints["chant/v1"]).toBe("COR001:test.ts:10:5");
+  });
+
+  test("includes ruleIndex in results", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].ruleIndex).toBe(0);
+  });
+
+  test("includes endLine/endColumn when provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        endLine: 12,
+        endColumn: 20,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const region = parsed.runs[0].results[0].locations[0].physicalLocation.region;
+
+    expect(region.startLine).toBe(10);
+    expect(region.startColumn).toBe(5);
+    expect(region.endLine).toBe(12);
+    expect(region.endColumn).toBe(20);
+  });
+
+  test("omits endLine/endColumn when not provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const region = parsed.runs[0].results[0].locations[0].physicalLocation.region;
+
+    expect(region.endLine).toBeUndefined();
+    expect(region.endColumn).toBeUndefined();
+  });
+
+  test("includes suppressed diagnostics with suppressions array", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Active issue",
+      },
+    ];
+
+    const suppressed: Array<LintDiagnostic & { reason?: string }> = [
+      {
+        file: "test.ts",
+        line: 5,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Suppressed issue",
+        reason: "backwards compat",
+      },
+    ];
+
+    const result = formatSarif(diagnostics, undefined, suppressed);
+    const parsed = JSON.parse(result);
+
+    // Should have 2 results total (1 active + 1 suppressed)
+    expect(parsed.runs[0].results).toHaveLength(2);
+
+    // First result: no suppressions
+    expect(parsed.runs[0].results[0].suppressions).toBeUndefined();
+
+    // Second result: has suppressions
+    expect(parsed.runs[0].results[1].suppressions).toHaveLength(1);
+    expect(parsed.runs[0].results[1].suppressions[0].kind).toBe("inSource");
+    expect(parsed.runs[0].results[1].suppressions[0].justification).toBe("backwards compat");
+  });
+
+  test("suppressed diagnostics without reason omit justification", () => {
+    const suppressed: Array<LintDiagnostic & { reason?: string }> = [
+      {
+        file: "test.ts",
+        line: 5,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Suppressed issue",
+      },
+    ];
+
+    const result = formatSarif([], undefined, suppressed);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].suppressions[0].kind).toBe("inSource");
+    expect(parsed.runs[0].results[0].suppressions[0].justification).toBeUndefined();
+  });
+
+  test("falls back to rule ID when no description available", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "UNKNOWN",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const sarifRule = parsed.runs[0].tool.driver.rules[0];
+
+    expect(sarifRule.shortDescription.text).toBe("UNKNOWN");
+    expect(sarifRule.helpUri).toContain("unknown");
+  });
+
+  test("converts absolute file paths to file:// URIs", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "/Users/test/project/test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const uri = parsed.runs[0].results[0].locations[0].physicalLocation.artifactLocation.uri;
+
+    expect(uri).toMatch(/^file:\/\//);
+  });
 });

package/src/cli/reporters/stylish.ts

@@ -1,4 +1,5 @@
-import type { LintDiagnostic } from "../../lint/rule";
+import type { LintDiagnostic, LintRule, Severity } from "../../lint/rule";
+import { pathToFileURL } from "node:url";
 
 /**
  * ANSI color codes
@@ -121,10 +122,90 @@ export function formatJson(diagnostics: LintDiagnostic[]): string {
   return JSON.stringify(diagnostics, null, 2);
 }
 
+/**
+ * Map lint severity to SARIF level
+ */
+function mapSeverity(severity: Severity): "error" | "warning" | "note" {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note";
+}
+
+/**
+ * Build a SARIF region object, only including endLine/endColumn when available
+ */
+function buildRegion(diag: LintDiagnostic): Record<string, number> {
+  const region: Record<string, number> = {
+    startLine: diag.line,
+    startColumn: diag.column,
+  };
+  if (diag.endLine !== undefined) region.endLine = diag.endLine;
+  if (diag.endColumn !== undefined) region.endColumn = diag.endColumn;
+  return region;
+}
+
+/**
+ * Build a SARIF result from a diagnostic
+ */
+function buildSarifResult(diag: LintDiagnostic, ruleIndex: Map<string, number>) {
+  const result: Record<string, unknown> = {
+    ruleId: diag.ruleId,
+    ruleIndex: ruleIndex.get(diag.ruleId),
+    level: mapSeverity(diag.severity),
+    message: { text: diag.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: diag.file.startsWith("/") ? pathToFileURL(diag.file).href : diag.file,
+          },
+          region: buildRegion(diag),
+        },
+      },
+    ],
+    fingerprints: {
+      "chant/v1": `${diag.ruleId}:${diag.file}:${diag.line}:${diag.column}`,
+    },
+  };
+  return result;
+}
+
 /**
  * Format diagnostics as SARIF (Static Analysis Results Interchange Format)
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param rules - Full list of loaded LintRules for rich metadata (optional)
+ * @param suppressed - Suppressed diagnostics with optional reason (optional)
+ * @param version - Tool version string (optional, defaults to "0.1.0")
  */
-export function formatSarif(diagnostics: LintDiagnostic[]): string {
+export function formatSarif(
+  diagnostics: LintDiagnostic[],
+  rules?: LintRule[],
+  suppressed?: Array<LintDiagnostic & { reason?: string }>,
+  version?: string,
+): string {
+  // Build rule metadata from LintRule objects when available, otherwise from diagnostics
+  const { sarifRules, ruleIndex } = buildRuleMetadata(diagnostics, suppressed ?? [], rules);
+
+  // Build active results
+  const results: Record<string, unknown>[] = diagnostics.map((diag) =>
+    buildSarifResult(diag, ruleIndex),
+  );
+
+  // Append suppressed results with SARIF suppressions
+  if (suppressed) {
+    for (const diag of suppressed) {
+      const result = buildSarifResult(diag, ruleIndex);
+      result.suppressions = [
+        {
+          kind: "inSource",
+          ...(diag.reason ? { justification: diag.reason } : {}),
+        },
+      ];
+      results.push(result);
+    }
+  }
+
   const sarif = {
     $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
     version: "2.1.0",
@@ -133,31 +214,12 @@ export function formatSarif(diagnostics: LintDiagnostic[]): string {
         tool: {
           driver: {
             name: "chant",
-            version: "0.1.0",
+            version: version ?? "0.1.0",
             informationUri: "https://chant.dev",
-            rules: getUniqueRules(diagnostics),
+            rules: sarifRules,
           },
         },
-        results: diagnostics.map((diag) => ({
-          ruleId: diag.ruleId,
-          level: diag.severity === "error" ? "error" : diag.severity === "warning" ? "warning" : "note",
-          message: {
-            text: diag.message,
-          },
-          locations: [
-            {
-              physicalLocation: {
-                artifactLocation: {
-                  uri: diag.file,
-                },
-                region: {
-                  startLine: diag.line,
-                  startColumn: diag.column,
-                },
-              },
-            },
-          ],
-        })),
+        results,
       },
     ],
   };
@@ -166,21 +228,56 @@ export function formatSarif(diagnostics: LintDiagnostic[]): string {
 }
 
 /**
- * Extract unique rules from diagnostics for SARIF
+ * Build SARIF rule metadata from loaded LintRules and/or diagnostics.
+ * Returns both the rules array and a ruleId→index map for result references.
  */
-function getUniqueRules(diagnostics: LintDiagnostic[]): Array<{ id: string; shortDescription: { text: string } }> {
-  const ruleIds = new Set<string>();
-  const rules: Array<{ id: string; shortDescription: { text: string } }> = [];
+function buildRuleMetadata(
+  diagnostics: LintDiagnostic[],
+  suppressed: LintDiagnostic[],
+  rules?: LintRule[],
+): {
+  sarifRules: Record<string, unknown>[];
+  ruleIndex: Map<string, number>;
+} {
+  // Build a lookup from rule objects
+  const ruleMap = new Map<string, LintRule>();
+  if (rules) {
+    for (const r of rules) {
+      ruleMap.set(r.id, r);
+    }
+  }
 
-  for (const diag of diagnostics) {
-    if (!ruleIds.has(diag.ruleId)) {
-      ruleIds.add(diag.ruleId);
-      rules.push({
-        id: diag.ruleId,
-        shortDescription: { text: diag.ruleId },
-      });
+  // Collect all unique rule IDs from diagnostics + suppressed
+  const seen = new Set<string>();
+  const orderedIds: string[] = [];
+  for (const diag of [...diagnostics, ...suppressed]) {
+    if (!seen.has(diag.ruleId)) {
+      seen.add(diag.ruleId);
+      orderedIds.push(diag.ruleId);
+    }
+  }
+
+  const sarifRules: Record<string, unknown>[] = [];
+  const ruleIndex = new Map<string, number>();
+
+  for (const id of orderedIds) {
+    const rule = ruleMap.get(id);
+    const descText = rule?.description || id;
+    const entry: Record<string, unknown> = {
+      id,
+      shortDescription: { text: descText },
+      fullDescription: { text: descText },
+      helpUri: rule?.helpUri || `https://chant.dev/lint-rules/${id.toLowerCase()}`,
+      defaultConfiguration: {
+        level: mapSeverity(rule?.severity ?? "warning"),
+      },
+    };
+    if (rule?.category) {
+      entry.properties = { category: rule.category };
     }
+    ruleIndex.set(id, sarifRules.length);
+    sarifRules.push(entry);
   }
 
-  return rules;
+  return { sarifRules, ruleIndex };
 }