@nowline/core 0.2.0

package/src/generated/module.ts

@@ -0,0 +1,25 @@
+/******************************************************************************
+ * This file was generated by langium-cli 4.2.0.
+ * DO NOT EDIT MANUALLY!
+ ******************************************************************************/
+
+import type { LangiumSharedCoreServices, LangiumCoreServices, LangiumGeneratedCoreServices, LangiumGeneratedSharedCoreServices, LanguageMetaData, Module } from 'langium';
+import { NowlineAstReflection } from './ast.js';
+import { NowlineGrammar } from './grammar.js';
+
+export const NowlineLanguageMetaData = {
+    languageId: 'nowline',
+    fileExtensions: ['.nowline'],
+    caseInsensitive: false,
+    mode: 'development'
+} as const satisfies LanguageMetaData;
+
+export const NowlineGeneratedSharedModule: Module<LangiumSharedCoreServices, LangiumGeneratedSharedCoreServices> = {
+    AstReflection: () => new NowlineAstReflection()
+};
+
+export const NowlineGeneratedModule: Module<LangiumCoreServices, LangiumGeneratedCoreServices> = {
+    Grammar: () => NowlineGrammar(),
+    LanguageMetaData: () => NowlineLanguageMetaData,
+    parser: {}
+};

package/src/i18n/codes.ts

@@ -0,0 +1,102 @@
+// Stable error codes for validator messages. Codes never change once shipped:
+// renumbering is a major-version concern. Adding a new code is always
+// safe; deleting one means the rule was removed entirely.
+//
+// Code ranges are reserved by category to keep the table scannable:
+//   NL.E0001–E0099  structural / file-level
+//   NL.E0100–E0199  directive
+//   NL.E0200–E0299  include
+//   NL.E0300–E0399  identifier / id-or-title / indentation
+//   NL.E0400–E0499  property values (duration, size, date, scale, etc.)
+//   NL.E0500–E0599  anchor / milestone / footnote
+//   NL.E0600–E0699  item / swimlane
+//   NL.E0700–E0799  capacity / utilization
+//   NL.E0800–E0899  style / color / symbol
+//   NL.E0900–E0999  config blocks (calendar, scale, default)
+//   NL.W0700–W0799  warnings (silently-ignored input)
+//
+// The full list of allocated codes lives in `messages.en.ts` (one entry
+// per code). The runtime walks the locale fallback chain and falls
+// through to en-US when a key is missing — see `i18n/index.ts`.
+
+export type MessageCode =
+    // Structural (NL.E0001–E0099)
+    | 'NL.E0001' // config-after-roadmap
+    | 'NL.E0002' // include-after-config
+    | 'NL.E0003' // include-after-roadmap
+    | 'NL.E0004' // swimlane-required
+    | 'NL.E0005' // mixed-tabs-and-spaces
+
+    // Directive (NL.E0100–E0199)
+    | 'NL.E0100' // invalid-version-format
+    | 'NL.E0101' // version-beyond-supported
+    | 'NL.E0102' // unknown-directive-property
+    | 'NL.E0103' // duplicate-directive-property
+    | 'NL.E0104' // invalid-locale
+
+    // Include (NL.E0200–E0299)
+    | 'NL.E0200' // invalid-include-mode
+    | 'NL.E0201' // duplicate-include-option
+
+    // Identifier (NL.E0300–E0399)
+    | 'NL.E0300' // duplicate-identifier
+    | 'NL.E0301' // id-or-title-required
+
+    // Property values (NL.E0400–E0499)
+    | 'NL.E0400' // invalid-duration
+    | 'NL.E0401' // invalid-size-ref
+    | 'NL.E0402' // invalid-effort
+    | 'NL.E0403' // invalid-remaining-percent
+    | 'NL.E0404' // remaining-out-of-range
+    | 'NL.E0405' // invalid-date
+    | 'NL.E0406' // invalid-scale
+    | 'NL.E0407' // invalid-calendar
+    | 'NL.E0408' // empty-property-list
+
+    // Anchor / milestone / footnote (NL.E0500–E0599)
+    | 'NL.E0500' // anchor-requires-date
+    | 'NL.E0501' // anchor-needs-roadmap-start
+    | 'NL.E0502' // anchor-before-roadmap-start
+    | 'NL.E0503' // milestone-requires-date-or-after
+    | 'NL.E0504' // milestone-before-roadmap-start
+    | 'NL.E0505' // footnote-requires-on
+
+    // Item (NL.E0600–E0699)
+    | 'NL.E0600' // item-requires-size-or-duration
+
+    // Warnings (NL.W0700–W0799)
+    | 'NL.W0700'; // unknown-entity-property
+
+export const ALL_CODES: ReadonlyArray<MessageCode> = [
+    'NL.E0001',
+    'NL.E0002',
+    'NL.E0003',
+    'NL.E0004',
+    'NL.E0005',
+    'NL.E0100',
+    'NL.E0101',
+    'NL.E0102',
+    'NL.E0103',
+    'NL.E0104',
+    'NL.E0200',
+    'NL.E0201',
+    'NL.E0300',
+    'NL.E0301',
+    'NL.E0400',
+    'NL.E0401',
+    'NL.E0402',
+    'NL.E0403',
+    'NL.E0404',
+    'NL.E0405',
+    'NL.E0406',
+    'NL.E0407',
+    'NL.E0408',
+    'NL.E0500',
+    'NL.E0501',
+    'NL.E0502',
+    'NL.E0503',
+    'NL.E0504',
+    'NL.E0505',
+    'NL.E0600',
+    'NL.W0700',
+] as const;

