@rettangoli/check 0.0.1

package/src/rules/methods.js

@@ -0,0 +1,117 @@
+import { parseNamedExportedFunctions } from "../core/exportedFunctions.js";
+import { getModelFilePath } from "./shared.js";
+
+const isObjectRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+const getSchemaMethodMap = (model) => {
+  const normalized = model?.schema?.normalized?.methods?.byName;
+  if (normalized instanceof Map) {
+    return normalized;
+  }
+
+  const methodProperties = model?.schema?.yaml?.methods?.properties;
+  if (!isObjectRecord(methodProperties)) {
+    return new Map();
+  }
+
+  return new Map(Object.entries(methodProperties));
+};
+
+const toRequiredObjectKeys = (schemaNode) => {
+  if (!isObjectRecord(schemaNode) || !Array.isArray(schemaNode.required)) {
+    return [];
+  }
+
+  return [...new Set(
+    schemaNode.required
+      .filter((entry) => typeof entry === "string" && entry.trim() === entry && entry.length > 0),
+  )].sort((left, right) => left.localeCompare(right));
+};
+
+export const runMethodRules = ({ models = [] }) => {
+  const diagnostics = [];
+
+  models.forEach((model) => {
+    const methodsPath = getModelFilePath({ model, fileType: "methods" });
+    const exportedFunctions = parseNamedExportedFunctions({
+      sourceText: model?.methods?.sourceText || "",
+      filePath: methodsPath,
+    });
+    const methodSchemaByName = getSchemaMethodMap(model);
+
+    methodSchemaByName.forEach((methodSchema, methodName) => {
+      if (!model?.methods?.exports?.has(methodName)) {
+        return;
+      }
+
+      const functionMeta = exportedFunctions.get(methodName);
+      if (!functionMeta) {
+        return;
+      }
+
+      if (
+        functionMeta.firstParam
+        && !["identifier", "object", "unknown", "none"].includes(functionMeta.firstParam.kind)
+      ) {
+        diagnostics.push({
+          code: "RTGL-CHECK-METHOD-001",
+          severity: "error",
+          filePath: methodsPath,
+          line: functionMeta.line,
+          message: `${model.componentKey}: method '${methodName}' must use an object payload parameter (identifier or object destructuring).`,
+        });
+        return;
+      }
+
+      if (functionMeta.paramCount > 1) {
+        diagnostics.push({
+          code: "RTGL-CHECK-METHOD-002",
+          severity: "warn",
+          filePath: methodsPath,
+          line: functionMeta.line,
+          message: `${model.componentKey}: method '${methodName}' defines ${functionMeta.paramCount} parameters; runtime method invocation passes a single payload object.`,
+        });
+      }
+
+      const requiredPayloadKeys = toRequiredObjectKeys(methodSchema?.payload);
+      if (requiredPayloadKeys.length === 0) {
+        return;
+      }
+
+      if (functionMeta.paramCount < 1) {
+        diagnostics.push({
+          code: "RTGL-CHECK-METHOD-003",
+          severity: "error",
+          filePath: methodsPath,
+          line: functionMeta.line,
+          message: `${model.componentKey}: method '${methodName}' payload contract requires keys [${requiredPayloadKeys.join(", ")}] but method has no payload parameter.`,
+        });
+        return;
+      }
+
+      if (functionMeta.firstParam?.kind !== "object") {
+        return;
+      }
+
+      if (functionMeta.firstParam.hasRest) {
+        return;
+      }
+
+      const presentKeys = new Set(functionMeta.firstParam.objectKeys || []);
+      const missingKeys = requiredPayloadKeys.filter((key) => !presentKeys.has(key));
+      if (missingKeys.length === 0) {
+        return;
+      }
+
+      diagnostics.push({
+        code: "RTGL-CHECK-METHOD-003",
+        severity: "error",
+        filePath: methodsPath,
+        line: functionMeta.line,
+        message: `${model.componentKey}: method '${methodName}' payload contract missing required key(s) [${missingKeys.join(", ")}].`,
+      });
+    });
+  });
+
+  return diagnostics;
+};

package/src/rules/refs.js

@@ -0,0 +1,20 @@
+import { createRefMatchers } from "@rettangoli/fe/contracts";
+import { isObjectRecord } from "./shared.js";
+
+export const collectInvalidRefKeys = (refs) => {
+  const invalidRefKeys = new Set();
+
+  if (!isObjectRecord(refs)) {
+    return invalidRefKeys;
+  }
+
+  Object.entries(refs).forEach(([refKey, refConfig]) => {
+    try {
+      createRefMatchers({ [refKey]: refConfig });
+    } catch {
+      invalidRefKeys.add(refKey);
+    }
+  });
+
+  return invalidRefKeys;
+};

package/src/rules/schema.js

@@ -0,0 +1,118 @@
+import { getModelFilePath, getYamlPathLine, isObjectRecord } from "./shared.js";
+
+const CUSTOM_ELEMENT_NAME_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+
+export const runSchemaRules = ({ models = [] }) => {
+  const diagnostics = [];
+  const componentNameOwners = new Map();
+
+  models.forEach((model) => {
+    const schema = model?.schema?.yaml;
+    const schemaPath = getModelFilePath({ model, fileType: "schema" });
+    const schemaKeyPathLines = model?.schema?.yamlKeyPathLines || new Map();
+    const componentNameLine = getYamlPathLine(schemaKeyPathLines, ["componentName"]);
+
+    if (schema === null || schema === undefined) {
+      return;
+    }
+
+    if (!isObjectRecord(schema)) {
+      diagnostics.push({
+        code: "RTGL-CHECK-SCHEMA-001",
+        severity: "error",
+        filePath: schemaPath,
+        message: `${model.componentKey}: schema must be a YAML object.`,
+      });
+      return;
+    }
+
+    const componentName = schema.componentName;
+    const normalizedComponentName = typeof componentName === "string" ? componentName.trim() : "";
+
+    if (typeof componentName !== "string" || normalizedComponentName === "") {
+      diagnostics.push({
+        code: "RTGL-CHECK-SCHEMA-002",
+        severity: "error",
+        filePath: schemaPath,
+        line: componentNameLine,
+        message: `${model.componentKey}: componentName is required.`,
+      });
+    } else if (componentName !== normalizedComponentName || !CUSTOM_ELEMENT_NAME_REGEX.test(componentName)) {
+      diagnostics.push({
+        code: "RTGL-CHECK-SCHEMA-003",
+        severity: "error",
+        filePath: schemaPath,
+        line: componentNameLine,
+        message: `${model.componentKey}: componentName '${componentName}' must be a valid custom-element tag (kebab-case with at least one '-').`,
+      });
+    } else {
+      if (!componentNameOwners.has(componentName)) {
+        componentNameOwners.set(componentName, []);
+      }
+      componentNameOwners.get(componentName).push({
+        filePath: schemaPath,
+        line: componentNameLine,
+      });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(schema, "attrsSchema")) {
+      diagnostics.push({
+        code: "RTGL-CHECK-SCHEMA-004",
+        severity: "error",
+        filePath: schemaPath,
+        line: getYamlPathLine(schemaKeyPathLines, ["attrsSchema"]),
+        message: `${model.componentKey}: attrsSchema is not supported.`,
+      });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(schema, "methods")) {
+      const methodsSchema = schema.methods;
+      if (!isObjectRecord(methodsSchema)) {
+        diagnostics.push({
+          code: "RTGL-CHECK-SCHEMA-005",
+          severity: "error",
+          filePath: schemaPath,
+          line: getYamlPathLine(schemaKeyPathLines, ["methods"]),
+          message: `${model.componentKey}: methods must be an object schema with a properties map.`,
+        });
+      } else {
+        if (Object.prototype.hasOwnProperty.call(methodsSchema, "type") && methodsSchema.type !== "object") {
+          diagnostics.push({
+            code: "RTGL-CHECK-SCHEMA-006",
+            severity: "error",
+            filePath: schemaPath,
+            line: getYamlPathLine(schemaKeyPathLines, ["methods", "type"]),
+            message: `${model.componentKey}: methods.type must be 'object'.`,
+          });
+        }
+
+        if (!isObjectRecord(methodsSchema.properties)) {
+          diagnostics.push({
+            code: "RTGL-CHECK-SCHEMA-007",
+            severity: "error",
+            filePath: schemaPath,
+            line: getYamlPathLine(schemaKeyPathLines, ["methods", "properties"]),
+            message: `${model.componentKey}: methods.properties must be an object keyed by method name.`,
+          });
+        }
+      }
+    }
+  });
+
+  componentNameOwners.forEach((owners, componentName) => {
+    if (owners.length < 2) {
+      return;
+    }
+    owners.forEach(({ filePath, line }) => {
+      diagnostics.push({
+        code: "RTGL-CHECK-SCHEMA-008",
+        severity: "error",
+        filePath,
+        line,
+        message: `Duplicate componentName '${componentName}' found in multiple schema files.`,
+      });
+    });
+  });
+
+  return diagnostics;
+};

