@north-light/crouter 0.3.226 → 0.3.228

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

@@ -0,0 +1,26 @@
+import type { CorpusBlocker, CorpusSnapshot, FrontDoorAction } from '../types.js';
+import type { RepositoryDecision, StorePrefixFacts } from './repository-facts.js';
+export interface FrontDoorPlan {
+    repositoryRoot: string;
+    /** The repository-root store's key. */
+    storeKey: string;
+    rootDocPath: string;
+    rootAction: 'kept' | 'created' | 'completed';
+    /** The unique legacy front door whose workspace-open entries this run removes. It may live
+     *  in a nested store of the same repository, so it carries its own store key. */
+    leafDocPath: string | null;
+    leafStoreKey: string | null;
+    /** The leaf's FINAL canonical name, for the created root body's `[[link]]`. */
+    leafCanonicalName: string | null;
+    action: FrontDoorAction;
+}
+export declare function planFrontDoors(repositories: readonly RepositoryDecision[], prefixes: ReadonlyMap<string, StorePrefixFacts>, corpus: CorpusSnapshot, finalNameOf: (realPath: string) => string | undefined): {
+    plans: FrontDoorPlan[];
+    blockers: CorpusBlocker[];
+};
+/** New repository-root INDEX.md source. `leafCanonicalName` null yields the generic minimal root body. */
+export declare function rootIndexSource(namespace: string, leafCanonicalName: string | null): string;
+/** Add the missing half or halves of the root front-door pair to a complete document source. */
+export declare function completeRootFrontDoor(source: string, docPath: string): string;
+/** Remove every workspace-open entry while preserving the body and every retained authored YAML byte. */
+export declare function demoteLeafSurfaces(source: string, docPath: string): string;

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