package/src/i18n/index.ts

@@ -0,0 +1,102 @@
+// Validator message registry. Walks the BCP-47 fallback chain, falling
+// through to `en-US` for any missing key. Other locales (fr, fr-CA,
+// fr-FR, …) plug in via `registerBundle` so the renderer in `@nowline/cli`
+// can wire them at startup without forcing `@nowline/core` to import
+// every locale file at build time.
+//
+// Coverage contract: `messages.en.ts` is the source of truth — every
+// `MessageCode` MUST have an entry there. Coverage CI lives in
+// `test/i18n/messages-coverage.test.ts`.
+
+import type { MessageCode } from './codes.js';
+import { messages as enMessages } from './messages.en.js';
+import { messages as frMessages } from './messages.fr.js';
+import { messages as frCAMessages } from './messages.fr-CA.js';
+import { messages as frFRMessages } from './messages.fr-FR.js';
+
+export type { MessageCode } from './codes.js';
+
+// `messages.en.ts` re-exported with its inferred type so other locales
+// can `satisfies` against it. Each function takes one named-argument
+// object and returns a localized string.
+export type MessageBundle = {
+    [K in MessageCode]?: (...args: never[]) => string;
+};
+
+// Bundles are keyed by the BCP-47 tag. `en-US` is the canonical root and
+// `fr` is the neutral French base; `fr-CA` and `fr-FR` are overlay shells
+// that ship empty by design. The fallback walker (`fr-CA → fr → en-US`)
+// fills in any missing keys, so authors only have to populate the
+// overlays when a regional divergence actually exists.
+//
+// Empty overlays are intentional — they establish the contract for
+// where regional divergences go when they appear, and keep the
+// distribution surface uniform across locales.
+const bundles = new Map<string, MessageBundle>([
+    ['en-US', enMessages as MessageBundle],
+    ['fr', frMessages],
+    ['fr-CA', frCAMessages],
+    ['fr-FR', frFRMessages],
+]);
+
+export function registerBundle(locale: string, bundle: MessageBundle): void {
+    bundles.set(locale, bundle);
+}
+
+/**
+ * Format a message in the resolved locale.
+ *
+ * Walks the locale fallback chain (`fr-CA → fr → en-US`) and returns
+ * the first match. Always returns a string because `en-US` is
+ * guaranteed to define every code.
+ */
+export function tr<K extends MessageCode>(
+    locale: string,
+    code: K,
+    ...args: MessageArgs<K>
+): string {
+    for (const tag of fallbackChain(locale)) {
+        const bundle = bundles.get(tag);
+        const fn = bundle?.[code];
+        if (fn) return (fn as (...a: typeof args) => string)(...args);
+    }
+    // Defensive fallback: en-US must define every code, but if a future
+    // refactor accidentally forgets one, surface the code itself rather
+    // than throwing — partial localization is recoverable; a thrown
+    // exception during validation is not.
+    return code;
+}
+
+// Type helper: extract the named-argument object type for a given code.
+// `messages.en.ts` is the canonical signature source; other bundles
+// satisfy `MessageBundle`, which only constrains the return type.
+export type MessageArgs<K extends MessageCode> = Parameters<(typeof enMessages)[K]>;
+
+const DEFAULT_LOCALE = 'en-US';
+
+// Local copy of the BCP-47 fallback walker. Intentionally duplicated
+// from `@nowline/layout/i18n` (which has the same logic) so that
+// `@nowline/core` doesn't depend on `@nowline/layout`. The two
+// implementations should evolve together — see `specs/localization.md`.
+function fallbackChain(locale: string): string[] {
+    const chain: string[] = [];
+    let current = normalize(locale);
+    while (current.length > 0) {
+        if (!chain.includes(current)) chain.push(current);
+        const dash = current.lastIndexOf('-');
+        if (dash <= 0) break;
+        current = current.slice(0, dash);
+    }
+    if (!chain.includes(DEFAULT_LOCALE)) chain.push(DEFAULT_LOCALE);
+    return chain;
+}
+
+function normalize(locale: string): string {
+    const parts = locale.split('-');
+    return parts
+        .map((part, i) => {
+            if (i === 0) return part.toLowerCase();
+            return /^[a-zA-Z]{2}$/.test(part) ? part.toUpperCase() : part;
+        })
+        .join('-');
+}

