@nowline/core 0.2.0

package/dist/language/nowline-validator.js

@@ -0,0 +1,1654 @@
+import { GrammarUtils } from 'langium';
+import { isAnchorDeclaration, isCalendarBlock, isDefaultDeclaration, isDescriptionDirective, isFootnoteDeclaration, isGroupBlock, isItemDeclaration, isLabelDeclaration, isMilestoneDeclaration, isParallelBlock, isPersonDeclaration, isPersonMemberRef, isSizeDeclaration, isStatusDeclaration, isStyleDeclaration, isSwimlaneDeclaration, isSymbolDeclaration, isTeamDeclaration, } from '../generated/ast.js';
+import { tr } from '../i18n/index.js';
+const SUPPORTED_VERSION = 'v1';
+// Built-in status vocabulary. `active` and `completed` are international-
+// friendly aliases for `in-progress` and `done` respectively — they
+// canonicalize at the layout boundary (see statusFromProp in layout.ts) so
+// downstream consumers see a single normalized form. Both spellings remain
+// valid input.
+const BUILTIN_STATUSES = new Set([
+    'planned',
+    'in-progress',
+    'active',
+    'done',
+    'completed',
+    'at-risk',
+    'blocked',
+]);
+const STYLE_PROP_KEYS = new Set([
+    'bg',
+    'fg',
+    'text',
+    'border',
+    'icon',
+    'shadow',
+    'font',
+    'weight',
+    'italic',
+    'text-size',
+    'padding',
+    'spacing',
+    'header-height',
+    'corner-radius',
+    'bracket',
+    'header-position',
+    'capacity-icon',
+    'timeline-position',
+    'minor-grid',
+]);
+// Built-in capacity-icon vocabulary. Renderer-curated SVG glyphs (plus 'multiplier'
+// which renders as the U+00D7 text character and 'none' which suppresses the glyph).
+const BUILTIN_CAPACITY_ICONS = new Set([
+    'none',
+    'multiplier',
+    'person',
+    'people',
+    'points',
+    'time',
+]);
+// Built-in icon: vocabulary. Superset of capacity-icon names plus the entity-decoration
+// icons currently shipped by the renderer.
+const BUILTIN_ICON_NAMES = new Set([...BUILTIN_CAPACITY_ICONS, 'shield', 'warning', 'lock']);
+// `utilization-warn-at:` / `utilization-over-at:` accept the literal `none`
+// to opt out of that color band (per specs/dsl.md rule 17d). Numeric forms
+// (positive percent, decimal, integer) are validated separately via
+// POSITIVE_NUMBER_RE / POSITIVE_PERCENT_RE.
+const UTILIZATION_NONE = 'none';
+const STYLE_PROP_ENUMS = {
+    border: new Set(['solid', 'dashed', 'dotted']),
+    shadow: new Set(['none', 'subtle', 'soft', 'hard']),
+    font: new Set(['sans', 'serif', 'mono']),
+    weight: new Set(['thin', 'light', 'normal', 'bold']),
+    italic: new Set(['true', 'false']),
+    'text-size': new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl']),
+    padding: new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl']),
+    spacing: new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl']),
+    'header-height': new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl']),
+    'corner-radius': new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl', 'full']),
+    bracket: new Set(['none', 'solid', 'dashed']),
+    'header-position': new Set(['beside', 'above']),
+    'timeline-position': new Set(['top', 'bottom', 'both']),
+    'minor-grid': new Set(['true', 'false']),
+};
+// Built-in color vocabulary. `grey` and `violet` are international-friendly
+// aliases for `gray` and `purple` — they canonicalize at the theme
+// boundary (resolveColor in packages/layout/src/themes/index.ts) so themes
+// don't grow new fields. Both spellings remain valid input.
+const COLOR_NAMES = new Set([
+    'red',
+    'blue',
+    'yellow',
+    'green',
+    'orange',
+    'purple',
+    'violet',
+    'gray',
+    'grey',
+    'navy',
+    'white',
+    'none',
+]);
+const CALENDAR_MODES = new Set(['business', 'full', 'custom']);
+const CALENDAR_FIELDS = new Set([
+    'days-per-week',
+    'days-per-month',
+    'days-per-quarter',
+    'days-per-year',
+]);
+const SCALE_FIELDS = new Set(['name', 'label-every', 'label']);
+const DEFAULT_ENTITY_TYPES = new Set([
+    'item',
+    'label',
+    'swimlane',
+    'roadmap',
+    'milestone',
+    'footnote',
+    'anchor',
+    'parallel',
+    'group',
+]);
+// Banned properties per entity type on `default <entity>` lines.
+// `capacity` on `default swimlane` is banned because each lane's budget must be
+// explicit at its declaration site (per dsl.md). `capacity` on `default item` is
+// allowed (and a useful "every item consumes 1 unit by default" lever).
+const DEFAULT_BANNED = {
+    item: new Set([
+        'size',
+        'duration',
+        'after',
+        'before',
+        'remaining',
+        'link',
+        'description',
+        'owner',
+    ]),
+    milestone: new Set(['date', 'after', 'link', 'description']),
+    anchor: new Set(['date', 'link', 'description']),
+    footnote: new Set(['on', 'link', 'description']),
+    label: new Set(['link', 'description']),
+    swimlane: new Set(['capacity']),
+    roadmap: new Set(),
+    parallel: new Set(),
+    group: new Set(),
+};
+// Properties every entity declaration may carry (`specs/dsl.md` § Universal Properties).
+// `description` is technically a sub-directive (`description "text"` indented under the
+// entity), not an EntityProperty, but we accept it here too: authors who type
+// `description:"text"` as a property aren't doing anything meaningful, but the typo is
+// common enough that warning on it adds noise rather than signal — the value is at
+// least carried into the AST and could be surfaced later if we choose to.
+const UNIVERSAL_ENTITY_PROPS = new Set(['labels', 'link', 'style', 'description']);
+// Properties each entity declaration's `properties: EntityProperty[]` bag actually
+// consumes downstream. Sourced from (a) the property tables in `specs/dsl.md` and
+// (b) every `propValue(...)`/`propValues(...)` call site in `packages/layout/`. Keys
+// outside this set + `UNIVERSAL_ENTITY_PROPS` are silently dropped by the layout —
+// `checkUnknownEntityProperties` warns on them so authors notice typos like
+// `now:2026-01-25` on a `roadmap` line.
+//
+// Raw style props (`bg`, `fg`, ...) intentionally stay OUT of this map — they are
+// rejected as errors by `checkNoRawStyleProperties` and the unknown-property check
+// short-circuits on them so authors don't see a duplicate diagnostic.
+const ENTITY_KNOWN_PROPS = {
+    RoadmapDeclaration: new Set([
+        'author',
+        'start',
+        'length',
+        'scale',
+        'calendar',
+        'logo',
+        'logo-size',
+    ]),
+    AnchorDeclaration: new Set(['date']),
+    SwimlaneDeclaration: new Set([
+        'owner',
+        'capacity',
+        'utilization-warn-at',
+        'utilization-over-at',
+        'status',
+        'after',
+        'before',
+    ]),
+    // `date:` and `start:` on items are read by `packages/layout/src/layout.ts`
+    // (`resolveChildStart`, `walkNode`) to pin an item to a fixed start date. Not
+    // documented in `specs/dsl.md` yet — left allow-listed so authors don't see
+    // a spurious warning for a working code path. See plan's out-of-scope note.
+    ItemDeclaration: new Set([
+        'size',
+        'duration',
+        'status',
+        'owner',
+        'after',
+        'before',
+        'remaining',
+        'capacity',
+        'date',
+        'start',
+    ]),
+    // size/duration/remaining/capacity on parallel/group are already errors via
+    // `checkNoComputedProperties`, so we don't list them here.
+    ParallelBlock: new Set(['owner', 'after', 'before', 'status']),
+    GroupBlock: new Set(['owner', 'after', 'before', 'status']),
+    MilestoneDeclaration: new Set(['date', 'after']),
+    FootnoteDeclaration: new Set(['on']),
+    PersonDeclaration: new Set(),
+    TeamDeclaration: new Set(),
+    LabelDeclaration: new Set(),
+    SizeDeclaration: new Set(['effort']),
+    StatusDeclaration: new Set(),
+};
+// Levenshtein distance with an early-exit cap: returns `cap + 1` once the running
+// minimum exceeds the cap so we can short-circuit the matcher in the common case
+// where the typo is much further than 2 edits from any valid key. The helper is
+// only used by `checkUnknownEntityProperties` for the "did you mean?" suggestion.
+function levenshteinCapped(a, b, cap) {
+    if (a === b)
+        return 0;
+    const an = a.length;
+    const bn = b.length;
+    if (Math.abs(an - bn) > cap)
+        return cap + 1;
+    if (an === 0)
+        return bn;
+    if (bn === 0)
+        return an;
+    let prev = new Array(bn + 1);
+    let curr = new Array(bn + 1);
+    for (let j = 0; j <= bn; j++)
+        prev[j] = j;
+    for (let i = 1; i <= an; i++) {
+        curr[0] = i;
+        let rowMin = i;
+        for (let j = 1; j <= bn; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+            if (curr[j] < rowMin)
+                rowMin = curr[j];
+        }
+        if (rowMin > cap)
+            return cap + 1;
+        const tmp = prev;
+        prev = curr;
+        curr = tmp;
+    }
+    return prev[bn];
+}
+// Pick the closest known key within `cap` edits of `key`, or undefined. Ties are
+// broken by the order of `candidates`, so callers should pass entity-specific keys
+// first when both lists are searched.
+function suggestKey(key, candidates, cap = 2) {
+    let best;
+    let bestDist = cap + 1;
+    for (const c of candidates) {
+        const d = levenshteinCapped(key, c, cap);
+        if (d < bestDist) {
+            best = c;
+            bestDist = d;
+            if (d === 0)
+                break;
+        }
+    }
+    return best;
+}
+function propKey(prop) {
+    return prop.key.endsWith(':') ? prop.key.slice(0, -1) : prop.key;
+}
+// Matches duration literals including decimals, e.g. `2w`, `0.5d`, `1.5m`.
+const DURATION_RE = /^\d+(?:\.\d+)?[dwmqy]$/;
+const PERCENTAGE_RE = /^\d+%$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{3,8}$/;
+const VERSION_RE = /^v\d+$/;
+const INTEGER_RE = /^\d+$/;
+const BARE_DURATION_SUFFIX_RE = /^[dwmqy]$/;
+// Capacity numeric forms — the grammar already separates DECIMAL/INTEGER/PERCENTAGE
+// terminals, but the validator needs to enforce the spec's "positive number" rule
+// and to differentiate where percent is allowed (item) vs. banned (swimlane).
+const POSITIVE_NUMBER_RE = /^\d+(\.\d+)?$/;
+const POSITIVE_PERCENT_RE = /^\d+(\.\d+)?%$/;
+// Disambiguated forms used by `utilization-warn-at:` / `utilization-over-at:`.
+// A decimal-fraction MUST include the dot so its meaning is unambiguous; a
+// bare integer matches the integer regex and is rejected by the validator
+// with a hint to switch to either the percent or decimal-fraction form.
+const POSITIVE_DECIMAL_FRACTION_RE = /^\d+\.\d+$/;
+const POSITIVE_INTEGER_RE = /^\d+$/;
+// ASCII printable, length 1-3 — used by the glyph declaration validator for the
+// `ascii:"..."` fallback property after Langium has stripped the surrounding quotes.
+const ASCII_FALLBACK_RE = /^[\x20-\x7E]{1,3}$/;
+// BCP-47 language tag, simplified to the subset Nowline cares about: a 2- or 3-letter
+// primary language subtag followed by an optional region subtag (2 letters or 3 digits).
+// Permissive enough for `fr`, `fr-CA`, `zh-CN`, `es-419` while rejecting obvious typos.
+// The runtime resolver does the actual fallback work; this regex just gates input shape.
+const BCP47_RE = /^[a-zA-Z]{2,3}(-[a-zA-Z]{2}|-\d{3})?$/;
+const INCLUDE_MODES = new Set(['merge', 'ignore', 'isolate']);
+// Allow-listed property keys on the `nowline` directive line. The directive existed
+// historically as `nowline v1` only; properties are a forward-extension point but stay
+// restrictive so authors get an early error instead of typos rendering silently.
+const DIRECTIVE_FIELDS = new Set(['locale']);
+function resolveLocalStart(file) {
+    const prop = file?.roadmapDecl?.properties.find((p) => propKey(p) === 'start');
+    if (!prop)
+        return { kind: 'missing' };
+    const raw = prop.value;
+    if (!raw || !DATE_RE.test(raw))
+        return { kind: 'invalid' };
+    const d = new Date(raw);
+    if (Number.isNaN(d.getTime()))
+        return { kind: 'invalid' };
+    return { kind: 'valid', iso: raw, date: d };
+}
+function displayName(node) {
+    return node.name ?? node.title ?? '<unnamed>';
+}
+function acceptTr(accept, severity, info, code, ...args) {
+    accept(severity, tr('en-US', code, ...args), {
+        ...info,
+        data: { code, args },
+    });
+}
+export function registerValidationChecks(services) {
+    const registry = services.validation.ValidationRegistry;
+    const validator = services.validation.NowlineValidator;
+    const checks = {
+        NowlineFile: [
+            validator.checkFileStructure,
+            validator.checkUniqueIdentifiers,
+            validator.checkSwimlaneRequired,
+            validator.checkIndentationConsistency,
+            validator.checkRoadmapOnlyKeywordsPosition,
+            validator.checkForwardReferences,
+            validator.checkReferenceResolution,
+            validator.checkCircularDependencies,
+            validator.checkDuplicateSizeIds,
+            validator.checkCalendarBlockConsistency,
+            validator.checkPersonDeclarations,
+            validator.checkDuplicateSymbolIds,
+            validator.checkSymbolReferences,
+        ],
+        NowlineDirective: [validator.checkDirectiveVersion, validator.checkDirectiveProperties],
+        IncludeOption: [validator.checkIncludeMode],
+        IncludeDeclaration: [validator.checkIncludeDuplicateOptions],
+        EntityProperty: [validator.checkPropertyValues],
+        RoadmapDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkRoadmapProperties,
+            validator.checkNoRawStyleProperties,
+            validator.checkUnknownEntityProperties,
+        ],
+        AnchorDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkAnchorRequiredDate,
+            validator.checkAnchorAgainstStart,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        SwimlaneDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkNoRawStyleProperties,
+            validator.checkUtilizationOrdering,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        ItemDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkItemRequiredDuration,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        ParallelBlock: [
+            validator.checkParallelMinChildren,
+            validator.checkNoComputedProperties,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        GroupBlock: [
+            validator.checkGroupMinChildren,
+            validator.checkNoComputedProperties,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        MilestoneDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkMilestoneRequirement,
+            validator.checkMilestoneAgainstStart,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        FootnoteDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkFootnoteOn,
+            validator.checkNoRawStyleProperties,
+            validator.checkUnknownEntityProperties,
+        ],
+        PersonDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        TeamDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkNoRawStyleProperties,
+            validator.checkNoFootnoteProperty,
+            validator.checkUnknownEntityProperties,
+        ],
+        StyleDeclaration: [validator.checkEntityIdOrTitle],
+        StyleProperty: [validator.checkStylePropertyEnum],
+        SymbolDeclaration: [validator.checkEntityIdOrTitle, validator.checkSymbolDeclaration],
+        LabelDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkNoRawStyleProperties,
+            validator.checkUnknownEntityProperties,
+        ],
+        SizeDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkSizeDeclaration,
+            validator.checkNoRawStyleProperties,
+            validator.checkUnknownEntityProperties,
+        ],
+        StatusDeclaration: [
+            validator.checkEntityIdOrTitle,
+            validator.checkStatusDeclaration,
+            validator.checkNoRawStyleProperties,
+            validator.checkUnknownEntityProperties,
+        ],
+        DefaultDeclaration: [validator.checkDefaultDeclaration, validator.checkUtilizationOrdering],
+        CalendarBlock: [validator.checkCalendarBlock],
+        ScaleBlock: [validator.checkScaleBlock],
+    };
+    registry.register(checks, validator);
+}
+export class NowlineValidator {
+    // --- Structural Rule 4: Section order ---
+    checkFileStructure(file, accept) {
+        // Use CST-aware lookup so the `config:` / `roadmap:` substrings inside
+        // INCLUDE_OPTION_KEY tokens (e.g. `config:isolate`) aren't mistaken for
+        // the top-level `config` section marker. See issue #1.
+        const configOffset = file.hasConfig
+            ? GrammarUtils.findNodeForKeyword(file.$cstNode, 'config')?.offset
+            : undefined;
+        const roadmapOffset = file.roadmapDecl?.$cstNode?.offset;
+        if (configOffset !== undefined &&
+            roadmapOffset !== undefined &&
+            configOffset > roadmapOffset) {
+            acceptTr(accept, 'error', { node: file, property: 'hasConfig' }, 'NL.E0001');
+        }
+        for (const inc of file.includes) {
+            const incOffset = inc.$cstNode?.offset ?? 0;
+            if (configOffset !== undefined && incOffset > configOffset) {
+                acceptTr(accept, 'error', { node: inc }, 'NL.E0002');
+            }
+            if (roadmapOffset !== undefined && incOffset > roadmapOffset) {
+                acceptTr(accept, 'error', { node: inc }, 'NL.E0003');
+            }
+        }
+    }
+    // --- Structural Rules 8/9/10: label/duration/status must live in roadmap section ---
+    // Parser enforces this by construction (these keywords are only valid as RoadmapEntry),
+    // so we mainly need to forbid custom statuses referenced before their declaration (rule 15).
+    checkRoadmapOnlyKeywordsPosition(_file, _accept) {
+        // No-op: the grammar places label/duration/status under RoadmapEntry.
+        // Any attempt to declare them before `roadmap` surfaces as a parse error.
+    }
+    // --- Rule 5: Directive version ---
+    checkDirectiveVersion(directive, accept) {
+        if (!VERSION_RE.test(directive.version)) {
+            acceptTr(accept, 'error', { node: directive, property: 'version' }, 'NL.E0100', {
+                version: directive.version,
+            });
+            return;
+        }
+        const num = parseInt(directive.version.slice(1), 10);
+        const supportedNum = parseInt(SUPPORTED_VERSION.slice(1), 10);
+        if (num > supportedNum) {
+            acceptTr(accept, 'error', { node: directive, property: 'version' }, 'NL.E0101', {
+                version: directive.version,
+                supported: SUPPORTED_VERSION,
+            });
+        }
+    }
+    // --- Directive properties (locale) ---
+    // Validates the optional key:value pairs on the `nowline` directive line. Today the
+    // only allowed key is `locale:` (BCP-47 tag); unknown keys are rejected so typos
+    // surface immediately. Duplicate keys are also rejected.
+    checkDirectiveProperties(directive, accept) {
+        const seen = new Set();
+        for (const prop of directive.properties) {
+            const key = propKey(prop);
+            if (!DIRECTIVE_FIELDS.has(key)) {
+                acceptTr(accept, 'error', { node: prop, property: 'key' }, 'NL.E0102', {
+                    key,
+                    allowed: [...DIRECTIVE_FIELDS].join(', '),
+                });
+                continue;
+            }
+            if (seen.has(key)) {
+                acceptTr(accept, 'error', { node: prop, property: 'key' }, 'NL.E0103', { key });
+            }
+            seen.add(key);
+            if (key === 'locale') {
+                const raw = prop.value;
+                if (!BCP47_RE.test(raw)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0104', {
+                        value: raw,
+                    });
+                }
+            }
+        }
+    }
+    // --- Rule 3: Id or title required ---
+    checkEntityIdOrTitle(node, accept) {
+        if (!node.name && !node.title) {
+            acceptTr(accept, 'error', { node }, 'NL.E0301', { type: node.$type });
+        }
+    }
+    // --- Rule 2: Unique identifiers ---
+    checkUniqueIdentifiers(file, accept) {
+        const seen = new Map();
+        const register = (name, node) => {
+            if (!name)
+                return;
+            const existing = seen.get(name);
+            if (existing) {
+                acceptTr(accept, 'error', { node }, 'NL.E0300', {
+                    name,
+                    location: locationOf(existing),
+                });
+            }
+            else {
+                seen.set(name, node);
+            }
+        };
+        if (file.roadmapDecl?.name) {
+            register(file.roadmapDecl.name, file.roadmapDecl);
+        }
+        for (const entry of file.roadmapEntries) {
+            registerEntity(entry, register);
+        }
+        for (const entry of file.configEntries) {
+            if (isStyleDeclaration(entry) && entry.name) {
+                register(entry.name, entry);
+            }
+        }
+    }
+    // --- Rule 7: Mixed tabs and spaces in indentation ---
+    checkIndentationConsistency(file, accept) {
+        const text = file.$document?.textDocument.getText() ?? file.$cstNode?.text;
+        if (!text)
+            return;
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.length === 0)
+                continue;
+            const match = line.match(/^([\t ]+)/);
+            if (!match)
+                continue;
+            const indent = match[1];
+            if (indent.includes('\t') && indent.includes(' ')) {
+                acceptTr(accept, 'error', { node: file }, 'NL.E0005', { line: i + 1 });
+                return;
+            }
+        }
+    }
+    // --- Rule 6: At least one swimlane ---
+    checkSwimlaneRequired(file, accept) {
+        const hasSwimlane = file.roadmapEntries.some(isSwimlaneDeclaration);
+        if (file.roadmapDecl && !hasSwimlane) {
+            acceptTr(accept, 'error', { node: file.roadmapDecl }, 'NL.E0004');
+        }
+    }
+    // --- Include rules 5/6: mode values ---
+    checkIncludeMode(option, accept) {
+        if (!INCLUDE_MODES.has(option.value)) {
+            acceptTr(accept, 'error', { node: option, property: 'value' }, 'NL.E0200', {
+                value: option.value,
+            });
+        }
+    }
+    // --- Include rule 4 (partial): Duplicate include options ---
+    checkIncludeDuplicateOptions(inc, accept) {
+        const keys = new Set();
+        for (const opt of inc.options) {
+            const normalized = opt.key.replace(/:$/, '');
+            if (keys.has(normalized)) {
+                acceptTr(accept, 'error', { node: opt }, 'NL.E0201', { key: normalized });
+            }
+            keys.add(normalized);
+        }
+    }
+    // --- Property value validation (general) ---
+    checkPropertyValues(prop, accept) {
+        const key = propKey(prop);
+        const val = prop.value;
+        const vals = prop.values;
+        const allValues = val ? [val] : vals;
+        switch (key) {
+            case 'status':
+                // Forward/resolution validated at file scope (checkForwardReferences).
+                break;
+            case 'duration':
+                // `duration:` is literal-only — no alias lookup. Authors who
+                // want a named alias use `size:NAME` instead, which resolves
+                // to the size's `effort:` (and divides by `capacity:` at
+                // layout time, m5).
+                if (val && !DURATION_RE.test(val)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0400', {
+                        value: val,
+                    });
+                }
+                break;
+            case 'size':
+                if (val && !isIdentifier(val)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0401', {
+                        value: val,
+                    });
+                }
+                break;
+            case 'effort':
+                if (val && !DURATION_RE.test(val)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0402', {
+                        value: val,
+                    });
+                }
+                break;
+            case 'remaining': {
+                // Accepts either a percent (`30%`, validated 0-100) or a
+                // single-engineer effort literal (`1w`, `0.5d`). The literal
+                // form is normalized to a percent at layout time using the
+                // item's resolved total effort (m5); overflow there emits a
+                // soft warning and clamps the rendered bar to 100%.
+                if (val) {
+                    if (PERCENTAGE_RE.test(val)) {
+                        const pct = parseFloat(val);
+                        if (pct < 0 || pct > 100) {
+                            acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0404', { value: val });
+                        }
+                    }
+                    else if (!DURATION_RE.test(val)) {
+                        acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0403', {
+                            value: val,
+                        });
+                    }
+                }
+                break;
+            }
+            case 'date':
+            case 'start':
+                if (val && (!DATE_RE.test(val) || Number.isNaN(new Date(val).getTime()))) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0405', {
+                        key,
+                        value: val,
+                    });
+                }
+                break;
+            case 'scale':
+                if (val && !DURATION_RE.test(val)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0406', {
+                        value: val,
+                    });
+                }
+                break;
+            case 'calendar':
+                if (val && !CALENDAR_MODES.has(val)) {
+                    acceptTr(accept, 'error', { node: prop, property: 'value' }, 'NL.E0407', {
+                        value: val,
+                    });
+                }
+                break;
+            case 'on':
+            case 'after':
+            case 'before':
+                if (allValues.length === 0) {
+                    acceptTr(accept, 'error', { node: prop }, 'NL.E0408', { key });
+                }
+                break;
+            case 'capacity': {
+                if (!val)
+                    break;
+                const parent = prop.$container;
+                const parentKind = capacityParentKind(parent);
+                // Parallel/group ban is reported by checkNoComputedProperties; skip here.
+                if (parentKind === 'invalid')
+                    break;
+                if (parentKind === 'lane') {
+                    if (!POSITIVE_NUMBER_RE.test(val) || parseFloat(val) <= 0) {
+                        accept('error', `Invalid swimlane capacity "${val}". Use a positive integer (e.g. capacity:5) or decimal (e.g. capacity:1.5). Percent literals are not allowed on swimlanes.`, { node: prop, property: 'value' });
+                    }
+                }
+                else {
+                    if (POSITIVE_PERCENT_RE.test(val)) {
+                        const pct = parseFloat(val);
+                        if (pct <= 0) {
+                            accept('error', `Item capacity "${val}" must be positive.`, {
+                                node: prop,
+                                property: 'value',
+                            });
+                        }
+                    }
+                    else if (POSITIVE_NUMBER_RE.test(val)) {
+                        if (parseFloat(val) <= 0) {
+                            accept('error', `Item capacity "${val}" must be positive.`, {
+                                node: prop,
+                                property: 'value',
+                            });
+                        }
+                    }
+                    else {
+                        accept('error', `Invalid item capacity "${val}". Use a positive integer (capacity:2), decimal (capacity:0.5), or percent literal (capacity:50%).`, { node: prop, property: 'value' });
+                    }
+                }
+                break;
+            }
+            case 'overcapacity': {
+                // Removed in m9. Suppression is now expressed via
+                // `utilization-warn-at:none` / `utilization-over-at:none`
+                // (see specs/dsl.md § Capacity → Utilization thresholds).
+                accept('error', `"overcapacity:" was removed. Use "utilization-over-at:none" (and/or "utilization-warn-at:none") to suppress the lane utilization underline.`, { node: prop });
+                break;
+            }
+            case 'utilization-warn-at':
+            case 'utilization-over-at': {
+                if (!val)
+                    break;
+                if (!isUtilizationAllowedHere(prop.$container)) {
+                    accept('error', `"${key}:" is only valid on "swimlane" or "default swimlane".`, { node: prop });
+                    break;
+                }
+                if (val === UTILIZATION_NONE)
+                    break;
+                if (POSITIVE_PERCENT_RE.test(val)) {
+                    if (parseFloat(val) <= 0) {
+                        accept('error', `${key} value "${val}" must be positive.`, {
+                            node: prop,
+                            property: 'value',
+                        });
+                    }
+                    break;
+                }
+                // Decimals must include the dot to read as fractions; bare
+                // integers are ambiguous (`80` could mean 80% or 8000% as a
+                // fraction) so we reject them with a hint to disambiguate.
+                if (POSITIVE_DECIMAL_FRACTION_RE.test(val)) {
+                    if (parseFloat(val) <= 0) {
+                        accept('error', `${key} value "${val}" must be positive.`, {
+                            node: prop,
+                            property: 'value',
+                        });
+                    }
+                    break;
+                }
+                if (POSITIVE_INTEGER_RE.test(val)) {
+                    accept('error', `Ambiguous ${key} value "${val}". Use the percent form ("${val}%") or the decimal-fraction form ("0.${val}") to make the intent explicit.`, { node: prop, property: 'value' });
+                    break;
+                }
+                accept('error', `Invalid ${key} value "${val}". Use a positive percent (e.g. 80%), a positive decimal fraction (e.g. 0.8), or "none" to opt out.`, { node: prop, property: 'value' });
+                break;
+            }
+            case 'capacity-icon':
+                // Value-form rule (built-in / symbol id / string literal) and
+                // forward-reference rule are enforced together by
+                // checkSymbolReferences at file scope so style blocks and
+                // default-declaration property positions share one code path.
+                break;
+            case 'icon':
+                // Same handling as capacity-icon.
+                break;
+            default:
+                if (STYLE_PROP_KEYS.has(key)) {
+                    if (key === 'bg' || key === 'fg' || key === 'text') {
+                        if (val && !isColorValue(val)) {
+                            accept('error', `Invalid color "${val}" for "${key}". Use a named color, hex value, or "none".`, {
+                                node: prop,
+                                property: 'value',
+                            });
+                        }
+                    }
+                    else if (key in STYLE_PROP_ENUMS) {
+                        const allowed = STYLE_PROP_ENUMS[key];
+                        if (val && !allowed.has(val) && !isColorValue(val)) {
+                            accept('error', `Invalid value "${val}" for "${key}". Allowed: ${[...allowed].join(', ')}.`, {
+                                node: prop,
+                                property: 'value',
+                            });
+                        }
+                    }
+                }
+                break;
+        }
+    }
+    // --- Rule 11: Anchor requires date: ---
+    checkAnchorRequiredDate(anchor, accept) {
+        const dateProp = anchor.properties.find((p) => propKey(p) === 'date');
+        if (!dateProp) {
+            acceptTr(accept, 'error', { node: anchor }, 'NL.E0500', { name: displayName(anchor) });
+        }
+    }
+    // --- R2 + R3: anchor must not precede roadmap start; dated roadmap requires start: ---
+    checkAnchorAgainstStart(anchor, accept) {
+        const dateProp = anchor.properties.find((p) => propKey(p) === 'date');
+        if (!dateProp?.value)
+            return;
+        const raw = dateProp.value;
+        if (!DATE_RE.test(raw))
+            return;
+        const anchorDate = new Date(raw);
+        if (Number.isNaN(anchorDate.getTime()))
+            return;
+        const start = resolveLocalStart(anchor.$container);
+        switch (start.kind) {
+            case 'invalid':
+                return;
+            case 'missing':
+                acceptTr(accept, 'error', { node: dateProp, property: 'value' }, 'NL.E0501', {
+                    name: displayName(anchor),
+                });
+                return;
+            case 'valid':
+                if (anchorDate < start.date) {
+                    acceptTr(accept, 'error', { node: dateProp, property: 'value' }, 'NL.E0502', {
+                        name: displayName(anchor),
+                        date: raw,
+                        start: start.iso,
+                    });
+                }
+                return;
+        }
+    }
+    // --- Rule 12: Milestone requires date: or after: ---
+    checkMilestoneRequirement(milestone, accept) {
+        const hasDate = milestone.properties.some((p) => propKey(p) === 'date');
+        const hasAfter = milestone.properties.some((p) => propKey(p) === 'after');
+        if (!hasDate && !hasAfter) {
+            acceptTr(accept, 'error', { node: milestone }, 'NL.E0503', {
+                name: displayName(milestone),
+            });
+        }
+    }
+    // --- R2 + R3: dated milestone must not precede roadmap start ---
+    checkMilestoneAgainstStart(milestone, accept) {
+        const dateProp = milestone.properties.find((p) => propKey(p) === 'date');
+        if (!dateProp?.value)
+            return;
+        const raw = dateProp.value;
+        if (!DATE_RE.test(raw))
+            return;
+        const milestoneDate = new Date(raw);
+        if (Number.isNaN(milestoneDate.getTime()))
+            return;
+        const start = resolveLocalStart(milestone.$container);
+        switch (start.kind) {
+            case 'invalid':
+                return;
+            case 'missing':
+                accept('error', `Milestone "${displayName(milestone)}" has a date but the roadmap is missing "start:". Add start:YYYY-MM-DD to the roadmap.`, {
+                    node: dateProp,
+                    property: 'value',
+                });
+                return;
+            case 'valid':
+                if (milestoneDate < start.date) {
+                    acceptTr(accept, 'error', { node: dateProp, property: 'value' }, 'NL.E0504', {
+                        name: displayName(milestone),
+                        date: raw,
+                        start: start.iso,
+                    });
+                }
+                return;
+        }
+    }
+    // --- Rule 13: Footnote requires on ---
+    checkFootnoteOn(footnote, accept) {
+        const hasOn = footnote.properties.some((p) => propKey(p) === 'on');
+        if (!hasOn) {
+            acceptTr(accept, 'error', { node: footnote }, 'NL.E0505');
+        }
+    }
+    // --- Rule 13a: `footnote:` is not a valid property on host entities ---
+    // The spec attaches footnotes via the `on:` property on the footnote
+    // declaration only; there is no forward `footnote:` property on the
+    // referenced item / swimlane / etc. Surface a fix-it style error so
+    // authors who reach for the (legacy, undocumented) forward form get
+    // a clear nudge toward the spec-mandated direction.
+    checkNoFootnoteProperty(node, accept) {
+        for (const prop of node.properties) {
+            if (propKey(prop) === 'footnote') {
+                accept('error', `Property "footnote:" is not valid on ${describeNode(node)}. ` +
+                    'Footnotes attach via "on:" on the footnote declaration — ' +
+                    'declare `footnote <id> on:<target-id>` instead.', { node: prop });
+            }
+        }
+    }
+    // --- Rule 10: Item requires either size: or duration: ---
+    checkItemRequiredDuration(item, accept) {
+        const hasDuration = item.properties.some((p) => propKey(p) === 'duration');
+        const hasSize = item.properties.some((p) => propKey(p) === 'size');
+        if (!hasDuration && !hasSize) {
+            acceptTr(accept, 'error', { node: item }, 'NL.E0600', { name: displayName(item) });
+        }
+    }
+    // --- Parallel/group rule 3: size/duration/remaining/capacity not valid on parallel/group ---
+    checkNoComputedProperties(node, accept) {
+        for (const prop of node.properties) {
+            const key = propKey(prop);
+            if (key === 'size' || key === 'duration' || key === 'remaining' || key === 'capacity') {
+                accept('error', `"${key}" is not valid on ${node.$type === 'ParallelBlock' ? 'parallel' : 'group'} (computed from children).`, {
+                    node: prop,
+                });
+            }
+        }
+    }
+    // --- Parallel/group rule 1: Parallel requires >= 2 children ---
+    checkParallelMinChildren(node, accept) {
+        const children = node.content.filter((c) => !isDescriptionDirective(c));
+        if (children.length === 0) {
+            accept('error', 'Parallel block must contain at least 2 children.', { node });
+        }
+        else if (children.length === 1) {
+            accept('warning', 'Parallel block has only 1 child. Use at least 2 for parallel execution.', { node });
+        }
+    }
+    // --- Parallel/group rule 2: Group requires >= 1 child ---
+    checkGroupMinChildren(node, accept) {
+        const children = node.content.filter((c) => !isDescriptionDirective(c));
+        if (children.length === 0) {
+            accept('error', 'Group must contain at least 1 child.', { node });
+        }
+    }
+    // --- Rule 20: Raw style properties banned on roadmap-section entities ---
+    checkNoRawStyleProperties(node, accept) {
+        for (const prop of node.properties) {
+            const key = propKey(prop);
+            if (STYLE_PROP_KEYS.has(key)) {
+                accept('error', `Raw style property "${key}" is not allowed on ${describeNode(node)}. ` +
+                    `Declare a named style in config and reference it via "style:id".`, { node: prop });
+            }
+        }
+    }
+    // Warn on property keys the runtime never reads. Severity is `warning` so a
+    // file that happened to render with a bogus key (e.g. `roadmap r now:2026-01-25`)
+    // keeps parsing — promoting to error would break files that work today even
+    // though the bogus key was a no-op all along.
+    //
+    // Skips:
+    //   - raw style keys (already an error from `checkNoRawStyleProperties`)
+    //   - `footnote` (already an error from `checkNoFootnoteProperty`)
+    //   - sizing keys on parallel/group (already an error from `checkNoComputedProperties`)
+    //
+    // Suggests the closest known key within 2 edits when one exists, so the
+    // existing `DID_YOU_MEAN_RE` in `packages/cli/src/diagnostics/adapt.ts` picks
+    // it up as a structured suggestion alongside the rendered message.
+    checkUnknownEntityProperties(node, accept) {
+        const known = ENTITY_KNOWN_PROPS[node.$type];
+        if (!known)
+            return;
+        const computedBanned = node.$type === 'ParallelBlock' || node.$type === 'GroupBlock'
+            ? new Set(['size', 'duration', 'remaining', 'capacity'])
+            : null;
+        for (const prop of node.properties) {
+            const key = propKey(prop);
+            if (known.has(key))
+                continue;
+            if (UNIVERSAL_ENTITY_PROPS.has(key))
+                continue;
+            if (STYLE_PROP_KEYS.has(key))
+                continue;
+            if (key === 'footnote')
+                continue;
+            if (computedBanned?.has(key))
+                continue;
+            const candidates = [...known, ...UNIVERSAL_ENTITY_PROPS];
+            const suggested = suggestKey(key, candidates) ?? '';
+            acceptTr(accept, 'warning', { node: prop, property: 'key' }, 'NL.W0700', {
+                key,
+                entity: describeNode(node),
+                suggested,
+            });
+        }
+    }
+    // --- Roadmap declaration specific property checks ---
+    // Property-level validation of start:/date: lives in the generic EntityProperty check;
+    // this hook is kept for future roadmap-scoped rules (and to make registration symmetric).
+    checkRoadmapProperties(_roadmap, _accept) {
+        // intentionally empty
+    }
+    // --- Rule 18: Style property enum values ---
+    // Value forms accepted by `icon:` and `capacity-icon:` (built-in identifier,
+    // symbol name, or inline string literal) plus forward-reference resolution are
+    // enforced by checkSymbolReferences at file scope so style blocks and
+    // `default <entity>` lines share a single code path.
+    checkStylePropertyEnum(prop, accept) {
+        const key = propKey(prop);
+        const val = prop.value;
+        if (key === 'bg' || key === 'fg' || key === 'text') {
+            if (!isColorValue(val)) {
+                accept('error', `Invalid color "${val}" for "${key}". Use a named color, hex value, or "none".`, {
+                    node: prop,
+                    property: 'value',
+                });
+            }
+        }
+        else if (key in STYLE_PROP_ENUMS) {
+            const allowed = STYLE_PROP_ENUMS[key];
+            if (!allowed.has(val)) {
+                accept('error', `Invalid value "${val}" for "${key}". Allowed: ${[...allowed].join(', ')}.`, {
+                    node: prop,
+                    property: 'value',
+                });
+            }
+        }
+        else if (!STYLE_PROP_KEYS.has(key)) {
+            accept('error', `Unknown style property "${key}".`, {
+                node: prop,
+                property: 'key',
+            });
+        }
+    }
+    // --- Size declaration: rule 5 (effort: required), rule 4 (id format) ---
+    checkSizeDeclaration(decl, accept) {
+        const effortProp = decl.properties.find((p) => propKey(p) === 'effort');
+        if (!effortProp) {
+            accept('error', `Size "${displayName(decl)}" requires an "effort:" property.`, {
+                node: decl,
+            });
+        }
+        if (decl.name) {
+            if (DURATION_RE.test(decl.name) || BARE_DURATION_SUFFIX_RE.test(decl.name)) {
+                accept('error', `Size id "${decl.name}" collides with the raw duration pattern. Choose a different name (e.g. "xs", "small", "quarter").`, { node: decl, property: 'name' });
+            }
+        }
+    }
+    // --- Status declaration: id collision with built-ins ---
+    checkStatusDeclaration(decl, accept) {
+        if (decl.name) {
+            if (BUILTIN_STATUSES.has(decl.name)) {
+                accept('error', `Status id "${decl.name}" collides with the built-in status value. Built-ins: ${[...BUILTIN_STATUSES].join(', ')}.`, { node: decl, property: 'name' });
+            }
+        }
+    }
+    // --- Rule 5: Duplicate size ids ---
+    checkDuplicateSizeIds(file, accept) {
+        const seen = new Map();
+        for (const entry of file.roadmapEntries) {
+            if (isSizeDeclaration(entry) && entry.name) {
+                const existing = seen.get(entry.name);
+                if (existing) {
+                    accept('error', `Duplicate size id "${entry.name}". First declared at ${locationOf(existing)}.`, { node: entry, property: 'name' });
+                }
+                else {
+                    seen.set(entry.name, entry);
+                }
+            }
+        }
+    }
+    // --- Rule 17d (ordering half): utilization-warn-at <= utilization-over-at ---
+    // Runs on both `SwimlaneDeclaration` and `DefaultDeclaration` (when its
+    // entityType is `swimlane`). The value-form check in checkPropertyValues
+    // has already run by the time this fires; this method only re-reads the
+    // values and compares fractions when both are numeric. `none` on either
+    // side opts that side out and skips the comparison (the spec treats the
+    // two thresholds as independent — see specs/dsl.md rule 17d).
+    checkUtilizationOrdering(decl, accept) {
+        if (isDefaultDeclaration(decl) && decl.entityType !== 'swimlane')
+            return;
+        const warnProp = decl.properties.find((p) => propKey(p) === 'utilization-warn-at');
+        const overProp = decl.properties.find((p) => propKey(p) === 'utilization-over-at');
+        if (!warnProp || !overProp)
+            return;
+        const warn = parseUtilizationFraction(warnProp.value);
+        const over = parseUtilizationFraction(overProp.value);
+        if (warn === null || over === null)
+            return;
+        if (warn > over) {
+            accept('error', `utilization-warn-at (${warnProp.value}) must be ≤ utilization-over-at (${overProp.value}). Warn fires below over; if both fire at the same point, the warn band collapses to zero.`, { node: warnProp, property: 'value' });
+        }
+    }
+    // --- Defaults rules 21-23: entity-type whitelist, duplicate-per-entity, banned props ---
+    checkDefaultDeclaration(decl, accept) {
+        if (!DEFAULT_ENTITY_TYPES.has(decl.entityType)) {
+            accept('error', `"${decl.entityType}" is not a supported entity type for default. Allowed: ${[...DEFAULT_ENTITY_TYPES].join(', ')}.`, { node: decl, property: 'entityType' });
+            return;
+        }
+        // Duplicate default <entity> within the same file.
+        const file = decl.$container;
+        let firstIdx = -1;
+        for (let i = 0; i < file.configEntries.length; i++) {
+            const other = file.configEntries[i];
+            if (isDefaultDeclaration(other) && other.entityType === decl.entityType) {
+                if (firstIdx < 0) {
+                    firstIdx = i;
+                }
+                else if (other === decl) {
+                    accept('error', `Duplicate "default ${decl.entityType}" declaration. Only one is allowed per entity type per file.`, { node: decl });
+                    break;
+                }
+            }
+        }
+        const banned = DEFAULT_BANNED[decl.entityType];
+        if (banned) {
+            for (const prop of decl.properties) {
+                const key = propKey(prop);
+                if (banned.has(key)) {
+                    accept('error', `"${key}" cannot be set on "default ${decl.entityType}". Identity-defining, sizing, sequencing, reference, and prose properties must be explicit on each entity.`, { node: prop });
+                }
+            }
+        }
+    }
+    // --- Rule 7 (calendar): calendar block only valid when roadmap calendar:custom ---
+    // Rule 8: custom calendar requires all four fields.
+    checkCalendarBlockConsistency(file, accept) {
+        const calendarBlocks = file.configEntries.filter(isCalendarBlock);
+        const calendarProp = file.roadmapDecl?.properties.find((p) => propKey(p) === 'calendar');
+        const calendarMode = calendarProp?.value;
+        if (calendarBlocks.length > 0 && calendarMode !== 'custom') {
+            for (const block of calendarBlocks) {
+                accept('error', `A "calendar" config block is only valid when the roadmap declares calendar:custom.`, { node: block });
+            }
+        }
+        if (calendarMode === 'custom' && calendarBlocks.length === 0) {
+            accept('error', `calendar:custom requires a "calendar" config block with days-per-week, days-per-month, days-per-quarter, and days-per-year.`, { node: file.roadmapDecl, property: 'properties' });
+        }
+        if (calendarMode === 'custom' && calendarBlocks.length > 0) {
+            for (const block of calendarBlocks) {
+                const presentKeys = new Set(block.properties.map((p) => propKey(p)));
+                for (const field of CALENDAR_FIELDS) {
+                    if (!presentKeys.has(field)) {
+                        accept('error', `calendar:custom requires "${field}" in the calendar config block.`, { node: block });
+                    }
+                }
+            }
+        }
+    }
+    // --- Rule 9: calendar block property values must be positive integers ---
+    checkCalendarBlock(block, accept) {
+        const seen = new Set();
+        for (const prop of block.properties) {
+            const key = propKey(prop);
+            if (!CALENDAR_FIELDS.has(key)) {
+                accept('error', `Unknown calendar property "${key}". Allowed: ${[...CALENDAR_FIELDS].join(', ')}.`, { node: prop, property: 'key' });
+                continue;
+            }
+            if (seen.has(key)) {
+                accept('error', `Duplicate calendar property "${key}".`, {
+                    node: prop,
+                    property: 'key',
+                });
+            }
+            seen.add(key);
+            if (!INTEGER_RE.test(prop.value) || parseInt(prop.value, 10) <= 0) {
+                accept('error', `"${key}" must be a positive integer, got "${prop.value}".`, {
+                    node: prop,
+                    property: 'value',
+                });
+            }
+        }
+    }
+    // --- Scale block property validation ---
+    checkScaleBlock(block, accept) {
+        const seen = new Set();
+        for (const prop of block.properties) {
+            const key = propKey(prop);
+            if (!SCALE_FIELDS.has(key)) {
+                accept('error', `Unknown scale property "${key}". Allowed: ${[...SCALE_FIELDS].join(', ')}.`, { node: prop, property: 'key' });
+                continue;
+            }
+            if (seen.has(key)) {
+                accept('error', `Duplicate scale property "${key}".`, {
+                    node: prop,
+                    property: 'key',
+                });
+            }
+            seen.add(key);
+            if (key === 'label-every') {
+                if (!INTEGER_RE.test(prop.value) || parseInt(prop.value, 10) <= 0) {
+                    accept('error', `"label-every" must be a positive integer, got "${prop.value}".`, { node: prop, property: 'value' });
+                }
+            }
+        }
+    }
+    // --- Rule 15: size:/status: references resolve to earlier declarations ---
+    checkForwardReferences(file, accept) {
+        // Declarations in source order across the file.
+        const sizeOrder = new Map();
+        const statusOrder = new Map();
+        for (let i = 0; i < file.roadmapEntries.length; i++) {
+            const entry = file.roadmapEntries[i];
+            if (isSizeDeclaration(entry) && entry.name) {
+                if (!sizeOrder.has(entry.name))
+                    sizeOrder.set(entry.name, i);
+            }
+            else if (isStatusDeclaration(entry) && entry.name) {
+                if (!statusOrder.has(entry.name))
+                    statusOrder.set(entry.name, i);
+            }
+        }
+        for (let i = 0; i < file.roadmapEntries.length; i++) {
+            const entry = file.roadmapEntries[i];
+            visitPropertiesDeep(entry, (prop) => {
+                const key = propKey(prop);
+                if (key === 'size' && prop.value) {
+                    const val = prop.value;
+                    const declIdx = sizeOrder.get(val);
+                    if (declIdx === undefined) {
+                        accept('error', `Size "${val}" is not declared. Add "size ${val} effort:<literal>" earlier in the roadmap section.`, { node: prop, property: 'value' });
+                    }
+                    else if (declIdx >= i) {
+                        accept('error', `Size "${val}" is referenced before its declaration. Move "size ${val}" above this entity.`, { node: prop, property: 'value' });
+                    }
+                }
+                else if (key === 'status' && prop.value) {
+                    const val = prop.value;
+                    if (BUILTIN_STATUSES.has(val))
+                        return;
+                    const declIdx = statusOrder.get(val);
+                    if (declIdx === undefined) {
+                        accept('error', `Status "${val}" is not a built-in and has no declaration. Add "status ${val}" earlier in the roadmap section.`, { node: prop, property: 'value' });
+                    }
+                    else if (declIdx >= i) {
+                        accept('error', `Status "${val}" is referenced before its declaration. Move "status ${val}" above this entity.`, { node: prop, property: 'value' });
+                    }
+                }
+            });
+        }
+    }
+    // --- Rules 24/1 (reference): after/before/on must resolve to declared ids ---
+    // `owner:` is intentionally NOT checked here. Per specs/dsl.md ("Declarations
+    // are optional"), `owner:sam` is valid even if no `person sam` declaration
+    // exists — it renders as the bare id. Sequencing properties (`after`,
+    // `before`, `on`) stay strict because a phantom dependency silently breaks
+    // the timeline / footnote target.
+    checkReferenceResolution(file, accept) {
+        const declaredIds = collectReferenceableIds(file);
+        const visit = (entry) => {
+            visitPropertiesDeep(entry, (prop) => {
+                const key = propKey(prop);
+                if (key !== 'after' && key !== 'before' && key !== 'on')
+                    return;
+                const vals = prop.value ? [prop.value] : prop.values;
+                for (const v of vals) {
+                    if (!v)
+                        continue;
+                    if (!declaredIds.has(v)) {
+                        accept('error', `${key}: reference "${v}" does not resolve to any declared entity in this file.`, { node: prop });
+                    }
+                }
+            });
+        };
+        for (const entry of file.roadmapEntries) {
+            visit(entry);
+        }
+    }
+    // --- Rule 25: circular dependencies in after/before graph ---
+    checkCircularDependencies(file, accept) {
+        // Build forward-edge graph: id -> set of ids that must finish before id can start.
+        // `after:x` on entity y means y depends on x (edge y -> x).
+        // `before:y` on entity x means x must finish before y starts, so y depends on x (edge y -> x).
+        const deps = new Map();
+        const addDep = (node, dep) => {
+            if (!deps.has(node))
+                deps.set(node, new Set());
+            deps.get(node).add(dep);
+        };
+        const indexDependents = (idName, props, file) => {
+            if (!idName)
+                return;
+            for (const prop of props) {
+                const key = propKey(prop);
+                if (key === 'after') {
+                    const refs = prop.value ? [prop.value] : prop.values;
+                    for (const r of refs)
+                        if (r)
+                            addDep(idName, r);
+                }
+                else if (key === 'before') {
+                    const refs = prop.value ? [prop.value] : prop.values;
+                    for (const r of refs)
+                        if (r)
+                            addDep(r, idName);
+                }
+            }
+            void file;
+        };
+        const visitEntry = (entry) => {
+            const id = entry.name;
+            const props = entry.properties ?? [];
+            indexDependents(id, props, file);
+            if (isSwimlaneDeclaration(entry)) {
+                for (const c of entry.content)
+                    visitEntry(c);
+            }
+            else if (isParallelBlock(entry) || isGroupBlock(entry)) {
+                for (const c of entry.content)
+                    visitEntry(c);
+            }
+        };
+        for (const entry of file.roadmapEntries)
+            visitEntry(entry);
+        // DFS for cycles.
+        const WHITE = 0, GRAY = 1, BLACK = 2;
+        const color = new Map();
+        for (const id of deps.keys())
+            color.set(id, WHITE);
+        const reported = new Set();
+        const dfs = (node, path) => {
+            color.set(node, GRAY);
+            path.push(node);
+            for (const dep of deps.get(node) ?? []) {
+                const c = color.get(dep) ?? WHITE;
+                if (c === GRAY) {
+                    const cycleStart = path.indexOf(dep);
+                    const cycle = path.slice(cycleStart).concat(dep);
+                    const key = [...cycle].sort().join('→');
+                    if (!reported.has(key)) {
+                        reported.add(key);
+                        accept('error', `Circular dependency detected: ${cycle.join(' → ')}.`, {
+                            node: file.roadmapDecl ?? file,
+                        });
+                    }
+                }
+                else if (c === WHITE) {
+                    dfs(dep, path);
+                }
+            }
+            path.pop();
+            color.set(node, BLACK);
+        };
+        for (const node of deps.keys()) {
+            if ((color.get(node) ?? WHITE) === WHITE)
+                dfs(node, []);
+        }
+    }
+    // --- Rules 30-32: Person declare-once + bare top-level warning ---
+    checkPersonDeclarations(file, accept) {
+        const declarations = new Map();
+        const isRealDeclaration = (p) => {
+            return Boolean(p.title) || p.properties.length > 0 || p.description !== undefined;
+        };
+        const visitPerson = (p) => {
+            if (!p.name)
+                return;
+            const isDecl = isRealDeclaration(p);
+            if (!declarations.has(p.name))
+                declarations.set(p.name, []);
+            declarations.get(p.name).push({ node: p, isDeclaration: isDecl });
+            if (!isDecl && p.$container.$type === 'NowlineFile') {
+                accept('warning', `Bare "person ${p.name}" at roadmap top level has no declaration. Either add properties (title, link, etc.) or remove the line.`, { node: p });
+            }
+        };
+        const visitTeam = (t) => {
+            for (const c of t.content) {
+                if (isPersonDeclaration(c))
+                    visitPerson(c);
+                else if (isTeamDeclaration(c))
+                    visitTeam(c);
+            }
+        };
+        for (const entry of file.roadmapEntries) {
+            if (isPersonDeclaration(entry))
+                visitPerson(entry);
+            else if (isTeamDeclaration(entry))
+                visitTeam(entry);
+        }
+        for (const [name, sites] of declarations) {
+            const decls = sites.filter((s) => s.isDeclaration);
+            if (decls.length > 1) {
+                for (let i = 1; i < decls.length; i++) {
+                    accept('error', `Person "${name}" is declared more than once. First declaration at ${locationOf(decls[0].node)}.`, { node: decls[i].node });
+                }
+            }
+        }
+    }
+    // --- Rules 17f / 17g / 17h / 17i: per-declaration symbol checks ---
+    // Note: Langium's default ValueConverter strips surrounding quotes from STRING
+    // tokens before they reach the AST, so unicode:"💰" arrives here as just "💰"
+    // — we validate the *content* (length / ASCII range) rather than presence of
+    // quotes. The grammar already restricts `unicode:` and `ascii:` to PropertyAtom,
+    // so the only quoteless form an author can pass is a bare identifier like
+    // `unicode:foo`, which we treat permissively (it's a single-grapheme literal).
+    checkSymbolDeclaration(decl, accept) {
+        if (decl.name && BUILTIN_ICON_NAMES.has(decl.name)) {
+            accept('error', `Symbol id "${decl.name}" collides with a built-in icon name. Reserved built-ins: ${[...BUILTIN_ICON_NAMES].sort().join(', ')}.`, { node: decl, property: 'name' });
+        }
+        const unicodeProp = decl.properties.find((p) => propKey(p) === 'unicode');
+        if (!unicodeProp) {
+            accept('error', `Symbol "${displayName(decl)}" requires a "unicode:" property (e.g. unicode:"💰" or unicode:"\\u{1F464}").`, { node: decl });
+        }
+        else if (!unicodeProp.value || unicodeProp.value.length === 0) {
+            accept('error', `Symbol "${displayName(decl)}" unicode: must be a non-empty value.`, {
+                node: unicodeProp,
+                property: 'value',
+            });
+        }
+        const asciiProp = decl.properties.find((p) => propKey(p) === 'ascii');
+        if (asciiProp) {
+            const raw = asciiProp.value ?? '';
+            if (!ASCII_FALLBACK_RE.test(raw)) {
+                accept('error', `Symbol "${displayName(decl)}" ascii: must be 1-3 ASCII characters (got ${raw.length} character${raw.length === 1 ? '' : 's'}).`, { node: asciiProp, property: 'value' });
+            }
+        }
+        for (const prop of decl.properties) {
+            const key = propKey(prop);
+            if (key !== 'unicode' && key !== 'ascii' && key !== 'link' && key !== 'description') {
+                accept('error', `Unknown symbol property "${key}". Allowed: unicode, ascii, link, description.`, { node: prop, property: 'key' });
+            }
+        }
+    }
+    // --- Rule 17j: duplicate symbol ids in the same file ---
+    checkDuplicateSymbolIds(file, accept) {
+        const seen = new Map();
+        for (const entry of file.configEntries) {
+            if (isSymbolDeclaration(entry) && entry.name) {
+                const existing = seen.get(entry.name);
+                if (existing) {
+                    accept('error', `Duplicate symbol id "${entry.name}". First declared at ${locationOf(existing)}.`, { node: entry, property: 'name' });
+                }
+                else {
+                    seen.set(entry.name, entry);
+                }
+            }
+        }
+    }
+    // --- Rule 17k: icon: / capacity-icon: references resolve to a built-in,
+    // a quoted Unicode literal, or an earlier symbol declaration. Forward
+    // references are an error. Walks both StyleDeclaration.properties and
+    // DefaultDeclaration.properties so style blocks and default <entity>
+    // lines share one path.
+    checkSymbolReferences(file, accept) {
+        const symbolOrder = new Map();
+        for (let i = 0; i < file.configEntries.length; i++) {
+            const entry = file.configEntries[i];
+            if (isSymbolDeclaration(entry) && entry.name) {
+                if (!symbolOrder.has(entry.name))
+                    symbolOrder.set(entry.name, i);
+            }
+        }
+        const checkRef = (entryIdx, key, val, propNode) => {
+            if (key !== 'icon' && key !== 'capacity-icon')
+                return;
+            if (!val)
+                return;
+            // Inline Unicode literals (`capacity-icon:"💰"`) reach the AST as their
+            // unquoted content — the only way to tell them from an identifier
+            // reference is by checking the character set. Anything that doesn't
+            // look like an identifier is treated as a literal and
+            // accepted as-is. Authors who genuinely want to write a literal that
+            // happens to spell a real identifier should declare a symbol instead.
+            if (!isIdentifier(val))
+                return;
+            if (key === 'capacity-icon' && BUILTIN_CAPACITY_ICONS.has(val))
+                return;
+            if (key === 'icon' && BUILTIN_ICON_NAMES.has(val))
+                return;
+            const declIdx = symbolOrder.get(val);
+            if (declIdx === undefined) {
+                const builtins = key === 'capacity-icon'
+                    ? [...BUILTIN_CAPACITY_ICONS].sort().join(', ')
+                    : [...BUILTIN_ICON_NAMES].sort().join(', ');
+                accept('error', `${key}: "${val}" is neither a built-in (${builtins}) nor a declared symbol. Add "symbol ${val} unicode:..." earlier in config or use a quoted Unicode literal.`, { node: propNode, property: 'value' });
+            }
+            else if (declIdx >= entryIdx) {
+                accept('error', `${key}: symbol "${val}" is referenced before its declaration. Move "symbol ${val}" above this entry.`, { node: propNode, property: 'value' });
+            }
+        };
+        for (let i = 0; i < file.configEntries.length; i++) {
+            const entry = file.configEntries[i];
+            if (isStyleDeclaration(entry)) {
+                for (const sp of entry.properties) {
+                    checkRef(i, propKey(sp), sp.value, sp);
+                }
+            }
+            else if (isDefaultDeclaration(entry)) {
+                for (const ep of entry.properties) {
+                    checkRef(i, propKey(ep), ep.value, ep);
+                }
+            }
+        }
+    }
+}
+// --- Helpers ---
+function isColorValue(val) {
+    return COLOR_NAMES.has(val) || HEX_COLOR_RE.test(val);
+}
+function isIdentifier(val) {
+    return /^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(val);
+}
+function capacityParentKind(parent) {
+    if (!parent)
+        return 'invalid';
+    if (isSwimlaneDeclaration(parent))
+        return 'lane';
+    if (isItemDeclaration(parent))
+        return 'item';
+    if (isDefaultDeclaration(parent)) {
+        return parent.entityType === 'swimlane' ? 'lane' : 'item';
+    }
+    return 'invalid';
+}
+function isUtilizationAllowedHere(parent) {
+    if (!parent)
+        return false;
+    if (isSwimlaneDeclaration(parent))
+        return true;
+    if (isDefaultDeclaration(parent) && parent.entityType === 'swimlane')
+        return true;
+    return false;
+}
+/**
+ * Parse a numeric utilization-threshold value into a fraction. Mirrors the
+ * accepted value forms in checkPropertyValues (case `utilization-warn-at` /
+ * `utilization-over-at`):
+ *
+ *   - `'none'` → null (opt-out; ordering check skips this side).
+ *   - positive percent (`80%`) → 0.8.
+ *   - positive decimal fraction (`0.8`) → 0.8 (or `1.25` → 1.25 for the
+ *     intentionally-stretched-over case `utilization-over-at:125%`).
+ *   - bare integer or anything else → null. Bare integers are rejected with
+ *     a disambiguation hint by the value-form check before this helper runs;
+ *     returning null here makes the ordering check skip that side instead of
+ *     double-reporting.
+ */
+function parseUtilizationFraction(val) {
+    if (!val || val === UTILIZATION_NONE)
+        return null;
+    if (POSITIVE_PERCENT_RE.test(val)) {
+        const n = parseFloat(val);
+        return Number.isFinite(n) && n > 0 ? n / 100 : null;
+    }
+    if (POSITIVE_DECIMAL_FRACTION_RE.test(val)) {
+        const n = parseFloat(val);
+        return Number.isFinite(n) && n > 0 ? n : null;
+    }
+    return null;
+}
+function locationOf(node) {
+    const cst = node.$cstNode;
+    if (cst) {
+        return `line ${cst.range.start.line + 1}`;
+    }
+    return 'unknown location';
+}
+function describeNode(node) {
+    const kind = node.$type.replace(/Declaration$|Block$/, '').toLowerCase();
+    const label = node.name ?? node.title;
+    return label ? `${kind} "${label}"` : kind;
+}
+function registerEntity(entry, register) {
+    if (isSwimlaneDeclaration(entry)) {
+        register(entry.name, entry);
+        for (const child of entry.content) {
+            registerSwimlaneContent(child, register);
+        }
+    }
+    else if (isPersonDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isTeamDeclaration(entry)) {
+        registerTeam(entry, register);
+    }
+    else if (isAnchorDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isMilestoneDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isFootnoteDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isLabelDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isSizeDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+    else if (isStatusDeclaration(entry)) {
+        register(entry.name, entry);
+    }
+}
+function registerTeam(team, register) {
+    register(team.name, team);
+    for (const member of team.content) {
+        if (isTeamDeclaration(member)) {
+            registerTeam(member, register);
+        }
+        // PersonMemberRef and bare person <id> are references, not declarations — skip.
+    }
+}
+function registerSwimlaneContent(child, register) {
+    if (isItemDeclaration(child)) {
+        register(child.name, child);
+    }
+    else if (isParallelBlock(child)) {
+        register(child.name, child);
+        for (const pc of child.content) {
+            registerSwimlaneContent(pc, register);
+        }
+    }
+    else if (isGroupBlock(child)) {
+        register(child.name, child);
+        for (const gc of child.content) {
+            registerSwimlaneContent(gc, register);
+        }
+    }
+}
+function visitPropertiesDeep(node, visit) {
+    const walk = (n) => {
+        const props = n.properties;
+        if (Array.isArray(props)) {
+            for (const p of props)
+                visit(p);
+        }
+        if (isSwimlaneDeclaration(n)) {
+            for (const c of n.content)
+                walk(c);
+        }
+        else if (isParallelBlock(n) || isGroupBlock(n)) {
+            for (const c of n.content)
+                walk(c);
+        }
+        else if (isTeamDeclaration(n)) {
+            for (const c of n.content) {
+                if (isTeamDeclaration(c) || isPersonDeclaration(c))
+                    walk(c);
+            }
+        }
+    };
+    walk(node);
+}
+function collectReferenceableIds(file) {
+    const ids = new Set();
+    if (file.roadmapDecl?.name)
+        ids.add(file.roadmapDecl.name);
+    const addEntry = (entry) => {
+        const name = entry.name;
+        if (name)
+            ids.add(name);
+        if (isSwimlaneDeclaration(entry)) {
+            for (const c of entry.content)
+                addEntry(c);
+        }
+        else if (isParallelBlock(entry) || isGroupBlock(entry)) {
+            for (const c of entry.content)
+                addEntry(c);
+        }
+        else if (isTeamDeclaration(entry)) {
+            for (const c of entry.content) {
+                if (isTeamDeclaration(c) || isPersonDeclaration(c))
+                    addEntry(c);
+                else if (isPersonMemberRef(c)) {
+                    // Don't register member refs — they reference persons declared elsewhere.
+                }
+            }
+        }
+    };
+    for (const entry of file.roadmapEntries)
+        addEntry(entry);
+    return ids;
+}
+//# sourceMappingURL=nowline-validator.js.map