@grexx/grexxlinter 0.2.343 → 0.2.350

package/cli.js

@@ -14456,7 +14456,7 @@ var require__ = __commonJS({
 });
 
 // src/cli.ts
-var import_yaml2 = __toESM(require_dist(), 1);
+var import_yaml3 = __toESM(require_dist(), 1);
 import { readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
 import { availableParallelism } from "node:os";
 import { extname, join as join2, relative } from "node:path";
@@ -14464,6 +14464,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
 
 // src/node.ts
+var import_yaml = __toESM(require_dist(), 1);
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
@@ -14518,9 +14519,11 @@ function createSchemaRegistry(schemas) {
     validateSchema: false
   });
   const casetypes = [];
+  const byId = /* @__PURE__ */ new Map();
   for (const schema of schemas) {
     const id = typeof schema.$id === "string" ? schema.$id : void 0;
     if (!id) continue;
+    byId.set(id, schema);
     if (!ajv.getSchema(id)) ajv.addSchema(schema, id);
     const m = /^https:\/\/grexx\.net\/studio-next\/schemas\/([^/]+)\.schema\.json$/.exec(id);
     if (m) casetypes.push(m[1]);
@@ -14538,12 +14541,81 @@ function createSchemaRegistry(schemas) {
     cache.set(casetype, fn);
     return fn;
   }
+  function resolveRef(ref, base) {
+    const hash = ref.indexOf("#");
+    const path = hash === -1 ? ref : ref.slice(0, hash);
+    const frag = hash === -1 ? "" : ref.slice(hash + 1);
+    let schema;
+    if (path === "") {
+      schema = base;
+    } else {
+      const file = path.replace(/^\.\//, "");
+      schema = byId.get(file.startsWith("http") ? file : `${SCHEMA_ID_BASE}${file}`);
+    }
+    if (!schema) return null;
+    if (!frag) return schema;
+    let cur = schema;
+    for (const raw of frag.split("/").filter(Boolean)) {
+      const key2 = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (cur == null || typeof cur !== "object") return null;
+      cur = cur[key2];
+    }
+    return cur ?? null;
+  }
   return {
     casetypes,
     has: (casetype) => validatorFor(casetype) != null,
-    validatorFor
+    validatorFor,
+    resolveRef
+  };
+}
+
+// src/types.ts
+var DEFAULT_RULE_SEVERITY = {
+  "required-field": "error",
+  "forbidden-field": "error",
+  "additional-field": "warning",
+  "invalid-value": "error",
+  "value-case": "warning",
+  "invalid-type": "error",
+  "invalid-format": "error",
+  "invalid-reference": "error",
+  "unknown-casetype": "warning",
+  "parse-error": "error",
+  schema: "error"
+};
+var DEFAULT_LINTER_SETTINGS = {
+  rules: {},
+  failOn: "error",
+  ignoreCasetypes: [],
+  includeCasetypes: [],
+  reportUncovered: false,
+  include: ["**/*.yaml", "**/*.yml"],
+  exclude: ["node_modules", "dist", ".git"]
+};
+var LINT_RULE_DESCRIPTORS = [
+  { id: "required-field", label: "Required field", description: "A field the casetype state requires (MUST) is missing.", defaultSeverity: "error" },
+  { id: "forbidden-field", label: "Forbidden field", description: "A field present that the casetype state forbids (MUST_NOT).", defaultSeverity: "error" },
+  { id: "additional-field", label: "Additional field", description: "A field not defined by the schema. Allowed in principle, but flagged for review.", defaultSeverity: "warning" },
+  { id: "invalid-value", label: "Invalid value", description: "Value not allowed by an enum / const.", defaultSeverity: "error" },
+  { id: "value-case", label: "Value case mismatch", description: "Value matches an allowed option except for case / camelCase / separators (e.g. FORM vs form).", defaultSeverity: "warning" },
+  { id: "invalid-type", label: "Invalid type", description: "Value has the wrong JSON type.", defaultSeverity: "error" },
+  { id: "invalid-format", label: "Invalid format", description: "Value fails a pattern / format constraint.", defaultSeverity: "error" },
+  { id: "invalid-reference", label: "Invalid reference", description: "A case-reference field points at a file whose `_type` is not in the field's allowedCasetypes.", defaultSeverity: "error" },
+  { id: "unknown-casetype", label: "Unknown casetype", description: "No schema found for the document `_type`.", defaultSeverity: "warning" },
+  { id: "parse-error", label: "Parse error", description: "The YAML document could not be parsed.", defaultSeverity: "error" },
+  { id: "schema", label: "Other schema error", description: "Any other constraint reported by the validator.", defaultSeverity: "error" }
+];
+function normalizeSettings(partial) {
+  return {
+    ...DEFAULT_LINTER_SETTINGS,
+    ...partial,
+    rules: { ...DEFAULT_LINTER_SETTINGS.rules, ...partial?.rules ?? {} }
   };
 }
+function severityFor(rule, settings) {
+  return settings.rules[rule] ?? DEFAULT_RULE_SEVERITY[rule];
+}
 
 // src/node.ts
 var require2 = createRequire(import.meta.url);
@@ -14576,6 +14648,95 @@ function loadCoverage(dir) {
     return null;
   }
 }
