@metaobjectsdev/metadata 1.0.12 → 1.1.0

package/src/index.ts

@@ -42,9 +42,52 @@ export * from "./core/identity/identity-constants.js";
 export * from "./core/index/index-constants.js";
 export * from "./core/requirement/requirement-constants.js";
 export { MetaRequirement } from "./core/requirement/meta-requirement.js";
+export * from "./core/reporting/reporting-constants.js";
+export { MetaDimension } from "./core/reporting/meta-dimension.js";
+export { MetaMeasure } from "./core/reporting/meta-measure.js";
+export { MetaSegment } from "./core/reporting/meta-segment.js";
+export {
+  reportFrom,
+  reportSpine,
+  reportDimensionItems,
+  reportMeasureNames,
+  reportMeasureItemName,
+  reportMeasureItemOwner,
+  reportDerivedFieldName,
+  type ReportDimensionItem,
+} from "./core/reporting/report-accessors.js";
+export {
+  measureDerivedSubType,
+  reportShape,
+  reportSpineEntity,
+  reportSpineHops,
+  reportingMemberOwner,
+  reportingViaHops,
+  resolveReportingFieldRef,
+  resolveDimensionOf,
+  type ReportField,
+  type ReportFieldRole,
+  type ReportShape,
+} from "./core/reporting/report-shape.js";
+export { reportReadModel, reportReadSource } from "./core/reporting/report-read-model.js";
+export {
+  describeDimension,
+  describeDimensionColumn,
+  describeFilter,
+  describeMeasure,
+  describeReportField,
+  describeReportRowScope,
+  describeReportRows,
+  describeRowScope,
+  describeSegment,
+  reportFieldTypeName,
+  reportNotServedReason,
+  reportingDescribedAttrs,
+} from "./core/reporting/report-describe.js";
 // Shared `@implementedBy` resolution — one resolver for the CLI's requirement
 // checks and codegen's requirement-test fan-out (FR-038).
 export {
+  effectiveRequirementPackage,
   resolveClaim,
   resolveClaimTarget,
   resolveMember,
@@ -81,6 +124,9 @@ export {
 // Core node classes
 export { MetaObject } from "./core/object/meta-object.js";
 export { MetaField } from "./core/field/meta-field.js";
+// The one authority for "which type does this enum field have" — the loader's #246
+// check and every codegen site share it (ADR-0026 Amendment 1).
+export { isSharedEnumDeclaration, resolveSharedEnumDeclaration } from "./core/field/shared-enum.js";
 export { MetaAttr } from "./core/attr/meta-attr.js";
 
 // Runtime object model — backing objects + FQN→factory binding (Phase A).
@@ -193,7 +239,7 @@ export { ExclusionReason } from "./registry-manifest-exclusions.js";
 
 // FR-033 S3 — metamodel doc-gen: tiered, LLM-readable docs FOR THE METAMODEL
 // (the type/subtype/attr vocabulary), generated from the strict registry.
-// Distinct from `meta docs --model` (which documents a user's entities).
+// Distinct from the `docs` generator (which documents a user's entities).
 export {
   renderMetamodelDocs,
   buildMetamodelProvenance,
@@ -251,7 +297,22 @@ export type { FormatFileOptions, FormatFileResult } from "./fmt.js";
 export { resolveSuperRef } from "./super-resolve.js";
 
 // FR-032 (ADR-0032) — canonical reference expansion + FQN object matching.
-export { expandRef, isRelativeRef, refMatchesObject, resolveObjectRef, didYouMeanHint, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
+export {
+  expandRef,
+  isRelativeRef,
+  refMatchesObject,
+  resolveObjectRef,
+  resolveRef,
+  lookupCanonical,
+  refTarget,
+  spellRef,
+  splitChildTail,
+  RefOverDropError,
+  didYouMeanHint,
+  didYouMeanSuperHint,
+  REF_BEARING_ATTR_NAMES,
+} from "./naming-refs.js";
+export { resolveReferences } from "./loader/resolve-references.js";
 
 // Loader hierarchy
 export { MetaDataLoader, declaredTopLevelKeys } from "./loader/meta-data-loader.js";
@@ -299,17 +360,24 @@ export type { Scope, CompiledScope } from "./scope.js";
 export { validateAttrSchema } from "./attr-schema-validate.js";
 export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
 
+// Guide URLs pinned to the running release's tag (prerelease → main).
+export {
+  DOCS_REPO_URL, DOCS_DEFAULT_REF, docsRefForVersion, docsBlobUrl, pinDocsRefs,
+} from "./docs-ref.js";
+
 // Naming — hoisted from runtime-ts in v0.2.3 so multiple consumers (runtime-ts, migrate-ts, codegen-ts)
 // share identical name resolution. See spec §4.1.
 export {
-  toSnakeCase, toKebabCase, pluralize,
-  applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY,
+  toSnakeCase, toKebabCase, pluralize, pluralizeTableNameLegacy,
+  applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, COLUMN_NAMING_STRATEGIES,
+  TABLE_NAMING_RULES, DEFAULT_PHYSICAL_NAMING, physicalNamingOf, applyTableNamingRule,
+  PHYSICAL_NAMING_MIGRATION_GUIDE, PHYSICAL_NAMING_MIGRATION_GUIDE_PATH, physicalNamingRemovedMessage,
   resolveTableName, resolveColumnName, resolveTableSchema, resolveIndexName,
   primaryRdbSource, sourceAddressKey,
   buildNameMap,
   stripPackage, packageOfResolutionKey,
 } from "./naming.js";
-export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
+export type { EntityNameMap, ColumnNamingStrategy, PhysicalNaming, TableNamingRule } from "./naming.js";
 
 // Retired vocabulary: the map the loader reads to explain a retirement, and the raw-document
 // rewriter `meta upgrade` drives from the SAME entries — so the error message and the fix

package/src/loader/declared-duplicate-fields.ts

@@ -0,0 +1,114 @@
+// declaredDuplicateFields — structural pre-parse walk for the `meta verify` field lint.
+//
+// Two `field.*` children with the same `name` in ONE object's `children` list load
+// with no error on every port, and the loaded model keeps no trace of it: the parser's
+// merge rule folds the later declaration into the first (a different subtype is
+// discarded outright). So the question "was this field declared twice?" can only be
+// answered from the document, before the merge — the same reason
+// `declaredTopLevelKeys` exists for the overlay lint.
+//
+// Scope, deliberately narrow:
+//   - ONE children list. The same field declared in a base file and again in an
+//     overlay file is the overlay merge working as designed, and a subtype
+//     redeclaring an inherited field is an override. Neither is in one list.
+//   - Root-level objects only, addressed by the resolution key the parser gives them.
+
+import { TYPE_FIELD, TYPE_METADATA, TYPE_OBJECT, SUBTYPE_ROOT } from "../shared/base-types.js";
+import {
+  PACKAGE_SEPARATOR,
+  RESERVED_KEY_CHILDREN,
+  RESERVED_KEY_NAME,
+  RESERVED_KEY_PACKAGE,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "../shared/structural.js";
+import { expandPackageForPath } from "../parser-core.js";
+import { parseYamlWithPositions } from "../core/yaml-positions-walker.js";
+import type { MetaDataFormat } from "./meta-data-source.js";
+
+/** The YAML authoring sugar for `isArray: true` — a suffix on the wrapper key. */
+const ARRAY_SUFFIX = "[]";
+
+/** One field name declared more than once in one object's `children` list. */
+export interface DeclaredDuplicateField {
+  /** The declaring object's resolution key (`<package>::<name>`, or the bare name). */
+  object: string;
+  /** The repeated field name. */
+  field: string;
+  /** How many times the list declares it (always 2 or more). */
+  count: number;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The TYPE segment of a wrapper key: `field.string[]` and the bare `field` are both `field`. */
+function wrapperType(key: string): string {
+  const dot = key.indexOf(TYPE_SUBTYPE_SEPARATOR);
+  const head = dot < 0 ? key : key.slice(0, dot);
+  return head.endsWith(ARRAY_SUFFIX) ? head.slice(0, -ARRAY_SUFFIX.length) : head;
+}
+
+/** A node's declared name: the body's `name`, or the body itself when YAML wrote a scalar. */
+function declaredName(body: unknown): string | undefined {
+  const name = isRecord(body) ? body[RESERVED_KEY_NAME] : body;
+  return typeof name === "string" && name !== "" ? name : undefined;
+}
+
+/**
+ * Structurally scan a source's raw content and report every field name a root-level
+ * object declares more than once in its own `children` list, in document order.
+ *
+ * Malformed shapes return `[]` rather than throwing — the real parse is where a
+ * structural error surfaces. A syntax error does throw, as `declaredTopLevelKeys` does.
+ */
+export function declaredDuplicateFields(
+  content: string,
+  format: MetaDataFormat,
+): ReadonlyArray<DeclaredDuplicateField> {
+  // Strip UTF-8 BOM if present (mirrors parseJson / parseYaml).
+  const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+  let parsed: unknown;
+  if (format === "json") parsed = JSON.parse(normalized);
+  else if (format === "yaml") parsed = parseYamlWithPositions(normalized).value;
+  else return [];
+  if (!isRecord(parsed)) return [];
+
+  // JSON fuses the subtype onto the root key; sigil-free YAML may write the bare type.
+  const rootBody = parsed[`${TYPE_METADATA}${TYPE_SUBTYPE_SEPARATOR}${SUBTYPE_ROOT}`] ?? parsed[TYPE_METADATA];
+  if (!isRecord(rootBody)) return [];
+  const rawRootPkg = rootBody[RESERVED_KEY_PACKAGE];
+  const rootPkg = typeof rawRootPkg === "string" ? rawRootPkg : "";
+  const children = rootBody[RESERVED_KEY_CHILDREN];
+  if (!Array.isArray(children)) return [];
+
+  const out: DeclaredDuplicateField[] = [];
+  for (const child of children) {
+    if (!isRecord(child)) continue;
+    for (const [wrapperKey, body] of Object.entries(child)) {
+      if (wrapperType(wrapperKey) !== TYPE_OBJECT || !isRecord(body)) continue;
+      const name = declaredName(body);
+      const members = body[RESERVED_KEY_CHILDREN];
+      if (name === undefined || !Array.isArray(members)) continue;
+
+      const counts = new Map<string, number>();
+      for (const member of members) {
+        if (!isRecord(member)) continue;
+        for (const [memberKey, memberBody] of Object.entries(member)) {
+          if (wrapperType(memberKey) !== TYPE_FIELD) continue;
+          const fieldName = declaredName(memberBody);
+          if (fieldName !== undefined) counts.set(fieldName, (counts.get(fieldName) ?? 0) + 1);
+        }
+      }
+
+      const rawOwnPkg = body[RESERVED_KEY_PACKAGE];
+      const pkg =
+        typeof rawOwnPkg === "string" && rawOwnPkg !== "" ? expandPackageForPath(rootPkg, rawOwnPkg) : rootPkg;
+      const object = pkg !== "" ? `${pkg}${PACKAGE_SEPARATOR}${name}` : name;
+      for (const [field, count] of counts) {
+        if (count > 1) out.push({ object, field, count });
+      }
+    }
+  }
+  return out;
+}

package/src/loader/meta-data-loader.ts

@@ -26,6 +26,7 @@ import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateOneSideReferenceResolution, validateM2MJunctionPairing, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
+import { validateReporting } from "./reporting-validation.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
@@ -35,6 +36,7 @@ import { validateFieldMutability } from "../core/field/validate-field-mutability
 import { validateEnumNormalizeAmbiguity } from "../core/field/validate-enum-normalize-ambiguity.js";
 import { validateDiscriminator } from "../core/object/validate-discriminator.js";
 import { resolveDeferredSupers, EXTENDS_TARGET_MISMATCH_RULE } from "../super-resolve.js";
+import { resolveReferences } from "./resolve-references.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateMaxOccurs } from "../validate-max-occurs.js";
 import { validateIdentityPassthrough } from "../core/identity/validate-identity-passthrough.js";
@@ -43,6 +45,7 @@ import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
 import { InMemoryStringSource } from "./meta-data-source.js";
 import type { ParseOptions, ParseResult, PendingOverlay } from "../parser-core.js";
 import { expandPackageForPath, applyPendingOverlays } from "../parser-core.js";
+import { didYouMeanSuperHint } from "../naming-refs.js";
 
 // Local mirror of DirectorySource's options shape. Deliberately inlined here
 // (instead of `import type`'d from ./sources/directory-source.js) so the
@@ -589,9 +592,22 @@ export class MetaDataLoader {
           );
           continue;
         }
+        if (failure.kind === "over-drop") {
+          // ADR-0059 R2 — `..::` dropped more segments than the package has.
+          errors.push(
+            new ParseError(
+              `the extends ref '${failure.ref}' on ${failure.nodeFqn} climbs above the root package — each '..::' drops one segment of the declaring package`,
+              {
+                code: "ERR_BAD_ATTR_VALUE",
+                source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
+              },
+            ),
+          );
+          continue;
+        }
         errors.push(
           new ParseError(
-            `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
+            `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})${didYouMeanSuperHint(root, failure.ref)}`,
             {
               code: "ERR_UNRESOLVED_SUPER",
               source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
@@ -646,6 +662,10 @@ export class MetaDataLoader {
       // an aggregate-derived or dangling ref is fail-closed (ERR_BAD_ATTR_FILTER).
       errors.push(...validateProjectionFilter(root));
 
+      // FR-044 — reporting vocabulary cross-node rules (dimensions, measures,
+      // segments, reports, relative-date filter values).
+      errors.push(...validateReporting(root));
+
       // FR-017 — M:N relationship validation (deferred-resolution): @through names a
       // junction declaring two identity.reference children; @sourceRefField matches one;
       // @symmetric is self-join-only + mutually exclusive with @sourceRefField; M:N attrs
@@ -745,6 +765,10 @@ export class MetaDataLoader {
       // finite number, boolean → true|false). Enum @default membership is validated
       // by validateAttrSchema (Check 5). Cross-port parity with Java/Python/C#.
       errors.push(...validateFieldDefaults(root));
+
+      // ADR-0059 R5 — after the last validation pass, before freeze: resolve every
+      // reference once, record its target and rewrite it to its canonical spelling.
+      resolveReferences(root);
     }
 
     // If nothing parsed successfully, synthesize an empty root so callers