gridmd 1.0.0

package/dist/parser.d.ts

@@ -0,0 +1,13 @@
+import type { Diagnostic, InfoArgs, Meta, ParsedDocument } from './types';
+export declare const RESERVED_KINDS: Set<string>;
+export declare function parseYaml(text: string, line: number, errors: Diagnostic[]): Meta;
+export declare function tryProps(text: string): Meta | null;
+export declare function findPropsSplit(text: string): {
+    scalarText: string;
+    propsText: string | null;
+};
+export declare function splitPipeRow(rawLine: string): string[] | null;
+export declare function parseInfoArgs(rest: string, line: number, errors: Diagnostic[]): InfoArgs;
+export declare function parseDocument(source: string, { mode }?: {
+    mode?: string;
+}): ParsedDocument;

package/dist/refs.d.ts

@@ -0,0 +1,8 @@
+import type { CellPos, Target } from './types';
+export declare const MAX_COL = 16384;
+export declare const MAX_ROW = 1048576;
+export declare function colToNum(letters: string): number;
+export declare function numToCol(n: number): string;
+export declare function parseCell(text: string): CellPos | null;
+export declare function parseTarget(input: string): Target | null;
+export declare const refKey: (col: number, row: number) => string;

package/dist/scalar.d.ts

@@ -0,0 +1,7 @@
+import type { Scalar } from './types';
+export declare const ERROR_VALUES: Set<string>;
+export declare function splitCached(text: string): {
+    head: string;
+    cached: string | null;
+};
+export declare function parseScalar(raw: string): Scalar;