+function loadCaseRefs(dir) {
+  const file = join(dir, ".caserefs.json");
+  if (!existsSync(file) || !statSync(file).isFile()) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+var docCache = /* @__PURE__ */ new Map();
+function targetDoc(absPath) {
+  if (docCache.has(absPath)) return docCache.get(absPath);
+  let doc = null;
+  if (existsSync(absPath) && statSync(absPath).isFile()) {
+    try {
+      doc = (0, import_yaml.parse)(readFileSync(absPath, "utf8"));
+    } catch {
+      doc = null;
+    }
+  }
+  docCache.set(absPath, doc);
+  return doc;
+}
+function targetType(absPath, fragment) {
+  const doc = targetDoc(absPath);
+  if (doc == null || typeof doc !== "object") return "not-found";
+  if (!fragment) {
+    const t2 = doc._type;
+    return typeof t2 === "string" ? t2 : null;
+  }
+  let found = null;
+  const walk = (n) => {
+    if (found || !n || typeof n !== "object") return;
+    if (Array.isArray(n)) {
+      n.forEach(walk);
+      return;
+    }
+    const o = n;
+    if (o._uid === fragment) {
+      found = o;
+      return;
+    }
+    for (const v of Object.values(o)) walk(v);
+  };
+  walk(doc);
+  if (!found) return "not-found";
+  const t = found._type;
+  return typeof t === "string" ? t : null;
+}
+var looksLikePath = (s) => s.includes("/") || s.endsWith(".yaml") || s.endsWith(".yml");
+function referenceFindings(value, file, caseRefs, settings) {
+  const sev = severityFor("invalid-reference", settings);
+  if (sev === "off" || Object.keys(caseRefs).length === 0) return [];
+  const baseDir = dirname(file);
+  const out = [];
+  const checkRef = (ref, allowed, casetype, field, path) => {
+    if (!looksLikePath(ref)) return;
+    const frag = /^(.*\.ya?ml)#(.+)$/.exec(ref);
+    const pathPart = frag ? frag[1] : ref;
+    const fragment = frag ? frag[2] : "";
+    const t = targetType(resolve(baseDir, pathPart), fragment);
+    if (t === "not-found") {
+      out.push({ severity: sev, rule: "invalid-reference", casetype, path, field, message: `reference target not found: "${ref}"`, file });
+    } else if (t !== null && !allowed.includes(t)) {
+      out.push({ severity: sev, rule: "invalid-reference", casetype, path, field, message: `field "${field}" references a "${t}" but must reference one of: ${allowed.join(", ")}`, file });
+    }
+  };
+  const walk = (node, path) => {
+    if (Array.isArray(node)) {
+      node.forEach((n, i) => walk(n, `${path}/${i}`));
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    const o = node;
+    const refs = typeof o._type === "string" ? caseRefs[o._type] : void 0;
+    if (refs) {
+      for (const [field, allowed] of Object.entries(refs)) {
+        const v = o[field];
+        if (typeof v === "string") checkRef(v, allowed, o._type, field, `${path}/${field}`);
+        else if (Array.isArray(v)) v.forEach((item, i) => {
+          if (typeof item === "string") checkRef(item, allowed, o._type, field, `${path}/${field}/${i}`);
+        });
+      }
+    }
+    for (const [k, v] of Object.entries(o)) walk(v, `${path}/${k}`);
+  };
+  walk(value, "");
+  return out;
+}
 function createNodeContext(opts = {}) {
   const schemasDir = resolveSchemasDir(opts.schemasDir);
   const registry = createSchemaRegistry(loadSchemasFromDir(schemasDir));
@@ -14584,40 +14745,7 @@ function createNodeContext(opts = {}) {
 }
 
 // src/yaml.ts
-var import_yaml = __toESM(require_dist(), 1);
-
-// src/types.ts
-var DEFAULT_RULE_SEVERITY = {
-  "required-field": "error",
-  "forbidden-field": "error",
-  "unknown-field": "warning",
-  "invalid-value": "error",
-  "value-case": "warning",
-  "invalid-type": "error",
-  "invalid-format": "error",
-  "unknown-casetype": "warning",
-  "parse-error": "error",
-  schema: "error"
-};
-var DEFAULT_LINTER_SETTINGS = {
-  rules: {},
-  failOn: "error",
-  ignoreCasetypes: [],
-  includeCasetypes: [],
-  reportUncovered: false,
-  include: ["**/*.yaml", "**/*.yml"],
-  exclude: ["node_modules", "dist", ".git"]
-};
-function normalizeSettings(partial) {
-  return {
-    ...DEFAULT_LINTER_SETTINGS,
-    ...partial,
-    rules: { ...DEFAULT_LINTER_SETTINGS.rules, ...partial?.rules ?? {} }
-  };
-}
-function severityFor(rule, settings) {
-  return settings.rules[rule] ?? DEFAULT_RULE_SEVERITY[rule];
-}
+var import_yaml2 = __toESM(require_dist(), 1);
 
 // src/lint.ts
 function ruleForKeyword(keyword) {
@@ -14628,7 +14756,7 @@ function ruleForKeyword(keyword) {
       return "forbidden-field";
     case "additionalProperties":
     case "unevaluatedProperties":
-      return "unknown-field";
+      return "additional-field";
     case "const":
     case "enum":
       return "invalid-value";
@@ -14656,7 +14784,7 @@ function humanize(err) {
       return `field "${lastSegment(err.instancePath) ?? ""}" is not allowed for this casetype state`;
     case "additionalProperties":
     case "unevaluatedProperties":
-      return `unknown field "${String(p.additionalProperty)}"`;
+      return `additional field "${String(p.additionalProperty)}" not defined by the schema`;
     case "const":
       return `must equal ${JSON.stringify(p.allowedValue)}`;
     case "enum":
@@ -14683,6 +14811,92 @@ function locate(err) {
   }
   return { field: lastSegment(err.instancePath), path: err.instancePath };
 }
+function collectConsts(cond, out = /* @__PURE__ */ new Map()) {
+  if (!cond || typeof cond !== "object") return out;
+  const c = cond;
+  const props = c.properties;
+  if (props) {
+    for (const [k, sub] of Object.entries(props)) {
+      if (sub && typeof sub === "object" && "const" in sub) {
+        (out.get(k) ?? out.set(k, /* @__PURE__ */ new Set()).get(k)).add(sub.const);
+      }
+    }
+  }
+  for (const key2 of ["allOf", "anyOf", "oneOf"]) {
+    if (Array.isArray(c[key2])) c[key2].forEach((s) => collectConsts(s, out));
+  }
+  return out;
+}
+function parentPointer(pointer) {
+  const i = pointer.lastIndexOf("/");
+  return i <= 0 ? "" : pointer.slice(0, i);
+}
+function fmtStateValue(v) {
+  if (v === void 0 || v === null || v === "") return "null";
+  if (typeof v === "string") return v;
+  if (typeof v === "object") return Array.isArray(v) ? `[${v.length}]` : "{\u2026}";
+  return String(v);
+}
+function deref(schema, resolve2, docRoot) {
+  let cur = schema;
+  for (let i = 0; cur && typeof cur === "object" && typeof cur.$ref === "string" && i < 16; i++) {
+    const ref = cur.$ref;
+    const next = resolve2(ref, docRoot.v ?? void 0);
+    if (!next) break;
+    if (!ref.startsWith("#")) docRoot.v = next;
+    cur = next;
+  }
+  return cur ?? null;
+}
+function propSchema(schema, key2) {
+  const direct = schema.properties;
+  if (direct && key2 in direct) return direct[key2];
+  for (const branch of schema.allOf ?? []) {
+    const t = branch.then ?? branch;
+    const props = t.properties;
+    if (props && key2 in props) return props[key2];
+  }
+  return null;
+}
+function schemaAtPointer(rootSchema, pointer, resolve2) {
+  const docRoot = { v: rootSchema };
+  let schema = deref(rootSchema, resolve2, docRoot);
+  for (const raw of pointer.split("/").filter(Boolean)) {
+    if (!schema) return null;
+    if (/^\d+$/.test(raw)) {
+      let items = schema.items;
+      if (Array.isArray(items)) items = items[Number(raw)] ?? items[0];
+      schema = deref(items, resolve2, docRoot);
+    } else {
+      const key2 = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+      schema = deref(propSchema(schema, key2), resolve2, docRoot);
+    }
+  }
+  return schema;
+}
+function describeState(rootSchema, err, root, resolve2) {
+  const m = /^#\/allOf\/(\d+)\/(then|else)\b/.exec(err.schemaPath);
+  if (!m || !rootSchema || typeof rootSchema !== "object") return null;
+  const branch = m[2];
+  const objPath = err.keyword === "false schema" ? parentPointer(err.instancePath) : err.instancePath;
+  const govSchema = schemaAtPointer(rootSchema, objPath, resolve2);
+  const allOf = govSchema?.allOf;
+  const clause = Array.isArray(allOf) ? allOf[Number(m[1])] : void 0;
+  if (!clause?.if) return null;
+  const consts = collectConsts(clause.if);
+  if (consts.size === 0) return null;
+  const obj = valueAtPointer(root, objPath);
+  if (!obj || typeof obj !== "object") return null;
+  const rec = obj;
+  if (branch === "then") {
+    for (const [field, values] of consts) if (!values.has(rec[field])) return null;
+    const parts2 = [...consts].map(([f, vs]) => `${f}=${fmtStateValue([...vs][0])}`);
+    return `(${parts2.join(", ")})`;
+  }
+  for (const field of consts.keys()) if (!(field in rec)) return null;
+  const parts = [...consts.keys()].map((f) => `${f}=${fmtStateValue(rec[f])}`);
+  return `(${parts.join(", ")})`;
+}
 function valueAtPointer(root, pointer) {
   if (!pointer) return root;
   let cur = root;
@@ -14734,6 +14948,7 @@ function lintDocument(ctx, input) {
     push("unknown-casetype", "", casetype, casetype ? `no schema for casetype "${casetype}"` : "could not determine casetype (no `_type`)");
   } else if (!validate(input.value)) {
     const errors = validate.errors ?? [];
+    const schema = validate.schema;
     const forbidden = /* @__PURE__ */ new Set();
     for (const e of errors) if (e.keyword === "false schema") forbidden.add(e.instancePath);
     for (const e of errors) {
@@ -14752,7 +14967,13 @@ function lintDocument(ctx, input) {
           continue;
         }
       }
-      push(ruleForKeyword(e.keyword), path, field, humanize(e));
+      const rule = ruleForKeyword(e.keyword);
+      let message = humanize(e);
+      if (rule === "forbidden-field" || rule === "required-field") {
+        const state = describeState(schema, e, input.value, ctx.registry.resolveRef);
+        if (state) message += ` ${state}`;
+      }
+      push(rule, path, field, message);
     }
   }
   if (settings.reportUncovered && ctx.coverage && casetype) {
@@ -14793,7 +15014,7 @@ function isLintableYaml(text) {
 // src/cli.ts
 var PARALLEL_THRESHOLD = 200;
 var MAX_WORKERS = 8;
-var VERSION = true ? "0.2.343" : "0.0.0-dev";
+var VERSION = true ? "0.2.350" : "0.0.0-dev";
 function isNewer(latest, current) {
   const a = latest.split(".").map(Number);
   const b = current.split(".").map(Number);
@@ -14812,19 +15033,30 @@ function checkForUpdate(disabled) {
   const timer = setTimeout(() => ctrl.abort(), 1500);
   return fetch("https://registry.npmjs.org/@grexx%2Fgrexxlinter/latest", { signal: ctrl.signal }).then((r) => r.ok ? r.json() : null).then((j) => j?.version && isNewer(j.version, VERSION) ? j.version : null).catch(() => null).finally(() => clearTimeout(timer));
 }
+var VALID_RULES = new Set(LINT_RULE_DESCRIPTORS.map((d) => d.id));
 function parseArgs(argv) {
-  const args = { paths: [], format: "text", quiet: false, noUpdateCheck: false };
+  const args = { paths: [], off: [], format: "text", quiet: false, noUpdateCheck: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--settings") args.settingsFile = argv[++i];
-    else if (a === "--schemas-dir") args.schemasDir = argv[++i];
+    else if (a === "--off") {
+      const list = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      for (const r of list) {
+        if (!VALID_RULES.has(r)) throw new Error(`--off: unknown rule "${r}" (valid: ${[...VALID_RULES].join(", ")})`);
+        args.off.push(r);
+      }
+    } else if (a === "--schemas-dir") args.schemasDir = argv[++i];
     else if (a === "--fail-on") args.failOn = argv[++i];
     else if (a === "--format") args.format = argv[++i];
+    else if (a === "--report") args.report = argv[++i];
     else if (a === "--quiet") args.quiet = true;
     else if (a === "--no-update-check") args.noUpdateCheck = true;
     else if (a.startsWith("--")) throw new Error(`unknown option: ${a}`);
     else args.paths.push(a);
   }
+  if (args.report && args.report !== "rules" && args.report !== "fields") {
+    throw new Error(`--report must be "rules" or "fields" (got "${args.report}")`);
+  }
   if (args.paths.length === 0) args.paths.push(".");
   return args;
 }
@@ -14879,9 +15111,42 @@ function printText(results, settings, quiet) {
 ${s.files} file(s)${skipped ? `, ${skipped} skipped` : ""} \u2014 ${paint(`${s.errors} error(s)`, COLORS.error)}, ${paint(`${s.warnings} warning(s)`, COLORS.warning)}, ${s.infos} info(s) [fail-on: ${settings.failOn}]`
   );
 }
+function printReport(results, kind) {
+  const msgs = results.filter((r) => !r.skipped).flatMap((r) => r.messages);
+  if (kind === "rules") {
+    const by2 = /* @__PURE__ */ new Map();
+    for (const m of msgs) {
+      const e = by2.get(m.rule) ?? { count: 0, severity: m.severity };
+      e.count++;
+      by2.set(m.rule, e);
+    }
+    const rows2 = [...by2.entries()].map(([rule, e]) => ({ count: e.count, rule, severity: e.severity })).sort((a, b) => b.count - a.count);
+    const w = Math.max(5, ...rows2.map((r) => String(r.count).length));
+    console.log(`${"count".padStart(w)}  rule              severity`);
+    for (const r of rows2) {
+      console.log(`${paint(String(r.count).padStart(w), COLORS[r.severity])}  ${r.rule.padEnd(16)}  ${r.severity}`);
+    }
+    return;
+  }
+  const by = /* @__PURE__ */ new Map();
+  for (const m of msgs) {
+    const key2 = `${m.casetype ?? "?"}\0${m.rule}\0${m.severity}\0${m.message}`;
+    const e = by.get(key2) ?? { count: 0, casetype: m.casetype ?? "?", severity: m.severity, message: m.message };
+    e.count++;
+    by.set(key2, e);
+  }
+  const rows = [...by.values()].sort((a, b) => b.count - a.count || a.casetype.localeCompare(b.casetype));
+  const cw = Math.max(5, ...rows.map((r) => String(r.count).length));
+  const tw = Math.max(8, ...rows.map((r) => r.casetype.length));
+  console.log(`${"count".padStart(cw)}  ${"casetype".padEnd(tw)}  severity  message`);
+  for (const r of rows) {
+    console.log(`${paint(String(r.count).padStart(cw), COLORS[r.severity])}  ${r.casetype.padEnd(tw)}  ${r.severity.padEnd(8)}  ${r.message}`);
+  }
+}
 var WORKER_FILE = fileURLToPath2(import.meta.url);
 function lintFiles(files, ctx, settings) {
   const out = [];
+  const caseRefs = loadCaseRefs(ctx.schemasDir);
   const parseErr = (file, message) => ({
     file,
     casetype: null,
@@ -14894,7 +15159,7 @@ function lintFiles(files, ctx, settings) {
     if (!isLintableYaml(text)) continue;
     let docs;
     try {
-      docs = (0, import_yaml2.parseAllDocuments)(text);
+      docs = (0, import_yaml3.parseAllDocuments)(text);
     } catch (e) {
       out.push(parseErr(file, e.message));
       continue;
@@ -14905,7 +15170,13 @@ function lintFiles(files, ctx, settings) {
         continue;
       }
       const input = { value: doc.toJS(), file };
-      out.push(lintDocument({ registry: ctx.registry, coverage: ctx.coverage, settings }, input));
+      const result = lintDocument({ registry: ctx.registry, coverage: ctx.coverage, settings }, input);
+      const refs = referenceFindings(input.value, file, caseRefs, settings);
+      if (refs.length) {
+        result.messages.push(...refs);
+        if (result.ok && refs.some((m) => meetsThreshold(m.severity, settings.failOn))) result.ok = false;
+      }
+      out.push(result);
     }
   }
   return out;
@@ -14946,6 +15217,9 @@ async function main() {
   let partial = {};
   if (args.settingsFile) partial = JSON.parse(readFileSync2(args.settingsFile, "utf8"));
   if (args.failOn) partial = { ...partial, failOn: args.failOn };
+  if (args.off.length > 0) {
+    partial = { ...partial, rules: { ...partial.rules, ...Object.fromEntries(args.off.map((r) => [r, "off"])) } };
+  }
   const settings = normalizeSettings(partial);
   const files = discover(args.paths, settings.exclude);
   const canParallel = WORKER_FILE.endsWith(".js") && files.length > PARALLEL_THRESHOLD;
@@ -14956,7 +15230,9 @@ async function main() {
     const ctx = createNodeContext({ schemasDir: args.schemasDir });
     results = lintFiles(files, ctx, settings);
   }
-  if (args.format === "json") {
+  if (args.report) {
+    printReport(results, args.report);
+  } else if (args.format === "json") {
     const active = results.filter((r) => !r.skipped);
     console.log(JSON.stringify({ summary: summarize(active), results }, null, 2));
   } else {