@milehimikey/em 1.17.0 → 1.18.0

package/dist/cli/storylineSuggest.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: MIT
+// `em storyline suggest <model>` (GH #290): advisory, read-only. Proposes `storyline` blocks (GH #277)
+// for a model written before they existed and prints them as a unified diff the user applies by
+// hand (`patch -p0`, `git apply`) — it never writes the model.
+//
+// Grouping, in this order, over the slices not already inside a storyline block:
+//  1. one storyline per distinct slice `source "url"` (the slices sharing that URL);
+//  2. the remaining slices by the view-instance chains they feed: a read model with at least one
+//     `view … again` instance links its originating slice, every `again` slice and the slices
+//     declaring the events any instance is built from. A chain that touches exactly one `source`
+//     group joins it; otherwise it becomes a storyline of its own;
+//  3. a slice that fits neither stays outside every storyline (and keeps the advisory
+//     `slice-outside-storyline` warning once any storyline exists).
+// A group whose slices are not adjacent in the file becomes several blocks with the same name — the
+// grammar's "a repeated name continues the storyline" — `source` only on the first.
+import { isAbsolute, relative, resolve, basename, sep } from "node:path";
+import { normalizeName } from "../model/model.js";
+import { encodeQuoted } from "../parser/lexer.js";
+function nameFromUrl(url) {
+    const frag = url.includes("#") ? url.slice(url.indexOf("#") + 1) : "";
+    const last = url.split("#")[0].replace(/\/+$/, "").split("/").pop() ?? "";
+    const raw = (frag || last).replace(/\.[a-z]+$/i, "").replace(/[-_]+/g, " ").trim();
+    if (raw === "")
+        return "Storyline";
+    return /^[a-z]/.test(raw) ? raw[0].toUpperCase() + raw.slice(1) : raw;
+}
+export function suggestStorylines(model) {
+    const n = model.slices.length;
+    const free = (i) => model.slices[i].storyline === undefined;
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (x) => (parent[x] === x ? x : (parent[x] = find(parent[x])));
+    const union = (a, b) => {
+        parent[find(a)] = find(b);
+    };
+    // View-instance chains.
+    for (const origin of model.elements) {
+        if (origin.kind !== "view" || origin.again === true)
+            continue;
+        const instances = model.elements.filter((e) => e.kind === "view" && e.again === true && e.logicalId === origin.id);
+        if (instances.length === 0)
+            continue;
+        for (const inst of [origin, ...instances]) {
+            union(origin.sliceIndex, inst.sliceIndex);
+            for (const evName of inst.from ?? []) {
+                for (const ev of model.byName.get(normalizeName(evName)) ?? [])
+                    if (ev.kind === "event")
+                        union(origin.sliceIndex, ev.sliceIndex);
+            }
+        }
+    }
+    const taken = new Set((model.storylines ?? []).map((s) => s.name.toLowerCase()));
+    const unique = (base) => {
+        let name = base;
+        for (let k = 2; taken.has(name.toLowerCase()); k++)
+            name = `${base} (${k})`;
+        taken.add(name.toLowerCase());
+        return name;
+    };
+    const bySource = new Map();
+    const sourceOf = (i) => model.slices[i].source;
+    const out = [];
+    const sourceName = (url) => {
+        let g = bySource.get(url);
+        if (!g) {
+            g = { name: unique(nameFromUrl(url)), source: url, sliceIndexes: [], basis: "source" };
+            bySource.set(url, g);
+            out.push(g);
+        }
+        return g.name;
+    };
+    // Component -> the distinct sources among its free slices.
+    const componentSources = new Map();
+    for (let i = 0; i < n; i++) {
+        const src = sourceOf(i);
+        if (!free(i) || src === undefined)
+            continue;
+        const set = componentSources.get(find(i)) ?? new Set();
+        set.add(src);
+        componentSources.set(find(i), set);
+    }
+    const groupOf = new Map(); // slice index -> storyline name
+    const chainGroups = new Map();
+    const componentSize = new Map();
+    for (let i = 0; i < n; i++)
+        if (free(i))
+            componentSize.set(find(i), (componentSize.get(find(i)) ?? 0) + 1);
+    for (let i = 0; i < n; i++) {
+        if (!free(i))
+            continue;
+        const src = sourceOf(i);
+        if (src !== undefined) {
+            groupOf.set(i, sourceName(src));
+            continue;
+        }
+        const srcs = componentSources.get(find(i));
+        if (srcs !== undefined && srcs.size === 1) {
+            groupOf.set(i, sourceName([...srcs][0]));
+            continue;
+        }
+        if ((componentSize.get(find(i)) ?? 0) > 1) {
+            let g = chainGroups.get(find(i));
+            if (!g) {
+                g = { name: unique(`${model.slices[i].name} journey`), sliceIndexes: [], basis: "view-chain" };
+                chainGroups.set(find(i), g);
+                out.push(g);
+            }
+            groupOf.set(i, g.name);
+        }
+    }
+    const byName = new Map(out.map((g) => [g.name, g]));
+    for (const [i, name] of [...groupOf].sort((a, b) => a[0] - b[0]))
+        byName.get(name).sliceIndexes.push(i);
+    const ungrouped = [];
+    for (let i = 0; i < n; i++)
+        if (free(i) && !groupOf.has(i))
+            ungrouped.push(i);
+    return { storylines: out.filter((g) => g.sliceIndexes.length > 0), ungrouped };
+}
+/** Index (0-based) of the line holding the `}` that closes the block opened on `start`. */
+export function blockEnd(lines, start) {
+    let depth = 0;
+    let opened = false;
+    for (let i = start; i < lines.length; i++) {
+        let inStr = false;
+        for (let c = 0; c < lines[i].length; c++) {
+            const ch = lines[i][c];
+            if (inStr) {
+                if (ch === "\\")
+                    c++;
+                else if (ch === '"')
+                    inStr = false;
+            }
+            else if (ch === '"')
+                inStr = true;
+            else if (ch === "#")
+                break;
+            else if (ch === "{") {
+                depth++;
+                opened = true;
+            }
+            else if (ch === "}")
+                depth--;
+        }
+        if (opened && depth <= 0)
+            return i;
+    }
+    return lines.length - 1;
+}
+/** The path used in the diff headers: relative to the cwd, no leading `./`, never absolute (`git apply`
+ *  rejects `a/./x.em` and `a//abs/x.em`). A file outside the cwd falls back to its basename. */
+export function diffPath(file) {
+    let rel = isAbsolute(file) || file.startsWith(".") ? relative(process.cwd(), resolve(file)) : file;
+    if (rel.startsWith("..") || isAbsolute(rel))
+        rel = basename(file);
+    return rel.split(sep).join("/").replace(/^(\.\/)+/, "");
+}
+/** Unified diff of `ops` (every original line appears as " " or "-"), 3 lines of context. */
+function unifiedDiff(file, ops) {
+    const CONTEXT = 3;
+    const changed = ops.map((o) => o.t !== " ");
+    const hunks = [];
+    for (let i = 0; i < ops.length; i++) {
+        if (!changed[i])
+            continue;
+        const lo = Math.max(0, i - CONTEXT);
+        const hi = Math.min(ops.length - 1, i + CONTEXT);
+        const last = hunks[hunks.length - 1];
+        if (last && lo <= last[1] + 1)
+            last[1] = hi;
+        else
+            hunks.push([lo, hi]);
+    }
+    const out = [`--- a/${file}`, `+++ b/${file}`];
+    for (const [lo, hi] of hunks) {
+        let oldStart = 1;
+        let newStart = 1;
+        for (let i = 0; i < lo; i++) {
+            if (ops[i].t !== "+")
+                oldStart++;
+            if (ops[i].t !== "-")
+                newStart++;
+        }
+        const slice = ops.slice(lo, hi + 1);
+        const oldLen = slice.filter((o) => o.t !== "+").length;
+        const newLen = slice.filter((o) => o.t !== "-").length;
+        out.push(`@@ -${oldLen === 0 ? oldStart - 1 : oldStart},${oldLen} +${newLen === 0 ? newStart - 1 : newStart},${newLen} @@`);
+        for (const o of slice)
+            out.push(o.t + o.text);
+    }
+    return out.join("\n") + "\n";
+}
+/** `model` compiled from `text` (the file named `file` in the diff headers). */
+export function buildStorylineSuggestion(model, text, file) {
+    const { storylines, ungrouped } = suggestStorylines(model);
+    if (storylines.length === 0)
+        return { storylines, ungrouped, patch: "" };
+    const crlf = text.includes("\r\n");
+    const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
+    const trailingNewline = lines[lines.length - 1] === "";
+    if (trailingNewline)
+        lines.pop();
+    // A run may only span slices with nothing but blank lines and `#` comments between them: any other
+    // top-level line (a `persona`, a `context`...) is not legal inside a storyline block, so it splits
+    // the run into two same-name blocks.
+    const gapIsClean = (a, b) => {
+        const from = blockEnd(lines, model.slices[a].line - 1) + 1;
+        for (let i = from; i < model.slices[b].line - 1; i++) {
+            const t = lines[i].trim();
+            if (t !== "" && !t.startsWith("#"))
+                return false;
+        }
+        return true;
+    };
+    // Contiguous runs (by slice index) per storyline.
+    const runs = [];
+    for (const story of storylines) {
+        let k = 0;
+        while (k < story.sliceIndexes.length) {
+            let j = k;
+            while (j + 1 < story.sliceIndexes.length &&
+                story.sliceIndexes[j + 1] === story.sliceIndexes[j] + 1 &&
+                gapIsClean(story.sliceIndexes[j], story.sliceIndexes[j + 1]))
+                j++;
+            runs.push({ story, first: story.sliceIndexes[k], last: story.sliceIndexes[j], continues: k > 0 });
+            k = j + 1;
+        }
+    }
+    runs.sort((a, b) => a.first - b.first);
+    const quote = (s) => `"${encodeQuoted(s)}"`;
+    const ops = [];
+    let cursor = 0;
+    for (const run of runs) {
+        const start = model.slices[run.first].line - 1;
+        const end = blockEnd(lines, model.slices[run.last].line - 1);
+        for (; cursor < start; cursor++)
+            ops.push({ t: " ", text: lines[cursor] });
+        ops.push({ t: "+", text: `storyline ${quote(run.story.name)}${!run.continues && run.story.source !== undefined ? ` source ${quote(run.story.source)}` : ""} {` });
+        for (let i = start; i <= end; i++)
+            ops.push({ t: "-", text: lines[i] });
+        for (let i = start; i <= end; i++)
+            ops.push({ t: "+", text: lines[i].trim() === "" ? lines[i] : `  ${lines[i]}` });
+        ops.push({ t: "+", text: "}" });
+        cursor = end + 1;
+    }
+    for (; cursor < lines.length; cursor++)
+        ops.push({ t: " ", text: lines[cursor] });
+    let patch = unifiedDiff(diffPath(file), ops);
+    if (crlf)
+        patch = patch.replace(/\n/g, "\r\n");
+    return { storylines, ungrouped, patch };
+}
+//# sourceMappingURL=storylineSuggest.js.map

