Skip to content

[fm-var] Implement fm-format cascade and effective configuration #117

Description

@DandyLyons

Problem / outcome

Implement <fm-format> validation and the specification-defined cascade so each scalar/list reference has an explainable effective formatting configuration.

Epic: #111. Milestone: 3 — Formatting and lists.

In scope

  • Parse and validate document defaults, for token sets, compatible attributes, duplicates, and placement.
  • Apply precedence: spec defaults; later compatible unscoped declarations; later matching scoped declarations; local element attributes.
  • Support targets string, boolean, integer, number, date, datetime, timestamp, and array.
  • Retain provenance for every effective option so explain output can identify its winning declaration.
  • Diagnose unknown/incompatible attributes and invalid declarations without silently applying them.

Relevant specification sections

  • §2.1/§2.2 local formatting attributes.
  • §2.3 <fm-format> placement, targeting, compatibility, and precedence.
  • §3.8 supported formatting option names.

Dependencies and blockers

Implementation considerations

  • Represent a typed option registry in MarkdownUtilitiesCore rather than scattered string switches.
  • Separate raw declaration diagnostics from cascade calculation; an invalid declaration must have defined effects on otherwise valid declarations/references.
  • Preserve declaration source order and location from the parser.
  • Make effective configuration/provenance Codable for structured explain output.

Acceptance Criteria

  • All allowed for tokens and compatible v1 options are modeled.
  • Cascade precedence and later-declaration wins behavior match the spec.
  • Local attributes override document defaults.
  • Unscoped declarations apply each attribute only to compatible references.
  • Incompatible/unknown attributes, invalid for values, and misplaced declarations receive stable diagnostics.
  • Effective values include provenance and deterministic ordering for explain output.
  • Multiple <fm-format> declarations do not modify source.

Test requirements

  • Matrix tests for scoped/unscoped/local precedence, multiple declarations, mixed compatible attributes, every target type, invalid tokens/options, and declaration placement.
  • Language-neutral effective-configuration fixtures.

Documentation / CLI-help impact

  • DocC cascade table and provenance examples; explain/inspect help later references it.

Explicitly deferred

  • Actual locale algorithms, list rendering, mutation of formatting declarations, and editor assistance.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions