@north-light/crouter 0.3.227 → 0.3.228

package/dist/migrations/003-repository-root-memory-identity/references.js

@@ -0,0 +1,469 @@
+import { matchesGlob } from 'node:path';
+import { isMap, isSeq, parseDocument } from 'yaml';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { findDocLinks } from '../../core/memory/doc-link-grammar.js';
+import { canonicalParent, composeCanonicalName, INDEX_SEGMENT, representationForPath, routingAnchorFor, stripNamespace, } from '../../core/memory/identity.js';
+/** Right-to-left, widest-first at a shared start. A whole-key removal beginning
+ * at the YAML block base must run before a zero-width insertion there. */
+export function applySplices(source, splices) {
+    let out = source;
+    for (const splice of [...splices].sort((a, b) => b.start - a.start || b.end - a.end)) {
+        out = out.slice(0, splice.start) + splice.text + out.slice(splice.end);
+    }
+    return out;
+}
+/** Locate the raw YAML within a complete document source. */
+export function yamlBlock(source) {
+    const parsed = parseFrontmatterGeneric(source);
+    if (parsed.raw === '')
+        return null;
+    const bodyStart = source.length - parsed.body.length;
+    const base = source.slice(0, bodyStart).indexOf(parsed.raw);
+    return base < 0 ? null : { base, raw: parsed.raw };
+}
+export function yamlMap(raw) {
+    const parsed = parseDocument(raw);
+    return parsed.errors.length === 0 && isMap(parsed.contents) ? parsed.contents : null;
+}
+export function itemFor(map, key) {
+    return map.items.find((item) => String(item.key) === key) ?? null;
+}
+/** Whole-line span of a mapping key, including its multiline value. */
+export function keyLineSpan(raw, item) {
+    const keyRange = item.key?.range;
+    if (keyRange === undefined)
+        return null;
+    const valueRange = item.value?.range;
+    let start = raw.lastIndexOf('\n', keyRange[0] - 1) + 1;
+    let end = valueRange?.[2] ?? keyRange[2];
+    if (!(end > 0 && raw[end - 1] === '\n')) {
+        while (end < raw.length && (raw[end] === ' ' || raw[end] === '\t' || raw[end] === '\r'))
+            end++;
+        if (raw[end] === '\n')
+            end++;
+    }
+    if (end >= raw.length && start > 0 && raw[start - 1] === '\n')
+        start -= 1;
+    return [start, end];
+}
+/** Span of a mapping value with trailing whitespace excluded. */
+export function valueSpan(raw, item) {
+    const range = item.value?.range;
+    if (range === undefined)
+        return null;
+    let end = range[1];
+    while (end > range[0] && /\s/.test(raw[end - 1]))
+        end--;
+    return [range[0], end];
+}
+const PLAIN_SCALAR_RE = /^[A-Za-z][A-Za-z0-9._\-/]*$/;
+export function renderScalar(value) {
+    return PLAIN_SCALAR_RE.test(value) ? value : JSON.stringify(value);
+}
+/** Render one or several route globs without expanding a one-line value into a
+ * block sequence. */
+export function renderGlobList(globs) {
+    return globs.length === 1 ? JSON.stringify(globs[0]) : `[${globs.map((glob) => JSON.stringify(glob)).join(', ')}]`;
+}
+export function viewsForStore(corpus, store) {
+    // A store no target mounts still holds references and resolves them against
+    // itself alone.
+    if (store.targets.length === 0) {
+        return [{ signature: store.key, storeKeys: [store.key], targetIds: [] }];
+    }
+    const views = new Map();
+    for (const targetId of store.targets) {
+        const storeKeys = corpus.storesForTarget(targetId).map((candidate) => candidate.key);
+        const signature = storeKeys.join('\u0000');
+        const existing = views.get(signature);
+        if (existing === undefined)
+            views.set(signature, { signature, storeKeys, targetIds: [targetId] });
+        else
+            existing.targetIds.push(targetId);
+    }
+    return [...views.values()];
+}
+function safeGlob(target, glob) {
+    try {
+        return matchesGlob(target, glob);
+    }
+    catch {
+        return false;
+    }
+}
+/** `foo/INDEX.md` deterministically fronts `foo.md`, then lexical path order
+ * breaks every remaining old-name tie. */
+function oldNameWinner(a, b) {
+    const aIndex = a.doc.relPath.endsWith(`${INDEX_SEGMENT}.md`);
+    const bIndex = b.doc.relPath.endsWith(`${INDEX_SEGMENT}.md`);
+    if (aIndex !== bIndex)
+        return aIndex ? a : b;
+    return a.doc.relPath.localeCompare(b.doc.relPath) <= 0 ? a : b;
+}
+/** Recover the effective prefix pinned into a document's final identity. */
+function effectivePrefixOf(fact) {
+    if (fact.finalLocal === '')
+        return fact.finalName;
+    if (fact.finalName === fact.finalLocal)
+        return '';
+    const suffix = `/${fact.finalLocal}`;
+    if (!fact.finalName.endsWith(suffix)) {
+        throw new Error(`migration 003 reference facts for ${fact.doc.path} disagree: final name \`${fact.finalName}\` does not compose from local name \`${fact.finalLocal}\``);
+    }
+    return fact.finalName.slice(0, -suffix.length);
+}
+/** Reference resolution under the frozen old corpus view. */
+export class OldCorpus {
+    facts = new Map();
+    matchCache = new Map();
+    constructor(docsByStoreKey) {
+        for (const [storeKey, docs] of docsByStoreKey) {
+            const byOldName = new Map();
+            let oldPrefix = null;
+            let effectivePrefix = null;
+            for (const fact of docs) {
+                const existing = byOldName.get(fact.oldName);
+                byOldName.set(fact.oldName, existing === undefined ? fact : oldNameWinner(existing, fact));
+                if (oldPrefix === null)
+                    oldPrefix = fact.oldPrefix;
+                else if (oldPrefix !== fact.oldPrefix) {
+                    throw new Error(`migration 003 reference facts for store ${storeKey} disagree on old prefix (\`${oldPrefix}\` vs \`${fact.oldPrefix}\`)`);
+                }
+                const candidate = effectivePrefixOf(fact);
+                if (effectivePrefix === null)
+                    effectivePrefix = candidate;
+                else if (effectivePrefix !== candidate) {
+                    throw new Error(`migration 003 reference facts for store ${storeKey} disagree on effective prefix (\`${effectivePrefix}\` vs \`${candidate}\`)`);
+                }
+            }
+            this.facts.set(storeKey, {
+                docs,
+                byOldName,
+                oldPrefix: oldPrefix ?? '',
+                effectivePrefix: effectivePrefix ?? '',
+            });
+        }
+    }
+    /** The physical old-name winner in one view, including a synthetic document
+     * phase 2 will delete. The retired directory-index fallback is part of this
+     * frozen lookup. A virtual bare-directory prefix has no physical fact. */
+    resolveOldFact(view, written) {
+        for (const key of view.storeKeys) {
+            const hit = this.facts.get(key)?.byOldName.get(written);
+            if (hit !== undefined)
+                return hit;
+        }
+        for (const key of view.storeKeys) {
+            const hit = this.facts.get(key)?.byOldName.get(`${written}/${INDEX_SEGMENT}`);
+            if (hit !== undefined)
+                return hit;
+        }
+        return null;
+    }
+    /** The final canonical name a written old name denoted in one view. Deleted
+     * physical winners have no final projection; dangling references and
+     * unprovable bare-directory mappings likewise return null. */
+    resolveOld(view, written) {
+        const winner = this.resolveOldFact(view, written);
+        if (winner !== null)
+            return winner.deleted ? null : winner.finalName;
+        const prefix = `${written}/`;
+        let derived = null;
+        let matched = false;
+        for (const key of view.storeKeys) {
+            for (const fact of this.facts.get(key)?.docs ?? []) {
+                if (!fact.oldName.startsWith(prefix))
+                    continue;
+                matched = true;
+                const rest = fact.oldName.slice(prefix.length);
+                if (!fact.finalName.endsWith(`/${rest}`))
+                    return null;
+                const candidate = fact.finalName.slice(0, fact.finalName.length - rest.length - 1);
+                if (derived === null)
+                    derived = candidate;
+                else if (derived !== candidate)
+                    return null;
+            }
+        }
+        return matched ? derived : null;
+    }
+    /** Realpaths a glob names under old or final identity, plus the effective
+     * prefixes of stores contributing a match. */
+    matchSet(view, glob, phase) {
+        const cacheKey = `${view.signature}\u0000${phase}\u0000${glob}`;
+        const cached = this.matchCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const paths = new Set();
+        const namespaces = new Set();
+        for (const key of view.storeKeys) {
+            const store = this.facts.get(key);
+            if (store === undefined)
+                continue;
+            for (const fact of store.docs) {
+                if (phase === 'final' && fact.deleted)
+                    continue;
+                const name = phase === 'old' ? fact.oldName : fact.finalName;
+                if (name === '' || !safeGlob(name, glob))
+                    continue;
+                paths.add(fact.realPath);
+                if (store.effectivePrefix !== '')
+                    namespaces.add(store.effectivePrefix);
+            }
+        }
+        const result = { paths, namespaces };
+        this.matchCache.set(cacheKey, result);
+        return result;
+    }
+    /** Candidate qualification for both accepted old models. A pre-003 store
+     * gains its final prefix; a superseded per-store declaration has its old
+     * prefix replaced by the repository-derived one. */
+    finalGlobSpellings(views, glob) {
+        const candidates = new Set();
+        for (const view of views) {
+            for (const key of view.storeKeys) {
+                const store = this.facts.get(key);
+                if (store === undefined || !store.docs.some((fact) => fact.oldName !== '' && safeGlob(fact.oldName, glob))) {
+                    continue;
+                }
+                candidates.add(composeCanonicalName(store.effectivePrefix, glob));
+                if (store.oldPrefix === '')
+                    continue;
+                if (glob === store.oldPrefix)
+                    candidates.add(store.effectivePrefix);
+                else if (glob.startsWith(`${store.oldPrefix}/`)) {
+                    candidates.add(composeCanonicalName(store.effectivePrefix, glob.slice(store.oldPrefix.length + 1)));
+                }
+            }
+        }
+        candidates.delete('');
+        return [...candidates].sort();
+    }
+}
+function isSubset(a, b) {
+    for (const value of a)
+        if (!b.has(value))
+            return false;
+    return true;
+}
+function sameSet(a, b) {
+    return a.size === b.size && isSubset(a, b);
+}
+/** Candidate final spellings for one authored glob, in preference order. */
+function candidateSpellings(base) {
+    const out = [];
+    const push = (candidate) => {
+        if (candidate !== '' && !out.includes(candidate))
+            out.push(candidate);
+    };
+    for (const candidate of base) {
+        push(candidate);
+        const collapsed = candidate.endsWith(`/${INDEX_SEGMENT}`)
+            ? candidate.slice(0, -(INDEX_SEGMENT.length + 1))
+            : candidate.endsWith('/**')
+                ? candidate.slice(0, -3)
+                : candidate.endsWith('/*')
+                    ? candidate.slice(0, -2)
+                    : null;
+        if (collapsed !== null)
+            push(collapsed);
+    }
+    return out;
+}
+/** The minimal glob list naming exactly the old match set under final identity,
+ * or null when no exact rewrite can be proved. */
+export function provenGlobs(corpus, views, glob) {
+    const perView = views.map((view) => ({ view, expected: corpus.matchSet(view, glob, 'old').paths }));
+    if (perView.every(({ expected }) => expected.size === 0))
+        return [glob];
+    const candidates = candidateSpellings([glob, ...corpus.finalGlobSpellings(views, glob)]);
+    let kept = candidates.filter((candidate) => perView.every(({ view, expected }) => isSubset(corpus.matchSet(view, candidate, 'final').paths, expected)));
+    const covers = (list) => perView.every(({ view, expected }) => {
+        const union = new Set();
+        for (const candidate of list) {
+            for (const path of corpus.matchSet(view, candidate, 'final').paths)
+                union.add(path);
+        }
+        return sameSet(union, expected);
+    });
+    if (!covers(kept))
+        return null;
+    for (let index = kept.length - 1; index >= 0; index--) {
+        const without = kept.filter((_, candidateIndex) => candidateIndex !== index);
+        if (without.length > 0 && covers(without))
+            kept = without;
+    }
+    return kept;
+}
+export function linkRewrites(corpus, views, store, fact, result, proofs) {
+    const links = findDocLinks(fact.doc.body);
+    if (links.length === 0)
+        return [];
+    const bodyBase = fact.doc.source.length - fact.doc.body.length;
+    const resolvedByName = new Map();
+    const splices = [];
+    for (const link of links) {
+        let target = resolvedByName.get(link.name);
+        if (target === undefined) {
+            const resolvedFacts = views.map((view) => ({ view, fact: corpus.resolveOldFact(view, link.name) }));
+            const deleted = resolvedFacts.filter((row) => row.fact?.deleted === true);
+            if (deleted.length > 0) {
+                const paths = [...new Set(deleted.map((row) => row.fact.doc.path))];
+                result.blockers.push({
+                    kind: 'divergent-reference',
+                    message: `[[${link.name}]] resolves to the synthetic document${paths.length === 1 ? '' : 's'} ${paths.map((path) => `\`${path}\``).join(', ')}, but this migration deletes ${paths.length === 1 ? 'that exact document' : 'those exact documents'} and no surviving physical document has the same identity — rewrite the link to the intended surviving document and re-run`,
+                    storeRoot: store.key,
+                    path: fact.doc.path,
+                    name: link.name,
+                    paths,
+                    ...(deleted[0]?.view.targetIds[0] === undefined ? {} : { targetId: deleted[0].view.targetIds[0] }),
+                });
+                target = null;
+                resolvedByName.set(link.name, target);
+                continue;
+            }
+            const resolutions = views
+                .map((view) => ({ view, name: corpus.resolveOld(view, link.name) }))
+                .filter((row) => row.name !== null);
+            const distinct = [...new Set(resolutions.map((row) => row.name))];
+            if (distinct.length > 1) {
+                result.blockers.push({
+                    kind: 'divergent-reference',
+                    message: `[[${link.name}]] resolves to different documents depending on the target view (${distinct.map((name) => `\`${name}\``).join(' vs ')}) — this migration never guesses which one the author meant; rewrite the link by hand and re-run`,
+                    storeRoot: store.key,
+                    path: fact.doc.path,
+                    name: link.name,
+                    ...(resolutions[0] === undefined || resolutions[0].view.targetIds[0] === undefined
+                        ? {}
+                        : { targetId: resolutions[0].view.targetIds[0] }),
+                });
+                target = null;
+            }
+            else {
+                target = distinct[0] ?? null;
+                if (target !== null && target !== link.name) {
+                    for (const row of resolutions) {
+                        const targetId = row.view.targetIds[0];
+                        if (targetId !== undefined)
+                            proofs.push({ targetId, carrier: fact.doc.path, name: target });
+                    }
+                    result.references.push({
+                        storeRoot: store.key,
+                        path: fact.doc.path,
+                        kind: 'link',
+                        from: link.name,
+                        to: target,
+                    });
+                }
+            }
+            resolvedByName.set(link.name, target);
+        }
+        if (target === null || target === link.name)
+            continue;
+        splices.push({ start: bodyBase + link.start, end: bodyBase + link.end, text: `[[${target}]]` });
+    }
+    return splices;
+}
+export function routeRewrites(corpus, views, store, fact, prefix, result, proofs) {
+    const surfaces = fact.doc.frontmatter?.['surfaces'];
+    if (!Array.isArray(surfaces))
+        return [];
+    const block = yamlBlock(fact.doc.source);
+    if (block === null)
+        return [];
+    const map = yamlMap(block.raw);
+    const seq = map === null ? null : itemFor(map, 'surfaces')?.value;
+    // A relative route remains safe when its carrier keeps the same local anchor
+    // while the entire store moves from oldPrefix to effectivePrefix.
+    const oldAnchor = canonicalParent(fact.oldName);
+    const oldLocalAnchor = stripNamespace(oldAnchor, fact.oldPrefix) ?? oldAnchor;
+    const expectedAnchor = composeCanonicalName(prefix.effectivePrefix, oldLocalAnchor);
+    const newAnchor = routingAnchorFor(fact.finalName, representationForPath(fact.doc.relPath));
+    const anchorMoved = newAnchor !== expectedAnchor;
+    const splices = [];
+    for (let index = 0; index < surfaces.length; index++) {
+        const entry = surfaces[index];
+        if (entry === null || typeof entry !== 'object' || entry['on'] !== 'memory-read')
+            continue;
+        const raw = entry['match'];
+        const globs = (typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : []).filter((glob) => typeof glob === 'string');
+        if (globs.length === 0)
+            continue;
+        const rewritten = [];
+        let changed = false;
+        for (const glob of globs) {
+            if (glob.startsWith('./')) {
+                if (anchorMoved) {
+                    result.blockers.push({
+                        kind: 'unsafe-route',
+                        message: `memory-read glob \`${glob}\` is anchored at \`${oldAnchor}\`, but this document's explicit \`name:\` re-anchors it at \`${newAnchor}\` after the identity cut — a different subtree, which no rewrite of the glob restores; spell the route out absolutely (or give the document the \`${expectedAnchor}/${INDEX_SEGMENT}.md\` path its name implies) and re-run`,
+                        storeRoot: store.key,
+                        path: fact.doc.path,
+                        name: glob,
+                    });
+                }
+                rewritten.push(glob);
+                continue;
+            }
+            const proven = provenGlobs(corpus, views, glob);
+            if (proven === null) {
+                result.blockers.push({
+                    kind: 'unsafe-route',
+                    message: `memory-read glob \`${glob}\` cannot be proved to name the same documents under repository-root identity — rewrite the entry by hand (or anchor it with \`./\`) and re-run`,
+                    storeRoot: store.key,
+                    path: fact.doc.path,
+                    name: glob,
+                });
+                rewritten.push(glob);
+                continue;
+            }
+            if (proven.length !== 1 || proven[0] !== glob) {
+                changed = true;
+                for (const view of views) {
+                    const targetId = view.targetIds[0];
+                    const expected = corpus.matchSet(view, glob, 'old').paths;
+                    if (targetId === undefined || expected.size === 0)
+                        continue;
+                    proofs.push({ targetId, carrier: fact.doc.path, globs: proven, expected: [...expected] });
+                }
+                result.references.push({
+                    storeRoot: store.key,
+                    path: fact.doc.path,
+                    kind: 'memory-read',
+                    from: glob,
+                    to: proven.join(', '),
+                });
+            }
+            rewritten.push(...proven);
+        }
+        if (!changed)
+            continue;
+        if (!isSeq(seq)) {
+            result.blockers.push({
+                kind: 'unsafe-route',
+                message: `memory-read routes in ${fact.doc.relPath} need rewriting but its \`surfaces:\` block is not a YAML sequence — fix the file and re-run`,
+                storeRoot: store.key,
+                path: fact.doc.path,
+            });
+            continue;
+        }
+        const entryNode = seq.items[index];
+        const item = isMap(entryNode) ? itemFor(entryNode, 'match') : null;
+        const span = item === null ? null : valueSpan(block.raw, item);
+        if (span === null) {
+            result.blockers.push({
+                kind: 'unsafe-route',
+                message: `memory-read route in ${fact.doc.relPath} needs rewriting but its \`match\` value cannot be located in the frontmatter text — fix the file and re-run`,
+                storeRoot: store.key,
+                path: fact.doc.path,
+            });
+            continue;
+        }
+        splices.push({
+            start: block.base + span[0],
+            end: block.base + span[1],
+            text: renderGlobList([...new Set(rewritten)]),
+        });
+    }
+    return splices;
+}

package/dist/migrations/003-repository-root-memory-identity/repository-facts.d.ts

@@ -0,0 +1,39 @@
+import { type ProjectNamespaceSource } from '../../core/memory/project-namespace.js';
+import type { CorpusBlocker, CorpusSnapshot, CorpusStore } from '../types.js';
+export interface RepositoryDecision {
+    repositoryKey: string;
+    repositoryRoot: string;
+    declarationPath: string;
+    namespace: string;
+    source: 'declared' | ProjectNamespaceSource;
+    action: 'kept' | 'created' | 'filled-linked-root';
+    /** Store keys grouped under this repository, in corpus order. */
+    storeKeys: readonly string[];
+}
+export type NestedDeclarationAction = 'none' | 'removed' | 'synthetic-index-removed';
+export interface StorePrefixFacts {
+    store: CorpusStore;
+    storeKey: string;
+    storeRoot: string;
+    ownerDir: string;
+    repositoryKey: string;
+    repositoryRoot: string;
+    ownerRelativePath: string;
+    /** The prefix this store's documents answered under BEFORE this run. */
+    oldPrefix: string;
+    /** How that prefix was proven: `'per-store-declaration'` when a declaration on
+     *  disk — this store's own legacy one, or the repository-root one a nested
+     *  store already answers under — names it, `'pre-003'` when nothing declares
+     *  it and the documents answered at bare local names. */
+    oldRule: 'pre-003' | 'per-store-declaration';
+    /** repositoryNamespace ⊕ ownerRelativePath. */
+    effectivePrefix: string;
+    nestedDeclarationAction: NestedDeclarationAction;
+    /** The legacy nested `namespace:` value, when one was present. */
+    legacyDeclaration: string | null;
+}
+export declare function planRepositories(corpus: CorpusSnapshot): {
+    repositories: RepositoryDecision[];
+    prefixes: Map<string, StorePrefixFacts>;
+    blockers: CorpusBlocker[];
+};