package/src/rules/shared.js

@@ -0,0 +1,20 @@
+const YAML_PATH_SEPARATOR = "\u0000";
+
+const toYamlPathKey = (parts = []) => {
+  return parts.join(YAML_PATH_SEPARATOR);
+};
+
+export const isObjectRecord = (value) => {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+
+export const getYamlPathLine = (keyPathLines, parts = []) => {
+  if (!(keyPathLines instanceof Map)) {
+    return undefined;
+  }
+  return keyPathLines.get(toYamlPathKey(parts));
+};
+
+export const getModelFilePath = ({ model, fileType = "view" } = {}) => {
+  return model?.[fileType]?.filePath || model?.entries?.[0]?.filePath || model?.componentKey || "unknown";
+};

package/src/rules/yahtmlAttrs.js

@@ -0,0 +1,238 @@
+import { toCamelCase, toKebabCase } from "../utils/case.js";
+
+const GENERIC_ALLOWED_ATTRS = new Set([
+  "accesskey",
+  "autocapitalize",
+  "autofocus",
+  "id",
+  "class",
+  "contenteditable",
+  "dir",
+  "draggable",
+  "enterkeyhint",
+  "exportparts",
+  "hidden",
+  "inert",
+  "inputmode",
+  "lang",
+  "nonce",
+  "part",
+  "popover",
+  "itemid",
+  "itemprop",
+  "itemref",
+  "itemscope",
+  "itemtype",
+  "spellcheck",
+  "style",
+  "slot",
+  "tabindex",
+  "title",
+  "translate",
+  "name",
+  "key",
+  "href",
+  "new-tab",
+  "rel",
+]);
+
+const normalizeBindingName = (bindingName = "") => {
+  if (bindingName.startsWith("@")) {
+    return {
+      sourceType: "event",
+      name: bindingName.slice(1),
+    };
+  }
+  if (bindingName.startsWith(":")) {
+    return {
+      sourceType: "prop",
+      name: bindingName.slice(1),
+    };
+  }
+  if (bindingName.startsWith("?")) {
+    return {
+      sourceType: "boolean-attr",
+      name: bindingName.slice(1),
+    };
+  }
+  if (bindingName.startsWith(".")) {
+    return {
+      sourceType: "legacy-prop",
+      name: bindingName.slice(1),
+    };
+  }
+  return {
+    sourceType: "attr",
+    name: bindingName,
+  };
+};
+
+const isDynamicToken = (value = "") => {
+  return (
+    value.includes("${")
+    || value.includes("#{")
+    || value.includes("{{")
+    || value.includes("}")
+    || value.includes("{")
+  );
+};
+
+const toCompactLower = (value = "") => {
+  return String(value).replaceAll("-", "").toLowerCase();
+};
+
+const getGenericAttrCandidates = (attrName = "") => {
+  if (!attrName) {
+    return [];
+  }
+
+  const raw = String(attrName);
+  const lower = raw.toLowerCase();
+  const kebab = toKebabCase(raw);
+  const compact = toCompactLower(kebab);
+
+  return [...new Set([raw, lower, kebab, compact])];
+};
+
+const isGenericAllowed = (attrName = "") => {
+  if (!attrName) {
+    return true;
+  }
+
+  return getGenericAttrCandidates(attrName).some((candidate) => {
+    if (GENERIC_ALLOWED_ATTRS.has(candidate)) {
+      return true;
+    }
+
+    if (candidate.startsWith("aria-") || candidate.startsWith("data-")) {
+      return true;
+    }
+
+    return candidate === "role";
+  });
+};
+
+const isAllowedByContract = ({ attrName, contract }) => {
+  const raw = attrName;
+  const kebab = toKebabCase(attrName);
+  const camel = toCamelCase(attrName);
+
+  return (
+    contract.attrs.has(raw)
+    || contract.attrs.has(kebab)
+    || contract.attrs.has(camel)
+    || contract.props.has(raw)
+    || contract.props.has(kebab)
+    || contract.props.has(camel)
+  );
+};
+
+export const runYahtmlAttrRules = ({ models = [], registry = new Map() }) => {
+  const diagnostics = [];
+
+  models.forEach((model) => {
+    const templateNodes = Array.isArray(model?.view?.templateAst?.nodes)
+      ? model.view.templateAst.nodes
+      : [];
+    const nodeByKey = new Map();
+    templateNodes.forEach((node) => {
+      const key = `${node?.range?.line || 0}::${node?.rawKey || ""}`;
+      nodeByKey.set(key, node);
+    });
+
+    model.view.selectorBindings.forEach((bindingLine) => {
+      const { tagName, bindingNames, filePath, line } = bindingLine;
+      if (!tagName || !tagName.includes("-")) {
+        return;
+      }
+
+      const contract = registry.get(tagName);
+      if (!contract) {
+        diagnostics.push({
+          code: "RTGL-CHECK-YAHTML-001",
+          severity: "error",
+          filePath,
+          line,
+          message: `${model.componentKey}: unknown custom element '${tagName}' in view template.`,
+        });
+        return;
+      }
+
+      const astNode = nodeByKey.get(`${line || 0}::${bindingLine.rawKey || ""}`);
+      const astAttributes = Array.isArray(astNode?.attributes) ? astNode.attributes : [];
+      const astBindingNames = astAttributes
+        .map((attribute) => attribute?.bindingName)
+        .filter(Boolean);
+      const allBindingNames = [...new Set([...(bindingNames || []), ...astBindingNames])];
+
+      allBindingNames.forEach((bindingName) => {
+        if (!bindingName || isDynamicToken(bindingName)) {
+          return;
+        }
+
+        const normalized = normalizeBindingName(bindingName);
+        const matchingAttrNode = astAttributes.find((attribute) => attribute.bindingName === bindingName);
+        const diagnosticColumn = Number.isInteger(matchingAttrNode?.range?.column)
+          ? matchingAttrNode.range.column
+          : undefined;
+        const diagnosticEndColumn = Number.isInteger(matchingAttrNode?.range?.endColumn)
+          ? matchingAttrNode.range.endColumn
+          : undefined;
+
+        if (normalized.sourceType === "legacy-prop") {
+          diagnostics.push({
+            code: "RTGL-CHECK-YAHTML-002",
+            severity: "error",
+            filePath,
+            line,
+            column: diagnosticColumn,
+            endLine: line,
+            endColumn: diagnosticEndColumn,
+            message: `${model.componentKey}: legacy '.${normalized.name}' binding is not supported. Use ':${normalized.name}'.`,
+            fix: {
+              kind: "line-regex-replace",
+              filePath,
+              line,
+              pattern: `\\.${normalized.name.replaceAll(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*=`,
+              replacement: `:${normalized.name}=`,
+              flags: "g",
+              description: `Convert '.${normalized.name}=' to ':${normalized.name}='.`,
+              safe: true,
+              confidence: 0.98,
+            },
+          });
+          return;
+        }
+        if (normalized.sourceType === "event") {
+          return;
+        }
+
+        const attrName = normalized.name;
+        if (!attrName || isDynamicToken(attrName)) {
+          return;
+        }
+
+        if (isGenericAllowed(attrName)) {
+          return;
+        }
+
+        if (isAllowedByContract({ attrName, contract })) {
+          return;
+        }
+
+        diagnostics.push({
+          code: "RTGL-CHECK-YAHTML-003",
+          severity: "error",
+          filePath,
+          line,
+          column: diagnosticColumn,
+          endLine: line,
+          endColumn: diagnosticEndColumn,
+          message: `${model.componentKey}: unsupported attr/prop '${attrName}' on '${tagName}'.`,
+        });
+      });
+    });
+  });
+
+  return diagnostics;
+};