package/dist/cli/storylineSuggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storylineSuggest.js","sourceRoot":"","sources":["../../src/cli/storylineSuggest.ts"],"names":[],"mappings":"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"}

package/dist/cli/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { GRANDFATHERED_RATIFIER } from "../roster/roster.js";
 import { NormalizedModel } from "../model/model.js";
 import { RefsResult } from "../model/refs.js";
 import { GitRunner } from "./diff-inputs.js";
@@ -13,6 +14,10 @@ export interface UpgradeContext {
     packagedAgentsRoot?: string;
     model: NormalizedModel;
     refs: RefsResult;
+    /** `--fold-continuations`: apply the opt-in `fold-continuations` step (default form: stack). */
+    foldContinuations?: boolean;
+    /** `--to-sugar` (implies `--fold-continuations`): fold into the host command slice instead. */
+    toSugar?: boolean;
 }
 export interface StepDetection {
     applicable: boolean;
@@ -25,11 +30,12 @@ export interface StepDetection {
 export type StepApplyOutcome = {
     ok: true;
     changedFiles: string[];
+    notes?: string[];
 } | {
     ok: false;
     message: string;
 };
-export type UpgradeStepId = "skill-bundle" | "skill-plugin" | "reaction-shape" | "state-file" | "ci-block" | "constitution" | "ratified-signoff" | "ratified-hash-scope" | "system-manifest";
+export type UpgradeStepId = "skill-bundle" | "skill-plugin" | "reaction-shape" | "state-file" | "ci-block" | "constitution" | "ratified-signoff" | "ratified-hash-scope" | "collapse-alternative-events" | "fold-continuations" | "view-doc-sources-stale" | "slice-index-stale" | "parking-lot-fragments" | "system-manifest";
 export interface UpgradeStepDef {
     id: UpgradeStepId;
     /** The em release that introduced the feature this step brings a repo up to date with —
@@ -38,19 +44,21 @@ export interface UpgradeStepDef {
     sinceVersion: string;
     detect(ctx: UpgradeContext): StepDetection;
     apply(ctx: UpgradeContext): StepApplyOutcome;
+    /** Opt-in steps are detected and listed by every run but applied only when this returns true. */
+    optedIn?(ctx: UpgradeContext): boolean;
 }
 /** MIL-257: the one human-readable sentence for "the state file exists but `parseState` rejected
  *  it", naming the file so the `--check` final line / `--apply` refusal is self-explanatory.
  *  `parseState`'s "missing bullet line(s): ..." reads as `is missing ...`; its format-mismatch
  *  messages (`"- **X:**" doesn't match ...`) follow a colon instead. */
 export declare function describeStateFileFailure(path: string, parseMessage: string): string;
-export declare const GRANDFATHERED_RATIFIER = "grandfathered (unsigned before em 1.14)";
+export { GRANDFATHERED_RATIFIER };
 /** Pure text transform: inserts the grandfather sign-off after the `status:` line, using only
  *  the key lines that are missing (a stray `ratifiedOn:` is kept as-is), in the file's own EOL.
  *  `null` when the doc isn't a candidate (no frontmatter/status, or `ratifiedBy` already set). */
 export declare function applyGrandfatherSignoff(raw: string, ratifiedOn: string): string | null;
 export declare const UPGRADE_STEPS: readonly UpgradeStepDef[];
-export type HumanItemId = "no-model-version" | "continuation-has-own-doc" | "ready-to-implement-no-ratifiedby" | "coverage-scope-default" | "unratified-constitution" | "predates-1.6" | "public-field-types-unresolved" | "plugin-install-locally";
+export type HumanItemId = "no-model-version" | "continuation-has-own-doc" | "ready-to-implement-no-ratifiedby" | "coverage-scope-default" | "unratified-constitution" | "predates-1.6" | "public-field-types-unresolved" | "plugin-install-locally" | "slice-doc-stale-signed" | "lineage-backlink-missing" | "fold-continuations-opt-in" | "shared-event-now-legal" | "roster-not-initialised";
 export interface HumanItem {
     id: HumanItemId;
     reason: string;
@@ -92,6 +100,8 @@ export interface StepReport {
     applicable: boolean;
     human: boolean;
     reason: string;
+    /** Present (true) for an opt-in step that is detected but not opted into by this run's flags: listed, never applied. */
+    optIn?: boolean;
 }
 export interface UpgradeReport {
     from: FromVersion;
@@ -108,6 +118,8 @@ export interface ApplyStepResult {
     applied: boolean;
     changedFiles: string[];
     commit: string | null;
+    /** What a human must still do for this step (e.g. content of a retired doc to carry over). */
+    notes?: string[];
 }
 export type ApplyUpgradeResult = {
     ok: true;