package/dist/types.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Open-ended, YAML-derived data (frontmatter, directive metadata, inline
+ * props and `@`-directive bodies). Structurally unconstrained by design; it
+ * enters as parsed YAML and is validated by the lint pass, not by the type
+ * system. Deliberate, documented divergence from CODING_PRACTICES §1.
+ */
+export type Meta = any;
+export interface Diagnostic {
+    line: number;
+    msg: string;
+}
+export type ScalarKind = 'blank' | 'text' | 'formula' | 'number' | 'boolean' | 'date' | 'time' | 'error' | 'invalid';
+/**
+ * One parsed cell scalar. A wide struct that mirrors the runtime object shape
+ * exactly (every field optional) so the parser/serializer round-trip without
+ * narrowing churn; `kind` is the discriminant every consumer switches on.
+ */
+export interface Scalar {
+    kind: ScalarKind;
+    value?: string | number | boolean;
+    formula?: string;
+    cse?: boolean;
+    cached?: Scalar | null;
+    problem?: string;
+    forced?: boolean;
+    quoted?: boolean;
+}
+export type TargetKind = 'cell' | 'range' | 'cols' | 'rows';
+export interface Target {
+    kind: TargetKind;
+    sheet: string | null;
+    c1: number;
+    r1: number;
+    c2: number;
+    r2: number;
+    line?: number;
+}
+export interface CellPos {
+    col: number;
+    row: number;
+}
+export interface XmlNode {
+    name: string;
+    attrs: Record<string, string | undefined>;
+    children: XmlNode[];
+    text: string;
+}
+export interface InfoArgs {
+    positional: string[];
+    flags: Record<string, string | undefined>;
+    anchor: string | null;
+    size: {
+        w: number;
+        h: number;
+    } | null;
+}
+export interface Row {
+    cells: string[];
+    line: number;
+}
+export interface FenceBlock {
+    type: 'fence';
+    kind: string;
+    args: InfoArgs;
+    body: string[];
+    line: number;
+    meta?: Meta;
+    rows?: Row[];
+    code?: string;
+    payload?: string;
+}
+export interface AtBlock {
+    type: 'at';
+    targetText: string;
+    line: number;
+    scalarText: string | null;
+    props: Meta | null;
+    body: Meta | null;
+}
+export type Block = FenceBlock | AtBlock;
+export interface SheetBlock {
+    name: string;
+    line: number;
+    blocks: Block[];
+}
+export interface ParseStats {
+    defs: number;
+    blocks: number;
+}
+export interface ParsedDocument {
+    frontmatter: Meta;
+    workbookBlocks: Block[];
+    sheets: SheetBlock[];
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+    mode: string;
+    stats?: ParseStats;
+}
+export interface LintResult {
+    doc: ParsedDocument;
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+    sheets: number;
+    cells: number;
+    blocks: number;
+}
+export interface CellContent {
+    formula?: string;
+    cse?: boolean;
+    cached?: Scalar | null;
+    scalar?: Scalar;
+    rich?: Meta;
+    arrayRef?: string;
+    entityFields?: Meta;
+    spillCache?: boolean;
+}
+export interface Cell {
+    col: number;
+    row: number;
+    content: CellContent | null;
+    patches: Meta[];
+}
+export interface TableModel {
+    name: string;
+    anchor: CellPos;
+    columns: string[];
+    headerRow: boolean;
+    bodyRows: number;
+    total: Meta;
+    style?: Meta;
+    banded: Meta;
+    filter: Meta;
+    sort: Meta[];
+    line: number;
+    sheetName?: string;
+}
+export interface CfBlock {
+    sqref: string;
+    rules: Meta;
+    line: number;
+}
+export interface ValidationBlock {
+    sqref: string;
+    meta: Meta;
+}
+export interface FilterBlock {
+    sqref: string;
+    meta: Meta;
+    line: number;
+}
+export interface NoteModel {
+    col: number;
+    row: number;
+    text: string;
+}
+export interface HyperlinkModel {
+    col: number;
+    row: number;
+    target: string;
+    tip?: Meta;
+}
+export interface ChartModel {
+    type: string | undefined;
+    title: string | null;
+    anchor: string | null;
+    size: {
+        w: number;
+        h: number;
+    } | null;
+    meta: Meta;
+    line: number;
+}
+export interface SparklineModel {
+    sqref: string;
+    meta: Meta;
+    line: number;
+}
+export interface PivotModel {
+    name: string;
+    anchor: string | null;
+    meta: Meta;
+    line: number;
+}
+export interface SlicerModel {
+    anchor: string | null;
+    size: {
+        w: number;
+        h: number;
+    } | null;
+    meta: Meta;
+    kind: string;
+    line: number;
+    _name?: string;
+    _timeline?: boolean;
+}
+export interface ImageModel {
+    anchor: string | null;
+    size: {
+        w: number;
+        h: number;
+    } | null;
+    src: string;
+    alt: Meta;
+    line: number;
+}
+export interface ShapeModel {
+    preset: string;
+    anchor: string | null;
+    size: {
+        w: number;
+        h: number;
+    } | null;
+    meta: Meta;
+    line: number;
+}
+export interface ThreadModel {
+    ref: string;
+    comments: Meta;
+    line: number;
+}
+export interface ScenarioModel {
+    name: string;
+    meta: Meta;
+    line: number;
+}
+export interface OutlineModel {
+    rows: Meta[];
+    cols: Meta[];
+}
+export interface Sheet {
+    name: string;
+    meta: Meta;
+    kind: 'worksheet' | 'chart';
+    cells: Map<string, Cell>;
+    merges: Target[];
+    tables: TableModel[];
+    cf: CfBlock[];
+    validations: ValidationBlock[];
+    notes: NoteModel[];
+    hyperlinks: HyperlinkModel[];
+    outline: OutlineModel;
+    page: Meta;
+    charts: ChartModel[];
+    sparklines: SparklineModel[];
+    pivots: PivotModel[];
+    slicers: SlicerModel[];
+    images: ImageModel[];
+    shapes: ShapeModel[];
+    threads: ThreadModel[];
+    scenarios: ScenarioModel[];
+    filters: FilterBlock[];
+}
+export type ReportAction = 'native' | 'carried' | 'partial' | 'not-emitted';
+export interface ReportEntry {
+    line?: number;
+    feature: string;
+    action: ReportAction;
+    note?: string;
+}
+export interface RawPart {
+    part: string;
+    payload: string | undefined;
+    encoding: string | undefined;
+    line: number;
+}
+export interface CarryEntry {
+    kind: string;
+    line: number;
+    feature?: string;
+    args?: InfoArgs | null;
+    meta?: Meta;
+    code?: string | null;
+    body?: Meta;
+}
+export interface TableIndexEntry extends TableModel {
+    sheetName: string;
+}
+export interface WorkbookModel {
+    fm: Meta;
+    themeColors: Record<string, string>;
+    sheets: Sheet[];
+    report: ReportEntry[];
+    rawParts: RawPart[];
+    carry: CarryEntry[];
+    tableIndex: Map<string, TableIndexEntry>;
+    baseDir: string;
+}

package/dist/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedDocument } from './types';
+export declare function isValidPartPath(p: unknown): boolean;
+export declare function validateDocument(doc: ParsedDocument): ParsedDocument;

package/dist/xlsx/chart.d.ts

@@ -0,0 +1,14 @@
+import type { ChartModel, ReportEntry, TableIndexEntry } from '../types';
+export declare const CLASSIC_TYPES: Set<string>;
+export declare const CHARTEX_TYPES: Set<string>;
+export declare function isClassicChart(type: unknown): boolean;
+export declare function resolveDataRef(ref: unknown, ownSheet: string, tableIndex: Map<string, TableIndexEntry>): string | null;
+interface ChartSpaceOpts {
+    ownSheet: string;
+    tableIndex: Map<string, TableIndexEntry>;
+    themeColors: Record<string, string>;
+    report: ReportEntry[];
+}
+export declare function chartSpaceXml(chart: ChartModel, { ownSheet, tableIndex, themeColors }: ChartSpaceOpts): string;
+export declare function splitTopLevel(text: string): string[];
+export {};

