light-plan 0.0.0-stage → 0.1.0

package/dist/remote/mapping.js

@@ -0,0 +1,336 @@
+/**
+ * Board vocabulary ↔ remote vocabulary: the type mapping (LP-268).
+ *
+ * One slice of the mapping engine (LP-254): how a board's issue types become a
+ * remote's issue types — or labels, where the provider has no native types —
+ * and back again.  The mapping is data: `mapping.types` in the remote's config
+ * block, a map from a board type name to its remote representation.  This
+ * module only applies it.
+ *
+ * Depth is never declared here.  `hierarchy` is the single source of parenting
+ * truth locally; every function takes the issue hierarchy (what
+ * `hierarchyFor(config, 'issue')` returns) and derives depth from it exactly as
+ * `typesAtDepth` does — a type is legal at the depth where the hierarchy lists
+ * it.  A second depth declaration in the remote config is the bug this
+ * arrangement exists to prevent.
+ *
+ * Pure: no disk, no network.  Everything takes its inputs and returns a value,
+ * so the mapping is testable against literals.  The sibling mappings are the
+ * same shape — declarative, driven by config, applied here: status (below),
+ * attribute in `attributes.ts` (LP-270), resource in `accounts.ts` (LP-271),
+ * then period (LP-272).
+ */
+/**
+ * Normalize one `mapping.types` value to the object form.  Accepts the bare
+ * string (`user_story: Story`) and the object form, and returns `undefined`
+ * when the value names nothing.
+ *
+ * Two **superseded** spellings are folded rather than refused, so a board
+ * written against an older shape keeps working and means what it meant:
+ * `{ type: Story, labels: [story] }` (the two carriers, before the provider
+ * was left to choose) and a list (`[Story, "User Story"]`, before types were
+ * one-to-one).  Where a fold has to choose, the native `type` wins over a
+ * label and the first entry wins over the rest — the value that was actually
+ * being written before.
+ */
+export function normalizeTypeMapping(value) {
+    const remote = remoteNameOf(value);
+    return remote === undefined ? undefined : { remote };
+}
+/** The single remote name a raw `mapping.types` value carries. */
+function remoteNameOf(value) {
+    const first = (input) => {
+        if (typeof input === 'string' && input.length > 0)
+            return input;
+        if (Array.isArray(input)) {
+            return input.find((entry) => typeof entry === 'string' && entry.length > 0);
+        }
+        return undefined;
+    };
+    if (typeof value === 'string' || Array.isArray(value))
+        return first(value);
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    // `remote` first, then the superseded keys in the order that preserves what
+    // the older shape actually wrote: the native type, then its label.
+    return first(raw.remote) ?? first(raw.type) ?? first(raw.labels);
+}
+/**
+ * Normalize the whole `mapping.types` block, dropping entries that name no
+ * remote type.  The provider schema rejects malformed values before this runs;
+ * this is the pure spelling of the same rule for callers that read a mapping
+ * without a schema in hand.
+ */
+export function normalizeTypeMappings(raw) {
+    const out = {};
+    for (const [type, value] of Object.entries(raw)) {
+        const entry = normalizeTypeMapping(value);
+        if (entry)
+            out[type] = entry;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Push: board type → the remote representation written
+// ---------------------------------------------------------------------------
+/**
+ * The remote name a push writes for a board type.  Returns `undefined` when
+ * the type has no usable mapping; a default remote type must never be
+ * invented, because filing everything as "Task" is precisely the silent data
+ * loss this refuses.
+ */
+export function mapTypeToRemote(mappings, boardType) {
+    return remoteNameFor(mappings[boardType]);
+}
+/**
+ * One entry's remote name, read defensively.  The provider schema normalizes
+ * every declaration before the engine sees it, so this is always a non-empty
+ * string in practice — but a hand-built mapping that skipped the schema (an
+ * older shape, a test literal) should read as *unmapped* rather than crash the
+ * push that would have reported it.
+ */
+function remoteNameFor(entry) {
+    const remote = entry?.remote;
+    if (typeof remote === 'string' && remote.length > 0)
+        return remote;
+    // Tolerate an unnormalized value the same way `normalizeTypeMapping` would.
+    return remote === undefined ? undefined : remoteNameOf(remote);
+}
+/** Every remote name any mapped type claims, in declaration order. */
+export function claimedTypeValues(mappings) {
+    return Object.values(mappings)
+        .map((entry) => remoteNameFor(entry))
+        .filter((name) => name !== undefined);
+}
+/**
+ * Board types (in hierarchy order) with no usable mapping — the list a
+ * preflight reports when it refuses to open the remote.  A mapping entry that
+ * names no remote type counts as missing.
+ */
+export function missingTypeMappings(mappings, hierarchy) {
+    const declared = hierarchy.flat();
+    return declared.filter((type) => mapTypeToRemote(mappings, type) === undefined);
+}
+/**
+ * Resolve a remote issue's type back to a board type.  When the observation
+ * matches several board types the resolution disambiguates **by depth first** —
+ * the type must be legal at the document's depth — **then by the managed
+ * block's recorded type**, the tiebreaker for two types that share a depth.
+ *
+ * `recordedType` is the `type` value the managed block wrote when this issue
+ * was pushed; it is consulted only within the depth-narrowed set, so it can
+ * break a tie but never override the hierarchy.
+ */
+export function mapTypeFromRemote(mappings, hierarchy, observation, opts) {
+    const candidates = boardTypesMatching(mappings, observation);
+    if (candidates.length === 0) {
+        return { type: undefined, candidates: [], unresolved: 'unmapped' };
+    }
+    const atDepth = new Set(hierarchy[opts.depth] ?? []);
+    const narrowed = candidates.filter((type) => atDepth.has(type));
+    if (narrowed.length === 1) {
+        return { type: narrowed[0], candidates, unresolved: undefined };
+    }
+    if (narrowed.length === 0) {
+        return { type: undefined, candidates, unresolved: 'depth' };
+    }
+    if (opts.recordedType !== undefined && narrowed.includes(opts.recordedType)) {
+        return { type: opts.recordedType, candidates, unresolved: undefined };
+    }
+    return { type: undefined, candidates, unresolved: 'ambiguous' };
+}
+/**
+ * True when a mapping entry matches the remote observation: one of the entry's
+ * `remote` values is the observed native type, or is present as a label.
+ *
+ * The entry does not say which carrier its values were written to, so both are
+ * checked — which is the point.  A repository that turns native issue types on
+ * (or a provider that gains them) starts reporting the same value in a
+ * different field, and the mapping that was already correct keeps working
+ * rather than silently resolving nothing.  Matching still runs on the
+ * *mapping's declared values*: a label a human happened to add only matters
+ * when some board type claims it.
+ */
+function entryMatches(entry, observation) {
+    const remote = remoteNameFor(entry);
+    if (remote === undefined)
+        return false;
+    return remote === observation.remoteType || observation.labels.includes(remote);
+}
+/**
+ * Every board type whose mapping claims this observation, sorted — the shared
+ * answer to "what type is this remote issue?" before depth and the managed
+ * block get a say.  Each provider's translator reads it rather than filtering
+ * `mapping.types` itself, so the four of them cannot drift apart on what
+ * counts as a match.
+ */
+export function boardTypesMatching(mappings, observation) {
+    return Object.entries(mappings)
+        .filter(([, entry]) => entryMatches(entry, observation))
+        .map(([boardType]) => boardType)
+        .sort();
+}
+/**
+ * The hierarchy levels beyond the remote's native depth — the levels whose
+ * parenting must be carried by the degradation ladder rather than a native
+ * parent field.  Their *types* still map normally; it is the nesting that
+ * degrades.
+ *
+ * `nativeDepth` is the number of levels the remote can nest, counting the root
+ * as level 1: a tracker with no hierarchy is 1, one with a single level of
+ * sub-issues (GitHub) is 2, and so on.  Levels at index `nativeDepth` and
+ * beyond are degraded.
+ */
+export function degradedHierarchyLevels(hierarchy, nativeDepth) {
+    const degraded = [];
+    for (let depth = nativeDepth; depth < hierarchy.length; depth += 1) {
+        const types = hierarchy[depth] ?? [];
+        if (types.length > 0)
+            degraded.push({ depth, types: [...types] });
+    }
+    return degraded;
+}
+/**
+ * Normalize one `mapping.statuses` value to the object form.  Accepts the
+ * three spellings — a single remote state (`done: Done`), a list
+ * (`done: [Done, "Won't Fix"]`), or the full object — and returns `undefined`
+ * when the value carries no usable remote state.
+ */
+export function normalizeStatusMapping(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return { remote: [value] };
+    }
+    if (Array.isArray(value)) {
+        const remote = value.filter((v) => typeof v === 'string' && v.length > 0);
+        return remote.length > 0 ? { remote } : undefined;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const raw = value;
+        const r = raw.remote;
+        const remote = typeof r === 'string' && r.length > 0
+            ? [r]
+            : Array.isArray(r)
+                ? r.filter((v) => typeof v === 'string' && v.length > 0)
+                : [];
+        if (remote.length === 0)
+            return undefined;
+        const entry = { remote };
+        if (typeof raw.push === 'string' && raw.push.length > 0)
+            entry.push = raw.push;
+        if (typeof raw.closed === 'boolean')
+            entry.closed = raw.closed;
+        return entry;
+    }
+    return undefined;
+}
+/**
+ * Normalize the whole `mapping.statuses` block, dropping entries that carry no
+ * usable remote state.  The provider schema rejects malformed values before
+ * this runs; this is the pure spelling of the same rule for callers that read
+ * a mapping without a schema in hand.
+ */
+export function normalizeStatusMappings(raw) {
+    const out = {};
+    for (const [status, value] of Object.entries(raw)) {
+        const entry = normalizeStatusMapping(value);
+        if (entry)
+            out[status] = entry;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Push: board status → remote state
+// ---------------------------------------------------------------------------
+/**
+ * One entry's `remote` states, read defensively.  Normalized entries always
+ * carry a list; a hand-built one that skipped the schema may carry the bare
+ * string the config also accepts (`done: { remote: Done }`), and that must
+ * read as one state — never as a string being indexed into, which would hand
+ * a push the single character `D`.
+ */
+export function statusStatesOf(entry) {
+    const remote = entry?.remote;
+    if (Array.isArray(remote))
+        return remote;
+    return typeof remote === 'string' && remote.length > 0 ? [remote] : [];
+}
+/**
+ * The remote state a push writes for a board status — `push` when declared,
+ * otherwise the first `remote` state.  Returns `undefined` when the status has
+ * no usable mapping; a default remote state must never be invented.
+ */
+export function mapStatusToRemote(mappings, boardStatus) {
+    const states = statusStatesOf(mappings[boardStatus]);
+    if (states.length === 0)
+        return undefined;
+    return mappings[boardStatus]?.push ?? states[0];
+}
+/**
+ * Whether a board status closes the remote issue, per the mapping: `true` when
+ * the entry says `closed: true`, `false` when it says `closed: false`, and
+ * `undefined` when the status is unmapped or the entry does not say — absent
+ * means "not declared", never "assume it matches `terminal`".
+ */
+export function isClosedRemote(mappings, boardStatus) {
+    return mappings[boardStatus]?.closed;
+}
+/**
+ * Board statuses with no usable mapping — the list a preflight reports when it
+ * refuses to open the remote.  A status with no key, or whose entry normalised
+ * away to nothing, counts as missing.
+ */
+export function missingStatusMappings(mappings, boardStatusIds) {
+    return boardStatusIds.filter((status) => mapStatusToRemote(mappings, status) === undefined);
+}
+/**
+ * Resolve observed remote states back to a single board status.  A board
+ * status claims the issue when one of its `remote` states is observed; a
+ * status mapping is expected to be many-remote-states-to-one-status, so a
+ * single observed state can never be ambiguous on its own — only several
+ * observed states that claim *different* board statuses are.
+ */
+export function mapStatusFromRemote(mappings, observed) {
+    const candidates = Object.entries(mappings)
+        .filter(([, entry]) => statusStatesOf(entry).some((state) => observed.includes(state)))
+        .map(([status]) => status)
+        .sort();
+    if (candidates.length === 0) {
+        return { status: undefined, candidates: [], unresolved: 'unmapped' };
+    }
+    if (candidates.length === 1) {
+        return { status: candidates[0], candidates, unresolved: undefined };
+    }
+    return { status: undefined, candidates, unresolved: 'ambiguous' };
+}
+/**
+ * Remote states with no board counterpart — the reverse-direction totality
+ * the preflight reports before anything is written.  `observedRemoteStates` is
+ * the full set of states the remote actually carries (from a live listing),
+ * not the labels on one issue.
+ */
+export function unmappedRemoteStates(mappings, observedRemoteStates) {
+    const claimed = new Set();
+    for (const entry of Object.values(mappings)) {
+        for (const state of statusStatesOf(entry))
+            claimed.add(state);
+    }
+    return observedRemoteStates.filter((state) => !claimed.has(state));
+}
+/**
+ * Board statuses whose `terminal` flag disagrees with the mapping's `closed`
+ * flag, in both directions: terminal-but-not-closed, and closed-but-not-
+ * terminal.  `statuses` is the board's status list (`BoardConfig.statuses`).
+ */
+export function statusClosednessMismatches(mappings, statuses) {
+    const mismatches = [];
+    for (const status of statuses) {
+        const terminal = status.terminal === true;
+        const closed = mappings[status.id]?.closed === true;
+        if (terminal !== closed) {
+            mismatches.push({ status: status.id, terminal, closed });
+        }
+    }
+    return mismatches;
+}
+//# sourceMappingURL=mapping.js.map

package/dist/remote/mapping.js.map

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

package/dist/remote/merge.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The field-by-field three-way merge (LP-284).
+ *
+ * Two people can edit the same linked document in two places between syncs.
+ * Given the base snapshot — each mapped field's value as it stood when both
+ * sides last agreed — a field is one of four cases, not two:
+ *
+ *   local vs base   remote vs base   outcome
+ *   -------------   --------------   -------
+ *   same            same             none
+ *   changed         same             push
+ *   same            changed          pull
+ *   changed         changed          conflict
+ *
+ * This file owns the *decision* for one field and nothing more. It does not
+ * say what a `push` or a `pull` means in operation terms (that is the
+ * planners'), and it does not say how a `conflict` is resolved (that is the
+ * policy story's, LP-286). Scalar fields end at the four-case table in
+ * `mergeValues`; list-valued fields go through `mergeLists` below (LP-285),
+ * which merges them element-by-element as sets — each side's additions and
+ * removals against base are computed and applied together, so a value added on
+ * both sides survives and a value removed on both sides is dropped, with only a
+ * genuinely undecidable value reported as a per-element conflict.
+ *
+ * ## Normalisation
+ *
+ * Markdown from a remote often comes back with `\r\n`, a trailing newline
+ * added or removed, and lists reordered.  Comparing raw values would report a
+ * conflict for edits that agree, so every comparison goes through a canonical
+ * form: strings are trimmed and line endings folded to `\n`, arrays are sorted
+ * (a label, id or path list is a set — order is not load-bearing), and object
+ * keys are sorted.  The base snapshot stores canonical forms too (`links.ts`
+ * hashes the body and sorts lists), so local, remote and base all compare on
+ * the same footing.  The body never reaches this function as raw text — it is
+ * compared through `hashBody`, which already trims and strips the managed
+ * block.
+ *
+ * ## No base
+ *
+ * A link created by *matching* rather than a previous sync has no base
+ * snapshot.  With no base there is nothing to attribute a difference to, so a
+ * field that differs between the two sides is a conflict — the only honest
+ * answer short of clobbering one side or asking about everything.  A field
+ * that is merely *absent from* a base that otherwise exists is a different
+ * case and never reaches this function: the caller skips it, exactly as the
+ * push planner's `diffIssue` does, because a field the base does not record
+ * cannot be tracked and must not manufacture a phantom conflict.
+ *
+ * Pure: no imports, so this compiles for the browser exactly like the
+ * planners.  No disk, no network, no clock.
+ */
+/**
+ * The outcome of merging one field.  `none` means both sides already agree;
+ * `push` / `pull` name the direction the agreed value has to travel; `conflict`
+ * means both sides moved and neither value was derived from the other.
+ */
+export type MergeOutcome = 'none' | 'push' | 'pull' | 'conflict';
+/**
+ * The marker for "this document has no base snapshot", distinct from `null`
+ * and `undefined` — either can be a legitimate base *value* (an unassigned
+ * issue snapshots `assignee: null`).  Only the whole-document case uses it: a
+ * base that exists but does not record a field is the caller's cue to skip the
+ * field, not to pass `NO_BASE`.
+ */
+export declare const NO_BASE: unique symbol;
+/**
+ * The canonical form of a value, for comparison and for storage.
+ *
+ *   - strings are trimmed and `\r\n` / `\r` folded to `\n`, so a remote's
+ *     line-ending and trailing-newline noise never disagrees with the board;
+ *   - arrays are sorted by their elements' canonical forms, so list order does
+ *     not matter;
+ *   - plain-object keys are sorted, so key order does not matter.
+ *
+ * Scalars other than strings are returned unchanged.  The result is a plain
+ * data value, never the input's identity — callers may store it.
+ */
+export declare function canonicalValue(value: unknown): unknown;
+/**
+ * True when two values agree in canonical form — trailing whitespace, line
+ * endings, and list or key order ignored.
+ */
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+/**
+ * Decide one field's merge outcome from its local, remote and base values.
+ *
+ * `base` is `NO_BASE` when the document has no base snapshot (a link created by
+ * matching, not by a previous sync); otherwise it is the concrete value the
+ * base recorded, which may itself be `null` or `undefined`.
+ *
+ * Both sides agreeing is always `none` — whether or not either moved from
+ * base, because a field two people edited to the same value needs no sync and
+ * no resolution.  When they disagree: a side equal to base has not moved, so
+ * the other side's value is the winner (`push` for the local edit, `pull` for
+ * the remote one); when neither equals base — or there is no base to compare
+ * against — the field is a `conflict`.
+ */
+export declare function mergeValues(local: unknown, remote: unknown, base: unknown): MergeOutcome;
+/**
+ * The result of merging one list-valued field as a set.
+ *
+ * A list field is not one value that either side edits as a whole: it is a set
+ * of elements (`labels`, `depends_on`, `relates_to`, `covers`), each of which
+ * a side can add or remove on its own.  `mergeValues`'s four-case table is the
+ * wrong granularity here — two people each adding a different label would read
+ * as a whole-field conflict when the honest answer is that both additions
+ * stick.  So the merge is per element:
+ *
+ *   - `localAdded` / `remoteAdded` are the values a side has that base did not;
+ *   - `localRemoved` / `remoteRemoved` are the values base had that a side
+ *     dropped;
+ *   - `merged` is the set every value both sides can agree on: base minus both
+ *     sides' removals, plus both sides' additions, minus the conflicting
+ *     values;
+ *   - `conflicts` are the values one side added and the other removed — the
+ *     one genuinely undecidable case, reported one entry per value rather than
+ *     once for the whole list.
+ *
+ * The caller applies `localAdded`/`localRemoved` toward the remote and
+ * `remoteAdded`/`remoteRemoved` toward the board, and hands each `conflicts`
+ * entry to the policy (`resolveByPolicy`) — exactly the per-element split the
+ * story asks for, so one bad value never holds the whole list hostage.
+ *
+ * ## Labels the mapping does not claim
+ *
+ * `labels` is the one list field that can carry values the board has no word
+ * for.  A label the mapping does not claim is not part of any field, so the
+ * caller filters it out *before* merging and never returns it in the additions
+ * or removals — that is what leaves it alone in both directions: a pull never
+ * reads it into a board field, and a push's additions/removals never name it,
+ * so nothing rewrites it.  The merge itself is deliberately field-agnostic and
+ * trusts the caller to pass only the mapped values.
+ *
+ * ## Where a conflict can actually arise
+ *
+ * Against one consistent base a value cannot be both an addition and a removal:
+ * "added" means base did not have it, "removed" means base did, and the two
+ * never meet.  The four case table above is complete for a sound base, so
+ * `conflicts` is empty there by construction.  The per-element conflict is
+ * real for the **no-base** case — a link created by matching, with no snapshot
+ * to attribute either side's list to — where every value exactly one side has
+ * is reported as a single-value conflict rather than a whole-list one.  That
+ * is deliberate and mirrors `mergeValues(…, NO_BASE)`, refined to elements.
+ *
+ * Pure: no imports, so this compiles for the browser exactly like the
+ * planners.  No disk, no network, no clock.
+ */
+export interface ListMerge {
+    /** The values both sides can agree on, sorted and de-duplicated. */
+    merged: string[];
+    /** Values one side added and the other removed, sorted and de-duplicated. */
+    conflicts: string[];
+    /** Values the local side added against base. */
+    localAdded: string[];
+    /** Values the local side removed against base. */
+    localRemoved: string[];
+    /** Values the remote side added against base. */
+    remoteAdded: string[];
+    /** Values the remote side removed against base. */
+    remoteRemoved: string[];
+}
+/**
+ * Merge a list-valued field as a set, element by element.
+ *
+ * `base` is `NO_BASE` when the document has no base snapshot; otherwise it is
+ * the concrete list the base recorded.  With a base, each side's additions and
+ * removals are computed against it and combined — the two never conflict, and
+ * the merged set carries both sides' additions.  With no base, the values both
+ * sides share are the merged set and every value exactly one side has is a
+ * per-element conflict, so a difference is never upgraded to a whole-list one.
+ */
+export declare function mergeLists(local: unknown, remote: unknown, base: unknown): ListMerge;