@nowline/core 0.6.0 → 0.8.0

package/src/convert/printer.ts

@@ -0,0 +1,358 @@
+import type { JsonAstNode } from './schema.js';
+
+// Keyed-property canonical order. Keys not in this list sort alphabetically after.
+const KEY_ORDER = [
+    'date',
+    'effort',
+    'on',
+    'size',
+    'duration',
+    'status',
+    'owner',
+    'after',
+    'before',
+    'remaining',
+    'labels',
+    'style',
+    'link',
+    'author',
+    'start',
+    'scale',
+    'calendar',
+    'header-position',
+    'timeline-position',
+    'minor-grid',
+];
+
+const INDENT = '  ';
+
+export interface PrintOptions {
+    indent?: string;
+}
+
+export function printNowlineFile(ast: JsonAstNode, options: PrintOptions = {}): string {
+    const printer = new Printer(options.indent ?? INDENT);
+    printer.file(ast);
+    return printer.toString();
+}
+
+class Printer {
+    private readonly lines: string[] = [];
+
+    constructor(private readonly indent: string) {}
+
+    toString(): string {
+        const text = this.lines.join('\n');
+        return text.endsWith('\n') ? text : `${text}\n`;
+    }
+
+    file(file: JsonAstNode): void {
+        assertType(file, 'NowlineFile');
+        const directive = file.directive as JsonAstNode | undefined;
+        if (directive) {
+            const props = asArray(directive.properties);
+            const tail = props.length > 0 ? ` ${props.map(renderProperty).join(' ')}` : '';
+            this.line(0, `nowline ${getString(directive, 'version')}${tail}`);
+            this.blank();
+        }
+        for (const inc of asArray(file.includes)) {
+            this.include(inc);
+        }
+        if (asArray(file.includes).length > 0) this.blank();
+        if (file.hasConfig) {
+            this.line(0, 'config');
+            this.blank();
+            for (const entry of asArray(file.configEntries)) {
+                this.configEntry(entry);
+                this.blank();
+            }
+        }
+        if (file.roadmapDecl) {
+            this.roadmap(file.roadmapDecl as JsonAstNode);
+            this.blank();
+        }
+        for (const entry of asArray(file.roadmapEntries)) {
+            this.roadmapEntry(entry, 0);
+        }
+    }
+
+    include(inc: JsonAstNode): void {
+        assertType(inc, 'IncludeDeclaration');
+        const p = getString(inc, 'path');
+        const options = asArray(inc.options)
+            .map((o) => `${getString(o, 'key')}:${getString(o, 'value')}`)
+            .join(' ');
+        const tail = options ? ` ${options}` : '';
+        this.line(0, `include ${JSON.stringify(p)}${tail}`);
+    }
+
+    configEntry(entry: JsonAstNode): void {
+        switch (entry.$type) {
+            case 'ScaleBlock':
+                return this.blockDecl('scale', asArray(entry.properties));
+            case 'CalendarBlock':
+                return this.blockDecl('calendar', asArray(entry.properties));
+            case 'StyleDeclaration':
+                return this.styleDecl(entry);
+            case 'DefaultDeclaration':
+                return this.defaultDecl(entry);
+            default:
+                throw new Error(`Unknown config entry type: ${String(entry.$type)}`);
+        }
+    }
+
+    blockDecl(keyword: string, properties: JsonAstNode[]): void {
+        this.line(0, keyword);
+        for (const p of properties) {
+            this.line(1, renderBlockProperty(p));
+        }
+    }
+
+    styleDecl(entry: JsonAstNode): void {
+        assertType(entry, 'StyleDeclaration');
+        const header = declarationHeader('style', entry, []);
+        this.line(0, header);
+        for (const p of asArray(entry.properties)) {
+            this.line(1, renderBlockProperty(p));
+        }
+    }
+
+    defaultDecl(entry: JsonAstNode): void {
+        assertType(entry, 'DefaultDeclaration');
+        const entityType = getString(entry, 'entityType');
+        const props = renderProperties(asArray(entry.properties));
+        const tail = props ? ` ${props}` : '';
+        this.line(0, `default ${entityType}${tail}`);
+    }
+
+    roadmap(decl: JsonAstNode): void {
+        assertType(decl, 'RoadmapDeclaration');
+        this.line(0, declarationHeader('roadmap', decl, asArray(decl.properties)));
+    }
+
+    roadmapEntry(entry: JsonAstNode, depth: number): void {
+        switch (entry.$type) {
+            case 'PersonDeclaration':
+                return this.simpleEntity('person', entry, depth);
+            case 'TeamDeclaration':
+                return this.team(entry, depth);
+            case 'AnchorDeclaration':
+                return this.simpleEntity('anchor', entry, depth);
+            case 'SizeDeclaration':
+                return this.simpleEntity('size', entry, depth);
+            case 'StatusDeclaration':
+                return this.simpleEntity('status', entry, depth);
+            case 'LabelDeclaration':
+                return this.simpleEntity('label', entry, depth);
+            case 'MilestoneDeclaration':
+                return this.simpleEntity('milestone', entry, depth);
+            case 'FootnoteDeclaration':
+                return this.simpleEntity('footnote', entry, depth);
+            case 'SwimlaneDeclaration':
+                return this.swimlane(entry, depth);
+            default:
+                throw new Error(`Unknown roadmap entry type: ${String(entry.$type)}`);
+        }
+    }
+
+    simpleEntity(keyword: string, entry: JsonAstNode, depth: number): void {
+        this.line(depth, declarationHeader(keyword, entry, asArray(entry.properties)));
+        this.maybeDescription(entry, depth + 1);
+    }
+
+    team(entry: JsonAstNode, depth: number): void {
+        this.line(depth, declarationHeader('team', entry, asArray(entry.properties)));
+        for (const child of asArray(entry.content)) {
+            this.teamContent(child, depth + 1);
+        }
+    }
+
+    teamContent(node: JsonAstNode, depth: number): void {
+        if (node.$type === 'PersonMemberRef') {
+            this.line(depth, `person ${getString(node, 'ref')}`);
+            return;
+        }
+        if (node.$type === 'TeamDeclaration') {
+            return this.team(node, depth);
+        }
+        if (node.$type === 'PersonDeclaration') {
+            return this.simpleEntity('person', node, depth);
+        }
+        if (node.$type === 'DescriptionDirective') {
+            return this.descriptionDirective(node, depth);
+        }
+        throw new Error(`Unknown team content type: ${String(node.$type)}`);
+    }
+
+    swimlane(entry: JsonAstNode, depth: number): void {
+        this.line(depth, declarationHeader('swimlane', entry, asArray(entry.properties)));
+        for (const child of asArray(entry.content)) {
+            this.swimlaneContent(child, depth + 1);
+        }
+    }
+
+    swimlaneContent(node: JsonAstNode, depth: number): void {
+        switch (node.$type) {
+            case 'ItemDeclaration':
+                this.simpleEntity('item', node, depth);
+                return;
+            case 'ParallelBlock':
+                this.parallelBlock(node, depth);
+                return;
+            case 'GroupBlock':
+                this.groupBlock(node, depth);
+                return;
+            case 'DescriptionDirective':
+                this.descriptionDirective(node, depth);
+                return;
+            default:
+                throw new Error(`Unknown swimlane content type: ${String(node.$type)}`);
+        }
+    }
+
+    parallelBlock(entry: JsonAstNode, depth: number): void {
+        this.line(depth, declarationHeader('parallel', entry, asArray(entry.properties)));
+        for (const child of asArray(entry.content)) {
+            this.swimlaneContent(child, depth + 1);
+        }
+    }
+
+    groupBlock(entry: JsonAstNode, depth: number): void {
+        this.line(depth, declarationHeader('group', entry, asArray(entry.properties)));
+        for (const child of asArray(entry.content)) {
+            this.swimlaneContent(child, depth + 1);
+        }
+    }
+
+    descriptionDirective(node: JsonAstNode, depth: number): void {
+        assertType(node, 'DescriptionDirective');
+        this.line(depth, `description ${JSON.stringify(getString(node, 'text'))}`);
+    }
+
+    maybeDescription(entry: JsonAstNode, depth: number): void {
+        const desc = entry.description as JsonAstNode | undefined;
+        if (desc) this.descriptionDirective(desc, depth);
+    }
+
+    private line(depth: number, text: string): void {
+        this.lines.push(this.indent.repeat(depth) + text);
+    }
+
+    private blank(): void {
+        if (this.lines.length === 0) return;
+        if (this.lines[this.lines.length - 1] === '') return;
+        this.lines.push('');
+    }
+}
+
+function declarationHeader(keyword: string, entry: JsonAstNode, properties: JsonAstNode[]): string {
+    const id = entry.name as string | undefined;
+    const title = entry.title as string | undefined;
+    const parts = [keyword];
+    if (id) parts.push(id);
+    if (title) parts.push(JSON.stringify(title));
+    const props = renderProperties(properties);
+    if (props) parts.push(props);
+    return parts.join(' ');
+}
+
+function renderProperties(properties: JsonAstNode[]): string {
+    return orderProperties(properties).map(renderProperty).join(' ');
+}
+
+function orderProperties(properties: JsonAstNode[]): JsonAstNode[] {
+    const indexOf = new Map(KEY_ORDER.map((k, i) => [k, i] as const));
+    return [...properties].sort((a, b) => {
+        const ak = normalizeKey(getString(a, 'key'));
+        const bk = normalizeKey(getString(b, 'key'));
+        const ai = indexOf.get(ak);
+        const bi = indexOf.get(bk);
+        if (ai !== undefined && bi !== undefined) return ai - bi;
+        if (ai !== undefined) return -1;
+        if (bi !== undefined) return 1;
+        return ak.localeCompare(bk);
+    });
+}
+
+function renderProperty(prop: JsonAstNode): string {
+    const key = normalizeKey(getString(prop, 'key'));
+    const values = asStringArray(prop.values);
+    const value = prop.value as string | undefined;
+    if (values.length >= 2) {
+        return `${key}:[${values.map(formatAtom).join(', ')}]`;
+    }
+    if (values.length === 1) {
+        return `${key}:${formatAtom(values[0])}`;
+    }
+    if (value !== undefined && value !== '') {
+        return `${key}:${formatAtom(value)}`;
+    }
+    return `${key}:`;
+}
+
+// Block-style property (one per line, rendered as `key: value`). Used inside
+// indented blocks like `scale`, `calendar`, and `style`.
+function renderBlockProperty(prop: JsonAstNode): string {
+    const key = normalizeKey(getString(prop, 'key'));
+    const values = asStringArray(prop.values);
+    const value = prop.value as string | undefined;
+    if (values.length >= 2) {
+        return `${key}: [${values.map(formatAtom).join(', ')}]`;
+    }
+    if (values.length === 1) {
+        return `${key}: ${formatAtom(values[0])}`;
+    }
+    if (value !== undefined && value !== '') {
+        return `${key}: ${formatAtom(value)}`;
+    }
+    return `${key}:`;
+}
+
+function normalizeKey(key: string): string {
+    return key.endsWith(':') ? key.slice(0, -1) : key;
+}
+
+const URL_RE = /^https?:\/\//;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DURATION_RE = /^\d+(?:\.\d+)?[dwmqy]$/;
+const PERCENTAGE_RE = /^\d+%$/;
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{3,8}$/;
+const INTEGER_RE = /^\d+$/;
+const ID_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+function formatAtom(atom: string): string {
+    if (
+        URL_RE.test(atom) ||
+        DATE_RE.test(atom) ||
+        DURATION_RE.test(atom) ||
+        PERCENTAGE_RE.test(atom) ||
+        HEX_COLOR_RE.test(atom) ||
+        INTEGER_RE.test(atom) ||
+        ID_RE.test(atom)
+    ) {
+        return atom;
+    }
+    if (atom.startsWith('"') && atom.endsWith('"')) return atom;
+    return JSON.stringify(atom);
+}
+
+function asArray(value: unknown): JsonAstNode[] {
+    if (Array.isArray(value)) return value as JsonAstNode[];
+    return [];
+}
+
+function asStringArray(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    return value.filter((v): v is string => typeof v === 'string');
+}
+
+function getString(node: JsonAstNode | Record<string, unknown>, key: string): string {
+    const value = (node as Record<string, unknown>)[key];
+    return typeof value === 'string' ? value : '';
+}
+
+function assertType(node: JsonAstNode, expected: string): void {
+    if (node.$type !== expected) {
+        throw new Error(`Expected $type "${expected}", got "${String(node.$type)}"`);
+    }
+}