package/src/i18n/messages.en.ts

@@ -0,0 +1,86 @@
+// English message bundle. The root locale — every key here MUST exist
+// (CI enforces this in `messages-coverage.test.ts`). Other locales may
+// omit keys; the loader falls through to en-US for any missing entry.
+//
+// Each entry is a plain function taking strongly-typed args. This keeps
+// translation reviewable (no positional `{0}` / `{1}` indirection) and
+// gives every placeholder a name. Authors translating to fr only have
+// to swap the function body — the signature stays identical.
+//
+// We deliberately do NOT use `satisfies Record<MessageCode, ...>` here:
+// the type of each entry is what `MessageArgs<K>` (in `index.ts`) reads
+// to type-check call sites. A `satisfies` constraint would widen each
+// entry to a uniform `(...args: never[]) => string` signature and break
+// per-code argument inference. Coverage of `MessageCode` is enforced by
+// the runtime test in `test/i18n/messages-coverage.test.ts`.
+
+export const messages = {
+    // Structural
+    'NL.E0001': () => 'Config section must appear before roadmap.',
+    'NL.E0002': () => 'Include declarations must appear before the config section.',
+    'NL.E0003': () => 'Include declarations must appear before the roadmap section.',
+    'NL.E0004': () => 'At least one swimlane is required.',
+    'NL.E0005': (a: { line: number }) =>
+        `Line ${a.line}: mixed tabs and spaces in indentation. Use either tabs or spaces consistently.`,
+
+    // Directive
+    'NL.E0100': (a: { version: string }) =>
+        `Invalid version format "${a.version}". Expected format: v1, v2, etc.`,
+    'NL.E0101': (a: { version: string; supported: string }) =>
+        `This file requires Nowline ${a.version}, but the parser only supports up to ${a.supported}.`,
+    'NL.E0102': (a: { key: string; allowed: string }) =>
+        `Unknown directive property "${a.key}". Allowed: ${a.allowed}.`,
+    'NL.E0103': (a: { key: string }) => `Duplicate directive property "${a.key}".`,
+    'NL.E0104': (a: { value: string }) =>
+        `Invalid locale "${a.value}". Use a BCP-47 tag like "en-US", "fr", or "fr-CA".`,
+
+    // Include
+    'NL.E0200': (a: { value: string }) =>
+        `Invalid include mode "${a.value}". Must be merge, ignore, or isolate.`,
+    'NL.E0201': (a: { key: string }) => `Duplicate "${a.key}" option on include.`,
+
+    // Identifier
+    'NL.E0300': (a: { name: string; location: string }) =>
+        `Duplicate identifier "${a.name}". First declared at ${a.location}.`,
+    'NL.E0301': (a: { type: string }) => `${a.type} must have an identifier, a title, or both.`,
+
+    // Property values
+    'NL.E0400': (a: { value: string }) =>
+        `Invalid duration "${a.value}". Use a raw duration literal like 0.5d, 2w, 1m, 2q. Use "size:NAME" to reference a declared size.`,
+    'NL.E0401': (a: { value: string }) =>
+        `Invalid size "${a.value}". Use the id of a declared size (e.g. xs, m, lg).`,
+    'NL.E0402': (a: { value: string }) =>
+        `Invalid effort "${a.value}". Use a raw duration literal like 0.5d, 2w, 1m, 2q.`,
+    'NL.E0403': (a: { value: string }) =>
+        `Invalid remaining value "${a.value}". Use a percentage like 30% or a duration literal like 1w, 0.5d.`,
+    'NL.E0404': (a: { value: string }) => `Remaining must be between 0% and 100%, got ${a.value}.`,
+    'NL.E0405': (a: { key: string; value: string }) =>
+        `Invalid ${a.key} "${a.value}". Use ISO 8601 format: YYYY-MM-DD.`,
+    'NL.E0406': (a: { value: string }) =>
+        `Invalid scale "${a.value}". Use a raw duration literal like 1w, 2w, 1q (no name lookup).`,
+    'NL.E0407': (a: { value: string }) =>
+        `Invalid calendar "${a.value}". Must be business, full, or custom.`,
+    'NL.E0408': (a: { key: string }) => `Property "${a.key}" requires at least one reference.`,
+
+    // Anchor / milestone / footnote
+    'NL.E0500': (a: { name: string }) => `Anchor "${a.name}" requires a "date:" property.`,
+    'NL.E0501': (a: { name: string }) =>
+        `Anchor "${a.name}" has a date but the roadmap is missing "start:". Add start:YYYY-MM-DD to the roadmap.`,
+    'NL.E0502': (a: { name: string; date: string; start: string }) =>
+        `Anchor "${a.name}" date ${a.date} is before roadmap start ${a.start}.`,
+    'NL.E0503': (a: { name: string }) =>
+        `Milestone "${a.name}" requires at least one of "date:" or "after:".`,
+    'NL.E0504': (a: { name: string; date: string; start: string }) =>
+        `Milestone "${a.name}" date ${a.date} is before roadmap start ${a.start}.`,
+    'NL.E0505': () => 'Footnote requires an "on:" property referencing one or more entities.',
+
+    // Item
+    'NL.E0600': (a: { name: string }) =>
+        `Item "${a.name}" requires a "size:" or "duration:" property.`,
+
+    // Warnings
+    'NL.W0700': (a: { key: string; entity: string; suggested: string }) =>
+        `Unknown property "${a.key}" on ${a.entity}. The renderer ignores it.${
+            a.suggested ? ` Did you mean "${a.suggested}"?` : ''
+        }`,
+};

