jg-plans 0.1.2 → 0.2.0

package/dist/documents/milestones.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { planErrors } from "../errors/index.js";
-import { diagnostic, sourceLines, sourceLocation } from "./utilities.js";
+import { diagnostic, headingSections, readFrontmatter, sourceLocation } from "./utilities.js";
 const markerFrom = (line, prefix) => {
     const leading = line.text.length - line.text.trimStart().length;
     if (!line.text.slice(leading).startsWith(prefix))
@@ -22,48 +22,51 @@ const cells = (line) => line
     .replace(/^\||\|$/g, '')
     .split('|')
     .map((cell) => cell.trim());
-const readOverview = (lines) => {
+const readOverview = (lines, sections) => {
     const rows = [];
+    const tables = [];
     let present = false;
     let inOverview = false;
-    let inTable = false;
+    const headings = new Map(sections.map((section) => [section.heading.start, section.title]));
     for (let index = 0; index < lines.length; index++) {
         const line = lines[index];
         if (line.fenced)
             continue;
-        const text = line.start === 0 ? line.text.replace(/^\uFEFF/, '') : line.text;
-        if (/^ {0,3}##[ \t]+/.test(text)) {
-            inOverview = /^ {0,3}## Overview[ \t]*$/.test(text);
-            inTable = false;
-        }
+        const start = line.start + (line.start === 0 && line.text.startsWith('\uFEFF') ? 1 : 0);
+        if (headings.has(start))
+            inOverview = headings.get(start) === 'Overview';
         if (!inOverview)
             continue;
         const columns = cells(line.text);
         if (columns.join('|') === 'Milestone|Name|Status') {
             const separator = cells(lines[index + 1]?.text ?? '');
-            inTable = separator.length === 3 && separator.every((cell) => /^:?-{3,}:?$/.test(cell));
-            if (inTable) {
+            if (!lines[index + 1]?.fenced &&
+                separator.length === 3 &&
+                separator.every((cell) => /^:?-{3,}:?$/.test(cell))) {
                 present = true;
-                index++;
+                const start = line.start;
+                let end = lines[++index].fullEnd;
+                while (index + 1 < lines.length) {
+                    const row = lines[index + 1];
+                    const values = cells(row.text);
+                    if (row.fenced || values.length !== 3 || !/^\d+$/.test(values[0]))
+                        break;
+                    index++;
+                    end = row.fullEnd;
+                    const ordinal = Number(values[0]);
+                    rows.push({
+                        ordinal: Number.isSafeInteger(ordinal) && ordinal > 0 ? ordinal : null,
+                        ordinalText: values[0],
+                        name: values[1],
+                        status: values[2],
+                        location: { offset: row.start, line: row.number, column: 1 },
+                    });
+                }
+                tables.push({ start, end });
             }
-            continue;
-        }
-        if (!inTable)
-            continue;
-        if (columns.length !== 3 || !/^\d+$/.test(columns[0])) {
-            inTable = false;
-            continue;
         }
-        const ordinal = Number(columns[0]);
-        rows.push({
-            ordinal: Number.isSafeInteger(ordinal) && ordinal > 0 ? ordinal : null,
-            ordinalText: columns[0],
-            name: columns[1],
-            status: columns[2],
-            location: { offset: line.start, line: line.number, column: 1 },
-        });
     }
-    return { present, rows };
+    return { present, rows, tables };
 };
 /**
  * Observe numbered milestones and their markers, ignoring fenced examples.
@@ -76,23 +79,30 @@ const readOverview = (lines) => {
 export const parseMilestones = (source) => {
     if (!z.string().safeParse(source).success)
         throw planErrors.create('invalidInput');
-    const lines = sourceLines(source);
-    const overview = readOverview(lines);
+    const observed = readFrontmatter(source, 'milestones');
+    const { lines } = observed;
+    const sections = headingSections(source, lines);
+    const overview = readOverview(lines, sections);
     const result = {
         source,
+        body: observed.body,
+        frontmatter: observed.frontmatter,
+        rawMetadata: observed.rawMetadata,
+        preamble: { start: 0, end: sections[0]?.heading.start ?? source.length },
+        sections,
+        overviewTables: overview.tables,
         milestones: [],
         overview: overview.rows,
         overviewPresent: overview.present,
-        diagnostics: [],
+        diagnostics: observed.diagnostics,
     };
-    const headings = lines.filter((line) => !line.fenced &&
-        /^ {0,3}##[ \t]+/.test(line.start === 0 ? line.text.replace(/^\uFEFF/, '') : line.text));
+    const headings = sections.map((section) => lines[sourceLocation(lines, section.heading.start).line - 1]);
     const ordinals = new Set();
     const ids = new Set();
     let previous = 0;
     for (let index = 0; index < headings.length; index++) {
         const heading = headings[index];
-        const match = /^ {0,3}##[ \t]+Milestone (-?\d+):[ \t]*(.*?)(?:[ \t]+#+)?[ \t]*$/.exec(heading.text.replace(/^\uFEFF/, ''));
+        const match = /^Milestone (-?\d+):[ \t]*(.*)$/s.exec(sections[index].title);
         if (!match)
             continue;
         const end = headings[index + 1]?.start ?? source.length;
@@ -114,6 +124,7 @@ export const parseMilestones = (source) => {
             status: statuses[0]?.value ?? null,
             id: identities[0]?.value ?? null,
             location,
+            headingEnd: heading.fullEnd,
             end,
             body: source.slice(heading.fullEnd, end),
             statusMarkers: statuses,

package/dist/documents/plan.js

@@ -1,8 +1,8 @@
-import { isMap, isNode, isScalar, parseDocument } from 'yaml';
+import { isMap, isNode, isScalar } from 'yaml';
 import { z } from 'zod';
 import { planErrors } from "../errors/index.js";
 import { PlanMetadataSchema } from "../protocol/index.js";
-import { diagnostic, sourceLines, sourceLocation } from "./utilities.js";
+import { diagnostic, headingSections, readFrontmatter, sourceLocation } from "./utilities.js";
 /**
  * Observe a plan without requiring valid metadata. Source and body remain unchanged.
  * Unsupported YAML expansion retains source and a diagnostic, not a fabricated value.
@@ -14,80 +14,45 @@ import { diagnostic, sourceLines, sourceLocation } from "./utilities.js";
 export const parsePlan = (source) => {
     if (!z.string().safeParse(source).success)
         throw planErrors.create('invalidInput');
+    const observed = readFrontmatter(source, 'plan');
+    const sections = headingSections(source, observed.lines);
     const result = {
         source,
-        body: source,
-        frontmatter: null,
-        rawMetadata: null,
+        body: observed.body,
+        frontmatter: observed.frontmatter,
+        rawMetadata: observed.rawMetadata,
         metadata: {},
-        diagnostics: [],
+        preamble: { start: 0, end: sections[0]?.heading.start ?? source.length },
+        sections,
+        diagnostics: observed.diagnostics,
     };
-    const lines = sourceLines(source);
-    const first = lines[0];
-    const bom = source.startsWith('\uFEFF') ? 1 : 0;
-    if (!first || !/^---[ \t]*$/.test(first.text.slice(bom))) {
+    const { yaml: document, frontmatter, lines } = observed;
+    if (!frontmatter)
         result.diagnostics.push(diagnostic('plan', 'MISSING_FRONTMATTER', 'Preferred plan metadata is absent.'));
-    }
-    else {
-        const closing = lines.slice(1).find((line) => /^---[ \t]*$/.test(line.text));
-        result.frontmatter = {
-            start: bom,
-            contentStart: first.fullEnd,
-            contentEnd: closing?.start ?? source.length,
-            end: closing?.fullEnd ?? source.length,
-            closed: Boolean(closing),
-        };
-        if (!closing)
-            result.diagnostics.push(diagnostic('plan', 'UNTERMINATED_FRONTMATTER', 'The opening frontmatter has no closing delimiter.', sourceLocation(lines, bom)));
-        else
-            result.body = source.slice(closing.fullEnd);
-        const yamlSource = source.slice(first.fullEnd, closing?.start ?? source.length);
-        const document = parseDocument(yamlSource, { keepSourceTokens: true, logLevel: 'silent' });
-        for (const issue of document.errors)
-            result.diagnostics.push(diagnostic('plan', 'INVALID_YAML', `YAML could not be fully parsed (${issue.code}).`, sourceLocation(lines, first.fullEnd + issue.pos[0])));
-        for (const issue of document.warnings)
-            result.diagnostics.push(diagnostic('plan', 'YAML_WARNING', `YAML reader warning (${issue.code}).`, sourceLocation(lines, first.fullEnd + issue.pos[0]), 'warning'));
-        try {
-            const raw = document.toJS({ maxAliasCount: 100 });
-            // JSON automation cannot represent recursive aliases, BigInt or nonfinite numbers.
-            // Keep their original YAML and report unavailable expansion instead of changing values.
-            JSON.stringify(raw, (_key, value) => {
-                if (typeof value === 'number' &&
-                    (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))
-                    throw planErrors.create('invalidInput');
-                return value;
-            });
-            result.rawMetadata = raw;
-        }
-        catch {
-            result.diagnostics.push(diagnostic('plan', 'YAML_VALUE_UNAVAILABLE', 'Some YAML values cannot be expanded into JSON-safe observations; the original source is retained.', sourceLocation(lines, first.fullEnd), 'warning'));
-        }
-        if (!isMap(document.contents)) {
-            result.diagnostics.push(diagnostic('plan', 'METADATA_NOT_MAPPING', 'Preferred frontmatter is a mapping of metadata fields.', sourceLocation(lines, first.fullEnd)));
-        }
-        else {
-            for (const key of Object.keys(PlanMetadataSchema.shape)) {
-                const node = document.get(key, true);
-                if (node === undefined)
-                    continue;
-                const raw = result.rawMetadata;
-                const value = raw !== null && typeof raw === 'object' && Object.hasOwn(raw, key)
-                    ? Reflect.get(raw, key)
-                    : isScalar(node)
-                        ? node.value
-                        : node;
-                const parsed = PlanMetadataSchema.shape[key].safeParse(value);
-                if (parsed.success)
-                    Object.assign(result.metadata, { [key]: parsed.data });
-                else
-                    result.diagnostics.push(diagnostic('plan', 'INVALID_METADATA_FIELD', `Metadata field '${key}' has an incompatible value.`, sourceLocation(lines, first.fullEnd + (isNode(node) ? (node.range?.[0] ?? 0) : 0))));
-            }
+    if (document && frontmatter && isMap(document.contents)) {
+        for (const key of Object.keys(PlanMetadataSchema.shape)) {
+            const node = document.get(key, true);
+            if (node === undefined)
+                continue;
+            const raw = result.rawMetadata;
+            const value = raw !== null && typeof raw === 'object' && Object.hasOwn(raw, key)
+                ? Reflect.get(raw, key)
+                : isScalar(node)
+                    ? node.value
+                    : node;
+            const parsed = PlanMetadataSchema.shape[key].safeParse(value);
+            if (parsed.success)
+                Object.assign(result.metadata, { [key]: parsed.data });
+            else
+                result.diagnostics.push(diagnostic('plan', 'INVALID_METADATA_FIELD', `Metadata field '${key}' has an incompatible value.`, sourceLocation(lines, frontmatter.contentStart + (isNode(node) ? (node.range?.[0] ?? 0) : 0))));
         }
     }
+    const invalid = new Set(result.diagnostics
+        .filter((item) => item.code === 'INVALID_METADATA_FIELD')
+        .map((item) => item.message));
     for (const key of Object.keys(PlanMetadataSchema.shape)) {
-        const isObserved = result.diagnostics.some((item) => item.code === 'INVALID_METADATA_FIELD' &&
-            item.message.startsWith(`Metadata field '${key}'`));
-        if (!(key in result.metadata) && !isObserved)
+        if (!(key in result.metadata) &&
+            !invalid.has(`Metadata field '${key}' has an incompatible value.`))
             result.diagnostics.push(diagnostic('plan', 'MISSING_METADATA_FIELD', `Preferred metadata field '${key}' is absent.`));
     }
     return result;

package/dist/documents/types.d.ts

@@ -1,4 +1,15 @@
 import type { IDiagnostic, IPlanMetadata, ISourceLocation } from '../protocol/index.ts';
+/** Original-source UTF-16 offsets, with an exclusive end. */
+export type ISourceSpan = {
+    start: number;
+    end: number;
+};
+/** One unfenced level-two heading and all text up to the next such heading. */
+export type IHeadingSection = {
+    title: string;
+    heading: ISourceSpan;
+    body: ISourceSpan;
+};
 /** Read models retain original text and partial observations; diagnostics carry ambiguity. */
 export type IFrontmatter = {
     start: number;
@@ -13,6 +24,8 @@ export type IParsedPlan = {
     frontmatter: IFrontmatter | null;
     rawMetadata: unknown;
     metadata: Partial<IPlanMetadata>;
+    preamble: ISourceSpan;
+    sections: IHeadingSection[];
     diagnostics: IDiagnostic[];
 };
 export type IMarker = {
@@ -30,6 +43,7 @@ export type IMilestone = {
     status: string | null;
     id: string | null;
     location: ISourceLocation;
+    headingEnd: number;
     end: number;
     body: string;
     statusMarkers: IMarker[];
@@ -44,6 +58,12 @@ export type IOverviewRow = {
 };
 export type IParsedMilestones = {
     source: string;
+    body: string;
+    frontmatter: IFrontmatter | null;
+    rawMetadata: unknown;
+    preamble: ISourceSpan;
+    sections: IHeadingSection[];
+    overviewTables: ISourceSpan[];
     milestones: IMilestone[];
     overview: IOverviewRow[];
     overviewPresent: boolean;
@@ -53,6 +73,8 @@ export type ICheckResult = {
     conforms: boolean;
     diagnostics: IDiagnostic[];
 };
+/** A structural observation; consumers decide exclusions and authorization policy. */
+export type { IPlanFingerprint } from '../protocol/index.ts';
 export type ISourceLine = {
     text: string;
     start: number;

package/dist/documents/utilities.d.ts

@@ -1,7 +1,21 @@
+import { parseDocument } from 'yaml';
 import type { IDiagnostic, ISourceLocation } from '../protocol/index.ts';
-import type { ISourceLine } from './types.ts';
+import type { IFrontmatter, IHeadingSection, ISourceLine } from './types.ts';
 /** Preserve original offsets and line endings. Fence recognition derives from public jg-agent-hq. */
-export declare const sourceLines: (source: string) => ISourceLine[];
+export declare const sourceLines: (source: string, frontmatterEnd?: number) => ISourceLine[];
 /** Binary lookup avoids rescanning the source for each diagnostic. */
 export declare const sourceLocation: (lines: ISourceLine[], offset: number) => ISourceLocation;
 export declare const diagnostic: (document: IDiagnostic["document"], code: string, message: string, location?: ISourceLocation, severity?: IDiagnostic["severity"]) => IDiagnostic;
+type IFrontmatterRead = {
+    body: string;
+    frontmatter: IFrontmatter | null;
+    rawMetadata: unknown;
+    yaml: ReturnType<typeof parseDocument> | null;
+    lines: ISourceLine[];
+    diagnostics: IDiagnostic[];
+};
+/** Shared framing/YAML reader; preferred plan fields are validated by the plan parser alone. */
+export declare const readFrontmatter: (source: string, name: IDiagnostic["document"]) => IFrontmatterRead;
+/** Complete, ordered section spans; the prefix before the first heading is the preamble. */
+export declare const headingSections: (source: string, lines: ISourceLine[]) => IHeadingSection[];
+export {};

package/dist/documents/utilities.js

@@ -1,21 +1,27 @@
+import { stringifyJsonDeterministically } from 'jg-utilities';
+import { isMap, isScalar, parseDocument, visit } from 'yaml';
+import { planErrors } from "../errors/index.js";
 /** Preserve original offsets and line endings. Fence recognition derives from public jg-agent-hq. */
-export const sourceLines = (source) => {
+export const sourceLines = (source, frontmatterEnd = 0) => {
     const lines = [];
     let fence = null;
     for (const match of source.matchAll(/([^\r\n]*)(\r\n|\n|\r|$)/g)) {
         if (!match[0])
             continue;
         const text = match[1];
-        const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(match.index === 0 ? text.replace(/^\uFEFF/, '') : text);
+        const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/s.exec(match.index === 0 ? text.replace(/^\uFEFF/, '') : text);
         const line = {
             text,
             start: match.index,
             end: match.index + text.length,
             fullEnd: match.index + match[0].length,
             number: lines.length + 1,
-            fenced: fence !== null,
+            fenced: match.index < frontmatterEnd || fence !== null,
         };
-        if (fence) {
+        if (match.index < frontmatterEnd) {
+            // YAML text never opens a Markdown fence that could hide later body sections.
+        }
+        else if (fence) {
             if (marker &&
                 marker[1][0] === fence.character &&
                 marker[1].length >= fence.length &&
@@ -51,3 +57,98 @@ export const diagnostic = (document, code, message, location, severity = 'error'
     severity,
     ...(location ? { location } : {}),
 });
+/** Shared framing/YAML reader; preferred plan fields are validated by the plan parser alone. */
+export const readFrontmatter = (source, name) => {
+    const lines = sourceLines(source);
+    const result = {
+        body: source,
+        frontmatter: null,
+        rawMetadata: null,
+        yaml: null,
+        lines,
+        diagnostics: [],
+    };
+    const first = lines[0];
+    const bom = source.startsWith('\uFEFF') ? 1 : 0;
+    if (!first || !/^---[ \t]*$/.test(first.text.slice(bom)))
+        return result;
+    const closing = lines.slice(1).find((line) => /^---[ \t]*$/.test(line.text));
+    result.frontmatter = {
+        start: bom,
+        contentStart: first.fullEnd,
+        contentEnd: closing?.start ?? source.length,
+        end: closing?.fullEnd ?? source.length,
+        closed: Boolean(closing),
+    };
+    result.lines = sourceLines(source, result.frontmatter.end);
+    if (closing)
+        result.body = source.slice(closing.fullEnd);
+    else
+        result.diagnostics.push(diagnostic(name, 'UNTERMINATED_FRONTMATTER', 'The opening frontmatter has no closing delimiter.', sourceLocation(lines, bom)));
+    const document = parseDocument(source.slice(first.fullEnd, closing?.start ?? source.length), {
+        keepSourceTokens: true,
+        logLevel: 'silent',
+    });
+    result.yaml = document;
+    for (const issue of document.errors)
+        result.diagnostics.push(diagnostic(name, 'INVALID_YAML', `YAML could not be fully parsed (${issue.code}).`, sourceLocation(lines, first.fullEnd + issue.pos[0])));
+    for (const issue of document.warnings)
+        result.diagnostics.push(diagnostic(name, 'YAML_WARNING', `YAML reader warning (${issue.code}).`, sourceLocation(lines, first.fullEnd + issue.pos[0]), 'warning'));
+    try {
+        // YAML coerces non-string mapping keys during toJS; that would lose structural identity.
+        visit(document, {
+            Pair(_key, pair) {
+                if (!isScalar(pair.key) || typeof pair.key.value !== 'string')
+                    throw planErrors.create('invalidInput');
+            },
+        });
+        const raw = document.toJS({ maxAliasCount: 100 });
+        JSON.stringify(raw, (_key, value) => {
+            if (typeof value === 'number' &&
+                (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))
+                throw planErrors.create('invalidInput');
+            return value;
+        });
+        // Wrapping permits observable scalar/array YAML while rejecting lossy JSON expansion.
+        stringifyJsonDeterministically({ metadata: raw }, { strict: true });
+        result.rawMetadata = raw;
+    }
+    catch {
+        result.diagnostics.push(diagnostic(name, 'YAML_VALUE_UNAVAILABLE', 'Some YAML values cannot be expanded into JSON-safe observations; the original source is retained.', sourceLocation(lines, first.fullEnd), 'warning'));
+    }
+    if (!isMap(document.contents))
+        result.diagnostics.push(diagnostic(name, 'METADATA_NOT_MAPPING', 'Preferred frontmatter is a mapping of metadata fields.', sourceLocation(lines, first.fullEnd)));
+    return result;
+};
+/** Complete, ordered section spans; the prefix before the first heading is the preamble. */
+export const headingSections = (source, lines) => {
+    const headings = lines.flatMap((line) => {
+        if (line.fenced)
+            return [];
+        const bom = line.start === 0 && line.text.startsWith('\uFEFF') ? 1 : 0;
+        const text = line.text.slice(bom);
+        const prefix = /^ {0,3}##[ \t]+/.exec(text);
+        if (!prefix)
+            return [];
+        // Linear scans avoid backtracking over long whitespace runs before a nonclosing suffix.
+        const start = prefix[0].length;
+        let end = text.length;
+        while (end > start && (text[end - 1] === ' ' || text[end - 1] === '\t'))
+            end--;
+        let hashes = end;
+        while (hashes > start && text[hashes - 1] === '#')
+            hashes--;
+        if (hashes < end &&
+            (hashes === start || text[hashes - 1] === ' ' || text[hashes - 1] === '\t')) {
+            end = hashes;
+            while (end > start && (text[end - 1] === ' ' || text[end - 1] === '\t'))
+                end--;
+        }
+        return [{ line, bom, title: text.slice(start, end) }];
+    });
+    return headings.map(({ line, bom, title }, index) => ({
+        title,
+        heading: { start: line.start + bom, end: line.fullEnd },
+        body: { start: line.fullEnd, end: headings[index + 1]?.line.start ?? source.length },
+    }));
+};

package/dist/edits/index.d.ts

@@ -1 +1,3 @@
 export { applyEdits, decodeSource, encodeSource, milestoneEdits, planEdits } from './utilities.ts';
+export { preparePlanUpdate, preparePlanDocumentWrite } from './preparations.ts';
+export type { IPreparedPlanEdit, IAssignedMilestoneId } from './types.ts';

package/dist/edits/index.js

@@ -1,2 +1,3 @@
-// Package-private editing primitives. Public consumers use createPlan/updatePlan.
+// Byte-editing primitives stay package-private; consumers can prepare edits without filesystem I/O.
 export { applyEdits, decodeSource, encodeSource, milestoneEdits, planEdits } from "./utilities.js";
+export { preparePlanUpdate, preparePlanDocumentWrite } from "./preparations.js";

package/dist/edits/preparations.d.ts

@@ -0,0 +1,30 @@
+import { type IPlanDocumentWrite, type IPlanUpdate } from '../protocol/index.ts';
+import type { IPreparedPlanEdit } from './types.ts';
+/** Package-private expectation guard, also used on original read bytes by filesystem adapters. */
+export declare const assertSourceExpectation: (source: string | Uint8Array | null, expected: string | null | undefined) => void;
+/**
+ * Prepare one guarded metadata/marker patch entirely in memory, without policy updates or I/O.
+ * @param source Original selected document text.
+ * @param patch Explicit narrow patch and optional observed exact-byte SHA-256.
+ * @returns Prepared source, digest, diagnostics, and whether bytes would change.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ */
+export declare const preparePlanUpdate: (source: string, patch: IPlanUpdate) => IPreparedPlanEdit;
+/**
+ * Prepare guarded body/metadata replacement or explicit milestone source/ID assignment in memory.
+ * A null source is accepted only for explicit absent milestone creation. No timestamps, revisions,
+ * identities, or completion are inferred; missing IDs are assigned only when requested.
+ * @param source Original selected document text, or null for absent milestones.
+ * @param input Explicit document replacement and required source expectation.
+ * @returns The exact source to persist once, its digest, diagnostics, and generated IDs.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
+ * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
+ * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
+ */
+export declare const preparePlanDocumentWrite: (source: string | null, input: IPlanDocumentWrite) => IPreparedPlanEdit;