package/dist/xlsx/chartex.d.ts

@@ -0,0 +1,9 @@
+import type { ChartModel } from '../types';
+export declare const CX_NS = "http://schemas.microsoft.com/office/drawing/2014/chartex";
+export declare const isChartExType: (t: unknown) => boolean;
+export interface LiteralResult {
+    f: string;
+    values: (string | number | null)[];
+}
+export type LiteralResolver = (ref: string) => LiteralResult | null;
+export declare function chartExXml(chart: ChartModel, resolveLiterals: LiteralResolver): string | null;

package/dist/xlsx/drawing.d.ts

@@ -0,0 +1,25 @@
+import type { ShapeModel } from '../types';
+export interface AnchorMarker {
+    col: number;
+    row: number;
+}
+export interface Anchor {
+    kind: 'absolute' | 'two' | 'one';
+    x?: number;
+    y?: number;
+    cx?: number;
+    cy?: number;
+    from?: AnchorMarker;
+    to?: AnchorMarker;
+}
+export declare function parseAnchor(anchorStr: string | null, size?: {
+    w: number;
+    h: number;
+} | null): Anchor;
+export declare function chartFrame(id: number, name: string, relId: string, anchor: Anchor): string;
+export declare function pictureFrame(id: number, name: string, relId: string, anchor: Anchor, alt: string | undefined): string;
+export declare function shapeFrame(id: number, shape: ShapeModel, anchor: Anchor, themeColors: Record<string, string>): string;
+export declare function chartExFrame(id: number, name: string, relId: string, anchor: Anchor): string;
+export declare function timesliceFrame(id: number, name: string, anchor: Anchor): string;
+export declare function slicerFrame(id: number, name: string, anchor: Anchor): string;
+export declare function drawingXml(anchors: string[]): string;

package/dist/xlsx/model.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedDocument, WorkbookModel } from '../types';
+export declare function buildWorkbookModel(doc: ParsedDocument, { baseDir }?: {
+    baseDir?: string;
+}): WorkbookModel;
+export declare function translateFormula(formula: string, dr: number, dc: number): string;

package/dist/xlsx/pivot.d.ts

@@ -0,0 +1,16 @@
+import type { PivotModel, Target, TableIndexEntry } from '../types';
+type HeaderFn = (tgt: Target) => string[] | null;
+export interface PivotParts {
+    cacheDef: string;
+    cacheRecords: string;
+    pivotTable: string;
+}
+export interface PivotBuildOpts {
+    pivotId: number;
+    cacheId: number;
+    tableIndex: Map<string, TableIndexEntry>;
+    getHeaderCells: HeaderFn;
+    numFmtId: (code: string) => number;
+}
+export declare function buildPivotParts(pivot: PivotModel, { cacheId, tableIndex, getHeaderCells, numFmtId }: PivotBuildOpts): PivotParts | null;
+export {};

package/dist/xlsx/read-objects.d.ts

@@ -0,0 +1,24 @@
+import type { XmlNode } from '../types';
+export interface AnchorSpec {
+    at: string;
+    size?: {
+        w: number;
+        h: number;
+    };
+}
+export interface DrawingAnchor {
+    kind: string;
+    el: XmlNode;
+}
+export type MediaLookup = (rid: string) => {
+    mime: string;
+    data: Buffer;
+} | null;
+export declare function anchorsOf(drawingDoc: XmlNode | null): DrawingAnchor[];
+export declare function anchorText(anchor: DrawingAnchor): AnchorSpec;
+export declare function reverseChart(chartDoc: XmlNode, anchorSpec: AnchorSpec): string[] | null;
+export declare function reversePicture(pic: XmlNode, anchorSpec: AnchorSpec, mediaLookup: MediaLookup): string[] | null;
+export declare function reverseShape(sp: XmlNode, anchorSpec: AnchorSpec): string[];
+export declare function reversePivot(ptDoc: XmlNode, cacheDoc: XmlNode | null): string[] | null;
+export declare function reverseSlicer(slicerEl: XmlNode, cacheDoc: XmlNode | null, tableNameById: Map<number, string | undefined>, anchorSpec: AnchorSpec | undefined): string[] | null;
+export declare function reverseChartEx(doc: XmlNode, anchorSpec: AnchorSpec): string[] | null;

package/dist/xlsx/read.d.ts

@@ -0,0 +1,6 @@
+import type { ReportEntry } from '../types';
+export interface ImportResult {
+    gmd: string;
+    report: ReportEntry[];
+}
+export declare function xlsxToGridmd(buffer: Buffer): ImportResult;