package/src/i18n/messages.fr-CA.ts

@@ -0,0 +1,13 @@
+// Bundle de messages — surcouche fr-CA (Québec).
+//
+// Vide à la conception. Cette surcouche existe pour héberger les
+// divergences spécifiques au Québec lorsqu'elles apparaissent\ : une
+// terminologie OQLF qui s'écarte du français neutre est rejetée de
+// `messages.fr.ts` et atterrit ici.
+//
+// Les clés absentes redescendent automatiquement la chaîne de repli
+// BCP-47\ : `fr-CA → fr → en-US`. Voir `specs/localization.md`.
+
+import type { MessageBundle } from './index.js';
+
+export const messages: MessageBundle = {};

package/src/i18n/messages.fr-FR.ts

@@ -0,0 +1,13 @@
+// Bundle de messages — surcouche fr-FR (France).
+//
+// Vide à la conception. Cette surcouche existe pour héberger les
+// divergences spécifiques à la France hexagonale lorsqu'elles
+// apparaissent\ : une terminologie qui s'écarte du français neutre est
+// rejetée de `messages.fr.ts` et atterrit ici.
+//
+// Les clés absentes redescendent automatiquement la chaîne de repli
+// BCP-47\ : `fr-FR → fr → en-US`. Voir `specs/localization.md`.
+
+import type { MessageBundle } from './index.js';
+
+export const messages: MessageBundle = {};

