@nowline/cli 0.0.0-dev.20260601071750.g04bdff9

package/src/convert/printer.ts

@@ -0,0 +1,376 @@
+import { CliError, ExitCode } from '../io/exit-codes.js';
+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 path = 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(path)}${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 CliError(
+                    ExitCode.ValidationError,
+                    `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 CliError(
+                    ExitCode.ValidationError,
+                    `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 CliError(
+            ExitCode.ValidationError,
+            `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 CliError(
+                    ExitCode.ValidationError,
+                    `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`. Uses formatAtom so
+// that quoted / template strings such as `label: "W{n}"` survive a round-trip.
+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;
+    }
+    // Already-quoted string survives a round trip through JSON.stringify by re-quoting once.
+    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 CliError(
+            ExitCode.ValidationError,
+            `Expected $type "${expected}", got "${String(node.$type)}"`,
+        );
+    }
+}

package/src/convert/schema.ts

@@ -0,0 +1,105 @@
+import type { NowlineFile } from '@nowline/core';
+import type { AstNode, CstNode, LangiumDocument } from 'langium';
+
+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/core/parse.ts

@@ -0,0 +1,97 @@
+import {
+    collectDocumentDiagnostics,
+    createNowlineServices,
+    type NowlineFile,
+    type NowlineServices,
+} from '@nowline/core';
+import { type LangiumDocument, URI } from 'langium';
+import { adaptLangiumDiagnostic, adaptLexerError, adaptParserError } from '../diagnostics/adapt.js';
+import type { CliDiagnostic, DiagnosticSource } from '../diagnostics/model.js';
+
+export interface ParseOptions {
+    validate?: boolean;
+}
+
+export interface ParseResult {
+    ast: NowlineFile;
+    document: LangiumDocument<NowlineFile>;
+    diagnostics: CliDiagnostic[];
+    /** True if any diagnostic (parse, lex, or semantic validation) has severity 'error'. */
+    hasErrors: boolean;
+    /** True if any *parser/lexer* diagnostic is present. Semantic validation errors don't count. */
+    hasParseErrors: boolean;
+    source: DiagnosticSource;
+}
+
+type Services = {
+    shared: ReturnType<typeof createNowlineServices>['shared'];
+    Nowline: NowlineServices;
+};
+
+let cachedServices: Services | undefined;
+let docCounter = 0;
+
+export function getServices(): Services {
+    if (!cachedServices) cachedServices = createNowlineServices();
+    return cachedServices;
+}
+
+export async function parseSource(
+    contents: string,
+    filePath: string,
+    options: ParseOptions = {},
+): Promise<ParseResult> {
+    const services = getServices();
+    const uri = uriFor(filePath);
+    const docFactory = services.shared.workspace.LangiumDocumentFactory;
+    const doc = docFactory.fromString<NowlineFile>(contents, uri);
+    await services.shared.workspace.DocumentBuilder.build([doc], {
+        validation: options.validate ?? true,
+    });
+
+    const source: DiagnosticSource = { file: filePath, contents };
+    const diagnostics: CliDiagnostic[] = [];
+    const parseDiagnostics: CliDiagnostic[] = [];
+
+    // collectDocumentDiagnostics owns the de-dup: Langium re-folds lexer +
+    // parser errors into doc.diagnostics, so the shared collector skips those
+    // copies. Lexer/parser rows also feed `parseDiagnostics` (drives the
+    // hasParseErrors gate that suppresses downstream layout/render).
+    for (const raw of collectDocumentDiagnostics(doc)) {
+        if (raw.origin === 'lexer') {
+            const adapted = adaptLexerError(raw.error, filePath);
+            parseDiagnostics.push(adapted);
+            diagnostics.push(adapted);
+        } else if (raw.origin === 'parser') {
+            const adapted = adaptParserError(raw.error, filePath);
+            parseDiagnostics.push(adapted);
+            diagnostics.push(adapted);
+        } else {
+            diagnostics.push(adaptLangiumDiagnostic(raw.diagnostic, filePath));
+        }
+    }
+
+    const hasErrors = diagnostics.some((d) => d.severity === 'error');
+    const hasParseErrors = parseDiagnostics.some((d) => d.severity === 'error');
+    return {
+        ast: doc.parseResult.value,
+        document: doc,
+        diagnostics,
+        hasErrors,
+        hasParseErrors,
+        source,
+    };
+}
+
+function uriFor(filePath: string): URI {
+    // Always mint a fresh URI for each parse. Re-using a URI across calls causes
+    // Langium's DocumentBuilder to mutate the prior document and/or rebind
+    // cross-references against an incompatible AST, which surfaces as spurious
+    // diagnostics when the CLI is embedded in a long-running process (tests,
+    // language server, etc.). The suffix ensures `build([doc])` is always a net
+    // new document.
+    if (filePath === '<stdin>') {
+        return URI.parse(`memory:///stdin-${++docCounter}.nowline`);
+    }
+    return URI.parse(`memory:///doc-${++docCounter}.nowline`);
+}

package/src/diagnostics/adapt.ts

@@ -0,0 +1,89 @@
+import {
+    extractSuggestion,
+    type LangiumLikeDiagnostic,
+    type LexerErrorLike,
+    type ParserErrorLike,
+    resolveDiagnosticCode,
+} from '@nowline/core';
+import type { CliDiagnostic, DiagnosticSeverity, LocalizedMessageData } from './model.js';
+
+export function adaptLangiumDiagnostic(diag: LangiumLikeDiagnostic, file: string): CliDiagnostic {
+    const severity = mapSeverity(diag.severity);
+    const line = (diag.range?.start.line ?? 0) + 1;
+    const column = (diag.range?.start.character ?? 0) + 1;
+    return {
+        file,
+        line,
+        column,
+        severity,
+        // resolveDiagnosticCode prefers the stable validator code carried in
+        // `data`, then Langium's `code`, then a message heuristic.
+        code: resolveDiagnosticCode(diag),
+        message: diag.message,
+        span: diag.range
+            ? {
+                  start: { line, column },
+                  end: {
+                      line: (diag.range.end.line ?? 0) + 1,
+                      column: (diag.range.end.character ?? 0) + 1,
+                  },
+              }
+            : undefined,
+        suggestion: extractSuggestion(diag.message),
+        // The CLI keeps the full { code, args } so formatDiagnostics can
+        // re-render the message in the operator's locale at print time.
+        data: extractMessageData(diag.data),
+    };
+}
+
+/**
+ * Validate the shape of `diag.data`. Validator-emitted diagnostics
+ * stash `{ code: MessageCode, args: MessageArgs<K> }` (where `args` is
+ * the spread tuple `[]` or `[{...}]`). Anything else (vscode code
+ * actions, third-party data, etc.) is ignored.
+ */
+function extractMessageData(data: unknown): LocalizedMessageData | undefined {
+    if (!data || typeof data !== 'object') return undefined;
+    const obj = data as { code?: unknown; args?: unknown };
+    if (typeof obj.code !== 'string') return undefined;
+    if (!Array.isArray(obj.args)) return undefined;
+    return { code: obj.code, args: obj.args };
+}
+
+export function adaptParserError(err: ParserErrorLike, file: string): CliDiagnostic {
+    const line = err.token?.startLine ?? 1;
+    const column = err.token?.startColumn ?? 1;
+    const endLine = err.token?.endLine ?? line;
+    const endColumn = (err.token?.endColumn ?? column) + 1;
+    return {
+        file,
+        line,
+        column,
+        severity: 'error',
+        code: 'parse-error',
+        message: err.message,
+        span: { start: { line, column }, end: { line: endLine, column: endColumn } },
+    };
+}
+
+export function adaptLexerError(err: LexerErrorLike, file: string): CliDiagnostic {
+    const line = err.line ?? 1;
+    const column = err.column ?? 1;
+    const length = err.length ?? 1;
+    return {
+        file,
+        line,
+        column,
+        severity: 'error',
+        code: 'lex-error',
+        message: err.message,
+        span: {
+            start: { line, column },
+            end: { line, column: column + Math.max(length, 1) },
+        },
+    };
+}
+
+function mapSeverity(severity: number | undefined): DiagnosticSeverity {
+    return severity === 2 ? 'warning' : 'error';
+}