@objectstack/lint 11.6.0 → 11.9.0

package/dist/index.d.cts

@@ -69,7 +69,7 @@ interface WidgetBindingFinding {
     /** How to fix (or deliberately suppress) it. */
     hint: string;
 }
-type AnyRec$7 = Record<string, unknown>;
+type AnyRec$8 = Record<string, unknown>;
 /**
  * Validate every dashboard widget's dataset binding. Returns the list of
  * findings (empty = clean). Caller decides how to surface them: `error`
@@ -77,7 +77,7 @@ type AnyRec$7 = Record<string, unknown>;
  * should fail validate/build; `warning` findings are advisory and must
  * never fail the build on their own.
  */
-declare function validateWidgetBindings(stack: AnyRec$7): WidgetBindingFinding[];
+declare function validateWidgetBindings(stack: AnyRec$8): WidgetBindingFinding[];
 
 interface ExprIssue {
     where: string;
@@ -90,12 +90,12 @@ interface ExprIssue {
      */
     severity?: 'error' | 'warning';
 }
-type AnyRec$6 = Record<string, unknown>;
+type AnyRec$7 = Record<string, unknown>;
 /**
  * Validate every predicate in the stack. Returns the list of issues (empty =
  * clean). Caller decides how to surface / whether to fail the build.
  */
-declare function validateStackExpressions(stack: AnyRec$6): ExprIssue[];
+declare function validateStackExpressions(stack: AnyRec$7): ExprIssue[];
 
 type StyleSeverity = 'error' | 'warning';
 interface StyleFinding {
@@ -113,14 +113,14 @@ declare const STYLE_CLASSNAME_TAILWIND = "style-classname-tailwind";
 declare const STYLE_RESPONSIVE_NO_BASE = "style-responsive-no-base";
 declare const STYLE_UNKNOWN_CSS_PROPERTY = "style-unknown-css-property";
 declare const STYLE_UNKNOWN_TOKEN = "style-unknown-token";
-type AnyRec$5 = Record<string, unknown>;
+type AnyRec$6 = Record<string, unknown>;
 /**
  * Validate every page's component tree for SDUI styling correctness (ADR-0065).
  * Returns findings (empty = clean). `error` findings describe styles that are
  * silently dropped and should fail validate/build; `warning` findings are
  * advisory (typos, drift, footguns).
  */
-declare function validateResponsiveStyles(stack: AnyRec$5): StyleFinding[];
+declare function validateResponsiveStyles(stack: AnyRec$6): StyleFinding[];
 
 type JsxPageSeverity = 'error' | 'warning';
 interface JsxPageFinding {
@@ -133,8 +133,8 @@ interface JsxPageFinding {
     message: string;
     hint: string;
 }
-type AnyRec$4 = Record<string, unknown>;
-declare function validateJsxPages(stack: AnyRec$4, opts?: {
+type AnyRec$5 = Record<string, unknown>;
+declare function validateJsxPages(stack: AnyRec$5, opts?: {
     manifest?: Manifest;
 }): JsxPageFinding[];
 
@@ -147,8 +147,8 @@ interface ReactPageFinding {
     message: string;
     hint: string;
 }
-type AnyRec$3 = Record<string, unknown>;
-declare function validateReactPages(stack: AnyRec$3): ReactPageFinding[];
+type AnyRec$4 = Record<string, unknown>;
+declare function validateReactPages(stack: AnyRec$4): ReactPageFinding[];
 
 type ReactPropSeverity = 'error' | 'warning';
 interface ReactPropFinding {
@@ -159,8 +159,8 @@ interface ReactPropFinding {
     message: string;
     hint: string;
 }
-type AnyRec$2 = Record<string, unknown>;
-declare function validateReactPageProps(stack: AnyRec$2): ReactPropFinding[];
+type AnyRec$3 = Record<string, unknown>;
+declare function validateReactPageProps(stack: AnyRec$3): ReactPropFinding[];
 
 type SourceStyleSeverity = 'error' | 'warning';
 interface SourceStyleFinding {
@@ -172,8 +172,8 @@ interface SourceStyleFinding {
     hint: string;
 }
 declare const PAGE_SOURCE_CLASSNAME = "page-source-className-tailwind";
-type AnyRec$1 = Record<string, unknown>;
-declare function validatePageSourceStyling(stack: AnyRec$1): SourceStyleFinding[];
+type AnyRec$2 = Record<string, unknown>;
+declare function validatePageSourceStyling(stack: AnyRec$2): SourceStyleFinding[];
 
 /**
  * Build-time record-title diagnostics (ADR-0079).
@@ -217,13 +217,56 @@ interface RecordTitleFinding {
     /** How to fix it. */
     hint: string;
 }
-type AnyRec = Record<string, unknown>;
+type AnyRec$1 = Record<string, unknown>;
 /**
  * Validate every object's record-title declaration. Returns the list of
  * findings (empty = clean). Both rules are advisory (`warning`): the caller
  * must never fail the build on them alone — auto-provision + the `Record #<id>`
  * floor guarantee a resolvable title at runtime.
  */
-declare function validateRecordTitle(stack: AnyRec): RecordTitleFinding[];
+declare function validateRecordTitle(stack: AnyRec$1): RecordTitleFinding[];
+
+/**
+ * Build-time semantic-role diagnostics (ADR-0085).
+ *
+ * The object-level semantic roles (`stageField`, `highlightFields` /
+ * deprecated `compactLayout`, `fieldGroups` + `Field.group`) are pointers
+ * into the object's own field map. A dangling pointer is Zod-valid but
+ * silently inert at render time — the exact "parsed, unmarked, silently
+ * inert" shape ADR-0078 prohibits — so the completeness lint flags it here,
+ * uniformly for `os build`/`os validate`, MCP authoring and hand authors.
+ *
+ * All three rules are warnings, not errors: every consumer degrades
+ * gracefully (an unknown `Field.group` renders in the ungrouped bucket, an
+ * unknown highlight name is skipped, an unknown `stageField` falls back to
+ * heuristics), so nothing is fully broken — but the author almost certainly
+ * typo'd a name and should be told at author time, not discover it by
+ * staring at an unchanged page.
+ */
+declare const FIELD_GROUP_UNDECLARED = "field-group-undeclared";
+declare const FIELD_GROUP_EMPTY = "field-group-empty";
+declare const SEMANTIC_ROLE_FIELD_UNKNOWN = "semantic-role-field-unknown";
+type SemanticRoleSeverity = 'error' | 'warning';
+interface SemanticRoleFinding {
+    /** Always `warning` today — all three rules are advisory (see module note). */
+    severity: SemanticRoleSeverity;
+    /** Diagnostic rule id, e.g. `field-group-undeclared`. */
+    rule: string;
+    /** Human-readable location, e.g. `object "invoice"`. */
+    where: string;
+    /** Config path, e.g. `objects[3]`. */
+    path: string;
+    /** What is wrong. */
+    message: string;
+    /** How to fix it. */
+    hint: string;
+}
+type AnyRec = Record<string, unknown>;
+/**
+ * Validate every object's semantic-role pointers. Returns the list of
+ * findings (empty = clean). Advisory only — the caller must never fail the
+ * build on these alone.
+ */
+declare function validateSemanticRoles(stack: AnyRec): SemanticRoleFinding[];
 
-export { CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type ExprIssue, type JsxPageFinding, type JsxPageSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, validateJsxPages, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateStackExpressions, validateWidgetBindings };
+export { CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, type JsxPageFinding, type JsxPageSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, validateJsxPages, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSemanticRoles, validateStackExpressions, validateWidgetBindings };

package/dist/index.d.ts

@@ -69,7 +69,7 @@ interface WidgetBindingFinding {
     /** How to fix (or deliberately suppress) it. */
     hint: string;
 }
-type AnyRec$7 = Record<string, unknown>;
+type AnyRec$8 = Record<string, unknown>;
 /**
  * Validate every dashboard widget's dataset binding. Returns the list of
  * findings (empty = clean). Caller decides how to surface them: `error`
@@ -77,7 +77,7 @@ type AnyRec$7 = Record<string, unknown>;
  * should fail validate/build; `warning` findings are advisory and must
  * never fail the build on their own.
  */
-declare function validateWidgetBindings(stack: AnyRec$7): WidgetBindingFinding[];
+declare function validateWidgetBindings(stack: AnyRec$8): WidgetBindingFinding[];
 
 interface ExprIssue {
     where: string;
@@ -90,12 +90,12 @@ interface ExprIssue {
      */
     severity?: 'error' | 'warning';
 }
-type AnyRec$6 = Record<string, unknown>;
+type AnyRec$7 = Record<string, unknown>;
 /**
  * Validate every predicate in the stack. Returns the list of issues (empty =
  * clean). Caller decides how to surface / whether to fail the build.
  */
-declare function validateStackExpressions(stack: AnyRec$6): ExprIssue[];
+declare function validateStackExpressions(stack: AnyRec$7): ExprIssue[];
 
 type StyleSeverity = 'error' | 'warning';
 interface StyleFinding {
@@ -113,14 +113,14 @@ declare const STYLE_CLASSNAME_TAILWIND = "style-classname-tailwind";
 declare const STYLE_RESPONSIVE_NO_BASE = "style-responsive-no-base";
 declare const STYLE_UNKNOWN_CSS_PROPERTY = "style-unknown-css-property";
 declare const STYLE_UNKNOWN_TOKEN = "style-unknown-token";
-type AnyRec$5 = Record<string, unknown>;
+type AnyRec$6 = Record<string, unknown>;
 /**
  * Validate every page's component tree for SDUI styling correctness (ADR-0065).
  * Returns findings (empty = clean). `error` findings describe styles that are
  * silently dropped and should fail validate/build; `warning` findings are
  * advisory (typos, drift, footguns).
  */
-declare function validateResponsiveStyles(stack: AnyRec$5): StyleFinding[];
+declare function validateResponsiveStyles(stack: AnyRec$6): StyleFinding[];
 
 type JsxPageSeverity = 'error' | 'warning';
 interface JsxPageFinding {
@@ -133,8 +133,8 @@ interface JsxPageFinding {
     message: string;
     hint: string;
 }
-type AnyRec$4 = Record<string, unknown>;
-declare function validateJsxPages(stack: AnyRec$4, opts?: {
+type AnyRec$5 = Record<string, unknown>;
+declare function validateJsxPages(stack: AnyRec$5, opts?: {
     manifest?: Manifest;
 }): JsxPageFinding[];
 
@@ -147,8 +147,8 @@ interface ReactPageFinding {
     message: string;
     hint: string;
 }
-type AnyRec$3 = Record<string, unknown>;
-declare function validateReactPages(stack: AnyRec$3): ReactPageFinding[];
+type AnyRec$4 = Record<string, unknown>;
+declare function validateReactPages(stack: AnyRec$4): ReactPageFinding[];
 
 type ReactPropSeverity = 'error' | 'warning';
 interface ReactPropFinding {
@@ -159,8 +159,8 @@ interface ReactPropFinding {
     message: string;
     hint: string;
 }
-type AnyRec$2 = Record<string, unknown>;
-declare function validateReactPageProps(stack: AnyRec$2): ReactPropFinding[];
+type AnyRec$3 = Record<string, unknown>;
+declare function validateReactPageProps(stack: AnyRec$3): ReactPropFinding[];
 
 type SourceStyleSeverity = 'error' | 'warning';
 interface SourceStyleFinding {
@@ -172,8 +172,8 @@ interface SourceStyleFinding {
     hint: string;
 }
 declare const PAGE_SOURCE_CLASSNAME = "page-source-className-tailwind";
-type AnyRec$1 = Record<string, unknown>;
-declare function validatePageSourceStyling(stack: AnyRec$1): SourceStyleFinding[];
+type AnyRec$2 = Record<string, unknown>;
+declare function validatePageSourceStyling(stack: AnyRec$2): SourceStyleFinding[];
 
 /**
  * Build-time record-title diagnostics (ADR-0079).
@@ -217,13 +217,56 @@ interface RecordTitleFinding {
     /** How to fix it. */
     hint: string;
 }
-type AnyRec = Record<string, unknown>;
+type AnyRec$1 = Record<string, unknown>;
 /**
  * Validate every object's record-title declaration. Returns the list of
  * findings (empty = clean). Both rules are advisory (`warning`): the caller
  * must never fail the build on them alone — auto-provision + the `Record #<id>`
  * floor guarantee a resolvable title at runtime.
  */
-declare function validateRecordTitle(stack: AnyRec): RecordTitleFinding[];
+declare function validateRecordTitle(stack: AnyRec$1): RecordTitleFinding[];
+
+/**
+ * Build-time semantic-role diagnostics (ADR-0085).
+ *
+ * The object-level semantic roles (`stageField`, `highlightFields` /
+ * deprecated `compactLayout`, `fieldGroups` + `Field.group`) are pointers
+ * into the object's own field map. A dangling pointer is Zod-valid but
+ * silently inert at render time — the exact "parsed, unmarked, silently
+ * inert" shape ADR-0078 prohibits — so the completeness lint flags it here,
+ * uniformly for `os build`/`os validate`, MCP authoring and hand authors.
+ *
+ * All three rules are warnings, not errors: every consumer degrades
+ * gracefully (an unknown `Field.group` renders in the ungrouped bucket, an
+ * unknown highlight name is skipped, an unknown `stageField` falls back to
+ * heuristics), so nothing is fully broken — but the author almost certainly
+ * typo'd a name and should be told at author time, not discover it by
+ * staring at an unchanged page.
+ */
+declare const FIELD_GROUP_UNDECLARED = "field-group-undeclared";
+declare const FIELD_GROUP_EMPTY = "field-group-empty";
+declare const SEMANTIC_ROLE_FIELD_UNKNOWN = "semantic-role-field-unknown";
+type SemanticRoleSeverity = 'error' | 'warning';
+interface SemanticRoleFinding {
+    /** Always `warning` today — all three rules are advisory (see module note). */
+    severity: SemanticRoleSeverity;
+    /** Diagnostic rule id, e.g. `field-group-undeclared`. */
+    rule: string;
+    /** Human-readable location, e.g. `object "invoice"`. */
+    where: string;
+    /** Config path, e.g. `objects[3]`. */
+    path: string;
+    /** What is wrong. */
+    message: string;
+    /** How to fix it. */
+    hint: string;
+}
+type AnyRec = Record<string, unknown>;
+/**
+ * Validate every object's semantic-role pointers. Returns the list of
+ * findings (empty = clean). Advisory only — the caller must never fail the
+ * build on these alone.
+ */
+declare function validateSemanticRoles(stack: AnyRec): SemanticRoleFinding[];
 
-export { CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type ExprIssue, type JsxPageFinding, type JsxPageSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, validateJsxPages, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateStackExpressions, validateWidgetBindings };
+export { CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, type JsxPageFinding, type JsxPageSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, validateJsxPages, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSemanticRoles, validateStackExpressions, validateWidgetBindings };

package/dist/index.js

@@ -939,11 +939,94 @@ function validateRecordTitle(stack) {
   }
   return findings;
 }
+
+// src/validate-semantic-roles.ts
+var FIELD_GROUP_UNDECLARED = "field-group-undeclared";
+var FIELD_GROUP_EMPTY = "field-group-empty";
+var SEMANTIC_ROLE_FIELD_UNKNOWN = "semantic-role-field-unknown";
+function asArray9(v) {
+  if (Array.isArray(v)) return v;
+  if (v && typeof v === "object") {
+    return Object.entries(v).map(([name, def]) => ({ name, ...def }));
+  }
+  return [];
+}
+function validateSemanticRoles(stack) {
+  const findings = [];
+  const objects = asArray9(stack.objects);
+  for (let i = 0; i < objects.length; i++) {
+    const obj = objects[i];
+    if (!obj || typeof obj !== "object") continue;
+    const objName = typeof obj.name === "string" ? obj.name : `(object ${i})`;
+    const where = `object "${objName}"`;
+    const path = `objects[${i}]`;
+    const fields = obj.fields && typeof obj.fields === "object" && !Array.isArray(obj.fields) ? obj.fields : {};
+    const fieldNames = new Set(Object.keys(fields));
+    const declaredGroups = new Set(
+      (Array.isArray(obj.fieldGroups) ? obj.fieldGroups : []).filter((g) => !!g && typeof g === "object").map((g) => g.key).filter((k) => typeof k === "string" && k.length > 0)
+    );
+    const referencedGroups = /* @__PURE__ */ new Set();
+    for (const [fname, f] of Object.entries(fields)) {
+      const g = f?.group;
+      if (typeof g !== "string" || g.length === 0) continue;
+      referencedGroups.add(g);
+      if (!declaredGroups.has(g)) {
+        findings.push({
+          severity: "warning",
+          rule: FIELD_GROUP_UNDECLARED,
+          where,
+          path: `${path}.fields.${fname}.group`,
+          message: `${objName}.${fname}: group "${g}" is not declared in fieldGroups \u2014 the field renders in the ungrouped bucket, not under "${g}"`,
+          hint: `Declare { key: '${g}', label: '\u2026' } in ${objName}.fieldGroups, or fix the field's group reference. Group keys are snake_case and must match exactly.`
+        });
+      }
+    }
+    for (const key of declaredGroups) {
+      if (!referencedGroups.has(key)) {
+        findings.push({
+          severity: "warning",
+          rule: FIELD_GROUP_EMPTY,
+          where,
+          path: `${path}.fieldGroups`,
+          message: `${objName}: fieldGroups declares "${key}" but no field references it \u2014 the group never renders`,
+          hint: `Assign at least one field via group: '${key}', or remove the unused group declaration.`
+        });
+      }
+    }
+    const stage = obj.stageField;
+    if (typeof stage === "string" && stage.length > 0 && !fieldNames.has(stage)) {
+      findings.push({
+        severity: "warning",
+        rule: SEMANTIC_ROLE_FIELD_UNKNOWN,
+        where,
+        path: `${path}.stageField`,
+        message: `${objName}: stageField "${stage}" is not a field on this object \u2014 consumers fall back to heuristic stage detection`,
+        hint: `Point stageField at an existing select/status field, or set stageField: false to declare the object has no linear lifecycle.`
+      });
+    }
+    const highlights = Array.isArray(obj.highlightFields) ? obj.highlightFields : Array.isArray(obj.compactLayout) ? obj.compactLayout : [];
+    for (const entry of highlights) {
+      if (typeof entry !== "string" || entry.length === 0 || fieldNames.has(entry)) continue;
+      findings.push({
+        severity: "warning",
+        rule: SEMANTIC_ROLE_FIELD_UNKNOWN,
+        where,
+        path: `${path}.highlightFields`,
+        message: `${objName}: highlightFields entry "${entry}" is not a field on this object \u2014 it is silently skipped by every consumer`,
+        hint: `Fix the field name (highlightFields drives default columns, cards, previews and the detail highlight strip, in order).`
+      });
+    }
+  }
+  return findings;
+}
 export {
   CHART_CONFIG_MISSING,
   CHART_FIELD_UNKNOWN,
+  FIELD_GROUP_EMPTY,
+  FIELD_GROUP_UNDECLARED,
   MEASURE_AGGREGATE_INCOHERENT,
   PAGE_SOURCE_CLASSNAME,
+  SEMANTIC_ROLE_FIELD_UNKNOWN,
   STYLE_CLASSNAME_TAILWIND,
   STYLE_NODE_MISSING_ID,
   STYLE_RESPONSIVE_NO_BASE,
@@ -961,6 +1044,7 @@ export {
   validateReactPages,
   validateRecordTitle,
   validateResponsiveStyles,
+  validateSemanticRoles,
   validateStackExpressions,
   validateWidgetBindings
 };