@rettangoli/check 0.0.1

package/src/core/semantic.js

@@ -0,0 +1,329 @@
+import { toCamelCase } from "../utils/case.js";
+import { parseSync } from "oxc-parser";
+import { JEMPL_NODE, parseJemplForCompiler } from "./parsers.js";
+
+const BUILTIN_ALLOWED_ROOTS = new Set([
+  "_event",
+  "_action",
+  "event",
+  "state",
+  "props",
+  "refs",
+  "constants",
+  "window",
+  "document",
+  "Math",
+  "Number",
+  "String",
+  "Boolean",
+  "Object",
+  "Array",
+  "Date",
+  "JSON",
+  "console",
+]);
+
+const RESERVED_WORDS = new Set([
+  "if",
+  "else",
+  "for",
+  "while",
+  "switch",
+  "case",
+  "break",
+  "continue",
+  "return",
+  "throw",
+  "try",
+  "catch",
+  "finally",
+  "new",
+  "typeof",
+  "instanceof",
+  "in",
+  "void",
+  "delete",
+  "await",
+  "async",
+  "true",
+  "false",
+  "null",
+  "undefined",
+]);
+
+const stripStringLiterals = (source = "") => {
+  return source.replace(/(['"`])(?:\\.|(?!\1)[^\\])*\1/gu, " ");
+};
+
+const extractExpressionRootIdentifiersRegexFallback = (expression = "") => {
+  const source = stripStringLiterals(String(expression));
+  const roots = new Set();
+  const regex = /(?:^|[^.\w$])([A-Za-z_$][A-Za-z0-9_$]*)/g;
+  let match = regex.exec(source);
+
+  while (match) {
+    const candidate = match[1];
+    if (!candidate || RESERVED_WORDS.has(candidate)) {
+      match = regex.exec(source);
+      continue;
+    }
+    roots.add(candidate);
+    match = regex.exec(source);
+  }
+
+  return [...roots];
+};
+
+const toPathRootIdentifier = (pathExpression = "") => {
+  const match = String(pathExpression || "").trim().match(/^([A-Za-z_$][A-Za-z0-9_$]*)/u);
+  if (!match) {
+    return null;
+  }
+  return match[1];
+};
+
+const collectExpressionRootIdentifiersFromAst = (expressionAst) => {
+  const roots = new Set();
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach((item) => visit(item));
+      return;
+    }
+    if (!node || typeof node !== "object") {
+      return;
+    }
+
+    if (node.type === JEMPL_NODE.PATH && typeof node.path === "string") {
+      const root = toPathRootIdentifier(node.path);
+      if (root && !RESERVED_WORDS.has(root)) {
+        roots.add(root);
+      }
+    }
+
+    Object.values(node).forEach((value) => visit(value));
+  };
+
+  visit(expressionAst);
+  return [...roots];
+};
+
+const collectObjectExpressionKeys = (node) => {
+  if (!node || node.type !== "ObjectExpression" || !Array.isArray(node.properties)) {
+    return [];
+  }
+
+  const keys = [];
+  node.properties.forEach((property) => {
+    if (!property || property.type !== "Property") {
+      return;
+    }
+    if (property.computed) {
+      return;
+    }
+    const keyNode = property.key;
+    if (keyNode?.type === "Identifier" && keyNode.name) {
+      keys.push(keyNode.name);
+      return;
+    }
+    if (
+      keyNode?.type === "StringLiteral"
+      || keyNode?.type === "Literal"
+      || keyNode?.type === "NumericLiteral"
+    ) {
+      const value = keyNode.value;
+      if (typeof value === "string" && value) {
+        keys.push(value);
+      }
+    }
+  });
+  return keys;
+};
+
+const collectReturnObjectKeysFromFunctionNode = (functionNode) => {
+  if (!functionNode || typeof functionNode !== "object") {
+    return [];
+  }
+
+  if (functionNode.body?.type === "ObjectExpression") {
+    return collectObjectExpressionKeys(functionNode.body);
+  }
+
+  if (functionNode.body?.type !== "BlockStatement" || !Array.isArray(functionNode.body.body)) {
+    return [];
+  }
+
+  for (let index = 0; index < functionNode.body.body.length; index += 1) {
+    const statement = functionNode.body.body[index];
+    if (!statement || statement.type !== "ReturnStatement") {
+      continue;
+    }
+    return collectObjectExpressionKeys(statement.argument);
+  }
+
+  return [];
+};
+
+export const collectSelectViewDataRoots = (sourceText = "", filePath = "unknown.js") => {
+  const roots = new Set();
+  if (!sourceText) {
+    return roots;
+  }
+
+  let parsed = null;
+  try {
+    parsed = parseSync(filePath, sourceText, { sourceType: "unambiguous" });
+  } catch {
+    return roots;
+  }
+  if (!parsed?.program?.body || !Array.isArray(parsed.program.body)) {
+    return roots;
+  }
+  if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+    return roots;
+  }
+
+  parsed.program.body.forEach((statement) => {
+    if (!statement || statement.type !== "ExportNamedDeclaration" || !statement.declaration) {
+      return;
+    }
+
+    const declaration = statement.declaration;
+    if (declaration.type === "FunctionDeclaration" && declaration.id?.name === "selectViewData") {
+      collectReturnObjectKeysFromFunctionNode(declaration).forEach((key) => roots.add(key));
+      return;
+    }
+
+    if (declaration.type === "VariableDeclaration" && Array.isArray(declaration.declarations)) {
+      declaration.declarations.forEach((declarator) => {
+        if (declarator?.id?.name !== "selectViewData") {
+          return;
+        }
+        const init = declarator.init;
+        if (!init || (init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression")) {
+          return;
+        }
+        collectReturnObjectKeysFromFunctionNode(init).forEach((key) => roots.add(key));
+      });
+    }
+  });
+
+  return roots;
+};
+
+const isNumericLiteral = (value = "") => {
+  return /^[-+]?(?:\d+\.?\d*|\d*\.?\d+)$/u.test(value.trim());
+};
+
+export const extractExpressionRootIdentifiers = (expression = "") => {
+  const normalizedExpression = String(expression || "").trim();
+  if (!normalizedExpression) {
+    return [];
+  }
+
+  const parsedExpression = parseJemplForCompiler({ source: normalizedExpression });
+  if (parsedExpression?.ast && !parsedExpression.parseError) {
+    const astRoots = collectExpressionRootIdentifiersFromAst(parsedExpression.ast);
+    if (astRoots.length > 0) {
+      return astRoots;
+    }
+  }
+
+  return extractExpressionRootIdentifiersRegexFallback(normalizedExpression);
+};
+
+export const collectKnownExpressionRoots = (model) => {
+  const known = new Set(BUILTIN_ALLOWED_ROOTS);
+  const normalizedPropNames = model?.schema?.normalized?.props?.names;
+  if (Array.isArray(normalizedPropNames) && normalizedPropNames.length > 0) {
+    normalizedPropNames.forEach((propName) => {
+      if (!propName) {
+        return;
+      }
+      known.add(propName);
+      known.add(toCamelCase(propName));
+    });
+  } else {
+    const schemaProperties = model?.schema?.yaml?.propsSchema?.properties;
+    if (schemaProperties && typeof schemaProperties === "object" && !Array.isArray(schemaProperties)) {
+      Object.keys(schemaProperties).forEach((propName) => {
+        if (!propName) {
+          return;
+        }
+        known.add(propName);
+        known.add(toCamelCase(propName));
+      });
+    }
+  }
+
+  const constants = model?.constants?.yaml;
+  if (constants && typeof constants === "object" && !Array.isArray(constants)) {
+    Object.keys(constants).forEach((constantName) => {
+      if (constantName) {
+        known.add(constantName);
+      }
+    });
+  }
+
+  [model?.handlers?.exports, model?.methods?.exports, model?.store?.exports].forEach((exportSet) => {
+    if (exportSet instanceof Set) {
+      exportSet.forEach((name) => {
+        if (name) {
+          known.add(name);
+        }
+      });
+    }
+  });
+
+  collectSelectViewDataRoots(
+    model?.store?.sourceText || "",
+    model?.store?.filePath || "unknown.store.js",
+  ).forEach((key) => known.add(key));
+
+  return known;
+};
+
+export const collectTemplateExpressionReferences = (model) => {
+  const references = [];
+  const nodes = Array.isArray(model?.view?.templateAst?.nodes) ? model.view.templateAst.nodes : [];
+
+  nodes.forEach((node) => {
+    const attributes = Array.isArray(node?.attributes) ? node.attributes : [];
+    attributes.forEach((attribute) => {
+      const sourceType = String(attribute?.sourceType || "");
+      if (sourceType === "legacy-prop" || sourceType === "event") {
+        return;
+      }
+
+      const expressions = Array.isArray(attribute?.expressions) ? attribute.expressions : [];
+      expressions.forEach((expression) => {
+        const roots = extractExpressionRootIdentifiers(expression);
+        references.push({
+          expression,
+          roots,
+          line: attribute?.range?.line || node?.range?.line,
+          column: attribute?.range?.column,
+          endLine: attribute?.range?.endLine || node?.range?.endLine,
+          endColumn: attribute?.range?.endColumn,
+        });
+      });
+    });
+  });
+
+  return references;
+};
+
+export const isUnknownExpressionRoot = ({
+  root = "",
+  knownRoots = new Set(),
+}) => {
+  if (!root) {
+    return false;
+  }
+  if (knownRoots.has(root)) {
+    return false;
+  }
+  if (isNumericLiteral(root)) {
+    return false;
+  }
+  return true;
+};

package/src/diagnostics/autofix.js

@@ -0,0 +1,191 @@
+import { readFileSync, writeFileSync } from "node:fs";
+
+const toLineOffset = ({ lines = [], line = 1, column = 1 }) => {
+  const lineIndex = Math.max(1, line) - 1;
+  const prefix = lines.slice(0, lineIndex).join("\n");
+  const prefixLength = prefix.length + (lineIndex > 0 ? 1 : 0);
+  return prefixLength + Math.max(1, column) - 1;
+};
+
+const normalizeFix = (fix = {}, diagnostic = {}) => {
+  if (!fix || typeof fix !== "object") {
+    return null;
+  }
+  const filePath = typeof fix.filePath === "string" && fix.filePath
+    ? fix.filePath
+    : diagnostic.filePath;
+  if (!filePath || filePath === "unknown") {
+    return null;
+  }
+
+  return {
+    kind: String(fix.kind || ""),
+    filePath,
+    line: Number.isInteger(fix.line) ? fix.line : undefined,
+    column: Number.isInteger(fix.column) ? fix.column : undefined,
+    endLine: Number.isInteger(fix.endLine) ? fix.endLine : undefined,
+    endColumn: Number.isInteger(fix.endColumn) ? fix.endColumn : undefined,
+    pattern: typeof fix.pattern === "string" ? fix.pattern : undefined,
+    replacement: typeof fix.replacement === "string" ? fix.replacement : "",
+    flags: typeof fix.flags === "string" ? fix.flags : "g",
+    description: typeof fix.description === "string" ? fix.description : "autofix",
+    confidence: Number.isFinite(fix.confidence) ? Number(fix.confidence) : 0,
+    safe: fix.safe !== false,
+  };
+};
+
+const buildUnifiedPatch = ({ filePath, before, after }) => {
+  const beforeLines = String(before).split("\n");
+  const afterLines = String(after).split("\n");
+
+  let startIndex = 0;
+  while (
+    startIndex < beforeLines.length
+    && startIndex < afterLines.length
+    && beforeLines[startIndex] === afterLines[startIndex]
+  ) {
+    startIndex += 1;
+  }
+
+  let endBeforeIndex = beforeLines.length - 1;
+  let endAfterIndex = afterLines.length - 1;
+  while (
+    endBeforeIndex >= startIndex
+    && endAfterIndex >= startIndex
+    && beforeLines[endBeforeIndex] === afterLines[endAfterIndex]
+  ) {
+    endBeforeIndex -= 1;
+    endAfterIndex -= 1;
+  }
+
+  const removed = beforeLines.slice(startIndex, endBeforeIndex + 1);
+  const added = afterLines.slice(startIndex, endAfterIndex + 1);
+  const startLine = startIndex + 1;
+  const fromCount = Math.max(0, removed.length);
+  const toCount = Math.max(0, added.length);
+
+  const lines = [
+    `--- ${filePath}`,
+    `+++ ${filePath}`,
+    `@@ -${startLine},${fromCount} +${startLine},${toCount} @@`,
+    ...removed.map((line) => `-${line}`),
+    ...added.map((line) => `+${line}`),
+  ];
+
+  return lines.join("\n");
+};
+
+export const applyDiagnosticFixes = ({
+  diagnostics = [],
+  dryRun = true,
+  minConfidence = 0.9,
+  includePatchText = false,
+} = {}) => {
+  const files = new Map();
+  const patches = [];
+  let candidateCount = 0;
+  let appliedCount = 0;
+  let skippedCount = 0;
+
+  const getFileState = (filePath) => {
+    if (!files.has(filePath)) {
+      const content = readFileSync(filePath, "utf8");
+      files.set(filePath, {
+        original: content,
+        content,
+      });
+    }
+    return files.get(filePath);
+  };
+
+  diagnostics.forEach((diagnostic) => {
+    const fix = normalizeFix(diagnostic.fix, diagnostic);
+    if (!fix) {
+      return;
+    }
+
+    candidateCount += 1;
+    if (!fix.safe || fix.confidence < minConfidence) {
+      skippedCount += 1;
+      return;
+    }
+
+    const state = getFileState(fix.filePath);
+    const before = state.content;
+    let after = before;
+
+    if (fix.kind === "line-regex-replace") {
+      const lines = before.split("\n");
+      const lineIndex = (fix.line || 1) - 1;
+      if (lineIndex < 0 || lineIndex >= lines.length || !fix.pattern) {
+        skippedCount += 1;
+        return;
+      }
+
+      const regex = new RegExp(fix.pattern, fix.flags || "g");
+      const replacedLine = lines[lineIndex].replace(regex, fix.replacement);
+      if (replacedLine === lines[lineIndex]) {
+        skippedCount += 1;
+        return;
+      }
+      lines[lineIndex] = replacedLine;
+      after = lines.join("\n");
+    } else if (fix.kind === "replace-range") {
+      if (!Number.isInteger(fix.line) || !Number.isInteger(fix.column) || !Number.isInteger(fix.endColumn)) {
+        skippedCount += 1;
+        return;
+      }
+
+      const lines = before.split("\n");
+      const start = toLineOffset({ lines, line: fix.line, column: fix.column });
+      const end = toLineOffset({ lines, line: fix.endLine || fix.line, column: fix.endColumn });
+      if (end <= start || start < 0 || end > before.length) {
+        skippedCount += 1;
+        return;
+      }
+      after = `${before.slice(0, start)}${fix.replacement}${before.slice(end)}`;
+    } else {
+      skippedCount += 1;
+      return;
+    }
+
+    if (after === before) {
+      skippedCount += 1;
+      return;
+    }
+
+    state.content = after;
+    appliedCount += 1;
+    const patch = {
+      code: diagnostic.code,
+      filePath: fix.filePath,
+      line: fix.line,
+      description: fix.description,
+      confidence: fix.confidence,
+    };
+    if (includePatchText) {
+      patch.patch = buildUnifiedPatch({
+        filePath: fix.filePath,
+        before,
+        after,
+      });
+    }
+    patches.push(patch);
+  });
+
+  if (!dryRun) {
+    files.forEach((state, filePath) => {
+      if (state.content !== state.original) {
+        writeFileSync(filePath, state.content, "utf8");
+      }
+    });
+  }
+
+  return {
+    candidateCount,
+    appliedCount,
+    skippedCount,
+    dryRun,
+    patches,
+  };
+};

package/src/diagnostics/catalog.js

@@ -0,0 +1,89 @@
+const CODE_NAMESPACE_REGEX = /^RTGL-(CHECK|CONTRACT|CLI|IR)-[A-Z0-9-]+-\d{3}$/;
+
+const DEFAULT_FAMILY_CONFIG = [
+  { prefix: "RTGL-CHECK-YAHTML-", family: "template", severity: "error", title: "YAHTML template diagnostic" },
+  { prefix: "RTGL-CHECK-JEMPL-", family: "template", severity: "error", title: "Jempl template diagnostic" },
+  { prefix: "RTGL-CHECK-EXPR-", family: "expression", severity: "error", title: "Expression diagnostic" },
+  { prefix: "RTGL-CHECK-SCHEMA-", family: "schema", severity: "error", title: "Schema diagnostic" },
+  { prefix: "RTGL-CHECK-SYMBOL-", family: "symbols", severity: "error", title: "Symbol resolution diagnostic" },
+  { prefix: "RTGL-CHECK-LISTENER-", family: "listeners", severity: "error", title: "Listener contract diagnostic" },
+  { prefix: "RTGL-CHECK-REF-", family: "refs", severity: "error", title: "Ref contract diagnostic" },
+  { prefix: "RTGL-CHECK-HANDLER-", family: "handlers", severity: "error", title: "Handler contract diagnostic" },
+  { prefix: "RTGL-CHECK-LIFECYCLE-", family: "lifecycle", severity: "error", title: "Lifecycle contract diagnostic" },
+  { prefix: "RTGL-CHECK-COMPAT-", family: "compatibility", severity: "error", title: "Compatibility diagnostic" },
+  { prefix: "RTGL-CHECK-METHOD-", family: "methods", severity: "error", title: "Method contract diagnostic" },
+  { prefix: "RTGL-CHECK-CONTRACT-", family: "contracts", severity: "error", title: "Contract diagnostic" },
+  { prefix: "RTGL-CONTRACT-", family: "contracts", severity: "error", title: "Legacy contract diagnostic" },
+  { prefix: "RTGL-CHECK-SEM-", family: "semantic", severity: "warn", title: "Semantic engine diagnostic" },
+  { prefix: "RTGL-CHECK-SEM-INV-", family: "semantic-invariants", severity: "error", title: "Semantic invariant diagnostic" },
+  { prefix: "RTGL-CHECK-CONSTANTS-", family: "constants", severity: "error", title: "Constants diagnostic" },
+  { prefix: "RTGL-CHECK-COMPONENT-", family: "component-identity", severity: "error", title: "Component identity diagnostic" },
+  { prefix: "RTGL-CHECK-READ-", family: "io", severity: "error", title: "Read/input diagnostic" },
+  { prefix: "RTGL-CHECK-PARSE-", family: "parse", severity: "error", title: "Parse diagnostic" },
+  { prefix: "RTGL-IR-VAL-", family: "ir-validation", severity: "error", title: "IR validation diagnostic" },
+  { prefix: "RTGL-IR-INV-", family: "ir-invariants", severity: "error", title: "IR invariant diagnostic" },
+  { prefix: "RTGL-CLI-", family: "cli", severity: "error", title: "CLI runtime diagnostic" },
+];
+
+const CATALOG_VERSION = 1;
+
+const CODE_OVERRIDES = {
+  "RTGL-CONTRACT-003": {
+    title: "Legacy dot-prop binding",
+    description: "Legacy '.prop=' template bindings are unsupported and should be converted to ':prop='.",
+    tags: ["autofix-safe", "template"],
+  },
+  "RTGL-CHECK-YAHTML-002": {
+    title: "Legacy YAHTML prop binding",
+    description: "Legacy '.prop' YAHTML binding is unsupported and should be converted to ':prop'.",
+    tags: ["autofix-safe", "template"],
+  },
+  "RTGL-CLI-001": {
+    title: "CLI runtime failure",
+    description: "CLI encountered invalid input or runtime execution failure.",
+    tags: ["cli"],
+  },
+};
+
+const findFamilyConfig = (code = "") => {
+  return DEFAULT_FAMILY_CONFIG.find((entry) => code.startsWith(entry.prefix)) || {
+    family: "general",
+    severity: "error",
+    title: "General diagnostic",
+  };
+};
+
+const codeToDocsAnchor = (code = "") => {
+  return `docs/diagnostics-reference.md#${code.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-")}`;
+};
+
+export const isValidDiagnosticCodeNamespace = (code = "") => {
+  return CODE_NAMESPACE_REGEX.test(String(code));
+};
+
+export const getDiagnosticCatalogEntry = (code = "") => {
+  const normalizedCode = String(code || "RTGL-CHECK-UNKNOWN");
+  const familyConfig = findFamilyConfig(normalizedCode);
+  const override = CODE_OVERRIDES[normalizedCode] || {};
+
+  return {
+    version: CATALOG_VERSION,
+    code: normalizedCode,
+    family: override.family || familyConfig.family,
+    title: override.title || familyConfig.title,
+    description: override.description || `${familyConfig.title}.`,
+    defaultSeverity: override.defaultSeverity || familyConfig.severity,
+    namespaceValid: isValidDiagnosticCodeNamespace(normalizedCode),
+    docsPath: override.docsPath || codeToDocsAnchor(normalizedCode),
+    tags: Array.isArray(override.tags) ? [...override.tags] : [familyConfig.family],
+  };
+};
+
+export const buildDiagnosticCatalog = (codes = []) => {
+  const unique = [...new Set((Array.isArray(codes) ? codes : []).map((code) => String(code || "")).filter(Boolean))]
+    .sort((left, right) => left.localeCompare(right));
+
+  return unique.map((code) => getDiagnosticCatalogEntry(code));
+};
+
+export const DIAGNOSTIC_CATALOG_VERSION = CATALOG_VERSION;

package/src/index.js

@@ -0,0 +1,2 @@
+export { analyzeProject } from "./core/analyze.js";
+export { runSemanticEngine } from "./semantic/engine.js";

package/src/reporters/index.js

@@ -0,0 +1,13 @@
+import { formatJsonReport } from "./json.js";
+import { formatSarifReport } from "./sarif.js";
+import { formatTextReport } from "./text.js";
+
+export const formatReport = ({ format = "text", result, warnAsError = false }) => {
+  if (format === "json") {
+    return formatJsonReport({ result, warnAsError });
+  }
+  if (format === "sarif") {
+    return formatSarifReport({ result });
+  }
+  return formatTextReport({ result, warnAsError });
+};

package/src/reporters/json.js

@@ -0,0 +1,42 @@
+import { buildDiagnosticCatalog, DIAGNOSTIC_CATALOG_VERSION } from "../diagnostics/catalog.js";
+
+const compareDiagnostics = (left = {}, right = {}) => {
+  const leftLine = Number.isInteger(left.line) ? left.line : 0;
+  const rightLine = Number.isInteger(right.line) ? right.line : 0;
+  const leftColumn = Number.isInteger(left.column) ? left.column : 0;
+  const rightColumn = Number.isInteger(right.column) ? right.column : 0;
+
+  return (
+    String(left.code || "").localeCompare(String(right.code || ""))
+    || String(left.severity || "").localeCompare(String(right.severity || ""))
+    || String(left.filePath || "").localeCompare(String(right.filePath || ""))
+    || leftLine - rightLine
+    || leftColumn - rightColumn
+    || String(left.message || "").localeCompare(String(right.message || ""))
+  );
+};
+
+export const formatJsonReport = ({ result, warnAsError = false }) => {
+  const effectiveErrors = result.summary.bySeverity.error
+    + (warnAsError ? result.summary.bySeverity.warn : 0);
+  const diagnostics = Array.isArray(result.diagnostics)
+    ? [...result.diagnostics].sort(compareDiagnostics)
+    : [];
+  const catalog = buildDiagnosticCatalog(diagnostics.map((diagnostic) => diagnostic.code));
+
+  return JSON.stringify({
+    $schema: "docs/diagnostics-json-schema-v1.json",
+    schemaVersion: 1,
+    contractVersion: 1,
+    reportFormat: "json",
+    diagnosticCatalogVersion: DIAGNOSTIC_CATALOG_VERSION,
+    ok: effectiveErrors === 0,
+    componentCount: result.componentCount,
+    registryTagCount: result.registryTagCount,
+    summary: result.summary,
+    warnAsError,
+    diagnosticCatalog: catalog,
+    autofix: result.autofix || undefined,
+    diagnostics,
+  }, null, 2);
+};