package/src/i18n/messages.fr.ts

@@ -0,0 +1,91 @@
+// Bundle de messages français — base régionalement neutre.
+//
+// Les divergences spécifiques au Québec ou à la France vont dans
+// `messages.fr-CA.ts` / `messages.fr-FR.ts`, qui se superposent par-dessus
+// celui-ci via la chaîne de repli BCP-47 (`fr-CA → fr → en-US`).
+//
+// Origine\ : traduction automatique amorcée, puis relecture humaine
+// francophone du Québec (terminologie OQLF, Grand dictionnaire
+// terminologique). Toute formulation typiquement québécoise doit
+// descendre dans `messages.fr-CA.ts` plutôt que de polluer cette base.
+//
+// Les clés manquantes ici font silencieusement repli sur `messages.en.ts`,
+// donc une couverture partielle est sûre.
+
+import type { MessageBundle } from './index.js';
+
+export const messages: MessageBundle = {
+    // Structurel
+    'NL.E0001': () => 'La section config doit précéder la section roadmap.',
+    'NL.E0002': () => 'Les déclarations include doivent précéder la section config.',
+    'NL.E0003': () => 'Les déclarations include doivent précéder la section roadmap.',
+    'NL.E0004': () => 'Au moins une swimlane est requise.',
+    'NL.E0005': (a: { line: number }) =>
+        `Ligne ${a.line}\u00A0: tabulations et espaces mélangés dans l'indentation. Utilisez l'un ou l'autre, mais pas les deux.`,
+
+    // Directive
+    'NL.E0100': (a: { version: string }) =>
+        `Format de version invalide «\u00A0${a.version}\u00A0». Format attendu\u00A0: v1, v2, etc.`,
+    'NL.E0101': (a: { version: string; supported: string }) =>
+        `Ce fichier requiert Nowline ${a.version}, mais l'analyseur ne prend en charge que jusqu'à ${a.supported}.`,
+    'NL.E0102': (a: { key: string; allowed: string }) =>
+        `Propriété de directive inconnue «\u00A0${a.key}\u00A0». Valeurs admises\u00A0: ${a.allowed}.`,
+    'NL.E0103': (a: { key: string }) => `Propriété de directive «\u00A0${a.key}\u00A0» en double.`,
+    'NL.E0104': (a: { value: string }) =>
+        `Locale invalide «\u00A0${a.value}\u00A0». Utilisez une étiquette BCP-47 telle que «\u00A0en-US\u00A0», «\u00A0fr\u00A0» ou «\u00A0fr-CA\u00A0».`,
+
+    // Include
+    'NL.E0200': (a: { value: string }) =>
+        `Mode d'include invalide «\u00A0${a.value}\u00A0». Doit être merge, ignore ou isolate.`,
+    'NL.E0201': (a: { key: string }) => `Option «\u00A0${a.key}\u00A0» en double sur include.`,
+
+    // Identifiant
+    'NL.E0300': (a: { name: string; location: string }) =>
+        `Identifiant en double «\u00A0${a.name}\u00A0». Première déclaration à ${a.location}.`,
+    'NL.E0301': (a: { type: string }) =>
+        `${a.type} doit comporter un identifiant, un titre, ou les deux.`,
+
+    // Valeurs de propriété
+    'NL.E0400': (a: { value: string }) =>
+        `Durée invalide «\u00A0${a.value}\u00A0». Utilisez un littéral de durée brut comme 0.5d, 2w, 1m, 2q. Utilisez «\u00A0size:NOM\u00A0» pour référencer une taille déclarée.`,
+    'NL.E0401': (a: { value: string }) =>
+        `Taille invalide «\u00A0${a.value}\u00A0». Utilisez l'identifiant d'une taille déclarée (p.\u00A0ex. xs, m, lg).`,
+    'NL.E0402': (a: { value: string }) =>
+        `Effort invalide «\u00A0${a.value}\u00A0». Utilisez un littéral de durée brut comme 0.5d, 2w, 1m, 2q.`,
+    'NL.E0403': (a: { value: string }) =>
+        `Valeur restante invalide «\u00A0${a.value}\u00A0». Utilisez un pourcentage tel que 30% ou un littéral de durée comme 1w, 0.5d.`,
+    'NL.E0404': (a: { value: string }) =>
+        `La valeur restante doit être comprise entre 0 % et 100 %, reçu ${a.value}.`,
+    'NL.E0405': (a: { key: string; value: string }) =>
+        `${a.key} invalide «\u00A0${a.value}\u00A0». Utilisez le format ISO 8601\u00A0: AAAA-MM-JJ.`,
+    'NL.E0406': (a: { value: string }) =>
+        `Échelle invalide «\u00A0${a.value}\u00A0». Utilisez un littéral de durée brut comme 1w, 2w, 1q (pas de recherche par nom).`,
+    'NL.E0407': (a: { value: string }) =>
+        `Calendrier invalide «\u00A0${a.value}\u00A0». Doit être business, full ou custom.`,
+    'NL.E0408': (a: { key: string }) =>
+        `La propriété «\u00A0${a.key}\u00A0» exige au moins une référence.`,
+
+    // Ancre / jalon / note de bas de page
+    'NL.E0500': (a: { name: string }) =>
+        `L'ancre «\u00A0${a.name}\u00A0» exige une propriété «\u00A0date:\u00A0».`,
+    'NL.E0501': (a: { name: string }) =>
+        `L'ancre «\u00A0${a.name}\u00A0» a une date, mais «\u00A0start:\u00A0» manque sur la roadmap. Ajoutez start:AAAA-MM-JJ à la roadmap.`,
+    'NL.E0502': (a: { name: string; date: string; start: string }) =>
+        `La date ${a.date} de l'ancre «\u00A0${a.name}\u00A0» précède le début de la roadmap (${a.start}).`,
+    'NL.E0503': (a: { name: string }) =>
+        `Le jalon «\u00A0${a.name}\u00A0» exige au moins l'une des propriétés «\u00A0date:\u00A0» ou «\u00A0after:\u00A0».`,
+    'NL.E0504': (a: { name: string; date: string; start: string }) =>
+        `La date ${a.date} du jalon «\u00A0${a.name}\u00A0» précède le début de la roadmap (${a.start}).`,
+    'NL.E0505': () =>
+        'Une note de bas de page exige une propriété «\u00A0on:\u00A0» référençant au moins une entité.',
+
+    // Élément
+    'NL.E0600': (a: { name: string }) =>
+        `L'élément «\u00A0${a.name}\u00A0» exige une propriété «\u00A0size:\u00A0» ou «\u00A0duration:\u00A0».`,
+
+    // Avertissements
+    'NL.W0700': (a: { key: string; entity: string; suggested: string }) =>
+        `Propriété inconnue «\u00A0${a.key}\u00A0» sur ${a.entity}. Le moteur de rendu l'ignore.${
+            a.suggested ? ` Vouliez-vous dire «\u00A0${a.suggested}\u00A0»\u00A0?` : ''
+        }`,
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+export * from './generated/ast.js';
+export * from './generated/module.js';
+export { ALL_CODES, type MessageCode } from './i18n/codes.js';
+export {
+    type MessageArgs,
+    type MessageBundle,
+    registerBundle,
+    tr,
+} from './i18n/index.js';
+export {
+    type IncludeMode,
+    type IsolatedRegion,
+    type ResolveDiagnostic,
+    type ResolvedConfig,
+    type ResolvedContent,
+    type ResolveIncludesOptions,
+    type ResolveResult,
+    resolveIncludes,
+} from './language/include-resolver.js';
+export type { NowlineAddedServices, NowlineServices } from './language/nowline-module.js';
+export { createNowlineServices, NowlineModule } from './language/nowline-module.js';
+export { NowlineValidator, registerValidationChecks } from './language/nowline-validator.js';