package/src/convert/schema.ts

@@ -0,0 +1,105 @@
+import type { AstNode, CstNode, LangiumDocument } from 'langium';
+import type { NowlineFile } from '../generated/ast.js';
+
+export const NOWLINE_SCHEMA_VERSION = '1';
+
+export interface NowlineDocument {
+    $nowlineSchema: string;
+    file: { uri: string; source: string };
+    ast: JsonAstNode;
+}
+
+export interface Position {
+    start: { line: number; column: number; offset: number };
+    end: { line: number; column: number; offset: number };
+}
+
+export interface JsonAstNode {
+    $type: string;
+    $position?: Position;
+    [key: string]: unknown;
+}
+
+export interface SerializeOptions {
+    includePositions?: boolean;
+}
+
+// Keys that Langium adds to AST nodes that we don't want in the JSON form.
+const CONTAINER_KEYS = new Set(['$container', '$containerProperty', '$containerIndex']);
+// $cstNode / $document are runtime-only. $type and $position are emitted.
+const RUNTIME_KEYS = new Set(['$cstNode', '$document']);
+
+export function serializeToJson(
+    document: LangiumDocument<NowlineFile>,
+    source: string,
+    options: SerializeOptions = {},
+): NowlineDocument {
+    const includePositions = options.includePositions ?? true;
+    return {
+        $nowlineSchema: NOWLINE_SCHEMA_VERSION,
+        file: {
+            uri: document.uri.toString(),
+            source,
+        },
+        ast: serializeNode(document.parseResult.value, includePositions),
+    };
+}
+
+function serializeNode(node: AstNode, includePositions: boolean): JsonAstNode {
+    const out: JsonAstNode = { $type: node.$type };
+    if (includePositions) {
+        const pos = cstPosition(node.$cstNode);
+        if (pos) out.$position = pos;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith('$')) continue;
+        if (CONTAINER_KEYS.has(key) || RUNTIME_KEYS.has(key)) continue;
+        out[key] = serializeValue(value, includePositions);
+    }
+    return out;
+}
+
+function serializeValue(value: unknown, includePositions: boolean): unknown {
+    if (value === null || value === undefined) return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => serializeValue(v, includePositions));
+    }
+    if (isAstNode(value)) {
+        return serializeNode(value, includePositions);
+    }
+    if (typeof value === 'object') {
+        const record = value as Record<string, unknown>;
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(record)) {
+            if (k.startsWith('$')) continue;
+            if (CONTAINER_KEYS.has(k) || RUNTIME_KEYS.has(k)) continue;
+            out[k] = serializeValue(v, includePositions);
+        }
+        return out;
+    }
+    return value;
+}
+
+function isAstNode(value: unknown): value is AstNode {
+    return (
+        value !== null &&
+        typeof value === 'object' &&
+        typeof (value as { $type?: unknown }).$type === 'string'
+    );
+}
+
+function cstPosition(cst: CstNode | undefined): Position | undefined {
+    if (!cst) return undefined;
+    return {
+        start: {
+            line: cst.range.start.line + 1,
+            column: cst.range.start.character + 1,
+            offset: cst.offset,
+        },
+        end: {
+            line: cst.range.end.line + 1,
+            column: cst.range.end.character + 1,
+            offset: cst.end,
+        },
+    };
+}