package/dist/xlsx/styles.d.ts

@@ -0,0 +1,37 @@
+import type { Meta } from '../types';
+export interface BorderEdge {
+    style: string;
+    color: string | null;
+}
+export interface BorderEdges {
+    top: BorderEdge | null;
+    right: BorderEdge | null;
+    bottom: BorderEdge | null;
+    left: BorderEdge | null;
+    diagUp: BorderEdge | null;
+    diagDown: BorderEdge | null;
+}
+export declare function parseBorderEdge(v: Meta, theme: Record<string, string>): BorderEdge | null;
+export declare class StyleRegistry {
+    theme: Record<string, string>;
+    numFmts: Map<string, number>;
+    fonts: string[];
+    fontKeys: Map<string, number>;
+    fills: string[];
+    fillKeys: Map<string, number>;
+    borders: string[];
+    borderKeys: Map<string, number>;
+    xfs: string[];
+    xfKeys: Map<string, number>;
+    dxfs: string[];
+    constructor(themeColors?: Record<string, string>);
+    numFmtId(code: string): number;
+    fontXml(p: Meta): string;
+    fontId(p: Meta): number;
+    fillId(p: Meta): number;
+    borderId(edges: BorderEdges | null): number;
+    alignmentXml(p: Meta): string;
+    xfId(p: Meta, borders: BorderEdges | null): number;
+    dxfId(fmt: Meta): number;
+    toXml(): string;
+}

package/dist/xlsx/units.d.ts

@@ -0,0 +1,8 @@
+export declare function isoToSerial(iso: string, dateSystem?: number): number;
+export declare function pxToColWidth(px: number): number;
+export declare const pxToPt: (px: number) => number;
+export declare const cmToInch: (cm: number) => number;
+export declare const DEFAULT_THEME: Record<string, string>;
+export declare function resolveColor(value: unknown, themeColors?: Record<string, string>): string | null;
+export declare const NUMFMT_ALIASES: Record<string, string>;
+export declare const BUILTIN_NUMFMT_IDS: Map<string, number>;

package/dist/xlsx/write.d.ts

@@ -0,0 +1,7 @@
+import type { ReportEntry, WorkbookModel } from '../types';
+interface WriteResult {
+    buffer: Buffer;
+    report: ReportEntry[];
+}
+export declare function writeXlsx(model: WorkbookModel): WriteResult;
+export {};

package/dist/xlsx/zip.d.ts

@@ -0,0 +1,7 @@
+export declare function crc32(buf: Uint8Array): number;
+export interface ZipEntry {
+    name: string;
+    data: Buffer | string;
+}
+export declare function zipWrite(entries: ZipEntry[]): Buffer;
+export declare function zipRead(buf: Buffer): Map<string, Buffer>;

package/dist/xml.d.ts

@@ -0,0 +1,8 @@
+import type { XmlNode } from './types';
+export declare function decodeEntities(s: string): string;
+export declare function parseXml(src: string): XmlNode;
+export declare function attr(el: XmlNode | null | undefined, name: string): string | undefined;
+export declare const one: (el: XmlNode | null | undefined, name: string) => XmlNode | null;
+export declare const all: (el: XmlNode | null | undefined, name: string) => XmlNode[];
+export declare function textOf(el: XmlNode | null | undefined): string;
+export declare function findDeep(el: XmlNode | null | undefined, name: string): XmlNode | null;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "gridmd",
+  "version": "1.0.0",
+  "description": "GridMD reference parser, linter and two-way XLSX converter (spec: SPEC.md)",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:fledgling-co/gridmd",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gridmd-lint": "dist/bin/gridmd-lint.js",
+    "gridmd2xlsx": "dist/bin/gridmd2xlsx.js",
+    "xlsx2gridmd": "dist/bin/xlsx2gridmd.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint:example": "bun bin/gridmd-lint.ts ../examples/quarterly-report.gmd",
+    "xlsx:example": "bun bin/gridmd2xlsx.ts ../examples/quarterly-report.gmd -o ../examples/quarterly-report.xlsx",
+    "roundtrip:example": "bun bin/gridmd2xlsx.ts ../examples/quarterly-report.gmd -o ../examples/quarterly-report.xlsx && bun bin/xlsx2gridmd.ts ../examples/quarterly-report.xlsx -o ../examples/quarterly-report.roundtrip.gmd && bun bin/gridmd-lint.ts ../examples/quarterly-report.roundtrip.gmd",
+    "dump": "bun bin/gridmd-dump.ts",
+    "prepublishOnly": "bun run typecheck && bun run build && bun test",
+    "typecheck:tsc": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20260704.1",
+    "typescript": "latest"
+  }
+}