@@ -0,0 +1,231 @@
+import { join, relative } from 'node:path';
+import { parse as parseYaml, stringify } from 'yaml';
+import { realpathOrSelf } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { localNameFromPath } from '../../core/memory/identity.js';
+import { appendRenderedKey, dropSequenceItems, dropTopLevelKeys, proveFrontmatterRoundTrip, rebuildDocSource, splitDocSource, } from '../frontmatter-splice.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function surfaceEntries(frontmatter) {
+    const raw = frontmatter?.['surfaces'];
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    return raw.map(record).filter((entry) => entry !== null);
+}
+function matchIncludesOwnerTree(match) {
+    return match === './**' || (Array.isArray(match) && match.includes('./**'));
+}
+function hasWorkspaceOpen(entries) {
+    return entries.some((entry) => entry['on'] === 'workspace-open' && entry['at'] === 'content');
+}
+function hasOwnerRead(entries) {
+    return entries.some((entry) => entry['on'] === 'read'
+        && entry['at'] === 'content'
+        && matchIncludesOwnerTree(entry['match']));
+}
+function hasCompleteFrontDoor(frontmatter) {
+    const entries = surfaceEntries(frontmatter);
+    return entries !== null && hasWorkspaceOpen(entries) && hasOwnerRead(entries);
+}
+function conflictingRootWorkspaceOpen(frontmatter) {
+    const entries = surfaceEntries(frontmatter);
+    if (entries === null)
+        return true;
+    return entries.some((entry) => {
+        if (entry['on'] !== 'workspace-open')
+            return false;
+        return entry['at'] !== 'content'
+            || Object.hasOwn(entry, 'match')
+            || Object.hasOwn(entry, 'gate')
+            || Object.hasOwn(entry, 'match-frontmatter');
+    });
+}
+function rootStoreKey(repositoryRoot, prefixes) {
+    for (const [storeKey, facts] of prefixes) {
+        if (facts.repositoryRoot === repositoryRoot && facts.ownerRelativePath === '')
+            return storeKey;
+    }
+    return realpathOrSelf(join(repositoryRoot, '.crouter', 'memory'));
+}
+function repositoryRelativePath(repositoryRoot, filePath) {
+    return relative(repositoryRoot, filePath).replace(/\\/g, '/');
+}
+function frontDoorBlocker(message, paths, repositoryRoot) {
+    return {
+        kind: 'front-door',
+        message,
+        storeRoot: join(repositoryRoot, '.crouter', 'memory'),
+        ...(paths.length === 1 ? { path: paths[0] } : {}),
+        paths: [...paths],
+    };
+}
+export function planFrontDoors(repositories, prefixes, corpus, finalNameOf) {
+    const plans = [];
+    const blockers = [];
+    for (const repository of repositories) {
+        const rootDocPath = join(repository.repositoryRoot, '.crouter', 'memory', 'INDEX.md');
+        const rootRealPath = realpathOrSelf(rootDocPath);
+        const rootKey = rootStoreKey(repository.repositoryRoot, prefixes);
+        let rootDoc = null;
+        const workspaceOpenDocs = new Map();
+        const candidates = new Map();
+        for (const storeKey of repository.storeKeys) {
+            const facts = prefixes.get(storeKey);
+            if (facts === undefined || facts.repositoryRoot !== repository.repositoryRoot)
+                continue;
+            const store = facts.store ?? corpus.store(storeKey);
+            if (store === undefined || !store.writable)
+                continue;
+            if (store.descriptor.scope !== 'project' || store.descriptor.plugin !== undefined)
+                continue;
+            for (const doc of store.snapshot.docs) {
+                const docRealPath = realpathOrSelf(doc.path);
+                if (docRealPath === rootRealPath) {
+                    rootDoc = doc;
+                    continue;
+                }
+                if (facts.nestedDeclarationAction === 'synthetic-index-removed'
+                    && localNameFromPath(doc.relPath) === '')
+                    continue;
+                const entry = { doc, storeKey, realPath: docRealPath };
+                const entries = surfaceEntries(doc.frontmatter);
+                if (entries?.some((surface) => surface['on'] === 'workspace-open' && surface['at'] === 'content')) {
+                    workspaceOpenDocs.set(docRealPath, entry);
+                }
+                if (!hasCompleteFrontDoor(doc.frontmatter))
+                    continue;
+                candidates.set(docRealPath, entry);
+            }
+        }
+        const leaves = [...candidates.values()];
+        const repositoryBlockers = [];
+        if (leaves.length > 1) {
+            const paths = leaves.map((leaf) => leaf.doc.path);
+            repositoryBlockers.push(frontDoorBlocker(`repository ${repository.repositoryRoot} has more than one non-root document carrying the complete workspace front door (${paths.join(', ')}) — keep one source guide as the transfer source, remove the other workspace-open entries, and re-run`, paths, repository.repositoryRoot));
+        }
+        const incompleteWorkspaceOpenDocs = [...workspaceOpenDocs.values()]
+            .filter((entry) => !candidates.has(entry.realPath));
+        if (incompleteWorkspaceOpenDocs.length > 0) {
+            const paths = incompleteWorkspaceOpenDocs.map((entry) => entry.doc.path);
+            repositoryBlockers.push(frontDoorBlocker(`repository ${repository.repositoryRoot} has non-root workspace-open documents without the complete owner-read pair (${paths.join(', ')}) — complete exactly one legacy front door or remove these workspace-open entries, then re-run`, paths, repository.repositoryRoot));
+        }
+        if (rootDoc !== null && conflictingRootWorkspaceOpen(rootDoc.frontmatter)) {
+            const paths = [rootDoc.path, ...leaves.map((leaf) => leaf.doc.path)];
+            repositoryBlockers.push(frontDoorBlocker(`repository-root guide ${rootDoc.path} carries a workspace-open route that migration cannot make authoritative without changing its predicate — make every root workspace-open entry exactly {on: workspace-open, at: content} and re-run`, paths, repository.repositoryRoot));
+        }
+        const leaf = leaves.length === 1 ? leaves[0] : null;
+        const leafCanonicalName = leaf === null ? null : finalNameOf(leaf.realPath);
+        if (leaf !== null && leafCanonicalName === undefined) {
+            repositoryBlockers.push(frontDoorBlocker(`legacy workspace front door ${leaf.doc.path} has no provable final canonical name — repair its identity blocker and re-run`, [leaf.doc.path], repository.repositoryRoot));
+        }
+        if (repositoryBlockers.length > 0) {
+            blockers.push(...repositoryBlockers);
+            continue;
+        }
+        const rootComplete = rootDoc !== null && hasCompleteFrontDoor(rootDoc.frontmatter);
+        const rootAction = rootDoc === null
+            ? 'created'
+            : rootComplete
+                ? 'kept'
+                : 'completed';
+        const relativeLeafPath = leaf === null
+            ? null
+            : repositoryRelativePath(repository.repositoryRoot, leaf.doc.path);
+        const action = relativeLeafPath !== null
+            ? `transferred-from:${relativeLeafPath}`
+            : rootComplete
+                ? 'kept-root'
+                : 'created-root';
+        plans.push({
+            repositoryRoot: repository.repositoryRoot,
+            storeKey: rootKey,
+            rootDocPath,
+            rootAction,
+            leafDocPath: leaf?.doc.path ?? null,
+            leafStoreKey: leaf?.storeKey ?? null,
+            leafCanonicalName: leafCanonicalName ?? null,
+            action,
+        });
+    }
+    return { plans, blockers };
+}
+/** New repository-root INDEX.md source. `leafCanonicalName` null yields the generic minimal root body. */
+export function rootIndexSource(namespace, leafCanonicalName) {
+    const label = namespace.split('/').at(-1) ?? namespace;
+    const body = leafCanonicalName === null
+        ? `# ${label}\n\nThis project's memory store. Every document here answers at \`${namespace}/<local name>\`.\n`
+        : `# ${label}\n\nThis project's memory store. Every document here answers at \`${namespace}/<local name>\`. Read [[${leafCanonicalName}]] for the detailed project guide.\n`;
+    return [
+        '---',
+        `namespace: ${JSON.stringify(namespace)}`,
+        'kind: knowledge',
+        `when-and-why-to-read: When working in \`${namespace}\`, this knowledge should be read because it names the namespace every document in this repository answers under.`,
+        'surfaces:',
+        '  - on: workspace-open',
+        '    at: content',
+        '  - on: read',
+        '    match: "./**"',
+        '    at: content',
+        '---',
+        '',
+        body,
+    ].join('\n');
+}
+function sourceWithFrontmatter(source) {
+    return parseFrontmatterGeneric(source).data === null ? `---\n\n---\n${source}` : source;
+}
+function parsedYamlRecord(rawYaml, docPath) {
+    let parsed;
+    try {
+        parsed = parseYaml(rawYaml === '' ? '{}' : rawYaml);
+    }
+    catch (error) {
+        throw new Error(`front-door migration: unparseable frontmatter in ${docPath}`, { cause: error });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`front-door migration: frontmatter is not a mapping in ${docPath}`);
+    }
+    return parsed;
+}
+/** Add the missing half or halves of the root front-door pair to a complete document source. */
+export function completeRootFrontDoor(source, docPath) {
+    const withFrontmatter = sourceWithFrontmatter(source);
+    const { rawYaml } = splitDocSource(withFrontmatter, docPath);
+    const before = parsedYamlRecord(rawYaml, docPath);
+    const rawSurfaces = before['surfaces'];
+    if (rawSurfaces !== undefined && !Array.isArray(rawSurfaces)) {
+        throw new Error(`front-door migration: surfaces is not a sequence in ${docPath}`);
+    }
+    const surfaces = rawSurfaces === undefined
+        ? []
+        : rawSurfaces.map((entry) => record(entry) ?? entry);
+    const entries = surfaces.filter((entry) => record(entry) !== null);
+    const merged = [...surfaces];
+    if (!hasWorkspaceOpen(entries))
+        merged.push({ on: 'workspace-open', at: 'content' });
+    if (!hasOwnerRead(entries))
+        merged.push({ on: 'read', match: './**', at: 'content' });
+    if (merged.length === surfaces.length)
+        return withFrontmatter;
+    let newYaml = rawYaml;
+    if (rawSurfaces !== undefined)
+        newYaml = dropTopLevelKeys(newYaml, ['surfaces'], docPath);
+    newYaml = newYaml === ''
+        ? stringify({ surfaces: merged }, { lineWidth: 0 }).replace(/\r?\n$/, '')
+        : appendRenderedKey(newYaml, 'surfaces', merged, docPath);
+    proveFrontmatterRoundTrip(newYaml, { ...before, surfaces: merged }, docPath);
+    return rebuildDocSource(withFrontmatter, newYaml, docPath);
+}
+/** Remove every workspace-open entry while preserving the body and every retained authored YAML byte. */
+export function demoteLeafSurfaces(source, docPath) {
+    if (parseFrontmatterGeneric(source).data === null)
+        return source;
+    const { rawYaml } = splitDocSource(source, docPath);
+    const newYaml = dropSequenceItems(rawYaml, 'surfaces', (item) => record(item)?.['on'] === 'workspace-open', docPath);
+    return newYaml === rawYaml ? source : rebuildDocSource(source, newYaml, docPath);
+}

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

@@ -0,0 +1,2 @@
+import type { CorpusMigration } from '../types.js';
+export declare const repositoryRootMemoryIdentityMigration: CorpusMigration;