package/src/i18n/codes.ts

@@ -14,6 +14,8 @@
 //   NL.E0800–E0899  style / color / symbol
 //   NL.E0900–E0999  config blocks (calendar, scale, default)
 //   NL.W0700–W0799  warnings (silently-ignored input)
+//   NL.W1000–W1099  layout warnings (author intent lost)
+//   NL.I1000–I1099  layout insights (informational reflow consequences)
 //
 // The full list of allocated codes lives in `messages.en.ts` (one entry
 // per code). The runtime walks the locale fallback chain and falls
@@ -69,7 +71,18 @@ export type MessageCode =
     | 'NL.E0600' // item-requires-size-or-duration
 
     // Warnings (NL.W0700–W0799)
-    | 'NL.W0700'; // unknown-entity-property
+    | 'NL.W0700' // unknown-entity-property
+
+    // Layout warnings (NL.W1000–W1099)
+    | 'NL.W1000' // now-line-outside-window
+
+    // Layout insights (NL.I1000–I1099)
+    | 'NL.I1000' // caption-spilled-right
+    | 'NL.I1001' // label-chips-outside
+    | 'NL.I1002' // bar-too-narrow
+    | 'NL.I1003' // before-overflow
+    | 'NL.I1004' // lane-multi-row
+    | 'NL.I1005'; // lane-over-capacity
 
 export const ALL_CODES: ReadonlyArray<MessageCode> = [
     'NL.E0001',
@@ -107,4 +120,11 @@ export const ALL_CODES: ReadonlyArray<MessageCode> = [
     'NL.E0505',
     'NL.E0600',
     'NL.W0700',
+    'NL.W1000',
+    'NL.I1000',
+    'NL.I1001',
+    'NL.I1002',
+    'NL.I1003',
+    'NL.I1004',
+    'NL.I1005',
 ] as const;

package/src/i18n/messages.en.ts

@@ -91,4 +91,24 @@ export const messages = {
         `Unknown property "${a.key}" on ${a.entity}. The renderer ignores it.${
             a.suggested ? ` Did you mean "${a.suggested}"?` : ''
         }`,
+
+    // Layout warnings
+    'NL.W1000': (a: { date: string; start: string; end: string }) =>
+        `Now-line date ${a.date} is outside the roadmap window (${a.start} – ${a.end}); it will not be drawn.`,
+
+    // Layout insights (informational)
+    'NL.I1000': (a: { name: string }) =>
+        `Title on item "${a.name}" is wider than its bar at this scale; it rendered to the right of the bar.`,
+    'NL.I1001': (a: { name: string }) =>
+        `Label chips on item "${a.name}" did not fit inside the bar; they rendered in a spill column to the right.`,
+    'NL.I1002': (a: { name: string }) =>
+        `Item "${a.name}" is too narrow to show its marker at this scale; decorations spilled beside the bar.`,
+    'NL.I1003': (a: { name: string; anchor?: string }) =>
+        a.anchor
+            ? `Item "${a.name}" extends past its "before:" anchor "${a.anchor}".`
+            : `Item "${a.name}" extends past its "before:" anchor.`,
+    'NL.I1004': (a: { lane: string; rows: number }) =>
+        `Swimlane "${a.lane}" packed into ${a.rows} rows to avoid overlap.`,
+    'NL.I1005': (a: { lane: string }) =>
+        `Swimlane "${a.lane}" is over capacity in one or more periods (red utilization band).`,
 };

package/src/index.ts

@@ -1,3 +1,13 @@
+export { type ParseJsonResult, parseNowlineJson } from './convert/parse-json.js';
+export { type PrintOptions, printNowlineFile } from './convert/printer.js';
+export {
+    type JsonAstNode,
+    NOWLINE_SCHEMA_VERSION,
+    type NowlineDocument,
+    type Position,
+    type SerializeOptions,
+    serializeToJson,
+} from './convert/schema.js';
 export {
     collectDocumentDiagnostics,
     extractSuggestion,
@@ -35,3 +45,4 @@ export {
 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';
+export { TEMPLATE_NAMES, type TemplateName } from './templates.js';

package/src/language/nowline-validator.ts

@@ -329,6 +329,35 @@ function suggestKey(key: string, candidates: Iterable<string>, cap = 2): string
     return best;
 }
 
+// Conceptual mistakes that aren't typos of a real key — e.g. `progress:60` is a
+// reasonable guess for "60% done", but Nowline models completion as
+// `status:` + `remaining:` (work *left*). Levenshtein can't bridge that gap, so
+// we map the concept directly. `requires` names a key the entity must support,
+// so the hint only fires where it's actionable (e.g. on an `item`, which has
+// `remaining`, not on a `roadmap` line).
+const CONCEPT_ALIASES: ReadonlyArray<{
+    keys: ReadonlySet<string>;
+    requires: string;
+    suggest: string;
+}> = [
+    {
+        keys: new Set(['progress', 'percent', 'percentage', 'pct', 'complete', 'completion']),
+        requires: 'remaining',
+        suggest: 'status: + remaining:',
+    },
+];
+
+// Suggest the canonical property (or combination) for a known conceptual
+// mistake, gated to entities that actually support the target key. Returns
+// undefined when no concept matches so callers fall back to `suggestKey`.
+function suggestConcept(key: string, known: ReadonlySet<string>): string | undefined {
+    const lower = key.toLowerCase();
+    for (const alias of CONCEPT_ALIASES) {
+        if (alias.keys.has(lower) && known.has(alias.requires)) return alias.suggest;
+    }
+    return undefined;
+}
+
 function propKey(prop: { key: string }): string {
     return prop.key.endsWith(':') ? prop.key.slice(0, -1) : prop.key;
 }
@@ -1195,7 +1224,7 @@ export class NowlineValidator {
             if (key === 'footnote') continue;
             if (computedBanned?.has(key)) continue;
             const candidates: string[] = [...known, ...UNIVERSAL_ENTITY_PROPS];
-            const suggested = suggestKey(key, candidates) ?? '';
+            const suggested = suggestConcept(key, known) ?? suggestKey(key, candidates) ?? '';
             acceptTr(accept, 'warning', { node: prop, property: 'key' }, 'NL.W0700', {
                 key,
                 entity: describeNode(node),

package/src/templates.ts

@@ -0,0 +1,3 @@
+export type TemplateName = 'minimal' | 'teams' | 'product' | 'showcase';
+
+export const TEMPLATE_NAMES: readonly TemplateName[] = ['minimal', 'teams', 'product', 'showcase'];